Overview

Calibrate Camera is designed to adjust the camera view to match real-world distances accurately. This functionality is useful for applications requiring precise distance measurements from video data. By ensuring the camera's view is correctly calibrated, users can rely on the accuracy of distance measurements within the video feed, enhancing the application's reliability and effectiveness.

The output of this node is used by Speed Estimation node.

Inputs & Outputs

Inputs : 1, Media Format : Raw Video
Outputs : 1, Media Format: Raw Video
Output Metadata : Presence Information

Properties

Property	Description	Type	Default	Required
`roi_labels`	Calibration square labels	`string`	`calibration`	No
`rois`	Outline a real-world square on the ground. It will normally appear as a trapezoid in the image. Conditional on `roi_labels`. Format: comma-separated normalized `x,y` coordinate pairs; separate multiple polygons with semicolons (for example, `0.1,0.1,0.9,0.1,0.9,0.9`).	`string`	`0.25,0.25,0.25,0.75,0.75,0.75,0.75,0.25`	No
`roi_size`	Real-world length of each side of the calibration square. Range: minimum `1`, maximum `100.0`. Step: `1`.	`integer`	`5`	Yes
`roi_size_units`	Units. Options: Foot (`ft`); Meter (`m`).	`enum`	`ft`	No
`display_roi`	Show orange ground-grid points and lines in both directions, plus the trusted measurement zone. The calibration label displays Poor or Invalid when attention is needed.	`bool`	`false`	No

The four square corners are ordered automatically. When the calibration grid is displayed, orange ground lines and their intersection points are drawn in both directions directly on the video. The calibration square outline marks the trusted measurement zone. A Good calibration displays only the square label and dimensions; Poor or Invalid is appended when attention is needed. Stability is estimated by perturbing each corner by two pixels and measuring the resulting local-distance variation. Tapering can also make a calibration Poor even when its point-placement stability is otherwise good:

Good (green outline): variation is at most 5% and the square is not severely tapered. No Good status suffix is displayed.
Poor (red): the calibration misses the Good stability or geometry criteria. The transform is still published, but the square should be made larger or adjusted if possible.
Invalid (red): the square or transform is degenerate, non-convex, singular, or otherwise unsafe. No homography is published.

Output Metadata

The fields below are declared by this node's metadata schema; the JSON values are representative examples.

Path	Type	Description
`nodes.<node_id>.homography`	`array`	Two-dimensional array containing the camera calibration homography matrix.
`nodes.<node_id>.homography_units`	`string`	Measurement units used by the calibration homography.
`nodes.<node_id>.type`	`string`	Identifies the node type that produced this metadata.

JSON example

{
  "nodes": {
    "calibrate_camera1": {
      "homography": [],
      "homography_units": "value",
      "type": "calibrate_camera"
    }
  }
}