Skip to content

map_imageMapImageMapImagemap_imagemap_image🔗

Short description🔗

map_imageMapImageMapImagemap_imagemap_image — Apply a general transformation to an image.

Signature🔗

map_image( image Image, image Map, out image ImageMapped )void MapImage( const HObject& Image, const HObject& Map, HObject* ImageMapped )static void HOperatorSet.MapImage( HObject image, HObject map, out HObject imageMapped )def map_image( image: HObject, map: HObject ) -> HObject

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

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

HImage HImage::MapImage( const HImage& Map ) const

HImage HImage.MapImage( HImage map )

Description🔗

map_imageMapImage transforms an image Imageimageimage using an arbitrary transformation Mapmapmap which, for example, was previously generated using gen_image_to_world_plane_mapGenImageToWorldPlaneMap or gen_radial_distortion_mapGenRadialDistortionMap. The multi-channel image Mapmapmap must be organized as follows:

The height and the width of Mapmapmap define the size of the output image ImageMappedimageMappedimage_mapped. The number of channels in Mapmapmap defines whether no interpolation or bilinear interpolation should be used. If Mapmapmap only consists of one channel, no interpolation is applied during the transformation. This channel contains ‘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 ImageMappedimageMappedimage_mapped the linearized coordinate of the pixel in the input image Imageimageimage from which the gray value should be taken is stored.

If bilinear interpolation between the pixels in the input image should be applied, Mapmapmap 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 ImageMappedimageMappedimage_mapped should not differ from the overall brightness of the input image Imageimageimage, 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 to 65535.

Furthermore, the weights must be chosen in a way that the range of values of the output image ImageMappedimageMappedimage_mapped 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 Mapmapmap that consists of a vector field containing absolute subpixel precise row and column coordinates (i.e., the field must be of the semantic type ‘vector_field_absolute’). The two Mapmapmap types described above can be converted into this type using convert_map_typeConvertMapType. This type is the only type supported on compute devices!

Attention🔗

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

For runtime reasons during the mapping process, it is not checked whether the linearized coordinates lie inside the input image. Thus, it must be ensured by the user that this constraint is fulfilled. In case interpolation is used, this also applies to the pixels to the right, below, and below to the right of this coordinate. Otherwise, the program may crash!

map_imageMapImage is parallelized automatically if and only if the specified type for Mapmapmap is either 'bilinear'"bilinear" or 'coord_map_sub_pix'"coord_map_sub_pix".

map_imageMapImage is executed on an OpenCL compute device only if the input map is of type 'coord_map_sub_pix'"coord_map_sub_pix" and if the input image does not exceed the maximum size of image objects of the selected device.

Execution information🔗

Execution information

  • Supports OpenCL compute devices.

  • Multithreading type: reentrant (runs in parallel with non-exclusive operators).

  • Multithreading scope: global (may be called from any thread).

  • Automatically parallelized on internal data level.

Parameters🔗

Imageimageimage (input_object) (multichannel-)image(-array) → object (byte / uint2 / real)HObject (byte / uint2 / real)HImage (byte / uint2 / real)HObject (byte / uint2 / real)Hobject (byte / uint2 / real)

Image to be mapped.

Mapmapmap (input_object) (multichannel-)image → object (int4 / int8 / uint2 / vector_field*)HObject (int4 / int8 / uint2 / vector_field*)HImage (int4 / int8 / uint2 / vector_field*)HObject (int4 / int8 / uint2 / vector_field*)Hobject (int4 / int8 / uint2 / vector_field*) *allowed for compute devices

Image containing the mapping data.

ImageMappedimageMappedimage_mapped (output_object) (multichannel-)image(-array) → object (byte / uint2 / real)HObject (byte / uint2 / real)HImage (byte / uint2 / real)HObject (byte / uint2 / real)Hobject * (byte / uint2 / real)

Mapped image.

Result🔗

map_imageMapImage returns 2 (H_MSG_TRUE) if all parameter values are correct. If necessary, an exception is raised.

Combinations with other operators🔗

Combinations

Possible predecessors

gen_image_to_world_plane_mapGenImageToWorldPlaneMap, gen_radial_distortion_mapGenRadialDistortionMap, convert_map_typeConvertMapType

See also

affine_trans_imageAffineTransImage, rotate_imageRotateImage

Module🔗

Foundation