v0.3.0

MAPTK v0.3.0 Release Notes

This is a minor release of MAPTK that provides both new functionality and fixes
over the previous v0.2.1 release. The primary contributions of this release
are initial GPU feature tracking via VisCL, local loop closure (shot stitching)
across bad frames, triangulation to initialize SBA, estimation and application
of similarity transformation to align SBA cameras with POS cameras, and
additional analysis tools for visualizing and computing statistics on tracks.

Updates since v0.2.1

Core Library

• Added abstract algorithms for triangulation of landmarks.
• Added function to extract a sub-matrix from a matrix
• Added functions to extract and update a sub-vector from a vector
• Added functions to compute determinants of 2x2 and 3x3 matrices.
• Added a class to represent a similarity transformation (scale, rotation,
  and translation).
• Added clone() functions to camera and landmark.
• Add transform() functions to apply similarity transformations to landmarks,
  cameras, covariances, and maps of cameras and landmarks.
• Added a templated set_value function to config_block to allow setting values
  directly without first needing a boost::lexical_cast.
• Added "yes" and "no" as value boolean configuration strings
• Replaced track_features_simple with track_features_default class,
  requiring any config file to change this value from "simple" to "default".
• Added algorithm definition for similarity transformation estimation.
• Added several helper functions to track_set class.
• Added a convert_image algorithm so that an image conversion between different
  formats can be pre-computed. This is important for non-trivial image
  conversions (e.g. sending image to GPU) to prevent them from occuring
  multiple times on the same image.
• Added ability to add rotational offset when converting INS data into
  cameras.
• Added additional error robustness to INS I/O operations (specifically the
  input stream and reading operations).
• Added a new close_loops base class for current and future loop closure work.
  Currently it just contains 1 simple implementation aimed at stitching over
  bad frames in the input data.

VCL Library

• Added implementation of GPU feature detector.
• Added implementation of GPU descriptor extractor (BRIEF descriptor).
• Added implementation of GPU feature matcher using a local search box.
• Added implementation of convert_image to upload to the GPU.
• Current tracking implementation is not as optimized as it could be.
  The tracker does not maintain pointers to the GPU data structures from the
  previous frame; therefore, the features and descriptors are re-uploaded to
  the GPU at each frame. This will be optimized in a future release.

VXL Library

• Added implementation of triangulation of landmarks algorithm using vpgl.
• Added similarity transformation estimation implementation using
  vgl_compute_similarity_3d.

Tests

• Factored out some reusable test functions into common header files.
• Added tests for VXL similarity transform estimation

Tools

• When loading POS files in the bundle_adjust_tracks tools, triangulate to
  compute initial landmark positions.
• Added the use of similarity transform estimation to SBA tool when POS files
  are input, transforming both cameras and landmarks back into the space of
  the input POS files.
• Added optional file output to draw_tracks plot generation script.
• pos2krtd utility now uses a configuration file.
• Added configuration options for both SBA and pos2krtd tools to specify a
  rotational offset for input POS file (INS data) via a quaternion.
• Added an analyze_tracks tool which serves two purposes: drawing feature
  point tracks on input imagery, in addition to outputting various statistics
  about feature tracks.

Fixes since v0.2.1

Core Library

• Fixed a bug in interpretation of yaw-pitch-roll in the rotation class.
  It previously differed from that used in the POS file format by a 180
  degree rotation about the local Y axis.

v0.2.1

MAPTK v0.2.1 Release Notes

Minor patch release since v0.2.0 containing bug fixes and small improvements.
The primary contributions of this release are proper handling of input and
output file names in the SBA tool (output file names for each frame now match
input file names), and improved Doxygen documentation. This release documents
all files and classes that were previously missing documentation.

Updates since v0.2.0

OpenCV

• Added test exposing OpenCV bug/error on Windows. Single test expected to
  fail on windows until this is resolved within OpenCV or we have a
  workaround.

Tools

• Added support in SBA tool to handle a sparse set of POS files (missing POS
  files for frames).
• Improved error reporting when checking configuration in SBA tool.

Documentation

• Added missing Doxygen documentation across all libraries by ensuring that
  every file and every class has a documentation string.

Fixes since v0.2.0

OpenCV

• Changed OCV detect_features default nested algorithm from GridSURF to SURF.
  Windows has an issue with GridSURF and its nested algorithm.

VXL

• Cached parameters to vpgl_bundle_adjust so that they are not reset to defaults
  each time a config file is parsed and written back out.

Tools

• SBA tool now outputs POS and KRTD files that have same filename stem as the
  source frames they are associated with.

Documentation

• Fixed most Doxygen warnings due to improper syntax in documentation
  comments.

v0.2.0

MAPTK v0.2.0 Release Notes

This is a minor release MAPTK that provides both new functionality and fixes
over the previous v0.1.2 release. The primary contribution of this release is
the addition of a bundle adjustment algorithm and tool for running it on
tracks from the feature tracking tool. Currently, the only concrete
implementation of bundle adjustment is provided by VXL.

Secondarily, this release provides support for documentation strings for
configuration options. These strings are written as comments in the
configuration files. Furthermore, internal parameters used by OpenCV algorithms
following the cv::Algorithm design are now automatically converted to MAPTK
config options. So, for example, one can now select which algorithm to use
in the OpenCV FeatureDetector (SIFT, SURF, ORB, etc.) and then set the
various parameters of that chosen algorithm.

Updates since v0.1.2

Core

• Applied the "abstract base class, templated derived class" pattern to the
  camera class. The same pattern had been used for features and landmarks.
  It allows a camera to be implemented in either double or float but
  maintain a type-agnostic interface through a common base class.
• Added type conversion for rotation, camera, and camera_intrinsics
  (e.g. cast rotation_ to rotation_).
• Added a look_at() member function to the camera_ class to set the camera
  rotation such that the camera looks at a specified point and has an up
  direction aligned with the specified scene up direction.
  Unit tests provided.
• Added map() and unmap() member functions to camera_intrinsics to apply
  and undo the camera intrinsic mapping as 2D-2D transformation. Also can
  map 3D points in normalized camera coordinates to 2D image coordinates.
  Unit tests provided.
• Added project() member function to the camera_ class project 3D points to
  2D image points by applying both extrinsic and intrinsic parameters.
  Unit tests provided.
• Added a magnitude(), magnitude_sqr() members and normalized() function for
  the vector class.
• Added a vector_ constructor from a raw array of data (const T*)
• Added a matrix_ member functions to set and extract rows and columns.
• Added a matrix_ member function to update a sub-matrix.
• Implemented the input and output stream operator for the rotation class.
• Added == and != operators to the rotation class.
• Added constructors and accessor functions to convert rotations to and
  from axis/angle representation and the related Rodrigues vector
  representation. Unit tests provided.
• Added a track ID member to the track class.
• Added landmark_map abstract container class to hold mappings between
  track/landmark IDs and landmark objects. Also provided a default
  implementation using std::map.
• Added camera_map abstract container class to hold mappings between frame
  numbers and camera objects. Also provided a default implementation
  using std::map.
• Added a bundle adjustment abstract algorithm that take a camera_map,
  a landmark_map, and a track_set and returns optimized versions of the
  camera_map and landmark_map.
• Added metrics for computing reprojection errors on SBA results.
  Currently support is Root-Mean-Square-Error (RMSE) of reprojections.
• Added key description in maptk::config_block.
• Added output of key descriptions as comments in configuration file output.
• Added use of config_block key descriptions to nested algorithm utilities
  and track_features utility.
• Added functions for reading and writing track files. Updated tools
  to use these functions.
• Added explicit functions for reading and writing POS files (ins_data).
  Updated tools to use these functions.
• Added explicit functions for reading and writing cameras in KRTD files.
  Also provided camera base class operator<< to support this.
• Added a function to write a landmark map in PLY file format.
• Added functions for batch initialization of cameras with INS data and
  batch updating of INS data using cameras.
• Added helper functions to track_set to return the set of all track IDs
  and all frame IDs contained in the tracks in the set.
• Added a tool to run sparse bundle adjustment on tracks read from a file.

VXL

• Added conversions between maptk::camera_ and vpgl_perspective_camera
• Added vxl::camera_map to implement the maptk::camera_map container using
  a map of vpgl_perspective_camera internally.
• Added vxl::bundle_adjust to implement to maptk::algo::bundle_adjust using
  vpgl_bundle_adjust from VXL.

OpenCV

• Added ability to configure nested, and recursively nested OpenCV
  cv::Algorithm instances.

Fixes since v0.1.2

Core

• Fixed typo in variable name in camera_ constructor (intrincs --> intrinsics)
• Fixed landmark inheritance: landmark_ is now derived from landmark.
• Fixed invalid doxygen syntax in rotation.h
• Rotation constructor from quaternion vector is now explicit to avoid
  accidental casting.
• update_camera() and update_ins_data() functions of local_geo_cs are now const
  as they should have been.
• Set ins_data source_name to be MAPTK in defualt constructor and update
  functions to avoid writing out unnamed POS files.
• Removed CLIF hack in rotation yaw-pitch-roll constructor.
• Fixed rotation_::get_yaw_pitch_roll() function to work symmetrically
  with the related constructor. Added tests to verify.
• Added std::skipws in operator>> for vector_ and matrix_ to allow used in
  boost::lexical_cast, which is used by the config file parser.

v0.1.2

MAPTK v0.1.2 Release Notes

This release provides patches to the MAPTK v0.1.1 release to address issues.
MAPTK v0.1.2 is primarily a bug fix release with minimal new functionality.

Updates since v0.1.1

CMake

• Added compiler specific flag settings structures, with initial, basic GCC
  and MSVC flags.
• Added addition of position-independent code flag when building statically.
• Build shared by default on Windows (no support yet for static Windows
  builds).

Fixes since v0.1.1

CMake

• Corrected MAKE_<module>_LIB flag typo bug in target utils.

Core Library

• New minimum requirement for Boost: 1.46.1. This is enforced in the
  CMakeLists.txt when finding Boost.
• Fixed grammar for configuration file parsing to be compatible for Boost
  1.46.1 and above.
• Fixed and added use of export flags to resolve and support DLL compilation
  on Windows.

OpenCV Library

• Added use of export flags to resolve and support DLL compilation on
  Windows.

Proj Library

• Added use of export flags to resolve and support DLL compilation on
  Windows.

VXL Library

• Added use of export flags to resolve and support DLL compilation on
  Windows.

Tests

• Added parentheses around arguments to test macros in test_common.h.
  This allows arguments to be expressions, like "a > 0.0", without
  interfering with the stream operators.
• Increased the tolerance on the homography estimation noisy points test.
  It was failing randomly because the error was just over the tolerance.

Warnings / Errors

• Fixed various Windows VS10 compiler warnings

v0.1.1

MAPTK v0.1.1 Release Notes

This release provides patches to the MAPTK v0.1.0 release to address issues.
MAPTK v0.1.1 is primarily a bug fix release with very minimal new functionality.

Updates since v0.1.0

Core Library

• Completed the implementation of the landmark class, fixed compiler errors,
  and provided template instantiations so that it is compiled.
• Added a non-templated base class landmark with a double precision interface
  that mirrors the approach used in the feature class.

OpenCV Library

• Renamed maptk::ocv::ocv_image_container to maptk::ocv::image_container

PROJ Library

• Renamed maptk::proj::proj_geo_map to maptk::proj::geo_map

VXL Library

• Renamed maptk::vxl::vxl_image_container to maptk::vxl::image_container

Documentation

• Added overview pages for each of the libraries in the Doxygen documentation.

Fixes since v0.1.0

Core Library

• Fixed bug in function maptk::local_geo_cs::update_ins_data(). Was not
  using reference coordinate UTM zone.

Documentation

• Fixed some documentation of the landmark class that was mistakenly using
  the name feature.
• Enabled dependency between modules in Doxygen so that Doxygen generated
  documentation for add-on modules can refer to the documentation in core.
• Fixed doxygen warnings dealing with incorrect object references.

Warnings / Errors

• Fixed various gcc compiler warnings (GCC 4.7.7)

v0.1.0

MAPTK v0.1.0 Release Notes

This is the first formal release of MAPTK. The features in this initial release
are summarized below. Future release notes will describe modifications since
the previous release.

Library Features

Package Configuration, Build System, & Documentation

• Build system uses CMake as a meta build system for easy build configuration,
  cross-platform compiling, and dashboard regression testing.
• A unit testing framework using CTest is provided in the 'test' directory.
  This makes writing unit tests easy.
• A CMake script is provided to make it easy for users to submit nightly builds
  and unit test runs to the MAPTK CDash dashboard. The CMake script is
  cmake/dashboard-scripts/MAPTK_common.cmake
• CMake scripts are provided to make it very easy to build the MAPTK code
  documentation using Doxygen. Just turn on the "MAPTK_ENABLE_DOCS" option
  in CMake to create a documentation build target (if you have Doxygen).
  Turn on "MAPTK_INSTALL_DOCS" to have to built documentation installed.

Core Library

• The core library contains
  • low-level mathematical structures (matrix, vector, covariance, rotation)
  • camera representation structures (camera, camera intrinsics)
  • feature tracking structures (image, feature, descriptor, landmark, track)
  • geographic structures (INS data, local geo coordinate system)
  • configuration management (config block, registrar)
  • definitions of C++ exceptions (exceptions directory)
  • abstract algorithm definitions (algo directory)
• The low-level mathematical structures are templated for use with either
  single or double precision floating point types. They provide basic
  linear algebra for 1-4 dimensional spaces.
• The camera structures are also currently templated over float type and
  provide a basic pin-hole camera model representation by building on the
  lower-level mathematical types
• The image representation currently supports on unsigned byte images.
  It is designed to represent various image memory layouts and easily
  share memory between multiple image objects. Minimal image manipulation
  operators are provided. The intent is that most image manipulation will
  occur in 3rd party code and MAPTK image structure provides a vehicle
  for transferring data between 3rd party representations.
• Feature tracking structures provide abstract base class implementations,
  which are not templated by float type. There are derived classes
  that are templated and provide implementations based on lower-level
  mathematical structures. As with the image class, these are structures
  are primarily a means to transfer data between 3rd party libraries by
  establishing a common interface.
• Feature tracking structures also have corresponding "set" structures to
  encapsulate collections of these objects (feature_set, descriptor_set,
  match_set, track_set). These are abstract base classes that provide
  "simple" derived classes (e.g. simple_feature_set) that implement the
  set using a STL vector of objects. The purpose of these sets is to
  allow the add-on modules to use custom data contains that only need to
  convert data structure on demand. For example, an OpenCL feature
  detector could store features in GPU memory and pass them directly
  to an OpenCL descriptor extractor without needing to transfer back
  to CPU memory.
• Geographic structures are currently focus on the data in the POS file
  format and mapping coordinates between Lat-Long and UTM. The ins_data
  structure is a direct representation of the contents of a POS file.
  The local geographic coordinate system (local_geo_cs) structure provides
  mappings between INS data and camera pose in a local UTM coordinate system.
• Configuration structures are used to dynamically configure combinations
  of algorithms and parameters at run time. The registrar class is used
  to create a look-up table of all registered algorithms by their name.
  The config_block structure represents a configuration of (potentially
  nested) algorithms and their parameters. The config_block is read and
  written to a configuration file to allow run-time configuration of
  algorithms and their associated parameters
• The algo directory provides a hierarchy of algorithms that can be
  combined together (or even nested) to build a sparse bundle adjustment
  system. Each algorithm provides an abstract base class, which defines
  the algorithm API. Each algorithm then has one or more implementations,
  generally using 3rd party software, that provide the required functionality.
  This allows a highly modular system where each algorithm component can be
  swapped out for alternate implementations.
• The abstract algorithms in this release are
  • image_io (read and write image files)
  • geo_map (convert Lat-Long to UTM coordinates)
  • detect_features (detect feature points on an image)
  • extract_descriptors (extract descriptors around feature points in an image)
  • match_features (match features in two images based on feature & descriptor)
  • estimate_homography (uses feature matches to estimate a homography matrix)
  • track_features (track features from frame to frame producing tracks)
    The track_features algorithm makes use of nested abstract algorithms
    detect_features, extract_descriptors, and match_features
• While most algorithm implementations are in add-on modules, some are in
  core/algo. In this release, these are
  • simple_track_features (implements track_features)
    Most of the work is done by the nested algorithms
  • match_feature_homography (implements match_features)
    This is an algorithm modifier. It contains another match_features
    algorithm to do the real work. It then uses an estimate_homography
    algorithm to estimate a homography and uses it to filter the matches.

Proj Module

• This module provides implementations dependent on the Proj4 library for
  geographic coordinate projections.
• Provides an implementation of the geo_map algorithm using pj_transform().

VXL Module

• This module provides implementations dependent on the VXL (Vision X
  Libraries) collection of computer vision libraries.
• Provides an implementation of an image_container for vil_image_view.
  This allows shallow copies (shared memory) between VXL and MAPTK image
  representations.
• Provides an implementation of the image_io algorithm.
  This uses vil_load() and vil_save() to read and write images.
• Provides an implementation of the estimate_homography algorithm.
  This uses rrel (Rensselaer robust estimation library)

OCV Module

• This module provides implementations dependent on the OpenCV
  collection of computer vision libraries.
• Provides an implementation of an image_container for cv::Mat.
  This allows shallow copies (shared memory) between OpenCV and MAPTK image
  representations.
• Provides an implementation of the image_io algorithm.
  This uses cv::imread() and cv::imwrite() to read and write images.
• Provides an implementation of the feature_set container.
  This allows passing of features in cv::Keypoint format and conversions
  between cv::Keypoint and maptk::feature.
• Provides an implementation of the detect_features algorithm.
  This allows feature detection using cv::FeatureDetector.
• Provides an implementation of the descriptor_set container.
  This allows passing of descriptor in cv::Mat format and conversions
  between cv::Mat and maptk::descriptor.
• Provides an implementation of the extract_descriptors algorithm.
  This allows feature detection using cv::DescriptorExtractor.
• Provides an implementation of the match_set container.
  This allows passing of feature matches in cv::DMatch format and conversions
  between cv::Dmatch and maptk::match.
• Provides an implementation of the match_features algorithm.
  This allows feature matching using cv::DescriptorMatcher.
• Provides conversion functions between cv::Mat and maptk::matrix.
• Provides an implementation of the estimate_homography algorithm.
  This uses cv::findHomography()

Tools and Scripts

Compiled Command-line Tools

• track_features -- Accepts a list of images files, computes frame-to-frame
  feature tracking, and writes of the resulting feature tracks in a simple
  ASCII text file format. This tool uses the image_io and track_features
  algorithms to compute results. The tool accepts a config file to select
  between algorithms implementations and to adjust parameter. However, in
  this release, only a minimal set of config options are exposed.
• pos2krtd -- Accepts a POS file, or a directory of POS files and produces
  corresponding KRTD camera files. The yaw, pitch, roll, latitude, longitude,
  and altitude fields of the POS file are mapped to a rotation matrix and
  a translation vector in UTM coordinates. If a directory of POS files is
  provided, the KRTD files are also translated to local UTM coordinate
  system with the origin on the ground at the mean of the camera easting and
  northing values. In this release, the intrinsic camera parameters are
  not specified and produce an identity calibration (K) matrix.

Python Scripts

• draw_tracks.py -- Accepts a track file (as produced by track_features)
  and draws the tracks on a single plot with each feature track drawn as a
  polyline in a randomly selected color. This script provides a visual
  debugging tool to assess the quality and distribution of tracks produced
  by the track_features tool.
• blender/io_import_krtd_camera.py -- This is a Python plug-in for the
  open source Blender application. It adds a menu item to the "File > Import"
  menu that allows importing KRTD camera files and constructing Blender camera
  objects. By default it loads a single KRTD file, but it also has options
  to load a directory of KRTD files and produce either multiple camera
  objects or an animation sequence of a single camera object. Translation,
  rotation, and focal length parameters are imported. This script is
  useful...