| Customize Help

Allocating, displaying, and annotating an image buffer


After you have allocated an application along with any required system(s), you are ready to grab and display an image. This section covers how to allocate and display an image buffer. For the basics required to start grabbing, see the Grabbing images section later in this chapter.

Allocating an image buffer

Image buffers are storage areas that can hold image data so that it can be displayed, manipulated, grabbed, and/or analyzed. To store color image data, MIL uses the concept of bands; your buffer needs one band per color component of your image. For example, an RGB image needs a buffer with three bands.

You can allocate a monochrome image buffer using MbufAlloc2d(). This function requires that you specify the following image buffer attributes:

  • The system on which to allocate the buffer.

  • The image buffer's size in X and Y.

  • The depth of the buffer: 1-, 8-, 16-, or 32-bit.

  • The image buffer's data type. Signed, unsigned, and floating-point buffers are all supported by MIL.

  • The image buffer's intended use (for example, processing or display).

You can allocate a color image buffer using MbufAllocColor(). This function requires that you specify the number of color bands in addition to the attributes listed above. To operate on a specific band or region of an image buffer, you can use MbufChild...(). For more information on how to deal with color using MIL, see the Dealing with color section later in this chapter.

When you allocate an image buffer, you need to specify its intended uses so that it will be appropriately allocated in memory. If you intend to use the buffer to store grabbed data, the buffer must be allocated with an M_GRAB attribute. If you intend to display the buffer, you must allocate it with an M_DISP attribute. If you intend to use the buffer as the source or destination buffer of a processing or analysis operation, you must allocate the buffer with an M_PROC attribute. Note that you can combine these attribute so that the buffer can be allocated for multiple uses.

For more information on buffers and other buffer attributes, see Chapter 21: Data buffers.

Displaying an image buffer

Especially during application development, it is useful to display the image buffer that you are manipulating. You must first allocate a MIL 2D display on the target system, using MdispAlloc(). If you have allocated a displayable image buffer (M_DISP), select it to this 2D display, using MdispSelect(); you can use the same function to stop displaying it.

Note that the image buffer and the 2D display should be allocated on the same system.

Annotating an image on display

You can also annotate an image on display. This can be done either destructively, which alters the original image, or non-destructively, which maintains the original image but displays annotations placed on top of it. To draw directly in an image, which replaces the image's original pixel values with the newly drawn values, you can use the MIL 2D graphics functions. For non-destructive image annotation, MIL offers two main options: using a 2D graphics list and using the overlay mechanism.

To draw directly in an image, you can use the functions in the MIL 2D graphics module, such as MgraArcFill() or MgraText() in the following example. You can specify a default 2D graphics context that uses default settings for background and foreground color and text alignment. Alternatively, you can allocate a new 2D graphics context. For both the default and user-allocated 2D graphics contexts, you can specify the graphics settings and these contexts can be re-used for multiple MIL 2D graphics functions.

To annotate an image non-destructively, you can allocate a 2D graphics list, using MgraAllocList(), populate it with graphics created using MIL 2D graphics functions or the draw functions of other MIL modules, and associate the 2D graphics list with the 2D display using MdispControl() with M_ASSOCIATED_GRAPHIC_LIST_ID. Once the 2D graphics list is associated with the 2D display, the graphics are drawn over the image buffer without altering the image buffer itself. When annotating with a 2D graphics list, zooming the 2D display will not affect the size or orientation of the annotations.

You can also use the overlay mechanism to annotate an image non-destructively, using MdispControl() with M_OVERLAY set to M_ENABLE. Once you have enabled the overlay mechanism, a temporary overlay buffer is allocated which you can populate with annotations using, for example, the MIL 2D graphics module or Windows GDI annotations. You can directly access this temporary overlay buffer using MdispInquire() with M_OVERLAY_ID.

The overlay buffer has a transparency (keying) color that helps determine whether the overlay buffer's pixels or the image buffer's pixels will be displayed. The pixels in the overlay buffer that are set to the transparency color are rendered invisible, displaying the underlying image buffer's pixels. Every pixel in the overlay buffer that has a color other than the transparency color will be displayed. You can determine the transparency color using MdispInquire() with M_TRANSPARENT_COLOR, and you can select another color using MdispControl() with M_TRANSPARENT_COLOR.

When annotating with the overlay mechanism, zooming the 2D display will resize the annotations. This can lead to pixelation, the loss of some annotations, or changes in line thickness.

The following code snippet shows you how to allocate, display, and annotate an image buffer. Note that the annotations are destructive because there is neither a 2D graphics list specified, nor is the overlay mechanism enabled.


/* Allocate a system for a Matrox Morphis board. Use a different */
/* value or "M_DEFAULT" for other types of systems.              */
MappAlloc (M_DEFAULT, &MilApplication);
MsysAlloc (M_DEFAULT, M_SYSTEM_MORPHIS, M_DEFAULT, M_DEFAULT, &MilSystem);
MdispAlloc (MilSystem, M_DEFAULT, MIL_TEXT("M_DEFAULT"), M_WINDOWED, &MilDisplay);

/* Allocate an image buffer with the default dimensions to do graphics. */
MbufAlloc2d (MilSystem, 512,512, 8+M_UNSIGNED, M_IMAGE+M_DISP+M_GRAB, &MilImage);

/* Draw and display a circle */
MbufClear (MilImage, 0L);
MgraArcFill (M_DEFAULT, MilImage, 256L, 240L, 100L, 100L, 0.0, 360.0);
MgraText (M_DEFAULT, MilImage, 238L, 234L, MIL_TEXT(" MIL "));

/* Display the image buffer. */
MdispSelect (MilDisplay, MilImage);

/* Print a message. */
MosPrintf (MIL_TEXT("A circle was drawn in the displayed image buffer.\n"));

/* Free all allocations */
MbufFree (MilImage);
MdispFree (MilDisplay);
MsysFree (MilSystem);
MappFree (MilApplication);

For more information on displaying and annotating an image, see Chapter 23: Displaying an image. To allocate a display on a DMIL remote system, see the Remote displays subsection of the Controlling configuration section of Chapter 48: Distributed MIL. For more information on MIL 2D graphics functions and 2D graphics lists, see Chapter 24: Generating graphics.