Click here to show toolbars of the Web Online Help System: show toolbars
 

| Customize Help
| Save Settings

McalDraw


Function Map
Syntax
Description
Parameters
- ContextGraId
Table: For specifying the graphics context
- ContextCalOrImageBufId
- DstImageBufOrListGraId
- Operation
Table: For a camera calibration context or a fixturing offset object
+ combination: For specifying how to draw the coordinate system
+ combination: For specifying where the axes will be displayed
Table: For a camera calibration context
Table: For a fixturing offset object
- Index
Table: For specifying the index of the pose
- ControlFlag
Compilation information
Synopsis
Draw specific features of results obtained from a camera 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 camera 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
Click to summarizeValue Description
Click to summarize 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)
Click to summarize MIL graphics context identifier

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

Specifies the camera 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 camera calibration context, it must have been previously allocated on the required system using McalAlloc(). The camera calibration context should have been successfully calibrated using McalList() or McalGrid().

When working in M_3D_ROBOTICS camera calibration mode, it is possible to use McalDraw() with M_DRAW_IMAGE_POINTS, and for fiducial grids M_DRAW_FIDUCIAL_BOX, between two successful calls to McalGrid() / McalList(), to draw the calibration points or the fiducial box of one camera 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 camera 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 camera calibration context or a fixturing offset object
Click to summarizeValue Description
Click to summarize M_DRAW_ABSOLUTE_COORDINATE_SYSTEM +

Draws the absolute coordinate system of the specified source camera 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 camera 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 camera 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 camera calibration information associated with them, the camera 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)
Click to summarize 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)
Click to summarize M_DRAW_RELATIVE_COORDINATE_SYSTEM +

Draws the relative coordinate system of the specified source camera 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 camera 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 camera 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 camera calibration information associated with them, the camera 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 values for the values listed in For a camera 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
Click to summarize
Combination value		 Description
Click to summarize 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)
Click to summarize 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)
Click to summarize M_DRAW_FRAME

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

(summarize)
Click to summarize 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)
Click to summarize M_DRAW_MAJOR_MARKS

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

(summarize)
Click to summarize M_DRAW_MINOR_MARKS

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

(summarize)
Combination value for M_DRAW_ABSOLUTE_COORDINATE_SYSTEM; M_DRAW_RELATIVE_COORDINATE_SYSTEM.

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
Click to summarizeCombination value Description
Click to summarize 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 camera calibration context, you can set the Operation parameter to one of the following:

function map For a camera calibration context
Click to summarizeValue Description
Click to summarize M_DRAW_FIDUCIAL_BOX

Draws a box around the fiducial located during calibration, for fiducial grids with a Data Matrix code (McalGrid() with M_GRID_FIDUCIAL set to M_DATAMATRIX).
Click to summarize M_DRAW_IMAGE_POINTS

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

(summarize)
Click to summarize M_DRAW_VALID_REGION

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

(summarize)
Click to summarize M_DRAW_VALID_REGION_FILLED

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

(summarize)
Click to summarize M_DRAW_WORLD_POINTS

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

To draw the real-world positions, it transforms these positions to pixel units using the camera 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 camera calibration; it uses the mapping established during camera calibration.

(summarize)

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

function map For a fixturing offset object
Click to summarizeValue Description
Click to summarize 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 camera calibration information associated to the image at the time of annotation.

(summarize)
Index

Specifies the index of the pose of a M_3D_ROBOTICS camera calibration context from which the calibration points or fiducial box 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
Click to summarizeValue Description
Click to summarize M_DEFAULT

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

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

Specifies the index of a camera 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 camera 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 FIDUCIAL BOX DRAW IMAGE POINTS DRAW VALID REGION DRAW VALID REGION FILLED DRAW WORLD POINTS DRAW FIXTURING OFFSET DEFAULT DATAMATRIX