| Customize Help
| Save Settings

MbufExport


Function Map
Syntax
Description
Parameters
- FileName
Table: For specifying the file name and path
- FileFormat
Table: For determining the file format automatically
Table: For specifying the file format that can be used with either a buffer or a container
Table: For specifying the file format that can be used with a buffer
Table: For specifying the file format for use with a buffer that stores image data
+ 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
Table: For specifying the file format that can be used with a container
Table: For specifying the file format for use with a 3D-processable container
- SrcContainerOrBufId
Remarks
Compilation information
Synopsis
Export a data buffer or container to a file.
Syntax
void MbufExport(
MIL_CONST_TEXT_PTR FileName, //in
MIL_INT64 FileFormat, //in
MIL_ID SrcContainerOrBufId //in
)
Description

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

When exporting an image buffer, all the pixel information in the buffer is exported to the file. 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, PNG, and BMP file formats).

When exporting an image buffer in the M_MIL_TIFF file format, you can save the camera calibration information associated with the buffer (if applicable) using M_WITH_CALIBRATION. Additionally, if the image buffer includes any region of interest (ROI) information, set using MbufSetRegion(), the ROI information is also exported to the file (unless you specify M_NO_REGION).

You can also save a buffer in the M_MIL_TIFF file format, using MbufSave().

[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.

You can export a buffer or container with all of its data, attributes, and settings (excluding process-dependent settings, such as MIL identifiers) using the M_MIL_NATIVE file format. You can restore the buffer or container exactly as it was exported using MbufImport().

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 or container. It is recommended that you use the appropriate file extension for the specified format (for example, files in a JPEG format should usually be stored with the jpg file extension). 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:

function map For specifying the file name and path
Click to summarizeValue Description
Click to summarize MIL_TEXT("FileName") 1

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)
Click to summarize MIL_TEXT("ftp://user:password@server/pathtofile") 1

Export a data buffer to a remote FTP file.

To access a remote FTP server anonymously, omit the user name and password.

FTPS is not supported.

Note that GenDC, STL, and PLY files cannot be imported using an FTP file path.

(summarize)

1 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.

The following setting can be used to store either a buffer or a container with an automatically determined file format.

function map For determining the file format automatically
Click to summarizeValue Description
Click to summarize M_USE_EXTENSION

Specifies that the buffer or container is saved in a format automatically determined from the file extension specified in the FileName parameter. An error is generated if the automatically determined file format cannot be used to store the specified buffer or container.

If the file extension specifies a jpeg or jpeg 2000 format, the buffer is saved as though it were exported using M_JPEG_LOSSY and M_JPEG2000_LOSSY respectively (except if the file extension is jp2, in which case the buffer is saved as though it were exported using M_JPEG2000_LOSSY_JP2).

If the file extension specifies a stl or ply format, the buffer is saved as though it were exported using M_STL_BINARY and M_PLY_BINARY_LITTLE_ENDIAN respectively.

(summarize)

The following file type can be used to store either a buffer or a container.

function map For specifying the file format that can be used with either a buffer or a container
Click to summarizeValue Description
Click to summarize M_MIL_NATIVE

Specifies that the buffer or container is saved in the MIL native file format. This format stores all contents of the buffer or container, including all attributes and settings (excluding process-dependent settings, such as MIL identifiers). The recommended file extension when exporting a buffer is mbuf. The recommended file extension when exporting a container is mbufc.

Note that the MIL native file format is MIL-specific. You can use the M_MIL_TIFF file format to export buffers to a file that complies with the TIFF standard.

(summarize)

The following file types can be used to store any data buffer.

function map For specifying the file format that can be used with a buffer
Click to summarizeValue Description
Click to summarize M_MIL_TIFF +

Specifies that the buffer is saved in a MIL file format that uses the baseline TIFF 6.0 file format with extra MIL 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).

The recommended file extension is mim.

(summarize)
Click to summarize 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)

The following file types can be used to store a buffer in an image format.

Note that the source buffer should typically have an M_IMAGE attribute when exporting to these formats. The data in non-image buffers will be exported as though it were image data. This can be useful for visualizing or compressing non-image data.

function map For specifying the file format for use with a buffer that stores image data
Click to summarizeValue Description MIL system-specific
tooltip (‡)
Click to summarize 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)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Click to summarize 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)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Click to summarize 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)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Click to summarize 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)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Click to summarize 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)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Click to summarize 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)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Click to summarize 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)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Click to summarize 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)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Click to summarize 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)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Click to summarize 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)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Click to summarize M_PNG

Specifies that the buffer is saved in a PNG file format.

 ‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Click to summarize 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)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Combination values for M_MIL_TIFF.

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.

function map For saving camera calibration information or ROI data
Click to summarizeCombination value Description
Click to summarize M_NO_REGION

Specifies that any ROI data associated with the buffer is not saved with the buffer contents.
Click to summarize M_WITH_CALIBRATION

Specifies that any camera calibration information associated with the buffer is saved. To restore the associated camera calibration, use McalRestore().

(summarize)
Combination value for M_MIL_TIFF; 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.

function map For saving a color image in a planar format
Click to summarizeCombination value Description
Click to summarize 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.

function map For saving an image in big endian format
Click to summarizeCombination value Description
Click to summarize 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.

function map For compressing a TIFF image file
Click to summarizeCombination value Description
Click to summarize M_COMPRESSION_CCITTFAX3

Specifies to use CCITT FAX3 compression.

This compression can only be used with monochrome 1-bit buffers.

(summarize)
Click to summarize M_COMPRESSION_CCITTFAX4

Specifies to use CCITT FAX4 compression.

This compression can only be used with monochrome 1-bit buffers.

(summarize)
Click to summarize M_COMPRESSION_CCITTRLE

Specifies to use CCITT RLE compression.

This compression can only be used with monochrome 1-bit buffers.

(summarize)
Click to summarize M_COMPRESSION_CCITTRLEW

Specifies to use CCITT RLEW compression.

This compression can only be used with monochrome 1-bit buffers.

(summarize)
Click to summarize M_COMPRESSION_LZW

Specifies to use LZW compression.
Click to summarize M_COMPRESSION_NONE

Specifies to use no compression.
Click to summarize M_COMPRESSION_PACKBITS

Specifies to use PackBits compression.

The following file type can be used to store any container.

function map For specifying the file format that can be used with a container
Click to summarizeValue Description
Click to summarize M_GENDC

Specifies that the container is saved in the GenDC file format.

The recommended file extension is gendc.

An error is generated if the source container has one of the following:

(summarize)

The following file types can be used to store a 3D-processable point cloud container (you can inquire whether a container is 3D-processable using MbufInquireContainer() with M_3D_PROCESSABLE). Any points with a confidence of zero will not be exported. Intensity, reflectance, normals, and mesh components will be included in the exported file.

Note that these settings are only available when mil3d.dll is present.

function map For specifying the file format for use with a 3D-processable container
Click to summarizeValue Description
Click to summarize M_PLY_ASCII

Specifies that the point cloud container is saved in the PLY file format using ASCII encoding.
Click to summarize M_PLY_BINARY_LITTLE_ENDIAN

Specifies that the point cloud container is saved in the PLY file format using binary encoding.
Click to summarize M_STL_ASCII

Specifies that the point cloud container is saved in the STL file format using ASCII encoding.

Note that exporting to an STL file requires the presence of a valid mesh component.

(summarize)
Click to summarize M_STL_BINARY

Specifies that the point cloud container is saved in the STL file format using binary encoding.

Note that exporting to an STL file requires the presence of a valid mesh component.

(summarize)
SrcContainerOrBufId

Specifies the identifier of the data buffer or container to save.

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, mil3d.dll for some formats.
USE EXTENSION MIL NATIVE MIL TIFF RAW BMP JPEG2000 LOSSLESS JPEG2000 LOSSLESS JP2 JPEG2000 LOSSY JPEG2000 LOSSY JP2 JPEG LOSSLESS JPEG LOSSLESS INTERLACED JPEG LOSSY JPEG LOSSY INTERLACED JPEG LOSSY RGB PNG TIFF NO REGION WITH CALIBRATION PLANAR BIG ENDIAN COMPRESSION CCITTFAX3 COMPRESSION CCITTFAX4 COMPRESSION CCITTRLE COMPRESSION CCITTRLEW COMPRESSION LZW COMPRESSION NONE COMPRESSION PACKBITS GENDC PLY ASCII PLY BINARY LITTLE ENDIAN STL ASCII STL BINARY NOT PROCESSABLE