# 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 $A$0, which contains the image data structure returned by AcquireImage.
Fixture | Defines the Region of Interest (ROI) relative to a Fixture input or the output of a Vision Tools function's image coordinate system. Setting the ROI relative to a Fixture ensures that if the Fixture is rotated or translated, the ROI will be rotated or translated in relation to the Fixture.
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; creates an Interactive Graphics Mode that can be transformed and rotated. With this parameter selected, by pressing the Maximize Region button on the property sheet's Job Edit toolbar, the region will automatically be stretched 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 region's x-axis.
Height | The dimension along the region's y-axis.
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.