ImageWriter

Typedefs
typedef struct peak_imagewriter *	peak_imagewriter_handle
	peak ImageWriter handle The value for an invalid ImageWriter handle is PEAK_INVALID_HANDLE.

Enumerations
enum	peak_imagefile_format {   PEAK_IMAGEFILE_FORMAT_INVALID , PEAK_IMAGEFILE_FORMAT_PNG , PEAK_IMAGEFILE_FORMAT_JPEG , PEAK_IMAGEFILE_FORMAT_TIFF ,   PEAK_IMAGEFILE_FORMAT_BMP , PEAK_IMAGEFILE_FORMAT_RAW }
	ImageWriter image file formats. More...

Functions
peak_status	peak_IPL_ImageWriter_Create (peak_imagewriter_handle *hImageWriter)
	Creates a new ImageWriter instance.
peak_status	peak_IPL_ImageWriter_Destroy (peak_imagewriter_handle hImageWriter)
	Destroys an ImageWriter instance.
peak_status	peak_IPL_ImageWriter_Save (peak_imagewriter_handle hImageWriter, peak_frame_handle hFrame, const char *fileName)
	Save the given frame.
peak_status	peak_IPL_ImageWriter_Format_Set (peak_imagewriter_handle hImageWriter, peak_imagefile_format imageFormat)
	Sets an image file format for the ImageWriter instance.
peak_status	peak_IPL_ImageWriter_Format_Get (peak_imagewriter_handle hImageWriter, peak_imagefile_format *imageFormat)
	Reads the currently set image file format from the ImageWriter instance.
peak_status	peak_IPL_ImageWriter_Compression_Set (peak_imagewriter_handle hImageWriter, uint32_t compression)
	Sets a compression for the ImageWriter instance.
peak_status	peak_IPL_ImageWriter_Compression_Get (peak_imagewriter_handle hImageWriter, uint32_t *compression)
	Reads the currently set compression ratio from the ImageWriter instance.

Detailed Description

ImageWriter saves images to a file. Multiple ImageWriter objects can be configured to specify image file format and compression ratio.

Note

If only an 'ImageWriter' is created without configuring the default image format is PNG with a compression ratio of 25.

The following image formats are supported:

• Portable Network Graphics (PNG)
• Bitmap (BMP)
• Joint Photographic Experts Group (JPEG)
• Tag Image File Format (TIFF)
• Raw Binary Format (RAW)

The image is saved via peak_IPL_ImageWriter_Save with specified file path and file name.

Note

The file extension for the given file name must match the specified image format when a image is saved. Otherwise an error will occur when saving an image. The file extensions are:

• PNG: .png
• BMP: .bmp
• JPEG: .jpeg
• TIFF: .tiff

It is also possible to save an image without the ImageWriter. See peak_Frame_Save for more information.

Note

The Compression ratio is only used for PNG and JPEG file formats.

Supported image and pixel formats

Bitmap

Not all image formats can be written to a Bitmap file. Supported image formats are:

• Mono8
• Mono10
• Mono12
• RGB8
• BGR8
• RGBa8
• BGRa8

Written as Mono:

• BayerGR8, BayerRG8, BayerGB8, BayerBG8
• BayerGR10, BayerRG10, BayerGB10, BayerBG10
• BayerGR12, BayerRG12, BayerGB12, BayerBG12

PNG

Not all image formats can be written to a PNG file. Supported image formats are:

• Mono8
• Mono10
• Mono12
• RGB8
• RGB10
• RGB12
• RGBa8
• RGBa10
• RGBa12

Written as Mono:

• BayerGR8, BayerRG8, BayerGB8, BayerBG8
• BayerGR10, BayerRG10, BayerGB10, BayerBG10,
• BayerGR12, BayerRG12, BayerGB12, BayerBG12

Written as RGB:

• BGR8
• BGR10
• BGR12
• BGRa8
• BGRa10
• RGBa12

Note

For PNG image format higher compression rates result in higher storage times and cpu utilization.

TIFF

Not all image formats can be written to a TIFF file. Unsupported images formats are all packed image formats, YUV, all formats with alpha channel and all BGR pixel formats.

JPEG

Not all image formats can be written to a JPEG file. Supported image formats are:

• Mono8
• RGB8
• BGR8
• RGBa8
• BGRa8

Written as Mono:

• BayerGR8, BayerRG8, BayerGB8, BayerBG8

Note

For JPEG image format higher compression rates result in lower quality image. A compression ratio of 0 means a maximum of image quality.

RAW

Writes the specified image to the filesystem as a raw binary image. This is supported for all non-packed pixel formats.

Examples

Note

To reduce and simplify the sample code, the examples do not check the return values.

Configure a PNG ImageWriter with high compression

peak_imagewriter_handle image_writer_handle = PEAK_INVALID_HANDLE;
peak_IPL_ImageWriter_Create(&image_writer_handle);
 
peak_IPL_ImageWriter_Format_Set(image_writer_handle, PEAK_IMAGEFILE_FORMAT_PNG);
peak_IPL_ImageWriter_Compression_Set(image_writer_handle, 80);
 
peak_IPL_ImageWriter_Save(image_writer_handle, hFrame, "out.png");
 
peak_IPL_ImageWriter_Destroy(image_writer_handle);

Configure a JPEG ImageWriter with maximum quality

peak_imagewriter_handle image_writer_handle = PEAK_INVALID_HANDLE;
peak_IPL_ImageWriter_Create(&image_writer_handle);
 
peak_IPL_ImageWriter_Format_Set(image_writer_handle, PEAK_IMAGEFILE_FORMAT_JPEG);
peak_IPL_ImageWriter_Compression_Set(image_writer_handle, 0);
 
peak_IPL_ImageWriter_Save(image_writer_handle, hFrame, "out.jpeg");
 
peak_IPL_ImageWriter_Destroy(image_writer_handle);

Enumeration Type Documentation

peak_imagefile_format

enum peak_imagefile_format

ImageWriter image file formats.

All currently supported image file formats that could be save via peak_IPL_ImageWriter_Save peak_Frame_Save

Enumerator
PEAK_IMAGEFILE_FORMAT_INVALID	Invalid image file format. Use this value for the initialization of variables of type peak_imagefile_format.
PEAK_IMAGEFILE_FORMAT_PNG	Image file format PNG. Use this value to configure the ImageWriter instance to save a PNG image File extension: .png
PEAK_IMAGEFILE_FORMAT_JPEG	Image file format JPEG. Use this value to configure the ImageWriter instance to save a JPEG image File extension: .jpeg
PEAK_IMAGEFILE_FORMAT_TIFF	Image file format TIFF. Use this value to configure the ImageWriter instance to save a TIFF file File extension: .tiff
PEAK_IMAGEFILE_FORMAT_BMP	Image file format BMP. Use this value to configure the ImageWriter instance to save a BMP file File extension: .bmp
PEAK_IMAGEFILE_FORMAT_RAW	Image file format RAW. Use this value to configure the ImageWriter instance to save a RAW file File extension: .raw

Function Documentation

peak_IPL_ImageWriter_Compression_Get()

peak_status peak_IPL_ImageWriter_Compression_Get	(	peak_imagewriter_handle	hImageWriter,
		uint32_t *	compression )

Reads the currently set compression ratio from the ImageWriter instance.

Reads the compression ratio from the ImageWriter instance

Parameters

[in]	hImageWriter	The ImageWriter handle.
[out]	compression	The currently used image format.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_INVALID_PARAMETER compression is an invalid pointer.

PEAK_STATUS_INVALID_HANDLE hImageWriter is an invalid handle.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_ERROR An unexpected internal error occurred.

Since

1.9

peak_IPL_ImageWriter_Compression_Set()

peak_status peak_IPL_ImageWriter_Compression_Set	(	peak_imagewriter_handle	hImageWriter,
		uint32_t	compression )

Sets a compression for the ImageWriter instance.

Configures the ImageWriter instance to use the specified compression ratio in range of 0 (no compression) - 100 (maximum compression).

Parameters

[in]	hImageWriter	The ImageWriter handle.
[in]	compression	The new compression ratio to use.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_INVALID_PARAMETER compression is an invalid value.

PEAK_STATUS_INVALID_HANDLE hImageWriter is an invalid handle.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_ERROR An unexpected internal error occurred.

Since

1.9

peak_IPL_ImageWriter_Create()

peak_status peak_IPL_ImageWriter_Create

(

peak_imagewriter_handle *

hImageWriter

)

Creates a new ImageWriter instance.

Parameters

[out]

hImageWriter

Pointer to a handle for an ImageWriter receiving the instance handle.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_INVALID_PARAMETER hImageWriter is an invalid pointer.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_ERROR An unexpected internal error occurred.

Since

1.9

peak_IPL_ImageWriter_Destroy()

peak_status peak_IPL_ImageWriter_Destroy

(

peak_imagewriter_handle

hImageWriter

)

Destroys an ImageWriter instance.

After the call, the handle is invalid.

Parameters

[in]

hImageWriter

The ImageWriter handle.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_INVALID_HANDLE hImageWriter is an invalid handle.

PEAK_STATUS_INVALID_PARAMETER hImageWriter is an invalid pointer.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_ERROR An unexpected internal error occurred.

Since

1.9

peak_IPL_ImageWriter_Format_Get()

peak_status peak_IPL_ImageWriter_Format_Get	(	peak_imagewriter_handle	hImageWriter,
		peak_imagefile_format *	imageFormat )

Reads the currently set image file format from the ImageWriter instance.

Reads the ImageWriter instance to use the specified image format to save images

Parameters

[in]	hImageWriter	The ImageWriter handle.
[out]	imageFormat	The currently used image format.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_INVALID_PARAMETER imageFormat is an invalid pointer.

PEAK_STATUS_INVALID_HANDLE hImageWriter is an invalid handle.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_ERROR An unexpected internal error occurred.

Since

1.9

peak_IPL_ImageWriter_Format_Set()

peak_status peak_IPL_ImageWriter_Format_Set	(	peak_imagewriter_handle	hImageWriter,
		peak_imagefile_format	imageFormat )

Sets an image file format for the ImageWriter instance.

Configures the ImageWriter instance to use the specified image format to save images

Parameters

[in]	hImageWriter	The ImageWriter handle.
[in]	imageFormat	The new image format to use.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_INVALID_PARAMETER imageFormat is an invalid value.

PEAK_STATUS_INVALID_HANDLE hImageWriter is an invalid handle.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_ERROR An unexpected internal error occurred.

Since

1.9

peak_IPL_ImageWriter_Save()

peak_status peak_IPL_ImageWriter_Save	(	peak_imagewriter_handle	hImageWriter,
		peak_frame_handle	hFrame,
		const char *	fileName )

Save the given frame.

Write the given frame to the file system with the configured file format and compression ratio.

Parameters

[in]	hImageWriter	The ImageWriter handle.
[in]	hFrame	The frame handle.
[in]	fileName	The given file name to use as an utf-8 encoded string

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_INVALID_PARAMETER fileName is an invalid pointer or invalid file extension.

PEAK_STATUS_INVALID_HANDLE hImageWriter or hFrame is an invalid handle.

PEAK_STATUS_NOT_SUPPORTED hFrame has an unsupported pixel format for this file format.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_IO Errors during file access e.g. no permissions on this file.

PEAK_STATUS_ERROR An unexpected internal error occurred.

Since

1.9