SegmentMeanShiftSearch (feature 0.26 API)

java.lang.Object
- boofcv.alg.segmentation.ms.SegmentMeanShiftSearch<T>

Direct Known Subclasses:

SegmentMeanShiftSearchColor, SegmentMeanShiftSearchGray
```
public abstract class SegmentMeanShiftSearch<T extends boofcv.struct.image.ImageBase>
extends java.lang.Object
```
Performs the search step in mean-shift image segmentation [1]. The mode of a pixel is the point at which mean-shift converges when initialized at that pixel. Pixels which have the same mode belong to the same segment. The weight kernel G(|x-y|^2/h) has independent normalization factors h for spacial and color components. A precomputed Normal distribution is used for the weight kernel.

Output is provided in the form of an image where each pixel contains the index of a region the pixel belongs to. Three other lists provide color value of the region, number of pixels in the region and the location of the mean-shift peak for that region. This output is unlikely to be final processing step since it will over segment the image. Merging of similar modes and pruning of small regions is a common next step.

An approximation of running mean-shift on each pixel is performed if the 'fast' flag is set to true. The approximation is about 5x faster and works by saving the mean-shift trajectory [2]. All points along the trajectory are given the same mode. When performing mean-shift if a pixel is encountered which has already been assigned a mode the search stops. This approximation tends to produce more regions and reduces clustering quality in high texture regions.

NOTES:
- Spacial distance is normalized by dividing the found Euclidean distance squared by the maximum possible Euclidean distance squared, thus ensuring it will be between 0 and 1.
- Color distance is normalized by dividing it by the maximum allows Euclidean distance squared. If its distance is more than the maximum allowed value then G() will be zero.
- Image edges are handled by truncating the spacial kernel. This truncation will create an asymmetric kernel, but there is really no good way to handle image edges.
CITATIONS:
1. Comaniciu, Dorin, and Peter Meer. "Mean shift analysis and applications." Computer Vision, 1999. The Proceedings of the Seventh IEEE International Conference on. Vol. 2. IEEE, 1999.
2. Christoudias, Christopher M., Bogdan Georgescu, and Peter Meer. "Synergism in low level vision." Pattern Recognition, 2002. Proceedings. 16th International Conference on. Vol. 4. IEEE, 2002.

Field Summary

Fields
Modifier and Type	Field and Description
`protected float`	`convergenceTol`
`protected T`	`image`
`protected float`	`maxColorDistanceSq`
`protected int`	`maxIterations`
`protected org.ddogleg.struct.FastQueue<float[]>`	`modeColor`
`protected org.ddogleg.struct.FastQueue<georegression.struct.point.Point2D_I32>`	`modeLocation`
`protected org.ddogleg.struct.GrowQueue_I32`	`modeMemberCount`
`protected float`	`modeX`
`protected float`	`modeY`
`protected boofcv.struct.image.GrayS32`	`pixelToMode`
`protected boofcv.struct.image.GrayS32`	`quickMode`
`protected int`	`radiusX`
`protected int`	`radiusY`
`protected float[]`	`spacialTable`
`protected float[]`	`weightTable`
`protected int`	`widthX`
`protected int`	`widthY`

Constructor Summary

Constructors
Constructor and Description
`SegmentMeanShiftSearch(int maxIterations, float convergenceTol, int radiusX, int radiusY, float maxColorDistance, boolean fast)` Configures mean-shift segmentation

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`static float`	`distanceSq(float[] a, float[] b)` Returns the Euclidean distance squared between the two vectors
`abstract boofcv.struct.image.ImageType<T>`	`getImageType()`
`org.ddogleg.struct.FastQueue<float[]>`	`getModeColor()`
`org.ddogleg.struct.FastQueue<georegression.struct.point.Point2D_I32>`	`getModeLocation()` Location of each peak in the image
`boofcv.struct.image.GrayS32`	`getPixelToRegion()` From peak index to pixel index
`org.ddogleg.struct.GrowQueue_I32`	`getRegionMemberCount()` Number of pixels which each peak as a member
`abstract void`	`process(T image)` Performs mean-shift clustering on the input image
`protected float`	`weight(float distance)` Returns the weight given the normalized distance.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

maxIterations
```
protected int maxIterations
```

convergenceTol
```
protected float convergenceTol
```

radiusX
```
protected int radiusX
```

radiusY
```
protected int radiusY
```

widthX
```
protected int widthX
```

widthY
```
protected int widthY
```

maxColorDistanceSq
```
protected float maxColorDistanceSq
```

pixelToMode

protected boofcv.struct.image.GrayS32 pixelToMode

quickMode

protected boofcv.struct.image.GrayS32 quickMode

modeLocation

protected org.ddogleg.struct.FastQueue<georegression.struct.point.Point2D_I32> modeLocation

modeMemberCount

protected org.ddogleg.struct.GrowQueue_I32 modeMemberCount

modeColor

protected org.ddogleg.struct.FastQueue<float[]> modeColor

spacialTable
```
protected float[] spacialTable
```

weightTable
```
protected float[] weightTable
```

image

protected T extends boofcv.struct.image.ImageBase image

modeX
```
protected float modeX
```

modeY
```
protected float modeY
```

Constructor Detail
- SegmentMeanShiftSearch
```
public SegmentMeanShiftSearch(int maxIterations,
                              float convergenceTol,
                              int radiusX,
                              int radiusY,
                              float maxColorDistance,
                              boolean fast)
```
  Configures mean-shift segmentation
  
  Parameters:
  
  maxIterations - Maximum number of mean-shift iterations. Try 30
  
  convergenceTol - When the change is less than this amount stop. Try 0.005
  
  radiusX - Spacial kernel radius x-axis
  
  radiusY - Spacial kernel radius y-axis
  
  maxColorDistance - Maximum allowed Euclidean distance squared for the color component
  
  fast - Improve runtime by approximating running mean-shift on each pixel. Try true.

Method Detail
- process
```
public abstract void process(T image)
```
  Performs mean-shift clustering on the input image
  
  Parameters:
  
  image - Input image
- distanceSq
```
public static float distanceSq(float[] a,
                               float[] b)
```
  Returns the Euclidean distance squared between the two vectors
- weight
```
protected float weight(float distance)
```
  Returns the weight given the normalized distance. Instead of computing the kernel distance every time a lookup table with linear interpolation is used. The distance has a domain from 0 to 1, inclusive
  
  Parameters:
  
  distance - Normalized Euclidean distance squared. From 0 to 1.
  
  Returns:
  
  Weight.
- getPixelToRegion
```
public boofcv.struct.image.GrayS32 getPixelToRegion()
```
  From peak index to pixel index
- getModeLocation
```
public org.ddogleg.struct.FastQueue<georegression.struct.point.Point2D_I32> getModeLocation()
```
  Location of each peak in the image
- getRegionMemberCount
```
public org.ddogleg.struct.GrowQueue_I32 getRegionMemberCount()
```
  Number of pixels which each peak as a member
- getModeColor
```
public org.ddogleg.struct.FastQueue<float[]> getModeColor()
```
- getImageType
```
public abstract boofcv.struct.image.ImageType<T> getImageType()
```

Class SegmentMeanShiftSearch<T extends boofcv.struct.image.ImageBase>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

maxIterations

convergenceTol

radiusX

radiusY

widthX

widthY

maxColorDistanceSq

pixelToMode

quickMode

modeLocation

modeMemberCount

modeColor

spacialTable

weightTable

image

modeX

modeY

Constructor Detail

SegmentMeanShiftSearch

Method Detail

process

distanceSq

weight

getPixelToRegion

getModeLocation

getRegionMemberCount

getModeColor

getImageType