| MIL 10 Reference
| Customize Help
| Save Settings

McalInquireSingle


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
McalInquire
McalList
Synopsis
Inquire about a single pose in a sequence of poses taken during calibration.
Syntax
MIL_INT McalInquireSingle(
MIL_ID CalibrationId, //in
MIL_INT Index, //in
MIL_INT64 InquireType, //in
void *UserVarPtr //out
)
Description

This function allows you to inquire about the settings of a single pose in the sequence of poses performed to calibrate M_3D_ROBOTICS calibration contexts. Every call to McalGrid() or McalList() with M_ACCUMULATE corresponds to a pose used to obtain information about the camera setup during the calibration process.

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
CalibrationId

Specifies the identifier of the calibration context.

Index

Specifies the index of the pose of a M_3D_ROBOTICS calibration context from which settings should be inquired. The first call corresponds to the index value 0 and the last one is the return value of McalInquire() with M_NUMBER_OF_CALIBRATION_POSES minus one.

InquireType

Specifies the setting about which to inquire.

See the Parameter associations section for possible values that can be specified.

UserVarPtr
Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):
  • array of type MIL_DOUBLE
  • char
  • MIL_DOUBLE
  • MIL_FLOAT
  • MIL_ID
  • MIL_INT
  • MIL_INT16
  • MIL_INT32
  • MIL_INT64

Specifies the address in which to return the value of the inquired setting.

Since McalInquireSingle() also returns the value of the inquired setting, you can set UserVarPtr to M_NULL.

See the Parameter associations section for possible values that can be returned.

Parameter associations

The tables below list possible values for the InquireType parameter and possible values returned to the UserVarPtr parameter.

The InquireType parameter can be set to one of the following values only after calibrating with McalGrid().

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_DOUBLE.

function map For a calibration context being calibrated using McalGrid()
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_COLUMN_NUMBER +

Inquires the number of columns in the calibration grid. SET

(summarize)
Collapse Value

Specifies the number of columns.
Collapse M_COLUMN_SPACING +

Inquires the number of world units between columns. SET

(summarize)
Collapse Value

Specifies the spacing between columns.
Collapse M_GRID_ORIGIN_X +

Inquires the X-position of the top-left circle of a circle grid, or the top-left point connecting four squares in a chessboard grid, in the camera calibration plane coordinate system. SET

(summarize)
Collapse Value

Specifies the X-position, in the camera calibration plane coordinate system.
Collapse M_GRID_ORIGIN_Y +

Inquires the Y-position of the top-left circle of a circle grid, or the top-left point connecting four squares in a chessboard grid, in the camera calibration plane coordinate system. SET

(summarize)
Collapse Value

Specifies the Y-position, in the camera calibration plane coordinate system.
Collapse M_GRID_ORIGIN_Z +

Inquires the Z-position of the top-left circle of a circle grid, or the top-left point connecting four squares in a chessboard grid, in the camera calibration plane coordinate system. SET

(summarize)
Collapse Value

Specifies the Z-position, in the camera calibration plane coordinate system.
Collapse M_GRID_TYPE +

Inquires the type of grid used to perform the calibration. SET

(summarize)
Collapse M_CHESSBOARD_GRID

Specifies a chessboard grid. INFO
Collapse M_CIRCLE_GRID

Specifies a grid of circles. INFO
Collapse M_ROW_NUMBER +

Inquires the number of rows in the calibration grid. SET

(summarize)
Collapse Value

Specifies the number of rows.
Collapse M_ROW_SPACING +

Inquires the spacing between rows in the calibration grid. SET

(summarize)
Collapse Value

Specifies the spacing between rows, in world units.
Combination constant for the values listed in For a calibration context being calibrated using McalGrid().

You can add the following value to the above-mentioned values to determine the default value of an inquire type.

function map For inquiring the default value
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_DEFAULT

Inquires the default value of the specified inquire type.

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_DOUBLE

The InquireType parameter can be set to one of the following values after a call to either McalGrid() or McalList().

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_DOUBLE.

function map For a calibration context being calibrated using McalGrid() or McalList()
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_AVERAGE_PIXEL_ERROR +

Inquires the average calibration error in the pixel coordinate system.

This is the average distance in the pixel coordinate system between the initial calibration points and their projected points in an image.

(summarize)
Collapse Value

Specifies the average calibration error, in pixels.
Collapse M_AVERAGE_WORLD_ERROR +

Inquires the average calibration error in the absolute coordinate system.

This is the average distance in the absolute coordinate system between the initial calibration points and their projected points in an image.

(summarize)
Collapse Value

Specifies the average calibration error, in world units.
Collapse M_CALIBRATION_IMAGE_POINTS_X +

Inquires the X-coordinate of the calibration points in the pixel coordinate system. SET

(summarize)
Collapse UserVarPtr data type info

Data type: array of type MIL_DOUBLE
Array size: The return value of McalInquireSingle() with M_NUMBER_OF_CALIBRATION_POINTS.

Collapse Value

Specifies the X-coordinate, in pixels.
Collapse M_CALIBRATION_IMAGE_POINTS_Y +

Inquires the Y-coordinate of the calibration points in the pixel coordinate system. SET

(summarize)
Collapse UserVarPtr data type info

Data type: array of type MIL_DOUBLE
Array size: The return value of McalInquireSingle() with M_NUMBER_OF_CALIBRATION_POINTS.

Collapse Value

Specifies the Y-coordinate, in pixels.
Collapse M_CALIBRATION_WORLD_POINTS_X +

Inquires the X-coordinate of the calibration points, in real-world units of the camera calibration plane (M_CALIBRATION_PLANE). SET

(summarize)
Collapse UserVarPtr data type info

Data type: array of type MIL_DOUBLE
Array size: The return value of McalInquireSingle() with M_NUMBER_OF_CALIBRATION_POINTS.

Collapse Value

Specifies the X-coordinate, in real-world units of the camera calibration plane (M_CALIBRATION_PLANE).
Collapse M_CALIBRATION_WORLD_POINTS_Y +

Inquires the Y-coordinate of the calibration points, in real-world units of the camera calibration plane (M_CALIBRATION_PLANE). SET

(summarize)
Collapse UserVarPtr data type info

Data type: array of type MIL_DOUBLE
Array size: The return value of McalInquireSingle() with M_NUMBER_OF_CALIBRATION_POINTS.

Collapse Value

Specifies the Y-coordinate, in real-world units of the camera calibration plane (M_CALIBRATION_PLANE).
Collapse M_CALIBRATION_WORLD_POINTS_Z +

Inquires the Z-coordinate of the calibration points, in real-world units of the camera calibration plane (M_CALIBRATION_PLANE). If this value is inquired for 2D-based calibration contexts, the specified array will be filled with 0.0 values. SET

(summarize)
Collapse UserVarPtr data type info

Data type: array of type MIL_DOUBLE
Array size: The return value of McalInquireSingle() with M_NUMBER_OF_CALIBRATION_POINTS.

Collapse Value

Specifies the Z-coordinate, in real-world units of the camera calibration plane (M_CALIBRATION_PLANE).
Collapse M_MAXIMUM_PIXEL_ERROR +

Inquires the maximum calibration error, in pixels.

(summarize)
Collapse Value

Specifies the maximum calibration error, in pixels.
Collapse M_MAXIMUM_WORLD_ERROR +

Inquires the maximum calibration error, in world units.

(summarize)
Collapse Value

Specifies the maximum calibration error, in world units.
Collapse M_NUMBER_OF_CALIBRATION_POINTS +

Inquires the number of calibration points found by McalGrid() or passed to McalList().

If you used McalList() to calibrate your camera setup, you can explicitly set the number of calibration points with the NumPoint parameter.

If you used McalGrid() to calibrate your camera setup, the number of calibration points is determined by the number of columns and rows in your grid. SET

(summarize)
Collapse Value

Specifies the number of calibration points.

The InquireType parameter can be set to one of the following values after a call to either McalGrid(), McalList(), or McalUniform().

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_DOUBLE.

function map For a calibration context being calibrated using McalGrid(), McalList(), or McalUniform()
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_CALIBRATION_INPUT_DATA +

Specifies the type of data that was used to perform the calibration.

(summarize)
Collapse M_GRID

Specifies that the calibration was performed using a calibration grid (McalGrid()).
Collapse M_LIST

Specifies that the calibration was performed by explicitly specifying the correspondence between some pixels and their real-world coordinates (McalList()).
Collapse M_PARAMETRIC

Specifies that the calibration was performed using an explicitly specified translation, scale, and offset from the absolute world coordinate system (McalUniform()).

You can add one of the following values to the above-mentioned values to cast the requested information to the required data type.

function map For specifying the data type
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_TYPE_CHAR

Casts the requested information to a char.

(summarize)
Collapse UserVarPtr data type info

Data type: char

Collapse M_TYPE_MIL_DOUBLE

Casts the requested information to a MIL_DOUBLE.

(summarize)
Collapse UserVarPtr data type info

  • Data type: array of type MIL_DOUBLE
    Array size: Depends on the result type.
    Note: When multiple results.

  • Data type: MIL_DOUBLE
    Note: When a single result.
Collapse M_TYPE_MIL_FLOAT

Casts the requested information to a MIL_FLOAT.

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_FLOAT

Collapse M_TYPE_MIL_ID

Casts the requested information to a MIL_ID.

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_ID

Collapse M_TYPE_MIL_INT

Casts the requested information to a MIL_INT.

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_INT

Collapse M_TYPE_MIL_INT16

Casts the requested results to a MIL_INT16.

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_INT16

Collapse M_TYPE_MIL_INT32

Casts the requested information to a MIL_INT32.

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_INT32

Collapse M_TYPE_MIL_INT64

Casts the requested information to a MIL_INT64.

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_INT64

Return value
The returned value is the requested information, cast to a MIL_INT. If the requested information is not a single value, or cannot be cast to a MIL_INT, this function will return M_NULL.
Compilation information
Header Include mil.h.
Library Use mil.lib; milcal.lib.
DLL Requires mil.dll; milcal.dll.
3D ROBOTICS COLUMN NUMBER COLUMN SPACING GRID ORIGIN X GRID ORIGIN Y GRID ORIGIN Z GRID TYPE CHESSBOARD GRID CIRCLE GRID ROW NUMBER ROW SPACING DEFAULT AVERAGE PIXEL ERROR AVERAGE WORLD ERROR CALIBRATION IMAGE POINTS X CALIBRATION IMAGE POINTS Y CALIBRATION WORLD POINTS X CALIBRATION WORLD POINTS Y CALIBRATION WORLD POINTS Z MAXIMUM PIXEL ERROR MAXIMUM WORLD ERROR NUMBER OF CALIBRATION POINTS CALIBRATION INPUT DATA GRID LIST PARAMETRIC TYPE CHAR TYPE MIL DOUBLE TYPE MIL FLOAT TYPE MIL ID TYPE MIL INT TYPE MIL INT16 TYPE MIL INT32 TYPE MIL INT64 GRID LIST PARAMETRIC