chore: sync table definition with tier4_perception_dataset (#185)

* update table definitions

* remove lidarseg

* style(pre-commit): autofix

* updated tests

* style(pre-commit): autofix

* removed redundancy

* style(pre-commit): autofix

* fixed test failures

* add ke_only

* style(pre-commit): autofix

* added test for autolabel_metadata

* style(pre-commit): autofix

Author: SamratThapa120

docs/schema/table.md

@@ -2,16 +2,17 @@
 
 ## Type Definition
 
-| Expression      | Description                                                                                                    |
-| --------------- | -------------------------------------------------------------------------------------------------------------- |
-| `str`           | String                                                                                                         |
-| `int`           | Integer                                                                                                        |
-| `float`         | Floating point number                                                                                          |
-| `bool`          | Boolean                                                                                                        |
-| `enum[X,Y,...]` | Enumerated type with possible values X, Y, ...                                                                 |
-| `[T;N]`         | Array of N elements of type T                                                                                  |
-| `option[T]`     | Optional value of type T                                                                                       |
-| `RLE`           | Run-length encoding given as `{"size": <[int;2]>, "counts": <str>}`, where `size` represents `(width, height)` |
+| Expression       | Description                                                                                                    |
+| ---------------- | -------------------------------------------------------------------------------------------------------------- |
+| `str`            | String                                                                                                         |
+| `int`            | Integer                                                                                                        |
+| `float`          | Floating point number                                                                                          |
+| `bool`           | Boolean                                                                                                        |
+| `enum[X,Y,...]`  | Enumerated type with possible values X, Y, ...                                                                 |
+| `[T;N]`          | Array of N elements of type T                                                                                  |
+| `option[T]`      | Optional value of type T                                                                                       |
+| `RLE`            | Run-length encoding given as `{"size": <[int;2]>, "counts": <str>}`, where `size` represents `(width, height)` |
+| `AutolabelModel` | Autolabel model information given as `{"name": <str>, "score": <float>, "uncertainty": <option[float]>}`       |
 
 ## Mandatory Tables
 
@@ -68,6 +69,8 @@ category {
   "name":               <str> -- Name of the category.
   "description":        <str> -- Description of the category.
   "index":              <option[int]> -- Category index, this is added to support `lidarseg`, or `None` when it doesn't support `lidarseg`.
+  "has_orientation":    <bool> -- Indicates whether annotations for this category may include an `orientation` field (e.g., traffic light arrows). If omitted, it is treated as `false`.
+  "has_number":         <bool> -- Indicates whether annotations for this category may include a `number` field (e.g., numeric traffic lights). If omitted, it is treated as `false`.
 }
 ```
 
@@ -178,6 +181,7 @@ sample_annotation {
   "next":                   <str> -- Foreign key to the `SampleAnnotation` table associated with the next annotation in the sequence. Empty string `""` if this is the last annotation.
   "prev":                   <str> -- Foreign key to the `SampleAnnotation` table associated with the previous annotation in the sequence. Empty string `""` if this is the first annotation.
   "automatic_annotation":   <bool> -- Indicates whether the annotation was automatically generated. Defaults to `false`.
+  "autolabel_metadata":     <option[[AutolabelModel;N]]> -- List of models used for autolabeling. Required if `automatic_annotation` is `true`.
 }
 ```
 
@@ -204,6 +208,7 @@ sample_data {
   "prev":                     <str> -- Foreign key to the `SampleData` table associated with the previous data in the sequence. Empty string `""` if this is the first data.
   "is_valid":                 <bool> -- Indicates whether this data is valid. Defaults to `true`.
   "info_filename":            <option[str]> -- Relative path to metadata-blob file.
+  "autolabel_metadata":       <option[[AutolabelModel;N]]> -- List of models used for autolabeling applied to this entire sample_data item (e.g., image or scan).
 }
 ```
 
@@ -295,7 +300,10 @@ object_ann {
   "attribute_tokens":         <[str;N]> -- Foreign keys to the `Attribute` table associated with the attributes of the object.
   "bbox":                     <[int;4]> -- Bounding box coordinates in the format (xmin, ymin, xmax, ymax).
   "mask":                     <RLE> -- Run length encoding of instance mask.
+  "orientation":              <option[float]> -- Orientation of the arrow shape within the bounding box, in radians. Present only for categories where `has_orientation` is true (e.g., traffic light arrows).
+  "number":                   <option[int]> -- The digit displayed within the bounding box. Present only for categories where `has_number` is true (e.g., numeric traffic lights).
   "automatic_annotation":     <bool> -- Whether the annotation was automatically generated. Defaults to `false`.
+  "autolabel_metadata":       <option[[AutolabelModel;N]]> -- List of models used for autolabeling. Required if `automatic_annotation` is `true`.
 }
 ```
 
@@ -312,6 +320,7 @@ surface_ann {
   "category_token":           <str> -- Foreign key to the `Category` table associated with the category of the surface.
   "mask":                     <RLE> -- Run length encoding of instance mask.
   "automatic_annotation":     <bool> -- Whether the annotation was automatically generated. Defaults to `false`.
+  "autolabel_metadata":       <option[[AutolabelModel;N]]> -- List of models used for autolabeling. Required if `automatic_annotation` is `true`.
 }
 ```
 
@@ -343,3 +352,15 @@ vehicle_state {
   "additional_info":          <option[AdditionalInfo]> -- Additional information about the vehicle state.
 }
 ```
+
+## AutolabelModel Definition
+
+The `AutolabelModel` type used in `autolabel_metadata` fields has the following structure:
+
+```json
+AutolabelModel {
+  "name":                     <str> -- Name of the model used for annotation. Can include version information.
+  "score":                    <float> -- Label score for the annotation from this model (range: 0.0–1.0).
+  "uncertainty":              <option[float]> -- Model-reported uncertainty for the annotation (range: 0.0–1.0). Lower values imply higher confidence.
+}
+```

t4_devkit/schema/tables/__init__.py

@@ -1,4 +1,5 @@
 from .attribute import *  # noqa
+from .autolabel_metadata import *  # noqa
 from .base import *  # noqa
 from .calibrated_sensor import *  # noqa
 from .category import *  # noqa

t4_devkit/schema/tables/autolabel_metadata.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from attrs import define, field, validators
+
+__all__ = ["AutolabelModel", "AutolabelMixin"]
+
+
+@define
+class AutolabelModel:
+    """A dataclass to represent a model used in autolabeling.
+
+    Attributes:
+        name (str): Name of the model used for annotation. Can include version information.
+        score (float): Label score for the annotation from this model (range: 0.0–1.0).
+        uncertainty (float | None, optional): Model-reported uncertainty for the annotation (range: 0.0–1.0).
+            Lower values imply higher confidence.
+    """
+
+    name: str = field(validator=validators.instance_of(str))
+    score: float = field(
+        validator=[
+            validators.instance_of(float),
+            validators.and_(validators.ge(0.0), validators.le(1.0)),
+        ]
+    )
+    uncertainty: float | None = field(
+        default=None,
+        validator=validators.optional(
+            (validators.instance_of(float), validators.and_(validators.ge(0.0), validators.le(1.0)))
+        ),
+    )
+
+    @staticmethod
+    def to_autolabel_model(x) -> list[AutolabelModel] | None:
+        """Convert input to a list of AutolabelModel instances.
+
+        Args:
+            x: Input to convert. Can be None, a list of dicts, or a list of AutolabelModel instances.
+
+        Returns:
+            list[AutolabelModel] | None: Converted list of AutolabelModel instances or None.
+        """
+        if x is None:
+            return None
+        if isinstance(x, list):
+            return [AutolabelModel(**model) if isinstance(model, dict) else model for model in x]
+        raise TypeError("Input must be None or a list of [dicts or AutolabelModel] instances.")
+
+
+@define(slots=False)
+class AutolabelMixin:
+    """Mixin class for schema tables that use autolabel metadata with automatic annotation."""
+
+    automatic_annotation: bool = field(
+        default=False, validator=validators.instance_of(bool), kw_only=True
+    )
+    autolabel_metadata: list[AutolabelModel] | None = field(
+        default=None,
+        converter=AutolabelModel.to_autolabel_model,
+        validator=validators.optional(
+            validators.deep_iterable(validators.instance_of(AutolabelModel))
+        ),
+        kw_only=True,
+    )
+
+    def __attrs_post_init__(self) -> None:
+        """Post-initialization validation for autolabel consistency."""
+        # if automatic_annotation=True, autolabel_metadata must exist
+        if self.automatic_annotation and self.autolabel_metadata is None:
+            raise TypeError("autolabel_metadata must be provided when automatic_annotation is True")
+        # if automatic_annotation=False, autolabel_metadata must not exist
+        if not self.automatic_annotation and self.autolabel_metadata is not None:
+            raise TypeError("autolabel_metadata must be None when automatic_annotation is False")

t4_devkit/schema/tables/category.py

@@ -19,10 +19,14 @@ class Category(SchemaBase):
         name (str): Category name.
         description (str): Category description.
         index (int | None, optional): Category index for lidar segmentation.
+        has_orientation (bool | None, optional): Indicates whether annotations for this category may include an `orientation` field (e.g., traffic light arrows). If omitted, it is treated as `false`.
+        has_number (bool | None, optional): Indicates whether annotations for this category may include a `number` field (e.g., numeric traffic lights). If omitted, it is treated as `false`.
     """
 
     name: str = field(validator=validators.instance_of(str))
     description: str = field(validator=validators.instance_of(str))
     index: int | None = field(
         default=None, validator=validators.optional(validators.instance_of(int))
     )
+    has_orientation: bool = field(default=False, validator=validators.instance_of(bool))
+    has_number: bool = field(default=False, validator=validators.instance_of(bool))

t4_devkit/schema/tables/object_ann.py

@@ -9,6 +9,7 @@
 from t4_devkit.typing import Roi
 
 from ..name import SchemaName
+from .autolabel_metadata import AutolabelMixin
 from .base import SchemaBase
 from .registry import SCHEMAS
 
@@ -51,7 +52,7 @@ def decode(self) -> NDArrayU8:
 
 @define(slots=False)
 @SCHEMAS.register(SchemaName.OBJECT_ANN)
-class ObjectAnn(SchemaBase):
+class ObjectAnn(SchemaBase, AutolabelMixin):
     """A dataclass to represent schema table of `object_ann.json`.
 
     Attributes:
@@ -62,8 +63,13 @@ class ObjectAnn(SchemaBase):
         attribute_tokens (list[str]): Foreign keys. List of attributes for this annotation.
         bbox (Roi): Annotated bounding box. Given as [xmin, ymin, xmax, ymax].
         mask (RLEMask): Instance mask using the COCO format compressed by RLE.
+        orientation (float | None, optional): Orientation of the arrow shape within the bounding box, in radians. Present only for categories where `has_orientation` is true (e.g., traffic light arrows).
+        number (int | None, optional): The digit displayed within the bounding box. Present only for categories where `has_number` is true (e.g., numeric traffic lights).
+
+    Inherited from AutolabelMixin:
         automatic_annotation (bool, optional): Indicates if the annotation is fully generated by an ML model.
             If any part is manually modified or annotated by human this value is False.
+        autolabel_metadata (list[AutolabelModel] | None, optional): List of models used for autolabeling. Required if `automatic_annotation` is `true`.
 
     Shortcuts:
     ---------
@@ -82,7 +88,12 @@ class ObjectAnn(SchemaBase):
         converter=lambda x: RLEMask(**x) if isinstance(x, dict) else x,
         validator=validators.optional(validators.instance_of(RLEMask)),
     )
-    automatic_annotation: bool = field(default=False, validator=validators.instance_of(bool))
+    orientation: float | None = field(
+        default=None, validator=validators.optional(validators.instance_of(float))
+    )
+    number: int | None = field(
+        default=None, validator=validators.optional(validators.instance_of(int))
+    )
 
     # shortcuts
     category_name: str = field(init=False, factory=str)

t4_devkit/schema/tables/sample_annotation.py

@@ -6,6 +6,7 @@
 from t4_devkit.typing import Quaternion, Vector3
 
 from ..name import SchemaName
+from .autolabel_metadata import AutolabelMixin
 from .base import SchemaBase
 from .registry import SCHEMAS
 
@@ -14,7 +15,7 @@
 
 @define(slots=False)
 @SCHEMAS.register(SchemaName.SAMPLE_ANNOTATION)
-class SampleAnnotation(SchemaBase):
+class SampleAnnotation(SchemaBase, AutolabelMixin):
     """A dataclass to represent schema table of `sample_annotation.json`.
 
     Attributes:
@@ -36,8 +37,11 @@ class SampleAnnotation(SchemaBase):
             [vx, vy, vz] in [m/s].
         acceleration (Vector3 | None, optional): Bonding box acceleration
             given as [ax, ay, av] in [m/s^2].
+
+    Inherited from AutolabelMixin:
         automatic_annotation (bool, optional): Indicates if the annotation is fully generated by an ML model.
             If any part is manually modified or annotated by human this value is False.
+        autolabel_metadata (list[AutolabelModel] | None, optional): List of models used for autolabeling. Required if `automatic_annotation` is `true`.
 
     Shortcuts:
     ---------
@@ -59,7 +63,6 @@ class SampleAnnotation(SchemaBase):
     prev: str = field(validator=validators.instance_of(str))
     velocity: Vector3 | None = field(default=None, converter=converters.optional(Vector3))
     acceleration: Vector3 | None = field(default=None, converter=converters.optional(Vector3))
-    automatic_annotation: bool = field(default=False, validator=validators.instance_of(bool))
 
     # shortcuts
     category_name: str = field(init=False, factory=str)

t4_devkit/schema/tables/sample_data.py

@@ -6,6 +6,7 @@
 from attrs import define, field, validators
 
 from ..name import SchemaName
+from .autolabel_metadata import AutolabelModel
 from .base import SchemaBase
 from .registry import SCHEMAS
 
@@ -85,6 +86,7 @@ class SampleData(SchemaBase):
             Empty if start of scene.
         is_valid (bool): True if this data is valid, else False. Invalid data should be ignored.
         info_filename (str): Relative path to metainfo data-blob on disk.
+        autolabel_metadata (list[AutolabelModel] | None, optional): List of models used for autolabeling applied to this entire sample_data item (e.g., image or scan).
 
     Shortcuts:
     ---------
@@ -107,6 +109,13 @@ class SampleData(SchemaBase):
     info_filename: str | None = field(
         default=None, validator=validators.optional(validators.instance_of(str))
     )
+    autolabel_metadata: list[AutolabelModel] | None = field(
+        default=None,
+        converter=AutolabelModel.to_autolabel_model,
+        validator=validators.optional(
+            validators.deep_iterable(validators.instance_of(AutolabelModel))
+        ),
+    )
 
     # shortcuts
     modality: SensorModality | None = field(init=False, default=None)

t4_devkit/schema/tables/surface_ann.py

@@ -6,6 +6,7 @@
 from t4_devkit.typing import Roi
 
 from ..name import SchemaName
+from .autolabel_metadata import AutolabelMixin
 from .base import SchemaBase
 from .object_ann import RLEMask
 from .registry import SCHEMAS
@@ -15,16 +16,19 @@
 
 @define(slots=False)
 @SCHEMAS.register(SchemaName.SURFACE_ANN)
-class SurfaceAnn(SchemaBase):
+class SurfaceAnn(SchemaBase, AutolabelMixin):
     """A dataclass to represent schema table of `surface_ann.json`.
 
     Attributes:
         token (str): Unique record identifier.
         sample_data_token (str): Foreign key pointing to the sample data, which must be a keyframe image.
         category_token (str): Foreign key pointing to the surface category.
         mask (RLEMask): Segmentation mask using the COCO format compressed by RLE.
+
+    Inherited from AutolabelMixin:
         automatic_annotation (bool, optional): Indicates if the annotation is fully generated by an ML model.
             If any part is manually modified or annotated by human this value is False.
+        autolabel_metadata (list[AutolabelModel] | None, optional): List of models used for autolabeling. Required if `automatic_annotation` is `true`.
 
     Shortcuts:
     ---------
@@ -38,7 +42,6 @@ class SurfaceAnn(SchemaBase):
         converter=lambda x: RLEMask(**x) if isinstance(x, dict) else x,
         validator=validators.optional(validators.instance_of(RLEMask)),
     )
-    automatic_annotation: bool = field(default=False, validator=validators.instance_of(bool))
 
     # shortcuts
     category_name: str = field(init=False, factory=str)

tests/schema/conftest.py

@@ -62,6 +62,8 @@ def category_dict() -> dict:
         "name": "animal",
         "description": "",
         "index": None,
+        "has_number": False,
+        "has_orientation": False,
     }
 
 
@@ -178,7 +180,8 @@ def sample_annotation_dict() -> dict:
         "num_radar_pts": 0,
         "next": "7b0ae1dae7531b7b917f403cb22259e6",
         "prev": "",
-        "automatic_annotation": False,
+        "automatic_annotation": True,
+        "autolabel_metadata": [{"name": "centerpoint_v1.2", "score": 0.95, "uncertainty": 0.1}],
     }
 
 
@@ -230,6 +233,9 @@ def sample_data_dict() -> dict:
         "is_valid": True,
         "next": "efe096cc01a610af846c29aaf4decc9a",
         "prev": "",
+        "autolabel_metadata": [
+            {"name": "image_preprocessor_v2.1", "score": 0.99, "uncertainty": None}
+        ],
     }
 
 
@@ -314,7 +320,13 @@ def object_ann_dict() -> dict:
         "attribute_tokens": [],
         "bbox": [0, 408.0529355733727, 1920, 728.1832152454293],
         "mask": {"size": [1920, 1280], "counts": "UFBQWzI='"},
-        "automatic_annotation": False,
+        "automatic_annotation": True,
+        "autolabel_metadata": [
+            {"name": "yolo_v8_segmentation", "score": 0.87, "uncertainty": 0.15},
+            {"name": "mask_rcnn_v3.0", "score": 0.92, "uncertainty": None},
+        ],
+        "number": None,
+        "orientation": None,
     }
 
 
@@ -336,6 +348,7 @@ def surface_ann_dict() -> dict:
         "category_token": "7864884179fb37bf9e973016b13a332c",
         "mask": {"size": [1920, 1280], "counts": "UFBQWzI='"},
         "automatic_annotation": False,
+        "autolabel_metadata": None,
     }