find_scaled_shape

Herror ::find_scaled_shape_model ( Hobject Image, const HTuple &ModelID, const HTuple &AngleStart, const HTuple &AngleExtent, const HTuple &ScaleMin, const HTuple &ScaleMax, const HTuple &MinScore, const HTuple &NumMatches, const HTuple &MaxOverlap, const HTuple &SubPixel, const HTuple &NumLevels, const HTuple &Greediness, HTuple *Row, HTuple *Column, HTuple *Angle, HTuple *Scale, HTuple *Score ) HTuple HImage::FindScaledShapeModel ( const HTuple &ModelID, const HTuple &AngleStart, const HTuple &AngleExtent, const HTuple &ScaleMin, const HTuple &ScaleMax, const HTuple &MinScore, const HTuple &NumMatches, const HTuple &MaxOverlap, const HTuple &SubPixel, const HTuple &NumLevels, const HTuple &Greediness, HTuple *Column, HTuple *Angle, HTuple *Scale, HTuple *Score ) const

Find the best matches of a scale invariant shape model in an image.

The operator find_scaled_shape_model finds the best NumMatches instances of the scale invariant shape model ModelID in the input image Image. The model must have been created previously by calling create_scaled_shape_model or read_scaled_shape_model.

The position, rotation, and scale of the found instances of the model are returned in Row, Column, Angle, and Scale. Additionally, the score of each found instance is returned in Score. The score is a number between 0 and 1, which is an approximate measure of how much of the model is visible in the image. If, for example, half of the model is occluded, the score cannot exceed 0.5.

The model is searched within those points of the domain of the image, in which the model lies completely within the image. This means that the model will not be found if it extends beyond the borders of the image, even if it would achieve a score greater than MinScore (see below). The parameters AngleStart and AngleExtent determine the range of rotations for which the model is searched. The parameters ScaleMin and ScaleMax determine the range of scales for which the model is searched. If necessary, both ranges are clipped to the range given when the model was created with create_scaled_shape_model.

The parameter MinScore determines what score a potential match must at least have to be regarded as an instance of the model in the image. The larger MinScore is chosen, the faster the search is. If the model can be expected never to be occluded in the images, MinScore may be set as high as 0.8 or even 0.9.

The maximum number of instances to be found can be determined with NumMatches. If more than NumMatches instances with a score greater than MinScore are found in the image, only the best NumMatches instances are returned. If fewer than NumMatches are found, only that number is returned, i.e., the parameter MinScore takes precedence over NumMatches.

If the model exhibits symmetries it may happen that multiple instances with similar positions but different rotations are found in the image. The parameter MaxOverlap determines by what fraction (i.e., a number between 0 and 1) two instances may at most overlap in order to consider them as different instances, and hence to be returned separately. If two instances overlap each other by more than MaxOverlap only the best instance is returned. The calculation of the overlap is based on the smallest enclosing rectangle of arbitrary orientation (see smallest_rectangle2) of the found instances. If MaxOverlap=0, the found instances may not overlap at all, while for MaxOverlap=1 all instances are returned.

The parameter SubPixel determines whether the instances should be extracted with subpixel accuracy. If SubPixel is set to 'true', the position as well as the rotation and scale are determined with subpixel accuracy.

The number of pyramid levels used during the search is determined with NumLevels. If necessary, the number of levels is clipped to the range given when the shape model was created with create_scaled_shape_model. If NumLevels is set to 0, the number of pyramid levels specified in create_scaled_shape_model is used.

The parameter Greediness determines how ``greedily'' the search should be carried out. If Greediness=0, a safe search heuristic is used, which always finds the model if it is visible in the image. However, the search will be relatively time consuming in this case. If Greediness=1, an unsafe search heuristic is used, which may cause the model not to be found in rare cases, even though it is visible in the image. For Greediness=1, the maximum search speed is achieved. In almost all cases, the shape model will always be found for Greediness=0.9.

Parameters

`Image` (input_object)	image `->` Hobject: HImage ( byte )
Input image in which the model should be found.

`ModelID` (input_control)	shape_model `->` HTuple.long
Handle of the model.

`AngleStart` (input_control)	angle.rad `->` HTuple.double
Smallest rotation of the model.
Default value: -0.39
Suggested values: -3.14, -1.57, -0.78, -0.39, -0.20, 0.0

`AngleExtent` (input_control)	angle.rad `->` HTuple.double
Extent of the rotation angles.
Default value: 0.78
Suggested values: 6.28, 3.14, 1.57, 0.78, 0.39, 0.0
Restriction: `AngleExtent >= 0`

`ScaleMin` (input_control)	number `->` HTuple.double
Minimum scale of the pattern.
Default value: 0.9
Suggested values: 0.5, 0.6, 0.7, 0.8, 0.9, 1.0
Restriction: `ScaleMin > 0`

`ScaleMax` (input_control)	number `->` HTuple.double
Maximum scale of the pattern.
Default value: 1.1
Suggested values: 1.0, 1.1, 1.2, 1.3, 1.4, 1.5
Restriction: `ScaleMax >= ScaleMin`

`MinScore` (input_control)	real `->` HTuple.double
Minumum score of the instances of the model to be found.
Default value: 0.5
Suggested values: 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0
Typical range of values: `0 <= MinScore <= 1`
Minimum increment: 0.01
Recommended increment: 0.05

`NumMatches` (input_control)	integer `->` HTuple.long
Number of instances of the model to be found.
Default value: 1
Suggested values: 0, 1, 2, 3, 4, 5, 10, 20

`MaxOverlap` (input_control)	real `->` HTuple.double
Maximum overlap of the instances of the model to be found.
Default value: 0.5
Suggested values: 0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0
Typical range of values: `0 <= MaxOverlap <= 1`
Minimum increment: 0.01
Recommended increment: 0.05

`SubPixel` (input_control)	string `->` HTuple.const char *
Subpixel accuracy if 'true'.
Default value: 'false'
List of values: 'true', 'false'

`NumLevels` (input_control)	integer `->` HTuple.long
Number of pyramid levels used in the matching.
Default value: 0
List of values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10

`Greediness` (input_control)	real `->` HTuple.double
``Greediness'' of the search heuristic (0: safe but slow; 1: fast but matches may be missed).
Default value: 0.9
Suggested values: 0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0
Typical range of values: `0 <= Greediness <= 1`
Minimum increment: 0.01
Recommended increment: 0.05

`Row` (output_control)	point.y-array `->` HTuple.double *
Row coordinate of the found instances of the model.

`Column` (output_control)	point.x-array `->` HTuple.double *
Column coordinate of the found instances of the model.

`Angle` (output_control)	angle.rad-array `->` HTuple.double *
Rotation angle of the found instances of the model.

`Scale` (output_control)	number-array `->` HTuple.double *
Scale of the found instances of the model.

`Score` (output_control)	real-array `->` HTuple.double *
Score of the found instances of the model.

Result

If the parameter values are correct, the operator find_scaled_shape_model returns the value H_MSG_TRUE. If the input is empty (no input images are available) the behaviour can be set via set_system('no_object_result',<Result>). If necessary, an exception handling is raised.

Parallelization Information

find_scaled_shape_model is reentrant and processed without parallelization.

Possible Predecessors

create_scaled_shape_model, read_scaled_shape_model

Alternatives

find_shape_model, best_match_rot_mg

Module

Template matching