evo-objects 0.6.1__tar.gz → 0.6.2__tar.gz

{evo_objects-0.6.1 → evo_objects-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: evo-objects
-Version: 0.6.1
+Version: 0.6.2
 Summary: Python SDK for using the Seequent Evo Geoscience Object API
 Project-URL: Source, https://github.com/SeequentEvo/evo-python-sdk
 Project-URL: Tracker, https://github.com/SeequentEvo/evo-python-sdk/issues

{evo_objects-0.6.1 → evo_objects-0.6.2}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "evo-objects"
 description = "Python SDK for using the Seequent Evo Geoscience Object API"
-version = "0.6.1"
+version = "0.6.2"
 requires-python = ">=3.10"
 license-files = ["LICENSE.md"]
 dynamic = ["readme"]

{evo_objects-0.6.1 → evo_objects-0.6.2}/src/evo/objects/typed/_grid.py

@@ -19,6 +19,7 @@ from typing import Annotated
 from uuid import UUID
 
 import pandas as pd
+from pydantic import AliasChoices, Field
 
 from evo.common import IFeedback
 from evo.common.utils import NoFeedback
@@ -198,8 +199,8 @@ class BlockModelGeometry:
 
     model_type: str
     origin: Point3
-    n_blocks: Size3i
-    block_size: Size3d
+    n_blocks: Annotated[Size3i, Field(validation_alias=AliasChoices("n_blocks", "n_parent_blocks"))]
+    block_size: Annotated[Size3d, Field(validation_alias=AliasChoices("block_size", "parent_block_size"))]
     rotation: Rotation | None = None
 
 

{evo_objects-0.6.1 → evo_objects-0.6.2}/src/evo/objects/typed/downhole_collection.py

@@ -1,303 +1,303 @@
-#  Copyright © 2026 Bentley Systems, Incorporated
-#  Licensed under the Apache License, Version 2.0 (the "License");
-#  you may not use this file except in compliance with the License.
-#  You may obtain a copy of the License at
-#      http://www.apache.org/licenses/LICENSE-2.0
-#  Unless required by applicable law or agreed to in writing, software
-#  distributed under the License is distributed on an "AS IS" BASIS,
-#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-#  See the License for the specific language governing permissions and
-#  limitations under the License.
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Annotated, Any, ClassVar, TypeAlias
-
-import numpy as np
-import pandas as pd
-from numpy._typing import NDArray
-
-from evo.common.interfaces import IContext
-from evo.objects import SchemaVersion
-from evo.objects.typed._data import DataTable, DataTableAndAttributes
-from evo.objects.typed._downhole import HoleIdCategory
-from evo.objects.typed._model import DataLocation, SchemaList, SchemaLocation, SchemaModel
-from evo.objects.typed.attributes import (
-    AttributeDescription,
-    Attributes,
-)
-from evo.objects.typed.exceptions import ObjectValidationError
-from evo.objects.typed.spatial import BaseSpatialObject, BaseSpatialObjectData
-from evo.objects.typed.types import BoundingBox
-from evo.objects.utils.table_formats import (
-    DOWNHOLE_COLLECTION_LOCATION_HOLES,
-    FLOAT_ARRAY_1,
-    FLOAT_ARRAY_3,
-    KnownTableFormat,
-)
-
-__all__ = [
-    "DownholeCollection",
-    "DownholeCollectionData",
-]
-
-_X = "x"
-_Y = "y"
-_Z = "z"
-_COORDINATE_COLUMNS = [_X, _Y, _Z]
-
-
-HolePath: TypeAlias = pd.DataFrame  # [ distance | dip | azimuth | <attributes> ]
-HoleChunks: TypeAlias = pd.DataFrame  # [ hole_id | offset | count ]
-HoleProperties: TypeAlias = pd.DataFrame  # [ hole_id | final | target | current | x | y | z ]
-HoleAttributes: TypeAlias = pd.DataFrame
-
-# If `Depths` has unit descriptions in its `DataFrame.attrs` dictionary, then those units will be used when building
-# the schema object.
-# This is the expected structure:
-#   >>> depths_df.attrs
-#   {'attribute_description': {<column names>:  <AttributeDescription>}, ...}
-Depths: TypeAlias = pd.DataFrame  # [ distance | <attributes> ]
-
-
-@dataclass
-class DistanceCollection:
-    name: str
-    holes: HoleChunks
-    distance_table: Depths
-    collection_type: str = "distance"
-
-
-@dataclass(kw_only=True, frozen=True)
-class DownholeCollectionData(BaseSpatialObjectData):
-    """Data class for creating a new DownholeCollection
-
-    :param name: The name of the object.
-    :param holes: A DataFrame describing which parts of `path` belong to which holes.
-            Columns: hole_id, offset, count
-    :param properties: DataFrame for the properties of the holes. The ith row corresponds to the ith element of `holes`.
-            Mandatory columns: hole_id, final, target, current, x, y, z
-    :param attributes: DataFrame for the attributes of the holes. The ith row corresponds to the ith element of `holes`.
-    :param path: Dataframe of [ distance | dip | azimuth | <attributes> ]. Distance/dip/azimuth describe the geometry as
-            the step since the previous row.
-    :param collections: A list of `DistanceCollection` describing a table of distances with attributes.
-    :param distance_unit: The distance unit for the `path` table and the `properties` x/y/y.
-    :param desurvey: The desurvey method appropriate for this collection.
-            Must be one of: "minimum_curvature", "balanced_tangent", "trench".
-    :param coordinate_reference_system: Optional EPSG code or WKT string for the coordinate reference system.
-    :param description: Optional description of the object.
-    :param tags: Optional dictionary of tags for the object.
-    :param extensions: Optional dictionary of extensions for the object.
-    """
-
-    path: HolePath
-    holes: HoleChunks
-    properties: HoleProperties
-    attributes: HoleAttributes | None
-    collections: list[DistanceCollection]
-    distance_unit: str | None
-    desurvey: str | None
-
-    def __post_init__(self):
-        if self.attributes is not None and len(self.holes) != len(self.attributes):
-            raise ObjectValidationError("The number of attributes rows must match the number or holes rows")
-
-        assert self.attributes is None or len(self.holes) == len(self.attributes)
-
-    def compute_bounding_box(self) -> BoundingBox:
-        bboxes = []
-
-        for i in range(len(self.holes)):
-            offset = self.holes.iat[i, 1]
-            count = self.holes.iat[i, 2]
-            collar = tuple(self.properties.loc[i, _COORDINATE_COLUMNS])
-            path_table = self.path[offset : offset + count]
-            bboxes.append(self._compute_hole_bounding_box(path_table, collar))
-
-        return BoundingBox.combine(bboxes)
-
-    @staticmethod
-    def _compute_bounding_box_np(
-        depths: NDArray[np.float64],
-        dips: NDArray[np.float64],
-        azimuths: NDArray[np.float64],
-        offset: tuple[float, float, float] = (0.0, 0.0, 0.0),
-    ) -> BoundingBox:
-        if not np.all(depths[:-1] <= depths[1:]):
-            raise ObjectValidationError("depths must be sorted")
-
-        if len(depths) != len(dips) or len(depths) != len(azimuths):
-            raise ObjectValidationError("depths, dips, and azimuths must have same length")
-
-        # Process NaNs
-        # `depths`, `dips`, and `azimuths` could be read-only views, so take copies instead of mutating
-        depths = depths[~np.isnan(depths)]
-        dips = np.where(np.isnan(dips), 90.0, dips)
-        azimuths = np.where(np.isnan(azimuths), 0.0, azimuths)
-
-        dips_rad = np.deg2rad(dips)
-        azimuths_rad = np.deg2rad(azimuths)
-
-        # Prepend 0 so `step` has the same shape as `dips` and `azimuths`, and so the first depth gets treated as the
-        # first step. The depth column might already start with 0, in which case the first step will be length 0, which
-        # is a no-op as far as the following calculation is concerned.
-        step = np.diff(depths, prepend=0.0)
-
-        dz_down = step * np.sin(dips_rad)
-        horiz = step * np.cos(dips_rad)
-
-        # Horizontal into N/E (0° = North, 90° = East)
-        dN = horiz * np.cos(azimuths_rad)
-        dE = horiz * np.sin(azimuths_rad)
-
-        # Convert to XYZ increments (Z up)
-        dX = dE
-        dY = dN
-        dZ = -dz_down
-
-        x = np.cumsum(dX)
-        y = np.cumsum(dY)
-        z = np.cumsum(dZ)
-
-        def ensure_zero(a, b):
-            return min(a, 0), max(b, 0)
-
-        x0, x1 = ensure_zero(x.min(), x.max())
-        y0, y1 = ensure_zero(y.min(), y.max())
-        z0, z1 = ensure_zero(z.min(), z.max())
-
-        return BoundingBox(
-            min_x=x0 + offset[0],
-            max_x=x1 + offset[0],
-            min_y=y0 + offset[1],
-            max_y=y1 + offset[1],
-            min_z=z0 + offset[2],
-            max_z=z1 + offset[2],
-        )
-
-    @staticmethod
-    def _compute_hole_bounding_box(
-        depths_dips_azimuths_table: pd.DataFrame,
-        collar: tuple[float, float, float],
-    ) -> BoundingBox:
-        """
-        Compute 3D bounding box for a deviated hole given collar XYZ and
-        depth / dip / azimuth data.
-
-        Conventions
-        -----------
-        - depths: measured depth along the hole (m), positive downward.
-        - dips: inclination FROM VERTICAL (degrees).
-            90° = vertical down, 0° = horizontal.
-        - azimuths: degrees clockwise from North.
-        - Coordinates: X = Easting, Y = Northing, Z = elevation (up).
-        """
-        df = depths_dips_azimuths_table.dropna(subset=["distance"])
-        box = DownholeCollectionData._compute_bounding_box_np(
-            df["distance"].astype(float).to_numpy(),
-            df["dip"].astype(float).to_numpy(),
-            df["azimuth"].astype(float).to_numpy(),
-            offset=collar,
-        )
-
-        return box
-
-
-class HoleChunksTable(DataTable):
-    table_format: ClassVar[KnownTableFormat] = DOWNHOLE_COLLECTION_LOCATION_HOLES
-    data_columns: ClassVar[list[str]] = ["hole_index", "offset", "count"]
-
-
-class PathTable(DataTable):
-    table_format: ClassVar[KnownTableFormat] = FLOAT_ARRAY_3
-    data_columns: ClassVar[list[str]] = ["distance", "azimuth", "dip"]
-
-
-class DownholePath(DataTableAndAttributes):
-    _table: Annotated[PathTable, SchemaLocation(""), DataLocation("")]
-
-
-class DistancesTable(DataTable):
-    table_format: ClassVar[KnownTableFormat] = FLOAT_ARRAY_3
-    data_columns: ClassVar[list[str]] = ["final", "target", "current"]
-
-    @classmethod
-    def _extract_distances(cls, data: HoleAttributes) -> pd.DataFrame:
-        return data[["final", "target", "current"]].astype(np.float64)
-
-    @classmethod
-    async def _data_to_schema(cls, data: HoleAttributes, context: IContext) -> Any:
-        distances_df = cls._extract_distances(data)
-        return await super()._data_to_schema(distances_df, context)
-
-
-class CollarCoordinates(DataTable):
-    table_format: ClassVar[KnownTableFormat] = FLOAT_ARRAY_3
-    data_columns: ClassVar[list[str]] = _COORDINATE_COLUMNS
-
-    @classmethod
-    def _extract_coordinates(cls, data: HoleAttributes):
-        return data[["x", "y", "z"]].astype(np.float64)
-
-    @classmethod
-    async def _data_to_schema(cls, data: HoleAttributes, context: IContext) -> Any:
-        distances_df = cls._extract_coordinates(data)
-        return await super()._data_to_schema(distances_df, context)
-
-
-class DownholeLocation(SchemaModel):
-    hole_id: Annotated[HoleIdCategory, SchemaLocation("hole_id"), DataLocation("properties")]
-    path: Annotated[DownholePath, SchemaLocation("path"), DataLocation("path")]
-    holes: Annotated[HoleChunksTable, SchemaLocation("holes"), DataLocation("holes")]
-    distances: Annotated[DistancesTable, SchemaLocation("distances"), DataLocation("properties")]
-    coordinates: Annotated[CollarCoordinates, SchemaLocation("coordinates"), DataLocation("properties")]
-    attributes: Annotated[Attributes, SchemaLocation("attributes"), DataLocation("attributes")]
-
-
-class _Distances(DataTable):
-    table_format: ClassVar[KnownTableFormat] = FLOAT_ARRAY_1
-    data_columns: ClassVar[list[str]] = ["distance"]
-
-
-class DistanceTableDistances(DataTableAndAttributes):
-    _table: Annotated[_Distances, SchemaLocation("values"), DataLocation("")]
-    unit: Annotated[str | None, SchemaLocation("unit")]
-
-    @classmethod
-    async def _data_to_schema(cls, data: pd.DataFrame, context: IContext) -> Any:
-        result = await super()._data_to_schema(data, context)
-        attr_desc: AttributeDescription = data.attrs.get("attribute_descriptions", {}).get("distance")
-        if attr_desc is not None and attr_desc.unit is not None:
-            # "unit" can be missing, but it must not be `None`
-            result["unit"] = attr_desc.unit
-        return result
-
-
-class DistanceTable(SchemaModel):
-    name: Annotated[str, SchemaLocation("name"), DataLocation("name")]
-    collection_type: Annotated[str, SchemaLocation("collection_type"), DataLocation("collection_type")]
-    distance: Annotated[DistanceTableDistances, SchemaLocation("distance"), DataLocation("distance_table")]
-
-
-class DownholeDistanceTable(DistanceTable):
-    holes: Annotated[HoleChunksTable, SchemaLocation("holes"), DataLocation("holes")]
-
-
-class DownholeCollectionTables(SchemaList[DownholeDistanceTable]):
-    pass
-
-
-class DownholeCollection(BaseSpatialObject):
-    """A GeoscienceObject representing a collection of downholes."""
-
-    _data_class = DownholeCollectionData
-    sub_classification = "downhole-collection"
-    creation_schema_version = SchemaVersion(major=1, minor=3, patch=1)
-
-    location: Annotated[DownholeLocation, SchemaLocation("location"), DataLocation("")]
-    collections: Annotated[DownholeCollectionTables, SchemaLocation("collections"), DataLocation("collections")]
-    distance_unit: Annotated[str | None, SchemaLocation("distance_unit")]
-    desurvey: Annotated[str | None, SchemaLocation("desurvey")]
-
-    type: ClassVar[Annotated[str, SchemaLocation("type")]] = "downhole"
+#  Copyright © 2026 Bentley Systems, Incorporated
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#      http://www.apache.org/licenses/LICENSE-2.0
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Annotated, Any, ClassVar, TypeAlias
+
+import numpy as np
+import pandas as pd
+from numpy._typing import NDArray
+
+from evo.common.interfaces import IContext
+from evo.objects import SchemaVersion
+from evo.objects.typed._data import DataTable, DataTableAndAttributes
+from evo.objects.typed._downhole import HoleIdCategory
+from evo.objects.typed._model import DataLocation, SchemaList, SchemaLocation, SchemaModel
+from evo.objects.typed.attributes import (
+    AttributeDescription,
+    Attributes,
+)
+from evo.objects.typed.exceptions import ObjectValidationError
+from evo.objects.typed.spatial import BaseSpatialObject, BaseSpatialObjectData
+from evo.objects.typed.types import BoundingBox
+from evo.objects.utils.table_formats import (
+    DOWNHOLE_COLLECTION_LOCATION_HOLES,
+    FLOAT_ARRAY_1,
+    FLOAT_ARRAY_3,
+    KnownTableFormat,
+)
+
+__all__ = [
+    "DownholeCollection",
+    "DownholeCollectionData",
+]
+
+_X = "x"
+_Y = "y"
+_Z = "z"
+_COORDINATE_COLUMNS = [_X, _Y, _Z]
+
+
+HolePath: TypeAlias = pd.DataFrame  # [ distance | dip | azimuth | <attributes> ]
+HoleChunks: TypeAlias = pd.DataFrame  # [ hole_id | offset | count ]
+HoleProperties: TypeAlias = pd.DataFrame  # [ hole_id | final | target | current | x | y | z ]
+HoleAttributes: TypeAlias = pd.DataFrame
+
+# If `Depths` has unit descriptions in its `DataFrame.attrs` dictionary, then those units will be used when building
+# the schema object.
+# This is the expected structure:
+#   >>> depths_df.attrs
+#   {'attribute_description': {<column names>:  <AttributeDescription>}, ...}
+Depths: TypeAlias = pd.DataFrame  # [ distance | <attributes> ]
+
+
+@dataclass
+class DistanceCollection:
+    name: str
+    holes: HoleChunks
+    distance_table: Depths
+    collection_type: str = "distance"
+
+
+@dataclass(kw_only=True, frozen=True)
+class DownholeCollectionData(BaseSpatialObjectData):
+    """Data class for creating a new DownholeCollection
+
+    :param name: The name of the object.
+    :param holes: A DataFrame describing which parts of `path` belong to which holes.
+            Columns: hole_id, offset, count
+    :param properties: DataFrame for the properties of the holes. The ith row corresponds to the ith element of `holes`.
+            Mandatory columns: hole_id, final, target, current, x, y, z
+    :param attributes: DataFrame for the attributes of the holes. The ith row corresponds to the ith element of `holes`.
+    :param path: Dataframe of [ distance | dip | azimuth | <attributes> ]. Distance/dip/azimuth describe the geometry as
+            the step since the previous row.
+    :param collections: A list of `DistanceCollection` describing a table of distances with attributes.
+    :param distance_unit: The distance unit for the `path` table and the `properties` x/y/y.
+    :param desurvey: The desurvey method appropriate for this collection.
+            Must be one of: "minimum_curvature", "balanced_tangent", "trench".
+    :param coordinate_reference_system: Optional EPSG code or WKT string for the coordinate reference system.
+    :param description: Optional description of the object.
+    :param tags: Optional dictionary of tags for the object.
+    :param extensions: Optional dictionary of extensions for the object.
+    """
+
+    path: HolePath
+    holes: HoleChunks
+    properties: HoleProperties
+    attributes: HoleAttributes | None
+    collections: list[DistanceCollection]
+    distance_unit: str | None
+    desurvey: str | None
+
+    def __post_init__(self):
+        if self.attributes is not None and len(self.holes) != len(self.attributes):
+            raise ObjectValidationError("The number of attributes rows must match the number or holes rows")
+
+        assert self.attributes is None or len(self.holes) == len(self.attributes)
+
+    def compute_bounding_box(self) -> BoundingBox:
+        bboxes = []
+
+        for i in range(len(self.holes)):
+            offset = self.holes.iat[i, 1]
+            count = self.holes.iat[i, 2]
+            collar = tuple(self.properties.loc[i, _COORDINATE_COLUMNS])
+            path_table = self.path[offset : offset + count]
+            bboxes.append(self._compute_hole_bounding_box(path_table, collar))
+
+        return BoundingBox.combine(bboxes)
+
+    @staticmethod
+    def _compute_bounding_box_np(
+        depths: NDArray[np.float64],
+        dips: NDArray[np.float64],
+        azimuths: NDArray[np.float64],
+        offset: tuple[float, float, float] = (0.0, 0.0, 0.0),
+    ) -> BoundingBox:
+        if not np.all(depths[:-1] <= depths[1:]):
+            raise ObjectValidationError("depths must be sorted")
+
+        if len(depths) != len(dips) or len(depths) != len(azimuths):
+            raise ObjectValidationError("depths, dips, and azimuths must have same length")
+
+        # Process NaNs
+        # `depths`, `dips`, and `azimuths` could be read-only views, so take copies instead of mutating
+        depths = depths[~np.isnan(depths)]
+        dips = np.where(np.isnan(dips), 90.0, dips)
+        azimuths = np.where(np.isnan(azimuths), 0.0, azimuths)
+
+        dips_rad = np.deg2rad(dips)
+        azimuths_rad = np.deg2rad(azimuths)
+
+        # Prepend 0 so `step` has the same shape as `dips` and `azimuths`, and so the first depth gets treated as the
+        # first step. The depth column might already start with 0, in which case the first step will be length 0, which
+        # is a no-op as far as the following calculation is concerned.
+        step = np.diff(depths, prepend=0.0)
+
+        dz_down = step * np.sin(dips_rad)
+        horiz = step * np.cos(dips_rad)
+
+        # Horizontal into N/E (0° = North, 90° = East)
+        dN = horiz * np.cos(azimuths_rad)
+        dE = horiz * np.sin(azimuths_rad)
+
+        # Convert to XYZ increments (Z up)
+        dX = dE
+        dY = dN
+        dZ = -dz_down
+
+        x = np.cumsum(dX)
+        y = np.cumsum(dY)
+        z = np.cumsum(dZ)
+
+        def ensure_zero(a, b):
+            return min(a, 0), max(b, 0)
+
+        x0, x1 = ensure_zero(x.min(), x.max())
+        y0, y1 = ensure_zero(y.min(), y.max())
+        z0, z1 = ensure_zero(z.min(), z.max())
+
+        return BoundingBox(
+            min_x=x0 + offset[0],
+            max_x=x1 + offset[0],
+            min_y=y0 + offset[1],
+            max_y=y1 + offset[1],
+            min_z=z0 + offset[2],
+            max_z=z1 + offset[2],
+        )
+
+    @staticmethod
+    def _compute_hole_bounding_box(
+        depths_dips_azimuths_table: pd.DataFrame,
+        collar: tuple[float, float, float],
+    ) -> BoundingBox:
+        """
+        Compute 3D bounding box for a deviated hole given collar XYZ and
+        depth / dip / azimuth data.
+
+        Conventions
+        -----------
+        - depths: measured depth along the hole (m), positive downward.
+        - dips: inclination FROM VERTICAL (degrees).
+            90° = vertical down, 0° = horizontal.
+        - azimuths: degrees clockwise from North.
+        - Coordinates: X = Easting, Y = Northing, Z = elevation (up).
+        """
+        df = depths_dips_azimuths_table.dropna(subset=["distance"])
+        box = DownholeCollectionData._compute_bounding_box_np(
+            df["distance"].astype(float).to_numpy(),
+            df["dip"].astype(float).to_numpy(),
+            df["azimuth"].astype(float).to_numpy(),
+            offset=collar,
+        )
+
+        return box
+
+
+class HoleChunksTable(DataTable):
+    table_format: ClassVar[KnownTableFormat] = DOWNHOLE_COLLECTION_LOCATION_HOLES
+    data_columns: ClassVar[list[str]] = ["hole_index", "offset", "count"]
+
+
+class PathTable(DataTable):
+    table_format: ClassVar[KnownTableFormat] = FLOAT_ARRAY_3
+    data_columns: ClassVar[list[str]] = ["distance", "azimuth", "dip"]
+
+
+class DownholePath(DataTableAndAttributes):
+    _table: Annotated[PathTable, SchemaLocation(""), DataLocation("")]
+
+
+class DistancesTable(DataTable):
+    table_format: ClassVar[KnownTableFormat] = FLOAT_ARRAY_3
+    data_columns: ClassVar[list[str]] = ["final", "target", "current"]
+
+    @classmethod
+    def _extract_distances(cls, data: HoleAttributes) -> pd.DataFrame:
+        return data[["final", "target", "current"]].astype(np.float64)
+
+    @classmethod
+    async def _data_to_schema(cls, data: HoleAttributes, context: IContext) -> Any:
+        distances_df = cls._extract_distances(data)
+        return await super()._data_to_schema(distances_df, context)
+
+
+class CollarCoordinates(DataTable):
+    table_format: ClassVar[KnownTableFormat] = FLOAT_ARRAY_3
+    data_columns: ClassVar[list[str]] = _COORDINATE_COLUMNS
+
+    @classmethod
+    def _extract_coordinates(cls, data: HoleAttributes):
+        return data[["x", "y", "z"]].astype(np.float64)
+
+    @classmethod
+    async def _data_to_schema(cls, data: HoleAttributes, context: IContext) -> Any:
+        distances_df = cls._extract_coordinates(data)
+        return await super()._data_to_schema(distances_df, context)
+
+
+class DownholeLocation(SchemaModel):
+    hole_id: Annotated[HoleIdCategory, SchemaLocation("hole_id"), DataLocation("properties")]
+    path: Annotated[DownholePath, SchemaLocation("path"), DataLocation("path")]
+    holes: Annotated[HoleChunksTable, SchemaLocation("holes"), DataLocation("holes")]
+    distances: Annotated[DistancesTable, SchemaLocation("distances"), DataLocation("properties")]
+    coordinates: Annotated[CollarCoordinates, SchemaLocation("coordinates"), DataLocation("properties")]
+    attributes: Annotated[Attributes, SchemaLocation("attributes"), DataLocation("attributes")]
+
+
+class _Distances(DataTable):
+    table_format: ClassVar[KnownTableFormat] = FLOAT_ARRAY_1
+    data_columns: ClassVar[list[str]] = ["distance"]
+
+
+class DistanceTableDistances(DataTableAndAttributes):
+    _table: Annotated[_Distances, SchemaLocation("values"), DataLocation("")]
+    unit: Annotated[str | None, SchemaLocation("unit")]
+
+    @classmethod
+    async def _data_to_schema(cls, data: pd.DataFrame, context: IContext) -> Any:
+        result = await super()._data_to_schema(data, context)
+        attr_desc: AttributeDescription = data.attrs.get("attribute_descriptions", {}).get("distance")
+        if attr_desc is not None and attr_desc.unit is not None:
+            # "unit" can be missing, but it must not be `None`
+            result["unit"] = attr_desc.unit
+        return result
+
+
+class DistanceTable(SchemaModel):
+    name: Annotated[str, SchemaLocation("name"), DataLocation("name")]
+    collection_type: Annotated[str, SchemaLocation("collection_type"), DataLocation("collection_type")]
+    distance: Annotated[DistanceTableDistances, SchemaLocation("distance"), DataLocation("distance_table")]
+
+
+class DownholeDistanceTable(DistanceTable):
+    holes: Annotated[HoleChunksTable, SchemaLocation("holes"), DataLocation("holes")]
+
+
+class DownholeCollectionTables(SchemaList[DownholeDistanceTable]):
+    pass
+
+
+class DownholeCollection(BaseSpatialObject):
+    """A GeoscienceObject representing a collection of downholes."""
+
+    _data_class = DownholeCollectionData
+    sub_classification = "downhole-collection"
+    creation_schema_version = SchemaVersion(major=1, minor=3, patch=1)
+
+    location: Annotated[DownholeLocation, SchemaLocation("location"), DataLocation("")]
+    collections: Annotated[DownholeCollectionTables, SchemaLocation("collections"), DataLocation("collections")]
+    distance_unit: Annotated[str | None, SchemaLocation("distance_unit")]
+    desurvey: Annotated[str | None, SchemaLocation("desurvey")]
+
+    type: ClassVar[Annotated[str, SchemaLocation("type")]] = "downhole"

{evo_objects-0.6.1 → evo_objects-0.6.2}/src/evo/objects/utils/data.py

@@ -9,7 +9,8 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
-from collections.abc import Iterator
+import asyncio
+from collections.abc import Iterator, Sequence
 from pathlib import Path
 from typing import Any, Iterable, cast
 from uuid import UUID
@@ -23,7 +24,7 @@ from evo.common.io.exceptions import DataExistsError
 from evo.common.utils import NoFeedback, PartialFeedback, split_feedback
 
 from ..exceptions import TableFormatError
-from ..io import _CACHE_SCOPE, ObjectDataUpload
+from ..io import _CACHE_SCOPE, ObjectDataDownload, ObjectDataUpload
 from .table_formats import INTEGER_ARRAY_1_INT32, INTEGER_ARRAY_MD_INT32, LOOKUP_TABLE_INT32
 from .tables import KnownTableFormat
 from .types import ArrayTableInfo, CategoryInfo, LookupTableInfo
@@ -46,6 +47,7 @@ __all__ = ["ObjectDataClient"]
 logger = logging.getLogger("object.data")
 
 _DATA_ID_KEY = "data"  # The key used to identify data references in geoscience objects.
+_DEFAULT_MAX_CONCURRENCY = 4  # Decent performance improvement going from 1 to 4 but beyond that not so much
 
 
 def _iter_refs(target: Any, _key: str | None = None) -> Iterator[str]:
@@ -287,20 +289,110 @@ class ObjectDataClient:
         :raises TableFormatError: If the data does not match the expected format.
         :raises SchemaValidationError: If the data has a different number of rows than expected.
         """
+        data_id = str(table_info["data"])
+        downloads = await self._prepare_data_downloads(object_id, version_id, [data_id])
+        return await self._download_prepared_table(downloads[data_id], table_info, fb)
+
+    async def _prepare_data_downloads(
+        self, object_id: UUID, version_id: str, data_identifiers: Sequence[str | UUID]
+    ) -> dict[str, ObjectDataDownload]:
+        """Prepare download contexts for multiple data files with one object metadata request.
+
+        :param object_id: The object ID to download data from.
+        :param version_id: The version ID of the object to download data from.
+        :param data_identifiers: The data IDs to download.
+
+        :return: A mapping of data IDs to prepared download contexts.
+
+        :raises DataNotFoundError: If a data ID is not associated with this object version.
+        """
         # Import here to avoid circular import.
         from ..client import ObjectAPIClient
-        from ..parquet import ParquetDownloader
+
+        if len(data_identifiers) == 0:
+            return {}
+
+        data_ids = list({str(data_id) for data_id in data_identifiers})
 
         client = ObjectAPIClient(self._environment, self._connector)
-        (download,) = [d async for d in client.prepare_data_download(object_id, version_id, [table_info["data"]])]
+        downloads = [download async for download in client.prepare_data_download(object_id, version_id, data_ids)]
+        return {download.name: download for download in downloads}
+
+    async def _download_prepared_table(self, download: ObjectDataDownload, table_info: dict, fb: IFeedback) -> pa.Table:
+        """Download and load one table using a prepared download context.
+
+        :param download: The prepared context for the table's data.
+        :param table_info: The table info that defines the expected format.
+        :param fb: A feedback object for tracking download progress.
+
+        :return: A pyarrow table loaded directly from the parquet file.
+        """
+        # Import here to avoid circular import.
+        from ..parquet import ParquetDownloader
 
-        # Defer downloading the table to the new ParquetLoader class.
         async with ParquetDownloader(
             download=download, transport=self._connector.transport, cache=self._cache
         ).with_feedback(fb) as loader:
             loader.validate_with_table_info(table_info)
             return loader.load_as_table()
 
+    async def download_tables(
+        self,
+        object_id: UUID,
+        version_id: str,
+        table_infos: Sequence[dict],
+        fb: IFeedback = NoFeedback,
+        max_concurrency: int = _DEFAULT_MAX_CONCURRENCY,
+    ) -> dict[str, pa.Table]:
+        """Download multiple pyarrow tables with one object metadata request.
+
+        The data references are prepared once and the table downloads are performed concurrently, up to
+        ``max_concurrency`` at a time. Duplicate data references are downloaded only once.
+
+        :param object_id: The object ID to download data from.
+        :param version_id: The version ID of the object to download data from.
+        :param table_infos: The table information that defines the expected format of each table.
+        :param fb: A feedback object for tracking download progress.
+        :param max_concurrency: The maximum number of tables to download concurrently.
+
+        :return: A mapping of data IDs to loaded pyarrow tables.
+
+        :raises ValueError: If ``max_concurrency`` is less than one.
+        :raises DataNotFoundError: If a data ID is not associated with this object version.
+        :raises TableFormatError: If a table does not match its expected format.
+        :raises SchemaValidationError: If a table has a different number of rows than expected.
+        """
+        if max_concurrency < 1:
+            raise ValueError("max_concurrency must be at least 1")
+
+        table_infos_by_data_id: dict[str, dict] = {str(table_info["data"]): table_info for table_info in table_infos}
+
+        if len(table_infos_by_data_id) == 0:
+            return {}
+
+        data_ids = list(table_infos_by_data_id)
+        downloads = await self._prepare_data_downloads(object_id, version_id, data_ids)
+        feedbacks = split_feedback(fb, [1.0] * len(data_ids))
+        semaphore = asyncio.Semaphore(max_concurrency)
+
+        async def download_one(data_id: str, table_info: dict, table_fb: IFeedback) -> pa.Table:
+            async with semaphore:
+                return await self._download_prepared_table(downloads[data_id], table_info, table_fb)
+
+        tasks = {
+            data_id: asyncio.create_task(download_one(data_id, table_info, table_fb))
+            for (data_id, table_info), table_fb in zip(table_infos_by_data_id.items(), feedbacks)
+        }
+        try:
+            await asyncio.gather(*tasks.values())
+        except BaseException:
+            # asyncio.gather doesn't cancel sibling tasks if one fails, manually cancel other tasks if one fails
+            for task in tasks.values():
+                task.cancel()
+            await asyncio.gather(*tasks.values(), return_exceptions=True)
+            raise
+        return {data_id: task.result() for data_id, task in tasks.items()}
+
     if _PD_AVAILABLE:
         # Optional support for pandas dataframes. Depends on both pyarrow and pandas.