HALCON Reference Manual 10.0.2

Name

map_imagemap_imagemap_imageMapImageMapImage — Apply a general transformation to an image.

Signature

map_image(Image, Map : ImageMapped : : )

Description

map_imagemap_imagemap_imageMapImageMapImage transforms an image ImageImageImageImageimage using an arbitrary transformation MapMapMapMapmap which, for example, was previously generated using gen_image_to_world_plane_mapgen_image_to_world_plane_mapgen_image_to_world_plane_mapGenImageToWorldPlaneMapGenImageToWorldPlaneMap or gen_radial_distortion_mapgen_radial_distortion_mapgen_radial_distortion_mapGenRadialDistortionMapGenRadialDistortionMap. The multi-channel image MapMapMapMapmap must be organized as follows:

The height and the width of MapMapMapMapmap define the size of the output image ImageMappedImageMappedImageMappedImageMappedimageMapped. The number of channels in MapMapMapMapmap defines whether no interpolation or bilinear interpolation should be used. If MapMapMapMapmap 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 ImageMappedImageMappedImageMappedImageMappedimageMapped the linearized coordinate of the pixel in the input image ImageImageImageImageimage from which the gray value should be taken is stored.

If bilinear interpolation between the pixels in the input image should be applied, MapMapMapMapmap 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 ImageMappedImageMappedImageMappedImageMappedimageMapped should not differ from the overall brighntess of the input image ImageImageImageImageimage, 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 ImageMappedImageMappedImageMappedImageMappedimageMapped 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.

It is also possible to use a MapMapMapMapmap that consists of a vector field containing absolute subpixel precise row and column coordinates. The two MapMapMapMapmap types described above can be converted into this type using convert_map_typeconvert_map_typeconvert_map_typeConvertMapTypeConvertMapType. This type is the only type supported on compute devices!

Attention

The weights must be choosen in a way that the range of values of the output image ImageMappedImageMappedImageMappedImageMappedimageMapped 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 MapMapMapMapmap, lie inside the input image. Thus, it must be ensured by the user that this constraint is fulfilled. Otherwise, the program may crash!

map_imagemap_imagemap_imageMapImageMapImage is parallelized automatically if and only if MapMapMapMapmap uses bilinear interpolation. map_imagemap_imagemap_imageMapImageMapImage is executed on an OpenCL compute device only if the input map is of type 'coord_map_sub_pix' and if the input image does not exceed the maximum size of image objects of the selected device.