closest_point_transformclosest_point_transformClosestPointTransformClosestPointTransform (Operator)


closest_point_transformclosest_point_transformClosestPointTransformClosestPointTransform — Compute the closest-point transformation of a region.


closest_point_transform(Region : Distances, ClosestPoints : Metric, Foreground, ClosestPointMode, Width, Height : )

Herror closest_point_transform(const Hobject Region, Hobject* Distances, Hobject* ClosestPoints, const char* Metric, const char* Foreground, const char* ClosestPointMode, const Hlong Width, const Hlong Height)

Herror T_closest_point_transform(const Hobject Region, Hobject* Distances, Hobject* ClosestPoints, const Htuple Metric, const Htuple Foreground, const Htuple ClosestPointMode, const Htuple Width, const Htuple Height)

void ClosestPointTransform(const HObject& Region, HObject* Distances, HObject* ClosestPoints, const HTuple& Metric, const HTuple& Foreground, const HTuple& ClosestPointMode, const HTuple& Width, const HTuple& Height)

HImage HRegion::ClosestPointTransform(HImage* ClosestPoints, const HString& Metric, const HString& Foreground, const HString& ClosestPointMode, Hlong Width, Hlong Height) const

HImage HRegion::ClosestPointTransform(HImage* ClosestPoints, const char* Metric, const char* Foreground, const char* ClosestPointMode, Hlong Width, Hlong Height) const

HImage HRegion::ClosestPointTransform(HImage* ClosestPoints, const wchar_t* Metric, const wchar_t* Foreground, const wchar_t* ClosestPointMode, Hlong Width, Hlong Height) const   (Windows only)

static void HOperatorSet.ClosestPointTransform(HObject region, out HObject distances, out HObject closestPoints, HTuple metric, HTuple foreground, HTuple closestPointMode, HTuple width, HTuple height)

HImage HRegion.ClosestPointTransform(out HImage closestPoints, string metric, string foreground, string closestPointMode, int width, int height)


closest_point_transformclosest_point_transformClosestPointTransformClosestPointTransformClosestPointTransform computes for every pixel of the input region RegionRegionRegionRegionregion (or its complement, respectively) the distance to the closest pixel outside the region (i.e., to the pixel on the outside border of the region) and returns this information in DistancesDistancesDistancesDistancesdistances. In addition to the distance, the corresponding closest pixel is returned in ClosestPointsClosestPointsClosestPointsClosestPointsclosestPoints.

The parameter ForegroundForegroundForegroundForegroundforeground determines whether the distances are calculated for all points within the region (ForegroundForegroundForegroundForegroundforeground = 'true'"true""true""true""true") or for all points outside the region (ForegroundForegroundForegroundForegroundforeground = 'false'"false""false""false""false"). The distance is computed for every pixel of the output images DistancesDistancesDistancesDistancesdistances and ClosestPointsClosestPointsClosestPointsClosestPointsclosestPoints. The size of the images is specified by WidthWidthWidthWidthwidth and HeightHeightHeightHeightheight. The input region is always clipped to the extent of the output image. If it is important that the distances within the entire region should be computed, the region should be moved (see move_regionmove_regionMoveRegionMoveRegionMoveRegion) so that it has only positive coordinates and the width and height of the output image should be large enough to contain the region. The extent of the input region can be obtained with smallest_rectangle1smallest_rectangle1SmallestRectangle1SmallestRectangle1SmallestRectangle1.

The parameter MetricMetricMetricMetricmetric determines which metric is used for the calculation of the distances. If MetricMetricMetricMetricmetric = 'city-block'"city-block""city-block""city-block""city-block", the distance is calculated from the shortest path from the point to the border of the region, where only horizontal and vertical “movements” are allowed. They are weighted with a weight of 1. If MetricMetricMetricMetricmetric = 'chessboard'"chessboard""chessboard""chessboard""chessboard", the distance is calculated from the shortest path to the border, where horizontal, vertical, and diagonal “movements” are allowed. They are weighted with a weight of 1. If MetricMetricMetricMetricmetric = 'octagonal'"octagonal""octagonal""octagonal""octagonal", a combination of these approaches is used, which leads to diagonal paths receiving a higher weight. If MetricMetricMetricMetricmetric = 'chamfer-3-4'"chamfer-3-4""chamfer-3-4""chamfer-3-4""chamfer-3-4", horizontal and vertical movements are weighted with a weight of 3, while diagonal movements are weighted with a weight of 4. To normalize the distances, the resulting distance image is divided by 3. Since this normalization step takes some time, and one usually is interested in the relative distances of the points, the normalization can be suppressed with MetricMetricMetricMetricmetric = 'chamfer-3-4-unnormalized'"chamfer-3-4-unnormalized""chamfer-3-4-unnormalized""chamfer-3-4-unnormalized""chamfer-3-4-unnormalized". Finally, if MetricMetricMetricMetricmetric = 'euclidean'"euclidean""euclidean""euclidean""euclidean", the computed distance is approximately Euclidean.

The parameter ClosestPointModeClosestPointModeClosestPointModeClosestPointModeclosestPointMode determines how the closest points are stored. For ClosestPointModeClosestPointModeClosestPointModeClosestPointModeclosestPointMode = 'absolute'"absolute""absolute""absolute""absolute", absolute coordinates are stored in ClosestPointsClosestPointsClosestPointsClosestPointsclosestPoints. For ClosestPointModeClosestPointModeClosestPointModeClosestPointModeclosestPointMode = 'relative'"relative""relative""relative""relative", the offset to the coordinate of the respective pixel is stored in ClosestPointsClosestPointsClosestPointsClosestPointsclosestPoints.


It should be noted that the closest points are usually not unique, i.e., for each pixel in the image DistancesDistancesDistancesDistancesdistances, there usually exist several points on the outer border of the region that have the respective distance to that pixel. For example, all points on the skeleton of the region in the chosen metric have the same distance to at least two distinct points on the outer border of the region. closest_point_transformclosest_point_transformClosestPointTransformClosestPointTransformClosestPointTransform returns one of these points that is determined by the implementation of the algorithm. In particular, invariances with respect to rotation or mirroring of the region should not be expected.

Furthermore, it should be noted that for ForegroundForegroundForegroundForegroundforeground = 'true'"true""true""true""true", point coordinates that lie outside the image defined by WidthWidthWidthWidthwidth and HeightHeightHeightHeightheight are returned if the input region RegionRegionRegionRegionregion touches the border of this image, since in this case the outside border of the region lies one pixel outside of the image. If the returned coordinates should be used for a direct access to an image, a suitable border treatment must be implemented.

Execution Information


RegionRegionRegionRegionregion (input_object)  region(-array) objectHRegionHRegionHobject

Region for which the distance to the border is computed.

DistancesDistancesDistancesDistancesdistances (output_object)  image objectHImageHImageHobject * (int4)

Image containing the distance information.

ClosestPointsClosestPointsClosestPointsClosestPointsclosestPoints (output_object)  image objectHImageHImageHobject * (vector_field)

Image containing the coordinates of the closest points.

MetricMetricMetricMetricmetric (input_control)  string HTupleHTupleHtuple (string) (string) (HString) (char*)

Type of metric to be used for the closest-point transformation.

Default value: 'city-block' "city-block" "city-block" "city-block" "city-block"

List of values: 'chamfer-3-4'"chamfer-3-4""chamfer-3-4""chamfer-3-4""chamfer-3-4", 'chamfer-3-4-unnormalized'"chamfer-3-4-unnormalized""chamfer-3-4-unnormalized""chamfer-3-4-unnormalized""chamfer-3-4-unnormalized", 'chessboard'"chessboard""chessboard""chessboard""chessboard", 'city-block'"city-block""city-block""city-block""city-block", 'euclidean'"euclidean""euclidean""euclidean""euclidean", 'octagonal'"octagonal""octagonal""octagonal""octagonal"

ForegroundForegroundForegroundForegroundforeground (input_control)  string HTupleHTupleHtuple (string) (string) (HString) (char*)

Compute the distance for pixels inside ('true'"true""true""true""true") or outside ('false'"false""false""false""false") the input region.

Default value: 'true' "true" "true" "true" "true"

List of values: 'false'"false""false""false""false", 'true'"true""true""true""true"

ClosestPointModeClosestPointModeClosestPointModeClosestPointModeclosestPointMode (input_control)  string HTupleHTupleHtuple (string) (string) (HString) (char*)

Mode in which the coordinates of the closest points are returned.

Default value: 'absolute' "absolute" "absolute" "absolute" "absolute"

List of values: 'absolute'"absolute""absolute""absolute""absolute", 'relative'"relative""relative""relative""relative"

WidthWidthWidthWidthwidth (input_control)  extent.x HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Width of the output images.

Default value: 640

Suggested values: 160, 192, 320, 384, 640, 768

Typical range of values: 1 ≤ Width Width Width Width width

HeightHeightHeightHeightheight (input_control)  extent.y HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Height of the output images.

Default value: 480

Suggested values: 120, 144, 240, 288, 480, 576

Typical range of values: 1 ≤ Height Height Height Height height


The runtime complexity is O(WidthWidthWidthWidthwidth*HeightHeightHeightHeightheight).


closest_point_transformclosest_point_transformClosestPointTransformClosestPointTransformClosestPointTransform returns 2 (H_MSG_TRUE) if all parameters are correct.

Possible Predecessors

thresholdthresholdThresholdThresholdThreshold, dyn_thresholddyn_thresholdDynThresholdDynThresholdDynThreshold, regiongrowingregiongrowingRegiongrowingRegiongrowingRegiongrowing

Possible Successors

thresholdthresholdThresholdThresholdThreshold, vector_field_to_realvector_field_to_realVectorFieldToRealVectorFieldToRealVectorFieldToReal



See also



Y. Ge, C.R. Maurer, Jr., J.M. Fitzpatrick: “Surface-based 3-D image registration using the Iterative Closest Point algorithm with a closest point transform”; in: “Medical Imaging 1996: Image Processing”, M.H. Loew, K.M. Hanson, Editors, Proc. SPIE 2710, pages 358--367, 1996.
P. Soille: “Morphological Image Analysis, Principles and Applications”; Springer Verlag Berlin Heidelberg New York, 1999.
G. Borgefors: “Distance Transformations in Arbitrary Dimensions”; Computer Vision, Graphics, and Image Processing, Vol. 27, pages 321--345, 1984.
P.E. Danielsson: “Euclidean Distance Mapping”; Computer Graphics and Image Processing, Vol. 14, pages 227--248, 1980.