AbstractModel (Fiji Javadocs 0-SNAPSHOT API)

java.lang.Object
- mpicbg.models.AbstractModel<M>

All Implemented Interfaces:: Serializable, CoordinateTransform, Model<M>

Direct Known Subclasses:: AbstractAffineModel1D, AbstractAffineModel2D, AbstractAffineModel3D, ConstantModel, CubicBSplineTransform, HomographyModel2D, IdentityModel, InterpolatedModel, PolynomialModel2D, TranslationInvariantModel

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 <saalfelds@janelia.hhmi.org>
See Also:: Serialized Form

Field Summary

Fields
Modifier and Type Field and Description

protected double cost
The cost depends on what kind of algorithm is running.

protected static Random rnd

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

Constructor Summary

Constructors
Constructor and Description

AbstractModel()

Constructors
Constructor and Description
`AbstractModel()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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  boolean test(Collection candidates,
 Collection 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  boolean test(Collection candidates,
 Collection 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  boolean filter(Collection candidates,
 Collection 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(java.util.List, java.util.Collection, int, double, double, int, double).
 
 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  boolean filter(Collection candidates,
 Collection 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  boolean filter(Collection candidates,
 Collection 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  boolean ransac(List candidates,
 Collection 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:
 
 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  boolean ransac(List candidates,
 Collection 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  boolean filterRansac(List candidates,
 Collection 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  boolean filterRansac(List candidates,
 Collection 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  boolean filterRansac(List candidates,
 Collection 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  boolean filterRansac(List candidates,
 Collection 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 - if not enough data points were available
 
 IllDefinedDataPointsException - if the set of data points is inappropriate to solve the Model
 - 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 - if not enough data points were available
 
 IllDefinedDataPointsException - if the set of data points is inappropriate to solve the Model
 - localSmoothnessFilter
```
public  boolean localSmoothnessFilter(Collection candidates,
 Collection 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:

Class AbstractModel<M extends AbstractModel<M>>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface mpicbg.models.Model

Methods inherited from interface mpicbg.models.CoordinateTransform

Field Detail

rnd

cost

Constructor Detail

AbstractModel

Method Detail

getCost

setCost

betterThan

test

test

filter

filter

filter

ransac

ransac

filterRansac

filterRansac

filterRansac

filterRansac

icp

fit

fit

localSmoothnessFilter