Skip to content

Object Space Schema

{
  "camera": {
    "descriptor": {
    //   ...
    },
    "detector": {
    //   ...
    }
  }
}

Top-Level Components

For every type of component you have an object space for, you'll have a root level field in the JSON. At present, we only support camera components.

In the future you might eventually have an object JSON that looks like:

{
  "camera": { /* ... */ },
  "lidar": { /* ... */ }
}

and so on. Each key defines the Detector-Descriptor pair for that modality, which in turn describes our object space.

A Note On Variance

Variance shows up in both Detectors and Descriptors. In object space, variance-covariance terms describe the rough confidence we have in the physical dimensions of the fiducial being captured in the calibration data.

For example, say you're working with a markerboard that curves inward slightly. The Z-dimension of every corner in that board might be ± 0.003 m away from planar. However, the X and Y dimensions are relatively fixed (since the board is printed that way), so every point might be within ± 0.001m in those axes.

We can encapsulate this in our object space variance. Turn our uncertainty measurements (which we can interpret as standard deviation) into variance for our detector:

{
    "markerboard":
    {
      "variances" : [1e-06, 1e-06, 9e-06]
    }  
}

Notice that the values are 0.001² and 0.003², since variance is standard deviation squared.

Detectors

Checkerboards

Supported By Components: Camera

Compatible With Descriptors: None because it is detector defined

Checkerboard

"camera": {
    "detector": {
        "checkerboard": {
            "width": 9,
            "height": 6,
            "checker_length": 0.061,
            "variances": [0.01, 0.01, 0.01]
        }
    },
    "descriptor": null
}
Field Type Description
"width" integer The number of checker squares that the board is "wide."
"height" integer The number of checker squares that the board is "tall."
"checker_length" number The length (in meters) of a side of the checker square.
"variances" [number, number, number] The (X, Y, Z) variances of points in the checkerboards (in meters²).

Markerboards

Supported By Components: Camera

Compatible With Descriptors: None because it is detector defined

Markerboard

"camera": {
    "detector": {
        "markerboard": {
            "width": 9,
            "height": 6,
            "checker_length": 0.061,
            "marker_length": 0.05,
            "marker_dictionary": "Aruco6x6_250",
            "variances": [0.01, 0.01, 0.01]
        }
    },
    "descriptor": null
}
Field Type Description
"width" integer The number of checker squares that the board is "wide."
"height" integer The number of checker squares that the board is "tall."
"checker_length" number The length (in meters) of a side of the checker square.
"marker_length" number The length (in meters) of a side of the markers.
"marker_dictionary" String The dictionary of markers that describes the set of markers being used.
"variances" [number, number, number] The (X, Y, Z) variances of points in the checkerboards (in meters²).

See Supported Dictionaries for all compatible marker dictionaries.

Aprilgrid

Supported By Components: Camera

Compatible With Descriptors: None because it is detector defined

Aprilgrid

"camera": {
    "descriptor": null,
    "detector": {
        "april_grid": {
            "width": 5,
            "height": 3,
            "marker_length": 0.125,
            "tag_spacing": 0.30,
            "marker_dictionary": "ApriltagKalibr",
            "variances": [0.01, 0.01, 0.01]
        }
    }
}
Field Type Description
"width" integer The number of checker squares that the board is "wide."
"height" integer The number of checker squares that the board is "tall."
"tag_spacing" number The space between the tags in fraction of the edge size [0..1]. For those using a Kalibr board, the kalibr default is 0.3.
"marker_length" number The length (in meters) of a side of the markers.
"marker_dictionary" String The dictionary of markers that describes the set of markers being used.
"variances" [number, number, number] The (X, Y, Z) variances of points in the checkerboards (in meters²).

Aprilgrids only support April dictionaries. See Supported Dictionaries for this list.

Markers

Supported By Components: Camera

Compatible With Descriptors: Target List

Markers

"camera": {
    "descriptor": {
        "targets": [
            {
                "coordinates": [0.05340714676149457, 0.04404427557453171, 0.0],
                "id": 4,
                "variances": [0.01, 0.01, 0.01]
            },
            {
                "coordinates": [0.02340602380315638, 0.0440430837159586, 0.0],
                "id": 5,
                "variances": [0.01, 0.01, 0.01]
            },
            {
                "coordinates": [0.02340602380315638, 0.014068607053580883, 0.0],
                "id": 6,
                "variances": [0.01, 0.01, 0.01]
            },
            {
                "coordinates": [0.05340714676149457, 0.014067416092491642, 0.0],
                "id": 7,
                "variances": [0.01, 0.01, 0.01]
            }
        ]
    },
    "detector": {
        "markers": {
            "marker_dictionary": "Apriltag36h11",
            "marker_length": 0.029999999329447746
        }
    }
}
Field
Type Description
"marker_length" number The length (in meters) of a side of the markers.
"marker_dictionary" String The dictionary of markers that describes the set of markers being used.

See Supported Dictionaries for all compatible marker dictionaries.

Descriptors

Detector-Defined

Because detector-defined descriptors do not require additional information, there is no JSON needed here. Example:

{
  "camera":
  {
    "detector": {
      "checkerboard" : {
        ...
      }
    }
    // No descriptor needed.
  }
}

Target List

Field Type Description
"targets" Array<Object> An array of JSON objects representing targets.

Each object in the "targets" array will have the following fields:

Field Type Description
"id" integer The identifier for the point.
"coordinates" [ number, number, number ] The (X, Y, Z) coordinate of the point.
"variances" [ number, number, number ] The (X, Y, Z) variances of the point.

Every id corresponds to a corner on the marker.

Descriptor: Marker Corner Ordering

Notice that each target in the target list has a separate set of variances. This allows one to express that some targets in your set of markers have different measurement accuracies.

Supported ArUco and AprilTag Dictionaries

The Detectors Markerboard, AprilGrid, and Marker all accept a marker_dictionary argument. The supported dictionaries are listed below.

Dictionary Name
Description
"Aruco4x4_50" 4x4 bit Aruco containing 50 markers.
"Aruco4x4_100" 4x4 bit Aruco containing 100 markers.
"Aruco4x4_250" 4x4 bit Aruco containing 250 markers.
"Aruco4x4_1000" 4x4 bit Aruco containing 1000 markers.
"Aruco5x5_50" 5x5 bit Aruco containing 50 markers.
"Aruco5x5_100" 5x5 bit Aruco containing 100 markers.
"Aruco5x5_250" 5x5 bit Aruco containing 250 markers.
"Aruco5x5_1000" 5x5 bit Aruco containing 1000 markers.
"Aruco6x6_50" 6x6 bit Aruco containing 50 markers.
"Aruco6x6_100" 6x6 bit Aruco containing 100 markers.
"Aruco6x6_250" 6x6 bit Aruco containing 250 markers.
"Aruco6x6_1000" 6x6 bit Aruco containing 1000 markers.
"Aruco7x7_50" 7x7 bit Aruco containing 50 markers.
"Aruco7x7_100" 7x7 bit Aruco containing 100 markers.
"Aruco7x7_250" 7x7 bit Aruco containing 250 markers.
"Aruco7x7_1000" 7x7 bit Aruco containing 1000 markers.
"ArucoOriginal" 5x5 bit Aruco containing the original generated marker library.
"Apriltag16h5" 4x4 bit Apriltag containing 20 markers.
"Apriltag25h9" 5x5 bit Apriltag containing 35 markers.
"Apriltag36h10" 6x6 bit Apriltag containing 2320 markers.
"Apriltag36h11" 6x6 bit Apriltag containing 587 markers.
"ApriltagKalibr" 6x6 bit Apriltag containing 587 markers, matching Kalibr format. These have a 2-block black border around markers, rather than the 1-block border in Apriltag36h11.