mpicbg.models

Interface Model<M extends Model<M>>

All Superinterfaces:

CoordinateTransform, Serializable

All Known Implementing Classes:

AbstractAffineModel1D, AbstractAffineModel2D, AbstractAffineModel3D, AbstractModel, AffineModel1D, AffineModel2D, AffineModel3D, ConstantAffineModel1D, ConstantModel, HomographyModel2D, IdentityModel, InterpolatedAffineModel1D, InterpolatedAffineModel2D, InterpolatedAffineModel3D, InterpolatedModel, InvertibleConstantModel, InvertibleInterpolatedModel, RigidModel2D, RigidModel3D, SimilarityModel2D, SimilarityModel3D, TranslationModel1D, TranslationModel2D, TranslationModel3D

public interface Model<M extends Model<M>>
extends CoordinateTransform

CoordinateTransform whose parameters can be estimated through a least-squares(like) fit. 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>

Method Summary

Modifier and Type	Method and Description
boolean	betterThan(M m) "Less than" operater to make Models comparable.
M	copy() Clone the model.
<P extends PointMatch> boolean	filter(Collection<P> candidates, Collection<P> inliers) Call filter(Collection, Collection, double) with maxTrust = 4 and minNumInliers = getMinNumMatches().
<P extends PointMatch> boolean	filter(Collection<P> candidates, Collection<P> inliers, double maxTrust) Call filter(Collection, Collection, double, int) with minNumInliers = getMinNumMatches().
<P extends PointMatch> boolean	filter(Collection<P> candidates, Collection<P> inliers, double maxTrust, int minNumInliers) Estimate the Model 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 = 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 Model from a set with many outliers by first filtering the worst outliers with RANSAC \citet[{FischlerB81} and filter potential outliers by robust iterative regression.
<P extends PointMatch> void	fit(Collection<P> matches) Fit the Model to a set of data points minimizing the global transfer error.
void	fit(double[][] p, double[][] q, double[] w) Fit the Model to a set of data points minimizing the global transfer error.
void	fit(float[][] p, float[][] q, float[] w) Fit the Model to a set of data points minimizing the global transfer error.
double	getCost()
int	getMinNumMatches()
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) Filter a Collection of PointMatches by the smoothness of their support for the given Model.
<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 = getMinNumMatches().
<P extends PointMatch> boolean	ransac(List<P> candidates, Collection<P> inliers, int iterations, double epsilon, double minInlierRatio, int minNumInliers) Find the Model of a set of PointMatch candidates containing a high number of outliers using RANSAC \citet[{FischlerB81}.
void	set(M m) Set the model to m
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 = getMinNumMatches().
<P extends PointMatch> boolean	test(Collection<P> candidates, Collection<P> inliers, double epsilon, double minInlierRatio, int minNumInliers) Test the Model for a set of PointMatch candidates.

Methods inherited from interface mpicbg.models.CoordinateTransform

apply, applyInPlace

Method Detail

getMinNumMatches

int getMinNumMatches()

Returns:

the minimal number of PointMatches required to solve the model.

getCost

double getCost()

setCost

void setCost(double c)

betterThan

boolean betterThan(M m)

"Less than" operater to make Models comparable.

Parameters:

m -

Returns:

false for cost < 0.0, otherwise true if this.getCost() is smaller than m.getCost()

fit

void fit(float[][] p,
         float[][] q,
         float[] w)
  throws NotEnoughDataPointsException,
         IllDefinedDataPointsException

Fit the Model to a set of data points minimizing the global transfer error. This is assumed to be implemented as a weighted least squares minimization.

This is a lower level version of fit(Collection) for optimal memory efficiency.

The estimated model transfers p to q.

n-dimensional points are passed as an n-dimensional array of floats, e.g. four 2d points as:

 float[][]{
   {x1, x2, x3, x4},
   {y1, y2, y3, y4} }
 

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

void fit(double[][] p,
         double[][] q,
         double[] w)
  throws NotEnoughDataPointsException,
         IllDefinedDataPointsException

Fit the Model to a set of data points minimizing the global transfer error. This is assumed to be implemented as a weighted least squares minimization.

This is a lower level version of fit(Collection) for optimal memory efficiency.

The estimated model transfers p to q.

n-dimensional points are passed as an n-dimensional array of doubles, e.g. four 2d points as:

 double[][]{
   {x1, x2, x3, x4},
   {y1, y2, y3, y4} }
 

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

<P extends PointMatch> void fit(Collection<P> matches)
                         throws NotEnoughDataPointsException,
                                IllDefinedDataPointsException

Fit the Model to a set of data points minimizing the global transfer error. This is assumed to be implemented as a weighted least squares minimization. Use ransac and/ or filter(java.util.Collection<P>, java.util.Collection<P>, double, int) to remove outliers from your data points.

The estimated model transfers match.p1.local to match.p2.world.

Parameters:

matches - set of point correpondences

Throws:

NotEnoughDataPointsException - if matches does not contain enough data points

IllDefinedDataPointsException - if the set of data points is inappropriate to solve the Model

test

<P extends PointMatch> boolean test(Collection<P> candidates,
                                    Collection<P> inliers,
                                    double epsilon,
                                    double minInlierRatio,
                                    int minNumInliers)

Test the Model 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|.

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

<P extends PointMatch> boolean test(Collection<P> candidates,
                                    Collection<P> inliers,
                                    double epsilon,
                                    double minInlierRatio)

Call test(Collection, Collection, double, double, int) with minNumInliers = getMinNumMatches().

filter

<P extends PointMatch> boolean filter(Collection<P> candidates,
                                      Collection<P> inliers,
                                      double maxTrust,
                                      int minNumInliers)
                               throws NotEnoughDataPointsException

Estimate the 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.util.List<P>, java.util.Collection<P>, int, double, double, int, double).

Sets cost to the average point transfer error.

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 Model could be estimated and inliers is not empty, false otherwise. If false, Model remains unchanged.

Throws:

NotEnoughDataPointsException

filter

<P extends PointMatch> boolean filter(Collection<P> candidates,
                                      Collection<P> inliers,
                                      double maxTrust)
                               throws NotEnoughDataPointsException

Call filter(Collection, Collection, double, int) with minNumInliers = getMinNumMatches().

Throws:

NotEnoughDataPointsException

filter

<P extends PointMatch> boolean filter(Collection<P> candidates,
                                      Collection<P> inliers)
                               throws NotEnoughDataPointsException

Call filter(Collection, Collection, double) with maxTrust = 4 and minNumInliers = getMinNumMatches().

Throws:

NotEnoughDataPointsException

ransac

<P extends PointMatch> boolean ransac(List<P> candidates,
                                      Collection<P> inliers,
                                      int iterations,
                                      double epsilon,
                                      double minInlierRatio,
                                      int minNumInliers)
                               throws NotEnoughDataPointsException

Find the Model of a set of PointMatch candidates containing a high number of outliers using RANSAC \citet[{FischlerB81}.

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 Model could be estimated and inliers is not empty, false otherwise. If false, Model remains unchanged.

Throws:

NotEnoughDataPointsException

ransac

<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 = getMinNumMatches().

Throws:

NotEnoughDataPointsException

filterRansac

<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 Model from a set with many outliers by first filtering the worst outliers with RANSAC \citet[{FischlerB81} and filter potential outliers by robust iterative regression.

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 Model could be estimated and inliers is not empty, false otherwise. If false, Model remains unchanged.

Throws:

NotEnoughDataPointsException

filterRansac

<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.

Throws:

NotEnoughDataPointsException

filterRansac

<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 = getMinNumMatches().

Throws:

NotEnoughDataPointsException

filterRansac

<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.

Throws:

NotEnoughDataPointsException

localSmoothnessFilter

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

Filter a Collection of PointMatches by the smoothness of their support for the given Model. Smoothness means that each PointMatch agrees with a locally weighted least squares fit of this Model up to a given maximal transfer error or up to a given multiply of the local mean transfer error. Locally weighted means that all PointMatches contribute to the fit weighted by their Euclidean distance to the candidate.

Parameters:

candidates -

inliers -

sigma -

maxEpsilon -

maxTrust -

Returns:

Throws:

NotEnoughDataPointsException

IllDefinedDataPointsException

icp

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
 

Parameters:

p - source

q - target

Returns:

the list of matches TODO Test---at least once!

set

void set(M m)

Set the model to m

Parameters:

m -

copy

M copy()

Clone the model.