feat: add support of loading dataset metadata

Signed-off-by: ktro2828 <kotaro.uetake@tier4.jp>

Author: ktro2828

docs/tutorials/initialize.md

@@ -25,7 +25,7 @@ You can initialize a `Tier4` instance as follows:
 
 >>> from t4_devkit import Tier4
 
->>> t4 = Tier4("annotation", "data/tier4/", verbose=True)
+>>> t4 = Tier4("data/tier4/", verbose=True)
 ======
 Loading T4 tables in `annotation`...
 Reverse indexing...

t4_devkit/cli/visualize.py

@@ -41,7 +41,7 @@ def scene(
 ) -> None:
     _create_dir(output)
 
-    t4 = Tier4("annotation", data_root, verbose=False)
+    t4 = Tier4(data_root, verbose=False)
     scene_token = t4.scene[0].token
     t4.render_scene(scene_token, future_seconds=future, save_dir=output)
 
@@ -71,7 +71,7 @@ def instance(
 ) -> None:
     _create_dir(output)
 
-    t4 = Tier4("annotation", data_root, verbose=False)
+    t4 = Tier4(data_root, verbose=False)
     t4.render_instance(instance_token=instance, future_seconds=future, save_dir=output)
 
 
@@ -99,7 +99,7 @@ def pointcloud(
 ) -> None:
     _create_dir(output)
 
-    t4 = Tier4("annotation", data_root, verbose=False)
+    t4 = Tier4(data_root, verbose=False)
     scene_token = t4.scene[0].token
     t4.render_pointcloud(
         scene_token,

t4_devkit/common/sanity.py

@@ -1,12 +1,11 @@
 from __future__ import annotations
 
-import re
 import warnings
 from pathlib import Path
 
 from attrs import define
 
-from t4_devkit import Tier4
+from t4_devkit import Tier4, load_metadata
 
 __all__ = ["DBException", "sanity_check"]
 
@@ -30,17 +29,6 @@ def sanity_check(db_root: str | Path, *, include_warning: bool = False) -> DBExc
     Returns:
         Exception or warning if exits, otherwise returns None.
     """
-    db_root_path = Path(db_root)
-
-    version_pattern = re.compile(r".*/\d+$")
-    versions = [d.name for d in db_root_path.iterdir() if version_pattern.match(str(d))]
-
-    if versions:
-        version = sorted(versions)[-1]
-        data_root = db_root_path.joinpath(version).as_posix()
-    else:
-        version = None
-        data_root = db_root_path.as_posix()
 
     with warnings.catch_warnings():
         if include_warning:
@@ -49,12 +37,14 @@ def sanity_check(db_root: str | Path, *, include_warning: bool = False) -> DBExc
             warnings.filterwarnings("ignore")
 
         try:
-            _ = Tier4("annotation", data_root=data_root, verbose=False)
+            _ = Tier4(data_root=db_root, verbose=False)
             exception = None
         except Exception as e:
+            metadata = load_metadata(db_root)
+
             exception = DBException(
-                dataset_id=db_root_path.name,
-                version=version,
+                dataset_id=metadata.dataset_id,
+                version=metadata.version,
                 message=str(e),
             )
     return exception

t4_devkit/tier4.py

@@ -1,11 +1,14 @@
 from __future__ import annotations
 
 import os.path as osp
+import re
 import time
 import warnings
+from pathlib import Path
 from typing import TYPE_CHECKING, Sequence
 
 import numpy as np
+from attrs import define
 from pyquaternion import Quaternion
 
 from t4_devkit.common.geometry import is_box_in_image
@@ -38,13 +41,46 @@
         Visibility,
     )
 
-__all__ = ("Tier4",)
+__all__ = ["DBMetadata", "load_metadata", "Tier4"]
+
+
+@define
+class DBMetadata:
+    data_root: str
+    dataset_id: str
+    version: str | None
+
+
+def load_metadata(db_root: str) -> DBMetadata:
+    """Load metadata of T4 dataset including root directory path, dataset ID, and version.
+
+    Args:
+        db_root (str): Path to root directory of database.
+
+    Returns:
+        Metadata of T4 dataset.
+    """
+    db_root_path = Path(db_root)
+
+    version_pattern = re.compile(r".*/\d+$")
+    versions = [d.name for d in db_root_path.iterdir() if version_pattern.match(d.as_posix())]
+
+    if versions:
+        version = sorted(versions)[-1]
+        data_root = db_root_path.joinpath(version).as_posix()
+    else:
+        version = None
+        data_root = db_root_path.as_posix()
+
+    return DBMetadata(data_root=data_root, dataset_id=db_root_path.name, version=version)
 
 
 class Tier4:
     """Database class for T4 dataset to help query and retrieve information from the database."""
 
-    def __init__(self, version: str, data_root: str, verbose: bool = True) -> None:
+    schema_dir: str = "annotation"
+
+    def __init__(self, data_root: str, verbose: bool = True) -> None:
         """Load database and creates reverse indexes and shortcuts.
 
         Args:
@@ -54,7 +90,7 @@ def __init__(self, version: str, data_root: str, verbose: bool = True) -> None:
 
         Examples:
             >>> from t4_devkit import Tier4
-            >>> t4 = Tier4("annotation", "data/tier4")
+            >>> t4 = Tier4("data/tier4")
             ======
             Loading T4 tables in `annotation`...
             Reverse indexing...
@@ -80,16 +116,14 @@ def __init__(self, version: str, data_root: str, verbose: bool = True) -> None:
             ======
 
         """
-        self.version = version
-        self.data_root = data_root
-        self.verbose = verbose
+        self._metadata = load_metadata(data_root)
 
         if not osp.exists(self.data_root):
             raise FileNotFoundError(f"Database directory is not found: {self.data_root}")
 
         start_time = time.time()
         if verbose:
-            print(f"======\nLoading T4 tables in `{self.version}`...")
+            print(f"======\nLoading T4 tables in `{self.schema_dir}`...")
 
         # assign tables explicitly
         self.attribute: list[Attribute] = self.__load_table__(SchemaName.ATTRIBUTE)
@@ -127,6 +161,21 @@ def __init__(self, version: str, data_root: str, verbose: bool = True) -> None:
         self._timeseries_helper = TimeseriesHelper(self)
         self._rendering_helper = RenderingHelper(self)
 
+    @property
+    def data_root(self) -> str:
+        """Return the path to dataset root directory."""
+        return self._metadata.data_root
+
+    @property
+    def dataset_id(self) -> str:
+        """Return the dataset ID."""
+        return self._metadata.dataset_id
+
+    @property
+    def version(self) -> str | None:
+        """Return the dataset version, or None if it is failed to lookup."""
+        return self._metadata.version
+
     def __load_table__(self, schema: SchemaName) -> list[SchemaTable]:
         """Load schema table from a json file.
 
@@ -139,7 +188,7 @@ def __load_table__(self, schema: SchemaName) -> list[SchemaTable]:
         Returns:
             Loaded table data saved in `.json`.
         """
-        filepath = osp.join(self.data_root, self.version, schema.filename)
+        filepath = osp.join(self.data_root, self.schema_dir, schema.filename)
         if not osp.exists(filepath) and schema.is_optional():
             return []