map_image (Operator)

Name

map_image — Apply a general transformation to an image.

Synopsis

Herror map_image(const Hobject Image, const Hobject Map, Hobject* ImageMapped)

Herror T_map_image(const Hobject Image, const Hobject Map, Hobject* ImageMapped)

Description

map_image transforms an image Image using an arbitrary transformation Map which, for example, was previously generated using gen_image_to_world_plane_map or gen_radial_distortion_map. The multi-channel image Map must be organized as follows:

The height and the width of Map define the size of the output image ImageMapped. The number of channels in Map defines whether no interpolation or bilinear interpolation should be used. If Map only consists of one channel, no interpolation is applied during the transformation. This channel containes 'int4' (resp. 'int8' in HALCON XL if the value range of 'int4' is not sufficient) values that describe the geometric transformation: For each pixel in the output image ImageMapped the linearized coordinate of the pixel in the input image Image from which the gray value should be taken is stored.

If bilinear interpolation between the pixels in the input image should be applied, Map must consist of 5 channels. The first channel again consists of an 'int4' resp. 'int8' image and describes the geometric transformation. The channels 2-5 consist of an 'uint2' image each and contain the weights [0...1] of the four neighboring pixels that are used during bilinear interpolation. If the overall brightness of the output image ImageMapped should not differ from the overall brighntess of the input image Image, the sum of the four unscaled weights must be 1 for each pixel. The weights [0...1] are scaled to the range of values of the 'uint2' image and therefore hold integer values from 0 bis 65535.

Furthermore, the weights must be chosen in a way that the range of values of the output image ImageMapped is not exceeded. The geometric relation between the four channels 2-5 is illustrated in the following sketch:

+---+---+
| 2 | 3 |
+---+---+
| 4 | 5 |
+---+---+

The reference point of the four pixels is the upper left pixel. The linearized coordinate of the reference point is stored in the first channel.

Attention

The weights must be choosen in a way that the range of values of the output image ImageMapped is not exceeded.

For runtime reasons during the mapping process, it is not checked whether the linearized coordinates which are stored in the first channel of Map, lie inside the input image. Thus, it must be ensured by the user that this constraint is fulfilled. Otherwise, the program may crash!

map_image is parallelized automatically if and only if Map uses bilinear interpolation.

Parameters

Image (input_object)	(multichannel-)image(-array) → Hobject (byte / uint2)
Image to be mapped.

Map (input_object)	(multichannel-)image → Hobject (int4 / int8 / uint2)
Image containing the mapping data.

ImageMapped (output_object)	(multichannel-)image(-array) → Hobject * (byte / uint2)
Mapped image.

Result

map_image returns H_MSG_TRUE if all parameter values are correct. If necessary, an exception is raised.

Parallelization Information

map_image is reentrant and automatically parallelized (on internal data level).

Possible Predecessors

gen_image_to_world_plane_map, gen_radial_distortion_map

See also

affine_trans_image, rotate_image

Module

Foundation