Input camera format¶
This format defines the input cameras, i.e. the data as provided by the user and camera database. It does not contain processed information, such as for example coordinates converted into the processing CRS. Those are handled separately.
Format specification¶
Specification format |
Version |
|---|---|
“application/opf-input-cameras+json” |
“1.0” |
Input cameras¶
Definition of the input cameras, i.e. the data as provided by the user and camera database.
Input cameras Properties
Type |
Description |
Required |
|
|---|---|---|---|
format |
|
For input cameras it must be |
✓ Yes |
version |
|
The version of this schema as |
✓ Yes |
sensors |
|
List of input sensors. |
✓ Yes |
captures |
|
List of input captures. |
✓ Yes |
extensions |
|
JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname |
No |
Band information¶
Information about a band
Band information Properties
Type |
Description |
Required |
|
|---|---|---|---|
name |
|
No |
|
weight |
|
Weights to compute a luminance representation of the image |
✓ Yes |
extensions |
|
JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname |
No |
Camera¶
One camera in a capture. It is associated to a sensor via a sensor identifier.
Camera Properties
Type |
Description |
Required |
|
|---|---|---|---|
sensor_id |
|
Unique identifier as unsigned 64 bit integer. |
✓ Yes |
id |
|
Unique identifier as unsigned 64 bit integer. |
✓ Yes |
model_source |
|
Allowed values : |
✓ Yes |
pixel_type |
|
Allowed values : |
✓ Yes |
pixel_range |
|
Defines the range of valid pixel values. Values ≤ min are considered underexposed and ≥ max overexposed. Can be a static range or a dynamic range. |
✓ Yes |
image_orientation |
|
Specifies the image orientation following EXIF, page 37. 1: no rotation, no mirror, 2: mirror horizontal, 3: rotate 180 degrees, 4: mirror vertical, 5: mirror horizontal and rotate 270 degrees CW, 6: rotate 90 degrees CW, 7: mirror horizontal and rotate 90 degrees CW, 8: rotate 270 degrees CW. |
No |
extensions |
|
JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname |
No |
Capture element¶
A collection of cameras and spatio-temporal information of an image acquisition event.
Capture element Properties
Type |
Description |
Required |
|
|---|---|---|---|
id |
|
Unique identifier as unsigned 64 bit integer. |
✓ Yes |
reference_camera_id |
|
ID of the reference camera in a rig. Required also for single camera capture. |
✓ Yes |
cameras |
|
List of cameras in the capture. |
✓ Yes |
rig_model_source |
|
Allowed values : |
✓ Yes |
geolocation |
Geolocation information |
No |
|
orientation |
|
One of Yaw-Pitch-Roll or Omega-Phi-Kappa orientation. |
No |
height_above_takeoff_m |
|
Height above the take-off place in meters. |
No |
time |
|
The time of image acquisition formatted as ISO 8601. If the timezone is known then the time should be specified as UTC, if no timezone is given then it is unknown. |
✓ Yes |
extensions |
|
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 |
|
One of: |
✓ Yes |
geoid_height |
|
Constant geoid height over the underlying ellipsoid in the units of the vertical CRS axis. |
No |
extensions |
|
JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname |
No |
Dynamic pixel range¶
Dynamically inferred pixel range. The range needs to be derived from the data by looking at the image content, filtering extreme values at both ends with the given percentile.
Dynamic pixel range Properties
Type |
Description |
Required |
|
|---|---|---|---|
percentile |
|
Percentage of values ignored on both ends of the ordered list of values when computing the min/max. It must be a positive value and 0 means nothing is ignored. |
✓ Yes |
extensions |
|
JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname |
No |
Fisheye internals¶
Parameters of the fisheye camera model as described in Pix4D knowledge base.
Fisheye internals Properties
Type |
Description |
Required |
|
|---|---|---|---|
type |
|
Must be |
✓ Yes |
principal_point_px |
(x, y) location of the principal point in pixels with (0, 0) being at the top left corner of the top left pixel. |
✓ Yes |
|
is_symmetric_affine |
|
If true, it is prior knowledge that the affine matrix is symmetric (that is, c=f and d=e=0) and should be kept symmetric. |
✓ Yes |
affine |
|
Affine transformation parameters as [ c d; e f ] |
✓ Yes |
polynomial |
|
The coefficients of the distortion polynomial. |
✓ Yes |
is_p0_zero |
|
If true, it is prior knowledge that the first polynomial coefficient is equal to zero and should be kept zero. |
✓ Yes |
extensions |
|
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 |
Coordinate reference system |
✓ Yes |
|
coordinates |
|
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 |
|
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 |
|
JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname |
No |
Input rig relatives¶
Input rig relatives contain the a priori knowledge about the relative translation and rotation of secondary cameras. Since these values are supposedly coming from a sensor database, the units are always meters and degrees.
Input rig relatives Properties
Type |
Description |
Required |
|
|---|---|---|---|
translation |
Input camera rig translation relative to the reference camera. |
✓ Yes |
|
rotation |
Input camera rig rotation relative to the reference camera. |
✓ Yes |
|
extensions |
|
JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname |
No |
Internals¶
One of perspective, fisheye or spherical internal. Parameters of the camera models are described in Pix4D knowledge base.
Omega-Phi-Kappa orientation¶
Omega-Phi-Kappa represent a rotation R_x(ω)R_y(ϕ)R_z(κ) from the image CS to a separately defined Cartesian CRS, where the image CS is right-top-back in image space.
Omega-Phi-Kappa orientation Properties
Type |
Description |
Required |
|
|---|---|---|---|
type |
|
Must be |
✓ Yes |
angles_deg |
|
Omega, phi, kappa angles in degrees. |
✓ Yes |
sigmas_deg |
|
Error estimation (standard deviation) in degrees. |
✓ Yes |
crs |
|
The target CRS of the rotation. A Cartesian horizontal CRS as WKT2 string or |
✓ Yes |
extensions |
|
JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname |
No |
Perspective internals¶
Parameters of the perspective camera model as described in Pix4D knowledge base.
Perspective internals Properties
Type |
Description |
Required |
|
|---|---|---|---|
type |
|
Must be |
✓ Yes |
principal_point_px |
(x, y) location of the principal point in pixels with (0, 0) being at the top left corner of the top left pixel. |
✓ Yes |
|
focal_length_px |
|
Focal length in pixels. |
✓ Yes |
radial_distortion |
|
The radial distortion coefficients (R1, R2, R3). |
✓ Yes |
tangential_distortion |
|
The tangential distortion coefficients (T1, T2). |
✓ Yes |
extensions |
|
JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname |
No |
Pixel range¶
Static pixel data range given by a minimum and maximum.
Pixel range Properties
Type |
Description |
Required |
|
|---|---|---|---|
min |
|
Minimum pixel value. |
✓ Yes |
max |
|
Maximum pixel value. |
✓ Yes |
extensions |
|
JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname |
No |
Principal point¶
(x, y) location of the principal point in pixels with (0, 0) being at the top left corner of the top left pixel.
Rig relative rotation¶
Input camera rig rotation relative to the reference camera.
Rig relative rotation Properties
Type |
Description |
Required |
|
|---|---|---|---|
angles_deg |
|
Euler angles in degree (see convention here). |
✓ Yes |
sigmas_deg |
|
Measurement error (standard deviation) in degrees. |
✓ Yes |
extensions |
|
JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname |
No |
Rig relative translation¶
Input camera rig translation relative to the reference camera.
Rig relative translation Properties
Type |
Description |
Required |
|
|---|---|---|---|
values_m |
|
Relative translation of the secondary sensor in the image CS of the reference sensor in meters. |
✓ Yes |
sigmas_m |
|
Measurement error (standard deviation) in meters. |
✓ Yes |
extensions |
|
JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname |
No |
Sensor element¶
Specifies one sensor model of a physical camera unit, described by lens type, general parameters and internal optical parameters.
Sensor element Properties
Type |
Description |
Required |
|
|---|---|---|---|
id |
|
Unique identifier as unsigned 64 bit integer. |
✓ Yes |
name |
|
Sensor name. |
✓ Yes |
bands |
|
Image band properties. The number of items must be equal to the channel count. For example, an RGB image has the three bands |
✓ Yes |
image_size_px |
|
Image width and height in pixels. |
✓ Yes |
pixel_size_um |
|
Pixel size in micrometers. |
✓ Yes |
internals |
One of perspective, fisheye or spherical internal. Parameters of the camera models are described in Pix4D knowledge base. |
✓ Yes |
|
rig_relatives |
Input rig relatives contain the a priori knowledge about the relative translation and rotation of secondary cameras. Since these values are supposedly coming from a sensor database, the units are always meters and degrees. |
No |
|
shutter_type |
|
Allowed values : |
✓ Yes |
extensions |
|
JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname |
No |
Spherical internals¶
Spherical internals Properties
Type |
Description |
Required |
|
|---|---|---|---|
type |
|
Must be |
✓ Yes |
principal_point_px |
(x, y) location of the principal point in pixels with (0, 0) being at the top left corner of the top left pixel. |
✓ Yes |
|
extensions |
|
JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname |
No |
Yaw-Pitch-Roll orientation¶
Yaw-Pitch-Roll angles represent a rotation R_z(yaw)R_y(pitch)R_x(roll) from the image CS to navigation CRS base change, where the image CS is right-top-back in image space, the navigation CRS is East-North-Down and angles (0, 0, 0) represent the identity transformation.
Yaw-Pitch-Roll orientation Properties
Type |
Description |
Required |
|
|---|---|---|---|
type |
|
Must be |
✓ Yes |
angles_deg |
|
Yaw, pitch, roll angles in degrees. |
✓ Yes |
sigmas_deg |
|
Error estimation (standard deviation) in degrees. |
✓ Yes |
extensions |
|
JSON object with extension-specific objects. Extensions follow the naming convention VENDOR[_(team❘product)]_extname |
No |
Example¶
{
"format": "application/opf-input-cameras+json",
"version": "1.0",
"sensors": [
{
"id": 18493134,
"name": "Parrot_Sequoia_4_0_1280x960",
"bands": [
{
"name": "Green",
"weight": 1
}
],
"image_size_px": [
1280,
960
],
"pixel_size_um": 3.75,
"internals": {
"type": "fisheye",
"principal_point_px": [
640,
480
],
"affine": [
1674.33,
0.0,
0.0,
1674.33
],
"is_symmetric_affine": true,
"polynomial": [
0.0,
1.0,
0.0152646,
-0.161096
],
"is_p0_zero": true
},
"shutter_type": "global"
},
{
"id": 21845677,
"name": "Parrot_Sequoia_4_0_1280x960",
"bands": [
{
"name": "Red",
"weight": 1
}
],
"image_size_px": [
1280,
960
],
"pixel_size_um": 3.75,
"internals": {
"type": "fisheye",
"principal_point_px": [
640,
480
],
"affine": [
1674.33,
0.0,
0.0,
1674.33
],
"is_symmetric_affine": true,
"polynomial": [
0.0,
1.0,
0.0152646,
-0.161096
],
"is_p0_zero": true
},
"rig_relatives": {
"rotation": {
"angles_deg": [
0,
0,
0
],
"sigmas_deg": [
0.05,
0.05,
0.05
]
},
"translation": {
"values_m": [
-0.015,
0.015,
0.0
],
"sigmas_m": [
0.001,
0.001,
0.001
]
}
},
"shutter_type": "global"
},
{
"id": 65728243,
"name": "Parrot_AnafiThermal_1.9_298x224",
"bands": [
{
"name": "TIR",
"weight": 1
}
],
"image_size_px": [
298,
224
],
"pixel_size_um": 1.9,
"internals": {
"type": "fisheye",
"principal_point_px": [
150,
112
],
"affine": [
496.084717,
0.0,
0.0,
496.084717
],
"is_symmetric_affine": true,
"polynomial": [
0.0,
1.0,
0.0,
0.0
],
"is_p0_zero": true
},
"rig_relatives": {
"rotation": {
"angles_deg": [
0,
0,
0
],
"sigmas_deg": [
0.05,
0.05,
0.05
]
},
"translation": {
"values_m": [
0.0,
0.0,
0.0
],
"sigmas_m": [
0.001,
0.001,
0.001
]
}
},
"shutter_type": "global"
},
{
"id": 86926181,
"name": "Parrot_AnafiThermal_4.0_3264x2448",
"bands": [
{
"name": "Red",
"weight": 0.2126
},
{
"name": "Green",
"weight": 0.7152
},
{
"name": "Blue",
"weight": 0.0722
}
],
"image_size_px": [
3264,
2448
],
"pixel_size_um": 1.5,
"internals": {
"type": "perspective",
"principal_point_px": [
1632,
1224
],
"focal_length_px": 1643,
"radial_distortion": [
-0.014393,
0.0125235,
-2.2309e-05
],
"tangential_distortion": [
0.00127711,
0.000421167
]
},
"shutter_type": "global"
},
{
"id": 57282113,
"name": "DJI_FC6540_24.0_6016x4008",
"bands": [
{
"name": "Red",
"weight": 0.2126
},
{
"name": "Green",
"weight": 0.7152
},
{
"name": "Blue",
"weight": 0.0722
}
],
"image_size_px": [
6016,
4008
],
"pixel_size_um": 1.6,
"internals": {
"type": "perspective",
"principal_point_px": [
3008,
2004
],
"focal_length_px": 5391,
"radial_distortion": [
-0.014393,
0.0125235,
-2.2309e-05
],
"tangential_distortion": [
0.00127711,
0.000421167
]
},
"shutter_type": "rolling"
}
],
"captures": [
{
"id": 19438547,
"rig_model_source": "database",
"cameras": [
{
"sensor_id": 18493134,
"id": 47292894,
"model_source": "database",
"pixel_type": "uint16",
"pixel_range": {
"min": 0,
"max": 63000
}
},
{
"sensor_id": 21845677,
"id": 57282923,
"model_source": "database",
"pixel_type": "uint16",
"pixel_range": {
"min": 0,
"max": 63000
},
"image_orientation": 1
}
],
"reference_camera_id": 47292894,
"geolocation": {
"crs": {
"definition": "EPSG:4326+5773"
},
"coordinates": [
46.522838638888885,
6.549273638888889,
531.239990234375
],
"sigmas": [
1.69,
1.69,
2.4
]
},
"orientation": {
"type": "yaw_pitch_roll",
"angles_deg": [
117.31300354,
9.7998399734,
9.9201202393
],
"sigmas_deg": [
5.0,
5.0,
5.0
]
},
"height_above_takeoff_m": 100.5,
"time": "2016-09-29T11:41:21Z"
},
{
"id": 78291034,
"rig_model_source": "database",
"cameras": [
{
"sensor_id": 65728243,
"id": 42727834,
"model_source": "database",
"pixel_type": "uint16",
"pixel_range": {
"percentile": 1
}
},
{
"sensor_id": 86926181,
"id": 84736329,
"model_source": "database",
"pixel_type": "uint8",
"pixel_range": {
"min": 0,
"max": 255
}
}
],
"reference_camera_id": 42727834,
"geolocation": {
"crs": {
"definition": "EPSG:4326+5773"
},
"coordinates": [
46.522838638888885,
6.549273638888889,
531.239990234375
],
"sigmas": [
1.6900000572,
1.6900000572,
2.4010000229
]
},
"orientation": {
"type": "omega_phi_kappa",
"angles_deg": [
3.3432,
-5.2849554,
9.345113
],
"sigmas_deg": [
5.0,
5.0,
5.0
],
"crs": "EPSG:32632"
},
"height_above_takeoff_m": 100.5,
"time": "2016-09-29T11:41:21Z"
},
{
"id": 92840,
"rig_model_source": "not_applicable",
"cameras": [
{
"sensor_id": 57282113,
"id": 86930102,
"model_source": "database",
"pixel_type": "uint8",
"pixel_range": {
"min": 0,
"max": 255
}
}
],
"reference_camera_id": 86930102,
"geolocation": {
"crs": {
"definition": "EPSG:4326+5773"
},
"coordinates": [
46.522838638888885,
6.549273638888889,
531.239990234375
],
"sigmas": [
1.6900000572,
1.6900000572,
2.4010000229
]
},
"orientation": {
"type": "yaw_pitch_roll",
"angles_deg": [
113.128800287,
10.52342304,
9.9310087264
],
"sigmas_deg": [
5.0,
5.0,
5.0
]
},
"height_above_takeoff_m": 100.5,
"time": "2020-09-25T09:12:53Z"
},
{
"id": 39503,
"rig_model_source": "not_applicable",
"cameras": [
{
"sensor_id": 57282113,
"id": 28493939,
"model_source": "generic",
"pixel_type": "uint8",
"pixel_range": {
"min": 0,
"max": 255
},
"extensions": {
"PIX4D_input_depth_map": {
"version": "1.0-draft2",
"id": 3347,
"confidence": {
"id": 238390,
"min": 1,
"max": 2,
"threshold": 2
}
}
}
}
],
"reference_camera_id": 28493939,
"geolocation": {
"crs": {
"definition": "EPSG:4150"
},
"coordinates": [
6.524116953632,
6.550081187764,
529.75
],
"sigmas": [
1.6900000572,
1.6900000572,
2.4010000229
]
},
"orientation": {
"type": "omega_phi_kappa",
"angles_deg": [
21.1345409,
3.331994,
-1.129403
],
"sigmas_deg": [
5.0,
5.0,
5.0
],
"crs": "EPSG:32632"
},
"height_above_takeoff_m": 100.5,
"time": "2020-09-25T09:13:13Z"
}
]
}