imaqLearnCalibrationPoints

NI Vision for LabWindows/CVI Function

imaqLearnCalibrationPoints

Usage

int imaqLearnCalibrationPoints(Image* image, const CalibrationPoints* points, const ROI* roi, const LearnCalibrationOptions* options, const GridDescriptor* grid, const CoordinateSystem* system, float* quality);

Purpose

Learns a calibration from a set of pixel coordinates and corresponding real-world coordinates. After removing coordinates outside the optional region of interest (ROI), the function requires at least four pixel coordinates and four real-world coordinates to successfully learn the calibration information.

Image Types Supported

IMAQ_IMAGE_U8, IMAQ_IMAGE_I16, IMAQ_IMAGE_SGL, IMAQ_IMAGE_RGB, IMAQ_IMAGE_HSL

Parameters

Name

Type

Description

image Image* The image to which the function attaches calibration information.
points const CalibrationPoints* The set of reference points the function uses to learn the calibration information. This parameter is required and cannot be NULL.
roi const ROI* Determines which pixel coordinates the function uses in the learning process. The function ignores all pixel coordinates that are outside the defined region when estimating the calibration transformation. To learn all of the pixel coordinates, set this parameter to NULL.
options const LearnCalibrationOptions* Describes how the function learns the calibration information.
grid const GridDescriptor* Contains scaling constants for the real-world coordinates that the function uses to learn the calibration.
system const CoordinateSystem* Defines the coordinate system for real-world coordinates.
quality float* On return, the quality score of the learning process, which is a value between 0-1000. A quality of 1000 means that the function learned the feature points perfectly with the chosen algorithm. It does not necessarily reflect the absolute accuracy of the estimated calibration mapping, but instead reflects how well the calibration mapping adapts to the learned points. Set this parameter to NULL if you do not need this information.

Return Value

Type

Description

int On success, this function returns a non-zero value. On failure, this function returns 0. To get extended error information, call imaqGetLastError().

Parameter Discussion

options—Set options to NULL to use the default options, as follows:

mode IMAQ_PERSPECTIVE
method IMAQ_SCALE_TO_FEATURES
roi IMAQ_USER_ROI
learnMap FALSE
learnTable FALSE

grid—Set grid to NULL to use the following default scaling constants:

xStep 1
yStep 1
unit IMAQ_UNDEFINED

system—Set system to NULL to use the following default coordinate system:

origin The function places the origin at the point with a x-coordinate equal to the lowest x-coordinate value in the point list.
angle 0
axisOrientation IMAQ_INDIRECT