mpicbg.models
Class AbstractModel<M extends AbstractModel<M>>

java.lang.Object
  extended by mpicbg.models.AbstractModel<M>
All Implemented Interfaces:
Serializable, CoordinateTransform, Model<M>
Direct Known Subclasses:
AbstractAffineModel1D, AbstractAffineModel2D, AbstractAffineModel3D, ConstantModel, HomographyModel2D, IdentityModel, InterpolatedModel

public abstract class AbstractModel<M extends AbstractModel<M>>
extends Object
implements Model<M>, Serializable

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 \cite{FischlerB81}, a robust regression method and the Iterative Closest Point Algorithm \cite{Zhang94} are implemented. 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},
 }
 @article{Zhang94,
   author    = {{Zhengyou Zhang}},
   title     = {Iterative point matching for registration of free-form curves and surfaces},
   journal   = {International Journal of Computer Vision},
   volume    = {13},
   number    = {2},
   month     = {October},
   year      = {1994},
   pages     = {119--152},
 }
 

Author:
Stephan Saalfeld
See Also:
Serialized Form

Field Summary
protected  double cost
          The cost depends on what kind of algorithm is running.
protected static Random rnd
           
 
Constructor Summary
AbstractModel()
           
 
Method Summary
 boolean betterThan(M m)
          "Less than" operater to make Models comparable.
<P extends PointMatch>
boolean
filter(Collection<P> candidates, Collection<P> inliers)
          Call filter(Collection, Collection, double) with maxTrust = 4 and minNumInliers = Model.getMinNumMatches().
<P extends PointMatch>
boolean
filter(Collection<P> candidates, Collection<P> inliers, double maxTrust)
          Call filter(Collection, Collection, double, int) with minNumInliers = Model.getMinNumMatches().
<P extends PointMatch>
boolean
filter(Collection<P> candidates, Collection<P> inliers, double maxTrust, int minNumInliers)
          Estimate the AbstractModel and filter potential outliers by robust iterative regression.
<P extends PointMatch>
boolean
filterRansac(List<P> candidates, Collection<P> inliers, int iterations, double maxEpsilon, double minInlierRatio)
          Call filterRansac(List, Collection, int, double, double, double) with maxTrust = 4.
<P extends PointMatch>
boolean
filterRansac(List<P> candidates, Collection<P> inliers, int iterations, double maxEpsilon, double minInlierRatio, double maxTrust)
          Call filterRansac(List, Collection, int, double, double, int, double) with minNumInliers = Model.getMinNumMatches().
<P extends PointMatch>
boolean
filterRansac(List<P> candidates, Collection<P> inliers, int iterations, double maxEpsilon, double minInlierRatio, int minNumInliers)
          Call filterRansac(List, Collection, int, double, double, int, double) with maxTrust = 4.
<P extends PointMatch>
boolean
filterRansac(List<P> candidates, Collection<P> inliers, int iterations, double maxEpsilon, double minInlierRatio, int minNumInliers, double maxTrust)
          Estimate a AbstractModel from a set with many outliers by first filtering the worst outliers with RANSAC \citet[{FischlerB81} and filter potential outliers by robust iterative regression.
 void fit(double[][] p, double[][] q, double[] w)
          Default fit implementation using Model.fit(Collection).
 void fit(float[][] p, float[][] q, float[] w)
          Default fit implementation using Model.fit(Collection).
 double getCost()
           
 Collection<PointMatch> icp(List<Point> p, List<Point> q)
          Estimate the best model in terms of the Iterative Closest Point Algorithm \cite{Zhang94} for matching two point clouds into each other.
<P extends PointMatch>
boolean
localSmoothnessFilter(Collection<P> candidates, Collection<P> inliers, double sigma, double maxEpsilon, double maxTrust)
          Default implementation of localSmoothnessFilter(Collection, Collection, double, double, double).
<P extends PointMatch>
boolean
ransac(List<P> candidates, Collection<P> inliers, int iterations, double epsilon, double minInlierRatio)
          Call ransac(List, Collection, int, double, double, int) with minNumInliers = Model.getMinNumMatches().
<P extends PointMatch>
boolean
ransac(List<P> candidates, Collection<P> inliers, int iterations, double epsilon, double minInlierRatio, int minNumInliers)
          Find the AbstractModel of a set of PointMatch candidates containing a high number of outliers using RANSAC \citet[{FischlerB81}.
 void setCost(double c)
           
<P extends PointMatch>
boolean
test(Collection<P> candidates, Collection<P> inliers, double epsilon, double minInlierRatio)
          Call test(Collection, Collection, double, double, int) with minNumInliers = Model.getMinNumMatches().
<P extends PointMatch>
boolean
test(Collection<P> candidates, Collection<P> inliers, double epsilon, double minInlierRatio, int minNumInliers)
          Test the AbstractModel for a set of PointMatch candidates.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface mpicbg.models.Model
copy, fit, getMinNumMatches, set
 
Methods inherited from interface mpicbg.models.CoordinateTransform
apply, applyInPlace
 

Field Detail

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 Detail

AbstractModel

public AbstractModel()
Method Detail

getCost

public final double getCost()
Specified by:
getCost in interface Model<M extends AbstractModel<M>>

setCost

public final void setCost(double c)
Specified by:
setCost in interface Model<M extends AbstractModel<M>>

betterThan

public final boolean betterThan(M m)
"Less than" operater to make Models comparable.

Specified by:
betterThan in interface Model<M extends AbstractModel<M>>
Parameters:
m -
Returns:
false for cost < 0.0, otherwise true if this.cost is smaller than m.cost

test

public final <P extends PointMatch> boolean test(Collection<P> candidates,
                                                 Collection<P> inliers,
                                                 double epsilon,
                                                 double minInlierRatio,
                                                 int minNumInliers)
Test the AbstractModel for a set of PointMatch 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. Sets cost = 1.0 - |inliers| / |candidates|.

Specified by:
test in interface Model<M extends AbstractModel<M>>
Parameters:
candidates - set of point correspondence candidates
inliers - set of point correspondences that fit the model
epsilon - maximal allowed transfer error
minInlierRatio - minimal ratio |inliers| / |candidates| (0.0 => 0%, 1.0 => 100%)
minNumInliers - minimally required absolute number of inliers

test

public final <P extends PointMatch> boolean test(Collection<P> candidates,
                                                 Collection<P> inliers,
                                                 double epsilon,
                                                 double minInlierRatio)
Call test(Collection, Collection, double, double, int) with minNumInliers = Model.getMinNumMatches().

Specified by:
test in interface Model<M extends AbstractModel<M>>

filter

public final <P extends PointMatch> boolean filter(Collection<P> candidates,
                                                   Collection<P> inliers,
                                                   double maxTrust,
                                                   int minNumInliers)
                     throws NotEnoughDataPointsException
Estimate the AbstractModel 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. Sets cost to the average point transfer error.

Specified by:
filter in interface Model<M extends AbstractModel<M>>
Parameters:
candidates - Candidate data points eventually inluding some outliers
inliers - Remaining after the robust regression filter
maxTrust - reject candidates with a cost larger than maxTrust * median cost
minNumInliers - minimally required absolute number of inliers
Returns:
true if AbstractModel could be estimated and inliers is not empty, false otherwise. If false, AbstractModel remains unchanged.
Throws:
NotEnoughDataPointsException

filter

public final <P extends PointMatch> boolean filter(Collection<P> candidates,
                                                   Collection<P> inliers,
                                                   double maxTrust)
                     throws NotEnoughDataPointsException
Call filter(Collection, Collection, double, int) with minNumInliers = Model.getMinNumMatches().

Specified by:
filter in interface Model<M extends AbstractModel<M>>
Throws:
NotEnoughDataPointsException

filter

public final <P extends PointMatch> boolean filter(Collection<P> candidates,
                                                   Collection<P> inliers)
                     throws NotEnoughDataPointsException
Call filter(Collection, Collection, double) with maxTrust = 4 and minNumInliers = Model.getMinNumMatches().

Specified by:
filter in interface Model<M extends AbstractModel<M>>
Throws:
NotEnoughDataPointsException

ransac

public final <P extends PointMatch> boolean ransac(List<P> candidates,
                                                   Collection<P> inliers,
                                                   int iterations,
                                                   double epsilon,
                                                   double minInlierRatio,
                                                   int minNumInliers)
                     throws NotEnoughDataPointsException
Find the AbstractModel of a set of PointMatch candidates containing a high number of outliers using RANSAC \citet[{FischlerB81}.

Specified by:
ransac in interface Model<M extends AbstractModel<M>>
Parameters:
modelClass - class of the model to be estimated
candidates - candidate data points inluding (many) outliers
inliers - remaining candidates after RANSAC
iterations - number of iterations
epsilon - maximal allowed transfer error
minInlierRatio - minimal number of inliers to number of candidates
minNumInliers - minimally required absolute number of inliers
Returns:
true if AbstractModel could be estimated and inliers is not empty, false otherwise. If false, AbstractModel remains unchanged.
Throws:
NotEnoughDataPointsException

ransac

public final <P extends PointMatch> boolean ransac(List<P> candidates,
                                                   Collection<P> inliers,
                                                   int iterations,
                                                   double epsilon,
                                                   double minInlierRatio)
                     throws NotEnoughDataPointsException
Call ransac(List, Collection, int, double, double, int) with minNumInliers = Model.getMinNumMatches().

Specified by:
ransac in interface Model<M extends AbstractModel<M>>
Throws:
NotEnoughDataPointsException

filterRansac

public final <P extends PointMatch> boolean filterRansac(List<P> candidates,
                                                         Collection<P> inliers,
                                                         int iterations,
                                                         double maxEpsilon,
                                                         double minInlierRatio,
                                                         int minNumInliers,
                                                         double maxTrust)
                           throws NotEnoughDataPointsException
Estimate a AbstractModel from a set with many outliers by first filtering the worst outliers with RANSAC \citet[{FischlerB81} and filter potential outliers by robust iterative regression.

Specified by:
filterRansac in interface Model<M extends AbstractModel<M>>
Parameters:
candidates - candidate data points inluding (many) outliers
inliers - remaining candidates after RANSAC
iterations - number of iterations
maxEpsilon - maximal allowed transfer error
minInlierRatio - minimal number of inliers to number of candidates
minNumInliers - minimally required absolute number of inliers
maxTrust - reject candidates with a cost larger than maxTrust * median cost
Returns:
true if AbstractModel could be estimated and inliers is not empty, false otherwise. If false, AbstractModel remains unchanged.
Throws:
NotEnoughDataPointsException

filterRansac

public final <P extends PointMatch> boolean filterRansac(List<P> candidates,
                                                         Collection<P> inliers,
                                                         int iterations,
                                                         double maxEpsilon,
                                                         double minInlierRatio,
                                                         int minNumInliers)
                           throws NotEnoughDataPointsException
Call filterRansac(List, Collection, int, double, double, int, double) with maxTrust = 4.

Specified by:
filterRansac in interface Model<M extends AbstractModel<M>>
Throws:
NotEnoughDataPointsException

filterRansac

public final <P extends PointMatch> boolean filterRansac(List<P> candidates,
                                                         Collection<P> inliers,
                                                         int iterations,
                                                         double maxEpsilon,
                                                         double minInlierRatio,
                                                         double maxTrust)
                           throws NotEnoughDataPointsException
Call filterRansac(List, Collection, int, double, double, int, double) with minNumInliers = Model.getMinNumMatches().

Specified by:
filterRansac in interface Model<M extends AbstractModel<M>>
Throws:
NotEnoughDataPointsException

filterRansac

public final <P extends PointMatch> boolean filterRansac(List<P> candidates,
                                                         Collection<P> inliers,
                                                         int iterations,
                                                         double maxEpsilon,
                                                         double minInlierRatio)
                           throws NotEnoughDataPointsException
Call filterRansac(List, Collection, int, double, double, double) with maxTrust = 4.

Specified by:
filterRansac in interface Model<M extends AbstractModel<M>>
Throws:
NotEnoughDataPointsException

icp

public final Collection<PointMatch> icp(List<Point> p,
                                        List<Point> q)
Estimate the best model in terms of the Iterative Closest Point Algorithm \cite{Zhang94} for matching two point clouds into each other. p -> q

Specified by:
icp in interface Model<M extends AbstractModel<M>>
Parameters:
p - source
q - target
Returns:
the list of matches TODO Test---at least once!

fit

public void fit(float[][] p,
                float[][] q,
                float[] w)
         throws NotEnoughDataPointsException,
                IllDefinedDataPointsException
Default fit implementation using Model.fit(Collection). This foils the intention that fit(float[][], float[][], float[]) would be potentially more efficient. You should better implement it directly.

Specified by:
fit in interface Model<M extends AbstractModel<M>>
Parameters:
p - source points
q - target points
w - weights
Throws:
NotEnoughDataPointsException
IllDefinedDataPointsException

fit

public void fit(double[][] p,
                double[][] q,
                double[] w)
         throws NotEnoughDataPointsException,
                IllDefinedDataPointsException
Default fit implementation using Model.fit(Collection). This foils the intention that fit(double[][], double[][], double[]) would be potentially more efficient. You should better implement it directly.

Specified by:
fit in interface Model<M extends AbstractModel<M>>
Parameters:
p - source points
q - target points
w - weights
Throws:
NotEnoughDataPointsException
IllDefinedDataPointsException

localSmoothnessFilter

public <P extends PointMatch> boolean localSmoothnessFilter(Collection<P> candidates,
                                                            Collection<P> inliers,
                                                            double sigma,
                                                            double maxEpsilon,
                                                            double maxTrust)

Default implementation of localSmoothnessFilter(Collection, Collection, double, double, double). Requires that Model.fit(Collection) is implemented as a weighted least squares fit or something similar.

Note that if candidates == inliers and an exception occurs, inliers will be cleared according to that there are no inliers.

Specified by:
localSmoothnessFilter in interface Model<M extends AbstractModel<M>>
Returns:


Copyright © 2007-2016 Fiji. All Rights Reserved.