Skip to content

About image data🔗

HALCON images are composed of one or multiple channels, each consisting of a pixel matrix of the same dimensions and pixel type. Each channel refers to a memory buffer depending on height, width, and the pixel type of the image. There is also a domain associated with each image, defining the region of the image where valid pixel values are assumed.

In general, HALCON only creates a new image when pixel data or image size are modified. In this case, memory is allocated from the OS or reused from the HALCON image cache.
Operators, such as compose3 or copy_obj, do not modify pixel data and HALCON will not allocate new memory or write any pixel data to improve performance.

In HALCON, several images can share the same gray value matrix. This is also true for any domain (for example, reduce_domain) or channel operators (for example, access_channel), where the actual image data remains untouched. reduce_domain, for example, creates a new HALCON image that references a different domain but the same gray value matrices.
To reduce the size of the image, use the crop_domain, crop_domain_rel, crop_part, or crop_rectangle1 operator.
To enforce a deep copy, use the copy_image operator.
In the C++ and .NET language interfaces, an additional Clone method for HALCON classes is available, which also performs a deep copy.

When a filter, cropping, or other transformations that modify pixel data or image size are applied, HALCON creates a new image.
With only a few exceptions (for example, set_grayval, overpaint_gray, and overpaint_region), in-place operations are not supported, even if the input and output variables share the same name.

Note

In-place operations are not always possible or reasonable to implement. For typical filters, for example, if the first (filtered) pixel is calculated and written into the original image, the original value of the first pixel would no longer available for the calculation of neighboring pixels. Complications like this would likely render the in-place operation slower.
Since new pixel data has to be written anyway and HALCON’s caching minimizes memory requests to the operating system, the advantage in terms of memory consumption would be small.

Internally, the HALCON library uses reference counters to keep track of the number of images that reference the same gray value matrix. Once the reference counter drops to zero, the memory used by the corresponding gray value matrix is automatically freed (and added to the image cache per default).

Read and filter an image

When reading image data from disk, new memory is allocated for the gray value matrix. The image Image points to this memory location and the reference counter is set to 1. The memory address can be queried via get_image_pointer1:

read_image (Image, 'fabrik')
get_image_pointer1 (Image, Pointer1, Type, Width, Height)

When a filter operation such as mean_image is applied, HALCON allocates new memory and writes the filtered image data to this new address. If the same variable is used for input and output, then the old image in it is replaced with the new image that points to the new address with an initial reference count of 1.
This can be checked with another call of get_image_pointer1. The reference counter of the old memory location drops to 0 and the destructor is called, freeing the old image memory:

mean_image (Image, Image, 3, 3)
get_image_pointer1 (Image, Pointer2, Type, Width, Height)

compose3 and overpaint_region or set_grayval

compose3 does not perform a deep copy of the image data. When used in the following way, the three channels of MultiChannelImage will therefore point to the same gray value matrix:

read_image (GrayImage, 'fabrik')
compose3 (GrayImage, GrayImage, GrayImage, MultiChannelImage)

If this is combined with one of the in-place operators, the result may be unexpected. In this case, overpaint_region first paints the first color into the gray value matrix, then the second color and lastly the third color (of the specified RGB values). Since all three channels refer to the same gray value matrix, only the last gray value (255) is seen in MultiChannelImage:

gen_rectangle1 (ROI_0, 100, 200, 200, 400)
overpaint_region (MultiChannelImage, ROI_0, [0,100,255], 'fill')

To have three independent channels in MultiChannelImage, copy_image can be used to produce deep copies:

read_image (GrayImage, 'fabrik')
copy_image (GrayImage, Red)
copy_image (GrayImage, Green)
copy_image (GrayImage, Blue)
compose3 (Red, Green, Blue, MultiChannelImage)
gen_rectangle1 (ROI_0, 100, 200, 200, 400)
overpaint_region (MultiChannelImage, ROI_0, [0,100,255], 'fill')