| Customize Help

Managing data buffers


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.

Copying data from one buffer to another

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

Cloning a data 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.

Transferring data between an array and a buffer

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.

Loading a data buffer

You can load data into a MIL data buffer, using one of two methods:

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.

Saving a data buffer

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 a buffer in an M_MIL_TIFF 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 use the M_MIL_NATIVE format to store any data buffer, including its settings, ROI, and calibration information. You can use the M_MIL_TIFF format to save an image buffer with its ROI and calibration information in a file that can be viewed by any software that supports the TIFF 6.0 specification.

Performing operations on a sequence of image buffers

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 29: Sequences.