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

Method Summary
 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, float) with maxTrust = 4 and minNumInliers = getMinNumMatches().
<P extends PointMatch>
boolean
filter(Collection<P> candidates, Collection<P> inliers, double maxTrust)
          Call #filter(Collection, Collection, float, 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, float, float, float) 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, float, float, int, float) 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, float, float, int, float) 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()

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.cost is smaller than m.cost

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:
{@link - NotEnoughDataPointsException} if not enough data points were available IllDefinedDataPointsException if the set of data points is inappropriate to solve the Model
NotEnoughDataPointsException
IllDefinedDataPointsException

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:
{@link - NotEnoughDataPointsException} if not enough data points were available IllDefinedDataPointsException if the set of data points is inappropriate to solve the Model
NotEnoughDataPointsException
IllDefinedDataPointsException

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(Class, Collection, Collection) 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:
{@link - NotEnoughDataPointsException} if matches does not contain enough data points IllDefinedDataPointsException if the set of data points is inappropriate to solve the Model
NotEnoughDataPointsException
IllDefinedDataPointsException

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. 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, float, int) with minNumInliers = getMinNumMatches().

Throws:
NotEnoughDataPointsException

filter

<P extends PointMatch> boolean filter(Collection<P> candidates,
                                      Collection<P> inliers)
               throws NotEnoughDataPointsException
Call #filter(Collection, Collection, float) 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:
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 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:
modelClass - class of the model to be estimated
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, float, float, int, float) 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, float, float, int, float) 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, float, float, float) 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.



Copyright © 2007-2016 Fiji. All Rights Reserved.