supervisely 6.73.438__py3-none-any.whl → 6.73.513__py3-none-any.whl

supervisely/project/volume_project.py

@@ -1,16 +1,22 @@
 # coding: utf-8
+import io
+import json
 import os
 import re
-import sys
-from collections import namedtuple
-from typing import Callable, Dict, List, Optional, Tuple, Union
+import struct
+from collections import defaultdict, namedtuple
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import numpy
 from tqdm import tqdm
 
+import supervisely as sly
+import supervisely.volume_annotation.constants as volume_constants
 from supervisely._utils import batched
 from supervisely.api.api import Api
 from supervisely.api.module_api import ApiField
+from supervisely.api.project_api import ProjectInfo
+from supervisely.api.volume.volume_api import VolumeInfo
 from supervisely.collection.key_indexed_collection import KeyIndexedCollection
 from supervisely.geometry.closed_surface_mesh import ClosedSurfaceMesh
 from supervisely.geometry.mask_3d import Mask3D
@@ -19,6 +25,11 @@ from supervisely.project.project import OpenMode
 from supervisely.project.project_meta import ProjectMeta
 from supervisely.project.project_type import ProjectType
 from supervisely.project.video_project import VideoDataset, VideoProject
+from supervisely.project.versioning.common import (
+    DEFAULT_VOLUME_SCHEMA_VERSION,
+    get_volume_snapshot_schema,
+)
+from supervisely.project.versioning.schema_fields import VersionSchemaField
 from supervisely.sly_logger import logger
 from supervisely.task.progress import Progress, tqdm_sly
 from supervisely.video_annotation.key_id_map import KeyIdMap
@@ -111,6 +122,14 @@ class VolumeProject(VideoProject):
     class DatasetDict(KeyIndexedCollection):
         item_type = VolumeDataset
 
+    _SERIALIZATION_MAGIC = b"SLYVOLPAR"
+    _SERIALIZATION_VERSION = 1
+    _SECTION_PROJECT_INFO = 1
+    _SECTION_PROJECT_META = 2
+    _SECTION_DATASETS = 3
+    _SECTION_VOLUMES = 4
+    _SECTION_ANNOTATIONS = 5
+
     def get_classes_stats(
         self,
         dataset_names: Optional[List[str]] = None,
@@ -202,6 +221,194 @@ class VolumeProject(VideoProject):
             progress_cb=progress_cb,
         )
 
+    @staticmethod
+    def download_bin(
+        api: Api,
+        project_id: int,
+        dest_dir: Optional[str] = None,
+        dataset_ids: Optional[List[int]] = None,
+        download_volumes: bool = True,
+        log_progress: bool = False,
+        progress_cb: Optional[Union[tqdm, Callable]] = None,
+        return_bytesio: bool = False,
+        schema_version: str = DEFAULT_VOLUME_SCHEMA_VERSION,
+        *args,
+        **kwargs,
+    ) -> Union[str, io.BytesIO]:
+        """
+        Download a Volume Project snapshot into a Parquet-backed binary blob (`.tar.zst` file or in-memory BytesIO).
+
+        The snapshot stores:
+
+        - Project info and meta
+        - Dataset tree (dataset infos)
+        - Volume infos (optionally)
+        - Volume annotations (for the included volumes)
+
+        The resulting binary snapshot can be restored later with :func:`upload_bin`.
+
+        :param api: Supervisely API client.
+        :type api: :class:`~supervisely.api.api.Api`
+        :param project_id: Source Volume Project ID on the server.
+        :type project_id: int
+        :param dest_dir: Local folder where the snapshot file will be written. Required when `return_bytesio=False`.
+        :type dest_dir: str, optional
+        :param dataset_ids: Optional list of dataset IDs to include. If provided, only these datasets will be included (recursively, preserving tree structure where applicable).
+        :type dataset_ids: List[int], optional
+        :param download_volumes: If False, only project/meta/dataset tree is stored (volume infos and annotations are skipped). This is useful for “structure-only” snapshots.
+        :type download_volumes: bool, optional
+        :param log_progress: If True, show a progress bar (unless a custom ``progress_cb`` is provided).
+        :type log_progress: bool
+        :param progress_cb: Optional callback (or tqdm-like object) called with incremental progress.
+        :type progress_cb: tqdm or callable, optional
+        :param return_bytesio: If True, return an in-memory :class:`io.BytesIO` with snapshot bytes. If False, write snapshot to ``dest_dir`` and return the file path.
+        :type return_bytesio: bool, optional
+        :param schema_version: Snapshot schema version. Controls the internal Parquet layout/fields. Supported values are the keys from :func:`~supervisely.project.volume_schema.get_volume_snapshot_schema` (currently: ``"v2.0.0"``).
+        :type schema_version: str, optional
+        :return: Snapshot file path (when ``return_bytesio=False``) or a BytesIO (when ``return_bytesio=True``).
+        :rtype: str or io.BytesIO
+        :raises ValueError: If ``dest_dir`` is not provided and ``return_bytesio`` is False.
+        :raises RuntimeError: If required optional dependencies (e.g. pyarrow) are missing.
+
+        :Usage example:
+
+        .. code-block:: python
+
+            import supervisely as sly
+            import os
+
+            api = sly.Api(os.environ["SERVER_ADDRESS"], os.environ["API_TOKEN"])
+
+            # 1) Save snapshot to disk
+            out_path = sly.VolumeProject.download_bin(
+                api,
+                project_id=123,
+                dest_dir="/tmp/vol_project_snapshot",
+                download_volumes=True,
+                log_progress=True,
+            )
+
+            # 2) Create an in-memory snapshot (BytesIO) and restore it
+            blob = sly.VolumeProject.download_bin(
+                api,
+                project_id=123,
+                return_bytesio=True,
+                download_volumes=False,  # structure-only
+            )
+            restored = sly.VolumeProject.upload_bin(api, blob, workspace_id=45, project_name="Restored")
+        """
+
+        pa = VolumeProject._require_pyarrow()
+        snapshot_schema = get_volume_snapshot_schema(schema_version)
+
+        if dest_dir is None and not return_bytesio:
+            raise ValueError(
+                "Local save directory dest_dir must be specified if return_bytesio is False"
+            )
+
+        ds_filters = (
+            [{"field": "id", "operator": "in", "value": dataset_ids}]
+            if dataset_ids is not None
+            else None
+        )
+
+        project_info = api.project.get_info_by_id(project_id)
+        project_meta = api.project.get_meta(project_id, with_settings=True)
+        project_meta_obj = ProjectMeta.from_json(project_meta)
+        dataset_infos = api.dataset.get_list(project_id, filters=ds_filters, recursive=True, include_custom_data=True)
+
+        dataset_records = [dataset_info._asdict() for dataset_info in dataset_infos]
+        volume_records: List[Dict] = []
+        annotations: Dict[str, Dict] = {}
+        key_id_map = KeyIdMap()
+
+        for dataset_info in dataset_infos:
+            if dataset_ids is not None and dataset_info.id not in dataset_ids:
+                continue
+
+            volumes = api.volume.get_list(dataset_info.id)
+            if len(volumes) == 0:
+                continue
+
+            if not download_volumes:
+                continue
+
+            ds_progress = progress_cb
+            if log_progress and progress_cb is None:
+                ds_progress = tqdm_sly(
+                    desc="Collecting volumes from: {!r}".format(dataset_info.name),
+                    total=len(volumes),
+                )
+
+            volume_ids = [volume_info.id for volume_info in volumes]
+            ann_jsons = api.volume.annotation.download_bulk(dataset_info.id, volume_ids)
+
+            # insert custom_data into ann_jsons (api does not return it in download_bulk atm)
+            # Build mappings:
+            # - volume_id -> ann_json
+            # - volume_id -> {figure_id -> spatial_figure_dict}
+            ann_by_volume_id: Dict[int, Dict[str, Any]] = {}
+            spatial_figures_by_volume: Dict[int, Dict[int, Dict[str, Any]]] = {}
+            for ann_json in ann_jsons:
+                volume_id = ann_json.get(ApiField.VOLUME_ID)
+                if volume_id is None:
+                    continue
+                ann_by_volume_id[volume_id] = ann_json
+                figures_list = ann_json.get(volume_constants.SPATIAL_FIGURES, []) or []
+                fig_id_to_spatial_figure: Dict[int, Dict[str, Any]] = {}
+                for spatial_figure in figures_list:
+                    fig_id = spatial_figure.get("id")
+                    if fig_id is not None:
+                        fig_id_to_spatial_figure[fig_id] = spatial_figure
+                spatial_figures_by_volume[volume_id] = fig_id_to_spatial_figure
+
+            figures_dict = api.volume.figure.download(dataset_info.id, volume_ids)
+            for volume_id, figure_infos in figures_dict.items():
+                ann_json = ann_by_volume_id.get(volume_id)
+                if ann_json is None:
+                    continue
+                fig_id_to_spatial_figure = spatial_figures_by_volume.get(volume_id, {})
+                for figure_info in figure_infos:
+                    spatial_figure = fig_id_to_spatial_figure.get(figure_info.id)
+                    if spatial_figure is not None:
+                        spatial_figure[ApiField.CUSTOM_DATA] = figure_info.custom_data
+
+            for volume_info, ann_json in zip(volumes, ann_jsons):
+                ann_dict = snapshot_schema.annotation_dict_from_raw(
+                    api=api,
+                    raw_ann_json=ann_json,
+                    project_meta_obj=project_meta_obj,
+                    key_id_map=key_id_map,
+                )
+                volume_records.append(volume_info._asdict())
+                annotations[str(volume_info.id)] = ann_dict
+                if progress_cb is not None:
+                    progress_cb(1)
+                if ds_progress is not None:
+                    ds_progress(1)
+
+        project_info_dict = project_info._asdict()
+        project_info_dict[VersionSchemaField.SCHEMA_VERSION] = schema_version
+        payload = {
+            "project_info": project_info_dict,
+            "project_meta": project_meta,
+            "dataset_infos": dataset_records,
+            "volume_infos": volume_records,
+            "annotations": annotations,
+        }
+        blob = VolumeProject._serialize_payload_to_parquet_blob(pa, payload, snapshot_schema)
+
+        if return_bytesio:
+            stream = io.BytesIO(blob)
+            stream.seek(0)
+            return stream
+
+        os.makedirs(dest_dir, exist_ok=True)
+        file_path = os.path.join(dest_dir, f"{project_info.id}_{project_info.name}.arrow")
+        with open(file_path, "wb") as out:
+            out.write(blob)
+        return file_path
+
     @staticmethod
     def upload(
         directory: str,
@@ -263,6 +470,417 @@ class VolumeProject(VideoProject):
             progress_cb=progress_cb,
         )
 
+    @staticmethod
+    def upload_bin(
+        api: Api,
+        file: Union[str, io.BytesIO],
+        workspace_id: int,
+        project_name: Optional[str] = None,
+        log_progress: bool = True,
+        progress_cb: Optional[Union[tqdm, Callable]] = None,
+        skip_missed_entities: bool = False,
+        *args,
+        **kwargs,
+    ) -> ProjectInfo:
+        """
+        Restore a volume project from a Parquet blob produced by :func:`download_bin`.
+
+        :param api: Supervisely API client.
+        :type api: :class:`~supervisely.api.api.Api`
+        :param file: Snapshot file path (``.tar.zst``) or an in-memory :class:`io.BytesIO` stream.
+        :type file: Union[str, io.BytesIO]
+        :param workspace_id: Target workspace ID where the project will be created.
+        :type workspace_id: int
+        :param project_name: Optional new project name. If not provided, the name from the snapshot will be used. If the name already exists in the workspace, a free name will be chosen.
+        :type project_name: str, optional
+        :param log_progress: If True, show a progress bar (unless a custom ``progress_cb`` is provided).
+        :type log_progress: bool
+        :param progress_cb: Optional callback (or tqdm-like object) called with incremental progress.
+        :type progress_cb: tqdm or callable, optional
+        :param skip_missed_entities: If True, skip volumes that cannot be restored because their source hash is missing in the snapshot payload. If False, such cases raise an error.
+        :type skip_missed_entities: bool
+        :return: Info of the newly created project.
+        :rtype: :class:`~supervisely.api.project_api.ProjectInfo`
+        :raises RuntimeError: If the snapshot contains volumes without hashes and ``skip_missed_entities`` is False.
+        """
+
+        pa = VolumeProject._require_pyarrow()
+
+        if isinstance(file, io.BytesIO):
+            raw_data = file.getbuffer()
+        else:
+            with open(file, "rb") as src:
+                raw_data = src.read()
+
+        payload = VolumeProject._deserialize_payload_from_parquet(pa, raw_data)
+
+        project_meta = ProjectMeta.from_json(payload["project_meta"])
+        project_info: Dict = payload.get("project_info", {})
+        dataset_records: List[Dict] = payload.get("dataset_infos", [])
+        volume_records: List[Dict] = payload.get("volume_infos", [])
+        annotations: Dict[str, Dict] = payload.get("annotations", {})
+
+        project_title = project_name or project_info.get("name")
+        if api.project.exists(workspace_id, project_title):
+            project_title = api.project.get_free_name(workspace_id, project_title)
+        src_project_desc = project_info.get("description")
+        new_project_info = api.project.create(
+            workspace_id,
+            project_title,
+            ProjectType.VOLUMES,
+            description=src_project_desc,
+            readme=project_info.get("readme"),
+        )
+        api.project.update_meta(new_project_info.id, project_meta)
+
+        custom_data = new_project_info.custom_data
+        source_project_id = payload["project_info"].get("id")
+        version_info = payload["project_info"].get("version") or {}
+        custom_data["restored_from"] = {
+            "project_id": source_project_id,
+            "version_num": version_info.get("version"),
+        }
+        original_custom_data = payload["project_info"].get("custom_data") or {}
+        custom_data.update(original_custom_data)
+        api.project.update_custom_data(new_project_info.id, custom_data, silent=True)
+
+        dataset_mapping: Dict[int, sly.DatasetInfo] = {}
+        sorted_datasets = sorted(
+            dataset_records,
+            key=lambda data: (data.get("parent_id") is not None, data.get("parent_id") or 0),
+        )
+        for dataset_data in sorted_datasets:
+            parent_ds_info = dataset_mapping.get(dataset_data.get("parent_id"))
+            new_parent_id = parent_ds_info.id if parent_ds_info else None
+            new_dataset_info = api.dataset.create(
+                project_id=new_project_info.id,
+                name=dataset_data.get("name"),
+                description=dataset_data.get("description"),
+                parent_id=new_parent_id,
+                custom_data=dataset_data.get("custom_data"),
+            )
+            dataset_mapping[dataset_data.get("id")] = new_dataset_info
+
+        volume_mapping: Dict[int, VolumeInfo] = {}
+        volumes_by_dataset: Dict[int, List[Dict]] = defaultdict(list)
+        for volume_data in volume_records:
+            volumes_by_dataset[volume_data.get("dataset_id")].append(volume_data)
+
+        for old_dataset_id, dataset_volumes in volumes_by_dataset.items():
+            new_dataset_info = dataset_mapping.get(old_dataset_id)
+            if new_dataset_info is None:
+                continue
+
+            dataset_volumes_to_upload: List[Dict] = []
+            missing_names: List[str] = []
+            for vol in dataset_volumes:
+                if vol.get("hash"):
+                    dataset_volumes_to_upload.append(vol)
+                else:
+                    missing_names.append(vol.get("name") or str(vol.get("id")))
+
+            if missing_names:
+                if skip_missed_entities:
+                    for vol_name in missing_names:
+                        logger.warning(
+                            "Volume %r skipped during restoration because its source hash is unavailable.",
+                            vol_name,
+                        )
+                    if len(dataset_volumes_to_upload) == 0:
+                        continue
+                else:
+                    raise RuntimeError(
+                        "Cannot restore volumes without available hash. Missing volume names: {}".format(
+                            ", ".join(missing_names)
+                        )
+                    )
+
+            hashes = [volume.get("hash") for volume in dataset_volumes_to_upload]
+            names = [volume.get("name") for volume in dataset_volumes_to_upload]
+            metas = [volume.get("meta") for volume in dataset_volumes_to_upload]
+
+            ds_progress = progress_cb
+            if log_progress and progress_cb is None:
+                ds_progress = tqdm_sly(
+                    desc="Uploading volumes to {!r}".format(new_dataset_info.name),
+                    total=len(dataset_volumes_to_upload),
+                )
+
+            new_volume_infos = api.volume.upload_hashes(
+                new_dataset_info.id,
+                names=names,
+                hashes=hashes,
+                metas=metas,
+                progress_cb=ds_progress,
+            )
+
+            for old_volume, new_volume in zip(dataset_volumes_to_upload, new_volume_infos):
+                volume_mapping[old_volume.get("id")] = new_volume
+
+        for volume_id_str, ann_json in annotations.items():
+            new_volume_info = volume_mapping.get(int(volume_id_str))
+            if new_volume_info is None:
+                if skip_missed_entities:
+                    logger.warning(
+                        "Annotation for volume %s skipped because the source volume was not restored.",
+                        volume_id_str,
+                    )
+                continue
+            ann_json["volumeId"] = new_volume_info.id
+            ann = VolumeAnnotation.from_json(ann_json, project_meta, None)
+            api.volume.annotation.append(new_volume_info.id, ann, None)
+
+        return api.project.get_info_by_id(new_project_info.id)
+
+    @staticmethod
+    def _require_pyarrow():
+        try:
+            import pyarrow as pa  # pylint: disable=import-error
+        except ModuleNotFoundError as exc:
+            raise ModuleNotFoundError(
+                "VolumeProject binary versioning requires the optional dependency 'pyarrow'. "
+                "Install it with `pip install pyarrow` to use download_bin/upload_bin."
+            ) from exc
+        return pa
+
+    @staticmethod
+    def _serialize_payload_to_parquet_blob(pa_module, payload: Dict[str, Dict], snapshot_schema) -> bytes:
+        dataset_records: List[Dict] = payload.get("dataset_infos", []) or []
+        volume_records: List[Dict] = payload.get("volume_infos", []) or []
+        annotations_dict: Dict[str, Dict] = payload.get("annotations", {}) or {}
+
+        dataset_rows = [snapshot_schema.dataset_row_from_record(r) for r in dataset_records]
+        dataset_table = pa_module.Table.from_pylist(
+            dataset_rows, schema=snapshot_schema.datasets_table_schema(pa_module)
+        )
+
+        volume_rows = [snapshot_schema.volume_row_from_record(r) for r in volume_records]
+        volume_table = pa_module.Table.from_pylist(
+            volume_rows, schema=snapshot_schema.volumes_table_schema(pa_module)
+        )
+
+        ann_rows = []
+        for volume_id_str, ann in annotations_dict.items():
+            try:
+                src_volume_id = int(volume_id_str)
+            except (TypeError, ValueError):
+                continue
+            ann_rows.append(
+                snapshot_schema.annotation_row_from_dict(src_volume_id=src_volume_id, annotation=ann)
+            )
+        annotations_table = pa_module.Table.from_pylist(
+            ann_rows, schema=snapshot_schema.annotations_table_schema(pa_module)
+        )
+
+        sections = [
+            (
+                VolumeProject._SECTION_PROJECT_INFO,
+                VolumeProject._json_bytes(payload.get("project_info", {})),
+            ),
+            (
+                VolumeProject._SECTION_PROJECT_META,
+                VolumeProject._json_bytes(payload.get("project_meta", {})),
+            ),
+            (
+                VolumeProject._SECTION_DATASETS,
+                VolumeProject._table_to_parquet_bytes(pa_module, dataset_table),
+            ),
+            (
+                VolumeProject._SECTION_VOLUMES,
+                VolumeProject._table_to_parquet_bytes(pa_module, volume_table),
+            ),
+            (
+                VolumeProject._SECTION_ANNOTATIONS,
+                VolumeProject._table_to_parquet_bytes(pa_module, annotations_table),
+            ),
+        ]
+
+        return VolumeProject._assemble_sections(sections)
+
+    @staticmethod
+    def _build_table(pa_module, columns: Dict[str, Tuple[List, Any]]):
+        arrays = {}
+        for name, (values, dtype) in columns.items():
+            arrays[name] = pa_module.array(values, type=dtype)
+        return pa_module.table(arrays)
+
+    @staticmethod
+    def _table_to_parquet_bytes(pa_module, table) -> bytes:
+        from pyarrow import parquet as pq  # pylint: disable=import-error
+
+        sink = pa_module.BufferOutputStream()
+        pq.write_table(table, sink)
+        return sink.getvalue().to_pybytes()
+
+    @staticmethod
+    def _parquet_bytes_to_table(pa_module, data: bytes):
+        if not data:
+            return pa_module.table({})
+        from pyarrow import parquet as pq  # pylint: disable=import-error
+
+        buffer = pa_module.BufferReader(data)
+        return pq.read_table(buffer)
+
+    @staticmethod
+    def _json_dumps(data) -> str:
+        if isinstance(data, str):
+            return data
+        return json.dumps(data, ensure_ascii=False)
+
+    @staticmethod
+    def _json_bytes(data) -> bytes:
+        return VolumeProject._json_dumps(data).encode("utf-8")
+
+    @staticmethod
+    def _assemble_sections(sections: List[Tuple[int, bytes]]) -> bytes:
+        if len(sections) > 255:
+            raise RuntimeError("Too many sections for VolumeProject binary payload")
+        buffer = io.BytesIO()
+        buffer.write(VolumeProject._SERIALIZATION_MAGIC)
+        buffer.write(struct.pack(">B", VolumeProject._SERIALIZATION_VERSION))
+        buffer.write(struct.pack(">B", len(sections)))
+        for section_type, payload in sections:
+            if payload is None:
+                payload = b""
+            buffer.write(struct.pack(">B", section_type))
+            buffer.write(struct.pack(">Q", len(payload)))
+            buffer.write(payload)
+        return buffer.getvalue()
+
+    @staticmethod
+    def _parse_parquet_sections(raw_data) -> Dict[int, bytes]:
+        magic = VolumeProject._SERIALIZATION_MAGIC
+        view = raw_data if isinstance(raw_data, memoryview) else memoryview(raw_data)
+        header_len = len(magic) + 2
+        if len(view) < header_len:
+            logger.warning(
+                f"VolumeProject binary payload too small: {len(view)} bytes (need >= {header_len}). First bytes(hex)={view[: min(len(view), 16)].tobytes().hex()}",
+            )
+            raise RuntimeError("Corrupted VolumeProject binary payload")
+        if view[: len(magic)].tobytes() != magic:
+            found = view[: len(magic)].tobytes()
+            logger.warning(
+                f"VolumeProject binary payload magic mismatch. expected={magic.hex()} found={found.hex()} total_bytes={len(view)} prefix16(hex)={view[:16].tobytes().hex()}",
+            )
+            raise RuntimeError(
+                "Unsupported VolumeProject binary payload format (magic mismatch). "
+                "Expected magic={!r}, found={!r}".format(magic, found)
+            )
+
+        offset = len(magic)
+        version = view[offset]
+        offset += 1
+        if version != VolumeProject._SERIALIZATION_VERSION:
+            logger.warning(
+                "VolumeProject binary payload version mismatch. expected=%d found=%d total_bytes=%d",
+                VolumeProject._SERIALIZATION_VERSION,
+                version,
+                len(view),
+            )
+            raise RuntimeError(
+                "Unsupported VolumeProject binary payload version: {}".format(version)
+            )
+
+        section_count = view[offset]
+        offset += 1
+        sections: Dict[int, bytes] = {}
+        for _ in range(section_count):
+            if offset + 9 > len(view):
+                raise RuntimeError("Corrupted VolumeProject binary payload")
+            section_type = view[offset]
+            offset += 1
+            length = int.from_bytes(view[offset : offset + 8], "big")
+            offset += 8
+            if offset + length > len(view):
+                raise RuntimeError("Corrupted VolumeProject binary payload")
+            sections[section_type] = view[offset : offset + length].tobytes()
+            offset += length
+        return sections
+
+    @staticmethod
+    def _deserialize_payload_from_parquet(pa_module, raw_data) -> Dict:
+        sections = VolumeProject._parse_parquet_sections(raw_data)
+
+        try:
+            project_info = json.loads(sections[VolumeProject._SECTION_PROJECT_INFO].decode("utf-8"))
+            project_meta = json.loads(sections[VolumeProject._SECTION_PROJECT_META].decode("utf-8"))
+        except KeyError as exc:
+            raise RuntimeError("VolumeProject payload missing metadata section") from exc
+
+        if VolumeProject._SECTION_DATASETS not in sections:
+            logger.warning("VolumeProject blob has no datasets section; treating as empty.")
+        if VolumeProject._SECTION_VOLUMES not in sections:
+            logger.warning("VolumeProject blob has no volumes section; treating as empty.")
+        if VolumeProject._SECTION_ANNOTATIONS not in sections:
+            logger.warning("VolumeProject blob has no annotations section; treating as empty.")
+
+        dataset_table = VolumeProject._parquet_bytes_to_table(
+            pa_module, sections.get(VolumeProject._SECTION_DATASETS, b"")
+        )
+        volume_table = VolumeProject._parquet_bytes_to_table(
+            pa_module, sections.get(VolumeProject._SECTION_VOLUMES, b"")
+        )
+        annotations_table = VolumeProject._parquet_bytes_to_table(
+            pa_module, sections.get(VolumeProject._SECTION_ANNOTATIONS, b"")
+        )
+
+        dataset_records: List[Dict] = []
+        if dataset_table is not None and dataset_table.num_rows:
+            col_json = (
+                VersionSchemaField.JSON
+                if VersionSchemaField.JSON in dataset_table.column_names
+                else "json"
+            )
+            if col_json in dataset_table.column_names:
+                dataset_jsons = dataset_table.column(col_json).to_pylist()
+                dataset_records = [json.loads(item) for item in dataset_jsons]
+
+        volume_records: List[Dict] = []
+        if volume_table is not None and volume_table.num_rows:
+            col_json = (
+                VersionSchemaField.JSON
+                if VersionSchemaField.JSON in volume_table.column_names
+                else "json"
+            )
+            if col_json in volume_table.column_names:
+                volume_jsons = volume_table.column(col_json).to_pylist()
+                volume_records = [json.loads(item) for item in volume_jsons]
+
+        annotations: Dict[str, Dict] = {}
+        if annotations_table is not None and annotations_table.num_rows:
+            col_vol_id = (
+                VersionSchemaField.SRC_VOLUME_ID
+                if VersionSchemaField.SRC_VOLUME_ID in annotations_table.column_names
+                else "volume_id"
+            )
+            col_ann = (
+                VersionSchemaField.ANNOTATION
+                if VersionSchemaField.ANNOTATION in annotations_table.column_names
+                else "annotation"
+            )
+            if col_vol_id in annotations_table.column_names and col_ann in annotations_table.column_names:
+                annotation_ids = annotations_table.column(col_vol_id).to_pylist()
+                annotation_payloads = annotations_table.column(col_ann).to_pylist()
+                for volume_id, annotation_json in zip(annotation_ids, annotation_payloads):
+                    if volume_id is None:
+                        continue
+                    annotations[str(volume_id)] = json.loads(annotation_json)
+
+        return {
+            "project_info": project_info,
+            "project_meta": project_meta,
+            "dataset_infos": dataset_records,
+            "volume_infos": volume_records,
+            "annotations": annotations,
+        }
+
+    @staticmethod
+    def _load_mask_geometries(api: Api, ann: VolumeAnnotation, key_id_map: KeyIdMap) -> None:
+        for sf in ann.spatial_figures:
+            if sf.geometry.name() != Mask3D.name():
+                continue
+            api.volume.figure.load_sf_geometry(sf, key_id_map)
+
     @staticmethod
     def get_train_val_splits_by_count(project_dir: str, train_count: int, val_count: int) -> None:
         """
@@ -270,7 +888,7 @@ class VolumeProject(VideoProject):
         :raises: :class:`NotImplementedError` in all cases.
         """
         raise NotImplementedError(
-            f"Static method 'get_train_val_splits_by_count()' is not supported for VolumeProject class now."
+            "Static method 'get_train_val_splits_by_count()' is not supported for VolumeProject class now."
         )
 
     @staticmethod
@@ -285,7 +903,7 @@ class VolumeProject(VideoProject):
         :raises: :class:`NotImplementedError` in all cases.
         """
         raise NotImplementedError(
-            f"Static method 'get_train_val_splits_by_tag()' is not supported for VolumeProject class now."
+            "Static method 'get_train_val_splits_by_tag()' is not supported for VolumeProject class now."
         )
 
     @staticmethod