MIL provides several data buffer management functions. These allow you to copy data from one buffer to another, clone a buffer, transfer data between an array and a buffer, load data into a buffer, save a buffer to disk, and perform operations on sequences of image buffers.
You can copy different required portions of one buffer to another as follows:
Copy an entire image buffer to another buffer, using MbufCopy() or using MbufClone() with M_COPY_SRC_DATA. While MbufCopy() requires you to allocate a destination buffer before calling the function, MbufClone() will automatically allocate one similar to the original.
Copy an image buffer to another buffer at the specified offset, using MbufCopyClip(). Data that falls outside of the destination buffer will be automatically clipped.
Copy specific non-sequential areas to another buffer based on a condition buffer, using MbufCopyCond(). Source buffer data is copied to the destination buffer if corresponding data in the specified condition buffer satisfies the copy condition. Other data in the destination buffer is left unaffected.
Copy specific non-consecutive bits to another buffer based on a mask, using MbufCopyMask(). Only destination bits that correspond to non-zero bits in the mask are modified with source bits.
Copy a single band of a multi-color band buffer to or from a single-band buffer, using MbufCopyColor() or MbufCopyColor2d(). This allows you to operate on a single color band of a buffer.
Note that only MbufCopy() and MbufClone() copy the entire buffer into another buffer; the other functions copy only portions of a buffer.
If the source and destination buffers have different depth and size, MIL converts data according to the following general rules:
|
Case |
Result |
|
Source depth > destination depth |
The most significant bits are truncated when the data is copied into the destination. |
|
Destination depth > source depth |
The source data is zero or sign-extended (depending on the type of the source) when copied into the destination. |
|
Destination size > source size |
Exceeding areas of the destination buffer are unaffected. |
If the source and destination buffers have the same number of band(s), all band(s) will be copied correspondingly. Otherwise, the following rules apply:
|
When copying from |
Result |
|
3-band to 1-band |
Only the first band of the three is copied (for example, the Y band of a YUV buffer and the R band of an RGB buffer). |
|
1-band to 3-band |
All the three bands of the destination buffer are filled with the same data. Note that if the source buffer is associated with a LUT buffer, it will be first mapped through the LUT. |
MIL automatically handles data type and data format conversions. When copying from a floating-point buffer to an integer buffer, the values are truncated. When converting an M_RGB15 buffer into an M_BGR24 buffer, the least-significant bits of each band are set to 0.
Note that when copying from a non-binary buffer to a binary buffer, all non-zero pixels in the source buffer are represented as ones (1) in the binary buffer. When copying a binary buffer to a buffer of a different depth, each single-bit pixel is copied into the least-significant bit of its corresponding destination pixel. The remaining bits of the destination pixel are set to 0; to propagate the bit value to all bits, use MimBinarize().
MIL also automatically handles source and destination buffers with different compression types.
|
When copying from |
Result |
|
M_COMPRESS to uncompressed |
The data will be automatically decompressed. |
|
Uncompressed to M_COMPRESS |
The data will be automatically compressed. |
|
M_COMPRESS to M_COMPRESS (with different compression types) |
The data will be re-compressed according to the settings in the destination buffer. |
You can clone a data buffer using MbufClone(). This function takes a specified source buffer and allocates a new buffer with similar characteristics (a clone). The degree of similarity between the two buffers is determined by the settings that you pass to MbufClone(). By default, MbufClone() allocates a clone on the same system as the original, and the two buffers have the same size, data type, and attributes. However, when calling MbufClone(), you can specify, for example, for the clone to have a different size than the source. You can also specify whether or not to copy the source buffer's data to the clone. The buffer's data is not copied by default.
Note that regardless of the specified settings, MbufClone() does not clone the source buffer's region of interest.
You can put data from an array into a data buffer, using MbufPut(), MbufPut1d(), MbufPut2d(), MbufPutColor(), or MbufPutColor2d(). MbufPut() puts data in the entire buffer, while MbufPutColor() or MbufPutColor2d() put data into one or all color bands of a multi-band buffer. The other two functions allow you to put data in a selected area of a monochrome buffer, respectively.
In addition, you can retrieve data from a data buffer and place it into an array, using MbufGet(), MbufGet1d(), MbufGet2d(), MbufGetColor(), or MbufGetColor2d(). MbufGet() gets data from the entire buffer, while MbufGetColor() or MbufGetColor2d() get data from one or all bands of a multi-band buffer. The other two functions, like their "put in buffer" counterparts, allow you to get data from a selected area of a monochrome, respectively.
Note that you can also access the contents of a MIL buffer from an array using MbufInquire(). Inquire the Host address of the buffer, and then using a pointer access the buffer as an array. This is discussed in more detail later.
You can load data into a MIL data buffer, using one of two methods:
Load data into an automatically allocated MIL data buffer, using MbufImport() with M_RESTORE, or using MbufRestore().
Load data into a previously allocated MIL data buffer, using MbufImport() with M_LOAD or using MbufLoad().
These functions internally handle the opening and closing of the file. With MbufImport(), you can specify the file's format. MbufLoad() and MbufRestore() will read the data in the file to determine the format; therefore, they might take more time to return a result.
You can save a data buffer to disk, using MbufExport() or MbufSave(). MbufExport() is the most general of these functions and can save data in any MIL-supported file format. MbufSave() can only save data in an M_MIL file format.
These functions internally handle opening and closing the file. If the given file name already exists, the file will be overwritten.
You can perform operations on a sequence of image buffers. You can import a sequence of images from a file using MbufImportSequence(). You can export a sequence of image buffers to a file using MbufExportSequence(). You can also use the MIL Sequences module to perform operations such as H.264 compression and decompression on sequences. For more information about using the Sequences module, see the MIL Sequences module overview section of Chapter 28: Sequences.