# CalibrateGrid

Utilizing a user-configurable calibration grid pattern, CalibrateGrid creates a 2D transformation to convert between pixel and real-world coordinate systems. CalibrateGrid also accounts for linear, non-linear and lens distortion.

## About CalibrateGrid

CalibrateGrid computes a 2D transformation between the set of points identified by the vertices of a checkerboard calibration grid pattern. During analysis, CalibrateGrid finds the pixel locations of the grid cell intersections, and then maps them back onto a model of the grid pattern.

In addition, CalibrateGrid uses a reference to a set of calibration points and a lens distortion model to compute a transformation mapping between image and real-world coordinates.

Note: To view or use vision tools on the undistorted image, use the TransformImage function.

You can configure the following with the CalibrateGrid:

- The type of calibration grid pattern to be used.
- The spacing of the calibration grid pattern.
- The type of real-world, physical measurement units.

Optionally, you can print a calibration plate grid. For more information, see Printing the Calibration Pattern Using the Print Grid Dialog. Once the image is acquired, CalibrateGrid automatically identifies as many feature points as possible. As soon as you press the Calibration button, CalibrateGrid begins to compute the calibration and reports a calibration point based on the spacing of the feature points.

After the calibration is performed, the CalibrateGrid cell stores the calibration data. This allows you to copy the CalibrateGrid function from one job and paste to another, or export and import as an external file using Export Cell/Import Cell. It is possible to have a different calibration for each job, as well as multiple calibrations in a single job, if necessary. Other functions that use Calibrate functions as arguments can reference the CalibrateGrid data structure.

Note: When using the Calibrate function, the physical and optical setup (the lens, sensor and the physical relationship between the sensor and the scene) must be the same for both the calibration and run-time operation. If you alter any of these items, you have to recalibrate the system. It is recommended that you use the same sensor and lens for both calibration and processing the run-time images. The sensor and lens must also retain their original setup and calibration settings. For example, altering the resolution or moving the sensor invalidates the computed 2D transformation that maps pixel to real-world coordinates.
Input

Parameter | Description
--- | ---
Image | This argument must reference a spreadsheet cell that contains a valid Image data structure. By default, the cell references , containing the Image data structure returned by the AcquireImage function.
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. The default setting is (0,0,0), the top leftmost corner of the image.
X (default = 0) | The X-offset, in image coordinates.
Y (default = 0) | The Y-offset, in image coordinates.
Theta (default = 0) | The rotation from the image X-axis, in the image coordinate system. (+/-360 degrees clockwise)
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.
Grid Type | Specifies the type of calibration pattern that is used to construct the calibration: Checkerboard, with fiducial Checkerboard, no fiducial
Checkerboard, with fiducial | Tile vertices (the point where the corners of four tiles meet) are used to determine the feature location. Vertices can be accurately located when the sensor is up to 45 degrees perpendicular to the surface; provides a fiducial marker to determine the origin of the grid, and identify the orientation of the grid in real-world space. Note: Checkerboard checks must be at least 15 pixels wide.
Checkerboard, no fiducial | Tile vertices (the point where the corners of four tiles meet) are used to determine the feature location; vertices can be accurately located when the sensor is up to 45 degrees perpendicular to the surface; the origin must be set using the Grid Origin. Note: Checkerboard checks must be at least 15 pixels wide.
Grid Origin | Specifies the origin point of the grid.
Center | If you select Checkerboard, with fiducial, CalibrateGrid determines the origin point automatically, the nearest to the center of the Region. If you select Checkerboard, no fiducial, you are allowed to check out the checkbox at the Center button. If you check out the checkbox, you can determine the Grid Origin manually. If you manually specify the Grid Origin, the origin point becomes the vertex closest to the point you specified.
X | Specifies the X location of the origin in pixel coordinates. If you use Checkerboard, with fiducial, the X-axis is determined automatically. If you use Checkerboard, no fiducial, the X-axis increases towards the right of the grid.
Y | Specifies the Y location of the origin in pixel coordinates. If you use Checkerboard, with fiducial, the Y-axis is determined automatically. If you use Checkerboard, no fiducial, the Y-axis increases towards the bottom of the grid.
Note: The Grid Origin parameters are only editable when you choose the Checkerboard, no fiducial for the Grid Type. If you chose Checkerboard, no fiducial, it allows you to manually pick one of the points to be the origin.
Calibrate | CalibrateGrid event trigger.
Grid Spacing Units | Specifies the real-world measurement units that the calibration is based upon. The default unit is millimeters. You can choose from the following units: Microns Millimeters Centimeters Inches
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 Y-axis.
Angle Range | 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. The minimum value is -180, the maximum value is 180. The default value is -180.
Angle End | Maximum possible angle between the grid horizontal axis and the camera horizontal axis. The minimum value is -180, the maximum value is 180. The default value is +180.
Tip: Restricting angle range can speed up point extraction when the relative orientation between grid and camera is well known.
Find Tolerances | Check the Angle Range parameter to enable the Find Tolerances parameter and restrict the angle range used to search for the grid. The default setting is unchecked.
Lens Distortion | The linear or non-linear lens distortion model to use in mapping real-world to image coordinates.
0 = No lens distortion | Only account for perspective distortion.
1 = Center radial distortion | Account for minor radial distortion that originates from the center of the image.
2 = Off-center radial distortion | Account for radial distortion originating from areas other than the center of the image.
3 = Projection distortion | Account for distortion caused by fish-eye and wide-angle lenses
4 = Broad distortion | Account for lens distortion ranging from minor to sever.
Timeout | Specifies a length of time in milliseconds to allow the CalibrateGrid function to run. Function execution stops when the time out has been exceeded. The minimum value is 0, the maximum is 9999999. The default value is 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 CalibrateGrid graphical overlays on top of the image.
0 = hide all (default) | All graphics are hidden, except when the cell containing the CalibrateGridfunction 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.

Outputs

Returns | A Calib data structure containing the coefficients that define the transformation between the two coordinate systems.

CalibrateGrid Workflow with Checkerboard, with Fiducial:

1. Drag and drop the CalibrateGrid tool to your Spreadsheet.

   The property sheet appears.

2. Specify the Region of Interest (ROI) by double-clicking the Region parameter. Select the region by dragging the red lines of the ROI. When finished, press enter or click the Accept Changes.

3. Specify the Grid Type. In this case, the checkerboard with fiducial is chosen.
4. Specify the Grid Units, which are the real-world measurement units that the real-world coordinates are based upon.

5. Click Calibrate to trigger the calibration.

   When the calibration is finished, the calibrated points appear inside the ROI.

6. Click OK. You receive a Calib data structure.

CalibrateGrid Workflow with Checkerboard, no Fiducial:

1. Drag and drop the CalibrateGrid tool to your Spreadsheet.

   The property sheet appears.

2. Specify the Region of Interest (ROI) by double-clicking the Region parameter. Select the region by dragging the red lines of the ROI. When finished, press Enter or click the Accept Changes.

3. Specify the Grid Type. In this case, the checkerboard, no fiducial is chosen.

4. Decide whether you want to manually determine the Grid Origin.

   - If you do not want to manually determine the origin point, leave the checkbox checked in at the Center checkbox.

   - If you want to manually determine the origin point, uncheck the Center checkbox. Double-click the X button and drag the origin point where you want to be. Press Enter, when finished.

5. Click Calibrate to trigger the calibration.

   When the calibration is finished, the calibrated points appear inside the ROI.

6. Click OK. You receive a Calib data structure.