Calibrate manually

Calibrate manually

Calculates scaling factors between pixels and world units. This tool can be used to calculate camera calibration factors when an application does not require high measurement accuracy. It assumes that the camera sensor is parallel to the world plane. In other words, the optical axis must meet the world plane at a right angle.

The simple calibration method requires an object whose length in world units is known. A ruler or a tape measure will do. The start and end points of the object (or a part of it) are marked in the input image, and the corresponding physical length is entered to the physicalLength input parameter. With this information, the tool calculates the necessary calibration factors. As an output, it produces an output image whose world coordinate system and calibration data is different from that of the input.

It is recommended to use millimeters as world units, but this is not an absolute requirement. If you feel more comfortable using e.g. inches, that is fine. The lengths are however stored in decimal notation. This means that 1 ft 2 in 3 thou will be represented as 14.003.

Usually, there is no need to change calibration factors at run time. Therefore, the typical use case is to use the simple calibration tool to calculate static calibration values once when building an application:

  • Add the Image Source that needs to be calibrated.
  • Open its image output to an image display.
  • Add the simple calibration tool.
  • Drag startPoint or endPoint on top of the image display.
  • Move the points so that they match the end points of the calibration object (or e.g. a 10 cm part of it).
  • Enter the known physical length of the line to the physicalLength input parameter.
  • If the position of the world coordinate system matters, drag the worldFrame input parameter on top of the image and adjust its location and orientation as needed.
  • Enter an approximate value to the cameraDistance parameter. This is actually not strictly required, but makes the calibration parameters physically meaningful. In run-time operation, the estimated camera distance will be relative to the value entered in the static calibration phase.
  • To save the calibration permanently to the Image Source, change its calibration input parameter to "Manual Calibration" and copy the frame and focalLength output parameters from the simple calibration tool to the corresponding input parameters in the Image Source.
  • Once a camera (or an image source) has been statically calibrated using a reference object, it is possible to use the simple calibration tool at run time to translate and rotate the world coordinate system. This is useful if the camera moves along its optical axis or rotates around it. In this case, the focal length of the camera does not change, but the camera distance does.

    To be able to do run-time calibration, the camera must always see an object whose length is known. Detectors (such as Blob Detection or Line Detection) can be used to produce start and end points of the known object. The output image can then be used as a new source image for subsequent analysis steps.

    To switch between static and run-time calibration modes, change the cameraDistance input parameter. If it is non-zero, the tool relies on it and adjusts focalLength accordingly. If cameraDistance is zero, the focal length stored in the input image is assumed to be correct, and cameraDistance will be adjusted.

    In run-time calibration, it is possible to rotate the world coordinate system by producing a new coordinate frame out of a detector's result e.g. with Translation and Rotation. Usually, it is a good idea to set the worldFrame input parameter to an identity matrix (which is the default value).

    Inputs

    image
    An input image. It is allowed that the input image has valid calibration data. It must however contain no 3D transformations. If it does, the resulting world coordinate system will not be correct. The tool will adjust the calibration data so that the length of the calibration object becomes equal to physicalLength in the world coordinate system of the output image.
    startPoint
    The start point of an object in image. The coordinates of the start point are in the world coordinate system of the input image. Since the tool changes calibration parameters, drawing the input point on the output image will generally place it to a different location.
    endPoint
    The start point of the object in image, in the world coordinate system of the input image.
    worldFrame
    The location and orientation of the new world coordinate system, in the world coordinate system of the input image.
    physicalLength
    The physical length of the object in world units.
    cameraDistance
    The distance between the camera's aperture and the world plane in world units. If this value is set to zero, the focal length stored in the input image is assumed to be correct, and the tool only adjusts the camera's distance from the world.

    Outputs

    image
    The input image with a new world coordinate system. If input parameters are invalid (e.g. startPoint and endPoint are the same), the tool applies no scaling to the calibration parameters.
    frame
    The world coordinate frame in the camera coordinate system. Drawing this frame on top of an image using its world coordinate system is not meaningful. Similarly, this frame does not work as an input to tools that expect a frame in the world coordinate system. To make the calibration permanent, this parameter can be copied to the frame input parameter of Image Source.
    focalLength
    The approximate focal length of the camera. To make the calibration permanent, this parameter can be copied to the focalLength input parameter of Image Source.
    startPoint
    startPoint in the new world coordinate system.
    endPoint
    startPoint in the new world coordinate system.
    cameraDistance
    The estimated distance between the camera's aperture and the world plane, in world units. Note that the same information is available in the frame output.