Control Points¶

This page specifies a common control point data format.

Definitions¶

A tie point represents a set of image points that identify the projections of a 3D point with unknown 3D position in the scene. A Manual Tie Point (MTP) is a tie point with user provided points in the images.

A position constrained tie point contains the known measured (prior) 3D-position of a point in the scene, together with the uncertainty on that measurement. A Ground Control Point (GCP) is a type of position constrained tie point.

The GCP coordinates are defined in some CRS and the input coordinate axes follow the convention of the CRS definition.

A control point is either a tie point or a position constrained tie point.

A checkpoint is a control point that may be provided by the user for the sake of quality assessment. Checkpoints are not taken into account for calibration but used later to compute the re-projection error and the position error (in the case of a position constrained tie point).

A control point mark is the association of a control point and an image. It has the following attributes:

position: the mark position in the image;
accuracy: number representing the accuracy of the click. This is used by the calibration algorithm to estimate the position error of the mark.

In the image coordinate system, (0, 0) is located at the top left corner of the top left pixel and (width, height) at the bottom right corner of the bottom right pixel, where width and height are the sensor dimensions in pixels. The pixel matrix is considered relative to physical sensor, i.e., the display orientation tag shall not be taken into account. Unless otherwise stated, the same convention shall apply to any extension where positions on images are used.

Control points exist in three variations:

input control points: input points with coordinates expressed in their original CRS;
projected control points: input points with coordinates expressed in the processing CRS;
calibrated control points: optimized points with coordinates expressed in the processing CRS.

The processing CRS is the translated canonical CRS implicitly defined by the top level scene reference frame.

Scale and orientation constraints can be added to calibration using control points:

a scale constraint is made of two control points and a measurement of the distance between the 3d corresponding points;
an orientation constraint is made of two control points and a constraint vector in the processing CRS. The calibration has to match the orientation and sense of the vector connecting the calibrated control point positions to the constraint vector.

File format¶

Control point data are relatively small. We typically have a dozen/hundred of control points in a project and a dozen of marks per tie point.

The control point data will be represented in JSON format.

Format specification: Input control points¶

Specification format	Version
“application/opf-input-control-points+json”	“1.0”

Input control points¶

Definition of the input control points, which are the control points in their original CRS

Input control points Properties

	Type	Description	Required
format	`string`	Required to be `"opf-input-control-points+json"`	✓ Yes
version	`string`	The version of this schema as `MAJOR.MINOR`. Breaking changes are reflected by a change in MAJOR version. Can optionally include a pre-release tag `MAJOR.MINOR-tag`. Examples: `0.1`, `1.0`, `1.0-draft1`	✓ Yes
gcps	`gcp` `[]`	List of input GCPs.	✓ Yes
mtps	`mtp` `[]`	List of input MTPs.	✓ Yes
extensions	`object`	JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname	No

CRS¶

Coordinate reference system

CRS Properties

	Type	Description	Required
definition	`string`	One of: - A WKT string version 2. - A string in the format `Authority:code+code` where the first code is for a 2D CRS and the second one if for a vertical CRS (e.g. `EPSG:4326+5773`). . - A string in the form `Authority:code+Authority:code` where the first code is for a 2D CRS and the second one if for a vertical CRS. - A string in the form `Authority:code` where the code is for a 2D or 3D CRS.	✓ Yes
geoid_height	`number`	Constant geoid height over the underlying ellipsoid in the units of the vertical CRS axis.	No
extensions	`object`	JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname	No

GCP¶

GCP Properties

	Type	Description	Required
id	`string`	A unique string that identifies the GCP.	✓ Yes
geolocation	`geolocation`	Geolocation information	✓ Yes
marks	`mark` `[]`	List of marks in the images that correspond to the projections of a 3D point.	✓ Yes
is_checkpoint	`boolean`	If true, the GCP is used only to measure the quality of the calibration results and it does not affect it.	✓ Yes
extensions	`object`	JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname	No

Geolocation¶

Geolocation information

Geolocation Properties

	Type	Description	Required
crs	`crs`	Coordinate reference system	✓ Yes
coordinates	`number` `[3]`	3D coordinates of a point using the same axis convention as declared by the CRS, i.e., the X, Y axes are not always Easting-Northing.	✓ Yes
sigmas	`number` `[3]`	Standard deviation of a measured position. For geographic CRSs, all units are meters. For Cartesian CRSs, the units are given by the 3D promoted definition of the axes (see the specification of the coordinate reference system above for the definition of the promotion).	✓ Yes
extensions	`object`	JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname	No

Mark¶

2D image mark

Mark Properties

	Type	Description	Required
camera_id	`integer`	Unique identifier as unsigned 64 bit integer.	✓ Yes
position_px	`number` `[2]`	(x,y) pixel location, (0,0) is the top left corner of the top left pixel.	✓ Yes
accuracy	`number`	A number representing the accuracy of the click, it is used by the calibration algorithm to estimate the position error of the mark.	✓ Yes
extensions	`object`	JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname	No

MTP¶

MTP Properties

	Type	Description	Required
id	`string`	A unique string that identifies the MTP.	✓ Yes
marks	`mark` `[]`	List of marks in the images that correspond to the projections of a 3D point.	✓ Yes
is_checkpoint	`boolean`	If true, the MTP is used only to measure the quality of the calibration results and it does not affect it.	✓ Yes
extensions	`object`	JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname	No

Example¶

{
    "format": "application/opf-input-control-points+json",
    "version": "1.0",
    "gcps": [
        {
            "id": "gcp0",
            "geolocation": {
                "crs": {
                    "definition": "EPSG:4265+5214",
                    "geoid_height": 123
                },
                "coordinates": [
                    1,
                    2,
                    3
                ],
                "sigmas": [
                    5,
                    5,
                    10
                ]
            },
            "marks": [
                {
                    "camera_id": 10000000,
                    "position_px": [
                        458,
                        668
                    ],
                    "accuracy": 1.0
                },
                {
                    "camera_id": 20000000,
                    "position_px": [
                        458,
                        668
                    ],
                    "accuracy": 10.0
                },
                {
                    "camera_id": 30000000,
                    "position_px": [
                        458,
                        668
                    ],
                    "accuracy": 20.0
                }
            ],
            "is_checkpoint": true
        }
    ],
    "mtps": [
        {
            "id": "mtp0",
            "marks": [
                {
                    "camera_id": 10000000,
                    "position_px": [
                        458,
                        668
                    ],
                    "accuracy": 1.0
                },
                {
                    "camera_id": 20000000,
                    "position_px": [
                        458,
                        668
                    ],
                    "accuracy": 10.0
                },
                {
                    "camera_id": 30000000,
                    "position_px": [
                        458,
                        668
                    ],
                    "accuracy": 20.0
                }
            ],
            "is_checkpoint": false
        }
    ]
}

Format specification: Projected control points¶

Specification format	Version
“application/opf-projected-control-points+json”	“1.0”

Projected control points¶

Definition of projected control points, which are the input control points with coordinates expressed in the processing CRS

Projected control points Properties

	Type	Description	Required
format	`string`	Required to be `"opf-projected-control-points+json"`	✓ Yes
version	`string`	The version of this schema as `MAJOR.MINOR`. Breaking changes are reflected by a change in MAJOR version. Can optionally include a pre-release tag `MAJOR.MINOR-tag`. Examples: `0.1`, `1.0`, `1.0-draft1`	✓ Yes
projected_gcps	`projected_gcp` `[]`	List of projected GCPs.	✓ Yes
extensions	`object`	JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname	No

Projected GCP¶

Projected GCP Properties

	Type	Description	Required
id	`string`	A string identifier that matches the correspondent input GCP.	✓ Yes
coordinates	`number` `[3]`	3D position in the processing CRS.	✓ Yes
sigmas	`number` `[3]`	Standard deviation of the 3D position in processing CRS units.	✓ Yes
extensions	`object`	JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname	No

Example¶

{
    "format": "application/opf-projected-control-points+json",
    "version": "1.0",
    "projected_gcps": [
        {
            "id": "gcp0",
            "coordinates": [
                3859391,
                103895,
                384
            ],
            "sigmas": [
                5,
                5,
                10
            ]
        }
    ]
}

Format specification: Calibrated control points¶

Specification format	Version
“application/opf-calibrated-control-points+json”	“1.0”

Calibrated control points¶

Definition of calibrated control points, which are the optimised control points with coordinates expressed in the processing CRS.

Calibrated control points Properties

	Type	Description	Required
format	`string`	Required to be `"opf-calibrated-control-points+json"`	✓ Yes
version	`string`	The version of this schema as `MAJOR.MINOR`. Breaking changes are reflected by a change in MAJOR version. Can optionally include a pre-release tag `MAJOR.MINOR-tag`. Examples: `0.1`, `1.0`, `1.0-draft1`	✓ Yes
points	`calibrated_control_point` `[]`	List of calibrated control points.	✓ Yes
extensions	`object`	JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname	No

Calibrated control point¶

Calibrated control point Properties

	Type	Description	Required
id	`string`	A string identifier that matches the corresponding input control point.	✓ Yes
coordinates	`number` `[3]`	Optimized 3D position in the processing CRS.	✓ Yes
extensions	`object`	JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname	No

Example¶

{
    "format": "application/opf-calibrated-control-points+json",
    "version": "1.0",
    "points": [
        {
            "id": "gcp0",
            "coordinates": [
                3959232,
                116595,
                384
            ]
        },
        {
            "id": "mtp1",
            "coordinates": [
                3959500,
                116595,
                423
            ]
        }
    ]
}

Format specification: Scale and orientation constraints¶

Specification format	Version
“application/opf-constraints+json”	“1.0”

Constraints¶

Scale and orientation constraints

Constraints Properties

	Type	Description	Required
format	`string`	Required to be `"opf-constraints+json"`	✓ Yes
version	`string`	The version of this schema as `MAJOR.MINOR`. Breaking changes are reflected by a change in MAJOR version. Can optionally include a pre-release tag `MAJOR.MINOR-tag`. Examples: `0.1`, `1.0`, `1.0-draft1`	✓ Yes
scale_constraints	`scale_constraint` `[]`	List of scale constraints.	✓ Yes
orientation_constraints	`orientation_constraint` `[]`	List of orientation constraints.	✓ Yes
extensions	`object`	JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname	No

Orientation constraint¶

Orientation constraint Properties

	Type	Description	Required
id	`string`	A unique string that identifies the constraint.	✓ Yes
id_from	`string`	A string identifier that matches the correspondent input control point.	✓ Yes
id_to	`string`	A string identifier that matches the correspondent input control point.	✓ Yes
unit_vector	`number` `[3]`	Direction in which the to-from vector has to point given as a unit vector in the processing CRS.	✓ Yes
sigma_deg	`number`	Accuracy of the alignment expressed as the angle between the unit_vector and the to-from vector in degrees.	✓ Yes
extensions	`object`	JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname	No

Scale constraint¶

Scale constraint Properties

	Type	Description	Required
id	`string`	A unique string that identifies the constraint.	✓ Yes
id_from	`string`	A string identifier that matches the correspondent input control point.	✓ Yes
id_to	`string`	A string identifier that matches the correspondent input control point.	✓ Yes
distance	`number`	Distance between the two control points in the processing CRS.	✓ Yes
sigma	`number`	Distance accuracy in the processing CRS.	✓ Yes
extensions	`object`	JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname	No

Example¶

{
    "format": "application/opf-constraints+json",
    "version": "1.0",
    "scale_constraints": [
        {
            "id": "sc1",
            "id_from": "gcp0",
            "id_to": "gcp1",
            "distance": 1.23,
            "sigma": 0.1
        }
    ],
    "orientation_constraints": [
        {
            "id": "oc1",
            "id_from": "gcp0",
            "id_to": "gcp1",
            "unit_vector": [
                0,
                0,
                1
            ],
            "sigma_deg": 1.0
        }
    ]
}