| Customize Help

2D graphics context


A 2D graphics context is used to control the behavior of graphics and drawings before they are rendered in an image or added to a 2D graphics list. To allocate a 2D graphics context, use MgraAlloc(). Whenever an annotation is done in an image buffer, 2D graphics context settings are applied to the graphics, which you can change according to your requirements using MgraControl(). Whenever a graphic is added to a 2D graphics list, it inherits 2D graphics context settings, which you can change afterwards using MgraControlList(). The following 2D graphics context settings apply to all graphics:

  • Foreground color. This determines the color in which graphics are drawn. The default foreground color value is the highest positive buffer value (typically corresponds to white). To change the default, use MgraControl() with M_COLOR.

    Note that a grayscale value can be any integer or floating-point number. If the given value exceeds the range of possible values that can be stored in each band of the destination buffer, the least significant bits of the value are used.

  • Draw offset and zoom. This determines whether to draw graphics and results into an image buffer with an offset and zoom. The default is no offset or zoom. For more information, see the Drawing graphics with offset and zoom subsection of the Drawing graphics section later in this chapter.

  • Input units. This determines the units to use for all applicable settings, such as position, dimension, and angle. The default is pixels. To change the default, use MgraControl() with M_INPUT_UNITS.

  • Camera calibration information. This determines the camera calibration information to use to interpret positioning and dimensioning information of a graphic defined in world units. The default is to use the camera calibration information associated with the destination.

  • Conversion mode. This determines how the graphic shape will be rendered, when the graphic has been defined in world units and the destination image does not have a constant pixel size, using either MgraControl() or MgraControlList() with M_GRAPHIC_CONVERSION_MODE.

Once you are satisfied with the graphics settings, you should determine whether you need to clear the destination image buffer prior to drawing in it. You can use MgraClear() or MbufClear() to clear the buffer to a specific color. To clear a 16-bit or 32-bit multi-band buffer to a color value, use MgraClear(). Note that, unlike MbufClear(), MgraClear() does not remove a camera calibration context associated with the image buffer.

Default 2D graphics context

When a MIL application context is allocated, using MappAlloc() or MappAllocDefault(), a default 2D graphics context is automatically allocated. It can be used in the same way as a normal 2D graphics context allocated with MgraAlloc(). Since the default 2D graphics context (M_DEFAULT) is simply another 2D graphics context, you can change its settings according to your needs using MgraControl().

Note that there is a different default 2D graphics context for each thread.

Specifying the camera calibration information

When rendering (drawing or displaying) a graphic, that has been defined in world units (M_INPUT_UNITS set to M_WORLD), MIL can interpret positioning and dimensioning information of the graphic solely using camera calibration information associated with the graphic. By default, MIL uses the destination camera calibration information, that is, the camera calibration information of the image buffer (or image buffer selected to the display) in which the graphic is to be rendered. Alternatively, you can have MIL use the source camera calibration information, that is, the camera calibration information of a camera calibration context, image buffer, or processing or analysis module result buffer, associated with the graphic (before being rendered in a destination image buffer).

The source camera calibration information is specified using MgraControl() or MgraControlList() with M_GRAPHIC_SOURCE_CALIBRATION. If this control type is set using MgraControl(), the camera calibration information will be associated with the 2D graphics context, not copied. For example, if the relative coordinate system changes after using M_GRAPHIC_SOURCE_CALIBRATION, it will be reflected in the camera calibration information that is used. Alternatively, if MgraControlList() is used to set the source camera calibration information, the camera calibration information will be copied to an internal camera calibration context; it will not be associated with the 2D graphics list. For example, if the relative coordinate system changes after using M_GRAPHIC_SOURCE_CALIBRATION, it will have no effect on the graphic.

If only the destination camera calibration information is available, it will be used to render the graphic. However, if the camera calibration information of both the destination and source are available, you should use M_FIXTURE to identify with respect to which of their relative coordinate systems the positioning and dimensioning information is to be specified. If with respect to that of the destination camera calibration information (M_FIXTURE set to M_USE_DESTINATION_FIRST), the source camera calibration information is not used. If with respect to that of the source camera calibration information (M_FIXTURE set to M_USE_SOURCE_FIRST), positions and dimensions are transformed from this relative coordinate system to the absolute coordinate system; then, since it is assumed that there is only one absolute coordinate system, these positions and dimensions are transformed from the absolute coordinate system to the pixel coordinate system, using the destination camera calibration information. If the destination camera calibration information is not available, the source camera calibration information will be used for the world to pixel mapping.