From 0268daff2d8b9aa66c6c959a887bd27b7a210a15 Mon Sep 17 00:00:00 2001 From: Mateo de Mayo Date: Tue, 23 Nov 2021 16:37:52 -0300 Subject: [PATCH] doc: Add json schema for new calibration file --- doc/CMakeLists.txt | 10 +- .../calibration_v2.example.json | 90 +++++++ .../calibration_v2.example.json.license | 2 + .../calibration_v2.schema.json | 222 ++++++++++++++++++ .../calibration_v2.schema.json.license | 2 + doc/example_configs/config_v0.schema.json | 2 +- 6 files changed, 326 insertions(+), 2 deletions(-) create mode 100644 doc/example_configs/calibration_v2.example.json create mode 100644 doc/example_configs/calibration_v2.example.json.license create mode 100644 doc/example_configs/calibration_v2.schema.json create mode 100644 doc/example_configs/calibration_v2.schema.json.license diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 5ee98dce9..b8a69228d 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -34,7 +34,7 @@ if(BUILD_DOC) # request to configure the file configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY) - # copy the schema + # copy the schemas configure_file( ${CMAKE_CURRENT_SOURCE_DIR}/example_configs/config_v0.schema.json ${CMAKE_CURRENT_BINARY_DIR}/html/config_v0.schema.json @ONLY @@ -43,6 +43,14 @@ if(BUILD_DOC) ${CMAKE_CURRENT_SOURCE_DIR}/example_configs/config_v0.schema.json.license ${CMAKE_CURRENT_BINARY_DIR}/html/config_v0.schema.json.license @ONLY ) + configure_file( + ${CMAKE_CURRENT_SOURCE_DIR}/example_configs/calibration_v2.schema.json + ${CMAKE_CURRENT_BINARY_DIR}/html/calibration_v2.schema.json @ONLY + ) + configure_file( + ${CMAKE_CURRENT_SOURCE_DIR}/example_configs/calibration_v2.schema.json.license + ${CMAKE_CURRENT_BINARY_DIR}/html/calibration_v2.schema.json.license @ONLY + ) # note the option ALL which allows to build the docs together with the application add_custom_target( diff --git a/doc/example_configs/calibration_v2.example.json b/doc/example_configs/calibration_v2.example.json new file mode 100644 index 000000000..9e55985bc --- /dev/null +++ b/doc/example_configs/calibration_v2.example.json @@ -0,0 +1,90 @@ +{ + "$schema": "https://monado.pages.freedesktop.org/monado/calibration_v2.schema.json", + "file": { + "version": 2, + "created_on": "2021-11-23T14:33:51Z" + }, + "cameras": [ + { + "name": "Fake Camera 0", + "model": "fisheye_equidistant4", + "intrinsics": { + "fx": 428.485, + "fy": 428.485, + "cx": 423.567, + "cy": 240.114 + }, + "distortion": { + "k1": 0, + "k2": 0, + "k3": 0, + "k4": 0 + }, + "resolution": { + "width": 848, + "height": 480 + } + }, + { + "name": "Fake Camera 1", + "model": "pinhole_radtan5", + "intrinsics": { + "fx": 428.485, + "fy": 428.485, + "cx": 423.567, + "cy": 240.114 + }, + "distortion": { + "k1": 0, + "k2": 0, + "p1": 0, + "p2": 0, + "k3": 0 + }, + "resolution": { + "width": 848, + "height": 480 + } + } + ], + "opencv_stereo_calibrate": { + "rotation": [ + 0.95321815970241375, + 0.0408369712626572, + -0.29951207286457837, + -0.0679705814297339, + 0.99441512328599491, + -0.080737616017587777, + 0.29454225515814791, + 0.097318571496875367, + 0.950670266479477 + ], + "translation": [ + 1.4416754185893419, + 1.176208605914552, + -4.208172261903619 + ], + "essential": [ + 0.060411219924425982, + 4.2991370799395261, + 0.77842875260280309, + -4.4359405481998833, + -0.31215080202694384, + -0.11015955723326701, + -1.2191749191904835, + 1.385591042076286, + 0.23589124131056205 + ], + "fundamental": [ + -2.9769859891445467e-07, + -2.8163083335581391e-05, + -0.0139603067332745, + 1.2138399250016221e-05, + 1.1354810181647868e-06, + -0.0015106776411851692, + 0.0061879358690168085, + 0.0041368502945713613, + 1 + ] + } +} diff --git a/doc/example_configs/calibration_v2.example.json.license b/doc/example_configs/calibration_v2.example.json.license new file mode 100644 index 000000000..a1d1e58cc --- /dev/null +++ b/doc/example_configs/calibration_v2.example.json.license @@ -0,0 +1,2 @@ +Copyright 2021, Collabora, Ltd. +SPDX-License-Identifier: CC0-1.0 diff --git a/doc/example_configs/calibration_v2.schema.json b/doc/example_configs/calibration_v2.schema.json new file mode 100644 index 000000000..9d427f2a4 --- /dev/null +++ b/doc/example_configs/calibration_v2.schema.json @@ -0,0 +1,222 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema", + "title": "Monado calibration file schema v2", + "type": "object", + "required": [ + "file", + "cameras", + "opencv_stereo_calibrate" + ], + "properties": { + "$schema": { + "type": "string", + "title": "JSON Schema directive", + "default": "https://monado.pages.freedesktop.org/monado/calibration_v2.schema.json" + }, + "file": { + "description": "Calibration file metadata", + "type": "object", + "required": [ + "version" + ], + "properties": { + "version": { + "const": 2 + }, + "created_on": { + "$ref": "#/$defs/datetime" + } + } + }, + "cameras": { + "type": "array", + "minItems": 2, + "maxItems": 2, + "description": "Stereo calibrated cameras", + "items": { + "$ref": "#/$defs/camera" + } + }, + "opencv_stereo_calibrate": { + "$ref": "#/$defs/opencv_stereo_calibrate" + } + }, + "$defs": { + "camera": { + "type": "object", + "required": [ + "name", + "model", + "intrinsics", + "distortion", + "resolution" + ], + "properties": { + "name": { + "$ref": "#/$defs/camera_name" + }, + "model": { + "description": "Camera and distortion model", + "enum": [ + "pinhole_radtan5", + "fisheye_equidistant4" + ] + }, + "intrinsics": { + "type": "object", + "required": [ + "fx", + "fy", + "cx", + "cy" + ], + "properties": { + "fx": { + "type": "number" + }, + "fy": { + "type": "number" + }, + "cx": { + "type": "number" + }, + "cy": { + "type": "number" + } + } + }, + "distortion": { + "description": "Parameters for the specified distortion model. radtan5: k1,k2,p1,p2,k3. equidistant4: k1,k2,k3,k4.", + "$comment": "There is no easy way to enforce the fields parameters in the schema based on the `model` property, the if-then validation could help but still would be very cumbersome.", + "oneOf": [ + { + "$ref": "#/$defs/equidistant4" + }, + { + "$ref": "#/$defs/radtan5" + } + ] + }, + "resolution": { + "type": "object", + "required": [ + "width", + "height" + ], + "properties": { + "width": { + "type": "integer" + }, + "height": { + "type": "integer" + } + } + } + } + }, + "camera_name": { + "description": "Display name; not necessarily unique.", + "type": "string", + "maxLength": 128 + }, + "opencv_stereo_calibrate": { + "description": "Data produced by cv::stereoCalibrate.", + "type": "object", + "required": [ + "rotation", + "translation", + "essential", + "fundamental" + ], + "additionalProperties": false, + "properties": { + "rotation": { + "$ref": "#/$defs/mat3x3d" + }, + "translation": { + "$ref": "#/$defs/mat3x1d" + }, + "essential": { + "$ref": "#/$defs/mat3x3d" + }, + "fundamental": { + "$ref": "#/$defs/mat3x3d" + } + } + }, + "mat3x3d": { + "type": "array", + "items": { + "type": "number" + }, + "minItems": 9, + "maxItems": 9 + }, + "mat3x1d": { + "type": "array", + "items": { + "type": "number" + }, + "minItems": 3, + "maxItems": 3 + }, + "equidistant4": { + "type": "object", + "required": [ + "k1", + "k2", + "k3", + "k4" + ], + "additionalProperties": false, + "properties": { + "k1": { + "type": "number" + }, + "k2": { + "type": "number" + }, + "k3": { + "type": "number" + }, + "k4": { + "type": "number" + } + } + }, + "radtan5": { + "type": "object", + "required": [ + "k1", + "k2", + "p1", + "p2", + "k3" + ], + "additionalProperties": false, + "properties": { + "k1": { + "type": "number" + }, + "k2": { + "type": "number" + }, + "p1": { + "type": "number" + }, + "p2": { + "type": "number" + }, + "k3": { + "type": "number" + } + } + }, + "datetime": { + "$comment": "The format specification might not be asserted against, that's why we also provide a regex pattern", + "type": "string", + "format": "date-time", + "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$" + } + } +} diff --git a/doc/example_configs/calibration_v2.schema.json.license b/doc/example_configs/calibration_v2.schema.json.license new file mode 100644 index 000000000..a1d1e58cc --- /dev/null +++ b/doc/example_configs/calibration_v2.schema.json.license @@ -0,0 +1,2 @@ +Copyright 2021, Collabora, Ltd. +SPDX-License-Identifier: CC0-1.0 diff --git a/doc/example_configs/config_v0.schema.json b/doc/example_configs/config_v0.schema.json index bdd8c9cef..a88c02cab 100644 --- a/doc/example_configs/config_v0.schema.json +++ b/doc/example_configs/config_v0.schema.json @@ -204,7 +204,7 @@ "w" ] }, - "vec3": { + "vector3": { "type": "object", "title": "Vector3", "properties": {