Package stitching.model

Class Model

java.lang.Object
stitching.model.Model
All Implemented Interfaces:
CoordinateTransform
Direct Known Subclasses:
InvertibleModel
public abstract class Model extends Object implements CoordinateTransform
Abstract class for arbitrary transformation models to be applied to Points in n-dimensional space.

Model: R^n --> R^n

Provides methods for generic optimization and model extraction algorithms. Currently, the Random Sample Consensus \citet{FischlerB81} and a robust regression method are implemented.

TODO: A model is planned to be a generic transformation pipeline to be applied to images, volumes or arbitrary sets of n-dimensional points. E.g. lens transformation of camera images, pose and location of mosaic tiles, non-rigid bending of confocal stacks etc.

BibTeX: 

 @article{FischlerB81,
         author    = {Martin A. Fischler and Robert C. Bolles},
   title     = {Random sample consensus: a paradigm for model fitting with applications to image analysis and automated cartography},
   journal   = {Communications of the ACM},
   volume    = {24},
   number    = {6},
   year      = {1981},
   pages     = {381--395},
   publisher = {ACM Press},
   address   = {New York, NY, USA},
   issn      = {0001-0782},
   doi       = {http://doi.acm.org/10.1145/358669.358692},
 }
Version:
0.2b
Author:
Stephan Saalfeld

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected double
    cost
    The cost depends on what kind of algorithm is running.
    protected static final Random
    rnd
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    Model()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    betterThan(Model m)
    less than operater to make the models comparable, returns false for error < 0
    abstract Model
    clone()
    Clone the model.
    static final <M extends Model>
    M
    filter(Class<M> modelClass, Collection<PointMatch> candidates, Collection<PointMatch> inliers)
    Estimate a Model and filter potential outliers by robust iterative regression.
    static <M extends Model>
    M
    filterRansac(Class<M> modelType, List<PointMatch> candidates, Collection<PointMatch> inliers, int iterations, float max_epsilon, float min_inlier_ratio)
    Estimate the best model for a set of feature correspondence candidates.
    abstract void
    fit(Collection<PointMatch> matches)
    Fit the Model to a set of data points minimizing the global transfer error.
    final double
    getCost()
     
    final double
    getError()
    Deprecated.
    The term Error may be missleading---use getCost() instead
    abstract int
    getMinSetSize()
     
    static final <M extends Model>
    M
    ransac(Class<M> modelClass, List<PointMatch> candidates, Collection<PointMatch> inliers, int iterations, double epsilon, double min_inlier_ratio)
    Estimate a Model from a set with many outliers by first filtering the worst outliers with ransac \citet[{FischlerB81} tand filter potential outliers by robust iterative regression.
    final void
    setCost(double c)
     
    final void
    setError(double e)
    Deprecated.
    The term Error may be missleading---use getCost() instead
    abstract void
    shake(Collection<PointMatch> matches, float scale, float[] center)
    randomly change the model a bit estimates the necessary amount of shaking for each single dimensional distance in the set of matches
    static final boolean
    test(Model model, Collection<PointMatch> candidates, Collection<PointMatch> inliers, double epsilon, double min_inlier_ratio)
    Test the Model for a set of point correspondence candidates.
    abstract String
    toString()
    Create a meaningful string representation of the model for save into text-files or display on terminals.

    Methods inherited from class java.lang.Object

    equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    Methods inherited from interface stitching.model.CoordinateTransform

    apply, applyInPlace

  • Field Details

    • rnd

      protected static final Random rnd

    • cost

      protected double cost
      The cost depends on what kind of algorithm is running. It is always true that a smaller cost is better than large cost

  • Constructor Details

    • Model

      public Model()

  • Method Details

    • getMinSetSize

      public abstract int getMinSetSize()

    • getCost

      public final double getCost()

    • setCost

      public final void setCost(double c)

    • getError

      @Deprecated public final double getError()
      Deprecated.
      The term Error may be missleading---use getCost() instead

    • setError

      @Deprecated public final void setError(double e)
      Deprecated.
      The term Error may be missleading---use getCost() instead

    • betterThan

      public boolean betterThan(Model m)
      less than operater to make the models comparable, returns false for error < 0
      Parameters:
      m -
      Returns:
      false for error < 0, otherwise true if this.error is smaller than m.error

    • shake

      public abstract void shake(Collection<PointMatch> matches, float scale, float[] center)
      randomly change the model a bit estimates the necessary amount of shaking for each single dimensional distance in the set of matches
      Parameters:
      matches - point matches
      scale - gives a multiplicative factor to each dimensional distance (scales the amount of shaking)
      center - local pivot point for centered shakes (e.g. rotation)

    • fit

      public abstract void fit(Collection<PointMatch> matches) throws NotEnoughDataPointsException
      Fit the Model to a set of data points minimizing the global transfer error. This is assumed to be implemented as a least squares minimization. Use ransac and/ or filter(Class, Collection, Collection) to remove outliers from your data points The estimated model transfers match.p2.local to match.p1.world.
      Parameters:
      matches - set of point correpondences
      Throws:
      NotEnoughDataPointsException - an exception if matches does not contain enough data points

    • test

      public static final boolean test(Model model, Collection<PointMatch> candidates, Collection<PointMatch> inliers, double epsilon, double min_inlier_ratio)
      Test the Model for a set of point correspondence candidates. Return true if the number of inliers / number of candidates is larger than or equal to min_inlier_ratio, otherwise false. Clears inliers and fills it with the fitting subset of candidates.
      Parameters:
      candidates - set of point correspondence candidates
      inliers - set of point correspondences that fit the model
      epsilon - maximal allowed transfer error
      min_inlier_ratio - minimal ratio of inliers (0.0 => 0%, 1.0 => 100%)

    • filter

      public static final <M extends Model> M filter(Class<M> modelClass, Collection<PointMatch> candidates, Collection<PointMatch> inliers) throws NotEnoughDataPointsException
      Estimate a Model and filter potential outliers by robust iterative regression. This method performs well on data sets with low amount of outliers. If you have many outliers, you can filter those with a `tolerant' RANSAC first as done in filterRansac(java.lang.Class<M>, java.util.List<stitching.model.PointMatch>, java.util.Collection<stitching.model.PointMatch>, int, float, float).
      Parameters:
      modelClass - Class of the model to be estimated
      candidates - Candidate data points eventually inluding some outliers
      inliers - Remaining after the robust regression filter
      Throws:
      NotEnoughDataPointsException

    • ransac

      public static final <M extends Model> M ransac(Class<M> modelClass, List<PointMatch> candidates, Collection<PointMatch> inliers, int iterations, double epsilon, double min_inlier_ratio) throws NotEnoughDataPointsException
      Estimate a Model from a set with many outliers by first filtering the worst outliers with ransac \citet[{FischlerB81} tand filter potential outliers by robust iterative regression. This method performs well on data sets with low amount of outliers. If you have many outliers, you can filter those with a `tolerant' RANSAC first as done in filterRansac(java.lang.Class<M>, java.util.List<stitching.model.PointMatch>, java.util.Collection<stitching.model.PointMatch>, int, float, float).
      Parameters:
      modelClass - Class of the model to be estimated
      candidates - Candidate data points inluding (many) outliers
      inliers - Remaining candidates after RANSAC
      iterations -
      epsilon -
      min_inlier_ratio - minimal number of inliers to number of candidates
      Returns:
      an instance of
      Throws:
      NotEnoughDataPointsException

    • filterRansac

      public static <M extends Model> M filterRansac(Class<M> modelType, List<PointMatch> candidates, Collection<PointMatch> inliers, int iterations, float max_epsilon, float min_inlier_ratio) throws NotEnoughDataPointsException
      Estimate the best model for a set of feature correspondence candidates. Increase the error as long as not more inliers apear. TODO: This is a very crappy way of identifying the minimal max_epsilon and maximal number of inliers at the same time. We suggest a more elaborate technique as follows: 1. Run RANSAC with large max_epsilon resulting in many outliers included. 2. Get rid of the outliers using the robust regression method of Dutter and Huber
      Throws:
      NotEnoughDataPointsException

    • toString

      public abstract String toString()
      Create a meaningful string representation of the model for save into text-files or display on terminals.
      Overrides:
      toString in class Object

    • clone

      public abstract Model clone()
      Clone the model.
      Overrides:
      clone in class Object