[FXC-5651] feat: add client-side OBB computation via DraftContext.compute_obb()

flow360/cloud/file_cache.py

@@ -0,0 +1,156 @@
+"""General-purpose size-based LRU disk cache for cloud file downloads.
+
+Stores files under ``~/.flow360/cache/<namespace>/<resource_id>/<file_path>``
+with a configurable total size limit.  Eviction granularity is the resource
+directory — all files for a resource are deleted together to avoid partial
+state (e.g. manifest present but bin evicted).
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from ..log import log
+
+CLOUD_FILE_CACHE_MAX_SIZE_MB: int = 2048  # default 2 GB, user-adjustable
+
+_shared_cache_instance: Optional["CloudFileCache"] = None
+
+
+def get_shared_cloud_file_cache() -> "CloudFileCache":
+    """Return the module-level shared CloudFileCache instance (created on first call)."""
+    global _shared_cache_instance  # pylint: disable=global-statement
+    if _shared_cache_instance is None:
+        _shared_cache_instance = CloudFileCache()
+    return _shared_cache_instance
+
+
+class CloudFileCache:
+    """Size-based LRU disk cache.
+
+    Keys are ``(namespace, resource_id, file_path)`` triples.
+    All namespaces share a single total-size budget.
+    """
+
+    def __init__(
+        self,
+        cache_root: Optional[Path] = None,
+        max_size_bytes: Optional[int] = None,
+    ) -> None:
+        self._cache_root = (cache_root or Path("~/.flow360/cache")).expanduser()
+        self._max_size_bytes = (
+            CLOUD_FILE_CACHE_MAX_SIZE_MB * 1024 * 1024 if max_size_bytes is None else max_size_bytes
+        )
+        self._disabled = False
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def get(self, namespace: str, resource_id: str, file_path: str) -> Optional[bytes]:
+        """Return cached bytes or ``None``.  Touches ``.last_access`` on hit."""
+        if self._disabled:
+            return None
+
+        target = self._file_path(namespace, resource_id, file_path)
+        if not target.is_file():
+            return None
+
+        try:
+            data = target.read_bytes()
+        except OSError:
+            return None
+
+        self._touch_last_access(namespace, resource_id)
+        return data
+
+    def put(self, namespace: str, resource_id: str, file_path: str, data: bytes) -> None:
+        """Write *data* to disk, evicting oldest resources if over size limit."""
+        if self._disabled:
+            return
+
+        # Skip caching entries that exceed the entire cache budget
+        if len(data) > self._max_size_bytes:
+            return
+
+        try:
+            # Account for the file being overwritten (net size delta, not gross)
+            target = self._file_path(namespace, resource_id, file_path)
+            existing_size = target.stat().st_size if target.is_file() else 0
+            net_incoming = len(data) - existing_size
+
+            current_resource_dir = self._resource_dir(namespace, resource_id)
+            self._evict_if_needed(net_incoming, protect=current_resource_dir)
+
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(data)
+            self._touch_last_access(namespace, resource_id)
+        except OSError as exc:
+            log.warning(f"CloudFileCache: disk write failed ({exc}), disabling cache")
+            self._disabled = True
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _file_path(self, namespace: str, resource_id: str, file_path: str) -> Path:
+        return self._cache_root / namespace / resource_id / file_path
+
+    def _resource_dir(self, namespace: str, resource_id: str) -> Path:
+        return self._cache_root / namespace / resource_id
+
+    def _last_access_path(self, namespace: str, resource_id: str) -> Path:
+        return self._resource_dir(namespace, resource_id) / ".last_access"
+
+    def _touch_last_access(self, namespace: str, resource_id: str) -> None:
+        """Create or update the ``.last_access`` sentinel in the resource dir."""
+        path = self._last_access_path(namespace, resource_id)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.touch()
+
+    def _collect_resource_dirs(self) -> Tuple[int, List[Tuple[float, int, Path]]]:
+        """Scan cache and return ``(total_size, [(mtime, size, dir), ...])``.
+
+        Single pass: computes both the aggregate size and per-resource metadata
+        needed for LRU eviction.
+        """
+        entries: List[Tuple[float, int, Path]] = []
+        total_size = 0
+        if not self._cache_root.exists():
+            return total_size, entries
+
+        for namespace_dir in self._cache_root.iterdir():
+            if not namespace_dir.is_dir():
+                continue
+            for resource_dir in namespace_dir.iterdir():
+                if not resource_dir.is_dir():
+                    continue
+                last_access = resource_dir / ".last_access"
+                mtime = last_access.stat().st_mtime if last_access.exists() else 0.0
+                size = sum(f.stat().st_size for f in resource_dir.rglob("*") if f.is_file())
+                total_size += size
+                entries.append((mtime, size, resource_dir))
+        return total_size, entries
+
+    def _evict_if_needed(self, incoming_bytes: int, protect: Optional[Path] = None) -> None:
+        """Delete oldest resource dirs until total size + *incoming_bytes* fits the budget.
+
+        *protect*, if given, is a resource directory that must not be evicted
+        (the resource currently being populated by the caller).
+        """
+        current_size, entries = self._collect_resource_dirs()
+        if current_size + incoming_bytes <= self._max_size_bytes:
+            return
+
+        # Sort by last-access time ascending (oldest first)
+        entries.sort(key=lambda e: e[0])
+
+        for _mtime, size, resource_dir in entries:
+            if current_size + incoming_bytes <= self._max_size_bytes:
+                break
+            if protect is not None and resource_dir == protect:
+                continue
+            shutil.rmtree(resource_dir, ignore_errors=True)
+            current_size -= size

flow360/component/geometry.py

@@ -389,6 +389,7 @@ class Geometry(AssetBase):
     def __init__(self, id: Union[str, None]):
         super().__init__(id)
         self.snappy_body_registry = None
+        self._project_length_unit = None
 
     @property
     def face_group_tag(self):
@@ -447,6 +448,14 @@ def _get_default_geometry_accuracy(simulation_dict: dict) -> LengthType.Positive
             else _get_default_geometry_accuracy(simulation_dict=simulation_dict)
         )
 
+        # Cache project length unit for OBB (avoids extra API call in create_draft)
+        asset_cache = simulation_dict.get("private_attribute_asset_cache", {})
+        length_unit_raw = asset_cache.get("project_length_unit")
+        # pylint: disable=no-member
+        self._project_length_unit = (
+            LengthType.validate(length_unit_raw) if length_unit_raw is not None else None
+        )
+
     @classmethod
     # pylint: disable=redefined-builtin
     def from_cloud(cls, id: str, **kwargs) -> Geometry:

flow360/component/project.py

@@ -13,6 +13,7 @@
 import typing_extensions
 from pydantic import PositiveInt
 
+from flow360.cloud.file_cache import get_shared_cloud_file_cache
 from flow360.cloud.flow360_requests import (
     CloneVolumeMeshRequest,
     LengthUnitType,
@@ -49,6 +50,9 @@
     CoordinateSystemStatus,
 )
 from flow360.component.simulation.draft_context.mirror import MirrorStatus
+from flow360.component.simulation.draft_context.obb.tessellation_loader import (
+    TessellationFileLoader,
+)
 from flow360.component.simulation.entity_info import (
     GeometryEntityInfo,
     merge_geometry_entity_info,
@@ -292,12 +296,30 @@ def _merge_geometry_entity_info(
         cache_key="coordinate_system_status",
     )
 
+    # Build tessellation loader for geometry-root drafts (enables compute_obb)
+    tessellation_loader = None
+    length_unit = None
+    if isinstance(new_run_from, Geometry):
+        # pylint: disable=protected-access
+        geometry_resources: Dict[str, Flow360Resource] = {new_run_from.id: new_run_from._webapi}
+        geometry_resources.update(
+            {geo.id: geo._webapi for geo in active_geometry_dependencies.values()}
+        )
+        tessellation_loader = TessellationFileLoader(
+            geometry_resources, get_shared_cloud_file_cache()
+        )
+
+        # Use length unit cached on Geometry during from_cloud (no extra API call)
+        length_unit = getattr(new_run_from, "_project_length_unit", None)
+
     return DraftContext(
         entity_info=entity_info_copy,
         mirror_status=mirror_status,
         coordinate_system_status=coordinate_system_status,
         imported_surfaces=imported_surfaces,
         imported_geometries=list(active_geometry_dependencies.values()),
+        tessellation_loader=tessellation_loader,
+        length_unit=length_unit,
     )
 
 

flow360/component/simulation/draft_context/context.py

@@ -5,7 +5,7 @@
 from contextlib import AbstractContextManager
 from contextvars import ContextVar, Token
 from dataclasses import dataclass
-from typing import List, Optional, get_args
+from typing import TYPE_CHECKING, List, Optional, Union, get_args
 
 from flow360.component.simulation.draft_context.coordinate_system_manager import (
     CoordinateSystemManager,
@@ -38,6 +38,11 @@
 from flow360.exceptions import Flow360RuntimeError, Flow360ValueError
 from flow360.log import log
 
+if TYPE_CHECKING:
+    from flow360.component.simulation.draft_context.obb.tessellation_loader import (
+        TessellationFileLoader,
+    )
+
 __all__ = [
     "DraftContext",
     "get_active_draft",
@@ -77,6 +82,10 @@ class DraftContext(  # pylint: disable=too-many-instance-attributes
         "_mirror_status",
         # Lightweight coordinate system relationships storage (compared to entity storages)
         "_coordinate_system_manager",
+        # OBB tessellation data loader (only available for geometry-root drafts)
+        "_tessellation_loader",
+        # Project length unit for dimensioned OBB results
+        "_length_unit",
         "_token",
     )
 
@@ -89,6 +98,8 @@ def __init__(
         imported_surfaces: Optional[List[ImportedSurface]] = None,
         mirror_status: Optional[MirrorStatus] = None,
         coordinate_system_status: Optional[CoordinateSystemStatus] = None,
+        tessellation_loader: Optional[TessellationFileLoader] = None,
+        length_unit=None,
     ) -> None:
         """
         Data members:
@@ -106,6 +117,8 @@ def __init__(
                 "[Internal] DraftContext requires `entity_info` to initialize."
             )
         self._token: Optional[Token] = None
+        self._tessellation_loader = tessellation_loader
+        self._length_unit = length_unit
 
         # DraftContext owns a deep copy of entity_info and mirror_status (created by create_draft()).
         # This signals transfer of entity ownership from the asset to the draft (context).
@@ -347,4 +360,112 @@ class MockEntityList:
             return [entity.name for entity in matched_entities]
         return matched_entities
 
+    def compute_obb(
+        self,
+        entities: Union[Surface, List[Surface], EntityRegistryView, EntitySelector],
+        *,
+        rotation_axis_hint=None,
+        lod_level: Optional[int] = None,
+    ):
+        """Compute oriented bounding box for the given surface entities.
+
+        Args:
+            entities: Surface entities or an EntitySelector that resolves to surfaces.
+                Accepts: a single Surface, a list of Surface, an EntityRegistryView,
+                or an EntitySelector.
+            rotation_axis_hint: optional approximate rotation axis direction (e.g. [0, 0, 1]).
+                If provided, the PCA axis most aligned with this hint is chosen as rotation axis.
+                If None, the axis whose perpendicular cross-section is most circular is used.
+            lod_level: LOD level override for tessellation data.
+
+        Returns:
+            OBBResult with center, axes, extents, axis_of_rotation, and radius as properties.
+
+        Raises:
+            Flow360RuntimeError: If this draft was not created from a Geometry resource.
+            Flow360ValueError: If no face IDs could be collected from the provided entities.
+        """
+        if self._tessellation_loader is None:
+            raise Flow360RuntimeError(
+                "compute_obb() requires a draft created from a Geometry resource. "
+                "Drafts from SurfaceMesh or VolumeMesh do not have tessellation data."
+            )
+
+        # Resolve entities to a flat list of Surface
+        if isinstance(entities, EntitySelector):
+            if entities.target_class != "Surface":
+                raise Flow360ValueError(
+                    f"compute_obb() requires a SurfaceSelector, "
+                    f"got selector with target_class='{entities.target_class}'."
+                )
+            # pylint: disable=import-outside-toplevel
+            from flow360.component.simulation.framework.entity_selector import (
+                expand_entity_list_selectors,
+            )
+
+            @dataclass
+            class _MockEntityList:
+                """Temporary wrapper for EntityList to satisfy expand_entity_list_selectors."""
+
+                selectors: List[EntitySelector]
+
+            surface_list = expand_entity_list_selectors(
+                registry=self._entity_registry,
+                entity_list=_MockEntityList(selectors=[entities]),
+            )
+        elif isinstance(entities, EntityRegistryView):
+            surface_list = list(entities)
+        elif isinstance(entities, Surface):
+            surface_list = [entities]
+        else:
+            surface_list = entities
+
+        # Filter to Surface only (selector expansion may include MirroredSurface
+        # which lacks sub_components and has no tessellation data)
+        non_surface = [s for s in surface_list if not isinstance(s, Surface)]
+        if non_surface:
+            names = [s.name for s in non_surface]
+            log.warning(
+                f"compute_obb(): skipping {len(non_surface)} non-Surface entity(ies) "
+                f"(e.g. MirroredSurface) — not yet supported: {names}"
+            )
+        surface_list = [s for s in surface_list if isinstance(s, Surface)]
+
+        # Collect face IDs from surface sub-components
+        face_ids = []
+        for surface in surface_list:
+            sub_components = surface.private_attribute_sub_components
+            if sub_components:
+                face_ids.extend(sub_components)
+
+        if not face_ids:
+            raise Flow360ValueError(
+                "No face IDs could be collected from the provided entities. "
+                "Ensure the entities have valid sub-component data."
+            )
+
+        # Lazy import to avoid circular dependency
+        # pylint: disable=import-outside-toplevel
+        from flow360.component.simulation.draft_context.obb.compute import compute_obb
+
+        log.info("Computing Oriented Bounding Box (OBB)...")
+
+        vertices = self._tessellation_loader.load_vertices(face_ids, lod_level)
+        log.info(f"OBB: extracted {len(vertices)} vertices, computing PCA...")
+
+        result = compute_obb(vertices, rotation_axis_hint=rotation_axis_hint)
+
+        # Apply length unit to dimensioned fields if available
+        if self._length_unit is not None:
+            result = type(result)(
+                center=result.center * self._length_unit,
+                axes=result.axes,
+                extents=result.extents * self._length_unit,
+                axis_of_rotation=result.axis_of_rotation,
+                radius=result.radius * self._length_unit,
+            )
+
+        log.info("OBB computation complete.")
+        return result
+
     # endregion ------------------------------------------------------------------------------------

flow360/component/simulation/draft_context/obb/__init__.py

@@ -0,0 +1 @@
+"""Oriented Bounding Box (OBB) computation from UVF tessellation data."""