| MIL 10 Reference
| Customize Help
| Save Settings

McalDraw


See also
Availability
Not available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
McalControl
McalFixture
Synopsis
Draw specific features of results obtained from a calibration operation.
Syntax
void McalDraw(
MIL_ID ContextGraId, //in
MIL_ID ContextCalOrImageBufId, //in
MIL_ID DstImageBufOrListGraId, //in
MIL_INT64 Operation, //in
MIL_INT Index, //in
MIL_INT64 ControlFlag //in
)
Description

This function draws specific features of results, obtained from a calibration operation, in the destination image buffer or graphics list.

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
ContextGraId

Specifies the identifier of the graphics context to use when drawing. This parameter must be set to one of the following values:

function map For specifying the graphics context
CollapseValue Description
Collapse M_DEFAULT

Specifies that the default graphics context of the current MIL application is used.

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

(summarize)
Collapse MIL graphics context identifier

Specifies a valid graphics context identifier, which you have allocated using MgraAlloc().
ContextCalOrImageBufId

Specifies the calibration context, calibrated image, corrected image, or fixturing offset object from which to extract the information to draw.

When specifying a calibrated image or corrected image, the image cannot be associated with a region of interest (ROI), otherwise an error will occur.

If passing a calibration context, it must have been previously allocated on the required system using McalAlloc(). The calibration context should have been successfully calibrated using McalList() or McalGrid().

When working in M_3D_ROBOTICS calibration mode, it is possible to use McalDraw() with M_DRAW_IMAGE_POINTS between two successful calls to McalGrid() / McalList(), to draw the calibration points of one calibration pose before being fully calibrated.

If passing a fixturing offset object, it must have been previously allocated on the required system using McalAlloc() with M_FIXTURING_OFFSET. In addition the fixturing offset object should have been set up using McalFixture() with M_LEARN_OFFSET.

If ContextCalOrImageBufId is set to M_NULL, the coordinate system of the destination image is used.

DstImageBufOrListGraId

Specifies the identifier of the destination image buffer or graphics list in which to draw. If a buffer is specified, it must be an unsigned 8-bit image buffer. By drawing into the display's overlay buffer or associating the graphics list with the display, you can also annotate an image non-destructively.

If specifying an image buffer, it must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

If you specify a graphics list, the graphics list must have been previously allocated using MgraAllocList().

Operation

Specifies the type of operation to perform.

For a calibration context or a fixturing offset object, you can set the Operation parameter to one of the following values. Note that if no combination constant is specified, the coordinate system will be drawn as if M_DRAW_ALL were specified.

function map For a calibration context or a fixturing offset object
CollapseValue Description
Collapse M_DRAW_ABSOLUTE_COORDINATE_SYSTEM +

Draws the absolute coordinate system of the specified source calibration context or calibrated image (ContextCalOrImageBufId). If ContextCalOrImageBufId is set to M_NULL, the function draws the absolute coordinate system of the destination image, DstImageBufOrListGraId. In the case of a graphics list being passed as the destination, the function will use the calibration information associated with the image in which the graphics in the graphics list are rendered; when the graphics list is associated with a display, it uses the calibration information of the image currently selected to the display.

An error is reported if ContextCalOrImageBufId is M_NULL and the image passed to DstImageBufOrListGraId is not a calibrated image. In the case of a graphics list being passed as the destination, the error will occur when the graphics in the graphics list are rendered in an uncalibrated image or display.

If both ContextCalOrImageBufId and DstImageBufOrListGraId have calibration information associated with them, the calibration information associated with ContextCalOrImageBufId will be used to define the position of the coordinate system, while DstImageBufOrListGraId will be used to define the mapping of the coordinates between world and pixel units.

(summarize)
Collapse M_DRAW_PIXEL_COORDINATE_SYSTEM +

Draws the pixel coordinate system of the destination image, DstImageBufOrListGraId with the origin placed at the center of the top-left pixel. ContextCalOrImageBufId should be set to M_NULL.

In the case of a graphics list being passed as the destination, the function will draw the pixel coordinate system of the image in which the graphics in the graphics list are rendered; when the graphics list is associated with a display, it draws the pixel coordinate system of the image currently selected to the display.

(summarize)
Collapse M_DRAW_RELATIVE_COORDINATE_SYSTEM +

Draws the relative coordinate system of the specified source calibration context or calibrated image (ContextCalOrImageBufId). If ContextCalOrImageBufId is set to M_NULL, the function draws the relative coordinate system of the destination image, DstImageBufOrListGraId. In the case of a graphics list being passed as the destination, the function will use the calibration information associated with the image in which the graphics in the graphics list are rendered; when the graphics list is associated with a display, it uses the calibration information of the image currently selected to the display.

An error is reported if ContextCalOrImageBufId is M_NULL and the image passed to DstImageBufOrListGraId is not a calibrated image. In the case of a graphics list being passed as the destination, the error will occur when the graphics in the graphics list are rendered in an uncalibrated image or display.

If both ContextCalOrImageBufId and DstImageBufOrListGraId have calibration information associated with them, the calibration information associated with ContextCalOrImageBufId will be used to define the position of the coordinate system, while DstImageBufOrListGraId will be used to define the mapping of the coordinates between world and pixel units.

(summarize)
Combination constants for the values listed in For a calibration context or a fixturing offset object.

You can add one of the following values to the above-mentioned values to specify how to draw the coordinate system.

function map For specifying how to draw the coordinate system
CollapseCombination value Description
Collapse M_DRAW_ALL

Draws the coordinate system using all the features listed in this table. The behavior of M_DRAW_AXES is chosen over M_DRAW_FRAME. The following is an example of the annotations.

This is the default value.

(summarize)
Collapse M_DRAW_AXES

Draws the X-axis and Y-axis lines with arrow heads and axis labels. If the Z-axis can be seen, it is drawn with an arrow and label. The following is an example of the annotations.

(summarize)
Collapse M_DRAW_FRAME

Draws three arrows (instead of full axes) and axis labels. The following is an example of the annotations.

(summarize)
Collapse M_DRAW_LEGEND

Draws the legend in the image at the bottom right. The major unit describes the distance in real world units between two major marks, and the minor unit describes the distance in real world units between two minor marks. The following is an example of the annotations.

(summarize)
Collapse M_DRAW_MAJOR_MARKS

Draws crosses at each major tick mark. The following is an example of the annotations.

(summarize)
Collapse M_DRAW_MINOR_MARKS

Draws dots at each minor tick mark. The following is an example of the annotations.

(summarize)

You can add the following value to the above-mentioned values to specify a new location for the axes to cross if drawing the world coordinate (0,0) causes an arrow not to be visible.

function map For specifying where the axes will be displayed
CollapseCombination value Description
Collapse M_ALWAYS_SHOW_AXES

Specifies to choose a new location for the axes to cross if, when trying to draw the lines and arrows at world coordinate (0,0), part of the axes would not otherwise be visible .

For a calibration context, you can set the Operation parameter to one of the following:

function map For a calibration context
CollapseValue Description
Collapse M_DRAW_IMAGE_POINTS

Draws the calibration points, used with McalGrid() or McalList(), to calibrate the source calibration context (ContextCalOrImageBufId). It draws the points at the original pixel positions specified (or established) for the calibration points during calibration; it does not use the mapping established during calibration.

(summarize)
Collapse M_DRAW_VALID_REGION

Draws a contour of the rectangle surrounding the calibrated area when using piecewise linear calibration mode (M_LINEAR_INTERPOLATION). The points transformed in this calibrated area are never extrapolated, only interpolated.

(summarize)
Collapse M_DRAW_VALID_REGION_FILLED

Draws a filled rectangle on the calibrated area when using piecewise linear calibration mode (M_LINEAR_INTERPOLATION). The points transformed in this calibrated area are never extrapolated, only interpolated.

(summarize)
Collapse M_DRAW_WORLD_POINTS

Draws the real-world positions of the calibration points, used with McalGrid() or McalList(), to calibrate the source calibration context (ContextCalOrImageBufId).

To draw the real-world positions, it transforms these positions to pixel units using the calibration context associated with destination image, or using ContextCalOrImageBufId if the destination image is not calibrated. It does not use the original pixel positions specified (or established) for the calibration points during calibration; it uses the mapping established during calibration.

(summarize)

For a fixturing offset object, you can set the Operation parameter to the following:

function map For a fixturing offset object
CollapseValue Description
Collapse M_DRAW_FIXTURING_OFFSET

Specifies to draw the reference location that would have been used to place the current relative coordinate system of the destination image, given the specified fixturing offset object. McalDraw() draws a line from the current origin of the relative coordinate system to the inferred reference position. It also draws a small arrow at this position, which illustrates the inferred reference angle.

If the destination image is not calibrated, McalDraw() behaves as if it were calibrated with a uniform scale of 1 and an absolute and relative coordinate system equal to the pixel coordinate system. Note, however, that the destination image remains uncalibrated.

In the case of a graphics list being passed as the destination, the function will use the calibration information associated to the image at the time of annotation.

(summarize)
Index

Specifies the index of the pose of a M_3D_ROBOTICS calibration context from which the calibration points should be drawn. If this information is not required or supported, set this parameter to M_DEFAULT.

function map For specifying the index of the pose
CollapseValue Description
Collapse M_DEFAULT

Specifies to draw the calibration points of the last pose, for M_3D_ROBOTICS calibration contexts. For all other cases, implements the default behavior.

(summarize)
Collapse 0 <= Value <= (Number of poses - 1)

Specifies the index of a calibration pose. Use McalInquire() with M_NUMBER_OF_CALIBRATION_POSES to determine the number of poses.

This setting must be used only when drawing calibration points of a calibration context in M_3D_ROBOTICS mode.

(summarize)
ControlFlag

Reserved for future expansion. This parameter must be set to M_DEFAULT.

Compilation information
Header Include mil.h.
Library Use mil.lib; milcal.lib.
DLL Requires mil.dll; milcal.dll.
DEFAULT NULL PROC NONE NULL TRUE PROC NONE UNSIGNED PROC NONE DRAW ABSOLUTE COORDINATE SYSTEM DRAW PIXEL COORDINATE SYSTEM DRAW RELATIVE COORDINATE SYSTEM DRAW ALL DRAW AXES DRAW FRAME DRAW LEGEND DRAW MAJOR MARKS DRAW MINOR MARKS ALWAYS SHOW AXES DRAW IMAGE POINTS DRAW VALID REGION DRAW VALID REGION FILLED DRAW WORLD POINTS DRAW FIXTURING OFFSET DEFAULT