Add the report diagram (made wiht plantuml.com) and move the explanation

to another page, in /usage makes more sense
tudelft3d · Aug 13, 2024 · e519224 · e519224
1 parent 0fb0142
commit e519224
Show file tree

Hide file tree

Showing 3 changed files with 141 additions and 135 deletions.
diff --git a/docs/_static/report_diagram.svg b/docs/_static/report_diagram.svg
diff --git a/docs/faq.rst b/docs/faq.rst
@@ -19,141 +19,6 @@ This tests, among many others, the following:
 You can read more about the `details <https://github.com/tudelft3d/val3dity/blob/main/tests/README.md>`_, or check the `complete list of tested geometries <https://github.com/tudelft3d/val3dity/blob/main/data/test_metadata.yml>`_
 
 
-How to interpret the report?
-----------------------------
-
-With the option ``--report`` a JSON report is output.
-
-The report lists the errors at two levels:
-
-  1. errors with the input files (errors 9xx)
-  2. all other errors, per feature (eg for each Building the list of errors is given)
-
-The report contains several properties, one example: 
-
-.. code-block:: json
-
-  {
-    "type": "val3dity_report",
-    "time": "2024-05-21T12:16:50 (CEST)",
-    "input_file": "/home/elvis/myfile.city.json",
-    "input_file_type": "CityJSON",
-    "val3dity_version": "2.5.0",
-    "validity": false,
-    "parameters": {
-      "overlap_tol": -1.0,
-      "planarity_d2p_tol": 0.01,
-      "planarity_n_tol": 20.0,
-      "snap_tol": 0.001
-    },
-    "all_errors": [102, 104, 203, 601],
-    "dataset_errors": [],
-    "features_overview": [
-      {
-        "total": 644,
-        "type": "Building",
-        "valid": 324
-      },
-      {
-        "total": 1,
-        "type": "TINRelief",
-        "valid": 1
-      }
-    ],
-    "primitives_overview": [
-      {
-        "total": 1490,
-        "type": "Solid",
-        "valid": 1305
-      },
-      {
-        "total": 1,
-        "type": "CompositeSurface",
-        "valid": 1
-      }
-    ],
-    "features": []
-  }
-
-
-The property ``"validity"`` is used to report whether the file is 100% valid, or not.
-If it's invalid, then ``"all_errors"`` lists all the error codes present in the input file (the list is empty if the file is valid).
-
-``"dataset_errors"`` lists all the errors related to the input file (errors 9xx).
-
-``"features_overview"`` gives you an overview of the features in the file, in this case there were 644 Buildings and 1 TINRelief.
-
-``"primitives_overview"`` gives you, similarly, an overview of the geometric primitives.
-
-The ``"features"`` property list all the features in the file, and for each the errors are reported, if any.
-An example is as follows:
-
-.. code-block:: json
-
-  {
-    "features": [
-      {
-        "id": "GUID_0048B9B9-8028-4C01-9D55-6D96F0AB3A15",
-        "type": "Building",
-        "validity": true,
-        "errors": []
-      },
-      {
-        "id": "GUID_00D36CED-764E-4631-B88C-EA98528BA782",
-        "type": "Building",
-        "validity": false,
-        "errors": [
-          {
-            "code": 203,
-            "description": "NON_PLANAR_POLYGON_DISTANCE_PLANE",
-            "id": "coid=GUID_00D36CED-764E-4631-B88C-EA98528BA782_1|geom=0|shell=0|face=4",
-            "info": "distance to fitted plane: 0.0122035 (tolerance=0.01)"
-          }
-        ]
-      },
-      {
-        "id": "GUID_00723D18-2A2C-47B4-ACF3-F5B6F4EC7224",
-        "type": "Building",
-        "validity": true,
-        "errors": [],
-      },
-      {
-        "id": "GUID_032A685A-1262-4157-A797-C9ED49A65725",
-        "type": "Building",
-        "validity": false
-        "errors": [
-          {
-            "code": 601,
-            "description": "BUILDINGPARTS_OVERLAP",
-            "id": "coid=GUID_032A685A-1262-4157-A797-C9ED49A65725_1|geom=0&&coid=GUID_032A685A-1262-4157-A797-C9ED49A65725_2|geom=0",
-            "info": "geometries are lod=2",
-            "type": "Error"
-          }
-        ],
-      },
-    ]
-  } 
-
-
-For each primitive, its identifier is (``"id"``) is given, its ``"type"``, and its ``"validity"``.
-The ``"errors"`` property is always listed, and it is an array of the errors; it is an empty array if the feature is valid.
-
-Because a feature (eg a Building) can contain several geometries and children (eg the BuildingPart of a Building), we report the error by giving extra information about its location.
-``coid=`` tells you the City Object identifier.
-``geom=0`` tells you that it's the first geometry in the list of geometries (if CityJSON is used), and similarly ``solid=1`` would indicate the second solid in a MultiSolid, ``shell=1`` would indicate that the 2nd shell in the Solid has an issue, and ``face=13`` would mean the 14th surface listed in the primitive has an issue.
-A 0-based system is used for reporting. 
-
-You can navigate this report with a JSON browser (eg drag it into an empty window in Firefox) or by loading it to the `val3dity report browser <http://geovalidation.bk.tudelft.nl/val3dity/browser/>`_:
-
-.. image:: _static/report1.png
-   :width: 49%
-.. image:: _static/report2.png
-   :width: 49%
-
-There you get an overview of the statistics per features and primitives, and each feature has its errors as children.   
-
-
-
 I get many errors 203 and 204, but my planes look planar to me. Why is that?
 ----------------------------------------------------------------------------
 

diff --git a/docs/usage.rst b/docs/usage.rst
@@ -112,6 +112,146 @@ The formal definitions of the 3D primitives, along with explanations, are given
    :width: 60%
 
 
+How to interpret the report?
+----------------------------
+
+With the option ``--report`` a JSON report is output.
+
+The report lists the errors at two levels:
+
+  1. errors with the input files (errors 9xx)
+  2. all other errors, per feature (eg for each Building the list of errors is given)
+
+This is a diagram of the structure of the report; watch out not all options for the properties are shown.
+
+.. image:: _static/report_diagram.svg
+   :width: 100%
+
+
+The report contains several properties, one example: 
+
+.. code-block:: json
+
+  {
+    "type": "val3dity_report",
+    "time": "2024-05-21T12:16:50 (CEST)",
+    "input_file": "/home/elvis/myfile.city.json",
+    "input_file_type": "CityJSON",
+    "val3dity_version": "2.5.0",
+    "validity": false,
+    "parameters": {
+      "overlap_tol": -1.0,
+      "planarity_d2p_tol": 0.01,
+      "planarity_n_tol": 20.0,
+      "snap_tol": 0.001
+    },
+    "all_errors": [102, 104, 203, 601],
+    "dataset_errors": [],
+    "features_overview": [
+      {
+        "total": 644,
+        "type": "Building",
+        "valid": 324
+      },
+      {
+        "total": 1,
+        "type": "TINRelief",
+        "valid": 1
+      }
+    ],
+    "primitives_overview": [
+      {
+        "total": 1490,
+        "type": "Solid",
+        "valid": 1305
+      },
+      {
+        "total": 1,
+        "type": "CompositeSurface",
+        "valid": 1
+      }
+    ],
+    "features": []
+  }
+
+
+The property ``"validity"`` is used to report whether the file is 100% valid, or not.
+If it's invalid, then ``"all_errors"`` lists all the error codes present in the input file (the list is empty if the file is valid).
+
+``"dataset_errors"`` lists all the errors related to the input file (errors 9xx).
+
+``"features_overview"`` gives you an overview of the features in the file, in this case there were 644 Buildings and 1 TINRelief.
+
+``"primitives_overview"`` gives you, similarly, an overview of the geometric primitives.
+
+The ``"features"`` property list all the features in the file, and for each the errors are reported, if any.
+An example is as follows:
+
+.. code-block:: json
+
+  {
+    "features": [
+      {
+        "id": "GUID_0048B9B9-8028-4C01-9D55-6D96F0AB3A15",
+        "type": "Building",
+        "validity": true,
+        "errors": []
+      },
+      {
+        "id": "GUID_00D36CED-764E-4631-B88C-EA98528BA782",
+        "type": "Building",
+        "validity": false,
+        "errors": [
+          {
+            "code": 203,
+            "description": "NON_PLANAR_POLYGON_DISTANCE_PLANE",
+            "id": "coid=GUID_00D36CED-764E-4631-B88C-EA98528BA782_1|geom=0|shell=0|face=4",
+            "info": "distance to fitted plane: 0.0122035 (tolerance=0.01)"
+          }
+        ]
+      },
+      {
+        "id": "GUID_00723D18-2A2C-47B4-ACF3-F5B6F4EC7224",
+        "type": "Building",
+        "validity": true,
+        "errors": [],
+      },
+      {
+        "id": "GUID_032A685A-1262-4157-A797-C9ED49A65725",
+        "type": "Building",
+        "validity": false,
+        "errors": [
+          {
+            "code": 601,
+            "description": "BUILDINGPARTS_OVERLAP",
+            "id": "coid=GUID_032A685A-1262-4157-A797-C9ED49A65725_1|geom=0&&coid=GUID_032A685A-1262-4157-A797-C9ED49A65725_2|geom=0",
+            "info": "geometries are lod=2",
+            "type": "Error"
+          }
+        ]
+      }
+    ]
+  } 
+
+
+For each primitive, its identifier is (``"id"``) is given, its ``"type"``, and its ``"validity"``.
+The ``"errors"`` property is always listed, and it is an array of the errors; it is an empty array if the feature is valid.
+
+Because a feature (eg a Building) can contain several geometries and children (eg the BuildingPart of a Building), we report the error by giving extra information about its location.
+``coid=`` tells you the City Object identifier.
+``geom=0`` tells you that it's the first geometry in the list of geometries (if CityJSON is used), and similarly ``solid=1`` would indicate the second solid in a MultiSolid, ``shell=1`` would indicate that the 2nd shell in the Solid has an issue, and ``face=13`` would mean the 14th surface listed in the primitive has an issue.
+A 0-based system is used for reporting. 
+
+You can navigate this report with a JSON browser (eg drag it into an empty window in Firefox) or by loading it to the `val3dity report browser <http://geovalidation.bk.tudelft.nl/val3dity/browser/>`_:
+
+.. image:: _static/report1.png
+   :width: 49%
+.. image:: _static/report2.png
+   :width: 49%
+
+There you get an overview of the statistics per features and primitives, and each feature has its errors as children.   
+
+
 
 Options for the validation
 --------------------------