McalInquireSingle

Filters
See also

User Guide:

Inquiring about your camera calibration

Reference:

McalAlloc McalControl McalGrid McalInquire McalList

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/GPm

Available on Matrox Supersight

Function map

Examples

cameraonrobotarmcalibration.cpp

Function Map

- Index

Parameter Associations

Table:	For a camera calibration context being calibrated using McalGrid()
+ combination:	For getting the string size
Table:	For a camera calibration context being calibrated using McalGrid() or McalList()
+ combination:	For specifying the data type

Return value

Compilation information

Synopsis

Inquire about a single pose in a sequence of poses taken during camera 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 camera 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 camera 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 camera calibration context.

Index

Specifies the index of the pose of a M_3D_ROBOTICS camera 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
array of type MIL_TEXT_CHAR
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 the McalInquireSingle() function also returns the requested information, you can set this parameter 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.

For a camera calibration context being calibrated using McalGrid()
For a camera calibration context being calibrated using McalGrid() or McalList()

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

For a camera calibration context being calibrated using McalGrid()
InquireType		Description
	UserVarPtr - Possible values returned	Description
M_COLUMN_NUMBER +		Inquires the number of columns in the camera calibration grid. SET (summarize) Inquires the number of columns in the camera calibration grid. SET (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE
	Value >= 2	Specifies the number of columns.
M_COLUMN_SPACING +		Inquires the number of world units between columns. SET (summarize) Inquires the number of world units between columns. SET (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE
	Value > 0.0	Specifies the spacing between columns.
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) 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 (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE
	Value	Specifies the X-position, in the camera calibration plane coordinate system.
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) 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 (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE
	Value	Specifies the Y-position, in the camera calibration plane coordinate system.
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) 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 (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE
	Value	Specifies the Z-position, in the camera calibration plane coordinate system.
M_GRID_TYPE +		Inquires the type of grid used to perform the camera calibration. SET (summarize) Inquires the type of grid used to perform the camera calibration. SET (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE
	M_CHESSBOARD_GRID	Specifies a chessboard grid. INFO
	M_CIRCLE_GRID	Specifies a grid of circles. INFO
M_GRID_UNIT_SHORT_NAME +		Inquires the units returned by M_GRID_UNITS. You can find the particular abbreviation for each unit in the description of M_GRID_UNITS. (summarize) Inquires the units returned by M_GRID_UNITS. (more details...)
	UserVarPtr extra info	Data type info: Data type: array of type MIL_TEXT_CHAR (more details...) Data type: array of type MIL_TEXT_CHAR Required array size:(McalInquireSingle() with M_GRID_UNIT_SHORT_NAME + M_STRING_SIZE) Note: You can also use M_GRID_UNIT_SHORT_NAME_MAX_SIZE as the array size. Data type info: Data type: array of type MIL_TEXT_CHAR (more details...) Data type: array of type MIL_TEXT_CHAR Required array size:(McalInquireSingle() with M_GRID_UNIT_SHORT_NAME + M_STRING_SIZE) Note: You can also use M_GRID_UNIT_SHORT_NAME_MAX_SIZE as the array size.
M_GRID_UNITS +		Inquires the units of measurement encoded in a chessboard grid with a fiducial. Note that this information is not used by the calibration module. No unit consistency is enforced and no unit conversion is performed. (summarize) Inquires the units of measurement encoded in a chessboard grid with a fiducial. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE
	M_CENTIMETERS	Specifies that the grid units are measured in centimeters.
	M_FEET	Specifies that the grid units are measured in feet.
	M_INCHES	Specifies that the grid units are measured in inches.
	M_KILOMETERS	Specifies that the grid units are measured in kilometers.
	M_METERS	Specifies that the grid units are measured in meters.
	M_MICROMETERS	Specifies that the grid units are measured in micrometers.
	M_MILES	Specifies that the grid units are measured in miles.
	M_MILLIMETERS	Specifies that the grid units are measured in millimeters.
	M_MILS	Specifies that the grid units are measured in mils.
	M_UNKNOWN	Specifies that grid units are measured in an unknown unit. INFO
M_ROW_NUMBER +		Inquires the number of rows in the camera calibration grid. SET (summarize) Inquires the number of rows in the camera calibration grid. SET (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE
	Value >= 2	Specifies the number of rows.
M_ROW_SPACING +		Inquires the spacing between rows in the camera calibration grid. SET (summarize) Inquires the spacing between rows in the camera calibration grid. SET (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE
	Value > 0.0	Specifies the spacing between rows, in world units.

Combination value for M_GRID_UNIT_SHORT_NAME.

You can add the following value to the above-mentioned value to get the string's length.

For getting the string size
Combination value	Description
M_STRING_SIZE	Retrieves the length of the string, including the terminating null character ("\0").

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

For a camera calibration context being calibrated using McalGrid() or McalList()
InquireType		Description
	UserVarPtr - Possible values returned	Description
M_AVERAGE_PIXEL_ERROR +		Inquires the average camera 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) Inquires the average camera calibration error in the pixel coordinate system. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE
	Value >= 0.0	Specifies the average camera calibration error, in pixels.
M_AVERAGE_WORLD_ERROR +		Inquires the average camera 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) Inquires the average camera calibration error in the absolute coordinate system. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE
	Value >= 0.0	Specifies the average camera calibration error, in world units.
M_CALIBRATION_IMAGE_POINTS_X +		Inquires the X-pixel coordinate of the calibration points. If you used McalGrid() to calibrate your camera setup, the calibration points' pixel coordinates are determined by the pixel positions of the centers of the circles in a circle grid or the intersections of four squares/rectangles in a chessboard grid. If you used McalList() to calibrate your camera setup, you explicitly set the calibration points' pixel coordinates with the PixCoordXArrayPtr parameter. SET (summarize) Inquires the X-pixel coordinate of the calibration points. SET (more details...)
	UserVarPtr extra info	Data type info: Data type: array of type MIL_DOUBLE (more details...) Data type: array of type MIL_DOUBLE Required array size: McalInquireSingle() with M_NUMBER_OF_CALIBRATION_POINTS Data type info: Data type: array of type MIL_DOUBLE (more details...) Data type: array of type MIL_DOUBLE Required array size: McalInquireSingle() with M_NUMBER_OF_CALIBRATION_POINTS
	Value	Specifies the X-coordinate, in pixels.
M_CALIBRATION_IMAGE_POINTS_Y +		Inquires the Y-pixel coordinate of the calibration points. If you used McalGrid() to calibrate your camera setup, the calibration points' pixel coordinates are determined by the pixel positions of the centers of the circles in a circle grid or the intersections of four squares/rectangles in a chessboard grid. If you used McalList() to calibrate your camera setup, you explicitly set the calibration points' pixel coordinates with the PixCoordYArrayPtr parameter. SET (summarize) Inquires the Y-pixel coordinate of the calibration points. SET (more details...)
	UserVarPtr extra info	Data type info: Data type: array of type MIL_DOUBLE (more details...) Data type: array of type MIL_DOUBLE Required array size: McalInquireSingle() with M_NUMBER_OF_CALIBRATION_POINTS Data type info: Data type: array of type MIL_DOUBLE (more details...) Data type: array of type MIL_DOUBLE Required array size: McalInquireSingle() with M_NUMBER_OF_CALIBRATION_POINTS
	Value	Specifies the Y-coordinate, in pixels.
M_CALIBRATION_INPUT_DATA +		Specifies the type of data that was used to perform the camera calibration. (summarize) Specifies the type of data that was used to perform the camera calibration. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE
	M_GRID	Specifies that the camera calibration was performed using a camera calibration grid (McalGrid()).
	M_LIST	Specifies that the camera calibration was performed by explicitly specifying the correspondence between some pixels and their real-world coordinates (McalList()).
M_CALIBRATION_WORLD_POINTS_X +		Inquires the X-world coordinate of the calibration points that are computed based on explicitly specified values. The coordinate is expressed in world units of the camera calibration plane (M_CALIBRATION_PLANE). If you used McalList() to calibrate your camera setup, you explicitly set the calibration points' world coordinates with the WorldCoordXArrayPtr parameter. If you used McalGrid() to calibrate your camera setup, the calibration points are computed from the parameters GridOffsetX, ColumnNumber, and ColumnSpacing. SET (summarize) Inquires the X-world coordinate of the calibration points that are computed based on explicitly specified values. SET (more details...)
	UserVarPtr extra info	Data type info: Data type: array of type MIL_DOUBLE (more details...) Data type: array of type MIL_DOUBLE Required array size: McalInquireSingle() with M_NUMBER_OF_CALIBRATION_POINTS Data type info: Data type: array of type MIL_DOUBLE (more details...) Data type: array of type MIL_DOUBLE Required array size: McalInquireSingle() with M_NUMBER_OF_CALIBRATION_POINTS
	Value	Specifies the X-coordinate, in real-world units of the camera calibration plane (M_CALIBRATION_PLANE).
M_CALIBRATION_WORLD_POINTS_Y +		Inquires the Y-world coordinate of the calibration points that are computed based on explicitly specified values. The coordinate is expressed in world units of the camera calibration plane (M_CALIBRATION_PLANE). If you used McalList() to calibrate your camera setup, you explicitly set the calibration points' world coordinates with the WorldCoordYArrayPtr parameter. If you used McalGrid() to calibrate your camera setup, the calibration points are computed from the parameters GridOffsetY, RowNumber, and RowSpacing. SET (summarize) Inquires the Y-world coordinate of the calibration points that are computed based on explicitly specified values. SET (more details...)
	UserVarPtr extra info	Data type info: Data type: array of type MIL_DOUBLE (more details...) Data type: array of type MIL_DOUBLE Required array size: McalInquireSingle() with M_NUMBER_OF_CALIBRATION_POINTS Data type info: Data type: array of type MIL_DOUBLE (more details...) Data type: array of type MIL_DOUBLE Required array size: McalInquireSingle() with M_NUMBER_OF_CALIBRATION_POINTS
	Value	Specifies the Y-coordinate, in real-world units of the camera calibration plane (M_CALIBRATION_PLANE).
M_CALIBRATION_WORLD_POINTS_Z +		Inquires the Z-world coordinate of the calibration points that are based on explicitly specified values. The computed calibration points are expressed in world units of the camera calibration plane (M_CALIBRATION_PLANE). If this value is inquired for 2D-based camera calibration contexts, the specified array will be filled with 0.0 values. If you used McalList() to calibrate your camera setup, you explicitly set the calibration points' pixel coordinates with the WorldCoordZArrayPtr parameter. If you used McalGrid() to calibrate your camera setup, you explicitly set the Z-coordinate of all the calibration points with the GridOffsetZ parameter. SET (summarize) Inquires the Z-world coordinate of the calibration points that are based on explicitly specified values. SET (more details...)
	UserVarPtr extra info	Data type info: Data type: array of type MIL_DOUBLE (more details...) Data type: array of type MIL_DOUBLE Required array size: McalInquireSingle() with M_NUMBER_OF_CALIBRATION_POINTS Data type info: Data type: array of type MIL_DOUBLE (more details...) Data type: array of type MIL_DOUBLE Required array size: McalInquireSingle() with M_NUMBER_OF_CALIBRATION_POINTS
	Value	Specifies the Z-coordinate, in real-world units of the camera calibration plane (M_CALIBRATION_PLANE).
M_MAXIMUM_PIXEL_ERROR +		Inquires the maximum camera calibration error, in pixels. (summarize) Inquires the maximum camera calibration error, in pixels. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE
	Value >= 0.0	Specifies the maximum camera calibration error, in pixels.
M_MAXIMUM_WORLD_ERROR +		Inquires the maximum camera calibration error, in world units. (summarize) Inquires the maximum camera calibration error, in world units. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE
	Value >= 0.0	Specifies the maximum camera calibration error, in world units.
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) Inquires the number of calibration points found by McalGrid() or passed to McalList(). SET (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE Data type info: Data type: address of a MIL_DOUBLE
	Value >= 0	Specifies the number of calibration points.

Combination values for the values listed in For a camera calibration context being calibrated using McalGrid() or McalList(); and for the following values: M_COLUMN_NUMBER; M_COLUMN_SPACING; M_GRID_ORIGIN_X; M_GRID_ORIGIN_Y; M_GRID_ORIGIN_Z; M_GRID_TYPE; M_GRID_UNITS; M_ROW_NUMBER; M_ROW_SPACING.

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

For specifying the data type
InquireType		Description
	UserVarPtr - Possible values returned	Description
M_TYPE_CHAR		Casts the requested information to a char. (summarize) Casts the requested information to a char. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a char Data type info: Data type: address of a char
M_TYPE_MIL_DOUBLE		Casts the requested information to a MIL_DOUBLE. (summarize) Casts the requested information to a MIL_DOUBLE. (more details...)
	UserVarPtr extra info	Data type info: Data type: array of type MIL_DOUBLE \| address of a MIL_DOUBLE (more details...) Data type: array of type MIL_DOUBLE Required array size:(defined elsewhere) Note: When multiple results. Data type: address of a MIL_DOUBLE Note: When a single result. Data type info: Data type: array of type MIL_DOUBLE \| address of a MIL_DOUBLE (more details...) Data type: array of type MIL_DOUBLE Required array size:(defined elsewhere) Note: When multiple results. Data type: address of a MIL_DOUBLE Note: When a single result.
M_TYPE_MIL_FLOAT		Casts the requested information to a MIL_FLOAT. (summarize) Casts the requested information to a MIL_FLOAT. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_FLOAT Data type info: Data type: address of a MIL_FLOAT
M_TYPE_MIL_ID		Casts the requested information to a MIL_ID. (summarize) Casts the requested information to a MIL_ID. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_ID Data type info: Data type: address of a MIL_ID
M_TYPE_MIL_INT		Casts the requested information to a MIL_INT. (summarize) Casts the requested information to a MIL_INT. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT
M_TYPE_MIL_INT16		Casts the requested results to a MIL_INT16. (summarize) Casts the requested results to a MIL_INT16. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_INT16 Data type info: Data type: address of a MIL_INT16
M_TYPE_MIL_INT32		Casts the requested information to a MIL_INT32. (summarize) Casts the requested information to a MIL_INT32. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_INT32 Data type info: Data type: address of a MIL_INT32
M_TYPE_MIL_INT64		Casts the requested information to a MIL_INT64. (summarize) Casts the requested information to a MIL_INT64. (more details...)
	UserVarPtr extra info	Data type info: Data type: address of a MIL_INT64 Data type info: Data type: address of a MIL_INT64

Return value

The returned value is the requested information, cast to a MIL_INT. If the requested information does not fit into a MIL_INT, this function will return M_NULL or truncate the information.

Compilation information

Header	Include mil.h.
Library	Use mil.lib; milcal.lib.
DLL	Requires mil.dll; milcal.dll.