# ExtractCalibrationPoints

The ExtractCalibrationPoints function extracts calibration points from an image of a checkerboard calibration grid pattern. The calibration points can be used by other calibrate tools.

## ExtractCalibrationPoints Overview

A calibration image, a checkerboard grid with a fiducial and known scale, is used to train the ExtractCalibrationPoints function. During analysis, it finds the pixel locations of the intersections of the grid cells, and then maps them back onto a model of the grid pattern. The function returns a CalibPoints data structure along with the number of points found within the grid. The set of calibration points can later be used by other calibrate tools, such as CalibratePoints, to correct for distortion, to map image coordinates to real-world coordinates or vice versa.

Note: Use a checkerboard calibration grid with fiducial marks. Calibration using a grid of dots or grids without fiducial is not be supported at this time.

## ExtractCalibrationPoints Inputs

Parameter | Description
--- | ---
Image | This argument must reference a spreadsheet cell that contains a valid Image data structure. By default, the cell referenced is cell A1, containing the Image data structure.
Fixture | Defines the Region of Interest (ROI) relative to a Fixture input or the output of the image coordinate system for the Vision Tools function. Setting the ROI relative to a Fixture ensures that if the Fixture is rotated or translated, the ROI is rotated or translated in relation to the Fixture. Note: 2D projections use real world units but fixturing with 2D tools requires input in pixel values. When using a 2D projection from a 3D point cloud as a Fixture, convert the real world units to pixel values using the TransWorldToPixel function.
X | The X-offset, in image coordinates.
Y | The Y-offset, in image coordinates.
Region | Also known as the Region of Interest (ROI), specifies the region of the image that undergoes analysis. Double-click on the Region parameter to create an Interactive Graphics Mode that you can transform and rotate. Select this parameter and press the Maximize Region button on the Job Edit toolbar of the property sheet to automatically stretch the region to cover the entire image.
X | The X-offset of the origin, in fixture coordinates.
Y | The Y-offset of the origin, in fixture coordinates.
Width | The dimension along the X-axis of the region.
Height | The dimension along the Y-axis of the region.
Extract Event | Press to extract calibration points from the image.
Grid Spacing Units | Specifies the unit of measurement used for the calibration grid pattern's spacing.
Microns = 0 | "µm"
Millimeters = 1 (Default) | "mm"
Centimeters = 2 | "cm"
Inches = 3 | "in"
X Grid Spacing | The actual measurement of the calibration grid pattern spacing along the x-axis.
Y Grid Spacing | The actual measurement of the calibration grid pattern spacing along the x-axis.
Angle Range | Select to enable the Find Tolerances parameter and restrict the angle range used to search for the grid. (Default = 0, unchecked) Tip: Restricting angle range may speed up point extraction when the relative orientation between grid and camera is well known.
Find Tolerances | The start and stop angle range used to search for the grid.
Angle Start | Minimum possible angle between the grid horizontal axis and the camera horizontal axis. (Min = -180, Max= 180, Default = -180)
Angle End | Maximum possible angle between the grid horizontal axis and the camera horizontal axis. (Min = -180, Max= 180, Default = +180)
Note: By default the angle range is not restricted. The Angle Range checkbox must be checked in order to enable restricting the angle start and end range set within the Find Tolerances parameter.
Timeout | Specifies a length of time (milliseconds) to allow the ExtractCalibrationPoints function to run. Function execution stops when the time out has been exceeded. (Minimum = 0, Maximum = 9999999, Default = 120000) Note: Timeout is used to as a fail safe to cause potentially very long running processes to terminate once the timeout has been exceeded. Timeout is not exact as execution may run a few seconds over the specified time.
Show | Specifies the display mode for ExtractCalibrationPoints graphical overlays on top of the image.
0 = hide all (default) | All graphics will be hidden, except when the cell containing the ExtractCalibrationPointsfunction is highlighted in the spreadsheet.
1 = result graphics only | Display extracted point locations overlayed on the input image
2 = input and results graphics | Display extracted point locations and the search region.

## ExtractCalibrationPoints Outputs

Returns | A CalibPoints data structure, or #ERR if any of the input parameters are invalid. The following Calibrate Vision Data Access functions are automatically inserted into the spreadsheet to create the result table:
Lable | Function | Description
Points | GetNFound() | Returns the number of points found in the calibration grid image.