Model (Fiji Javadocs 0-SNAPSHOT API)

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

Model()

Constructors
Constructor and Description
`Model()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and 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 <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.
`double`	`getCost()`
`double`	`getError()` Deprecated. The term Error may be missleading---use `getCost()` instead
`abstract int`	`getMinSetSize()`
`static <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.
`void`	`setCost(double c)`
`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 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 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
  - Model
```
public Model()
```
- Method Detail
  - 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

Class Model

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface stitching.model.CoordinateTransform

Field Detail

rnd

cost

Constructor Detail

Model

Method Detail

getMinSetSize

getCost

setCost

getError

setError

betterThan

shake

fit

test

filter

ransac

filterRansac

toString

clone