# Calibrate

Utilizing up to 32 user-specified point pairs, Calibrate creates a 2D transformation to convert between pixel and real-world coordinate systems.

## About Calibrate

The Calibrate function Functions are tools that are available in Spreadsheet for processing and analyzing acquisitions or other results. You can add functions to your Spreadsheet job to create tool chains and produce results for specific applications. requires user-specified points, expressed in two different coordinate systems:

- The real-world physical coordinate system of the object

- The pixel coordinates of the object image

To extract features from an image, Calibrate requires 2D Vision Tools. The Calibrate function enters the location of the features as both real-world and pixel coordinates. Calibrate allows from one to thirty-two pixel and real-world coordinate pairs.

During the calibration phase, the function acquires an image that contains features with known locations in real-world coordinates. To locate and report features of an image in pixel coordinates, the function uses vision tools such as FindPatMaxRedLine or FindLine.

Note: The origin of the pixel coordinates is always the upper-left corner of the upper-left pixel.

Next, both the pixel and real-world coordinates are entered as arguments. For the pixel coordinates, a cell reference to the Row and Column values of a vision tool can be used, while a numeric value can be entered to express the real-world coordinates. Then the tool computes the 2D transformation between the real-world and pixel coordinates, producing a Calib structure that represents the transformation.

Note:

- Calibrate does not have a property sheet, it is based on one to thirty-two variable arguments expressed by the number of point pairs. For instance, if you insert a Calibrate function to the spreadsheet, and use an ExtractBlobs function that reported five different blobs to calibrate the system, the pixel coordinates are expressed as cell references to the reported Row and Column values of the ExtractBlobs tool. Then, the world coordinates have to be set according to the specific real-world value, resulting in the following formula: Calibrate($D$11,$D$12,0,0,$E$11,$E$12,2,0,$F$11,$F$12,2,2,$G$11,$G$12,0,2,$H$11,$H$12,1,2).

- The maximum string length allowed in a cell is 255 characters. If you use more than 255 characters to specify the variable arguments, an error message displays. When a string used to specify the variables arguments exceeds the 255 character limits, use a cell range. You can also include real-world coordinates in a cell range by entering the X and the Y values directly into the cells. For example, when specifying thirty-two point pairs using a cell range, you can use the following formula: Calibrate(C11:F42).

You can also use Calibrate for the following transformations:

- Translation in two dimensions (using one or more point pairs)
- Rotation about three axes (using four or more point pairs)
- Scale in two dimensions (using two or more point pairs)
- Perspective distortion (using four or more point pairs)
- Parallelogramming or skewing (using four or more point pairs)

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 set-up and calibration settings. For example, altering the resolution or moving the sensor invalidates the computed 2D transformation that maps pixel to real-world coordinates.

Inputs

Syntax: Calibrate(Pixel Point 0.Row,Pixel Point 0.Column,World Point 0.X,World Point 0.Y,...,Pixel Point 31.Row,Pixel Point 31.Column,World Point 31.X,World Point 31.Y)

Input | Description
--- | ---
Pixel Point 0 to N | Specifies the pixel coordinates of a pixel-to-world association.
X | The image X-coordinate.
Y | The image Y-coordinate.
World Point 0 to N | Specifies the real-world coordinates of a pixel-to-world association (-16777216 to 16777216).
X | The X-axis coordinate, as a world value.
Y | The Y-axis coordinate, as a world value.

Outputs

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