v0.6.0

MAP-Tk v0.6.0 Release Notes

This is a major release of MAP-Tk that provides both new functionality and
fixes over the previous v0.5.1 release. Although the API has changed
significantly, we still consider MAP-Tk to be in "pre-release" and are
not yet ready to increase the major version number and mark this release as
v1.0.0. Additional major restructuring is planned before we release v1.0.0
with a "stable" API.

The primary changes in this release are a major restructuring to provide
true dynamically loaded plugins instead of the previous module framework,
and a switch to Eigen3 to provide the core linear algebra data structure
and algorithms (e.g. matrix and vector). This release also adds a few
new algorithms and provides a preview of new C and Python bindings, which
are still under development.

The new plugin framework allows new algorithms to be loaded at runtime
without needing to recompile MAP-Tk or any tools built on top of MAP-Tk.
The previous modules (vxl, ocv, proj, vcl) have been converted to plugins,
and a new core plugin has been added for core algorithm implementations that
were previously in the maptk library. Abstract algorithm declarations are
still the main maptk library, but concrete implementations of those algorithms
are now all loaded through plugins. This means you can write your own plugin,
drop it into the plugins directory, and insert your algorithm implementations
into a MAP-Tk pipeline with just a configuration file change.

Eigen3 joins Boost as one of the few required dependencies in MAP-Tk v0.6.0.
Previously MAP-Tk had its own matrix and vector classes to reduce third party
dependencies in the main library. As development progressed, we found
ourselves adding more and more basic linear algebra code and reinventing what
is already available, and done very well, in Eigen. We decided to switch
to Eigen rather than waste time reinventing it. Eigen is a header-only library
and should be easy to obtain and use across platforms.

This release of MAP-Tk provides options for a new two-pass feature matching
approach, a feature filter algorithm, and a geometrically constrained feature
matcher. The intended use case for these is to first match a "strong" subset
of features, estimate a homography from these matches, and use the homography
to predict the approximate motion of the remaining features, then search in a
local neighborhood to quickly find weaker or more ambiguous matches that
otherwise would have been missed.

Language bindings for C and Python are also new in MAP-Tk v0.6.0. These
bindings are not yet complete, but offer a preview of what is to come.
Producing Python bindings for a C++ API is challenging for a variety of
reasons, but Python bindings for C are comparatively easy to produce. Our
approach is to produce C bindings for the C++ API and then build Python
bindings on the C API. This will also allow other language bindings to be
built in the future more easily by using the C API. The current set of
bindings allows a subset of algorithms to be run, but does not allow
introspection of the data objects.

Additional details about changes in this release are found below.

Updates since v0.5.1

Build System

• Revised modules into plugins for dynamic loading. Each plugin provides a
  library for static linking and a light weight wrapper to produce a plugin
  that is loaded at run-time.
• Provided CMake tools to make it easy to construct the plugins with minimal
  boilerplate code.
• Added install rules for CMake utilities for MAP-Tk users to create MAP-Tk
  compliant plugin interface libraries.
• Added FindEigen3 CMake module and call it to find Eigen, which is now a
  required dependency.
• Added private header CMake variables for add_library call, allowing
  visibility of file in IDEs.
• Separated out plugin management into separate library in order to allow for
  static plugin library linking for static builds, preventing a non-
  deterministic issue with dynamically loading static libraries causing
  duplicated symbols.
• Simplified string logic for finding compiler flags file.
• Added Eigen3 include directory path to include directories exported by
  MAP-Tk.
• Added support for LIB_SUFFIX. This supersedes MAPTK_LIB_SUFFIX; if the old
  variable is set, it will be used as the default value for LIB_SUFFIX, but a
  warning will be issued.

MAP-Tk Library

• Added plugin support for loading externally defined algorithm
  implementations.
• Refactored source file layout.
• Separated out algorithm implementations that used to be in the main MAP-Tk
  library into a core library with a plugin interface.
• Added required dependency on the Eigen3 header-only library. Going forward
  Eigen will provide standardized linear algebra functionality so we do not
  waste effort duplicating linear algebra code in MAP-Tk.
• Replaced maptk::matrix_<M,N,T> with Eigen::Matrix<T,M,N>
• Replaced maptk::vector_<N,T> with Eigen::Matrix<T,N,1>
• Removed vector_2_, vector_3_, and vector_4_ sub-classes
• Added missing operator>> for Eigen::Matrix<T,M,N>
• Changed internal quaternion vector in maptk::rotation_ to use
  Eigen::Quaternion and replaced most of the calculations with those
  provided by Eigen::Quaternion member functions.
• Removed use of logging helper macros from header files as logging macro
  header is not a public header.
• Added optional mask image input to track features algorithm definition and
  core implementation.
• Added transform_image function to efficiently transform in-place an image
  given a unary function that is operated on every pixel.
• Revised homography structures into objects that contain, rather than
  subclass, Eigen::Matrix.
• Revised import/export logic in auto-generated plugin library code.
• Redefined algorithm registration to allow for overwriting by label.
• Added informative debugging messages to allow for plugin implementation
  tracing.
• Added constructor from base class for feature_.
• Added abstract base class for algorithm to filter a set of features
  (filter_features).
• Added verbose output during configuration check failure to make it easy
  to track down errors in configuration files.
• Moved several member functions from algorithm_def up to the algorithm
  base class. This provides a better polymorphic design, allowing algorithms
  to be manipulated without knowing the algorithm type. Functions moved up
  include "clone" and "create" (each now returns algorithm_sptr);
  "registered_names" and "has_impl_name" (each now takes a type_name string);
  and the "*_nested_algo_configuration" helpers (each now takes a type_name
  string).

Core Plugin

• Separated out algorithm implementations that used to be in the main MAP-Tk
  library to create this core plugin.
• Updated compute_ref_homog algorithm to allow additional constraints
  (minimum inliers, reference frame [non]regression)
• Added concrete algorithm to filter a feature set by magnitude of detector
  response (filter_features_magnitude).
• Updated match_features_homography to allow two-pass feature matching with
  (potentially) different matchers, a feature filter applied during the
  first pass, and homography warping applied between the matchers.

OCV Plugin

• Converted module library into a library-plugin pair.

PROJ Plugin

• Converted module library into a library-plugin pair.

VisCL Plugin

• Converted module library into a library-plugin pair.
• Renamed viscl_image_container to vcl::image_container for consistency.
• Added missing Doxygen page for this plugin.

VXL Plugin

• Converted module library into a library-plugin pair.
• Added a geometrically constrained feature matcher
  (match_features_constrained) that uses a search radius on feature location
  (and optionally scale and orientation) to limit search for matches.
• Added parameters to the image_io load function to allow stretching of the
  image intensity range, either automatically or with a manually specified
  range. This is useful for handling 12-bit or 16-bit images, for example.

C/Python API

• Added C and Python interfaces. These wrappers are currently incomplete but
  offer an introduction into what they will look like and how they will
  function.

Test System / Tests

• Refactored test code to reference correct libraries and use new plugin
  loading and management where required.
• Added automatic message generation to test executables to inform the caller
  of available test names in that executable.

Tools

• In track features tool, Added ability to specify paired mask image files.

Fixes since v0.5.1

Build System

• Fixed addition of library to global maptk_libraries property to only happen
  if that library is being exported.
• Removed target generation for doxygen template file configuration which had
  caused race-conditions in parallel builds that included documentation
  generation.
• Changed target property getter function to one that is not currently subject
  to a CMake regression bug.

Core Plugin

• Added missing header to source list
• Fixed import/export macro definition variable spelling.

Test System / Tests

• Fixed CMake-side parsing of test source files during discovery mode to allow
  extra white-space in IMPLEMENT_TEST() and TEST_PROPERTY() parameter areas.