write_imagewrite_imageWriteImageWriteImagewrite_image (Operator)

Name

write_imagewrite_imageWriteImageWriteImagewrite_image — Write images in graphic formats.

Signature

write_image(Image : : Format, FillColor, FileName : )

Herror write_image(const Hobject Image, const char* Format, const Hlong FillColor, const char* FileName)

Herror T_write_image(const Hobject Image, const Htuple Format, const Htuple FillColor, const Htuple FileName)

void WriteImage(const HObject& Image, const HTuple& Format, const HTuple& FillColor, const HTuple& FileName)

void HImage::WriteImage(const HString& Format, const HTuple& FillColor, const HTuple& FileName) const

void HImage::WriteImage(const HString& Format, Hlong FillColor, const HString& FileName) const

void HImage::WriteImage(const char* Format, Hlong FillColor, const char* FileName) const

void HImage::WriteImage(const wchar_t* Format, Hlong FillColor, const wchar_t* FileName) const   (Windows only)

static void HOperatorSet.WriteImage(HObject image, HTuple format, HTuple fillColor, HTuple fileName)

void HImage.WriteImage(string format, HTuple fillColor, HTuple fileName)

void HImage.WriteImage(string format, int fillColor, string fileName)

def write_image(image: HObject, format: str, fill_color: Union[int, float], file_name: MaybeSequence[str]) -> None

Description

The operator write_imagewrite_imageWriteImageWriteImageWriteImagewrite_image saves the input image ImageImageImageImageimageimage in the file FileNameFileNameFileNameFileNamefileNamefile_name in the format FormatFormatFormatFormatformatformat. If the domain (region) cannot be saved in the specified FormatFormatFormatFormatformatformat (this is the case for 'bmp', 'jpeg', and 'ima'), all pixels outside the region receive the color defined by FillColorFillColorFillColorFillColorfillColorfill_color. For gray value images a value between 0 (black) and 255 (white) must be passed. For RGB color images the RGB values can be passed directly as a hexadecimal value: e.g., 0xffff00 for a yellow background (red=255, green=255, blue=0).

The following formats are currently supported:

'tiff', 'bigtiff': TIFF format, file extension *.tif

All HALCON pixel types are supported. Image object tuples with up to 65535 image objects and up to 65535 channels can be written. Image objects with channels of mixed pixel types can be written.

Compression is possible with

'deflate [num]'"deflate [num]""deflate [num]""deflate [num]""deflate [num]""deflate [num]": Adobe deflate compression (lossless)
'jpeg [num]'"jpeg [num]""jpeg [num]""jpeg [num]""jpeg [num]""jpeg [num]": JPEG (lossy)
'lzw'"lzw""lzw""lzw""lzw""lzw" LZW (lossless)
'packbits'"packbits""packbits""packbits""packbits""packbits" PackBits (lossless)

Here, '[num]'"[num]""[num]""[num]""[num]""[num]" denotes an optional specification of a compression parameter. For 'deflate'"deflate""deflate""deflate""deflate""deflate", a number between 0 (no compression) and 9 (maximum compression) can be specified. For 'jpeg'"jpeg""jpeg""jpeg""jpeg""jpeg", a number between 0 and 100 can be specified. The semantics are identical to the semantics of 'jpeg' described below. 'jpeg'"jpeg""jpeg""jpeg""jpeg""jpeg" can only be used for images of type byte and int1 with up to four channels.

The domain (region) of each image object can be saved in compressed form via 'mask'"mask""mask""mask""mask""mask" (default setting) or as an additional alpha channel via 'alpha'"alpha""alpha""alpha""alpha""alpha". The domain is only stored if it does not comprise the full image. 'jpeg'"jpeg""jpeg""jpeg""jpeg""jpeg" and 'alpha'"alpha""alpha""alpha""alpha""alpha" cannot be used together because owing to the lossy compression of JPEG the domain of the image cannot be reconstructed correctly. The different options can be accumulated by appending them separated by a space character.

Examples:
'tiff deflate 9'"tiff deflate 9""tiff deflate 9""tiff deflate 9""tiff deflate 9""tiff deflate 9": Adobe deflate compression,
the domain is stored as a mask image if necessary
'tiff jpeg 90'"tiff jpeg 90""tiff jpeg 90""tiff jpeg 90""tiff jpeg 90""tiff jpeg 90": JPEG compression with high quality,
the domain is stored as a mask image if necessary
'tiff lzw alpha'"tiff lzw alpha""tiff lzw alpha""tiff lzw alpha""tiff lzw alpha""tiff lzw alpha": LZW compression,
the domain is stored as an alpha channel if necessary
'tiff'"tiff""tiff""tiff""tiff""tiff" or 'tiff none'"tiff none""tiff none""tiff none""tiff none""tiff none": no compression,
the domain is stored as a mask image if necessary

Note that 'bigtiff'"bigtiff""bigtiff""bigtiff""bigtiff""bigtiff" denotes TIFF files that can be larger than 4 GB, while 'tiff'"tiff""tiff""tiff""tiff""tiff" denotes TIFF files that are limited to 4 GB. The file size depends on the image size and the selected compression. Therefore, 'bigtiff'"bigtiff""bigtiff""bigtiff""bigtiff""bigtiff" should be selected if there is a possibility that the compressed file will grow to more than 4 GB.

'bmp': Windows-BMP format, file extension *.bmp

This format can only store images with one channel (gray value image) or three channels (RGB image).

Only images with the pixel type byte are supported for this file format.

'jpeg': JPEG format (lossy compression), file extension *.jpg

Together with the format string the quality value determining the compression rate can be provided, e.g., 'jpeg 30'.

This format can only store images with one channel (gray value image) or three channels (RGB image).

Only images with the pixel type byte are supported for this file format.

Attention: Images stored for being processed later should not be stored in this format due to the loss of information during compression.

'jp2': JPEG-2000 format (lossless and lossy compression), file extension *.jp2

Together with the format string the quality value determining the compression rate can be provided (e.g., 'jp2 40'"jp2 40""jp2 40""jp2 40""jp2 40""jp2 40"). This value corresponds to the ratio of the size of the compressed image and the size of the uncompressed image (in percent). Since lossless JPEG-2000 compression already reduces the file size significantly, only smaller values (typically smaller than 50) influence the file size. If no value is provided for the compression (and only then), the image is compressed without loss.

The image can contain an arbitrary number of channels. Possible types are byte, cyclic, direction, int1, uint2, int2, and int4. In the case of int4 it is only possible to store images with less or equal to 24 bits precision (otherwise an exception is raised). If an image with a reduced domain is written, the region is stored as 1-bit alpha channel.

Note that the JPEG-2000 encoding of an image requires a lot of memory. For large images, it is therefore recommended to use a different format (e.g., 'tiff'"tiff""tiff""tiff""tiff""tiff"). The maximal supported image size (width x height) for JPEG-2000 is also in HALCON-XL.

'jpegxr': JPEG-XR format (lossless and lossy compression), file extension *.jxr

Together with the format string the quality value determining the compression rate can be provided, e.g., 'jpegxr 30' (use 'jpegxr' or 'jpegxr 100' for lossless encoding). All HALCON pixel types except int8 are supported. Image object tuples with an arbitrary number of image objects can be written. Images may have up to 8 channels. In the case of int4 and real images, the numeric range is compressed to 24 bit accuracy. Note that this may induce loss regardless of the quality setting. If an image with a reduced domain is written, the region is stored without loss as 1-bit alpha channel. Complex images, vector fields and regular images with two gray value channels are padded with an empty third channel to be compliant with the standard.

Note that you need to have write permission in your current working directory in order to save an image in JPEG-XR format, regardless of the target directory.

'png': PNG format (lossless compression), file extension *.png

Together with the format string, a compression level between 0 and 9 can be specified, where 0 corresponds to no compression and 9 to the best possible compression. Alternatively, the compression can be selected with the following strings: 'best'"best""best""best""best""best", 'fastest'"fastest""fastest""fastest""fastest""fastest", and 'none'"none""none""none""none""none". Hence, examples for correct parameters are 'png'"png""png""png""png""png", 'png 7'"png 7""png 7""png 7""png 7""png 7", and 'png none'"png none""png none""png none""png none""png none".

Images of type byte and uint2 can be stored in PNG files. If an image with a reduced domain is written, the region is stored as the alpha channel, where the points within the domain are stored as the maximum gray value of the image type and the points outside the domain are stored as the gray value 0. If an image with a full domain is written, no alpha channel is stored.

This format can only store images with one channel (gray value image) or three channels (RGB image). The maximal supported image size (width x height) for PNG is also in HALCON-XL.

'hobj': HALCON Iconic Object (HOBJ), file extension *.hobj

All types of HALCON images are supported. See write_objectwrite_objectWriteObjectWriteObjectWriteObjectwrite_object for more information about the HOBJ format.

'ima': HALCON format, file extension *.ima and *.exp

This file format is now legacy and the HOBJ format should be used instead. The data is written in binary form line by line (without header or carriage return). The size of the image and the pixel type are stored in the description file ”FileNameFileNameFileNameFileNamefileNamefile_name.exp”. All HALCON pixel types except 'complex'"complex""complex""complex""complex""complex" and 'vector_field'"vector_field""vector_field""vector_field""vector_field""vector_field" can be written. For this format, only one channel images can be stored.

Execution Information

Parameters

ImageImageImageImageimageimage (input_object)  (multichannel-)image(-array) objectHImageHObjectHImageHobject (byte / direction / cyclic / int1 / complex / int2 / uint2 / vector_field / int4 / int8 / real)

Input images.

FormatFormatFormatFormatformatformat (input_control)  string HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Graphic format.

Default value: 'tiff' "tiff" "tiff" "tiff" "tiff" "tiff"

Suggested values: 'tiff'"tiff""tiff""tiff""tiff""tiff", 'tiff mask'"tiff mask""tiff mask""tiff mask""tiff mask""tiff mask", 'tiff alpha'"tiff alpha""tiff alpha""tiff alpha""tiff alpha""tiff alpha", 'tiff deflate 9'"tiff deflate 9""tiff deflate 9""tiff deflate 9""tiff deflate 9""tiff deflate 9", 'tiff deflate 9 alpha'"tiff deflate 9 alpha""tiff deflate 9 alpha""tiff deflate 9 alpha""tiff deflate 9 alpha""tiff deflate 9 alpha", 'tiff jpeg 90'"tiff jpeg 90""tiff jpeg 90""tiff jpeg 90""tiff jpeg 90""tiff jpeg 90", 'tiff lzw'"tiff lzw""tiff lzw""tiff lzw""tiff lzw""tiff lzw", 'tiff lzw alpha '"tiff lzw alpha ""tiff lzw alpha ""tiff lzw alpha ""tiff lzw alpha ""tiff lzw alpha ", 'tiff packbits'"tiff packbits""tiff packbits""tiff packbits""tiff packbits""tiff packbits", 'bigtiff'"bigtiff""bigtiff""bigtiff""bigtiff""bigtiff", 'bigtiff mask'"bigtiff mask""bigtiff mask""bigtiff mask""bigtiff mask""bigtiff mask", 'bigtiff alpha'"bigtiff alpha""bigtiff alpha""bigtiff alpha""bigtiff alpha""bigtiff alpha", 'bigtiff deflate 9'"bigtiff deflate 9""bigtiff deflate 9""bigtiff deflate 9""bigtiff deflate 9""bigtiff deflate 9", 'bigtiff deflate 9 alpha'"bigtiff deflate 9 alpha""bigtiff deflate 9 alpha""bigtiff deflate 9 alpha""bigtiff deflate 9 alpha""bigtiff deflate 9 alpha", 'bigtiff jpeg 90'"bigtiff jpeg 90""bigtiff jpeg 90""bigtiff jpeg 90""bigtiff jpeg 90""bigtiff jpeg 90", 'bigtiff lzw'"bigtiff lzw""bigtiff lzw""bigtiff lzw""bigtiff lzw""bigtiff lzw", 'bigtiff lzw alpha '"bigtiff lzw alpha ""bigtiff lzw alpha ""bigtiff lzw alpha ""bigtiff lzw alpha ""bigtiff lzw alpha ", 'bigtiff packbits'"bigtiff packbits""bigtiff packbits""bigtiff packbits""bigtiff packbits""bigtiff packbits", 'bmp'"bmp""bmp""bmp""bmp""bmp", 'jpeg'"jpeg""jpeg""jpeg""jpeg""jpeg", 'jpeg 100'"jpeg 100""jpeg 100""jpeg 100""jpeg 100""jpeg 100", 'jpeg 80'"jpeg 80""jpeg 80""jpeg 80""jpeg 80""jpeg 80", 'jpeg 60'"jpeg 60""jpeg 60""jpeg 60""jpeg 60""jpeg 60", 'jpeg 40'"jpeg 40""jpeg 40""jpeg 40""jpeg 40""jpeg 40", 'jpeg 20'"jpeg 20""jpeg 20""jpeg 20""jpeg 20""jpeg 20", 'jp2'"jp2""jp2""jp2""jp2""jp2", 'jp2 50'"jp2 50""jp2 50""jp2 50""jp2 50""jp2 50", 'jp2 40'"jp2 40""jp2 40""jp2 40""jp2 40""jp2 40", 'jp2 30'"jp2 30""jp2 30""jp2 30""jp2 30""jp2 30", 'jp2 20'"jp2 20""jp2 20""jp2 20""jp2 20""jp2 20", 'jpegxr'"jpegxr""jpegxr""jpegxr""jpegxr""jpegxr", 'jpegxr 50'"jpegxr 50""jpegxr 50""jpegxr 50""jpegxr 50""jpegxr 50", 'jpegxr 40'"jpegxr 40""jpegxr 40""jpegxr 40""jpegxr 40""jpegxr 40", 'jpegxr 30'"jpegxr 30""jpegxr 30""jpegxr 30""jpegxr 30""jpegxr 30", 'jpegxr 20'"jpegxr 20""jpegxr 20""jpegxr 20""jpegxr 20""jpegxr 20", 'png'"png""png""png""png""png", 'png best'"png best""png best""png best""png best""png best", 'png fastest'"png fastest""png fastest""png fastest""png fastest""png fastest", 'png none'"png none""png none""png none""png none""png none", 'ima'"ima""ima""ima""ima""ima", 'hobj'"hobj""hobj""hobj""hobj""hobj"

FillColorFillColorFillColorFillColorfillColorfill_color (input_control)  number HTupleUnion[int, float]HTupleHtuple (integer / real) (int / long / double) (Hlong / double) (Hlong / double)

Fill gray value for pixels not belonging to the image domain (region).

Default value: 0

Suggested values: -1, 0, 255, 65280, 16711680

FileNameFileNameFileNameFileNamefileNamefile_name (input_control)  filename.write(-array) HTupleMaybeSequence[str]HTupleHtuple (string) (string) (HString) (char*)

Name of image file.

File extension: .hobj, .ima, .tif, .tiff, .bmp, .jpg, .jpeg, .jp2, .jxr, .png

Result

If the parameter values are correct the operator write_imagewrite_imageWriteImageWriteImageWriteImagewrite_image returns the value TRUE. Otherwise an exception is raised.

Possible Predecessors

open_windowopen_windowOpenWindowOpenWindowOpenWindowopen_window, read_imageread_imageReadImageReadImageReadImageread_image

Module

Foundation