From c576427ffe11b181dcd4a35c8c1e07a7a2046338 Mon Sep 17 00:00:00 2001 From: Kotaro Uetake <60615504+ktro2828@users.noreply.github.com> Date: Tue, 19 Nov 2024 03:42:48 +0900 Subject: [PATCH] docs: update documents (#40) Signed-off-by: ktro2828 --- docs/apis/dataclass.md | 7 +-- docs/apis/schema.md | 11 +---- t4_devkit/dataclass/pointcloud.py | 19 +++++++- t4_devkit/dataclass/roi.py | 38 +++++++++++++++- t4_devkit/dataclass/transform.py | 46 ++++++++++++++++++++ t4_devkit/schema/tables/sample.py | 1 - t4_devkit/schema/tables/sample_annotation.py | 1 - t4_devkit/schema/tables/sample_data.py | 1 - t4_devkit/schema/tables/sensor.py | 1 - 9 files changed, 107 insertions(+), 18 deletions(-) diff --git a/docs/apis/dataclass.md b/docs/apis/dataclass.md index 521ff99..4c3127a 100644 --- a/docs/apis/dataclass.md +++ b/docs/apis/dataclass.md @@ -1,13 +1,14 @@ # `dataclass` -::: t4_devkit.dataclass.box + +::: t4_devkit.dataclass.label options: - filters: ["!BaseBox"] show_bases: false -::: t4_devkit.dataclass.label +::: t4_devkit.dataclass.box options: + filters: ["!BaseBox"] show_bases: false ::: t4_devkit.dataclass.pointcloud diff --git a/docs/apis/schema.md b/docs/apis/schema.md index 224855e..2428502 100644 --- a/docs/apis/schema.md +++ b/docs/apis/schema.md @@ -16,14 +16,7 @@ ::: t4_devkit.schema.tables options: - members: ["SchemaBase"] - show_bases: false - ---- - -::: t4_devkit.schema.tables - options: - filters: ["!SchemaBase", "!FileFormat", "!SensorModality", "!VisibilityLevel"] + filters: ["!SchemaBase", "!FileFormat", "!SensorModality", "!VisibilityLevel", "!RLEMask"] show_root_toc_entry: false merge_init_into_class: false show_signature_annotations: false @@ -35,7 +28,7 @@ ::: t4_devkit.schema.tables options: - members: ["FileFormat", "SensorModality", "VisibilityLevel"] + members: ["FileFormat", "SensorModality", "VisibilityLevel", "RLEMask"] show_root_toc_entry: false merge_init_into_class: false show_signature_annotations: false diff --git a/t4_devkit/dataclass/pointcloud.py b/t4_devkit/dataclass/pointcloud.py index e01bcf7..d0a64dd 100644 --- a/t4_devkit/dataclass/pointcloud.py +++ b/t4_devkit/dataclass/pointcloud.py @@ -80,7 +80,11 @@ def transform(self, matrix: NDArrayFloat) -> None: @define class LidarPointCloud(PointCloud): - """A dataclass to represent lidar pointcloud.""" + """A dataclass to represent lidar pointcloud. + + Attributes: + points (NDArrayFloat): Points matrix in the shape of (4, N). + """ @staticmethod def num_dims() -> int: @@ -97,6 +101,12 @@ def from_file(cls, filepath: str) -> Self: @define class RadarPointCloud(PointCloud): + """A dataclass to represent radar pointcloud. + + Attributes: + points (NDArrayFloat): Points matrix in the shape of (18, N). + """ + # class variables invalid_states: ClassVar[list[int]] = [0] dynprop_states: ClassVar[list[int]] = range(7) @@ -194,6 +204,13 @@ def from_file( @define class SegmentationPointCloud(PointCloud): + """A dataclass to represent segmentation pointcloud. + + Attributes: + points (NDArrayFloat): Points matrix in the shape of (4, N). + labels (NDArrayU8): Label matrix. + """ + labels: NDArrayU8 = field(converter=lambda x: np.asarray(x, dtype=np.uint8)) @staticmethod diff --git a/t4_devkit/dataclass/roi.py b/t4_devkit/dataclass/roi.py index 597e17b..4d12c3e 100644 --- a/t4_devkit/dataclass/roi.py +++ b/t4_devkit/dataclass/roi.py @@ -12,36 +12,72 @@ @define class Roi: + """A dataclass to represent 2D box ROI. + + Attributes: + roi (RoiType): Box ROI in the order of (x, y, width, height). + """ + roi: RoiType = field(converter=tuple) - def __post_init__(self) -> None: + def __attrs_post_init__(self) -> None: assert len(self.roi) == 4, ( "Expected roi is (x, y, width, height), " f"but got length with {len(self.roi)}." ) @property def offset(self) -> tuple[int, int]: + """Return the xy offset from the image origin at the top left of the box. + + Returns: + Top left corner (x, y). + """ return self.roi[:2] @property def size(self) -> tuple[int, int]: + """Return the size of the box. + + Returns: + Box size (width, height). + """ return self.roi[2:] @property def width(self) -> int: + """Return the width of the box. + + Returns: + Box width. + """ return self.size[0] @property def height(self) -> int: + """Return the height of the box. + + Returns: + Box height. + """ return self.size[1] @property def center(self) -> tuple[int, int]: + """Return the center position of the box from the image origin. + + Returns: + Center position of the box (cx, cy). + """ ox, oy = self.offset w, h = self.size return ox + w // 2, oy + h // 2 @property def area(self) -> int: + """Return the area of the box. + + Returns: + Area of the box. + """ w, h = self.size return w * h diff --git a/t4_devkit/dataclass/transform.py b/t4_devkit/dataclass/transform.py index d5f5f04..ae9a400 100644 --- a/t4_devkit/dataclass/transform.py +++ b/t4_devkit/dataclass/transform.py @@ -25,6 +25,12 @@ @define class TransformBuffer: + """A buffer class to store transformation matrices. + + Args: + buffer (dict[tuple[str, str], HomogeneousMatrix]): Matrix buffer whose key is `(src, dst)`. + """ + buffer: dict[tuple[str, str], HomogeneousMatrix] = field(factory=dict, init=False) def set_transform(self, matrix: HomogeneousMatrix) -> None: @@ -43,19 +49,59 @@ def set_transform(self, matrix: HomogeneousMatrix) -> None: self.buffer[(dst, src)] = matrix.inv() def lookup_transform(self, src: str, dst: str) -> HomogeneousMatrix | None: + """Look up the transform matrix corresponding to the `src` and `dst` frame ID. + + Args: + src (str): Source frame ID. + dst (str): Destination frame ID. + + Returns: + Returns `HomogeneousMatrix` if the corresponding matrix can be found, + otherwise it returns `None`. + """ if src == dst: return HomogeneousMatrix.as_identity(src) return self.buffer[(src, dst)] if (src, dst) in self.buffer else None def do_translate(self, src: str, dst: str, *args, **kwargs) -> TranslateItemLike | None: + """Translate specified items with the matrix corresponding to `src` and `dst` frame ID. + + Args: + src (str): Source frame ID. + dst (str): Destination frame ID. + + Returns: + TranslateItemLike | None: Returns translated items if the corresponding matrix can be found, + otherwise it returns `None`. + """ tf_matrix = self.lookup_transform(src, dst) return tf_matrix.translate(*args, **kwargs) if tf_matrix is not None else None def do_rotate(self, src: str, dst: str, *args, **kwargs) -> RotateItemLike | None: + """Rotate specified items with the matrix corresponding to `src` and `dst` frame ID. + + Args: + src (str): Source frame ID. + dst (str): Destination frame ID. + + Returns: + TranslateItemLike | None: Returns rotated items if the corresponding matrix can be found, + otherwise it returns `None`. + """ tf_matrix = self.lookup_transform(src, dst) return tf_matrix.rotate(*args, **kwargs) if tf_matrix is not None else None def do_transform(self, src: str, dst: str, *args, **kwargs) -> TransformItemLike | None: + """Transform specified items with the matrix corresponding to `src` and `dst` frame ID. + + Args: + src (str): Source frame ID. + dst (str): Destination frame ID. + + Returns: + TranslateItemLike | None: Returns transformed items if the corresponding matrix can be found, + otherwise it returns `None`. + """ tf_matrix = self.lookup_transform(src, dst) return tf_matrix.transform(*args, **kwargs) if tf_matrix is not None else None diff --git a/t4_devkit/schema/tables/sample.py b/t4_devkit/schema/tables/sample.py index d7df07a..a263713 100644 --- a/t4_devkit/schema/tables/sample.py +++ b/t4_devkit/schema/tables/sample.py @@ -22,7 +22,6 @@ class Sample(SchemaBase): prev (str): Foreign key pointing the sample that precedes this in time. Empty if start of scene. Shortcuts: - --------- data (dict[str, str]): Sensor channel and its token. This should be set after instantiated. ann_3ds (list[str]): List of foreign keys pointing the sample annotations. diff --git a/t4_devkit/schema/tables/sample_annotation.py b/t4_devkit/schema/tables/sample_annotation.py index 2b78aff..50be73f 100644 --- a/t4_devkit/schema/tables/sample_annotation.py +++ b/t4_devkit/schema/tables/sample_annotation.py @@ -50,7 +50,6 @@ class SampleAnnotation(SchemaBase): given as [ax, ay, av] in [m/s^2]. Shortcuts: - --------- category_name (str): Category name. This should be set after instantiated. """ diff --git a/t4_devkit/schema/tables/sample_data.py b/t4_devkit/schema/tables/sample_data.py index 35f8c44..0a41928 100644 --- a/t4_devkit/schema/tables/sample_data.py +++ b/t4_devkit/schema/tables/sample_data.py @@ -85,7 +85,6 @@ class SampleData(SchemaBase): is_valid (bool): True if this data is valid, else False. Invalid data should be ignored. Shortcuts: - --------- modality (SensorModality): Sensor modality. This should be set after instantiated. channel (str): Sensor channel. This should be set after instantiated. """ diff --git a/t4_devkit/schema/tables/sensor.py b/t4_devkit/schema/tables/sensor.py index 53a06b1..5baa057 100644 --- a/t4_devkit/schema/tables/sensor.py +++ b/t4_devkit/schema/tables/sensor.py @@ -36,7 +36,6 @@ class Sensor(SchemaBase): modality (SensorModality): Sensor modality. Shortcuts: - --------- first_sd_token (str): The first sample data token corresponding to its sensor channel. """