create_distance_transform_xldCreateDistanceTransformXldCreateDistanceTransformXldcreate_distance_transform_xldT_create_distance_transform_xld🔗

Short description🔗

create_distance_transform_xldCreateDistanceTransformXldCreateDistanceTransformXldcreate_distance_transform_xldT_create_distance_transform_xld — Create the XLD distance transform.

Signature🔗

create_distance_transform_xld( xld_cont Contour, string Mode, real MaxDistance, out xld_dist_trans DistanceTransformID )

Description🔗

create_distance_transform_xldCreateDistanceTransformXld creates the XLD distance transform of the reference contour Contourcontourcontour and returns the resulting handle in DistanceTransformIDdistanceTransformIDdistance_transform_id.

Once the XLD distance transform has been created, the operator apply_distance_transform_xldApplyDistanceTransformXld calculates pointwise distances from test contours to the reference contour Contourcontourcontour. More precisely, for each point of a test contour its minimal distance to the contours in Contourcontourcontour is calculated.

The parameter Modemodemode determines which distances apply_distance_transform_xldApplyDistanceTransformXld calculates: 'point_to_point'"point_to_point" calculates the minimum distance to the base points of the Contourcontourcontour. In contrast, 'point_to_segment'"point_to_segment" calculates the minimum distance to the contour segments in Contourcontourcontour (see the figure below).

The dashed lines illustrate the calculated distances starting from point 1 of the test contour on the left. The distance \(d_{1}\) corresponds to the 'point_to_point'"point_to_point" mode, whereas the distance \(d_{2}\) corresponds to the 'point_to_segment'"point_to_segment" mode. The gray area illustrates the area within MaxDistancemaxDistancemax_distance around the reference contour for which distances are calculated. The distance of point 2 of the test contour would be set to MaxDistancemaxDistancemax_distance because it is outside of this area.

The parameter MaxDistancemaxDistancemax_distance specifies a maximum distance from the reference contour Contourcontourcontour which is of interest to the caller. If the distance from a point of a test contour to the reference contour exceeds MaxDistancemaxDistancemax_distance, the output distance of apply_distance_transform_xldApplyDistanceTransformXld is set to MaxDistancemaxDistancemax_distance.

The operators create_distance_transform_xldCreateDistanceTransformXld and apply_distance_transform_xldApplyDistanceTransformXld are an alternative to distance_contours_xldDistanceContoursXld, if the reference contour is repeatedly used. create_distance_transform_xldCreateDistanceTransformXld stores for each pixel in a relevant area around Contourcontourcontour its nearest points or segments (depending on Modemodemode) of the reference contour Contourcontourcontour. This allows apply_distance_transform_xldApplyDistanceTransformXld to calculate the distances rather fast, nearly independent of the number of points or segments of the reference contour, the Modemodemode and the position of the points of the test contour. However, the preparation of the XLD distance transform can take several seconds or minutes, depending on the number of points or segments of the reference contour and the relevant area around Contourcontourcontour which can be influenced by MaxDistancemaxDistancemax_distance. Furthermore, create_distance_transform_xldCreateDistanceTransformXld is faster, if Modemodemode is set to ‘point_to_point’.

get_distance_transform_xld_contourGetDistanceTransformXldContour and get_distance_transform_xld_paramGetDistanceTransformXldParam can be used to get back the reference contours and the parameters of the XLD distance transform DistanceTransformIDdistanceTransformIDdistance_transform_id.

Execution information🔗

Execution information

Multithreading type: reentrant (runs in parallel with non-exclusive operators).
Multithreading scope: global (may be called from any thread).
Processed without parallelization.

This operator returns a handle. Note that the state of an instance of this handle type may be changed by specific operators even though the handle is used as an input parameter by those operators.

Parameters🔗

Contourcontourcontour (input_object) xld_cont(-array) → objectHObjectHXLDContHObjectHobject

Reference contour(s).

Modemodemode (input_control) string → (string)HTuple (HString)HTuple (string)strHtuple (char*)

Compute the distance to points (‘point_to_point’) or entire segments (‘point_to_segment’).

Default: 'point_to_point'"point_to_point"
List of values: 'point_to_point', 'point_to_segment'"point_to_point", "point_to_segment"

MaxDistancemaxDistancemax_distance (input_control) real → (real / integer)HTuple (double / Hlong)HTuple (double / int / long)Union[int, float]Htuple (double / Hlong)

Maximum distance of interest.

Default: 20.020.0

DistanceTransformIDdistanceTransformIDdistance_transform_id (output_control) xld_dist_trans → (handle)HTuple (HHandle)HXLDDistTrans, HTuple (IntPtr)HHandleHtuple (handle)

Handle of the XLD distance transform.

Result🔗

If all parameters are correct, the operator returns the value 2 (H_MSG_TRUE). Otherwise, an exception is raised.

Combinations with other operators🔗

Combinations

Possible successors

apply_distance_transform_xldApplyDistanceTransformXld, write_distance_transform_xldWriteDistanceTransformXld, serialize_distance_transform_xldSerializeDistanceTransformXld, clear_distance_transform_xldClearDistanceTransformXld

Module🔗

Foundation