From 6b1161e676b95b631206761c7a9dae37f874d645 Mon Sep 17 00:00:00 2001
From: unexcellent <>
Date: Mon, 4 Nov 2024 08:08:14 +0100
Subject: [PATCH] feat: add JSON annotations

---
 raillabel/json_format/bbox.py   | 33 ++++++++++++++++++++++++++++
 raillabel/json_format/cuboid.py | 35 +++++++++++++++++++++++++++++
 raillabel/json_format/num.py    | 29 ++++++++++++++++++++++++
 raillabel/json_format/poly2d.py | 39 +++++++++++++++++++++++++++++++++
 raillabel/json_format/poly3d.py | 33 ++++++++++++++++++++++++++++
 raillabel/json_format/vec.py    | 34 ++++++++++++++++++++++++++++
 6 files changed, 203 insertions(+)
 create mode 100644 raillabel/json_format/bbox.py
 create mode 100644 raillabel/json_format/cuboid.py
 create mode 100644 raillabel/json_format/num.py
 create mode 100644 raillabel/json_format/poly2d.py
 create mode 100644 raillabel/json_format/poly3d.py
 create mode 100644 raillabel/json_format/vec.py

diff --git a/raillabel/json_format/bbox.py b/raillabel/json_format/bbox.py
new file mode 100644
index 0000000..bcccbbd
--- /dev/null
+++ b/raillabel/json_format/bbox.py
@@ -0,0 +1,33 @@
+# Copyright DB InfraGO AG and contributors
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel
+
+from .attributes import JSONAttributes
+
+
+class JSONBbox(BaseModel):
+    """A 2D bounding box is defined as a 4-dimensional vector [x, y, w, h].
+
+    [x, y] is the center of the bounding box and [w, h] represent the width (horizontal,
+    x-coordinate dimension) and height (vertical, y-coordinate dimension), respectively.
+    """
+
+    name: str
+    """This is a string encoding the name of this object data. It is used as index inside the
+    corresponding object data pointers."""
+
+    val: tuple[float, float, float, float]
+    "The array of 4 values that define the [x, y, w, h] values of the bbox."
+
+    coordinate_system: str | None
+    "Name of the coordinate system in respect of which this object data is expressed."
+
+    uid: UUID | None
+    "This is a string encoding the Universal Unique identifyer of the annotation."
+
+    attributes: JSONAttributes | None
diff --git a/raillabel/json_format/cuboid.py b/raillabel/json_format/cuboid.py
new file mode 100644
index 0000000..991013e
--- /dev/null
+++ b/raillabel/json_format/cuboid.py
@@ -0,0 +1,35 @@
+# Copyright DB InfraGO AG and contributors
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel
+
+from .attributes import JSONAttributes
+
+
+class JSONCuboid(BaseModel):
+    """A cuboid or 3D bounding box.
+
+    It is defined by the position of its center, the rotation in 3D, and its dimensions.
+    """
+
+    name: str
+    """This is a string encoding the name of this object data. It is used as index inside the
+    corresponding object data pointers."""
+
+    val: tuple[float, float, float, float, float, float, float, float, float, float]
+    """List of values encoding the position, rotation and dimensions. It is
+    (x, y, z, qx, qy, qz, qw, sx, sy, sz) where (x, y, z) encodes the position, (qx, qy, qz, qw)
+    encodes the quaternion that encode the rotation, and (sx, sy, sz) are the dimensions of the
+    cuboid in its object coordinate system"""
+
+    coordinate_system: str | None
+    "Name of the coordinate system in respect of which this object data is expressed."
+
+    uid: UUID | None
+    "This is a string encoding the Universal Unique identifyer of the annotation."
+
+    attributes: JSONAttributes | None
diff --git a/raillabel/json_format/num.py b/raillabel/json_format/num.py
new file mode 100644
index 0000000..2898e2f
--- /dev/null
+++ b/raillabel/json_format/num.py
@@ -0,0 +1,29 @@
+# Copyright DB InfraGO AG and contributors
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel
+
+from .attributes import JSONAttributes
+
+
+class JSONNum(BaseModel):
+    """A number."""
+
+    name: str
+    """This is a string encoding the name of this object data. It is used as index inside the
+    corresponding object data pointers."""
+
+    val: list[int]
+    "The numerical value of the number."
+
+    coordinate_system: str | None
+    "Name of the coordinate system in respect of which this object data is expressed."
+
+    uid: UUID | None
+    "This is a string encoding the Universal Unique identifyer of the annotation."
+
+    attributes: JSONAttributes | None
diff --git a/raillabel/json_format/poly2d.py b/raillabel/json_format/poly2d.py
new file mode 100644
index 0000000..3519d0e
--- /dev/null
+++ b/raillabel/json_format/poly2d.py
@@ -0,0 +1,39 @@
+# Copyright DB InfraGO AG and contributors
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel
+
+from .attributes import JSONAttributes
+
+
+class JSONPoly2d(BaseModel):
+    """A 2D polyline defined as a sequence of 2D points."""
+
+    name: str
+    """This is a string encoding the name of this object data. It is used as index inside the
+    corresponding object data pointers."""
+
+    val: list[float | str]
+    "List of numerical values of the polyline, according to its mode."
+
+    closed: bool
+    """A boolean that defines whether the polyline is closed or not. In case it is closed, it is
+    assumed that the last point of the sequence is connected with the first one."""
+
+    mode: Literal["MODE_POLY2D_ABSOLUTE"]
+    """Mode of the polyline describes how the points should be arranged in the images.
+    MODE_POLY2D_ABSOLUTE means that any point defined by an x-value followed by a y-value is the
+    absolute position."""
+
+    coordinate_system: str | None
+    "Name of the coordinate system in respect of which this object data is expressed."
+
+    uid: UUID | None
+    "This is a string encoding the Universal Unique identifyer of the annotation."
+
+    attributes: JSONAttributes | None
diff --git a/raillabel/json_format/poly3d.py b/raillabel/json_format/poly3d.py
new file mode 100644
index 0000000..6c6e15f
--- /dev/null
+++ b/raillabel/json_format/poly3d.py
@@ -0,0 +1,33 @@
+# Copyright DB InfraGO AG and contributors
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel
+
+from .attributes import JSONAttributes
+
+
+class JSONPoly2d(BaseModel):
+    """A 3D polyline defined as a sequence of 3D points."""
+
+    name: str
+    """This is a string encoding the name of this object data. It is used as index inside the
+    corresponding object data pointers."""
+
+    val: list[float]
+    "List of numerical values of the polyline, according to its mode."
+
+    closed: bool
+    """A boolean that defines whether the polyline is closed or not. In case it is closed, it is
+    assumed that the last point of the sequence is connected with the first one."""
+
+    coordinate_system: str | None
+    "Name of the coordinate system in respect of which this object data is expressed."
+
+    uid: UUID | None
+    "This is a string encoding the Universal Unique identifyer of the annotation."
+
+    attributes: JSONAttributes | None
diff --git a/raillabel/json_format/vec.py b/raillabel/json_format/vec.py
new file mode 100644
index 0000000..842c00f
--- /dev/null
+++ b/raillabel/json_format/vec.py
@@ -0,0 +1,34 @@
+# Copyright DB InfraGO AG and contributors
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel
+
+from .attributes import JSONAttributes
+
+
+class JSONPoly2d(BaseModel):
+    """A vector (list) of numbers."""
+
+    name: str
+    """This is a string encoding the name of this object data. It is used as index inside the
+    corresponding object data pointers."""
+
+    val: list[float]
+    "The numerical values of the vector (list) of numbers."
+
+    coordinate_system: str | None
+    "Name of the coordinate system in respect of which this object data is expressed."
+
+    uid: UUID | None
+    "This is a string encoding the Universal Unique identifyer of the annotation."
+
+    type: Literal["values", "range"] | None
+    """This attribute specifies whether the vector shall be considered as a descriptor of individual
+    values or as a definition of a range."""
+
+    attributes: JSONAttributes | None