Using N-Point CalibrationCognex VisionPro

This topic contains the following sections.

In a vision application, you often want to relate measurements and locations of objects in an acquired image to meaningful, real-world values. You do so by calibrating your vision system. Calibration is a process that calculates a 2D transformation that maps image coordinates to real-world coordinates and that attaches the calculated transform to an input image. This process applies to the entire camera image or world view, eliminating camera aspect ratio and lens distortion.

In VisionPro, you can calibrate your system using the CogCalibNPointToNPointTool. This tool accepts two sets of N points, one specified in uncalibrated space and the other specified in raw calibrated space, and an optional origin adjustment for the final calibrated space. At train-time, the tool determines a best-fit, 2D transformation that maps pixels in an input image (uncalibrated space points) to real-world physical measurements (raw calibrated space points). The transform is calculated once at tool training-time and stored in the tool. When you run the N-point calibration tool, it attaches this transform to the coordinate space tree of an input image and returns a copy of the image for use by other vision tools. Once you have created a calibrated space, you can use it to relate position and measurement information given by other vision tools into precise physical locations.

This topic shows you how to use the N-point calibration tool, CogCalibNPointToNPointTool, to perform the two steps involved in the calibration process. For more information about calibration and the N-point calibration tool, see the topic Calibration and Fixturing.

Before You Begin

Choose Project -> Add Reference and add a reference to the Cognex.VisionPro.CalibFix assembly to your Visual Studio.NET project.

Your program will need to be able to acquire images and display them. The sample code in this topic assumes that you have initialized a CogAcqFifoTool with which to acquire the image and that you have created a form with a display control to show the final calibrated image and graphics.

Acquire a Calibration Image

When calibrating, you acquire an image of a special calibration plate or circuit board with fiducial markings. The plate or board provides accurately measurable distances and known locations. To obtain valid results in calibrated space across tools, you must acquire images at run-time from the same camera and lens that you employ at the time of calibration.

Locate Uncalibrated Feature Points

Using a vision tool, such as CogPMAlignTool or CogBlobTool, locate features within your acquired image. The selected space of the image is uncalibrated space. You will use the coordinates of the found features as the set of N points in uncalibrated space required as input by the calibration tool.

Create an N-Point Calibration Tool

Create an N-point calibration tool and set the tool's input image to the image acquired by the AcqFifo.

Copy to ClipboardPrint
using Cognex.VisionPro;
using Cognex.VisionPro.CalibFix;
using Cognex.VisionPro.ImageFile;

private CogCalibNPointToNPointTool myCalibTool;

private void SetUpCalibTool()
{
    myCalibTool = new CogCalibNPointToNPointTool();

    myCalibTool.InputImage = myImageFileTool.OutputImage;
}
Choose the Number of Points to Match

Decide on the number (N) of points in each set, uncalibrated and raw calibrated, to provide as input to the N-point calibration tool. For N-point calibration, you supply at least three points, but to obtain more accurate results, you may use more points. Note that because you are calculating a calibration transform (which incorporates scaling, aspect, skew, rotation, and so on.), you do need at least the default three points in each point set. In addition, these points must not be colinear. They should be spread throughout your input image.

Add Uncalibrated and Raw Calibrated Point Pairs

You get the coordinates of the points in uncalibrated space from the output of a feature-locating tool. You must also specify a set of N points in raw calibrated space. You typically get the coordinates of the raw calibrated points by measuring a physical model of your object, having its schematics, or by using an object with a regular pattern (such as a grid) with known dimensions. You can add a pair of points with the AddPointPair method.

To change point values at a later time, you can set x- and y-coordinates individually using these methods:

You can also use the wide-setters SetUncalibratedPoint and SetRawCalibratedPoint to change point values.

The following code shows how you add point pairs in uncalibrated and raw calibrated space if you know the distance between object features. For example, you might have three important features on your object. Two points lie at a distance of 155mm and 52mm from a main feature. You place the origin of the raw calibrated space at (0, 0) and supply the other distance values as the points (155, 0) and (0, 52), as shown in the following figure.

Framework Calibration And Fixturing Walkthrough UseNPoint Howto Use NPoint Calibration 3points

Note that the code removes any default points, setting NumPoints to zero, before adding new ones. You could also, in this instance, use the wide-setters to change the values of the default points.

Copy to ClipboardPrint
private void SetUpPointPairs()
{
        myCalibTool.Calibration.NumPoints = 0;

        myCalibTool.Calibration.AddPointPair(myPMTool.Results[0].GetPose().TranslationX,
                myPMTool.Results[0].GetPose().TranslationY, 0, 0);
        myCalibTool.Calibration.AddPointPair(myPMTool.Results[1].GetPose().TranslationX,
                myPMTool.Results[1].GetPose().TranslationY, 155, 0);
        myCalibTool.Calibration.AddPointPair(myPMTool.Results[2].GetPose().TranslationX,
                myPMTool.Results[2].GetPose().TranslationY, 0, 52);
}
Specify Degrees of Freedom (DOFs)

Degrees of freedom determine what transform components the N-point calibration tool will use in calculating the transform that defines calibrated space. By default, the calibration tool has all degrees of freedom enabled: scaling, aspect, rotation, skew, and translation. To find the best fit between point sets, you usually want to keep all degrees of freedom. The CogNPointToNPointDOFConstants enumeration specifies the various degrees of freedom that can be computed during the N-point fitting operation.

Copy to ClipboardPrint
private void SetDOFs()
{
    myCalibTool.Calibration.DOFsToCompute =
        CogNPointToNPointDOFConstants.ScalingAspectRotationSkewAndTranslation;
}
Configure an Adjustment Transform

You may want your final calibrated space to be placed at a different location than indicated by the physical location values. You might find it more convenient in your application to place the origin of the calibrated space at the center of an object, rather than at its corner. The calibration tool computes the best-fit transformation to map the raw calibrated points to the uncalibrated points, and then applies the adjustment transform you specify to create the final calibrated space. The CogCalibNPointToNPointTool provides the following methods to perform this adjustment:

You cannot adjust the scaling or skew values of the final calibrated space because this would almost certainly produce a 2D transform that represents an invalid calibrated space.

You must also indicate to the tool whether you have expressed the origin and rotation adjustments in uncalibrated or raw calibrated space by supplying a CogCalibNPointAdjustmentSpaceConstants enumeration value to the CalibratedOriginSpace and CalibratedXAxisRotationSpace properties. You may find it convenient to specify adjustments in uncalibrated space if, for example, you wanted the origin of your calibrated space to be placed at the exact center of your image.

The following code moves the origin of the final calibrated space by 50 units relative to the raw calibrated space axes, centering it between the object features. It does not rotate the x-axis or swap the handedness of the final calibrated space. Note that if you expressed the origin adjustment in terms of the uncalibrated space, the final coordinate axes would be moved by 50 units closer to the center of the image.

Copy to ClipboardPrint
private void SetAdjustTansform()
{
    myCalibTool.Calibration.CalibratedOriginSpace = CogCalibNPointAdjustmentSpaceConstants.RawCalibrated;
    myCalibTool.Calibration.CalibratedXAxisRotationSpace = CogCalibNPointAdjustmentSpaceConstants.RawCalibrated;
    myCalibTool.Calibration.CalibratedXAxisRotation = 0;
    myCalibTool.Calibration.CalibratedOriginX = 50;
    myCalibTool.Calibration.CalibratedOriginY = 0;
    myCalibTool.Calibration.SwapCalibratedHandedness = false;
}
Select a Calibrated Space Name and Space to Output

When you calibrate an image, the calibration tool attaches the computed transform that represents the calibrated space to the coordinate space tree of the input image. You supply the name of this new space to the CalibratedSpaceName property. The name must be a valid nonqualified space name. You must also set the selected space of the output image. You supply a CogCalibSpaceToOutputConstants value to the SpaceToOutput property to indicate whether the selected space name of the output image is a fully-qualified copy of the uncalibrated space name or of the calibrated space name. The output space determines the selected space name of the output image. Any other tool that receives this image as input will report its results in this selected space.

Copy to ClipboardPrint
private void SetSpaces()
{
    myCalibTool.RunParams.CalibratedSpaceName = "N-Point Calibration Result";
    myCalibTool.RunParams.SpaceToOutput = CogCalibSpaceToOutputConstants.CalibratedSpace;
}
Include Input, Diagnostic, and Calibration Data in Tool Records

You can include various input, diagnostic, and calibration data in the tool's CurrentRecord and LastRunRecord. You use this data, for example, to display interactive and noninteractive graphics that represent coordinate axes and points in uncalibrated, raw calibrated, and calibrated spaces. To include such data, enable the appropriate tool records and select the data to include using the CurrentRecordEnable, LastRunRecordDiagEnable, and LastRunRecordEnable properties. The values of the CogCalibNPointToNPointCurrentRecordConstants, CogCalibNPointToNPointLastRunRecordDiagConstants, and CogCalibNPointToNPointLastRunRecordConstants enumerations specify the types of data you can include in the tool's records.

Copy to ClipboardPrint

private void SetRecordOptions()
{
    myCalibTool.CurrentRecordEnable = CogCalibNPointToNPointCurrentRecordConstants.UncalibratedAxes |
        CogCalibNPointToNPointCurrentRecordConstants.CalibratedAxes |
        CogCalibNPointToNPointCurrentRecordConstants.CalUncalibratedPoints |
        CogCalibNPointToNPointCurrentRecordConstants.CalRawCalibratedAxes |
        CogCalibNPointToNPointCurrentRecordConstants.CalRawCalibratedPoints |
        CogCalibNPointToNPointCurrentRecordConstants.CalCalibratedAxes |
        CogCalibNPointToNPointCurrentRecordConstants.CalUncalibratedPoints;

    myCalibTool.LastRunRecordDiagEnable = CogCalibNPointToNPointLastRunRecordDiagConstants.UncalibratedAxes |
        CogCalibNPointToNPointLastRunRecordDiagConstants.CalibratedAxes;
}
Compute a Calibration

You calibrate your tool once at training time and then use the precomputed calibration when you run the tool. To compute the 2D transform that defines the calibrated space, you call the Calibrate method of the tool's train-time parameters object. The tool stores the computed calibration.

Copy to ClipboardPrint
private void ComputeCalibration()
{
    myCalibTool.Calibration.Calibrate();
}
Check the RMS Error

After calibrating, you should check the root mean squared (RMS) error value for the calculation. The RMS error measures the variation between the two sets of N points after computing the best-fit transformation. A large RMS error value may indicate that points are not in an appropriate position and therefore measured incorrectly by the tool; or that you have not enabled enough degrees of freedom (DOFs) for the calculation. You can obtain the RMS error for the calibration from the tool parameter's ComputedRMSError property.

Run the N-Point Calibration Tool

Running the N-point calibration tool attaches the precomputed transform for the calibrated space to the coordinate space tree of an input image and returns a copy of the CogImage for use by other vision tools. You run the N-point calibration tool by calling its Run method.

In the following example, a Blob tool receives the image output from the calibration tool. The Blob tool runs in the calibrated space.

Copy to ClipboardPrint
private void RunTool()
{
    CogBlobTool myBlobTool = new CogBlobTool();

    myCalibTool.Run();

    myBlobTool.InputImage = myCalibTool.OutputImage;
    myBlobTool.Run();
}

You can also explicitly use the UncalibratedFromCalibrated transform to set the values of other tools and graphics. You obtain this transform by calling the GetComputedUncalibratedFromCalibratedTransform method. The following code shows how to use the returned transform to configure a coordinate axes graphic that shows the final calibrated space on a display. For more information about displaying graphics, see Draw Graphics.

Copy to ClipboardPrint
private void DrawAxes()
{
    if (myCalibTool.Calibration.Calibrated)
    {
        CogCoordinateAxes myAxes = new CogCoordinateAxes();

        myAxes.Transform = myCalibTool.Calibration.GetComputedUncalibratedFromCalibratedTransform();

        myAxes.Color = CogColorConstants.Green;
        myAxes.XAxisLabel.Color = CogColorConstants.Green;
        myAxes.YAxisLabel.Color = CogColorConstants.Green;
        myAxes.DisplayedXAxisLength = 50;

        cogDisplay1.InteractiveGraphics.Add(myAxes, "", false);
    }
}