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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: evo-objects
-Version: 0.4.3
+Version: 0.6.1
 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
@@ -9,7 +9,7 @@ Project-URL: Documentation, https://developer.seequent.com/
 Author-email: Seequent <support@seequent.com>
 License-File: LICENSE.md
 Requires-Python: >=3.10
-Requires-Dist: evo-sdk-common[jmespath]>=0.5.8
+Requires-Dist: evo-sdk-common[jmespath]>=0.5.26
 Requires-Dist: pydantic<3,>=2
 Provides-Extra: aiohttp
 Requires-Dist: evo-sdk-common[aiohttp]; extra == 'aiohttp'

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

@@ -1,7 +1,7 @@
 [project]
 name = "evo-objects"
 description = "Python SDK for using the Seequent Evo Geoscience Object API"
-version = "0.4.3"
+version = "0.6.1"
 requires-python = ">=3.10"
 license-files = ["LICENSE.md"]
 dynamic = ["readme"]
@@ -10,7 +10,7 @@ authors = [
 ]
 
 dependencies = [
-    "evo-sdk-common[jmespath]>=0.5.8",
+    "evo-sdk-common[jmespath]>=0.5.26",
     "pydantic>=2,<3",
 ]
 

{evo_objects-0.4.3 → evo_objects-0.6.1}/src/evo/objects/typed/__init__.py

@@ -1,4 +1,4 @@
-#  Copyright © 2025 Bentley Systems, Incorporated
+#  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
@@ -22,6 +22,8 @@ from .base import BaseObject, object_from_path, object_from_reference, object_fr
 from .block_model_ref import (
     BlockModel,
 )
+from .downhole_collection import DownholeCollection, DownholeCollectionData
+from .downhole_intervals import DownholeIntervals, DownholeIntervalsData
 from .pointset import (
     Locations,
     PointSet,
@@ -80,6 +82,10 @@ __all__ = [
     "BoundingBox",
     "CoordinateReferenceSystem",
     "CubicStructure",
+    "DownholeCollection",
+    "DownholeCollectionData",
+    "DownholeIntervals",
+    "DownholeIntervalsData",
     "Ellipsoid",
     "EllipsoidRanges",
     "EpsgCode",

{evo_objects-0.4.3 → evo_objects-0.6.1}/src/evo/objects/typed/_data.py

@@ -1,3 +1,14 @@
+#  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 typing import Annotated, Any, ClassVar
@@ -111,7 +122,7 @@ class DataTableAndAttributes(SchemaModel):
         if attr_df is not None:
             await self.attributes.set_attributes(attr_df, fb=fb)
         else:
-            await self.attributes.clear()
+            self.attributes.clear()
 
     def validate(self) -> None:
         """Validate that all attributes have the correct length."""
@@ -143,4 +154,6 @@ class DataTableAndAttributes(SchemaModel):
         builder = SchemaBuilder(cls, context)
         await builder.set_sub_model_value("_table", table_df)
         await builder.set_sub_model_value("attributes", attr_df)
-        return builder.document
+
+        # As we specially handle the _table and attributes sub-models above, we skip them in the default data processing of build_from_data.
+        return await builder.build_from_data(data, skip_sub_models={"_table", "attributes"})

evo_objects-0.6.1/src/evo/objects/typed/_downhole.py

@@ -0,0 +1,62 @@
+#  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.
+
+"""Shared sub-models for downhole typed objects."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, ClassVar
+
+import pandas as pd
+
+from evo.common.interfaces import IContext
+from evo.objects.utils.table_formats import FLOAT_ARRAY_2, KnownTableFormat
+
+from ._data import DataTable
+from ._model import DataLocation, SchemaLocation, SchemaModel
+from .attributes import Category
+
+_HOLE_ID_COL = "hole_id"
+_FROM_COL = "from"
+_TO_COL = "to"
+_DEPTH_COLS: list[str] = [_FROM_COL, _TO_COL]
+
+
+class HoleIdCategory(Category):
+    """Categorical hole identifier column, shared by downhole typed objects."""
+
+    @classmethod
+    async def _data_to_schema(cls, data: pd.DataFrame, context: IContext) -> Any:
+        category_table = data[[_HOLE_ID_COL]].astype("category")
+        return await super()._data_to_schema(category_table, context=context)
+
+
+class DepthIntervalsTable(DataTable):
+    table_format: ClassVar[KnownTableFormat] = FLOAT_ARRAY_2
+    data_columns: ClassVar[list[str]] = _DEPTH_COLS
+
+    @classmethod
+    async def _data_to_schema(cls, data: pd.DataFrame, context: IContext) -> Any:
+        return await super()._data_to_schema(data[_DEPTH_COLS], context)
+
+
+class FromToModel(SchemaModel):
+    """Schema model for the `from_to` component of a downhole intervals object."""
+
+    intervals: Annotated[DepthIntervalsTable, SchemaLocation("intervals.start_and_end"), DataLocation("intervals")]
+    unit: Annotated[str | None, SchemaLocation("unit"), DataLocation("depth_unit")]
+
+    @classmethod
+    async def _data_to_schema(cls, data: Any, context: IContext) -> Any:
+        result = await super()._data_to_schema(data, context)
+        if data.depth_unit is not None:
+            result["unit"] = data.depth_unit
+        return result

{evo_objects-0.4.3 → evo_objects-0.6.1}/src/evo/objects/typed/_model.py

@@ -14,7 +14,7 @@ from __future__ import annotations
 import copy
 from collections.abc import Sequence
 from dataclasses import dataclass, field
-from typing import Annotated, Any, Callable, Generic, TypeVar, get_args, get_origin, get_type_hints, overload
+from typing import Annotated, Any, Callable, ClassVar, Generic, TypeVar, get_args, get_origin, get_type_hints, overload
 
 from pydantic import TypeAdapter
 
@@ -86,11 +86,8 @@ class SubModelMetadata:
     """The field name in the data class for this sub-model."""
 
 
-class SchemaProperty(Generic[_T]):
-    """Descriptor for data within a Geoscience Object schema.
-
-    This can be used on either typed objects classes or dataset classes.
-    """
+class BaseSchemaProperty(Generic[_T]):
+    """Base descriptor for reading data from a Geoscience Object schema."""
 
     def __init__(
         self,
@@ -111,7 +108,7 @@ class SchemaProperty(Generic[_T]):
         return self._type_adapter.dump_python(value)
 
     @overload
-    def __get__(self, instance: None, owner: type[SchemaModel]) -> SchemaProperty[_T]: ...
+    def __get__(self, instance: None, owner: type[SchemaModel]) -> BaseSchemaProperty[_T]: ...
 
     @overload
     def __get__(self, instance: SchemaModel, owner: type[SchemaModel]) -> _T: ...
@@ -128,6 +125,13 @@ class SchemaProperty(Generic[_T]):
         # Use TypeAdapter to validate and apply defaults from Field annotations
         return self._type_adapter.validate_python(value)
 
+
+class SchemaProperty(BaseSchemaProperty[_T]):
+    """Descriptor for mutable data within a Geoscience Object schema.
+
+    This can be used on either typed objects classes or dataset classes.
+    """
+
     def __set__(self, instance: SchemaModel, value: Any) -> None:
         _set_property_value(self, instance._document, value)
 
@@ -140,7 +144,19 @@ class SchemaProperty(Generic[_T]):
         _set_property_value(self, document, value)
 
 
-def _set_property_value(schema_property: SchemaProperty, document: dict[str, Any], value: Any) -> None:
+class SchemaConstantProperty(BaseSchemaProperty[_T]):
+    """A SchemaProperty that always writes a fixed value to the schema."""
+
+    def __init__(self, jmespath_expr: str, type_adapter: TypeAdapter[_T], value: _T) -> None:
+        super().__init__(jmespath_expr=jmespath_expr, type_adapter=type_adapter)
+        self._value = value
+
+    @property
+    def value(self) -> _T:
+        return self._value
+
+
+def _set_property_value(schema_property: BaseSchemaProperty, document: dict[str, Any], value: Any) -> None:
     """Set the value of a SchemaProperty by name.
 
     :param property_name: The name of the property to set.
@@ -177,6 +193,26 @@ class SchemaBuilder:
         else:
             self.document.update(sub_document)
 
+    async def build_from_data(self, data: Any, skip_sub_models: set[str] | None = None) -> dict[str, Any]:
+        """Build the schema document by applying all properties and sub-models."""
+        for key, prop in self._properties.items():
+            if isinstance(prop, SchemaConstantProperty):
+                self.set_property(key, prop.value)
+            else:
+                value = getattr(data, key, None)
+                self.set_property(key, value)
+
+        for name, metadata in self._sub_models.items():
+            if skip_sub_models and name in skip_sub_models:
+                continue
+            if metadata.data_field:
+                sub_data = getattr(data, metadata.data_field, None)
+            else:
+                sub_data = data
+            await self.set_sub_model_value(name, sub_data)
+
+        return self.document
+
 
 def _get_base_type(annotation: Any) -> tuple[Any, SchemaLocation | None, DataLocation | None]:
     """Extract the base type and SchemaLocation from an annotation.
@@ -208,14 +244,14 @@ class SchemaModel:
     automatically created for nested SchemaModel/SchemaList fields.
     """
 
-    _schema_properties: dict[str, SchemaProperty[Any]] = {}
+    _schema_properties: dict[str, BaseSchemaProperty[Any]] = {}
     _sub_models: dict[str, SubModelMetadata] = {}
 
     def __init_subclass__(cls, **kwargs: Any) -> None:
         super().__init_subclass__(**kwargs)
 
         # Initialize with inherited values (copy to avoid mutating parent)
-        schema_properties: dict[str, SchemaProperty[Any]] = {}
+        schema_properties: dict[str, BaseSchemaProperty[Any]] = {}
         sub_models: dict[str, SubModelMetadata] = {}
         for base in cls.__mro__[1:]:
             if issubclass(base, SchemaModel):
@@ -232,8 +268,28 @@ class SchemaModel:
             cls._sub_models = sub_models
             return
 
-        # Process the resolved annotations
+        # Process the resolved annotations, to produce the final set of schema properties and sub-models for this class
         for field_name, annotation in hints.items():
+            # Handle ClassVar fields
+            if get_origin(annotation) is ClassVar:
+                inner_args = get_args(annotation)
+                inner_type = inner_args[0]
+                base_type, schema_location, _ = _get_base_type(inner_type)
+                # Skip class variables without a SchemaLocation, e.g. data_columns: ClassVar[list[str]] = [],
+                if schema_location is None:
+                    continue
+
+                # Treat such remaining ClassVar fields as constants, which also have a corresponding value in the schema
+                type_adapter = TypeAdapter(base_type)
+                prop = SchemaConstantProperty(
+                    jmespath_expr=schema_location.jmespath_expr,
+                    type_adapter=type_adapter,
+                    value=getattr(cls, field_name),
+                )
+                setattr(cls, field_name, prop)
+                schema_properties[field_name] = prop
+                continue
+
             base_type, schema_location, data_location = _get_base_type(annotation)
 
             # Skip fields without a SchemaLocation
@@ -348,16 +404,7 @@ class SchemaModel:
         :return: The dictionary representation of the data.
         """
         builder = SchemaBuilder(cls, context)
-        for key in cls._schema_properties.keys():
-            value = getattr(data, key, None)
-            builder.set_property(key, value)
-        for name, metadata in cls._sub_models.items():
-            if metadata.data_field:
-                sub_data = getattr(data, metadata.data_field, None)
-            else:
-                sub_data = data
-            await builder.set_sub_model_value(name, sub_data)
-        return builder.document
+        return await builder.build_from_data(data)
 
     def search(self, expression: str) -> Any:
         """Search the model using a JMESPath expression.

{evo_objects-0.4.3 → evo_objects-0.6.1}/src/evo/objects/typed/attributes.py

@@ -1,4 +1,4 @@
-#  Copyright © 2025 Bentley Systems, Incorporated
+#  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
@@ -11,7 +11,9 @@
 
 from __future__ import annotations
 
+import typing
 import uuid
+from dataclasses import dataclass
 from typing import TYPE_CHECKING, Annotated, Any
 from uuid import UUID
 
@@ -23,6 +25,7 @@ from evo.common.utils import NoFeedback, iter_with_fb
 from evo.objects import DownloadedObject
 from evo.objects.utils.table_formats import (
     BOOL_ARRAY_1,
+    DATE_TIME_ARRAY,
     FLOAT_ARRAY_1,
     INTEGER_ARRAY_1_INT32,
     INTEGER_ARRAY_1_INT64,
@@ -67,6 +70,8 @@ def _infer_attribute_type_from_series(series: pd.Series) -> str:
         return "category"
     elif pd.api.types.is_string_dtype(series):
         return "string"
+    elif pd.api.types.infer_dtype(series, skipna=True) in ["date", "datetime", "datetime64"]:
+        return "date_time"
     else:
         raise UnSupportedDataTypeError(f"Unsupported dtype for attribute: {series.dtype}")
 
@@ -76,9 +81,35 @@ _attribute_table_formats = {
     "integer": [INTEGER_ARRAY_1_INT32, INTEGER_ARRAY_1_INT64],
     "bool": [BOOL_ARRAY_1],
     "string": [STRING_ARRAY],
+    "date_time": [DATE_TIME_ARRAY],
 }
 
 
+@dataclass
+class AttributeDescription:
+    discipline: str = ""
+    type: str = ""
+    unit: str | None = None
+    scale: str | None = None
+    extensions: dict[str, typing.Any] | None = None
+    tags: dict[str, str] | None = None
+
+    def to_schema(self):
+        result = {
+            "discipline": self.discipline,
+            "type": self.type,
+        }
+        if self.unit:
+            result["unit"] = self.unit
+        if self.scale:
+            result["scale"] = self.scale
+        if self.extensions:
+            result["extensions"] = self.extensions
+        if self.tags:
+            result["tags"] = self.tags
+        return result
+
+
 class Attribute(SchemaModel):
     """A Geoscience Object Attribute"""
 
@@ -158,7 +189,7 @@ class Attribute(SchemaModel):
             table_formats = _attribute_table_formats.get(attribute_type)
             attr_doc["values"] = await data_client.upload_dataframe(df, table_format=table_formats, fb=fb)
 
-        if attribute_type in ["scalar", "integer", "category"]:
+        if attribute_type in ["scalar", "integer", "category", "date_time"]:
             attr_doc["nan_description"] = {"values": []}
 
 
@@ -203,7 +234,15 @@ class PendingAttribute:
 
 
 class Attributes(SchemaList[Attribute]):
-    """A collection of Geoscience Object Attributes"""
+    """A collection of Geoscience Object Attributes
+
+    The data source is a pandas DataFrame. If the DataFrame has attribute descriptions attached
+    to it, then they will be used to populate the schema's "attribute_description" fields. The
+    attribute descriptions are attached to the DataFrame's `attrs` attribute.
+
+    >>> df.attrs
+    {'attribute_description': {<column names>:  <AttributeDescription>}, ...}
+    """
 
     _schema_path: str | None = None
     """The full JMESPath to this attributes list within the parent object schema."""
@@ -263,7 +302,7 @@ class Attributes(SchemaList[Attribute]):
 
         for col in df.columns:
             series = df[col]
-            attribute_type = _infer_attribute_type_from_series(series)
+            attribute_type = _infer_attribute_type_from_series(df[col])
 
             attr_doc: dict[str, Any] = {
                 "name": str(col),
@@ -271,9 +310,19 @@ class Attributes(SchemaList[Attribute]):
                 "attribute_type": attribute_type,
             }
 
-            col_df = df[[col]]
+            if attribute_type == "date_time":
+                series = pd.to_datetime(series, utc=True).dt.as_unit("us")
+
+            col_df = pd.DataFrame({col: series})
             await Attribute._upload_attribute_values(attr_doc, col_df, attribute_type, data_client)
 
+            attr_desc: AttributeDescription | None = df.attrs.get("attribute_descriptions", {}).get(col)
+            if attr_desc is not None:
+                if not isinstance(attr_desc, AttributeDescription):
+                    raise TypeError("attribute description must be a AttributeDescription.")
+                if attr_desc.unit is not None:
+                    attr_doc["attribute_description"] = attr_desc.to_schema()
+
             attributes_list.append(attr_doc)
 
     async def to_dataframe(self, *keys: str, fb: IFeedback = NoFeedback) -> pd.DataFrame:
@@ -528,3 +577,27 @@ class BlockModelAttributes:
     def __repr__(self) -> str:
         names = [attr.name for attr in self._attributes]
         return f"BlockModelAttributes({names})"
+
+
+class Category(SchemaModel):
+    _data: Annotated[str, SchemaLocation("values.data")]
+    _length: Annotated[int, SchemaLocation("values.length")]
+
+    @property
+    def length(self):
+        return self._length
+
+    @classmethod
+    async def _data_to_schema(cls, category_table, context: IContext) -> Any:
+        data_client = get_data_client(context)
+        return await data_client.upload_category_dataframe(category_table)
+
+    async def to_dataframe(self, fb: IFeedback = NoFeedback) -> pd.DataFrame:
+        """Load a DataFrame containing values for this table.
+
+        :param fb: Optional feedback object to report download progress.
+        :return: The loaded DataFrame with values for this table.
+        """
+        if self._context.is_data_modified(self._data):
+            raise DataLoaderError("Data was modified since the object was downloaded")
+        return await self._obj.download_category_dataframe(self.as_dict(), fb=fb)

{evo_objects-0.4.3 → evo_objects-0.6.1}/src/evo/objects/typed/base.py

@@ -227,31 +227,8 @@ class _BaseObject(SchemaModel):
                 "sub_classification and creation_schema_version must be defined by the subclass"
             )
         schema_id = ObjectSchema("objects", cls.sub_classification, cls.creation_schema_version)
-        result: dict[str, Any] = {
-            "schema": str(schema_id),
-        }
-
-        # Handle schema properties
-        for key, prop in cls._schema_properties.items():
-            value = getattr(data, key, None)
-            if value is not None:
-                prop.apply_to(result, value)
-
-        # Handle annotation-based sub-models
-        for name, metadata in cls._sub_models.items():
-            if metadata.data_field:
-                sub_data = getattr(data, metadata.data_field, None)
-            else:
-                sub_data = data
-            if sub_data is not None:
-                from ._utils import assign_jmespath_value
-
-                sub_document = await metadata.model_type._data_to_schema(sub_data, context)
-                if metadata.jmespath_expr:
-                    assign_jmespath_value(result, metadata.jmespath_expr, sub_document)
-                else:
-                    result.update(sub_document)
-
+        result = await super()._data_to_schema(data, context)
+        result["schema"] = str(schema_id)
         return result
 
     @classmethod

evo_objects-0.6.1/src/evo/objects/typed/downhole_collection.py

@@ -0,0 +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"

evo_objects-0.6.1/src/evo/objects/typed/downhole_intervals.py

@@ -0,0 +1,246 @@
+#  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.
+
+"""Typed access for downhole-intervals objects."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Annotated, Any, ClassVar
+
+import pandas as pd
+
+from evo.common import IContext, IFeedback
+from evo.common.utils import NoFeedback
+from evo.objects import SchemaVersion
+from evo.objects.utils.table_formats import FLOAT_ARRAY_3
+
+from ._data import DataTable
+from ._downhole import FromToModel, HoleIdCategory
+from ._model import DataLocation, SchemaLocation
+from .attributes import Attributes
+from .exceptions import ObjectValidationError
+from .spatial import BaseSpatialObject, BaseSpatialObjectData
+from .types import BoundingBox
+
+__all__ = [
+    "DownholeIntervals",
+    "DownholeIntervalsData",
+]
+
+
+_HOLE_ID_COL = "hole_id"
+_FROM_COL = "from"
+_TO_COL = "to"
+_START_COLS: list[str] = ["x_start", "y_start", "z_start"]
+_END_COLS: list[str] = ["x_end", "y_end", "z_end"]
+_MID_COLS: list[str] = ["x_mid", "y_mid", "z_mid"]
+
+_ALL_REQUIRED_COLS: frozenset[str] = frozenset([_HOLE_ID_COL, _FROM_COL, _TO_COL] + _START_COLS + _END_COLS + _MID_COLS)
+
+
+@dataclass(kw_only=True, frozen=True)
+class DownholeIntervalsData(BaseSpatialObjectData):
+    """Data for creating a new DownholeIntervals object.
+
+    :param name: The name of the object.
+    :param intervals: DataFrame containing the interval data. Required columns:
+
+        * `hole_id` — hole identifier (string or Categorical)
+        * `from` — depth of the top of the interval
+        * `to` — depth of the base of the interval
+        * `x_start`, `y_start`, `z_start` — 3D start-point coordinates
+        * `x_end`, `y_end`, `z_end` — 3D end-point coordinates
+        * `x_mid`, `y_mid`, `z_mid` — 3D mid-point coordinates
+
+        Any additional columns are uploaded as interval attributes. Per-attribute
+        units can be specified via the DataFrame's `attrs` dictionary using
+        :class:`~evo.objects.typed.attributes.AttributeDescription`::
+
+            from evo.objects.typed.attributes import AttributeDescription
+            df.attrs["attribute_descriptions"] = {"grade": AttributeDescription(unit="ppm")}
+
+    :param is_composited: Whether the intervals have been composited.
+    :param depth_unit: Optional unit identifier for the from/to depths (e.g. `"m"`).
+    :param coordinate_reference_system: Optional EPSG code or OGC WKT string for the CRS.
+    :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.
+    """
+
+    intervals: pd.DataFrame
+    is_composited: bool
+    depth_unit: str | None = None
+
+    def __post_init__(self) -> None:
+        missing = _ALL_REQUIRED_COLS - set(self.intervals.columns)
+        if missing:
+            raise ObjectValidationError(f"intervals DataFrame is missing required columns: {sorted(missing)}")
+
+    def compute_bounding_box(self) -> BoundingBox:
+        """Compute the bounding box from all start, end, and mid-point coordinates."""
+        df = self.intervals
+        all_x = pd.concat([df["x_start"], df["x_end"], df["x_mid"]])
+        all_y = pd.concat([df["y_start"], df["y_end"], df["y_mid"]])
+        all_z = pd.concat([df["z_start"], df["z_end"], df["z_mid"]])
+        return BoundingBox.from_points(all_x.values, all_y.values, all_z.values)
+
+
+class StartCoordTable(DataTable):
+    table_format: ClassVar = FLOAT_ARRAY_3
+    data_columns: ClassVar[list[str]] = _START_COLS
+
+    @classmethod
+    async def _data_to_schema(cls, data: pd.DataFrame, context: IContext) -> Any:
+        return await super()._data_to_schema(data[_START_COLS], context)
+
+
+class EndCoordTable(DataTable):
+    table_format: ClassVar = FLOAT_ARRAY_3
+    data_columns: ClassVar[list[str]] = _END_COLS
+
+    @classmethod
+    async def _data_to_schema(cls, data: pd.DataFrame, context: IContext) -> Any:
+        return await super()._data_to_schema(data[_END_COLS], context)
+
+
+class MidCoordTable(DataTable):
+    table_format: ClassVar = FLOAT_ARRAY_3
+    data_columns: ClassVar[list[str]] = _MID_COLS
+
+    @classmethod
+    async def _data_to_schema(cls, data: pd.DataFrame, context: IContext) -> Any:
+        return await super()._data_to_schema(data[_MID_COLS], context)
+
+
+class IntervalAttributes(Attributes):
+    """Attributes sub-model that filters out required columns before upload."""
+
+    @classmethod
+    async def _data_to_schema(cls, data: Any, context: IContext) -> list[dict[str, Any]]:
+        if data is not None:
+            attr_cols = [c for c in data.columns if c not in _ALL_REQUIRED_COLS]
+            data = data[attr_cols] if attr_cols else None
+        return await super()._data_to_schema(data, context)
+
+
+class DownholeIntervals(BaseSpatialObject):
+    """A GeoscienceObject representing downhole intervals.
+
+    Downhole intervals describe depth-ranged samples along drill holes.  Each
+    interval is defined by a hole identifier, a from/to depth range, and the
+    3D coordinates of the interval's start, end, and mid-point.  Optional
+    attributes (assay values, lithology codes, etc.) may also be attached.
+
+    Example usage::
+
+        import pandas as pd
+        from evo.objects.typed import DownholeIntervals, DownholeIntervalsData
+
+        df = pd.DataFrame(
+            {
+                "hole_id": pd.Categorical(["DH001", "DH001", "DH002"]),
+                "from":    [0.0,  5.0,  0.0],
+                "to":      [5.0, 10.0,  3.0],
+                "x_start": [100.0, 100.0, 200.0],
+                "y_start": [200.0, 200.0, 300.0],
+                "z_start": [  0.0,  -5.0,   0.0],
+                "x_end":   [100.0, 100.0, 200.0],
+                "y_end":   [200.0, 200.0, 300.0],
+                "z_end":   [ -5.0, -10.0,  -3.0],
+                "x_mid":   [100.0, 100.0, 200.0],
+                "y_mid":   [200.0, 200.0, 300.0],
+                "z_mid":   [ -2.5,  -7.5,  -1.5],
+            }
+        )
+        data = DownholeIntervalsData(
+            name="My Downhole Intervals",
+            intervals=df,
+            is_composited=False,
+            depth_unit="m",
+        )
+        obj = await DownholeIntervals.create(context, data)
+
+        # Download all data as a single DataFrame
+        df = await obj.to_dataframe()
+    """
+
+    _data_class = DownholeIntervalsData
+
+    sub_classification = "downhole-intervals"
+    creation_schema_version = SchemaVersion(major=1, minor=3, patch=0)
+
+    is_composited: Annotated[bool, SchemaLocation("is_composited")]
+
+    start: Annotated[StartCoordTable, SchemaLocation("start.coordinates"), DataLocation("intervals")]
+    end: Annotated[EndCoordTable, SchemaLocation("end.coordinates"), DataLocation("intervals")]
+    mid_points: Annotated[MidCoordTable, SchemaLocation("mid_points.coordinates"), DataLocation("intervals")]
+    from_to: Annotated[FromToModel, SchemaLocation("from_to")]
+    hole_id: Annotated[HoleIdCategory, SchemaLocation("hole_id"), DataLocation("intervals")]
+    attributes: Annotated[IntervalAttributes, SchemaLocation("attributes"), DataLocation("intervals")]
+
+    @property
+    def depth_unit(self) -> str | None:
+        """The unit of the from/to depths, or None if not specified."""
+        return self.from_to.unit
+
+    @property
+    def num_intervals(self) -> int:
+        """The number of intervals in this object."""
+        return self.from_to.intervals.length
+
+    async def to_dataframe(self, *keys: str, fb: IFeedback = NoFeedback) -> pd.DataFrame:
+        """Get all interval data as a single DataFrame.
+
+        The returned DataFrame has the following columns, in order:
+
+        * `hole_id` — hole identifier
+        * `from`, `to` — depth interval
+        * `x_start`, `y_start`, `z_start` — start-point coordinates
+        * `x_end`, `y_end`, `z_end` — end-point coordinates
+        * `x_mid`, `y_mid`, `z_mid` — mid-point coordinates
+        * Any attribute columns
+
+        :param keys: Optional attribute keys/names to include.  If omitted, all
+            attributes are included.
+        :param fb: Optional feedback object to report download progress.
+        :return: A combined DataFrame of all interval data and attributes.
+        """
+        hole_id_df = await self.hole_id.to_dataframe(fb=fb)
+        depth_df = await self.from_to.intervals.to_dataframe(fb=fb)
+        start_df = await self.start.to_dataframe(fb=fb)
+        end_df = await self.end.to_dataframe(fb=fb)
+        mid_df = await self.mid_points.to_dataframe(fb=fb)
+
+        parts: list[pd.DataFrame] = [hole_id_df, depth_df, start_df, end_df, mid_df]
+
+        if len(self.attributes) > 0:
+            attr_df = await self.attributes.to_dataframe(*keys, fb=fb)
+            parts.append(attr_df)
+
+        return pd.concat(parts, axis=1)
+
+    def validate(self) -> None:
+        """Validate the object, checking that all interval tables have consistent lengths."""
+        super().validate()
+        expected_length = self.num_intervals
+        for table_name, table in (
+            ("hole_id", self.hole_id),
+            ("start.coordinates", self.start),
+            ("end.coordinates", self.end),
+            ("mid_points.coordinates", self.mid_points),
+        ):
+            if table.length != expected_length:
+                raise ObjectValidationError(
+                    f"{table_name} length ({table.length}) does not match expected length ({expected_length})"
+                )
+
+        self.attributes.validate_lengths(expected_length)

{evo_objects-0.4.3 → evo_objects-0.6.1}/src/evo/objects/typed/spatial.py

@@ -48,6 +48,7 @@ class BaseSpatialObject(BaseObject):
     """Base class for all Geoscience Objects with spatial data."""
 
     _bbox_type_adapter: ClassVar[TypeAdapter[BoundingBox]] = TypeAdapter(BoundingBox)
+    _crs_type_adapter: ClassVar[TypeAdapter[CoordinateReferenceSystem]] = TypeAdapter(CoordinateReferenceSystem)
     _bounding_box: Annotated[BoundingBox, SchemaLocation("bounding_box")]
     coordinate_reference_system: Annotated[CoordinateReferenceSystem, SchemaLocation("coordinate_reference_system")]
 
@@ -56,14 +57,7 @@ class BaseSpatialObject(BaseObject):
         """Create a object dictionary suitable for creating a new Geoscience Object."""
         object_dict = await super()._data_to_schema(data, context)
         object_dict["bounding_box"] = cls._bbox_type_adapter.dump_python(data.compute_bounding_box())
-        # Always set coordinate_reference_system, defaulting to "unspecified" if None
-        crs = data.coordinate_reference_system
-        if crs is None:
-            object_dict["coordinate_reference_system"] = "unspecified"
-        elif isinstance(crs, int):
-            object_dict["coordinate_reference_system"] = {"epsg_code": crs}
-        else:
-            object_dict["coordinate_reference_system"] = crs
+        object_dict["coordinate_reference_system"] = cls._crs_type_adapter.dump_python(data.coordinate_reference_system)
         return object_dict
 
     # The bounding box is defined as regular a property so that subclasses can override it if needed

{evo_objects-0.4.3 → evo_objects-0.6.1}/src/evo/objects/typed/types.py

@@ -1,4 +1,4 @@
-#  Copyright © 2025 Bentley Systems, Incorporated
+#  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
@@ -17,9 +17,9 @@ from typing import Annotated, Any, overload
 import numpy as np
 import numpy.typing as npt
 import pydantic
-from pydantic_core import core_schema
 
 # Import basic geometry types from evo.common and re-export
+from evo.common.crs import EpsgCode, parse_crs
 from evo.common.typed import Point3, Size3d, Size3i
 
 __all__ = [
@@ -35,36 +35,6 @@ __all__ = [
 ]
 
 
-class EpsgCode(int):
-    """An integer representing an EPSG code."""
-
-    def __new__(cls, value: int | str) -> EpsgCode:
-        if isinstance(value, str):
-            try:
-                value = int(value)
-            except ValueError as ve:
-                raise ValueError(f"Cannot convert '{value}' to an integer EPSG code") from ve
-
-        if not (1024 <= value <= 32767):
-            raise ValueError(f"EPSG code must be between 1024 and 32767, got {value}")
-
-        return int.__new__(cls, value)
-
-    def __repr__(self) -> str:
-        return f"EpsgCode({int(self)})"
-
-    def __str__(self):
-        return f"EPSG:{int(self)}"
-
-    @classmethod
-    def __get_pydantic_core_schema__(cls, source_type: Any, handler: Any) -> core_schema.CoreSchema:
-        return core_schema.no_info_after_validator_function(
-            cls,
-            core_schema.int_schema(),
-            serialization=core_schema.plain_serializer_function_ser_schema(int),
-        )
-
-
 def _dump_crs(value: EpsgCode | str | None) -> Any:
     if value is None:
         return "unspecified"
@@ -78,17 +48,16 @@ def _dump_crs(value: EpsgCode | str | None) -> Any:
 
 def _load_crs(value: Any) -> EpsgCode | str | None:
     if value == "unspecified":
-        return None
-    elif isinstance(value, dict):
-        if "epsg_code" in value:
-            return EpsgCode(value["epsg_code"])
-        elif "ogc_wkt" in value:
-            return value["ogc_wkt"]
-        else:
-            raise ValueError("Invalid CRS dictionary format")
-    else:
+        return parse_crs(value)
+    if not isinstance(value, dict):
         raise ValueError("Invalid CRS format")
 
+    if set(value) == {"epsg_code"}:
+        return parse_crs(value["epsg_code"])
+    if set(value) == {"ogc_wkt"} and isinstance(value["ogc_wkt"], str):
+        return value["ogc_wkt"]
+    raise ValueError("Invalid CRS dictionary format")
+
 
 CoordinateReferenceSystem = Annotated[
     EpsgCode | str | None, pydantic.PlainValidator(_load_crs), pydantic.PlainSerializer(_dump_crs)
@@ -218,6 +187,20 @@ class BoundingBox:
         )
         return cls.from_extent(origin, extent, rotation)
 
+    @classmethod
+    def combine(cls, bboxes: list[BoundingBox]):
+        if not bboxes:
+            raise ValueError("bboxes list is empty")
+
+        return cls(
+            min_x=min(b.min_x for b in bboxes),
+            max_x=max(b.max_x for b in bboxes),
+            min_y=min(b.min_y for b in bboxes),
+            max_y=max(b.max_y for b in bboxes),
+            min_z=min(b.min_z for b in bboxes),
+            max_z=max(b.max_z for b in bboxes),
+        )
+
 
 @dataclass(frozen=True)
 class Rotation: