MbufExport

Filters
See also

User Guide:

Camera calibration propagation Dealing with color General steps Managing data buffers

Reference:

MbufAllocColor MbufControl MbufImport MbufSave MbufSetRegion McalRestore

Availability

Available in MIL-Lite with restrictions (see remarks)

Available in MIL

Available on Windows

Available on Linux

Partially supported on:

Partially supported on Matrox Iris GT (f)

Partially supported on Matrox Iris GTR (requires Update 28) (t)

Fully supported on:

Fully supported on Host system (a)

Fully supported on Matrox CronosPlus (b)

Fully supported on Matrox GigE Vision driver (c)

Fully supported on Matrox GPU processing driver (d)

Fully supported on Matrox IEEE 1394 IIDC driver (e)

Fully supported on Matrox Morphis (g)

Fully supported on Matrox Morphis QxT (h)

Fully supported on Matrox Orion HD (i)

Fully supported on Matrox Radient eCL (j)

Fully supported on Matrox Radient eV-CXP (k)

Fully supported on Matrox Solios eA/XA (l)

Fully supported on Matrox Solios ecl/xcl/ev-cl (m)

Fully supported on Matrox Vio (n)

Fully supported on Matrox USB3 Vision driver (requires Update 19) (o)

Fully supported on Matrox RadientPro-CL (requires Update 7) (p)

Fully supported on Matrox Radient eV-CLHS (requires Update 21) (q)

Fully supported on Matrox Radient eV-CL (requires Update 27) (r)

Fully supported on Matrox GigE Vision driver (requires Update 25) (s)

For any information regarding a MIL system added during a MIL Update, see the MIL system’s release note

Available on Non-Matrox computer

Available on Matrox 4Sight-X

Available on Matrox 4Sight GP/GPm

Available on Matrox Supersight

Function map

Examples

addfiducials.cpp
calgenchessgrid.cpp
mdispgtkview.cpp
mdispmfcdoc.cpp
mdispqtview.cpp

Function Map

- FileName

Table:

For specifying the file name and path

- FileFormat

Table:	For specifying the file format
+ combination:	For saving camera calibration information or ROI data
+ combination:	For saving a color image in a planar format
+ combination:	For saving an image in big endian format
+ combination:	For compressing a TIFF image file

- SrcBufId

Remarks

Compilation information

Synopsis

Export a data buffer to a file.

Syntax

void MbufExport(

MIL_CONST_TEXT_PTR FileName,	//in
MIL_INT64 FileFormat,	//in
MIL_ID SrcBufId	//in

)

Description

This function exports a data buffer to a file, in the specified output file format.

If exporting an image, all the pixel information in the buffer is exported to the file. Additionally, if the image buffer includes any region of interest (ROI) information, set using MbufSetRegion(), the ROI information is also exported to the file when you export the image in M_MIL file format. If you specify a different file format (for example, M_TIFF), the ROI information cannot be exported to the file. To avoid exporting ROI information to the file when exporting the image in M_MIL file format, set FileFormat to M_MIL + M_NO_REGION.

Note that you can also save a buffer in an M_MIL file format, using MbufSave(). The M_MIL file format is TIFF compatible.

To export an image with a LUT (color palette), associate the LUT to the image, using MbufControl(). Upon export, the image is saved with its associated color palette (MIM, TIFF, and BMP file formats).

[MIL-Lite with restriction]

When exporting uncompressed data to a file in an M_JPEG_... or M_JPEG2000_... file format, this function will automatically compress the data, according to the specified file format. The buffer does not need an M_COMPRESS attribute. If you are exporting compressed data to a file in an uncompressed file format, this function will automatically decompress the data.

To save the camera calibration information associated with the buffer (if applicable), use M_WITH_CALIBRATION.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see which MIL system’s documentation you should use in its place and any possible differences.

Parameters

This function is not supported on the selected boards.

This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.

Parameters

FileName

Specifies the name and path of the file in which to save the data buffer. It is recommended that you use the MIM file extension for easier use with other Matrox Imaging software products. The function handles (internally) the opening and closing of the file. If the file already exists, it will be overwritten.

This parameter can be set to the following value:

For specifying the file name and path
Value	Description
MIL_TEXT("FileName") ¹	Specifies the drive, directory, and name of the file (for example, "C:\mydirectory\myfile"). To specify a file on a remote computer (under Distributed MIL), prefix the specified file name string with "remote:///" (for example, "remote:///C:\mydirectory\myfile"). (summarize) Specifies the drive, directory, and name of the file (for example, "C:\mydirectory\myfile"). (more details...)

¹ If you are passing the value in a variable, don't enclose it in MIL_TEXT().

FileFormat INQ

Specifies the file format. This parameter can be set to one of the following values. Note that, except for the M_MIL and M_RAW file formats, the source buffer should have an M_IMAGE attribute; otherwise, the data is saved as if it were image data.

For specifying the file format
Value	Description	MIL system-specific tooltip (‡)
M_BMP	Specifies that the buffer is saved in a BMP file format. The standard Windows BMP format is used. This file format supports images that are grayscale or RGB. Images in a different format are internally converted before being saved. This file format supports only 8-bit, or 8-bit/band if applicable, buffers. If you are saving a non 8-bit buffer in this file format, only the 8 least-significant bits are saved/band. (summarize) Specifies that the buffer is saved in a BMP file format. (more details...)	‡	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s	t	u
M_JPEG2000_LOSSLESS	[For essential MIL-Lite information, see remarks ] Specifies that the buffer is saved in a JPEG2000 lossless file format. If the buffer is 3-band and does not have an M_COMPRESS + M_JPEG2000_LOSSLESS attribute, the data will be stored in RGB format; otherwise, it will be stored in the same color format as the buffer. This file format supports only 8- and 16-bit buffers. 1-bit buffers are unpacked and saved as 8-bit buffers. 32-bit buffers are saved as 16-bit buffers; only the 16-least significant bits are saved. In the case of a 32-bit buffer, it is best to shift the buffer by 16 bits to the right before exporting the image to keep the most significant data. (summarize) [For essential MIL-Lite information, see remarks ] Specifies that the buffer is saved in a JPEG2000 lossless file format. (more details...)	‡	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s	t	u
M_JPEG2000_LOSSLESS_JP2	[For essential MIL-Lite information, see remarks ] Specifies that the buffer is saved in a JPEG2000 lossless file format using the standard JP2 format. Only the color specification of the image buffer can be specified from the additional JP2 information. If the buffer is 3-band and does not have an M_COMPRESS + M_JPEG2000_LOSSLESS attribute, the data will be stored in RGB format; otherwise, it will be stored in the same color format as the buffer. This file format supports only 8- and 16-bit buffers. 1-bit buffers are unpacked and saved as 8-bit buffers. 32-bit buffers are saved as 16-bit buffers; only the 16-least significant bits are saved. In the case of a 32-bit buffer, it is best to shift the buffer by 16 bits to the right before exporting the image to keep the most significant data. (summarize) [For essential MIL-Lite information, see remarks ] Specifies that the buffer is saved in a JPEG2000 lossless file format using the standard JP2 format. (more details...)	‡	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s	t	u
M_JPEG2000_LOSSY	[For essential MIL-Lite information, see remarks ] Specifies that the buffer is saved in a JPEG2000 lossy file format. If the buffer is 3-band and does not have an M_COMPRESS + M_JPEG2000_LOSSY attribute, the data will be stored in YUV16 planar format if the buffer is 8-bit or in RGB format if the buffer is 16-bit; otherwise, it will be stored in the same color format as the buffer. This file format supports only 8- and 16-bit buffers. 1-bit buffers are unpacked and saved as 8-bit buffers. 32-bit buffers are saved as 16-bit buffers; only the 16-least significant bits are saved. In the case of a 32-bit buffer, it is best to shift the buffer by 16 bits to the right before exporting the image to keep the most significant data. (summarize) [For essential MIL-Lite information, see remarks ] Specifies that the buffer is saved in a JPEG2000 lossy file format. (more details...)	‡	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s	t	u
M_JPEG2000_LOSSY_JP2	[For essential MIL-Lite information, see remarks ] Specifies that the buffer is saved in a JP2000 lossy file format using the standard JP2 file format. Only the color specification of the image buffer can be specified from the additional JP2 information. If the buffer is 3-band and does not have an M_COMPRESS + M_JPEG2000_LOSSY attribute, the data will be stored in YUV16 planar format if the buffer is 8-bit or in RGB format if the buffer is 16-bit; otherwise, it will be stored in the same color format as the buffer. This file format supports only 8- and 16-bit buffers. 1-bit buffers are unpacked and saved as 8-bit buffers. 32-bit buffers are saved as 16-bit buffers; only the 16-least significant bits are saved. In the case of a 32-bit buffer, it is best to shift the buffer by 16 bits to the right before exporting the image to keep the most significant data. (summarize) [For essential MIL-Lite information, see remarks ] Specifies that the buffer is saved in a JP2000 lossy file format using the standard JP2 file format. (more details...)	‡	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s	t	u
M_JPEG_LOSSLESS	[For essential MIL-Lite information, see remarks ] Specifies that the buffer is saved in a JPEG lossless file format. If the buffer is 3-band, the data will be stored in RGB format. This file format supports only 8- and 16-bit buffers. 1-bit buffers are unpacked and saved as 8-bit buffers. 32-bit buffers are saved as 16-bit buffers; only the 16-least significant bits are saved. In the case of a 32-bit buffer, it is best to shift the buffer by 16 bits to the right before exporting the image to keep the most significant data. (summarize) [For essential MIL-Lite information, see remarks ] Specifies that the buffer is saved in a JPEG lossless file format. (more details...)	‡	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s	t	u
M_JPEG_LOSSLESS_INTERLACED	[For essential MIL-Lite information, see remarks ] Specifies that the buffer is saved in an interlaced JPEG lossless file format. This file format is only applicable to 1-band image buffers. This file format supports only 8- and 16-bit buffers. 1-bit buffers are unpacked and saved as 8-bit buffers. 32-bit buffers are saved as 16-bit buffers; only the 16-least significant bits are saved. In the case of a 32-bit buffer, it is best to shift the buffer by 16 bits to the right before exporting the image to keep the most significant data. (summarize) [For essential MIL-Lite information, see remarks ] Specifies that the buffer is saved in an interlaced JPEG lossless file format. (more details...)	‡	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s	t	u
M_JPEG_LOSSY	[For essential MIL-Lite information, see remarks ] Specifies that the buffer is saved in a JPEG lossy file format. If the buffer is 3-band and does not have an M_COMPRESS + M_JPEG_LOSSY attribute, the data will be stored in YUV16 packed format; otherwise, it will be stored in the same color format as the buffer. This file format supports only 8-bit, or 8-bit/band if applicable, buffers. If you are saving a non 8-bit buffer in this file format, only the 8 least-significant bits are saved/band. (summarize) [For essential MIL-Lite information, see remarks ] Specifies that the buffer is saved in a JPEG lossy file format. (more details...)	‡	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s	t	u
M_JPEG_LOSSY_INTERLACED	[For essential MIL-Lite information, see remarks ] Specifies that the buffer is saved in an interlaced JPEG lossy file format. If the buffer is 3-band, the data will be stored in YUV16 packed format. This file format supports only 8-bit, or 8-bit/band if applicable, buffers. If you are saving a non 8-bit buffer in this file format, only the 8 least-significant bits are saved/band. (summarize) [For essential MIL-Lite information, see remarks ] Specifies that the buffer is saved in an interlaced JPEG lossy file format. (more details...)	‡	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s	t	u
M_JPEG_LOSSY_RGB	[For essential MIL-Lite information, see remarks ] Specifies that the buffer is saved in a JPEG lossy file format. If the buffer is 3-band, the data will be stored in RGB format. This file format supports only 8-bit, or 8-bit/band if applicable, buffers. If you are saving a non 8-bit buffer in this file format, only the 8 least-significant bits are saved/band. (summarize) [For essential MIL-Lite information, see remarks ] Specifies that the buffer is saved in a JPEG lossy file format. (more details...)	‡	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s	t	u
M_MIL +	Specifies that the buffer is saved in a MIL file format. It uses a baseline TIFF 6.0 file format with extra information included in the comment field. The buffer attributes and data type are also saved in the file. This file format supports images that are binary, grayscale, and RGB, as well as palette-color images. The MIL file format is a single-page, uncompressed TIFF file format. By default, most color image buffers are saved in a packed (chunky) format (in accordance with baseline TIFF 6.0 specifications). Color binary buffers are saved in a 1-bit per pixel format (data is stored in a 3-band, packed binary format). (summarize) Specifies that the buffer is saved in a MIL file format. (more details...)	‡	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s	t	u
M_PNG	Specifies that the buffer is saved in a PNG file format.	‡	a	b	c	d	e		g	h	i	j	k	l	m	n	o	p	q	r	s		u
M_RAW	Specifies that the buffer is saved as raw data. The contents are dumped directly (byte stream) into the file and no header is added. If the buffer is multi-band, the buffer is saved in planar format (one band after another). (summarize) Specifies that the buffer is saved as raw data. (more details...)	‡	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s	t	u
M_TIFF +	Specifies that the buffer is saved in a TIFF file format. The TIFF file format that is used respects the baseline TIFF 6.0 specification. The TIFF file format that is used supports images that are binary, grayscale, and RGB, as well as palette-color images. Also, this TIFF format supports any data type and depth that MIL supports for buffers. An image buffer cannot be saved using a multi-page TIFF file format; it is always saved as a single-page TIFF file. By default, most color image buffers are saved in a packed (chunky) format (in accordance with baseline TIFF 6.0 specifications). Color binary buffers are saved in a 1-bit per pixel format (data is stored in a 3-band, packed binary format). (summarize) Specifies that the buffer is saved in a TIFF file format. (more details...)	‡	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s	t	u

Combination values for M_MIL.

You can add one of the following values to the above-mentioned value to set whether to save the camera calibration information or region of interest data associated with the buffer.

For saving camera calibration information or ROI data
Combination value	Description
M_NO_REGION	Specifies that any ROI data associated with the buffer is not saved with the buffer contents.
M_WITH_CALIBRATION	Specifies that any camera calibration information associated with the buffer is saved. To restore the associated camera calibration, use McalRestore(). (summarize) Specifies that any camera calibration information associated with the buffer is saved. (more details...)

Combination value for M_MIL; M_TIFF.

You can add the following value to the above-mentioned values to set whether to save the color image buffer in a planar format.

For saving a color image in a planar format
Combination value	Description
M_PLANAR	Specifies that the color image buffer is saved in a planar format.

Combination value for M_TIFF.

You can add the following value to the above-mentioned value to set whether to save the image buffer in big endian format.

For saving an image in big endian format
Combination value	Description
M_BIG_ENDIAN	Specifies that the image buffer is saved in big endian format.

Combination values for M_TIFF.

You can add one of the following values to the above-mentioned value to set whether to use compression when saving a TIFF image file.

For compressing a TIFF image file
Combination value	Description
M_COMPRESSION_CCITTFAX3	Specifies to use CCITT FAX3 compression. This compression can only be used with monochrome 1-bit buffers. (summarize) Specifies to use CCITT FAX3 compression. (more details...)
M_COMPRESSION_CCITTFAX4	Specifies to use CCITT FAX4 compression. This compression can only be used with monochrome 1-bit buffers. (summarize) Specifies to use CCITT FAX4 compression. (more details...)
M_COMPRESSION_CCITTRLE	Specifies to use CCITT RLE compression. This compression can only be used with monochrome 1-bit buffers. (summarize) Specifies to use CCITT RLE compression. (more details...)
M_COMPRESSION_CCITTRLEW	Specifies to use CCITT RLEW compression. This compression can only be used with monochrome 1-bit buffers. (summarize) Specifies to use CCITT RLEW compression. (more details...)
M_COMPRESSION_LZW	Specifies to use LZW compression.
M_COMPRESSION_NONE	Specifies to use no compression.
M_COMPRESSION_PACKBITS	Specifies to use PackBits compression.

SrcBufId

Specifies the identifier of the data buffer to save. This image buffer can have an ROI set using MbufSetRegion().

Remark

[MIL-Lite]

Note that during development and at runtime, compression support, particularly for an M_IMAGE + M_COMPRESS buffer type, requires the presence of a MIL license that grants access to the compression/decompression package. This access is only granted by default with the development license dongle for the full version of MIL. In other cases, you must purchase access to this package separately.

Compilation information

Header	Include mil.h.
Library	Use mil.lib.
DLL	Requires mil.dll.