MbufImport

See also

Availability

Available in MIL-Lite with restrictions (see remarks)

Available in MIL

Available on Windows

Available on Linux

Available on Non-Matrox computer

Available on Matrox 4Sight-X

Available on Matrox 4Sight GP/GPm

Available on Matrox Supersight

Function map

Examples

Function Map

- FileName

Table:

For specifying the file name and path

- FileFormat

Table:	For specifying a file format that might need to be imported to a buffer or container
Table:	For specifying a file format that must be imported to a buffer
+ combination:	For importing camera calibration or ROI information
Table:	For specifying a file format that must be imported to a container

- Operation

Table:	For specifying the import operation
+ combination:	For specifying how the buffer or container is loaded
+ combination:	For specifying that the buffer is not restored with a certain attribute

- SysId

Table:

For specifying the system on which to allocate the buffer (with M_RESTORE)

- ContainerOrBufIdPtr

Return value

Remarks

Compilation information

Synopsis

Import data from a file into a data buffer or container.

Syntax

MIL_ID MbufImport(

MIL_CONST_TEXT_PTR FileName,	//in
MIL_INT64 FileFormat,	//in
MIL_INT64 Operation,	//in
MIL_ID SysId,	//in
MIL_ID *ContainerOrBufIdPtr	//in-out

)

Description

This function imports data from a file into an existing or automatically allocated MIL data buffer or container. The function assumes that the data in the file is in the specified format.

Note, you can also import data using MbufLoad() or MbufRestore(); however, these functions try to determine the format from the data rather than allowing you to specify the format.

For an M_RESTORE operation of an image, this function tries to allocate the buffer so that it can be used for acquisition (M_GRAB), display (M_DISP), and processing (M_PROC) operations. If there is insufficient appropriate memory to allocate such a buffer, it allocates one that can be used in all of the above operations except for acquisition (M_GRAB). Note that the maximum (total) number of grab (M_GRAB) buffers that can be allocated is restricted by the total amount of MIL non-paged (DMA) memory (specified at installation time or using the MILConfig utility). For systems with on-board processors, the total number of M_GRAB buffers and M_PROC buffers is limited by the amount of on-board memory. You can specify that the restored buffer is not allocated with the acquisition or compression attributes (M_GRAB or M_COMPRESS respectively), by combining M_RESTORE with M_NO_GRAB or M_NO_COMPRESS respectively.

For an M_RESTORE operation of 3D data stored in the M_MIL_NATIVE file format, this function allocates a container with the same intended purpose attributes (M_GRAB, M_PROC and M_DISP) as the container stored in the file. For and M_RESTORE operation of 3D data stored in another file format, this function allocates a container that can be used for display (M_DISP) and processing (M_PROC) operations.

For an M_RESTORE operation with an M_MIL_TIFF or M_MIL_NATIVE file format that stores a non-image buffer, this function allocates the destination buffer with the same attributes as the original buffer.

If importing an image, all the pixel information in the file is imported and loaded into the buffer. Additionally, if the file was saved in M_MIL_TIFF file format and includes any region of interest (ROI) information, the ROI information is also imported and loaded into the buffer when the FileFormat parameter is set to M_MIL_TIFF. To load the M_MIL_TIFF file without its ROI information, set FileFormat to M_MIL_TIFF + M_NO_REGION. If the file was saved with calibration information, it is always loaded.

If the vectorial information of an M_VECTOR_AND_RASTER ROI was input in M_WORLD units, the ROI will be imported as an M_VECTOR ROI.

[MIL-Lite with restriction]

When performing an M_RESTORE operation on a file containing compressed data, the buffer will have an M_COMPRESS attribute.

[MIL-Lite with restriction]

When importing compressed data, the following applies. When performing an M_LOAD operation and the destination buffer has an M_IMAGE attribute (but not an M_COMPRESS attribute), this function will automatically decompress it. If necessary, the data in the file will be transformed to the format of the buffer. If unsure of the compression type of the data, use M_DEFAULT as the file format rather than M_JPEG_... or M_JPEG2000_...; the data will be read correctly.

[MIL-Lite with restriction]

When importing uncompressed data into a buffer with an M_COMPRESS attribute, this function will automatically compress it, according to the compression settings found in the buffer.

When importing an image file (not stored in the M_MIL_NATIVE file format) that has been saved with an associated LUT (color palette) into a 3-band 8-bit image buffer, the LUT is automatically applied to the data to generate 3-band image data. In this case, a LUT buffer is not created and, therefore, is not associated with the 3-band 8-bit buffer. When importing an image file that has been saved with an associated LUT (color palette) into any other type of image buffer, the LUT is also imported and associated with the resulting image buffer. You can obtain the identifier of the associated LUT, using MbufInquire().

Note that the associated LUT will be automatically selected on the display (MdispLut()) if the image buffer is selected on a display and the default LUT has not been overridden by a former call to MdispLut().

Using MbufDiskInquire(), you can inquire about the dimensions of the data saved in a file (except for raw files, M_GENDC files, and M_MIL_NATIVE files that store a container) without importing it.

After restoring a buffer or container, it is recommended that you check if the operation was successful, using MappGetError(), or by verifying that the returned buffer or container identifier is not M_NULL.

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 if there is complementary information.

Parameters

This function is not supported on the selected boards.

Parameters

FileName

Specifies the name and path of the file from which to import the data. The function handles (internally) the opening and closing of the file.

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...)
MIL_TEXT("ftp://user:password@server/pathtofile") ¹	Import data from a remote FTP server into a data buffer or container. To access a remote FTP server anonymously, omit the user name and password. FTPS is not supported. Note that importing PLY and STL files from a remote FTP server is not supported. (summarize) Import data from a remote FTP server into a data buffer or container. (more details...)
MIL_TEXT("http://user:password@server/pathtofile") ¹	Import data from a remote HTTP server into a data buffer or container. HTTPS is not supported. Note that importing PLY and STL files from a remote HTTP server is not supported. (summarize) Import data from a remote HTTP server into a data buffer or container. (more details...)

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

FileFormat

Specifies the file format. This parameter can be set to one of the following values. Note that except for the M_MIL_NATIVE, M_MIL_TIFF, M_GENDC and M_RAW file formats, data is treated as image data. When performing an M_LOAD operation, the data is internally converted appropriately.

The following file types might require a buffer or a container as a destination. You can determine which object type is required as a destination using MbufDiskInquire() with M_OBJECT_TYPE.

For specifying a file format that might need to be imported to a buffer or container
Value	Description
M_DEFAULT	Specifies that MIL automatically determines the file format. If the file format is not supported, its data will be treated as raw data. (summarize) Specifies that MIL automatically determines the file format. (more details...)
M_MIL_NATIVE	Imports a container or buffer saved in the MIL native file format (typically with the mbuf or mbufc file extension). This format stores the entire content of a MIL container or MIL buffer, including settings. (summarize) Imports a container or buffer saved in the MIL native file format (typically with the mbuf or mbufc file extension). (more details...)

The following file formats must have a buffer as a destination.

For specifying a file format that must be imported to a buffer
Value	Description
M_BMP	Imports image data that is in BMP file format. The standard Windows BMP format is used. If the specified BMP file contains an image whose image format, data type, and/or depth is not supported by MIL for image buffers, the image will not be imported. (summarize) Imports image data that is in BMP file format. (more details...)
M_JPEG2000_LOSSLESS	[For essential MIL-Lite information, see remarks ] Imports a JPEG2000 lossless image.
M_JPEG2000_LOSSLESS_JP2	[For essential MIL-Lite information, see remarks ] Imports a JPEG2000 lossless image, as well as the additional JP2 information.
M_JPEG2000_LOSSY	[For essential MIL-Lite information, see remarks ] Imports a JPEG2000 lossy image.
M_JPEG2000_LOSSY_JP2	[For essential MIL-Lite information, see remarks ] Imports a JPEG2000 lossy image, as well as the additional JP2 information.
M_JPEG_LOSSLESS	[For essential MIL-Lite information, see remarks ] Imports a JPEG lossless image.
M_JPEG_LOSSLESS_INTERLACED	[For essential MIL-Lite information, see remarks ] Imports a JPEG lossless image stored in two separate fields.
M_JPEG_LOSSY	[For essential MIL-Lite information, see remarks ] Imports a JPEG lossy image.
M_JPEG_LOSSY_INTERLACED	[For essential MIL-Lite information, see remarks ] Imports a JPEG lossy image stored in two separate fields.
M_JPEG_LOSSY_RGB	[For essential MIL-Lite information, see remarks ] Imports a 3-band JPEG lossy image that is in an RGB format.
M_MIL_TIFF +	Imports data that is in the M_MIL_TIFF file format (typically with the mim file extension). The baseline TIFF 6.0 specification is used. (summarize) Imports data that is in the M_MIL_TIFF file format (typically with the mim file extension). (more details...)
M_PNG	Imports image data that is in a PNG file format.
M_RAW	Imports raw data.
M_TIFF	Imports image data that is in a TIFF file format. The baseline TIFF 6.0 specification is used. If the specified TIFF file contains an image whose image format, data type, and/or depth is not supported by MIL for image buffers, the image will not be imported. Multi-page TIFF files can be imported into MIL buffers but only the first page is saved in the buffer. (summarize) Imports image data that is in a TIFF file format. (more details...)

Combination values for M_MIL_TIFF.

You can add one or more of the following values to the above-mentioned value to set whether to import the image with additional information.

Note that you can only specify these values if importing an image (for example, you can specify M_NO_REGION + M_WITH_CALIBRATION).

For importing camera calibration or ROI information
Combination value	Description
M_NO_REGION	Imports the image, excluding any saved ROI information.
M_WITH_CALIBRATION	Imports the image, including its camera calibration information. Note that, this image must have been saved using MbufExport() and it must have a constant pixel size. If the image does not have a constant pixel size, the image will be imported without its camera calibration information; the target buffer will be uncalibrated. If the image is calibrated and it has a constant pixel size, it is associated with a default uniform camera calibration context upon being imported into the buffer (as set using McalUniform()). If the image is imported into an existing buffer that is associated with a camera calibration context, the initial camera calibration context is replaced by that of the imported image. (summarize) Imports the image, including its camera calibration information. (more details...)

The following file types must have a container as a destination.

For specifying a file format that must be imported to a container
Value	Description
M_GENDC	Imports a container saved in the GenDC file format.
M_PLY_ASCII	Imports point cloud data saved in the PLY file format using ASCII encoding. mil3d.dll must be present to import this format. (summarize) Imports point cloud data saved in the PLY file format using ASCII encoding. (more details...)
M_PLY_BINARY_LITTLE_ENDIAN	Imports point cloud data saved in the PLY file format using binary encoding. mil3d.dll must be present to import this format. (summarize) Imports point cloud data saved in the PLY file format using binary encoding. (more details...)
M_STL_ASCII	Imports point cloud data, saved in the STL file format using ASCII encoding. STL files always include mesh data. mil3d.dll must be present to import this format. (summarize) Imports point cloud data, saved in the STL file format using ASCII encoding. (more details...)
M_STL_BINARY	Imports point cloud data, saved in the STL file format using binary encoding. STL files always include mesh data. mil3d.dll must be present to import this format. (summarize) Imports point cloud data, saved in the STL file format using binary encoding. (more details...)

Operation

Specifies the import operation. This parameter can be set to one of the following values.

For specifying the import operation
Value	Description
M_LOAD +	Imports data from the specified file into a previously allocated MIL data buffer or container. If the destination is a container, all of its existing components will be freed. By default, the contents of the file are loaded, including all data and settings. Optional attributes (such as M_COMPRESS) of data stored in the file are not copied. You can use M_IDENTICAL to specify that the buffer size and optional attributes of the specified file must be loaded from the file. When loading a file to a buffer, the attributes of the destination buffer are used when loading the data (for example, if the destination does not have the M_COMPRESS attribute, the file will be decompressed during the load operation).When loading a file to a container, components in the file are loaded to components allocated without optional attributes (for example, components that store compressed data are loaded to components allocated without the M_COMPRESS attribute). (summarize) Imports data from the specified file into a previously allocated MIL data buffer or container. (more details...)
M_RESTORE +	Imports data from the specified file into an automatically allocated MIL data buffer or container. Note, you cannot restore (M_RESTORE) a RAW data file (M_RAW) because its dimensions are unknown. (summarize) Imports data from the specified file into an automatically allocated MIL data buffer or container. (more details...)

Combination values for M_LOAD.

You can add one of the following values to the above-mentioned value to specify how the contents of the file are loaded into the specified buffer or container..

Note that these settings are only available for loading from a M_MIL_NATIVE or M_GENDC file.

For specifying how the buffer or container is loaded
Combination value	Description
M_BASIC_ATTRIBUTE	Specifies to load the contents of the file (that stores data suitable for loading into a container) to automatically allocated components that might have different attributes than the components stored in the file. Note that this setting is only available for a container, not a buffer. (summarize) Specifies to load the contents of the file (that stores data suitable for loading into a container) to automatically allocated components that might have different attributes than the components stored in the file. (more details...)
M_IDENTICAL	Specifies to load the contents of the file, including all data, settings, and attributes. This setting is only available for M_MIL_NATIVE and M_GENDC files. An error will be generated if there is a mismatch between the size, number of bands, or attributes (such as M_RGB24) of the destination buffer and the contents of the file. (summarize) Specifies to load the contents of the file, including all data, settings, and attributes. (more details...)
M_USE_DESTINATION	Specifies to load the contents of the file (that stores data suitable for loading into a container) into the existing components of the destination container. An error will be generated if the file has a different number of components than the destination container, or if at least one of the components in the file cannot be loaded into the component with the same index in the container (for example, because the components of the destination container are of the wrong buffer type to store the imported data). Note that this setting is only available for a container, not a buffer. (summarize) Specifies to load the contents of the file (that stores data suitable for loading into a container) into the existing components of the destination container. (more details...)

Combination values for M_RESTORE.

You can add one or more of the following values to the above-mentioned value to specify that the buffer is not restored with a certain attribute.

Note that these values are only available when restoring an image buffer, not a container.

For specifying that the buffer is not restored with a certain attribute
Combination value	Description
M_NO_COMPRESS	Specifies that MIL will not allocate the restored data buffer with an M_COMPRESS attribute.
M_NO_GRAB	Specifies that MIL will not allocate the restored data buffer or container with an M_GRAB attribute.

SysId

Specifies the system on which to allocate the buffer or container for an M_RESTORE operation. For an M_LOAD operation, this parameter should be set to M_NULL.

For an M_RESTORE operation, this parameter should be set to one of the following values:

For specifying the system on which to allocate the buffer (with M_RESTORE)
Value	Description
M_DEFAULT_HOST	Specifies the default Host system of the current MIL application.
MIL system identifier	Specifies a valid system identifier, previously allocated using MsysAlloc().

ContainerOrBufIdPtr

Specifies the address of the variable containing the buffer or container identifier, for an M_LOAD operation, or the address of the variable in which to store the new buffer or container identifier, for an M_RESTORE operation.

For an M_LOAD operation, the destination buffer must be large enough in depth and dimensions to hold the data. If the data is deeper than the buffer, the most-significant bits of the data are truncated when loaded into the buffer. If the buffer depth is greater than that of the data, the data is zero or sign-extended (depending on the data type) when loaded into the buffer. If the buffer is larger in size than the data, exceeding areas of the buffer are unaffected.

For an M_RESTORE operation, the destination buffer or container will be allocated with an appropriate size and type to hold the data. Since MbufImport() also returns the buffer or container identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

The returned value is the buffer or container identifier (for an M_RESTORE operation only). If allocation fails, M_NULL is returned.

Remark

[MIL-Lite]

Note that during development and at runtime, compression support is reliant upon the presence of a compression/decompression package license. This license is only included by default with the development dongle for the full version of MIL. In other cases, this license must be purchased separately.

Compilation information

Header	Include mil.h.
Library	Use mil.lib;.
DLL	Requires mil.dll, mil3d.dll for some formats.