compass-lib 0.0.2__py3-none-any.whl → 0.0.3__py3-none-any.whl

compass_lib/models.py

@@ -1,129 +1,251 @@
+# -*- coding: utf-8 -*-
+"""Core data models for Compass file formats.
+
+This module contains the base Pydantic models used across
+survey, project, and plot parsing.
+"""
+
 from __future__ import annotations
 
-import datetime  # noqa: TC003
-import json
-from pathlib import Path
 from typing import Annotated
-from typing import Any
 
 from pydantic import BaseModel
-from pydantic import ConfigDict
 from pydantic import Field
 from pydantic import field_validator
+from pyproj import CRS
+from pyproj import Transformer
+
+from compass_lib.enums import Datum
+
+
+class NEVLocation(BaseModel):
+    """3D location with Northing, Easting, and Vertical (elevation) components.
+
+    All values are stored with their associated unit. The unit for all three
+    components must be the same.
+
+    Attributes:
+        easting: East-West coordinate
+        northing: North-South coordinate
+        elevation: Vertical elevation
+        unit: The length unit for all coordinates ('f' for feet, 'm' for meters)
+    """
+
+    easting: float
+    northing: float
+    elevation: float
+    unit: Annotated[str, Field(default="f", pattern="^[fmFM]$")]
+
+    def __str__(self) -> str:
+        """Format as human-readable string."""
+        return (
+            f"NEVLocation(easting={self.easting}, "
+            f"northing={self.northing}, "
+            f"elevation={self.elevation}, "
+            f"unit={self.unit})"
+        )
+
+
+class UTMLocation(BaseModel):
+    """Represents a UTM-based coordinate for fixed stations."""
+
+    easting: Annotated[
+        float,
+        Field(
+            ge=166_000,
+            le=834_000,
+            description="Easting coordinate in meters (valid UTM range)",
+        ),
+    ]
+
+    northing: Annotated[
+        float,
+        Field(ge=0, le=10_000_000, description="Northing coordinate in meters"),
+    ]
+
+    elevation: Annotated[
+        float,
+        Field(
+            ge=-435.0,  # Dead Sea (Israel/Jordan/West Bank)
+            le=8850,  # Everest
+            description="Elevation in meters",
+        ),
+    ]
+
+    zone: Annotated[
+        int,
+        Field(
+            ge=-60,
+            le=60,
+            description="UTM zone number (1-60 north, -1 to -60 south, 0 not allowed)",
+        ),
+    ]
+
+    convergence: Annotated[
+        float,
+        Field(default=0.0, ge=-5.0, le=5.0, description="Convergence angle in degrees"),
+    ]
+
+    datum: Annotated[
+        Datum | None,
+        Field(
+            default=None,
+            description="Datum (e.g., Datum.NORTH_AMERICAN_1927, Datum.WGS_1984)",
+        ),
+    ]
+
+    # -----------------------------
+    # Validators
+    # -----------------------------
+
+    @field_validator("zone")
+    @classmethod
+    def validate_zone(cls, v: int) -> int:
+        """Validate UTM zone number.
+
+        Positive values (1-60) indicate northern hemisphere.
+        Negative values (-1 to -60) indicate southern hemisphere.
+        Zero is not allowed.
+
+        Args:
+            v: Zone number
+
+        Returns:
+            Validated zone number
+
+        Raises:
+            ValueError: If zone is 0 or abs(zone) > 60
+        """
+        if v == 0:
+            raise ValueError(
+                "UTM zone cannot be 0. Use 1-60 for north, -1 to -60 for south."
+            )
+        if abs(v) > 60:
+            raise ValueError(
+                f"UTM zone must be between -60 and 60 (excluding 0), got {v}"
+            )
+        return v
+
+    @field_validator("datum", mode="before")
+    @classmethod
+    def normalize_datum(cls, value: str | Datum | None) -> Datum | None:
+        """Validate and normalize datum string to Datum enum.
 
-from compass_lib.encoding import EnhancedJSONEncoder
-
-# from compass_lib.errors import DuplicateValueError
-
-
-class SurveyShot(BaseModel):
-    from_id: str
-    to_id: str
-
-    azimuth: Annotated[float, Field(ge=0, lt=360)]
+        Accepts either a string (which will be normalized) or a Datum enum value.
 
-    inclination: Annotated[float, Field(ge=-90, le=90)]
-    length: Annotated[float, Field(ge=0)]
+        Args:
+            value: Datum as string or Datum enum, or None
+
+        Returns:
+            Datum enum value or None
 
-    # Optional Values
-    comment: str | None = None
-    flags: Any | None = None
+        Raises:
+            ValueError: If datum string is not recognized
+        """
+        if value is None or isinstance(value, Datum):
+            return value
 
-    azimuth2: Annotated[float, Field(ge=0, lt=360)] | None = None
-    inclination2: Annotated[float, Field(ge=-90, le=90)] | None = None
+        # Normalize string to Datum enum
+        return Datum.normalize(value)
 
-    # LRUD
-    left: Annotated[float, Field(ge=0)] = 0.0
-    right: Annotated[float, Field(ge=0)] = 0.0
-    up: Annotated[float, Field(ge=0)] = 0.0
-    down: Annotated[float, Field(ge=0)] = 0.0
+    # -----------------------------
+    # Properties
+    # -----------------------------
 
-    model_config = ConfigDict(extra="forbid")
+    @property
+    def is_northern_hemisphere(self) -> bool:
+        """Check if this location is in the northern hemisphere.
 
-    @field_validator("left", "right", "up", "down", mode="before")
-    @classmethod
-    def validate_lrud(cls, value: float) -> float:
-        return value if value > 0 else 0.0
+        Returns:
+            True if northern hemisphere (zone > 0), False if southern (zone < 0)
+        """
+        return self.zone > 0
 
-    @field_validator("azimuth", "azimuth2", mode="before")
-    @classmethod
-    def validate_azimuth(cls, value: float) -> float:
-        return value if value > 0 else 0.0
+    @property
+    def zone_number(self) -> int:
+        """Get the absolute zone number (1-60).
 
-    @field_validator("inclination2", mode="before")
-    @classmethod
-    def validate_inclination2(cls, value: float) -> float:
-        return value if -90 <= value <= 90 else 0.0
+        Returns:
+            Absolute value of the zone number
+        """
+        return abs(self.zone)
 
-    # ======================== VALIDATOR UTILS ======================== #
+    # -----------------------------
+    # Methods
+    # -----------------------------
 
-    # @classmethod
-    # def validate_unique(cls, field: str, values: list) -> list:
-    #     vals2check = [getattr(val, field) for val in values]
-    #     dupl_vals = list(duplicates(vals2check))
-    #     if dupl_vals:
-    #         raise DuplicateValueError(
-    #             f"[{cls.__name__}] Duplicate value found for `{field}`: "
-    #             f"{dupl_vals}"
-    #         )
-    #     return values
+    def to_latlon(self) -> tuple[float, float]:
+        """
+        Convert this UTM location to GPS coordinates (latitude, longitude).
 
-    # @field_validator("to_id", mode="before")
-    # @classmethod
-    # def validate_unique_to_id(cls, value: str | None) -> str:
-    #     """Note: Validators are only ran with custom fed values.
-    #     Not autogenerated ones. Hence we need to register the name."""
+        NOTE: This method takes the decision to exclusively use DATUM WGS 1984 for uniformity
+        and ignore the datum from the MAK project file.
+        This allows for a consistent and predictable conversion of UTM coordinates to GPS coordinates.
+        And inter-operability with other software that uses WGS 1984 for GPS coordinates.
 
-    #     if value is None or value == "":
-    #         return cls.to_id.default_factory()
+        The hemisphere is determined by the sign of the zone:
+        - Positive zone (1-60): Northern hemisphere
+        - Negative zone (-1 to -60): Southern hemisphere
 
-    #     # 1. Verify the name is only composed of valid chars.
-    #     for char in value:
-    #         if char.upper() not in [
-    #             *UniqueNameGenerator.VOCAB,
-    #             *list("_-~:!?.'()[]{}@*&#%|$")
-    #         ]:
-    #             raise ValueError(f"The character `{char}` is not allowed as `name`.")
+        Args:
+            None
 
-    #     if len(value) > COMPASS_MAX_NAME_LENGTH:
-    #         raise ValueError(f"Name {value} is too long, maximum allowed: "
-    #                          f"{COMPASS_MAX_NAME_LENGTH}")
+        Returns:
+            (lat, lon) in decimal degrees
+        """  # noqa: E501
 
-    #     UniqueNameGenerator.register(value=value)
-    #     return value
+        WGS_1984_EPSG = 4326
+        geographic_crs = CRS.from_epsg(WGS_1984_EPSG)
 
+        # ---- Build UTM CRS ----
+        # Note: pyproj expects "WGS84" (no space) in proj4 strings, not "WGS 1984"
+        # Note: pyproj requires positive zone number and hemisphere specified separately
+        hemisphere = "+north" if self.is_northern_hemisphere else "+south"
+        utm_crs = CRS.from_proj4(
+            f"+proj=utm +zone={self.zone_number} {hemisphere} +datum=WGS84 +units=m +no_defs"  # noqa: E501
+        )
 
-class SurveySection(BaseModel):
-    name: str
-    comment: str
-    correction: list[float]
-    correction2: list[float]
-    survey_date: datetime.date | None = None
-    discovery_date: datetime.date | None = None
-    declination: float
-    format: str = "DDDDUDLRLADN"
-    shots: list[SurveyShot]
-    surveyors: str | None = None
+        transformer = Transformer.from_crs(
+            utm_crs,
+            geographic_crs,
+            always_xy=True,
+        )
 
-    model_config = ConfigDict(extra="forbid")
+        lon, lat = transformer.transform(self.easting, self.northing)
+        return lat, lon
 
 
-class Survey(BaseModel):
-    cave_name: str
-    description: str = ""
+class Location(BaseModel):
+    """3D plot location with northing, easting, and vertical components.
 
-    sections: list[SurveySection] = []
+    Used for plot file commands. Values are in feet.
 
-    model_config = ConfigDict(extra="forbid")
+    Attributes:
+        northing: North-South coordinate (feet)
+        easting: East-West coordinate (feet)
+        vertical: Vertical coordinate (feet)
+    """
 
-    def to_json(self, filepath: str | Path | None = None) -> str:
-        filepath = Path(filepath) if filepath else None
-        data = self.model_dump()
+    northing: float | None = None
+    easting: float | None = None
+    vertical: float | None = None
+
+    def __str__(self) -> str:
+        """Format as human-readable string."""
+        return (
+            f"Location(northing={self.northing}, "
+            f"easting={self.easting}, "
+            f"vertical={self.vertical})"
+        )
 
-        json_str = json.dumps(data, indent=4, sort_keys=True, cls=EnhancedJSONEncoder)
 
-        if filepath is not None:
-            with filepath.open(mode="w") as file:
-                file.write(json_str)
+class Bounds(BaseModel):
+    """Bounding box with lower and upper bounds.
+
+    Attributes:
+        lower: Lower bound location
+        upper: Upper bound location
+    """
 
-        return json_str
+    lower: Location = Field(default_factory=Location)
+    upper: Location = Field(default_factory=Location)

compass_lib/plot/__init__.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+"""Plot module for parsing Compass .PLT files."""
+
+from compass_lib.plot.models import BeginFeatureCommand
+from compass_lib.plot.models import BeginSectionCommand
+from compass_lib.plot.models import BeginSurveyCommand
+from compass_lib.plot.models import CaveBoundsCommand
+from compass_lib.plot.models import CompassPlotCommand
+from compass_lib.plot.models import DatumCommand
+from compass_lib.plot.models import DrawSurveyCommand
+from compass_lib.plot.models import FeatureCommand
+from compass_lib.plot.models import SurveyBoundsCommand
+from compass_lib.plot.models import UtmZoneCommand
+from compass_lib.plot.parser import CompassPlotParser
+
+__all__ = [
+    "BeginFeatureCommand",
+    "BeginSectionCommand",
+    "BeginSurveyCommand",
+    "CaveBoundsCommand",
+    "CompassPlotCommand",
+    "CompassPlotParser",
+    "DatumCommand",
+    "DrawSurveyCommand",
+    "FeatureCommand",
+    "SurveyBoundsCommand",
+    "UtmZoneCommand",
+]

compass_lib/plot/models.py

@@ -0,0 +1,265 @@
+# -*- coding: utf-8 -*-
+"""Plot data models for Compass .PLT files.
+
+This module contains Pydantic models for representing plot commands
+found in Compass .PLT plot files.
+"""
+
+import datetime
+from decimal import Decimal
+
+from pydantic import BaseModel
+from pydantic import Field
+from pydantic import field_validator
+
+from compass_lib.enums import Datum
+from compass_lib.enums import DrawOperation
+from compass_lib.models import Bounds
+from compass_lib.models import Location
+
+
+class CompassPlotCommand(BaseModel):
+    """Base class for all plot commands."""
+
+
+class BeginSurveyCommand(CompassPlotCommand):
+    """Begin survey command (N).
+
+    Marks the start of a new survey section.
+
+    Attributes:
+        survey_name: Survey identifier (max 12 chars)
+        date: Survey date
+        comment: Optional comment (max 80 chars)
+    """
+
+    survey_name: str
+    date: datetime.date | None = None
+    comment: str | None = None
+
+    def __str__(self) -> str:
+        """Format as PLT file syntax."""
+        result = f"N{self.survey_name[:12]}"
+        if self.date:
+            result += f"\tD {self.date.month} {self.date.day} {self.date.year}"
+        else:
+            result += "\tD 1 1 1"
+        if self.comment:
+            result += f"\tC{self.comment[:80]}"
+        return result
+
+
+class BeginSectionCommand(CompassPlotCommand):
+    """Begin section command (S).
+
+    Marks the start of a new section.
+
+    Attributes:
+        section_name: Section name (max 20 chars)
+    """
+
+    section_name: str
+
+    def __str__(self) -> str:
+        """Format as PLT file syntax."""
+        return f"S{self.section_name[:20]}"
+
+
+class BeginFeatureCommand(CompassPlotCommand):
+    """Begin feature command (F).
+
+    Marks the start of a feature definition with optional range.
+
+    Attributes:
+        feature_name: Feature name (max 12 chars)
+        min_value: Optional minimum value for range
+        max_value: Optional maximum value for range
+    """
+
+    feature_name: str
+    min_value: Decimal | None = None
+    max_value: Decimal | None = None
+
+    def __str__(self) -> str:
+        """Format as PLT file syntax."""
+        result = f"F{self.feature_name[:12]}"
+        if self.min_value is not None and self.max_value is not None:
+            result += f"\tR\t{float(self.min_value)}\t{float(self.max_value)}"
+        return result
+
+
+class DrawSurveyCommand(CompassPlotCommand):
+    """Draw survey command (M or D).
+
+    Represents a move-to or draw-to operation with station data.
+
+    Attributes:
+        operation: MOVE_TO (M) or LINE_TO (D)
+        location: 3D coordinates
+        station_name: Station identifier
+        left: Distance to left wall (feet, None if missing)
+        right: Distance to right wall (feet, None if missing)
+        up: Distance to ceiling (feet, None if missing)
+        down: Distance to floor (feet, None if missing)
+        distance_from_entrance: Distance from cave entrance (feet)
+    """
+
+    operation: DrawOperation
+    location: Location = Field(default_factory=Location)
+    station_name: str | None = None
+    left: float | None = None
+    right: float | None = None
+    up: float | None = None
+    down: float | None = None
+    distance_from_entrance: float = 0.0
+
+    def __str__(self) -> str:
+        """Format as PLT file syntax."""
+        cmd = "M" if self.operation == DrawOperation.MOVE_TO else "D"
+        result = f"{cmd}\t{self.location.northing}\t{self.location.easting}"
+        result += f"\t{self.location.vertical}"
+        if self.station_name:
+            result += f"\tS{self.station_name[:12]}"
+        result += "\tP"
+        result += f"\t{self.left if self.left is not None else -9.0}"
+        result += f"\t{self.up if self.up is not None else -9.0}"
+        result += f"\t{self.down if self.down is not None else -9.0}"
+        result += f"\t{self.right if self.right is not None else -9.0}"
+        result += f"\tI\t{self.distance_from_entrance}"
+        return result
+
+
+class FeatureCommand(CompassPlotCommand):
+    """Feature point command (L).
+
+    Represents a feature location with optional value.
+
+    Attributes:
+        location: 3D coordinates
+        station_name: Station identifier
+        left: Distance to left wall (feet, None if missing)
+        right: Distance to right wall (feet, None if missing)
+        up: Distance to ceiling (feet, None if missing)
+        down: Distance to floor (feet, None if missing)
+        value: Feature value
+    """
+
+    location: Location = Field(default_factory=Location)
+    station_name: str | None = None
+    left: float | None = None
+    right: float | None = None
+    up: float | None = None
+    down: float | None = None
+    value: Decimal | None = None
+
+    def __str__(self) -> str:
+        """Format as PLT file syntax."""
+        result = f"L\t{self.location.northing}\t{self.location.easting}"
+        result += f"\t{self.location.vertical}"
+        if self.station_name:
+            result += f"\tS{self.station_name[:12]}"
+        result += "\tP"
+        result += f"\t{self.left if self.left is not None else -9.0}"
+        result += f"\t{self.right if self.right is not None else -9.0}"
+        result += f"\t{self.up if self.up is not None else -9.0}"
+        result += f"\t{self.down if self.down is not None else -9.0}"
+        if self.value is not None:
+            result += f"\tV\t{self.value}"
+        return result
+
+
+class SurveyBoundsCommand(CompassPlotCommand):
+    """Survey bounds command (X).
+
+    Defines the bounding box for the current survey.
+
+    Attributes:
+        bounds: Lower and upper bound locations
+    """
+
+    bounds: Bounds = Field(default_factory=Bounds)
+
+    def __str__(self) -> str:
+        """Format as PLT file syntax."""
+        lb = self.bounds.lower
+        ub = self.bounds.upper
+        return (
+            f"X\t{lb.northing}\t{ub.northing}\t{lb.easting}"
+            f"\t{ub.easting}\t{lb.vertical}\t{ub.vertical}"
+        )
+
+
+class CaveBoundsCommand(CompassPlotCommand):
+    """Cave bounds command (Z).
+
+    Defines the overall bounding box for the cave.
+
+    Attributes:
+        bounds: Lower and upper bound locations
+        distance_to_farthest_station: Distance to farthest station from entrance
+    """
+
+    bounds: Bounds = Field(default_factory=Bounds)
+    distance_to_farthest_station: float | None = None
+
+    def __str__(self) -> str:
+        """Format as PLT file syntax."""
+        lb = self.bounds.lower
+        ub = self.bounds.upper
+        result = (
+            f"Z\t{lb.northing}\t{ub.northing}\t{lb.easting}"
+            f"\t{ub.easting}\t{lb.vertical}\t{ub.vertical}"
+        )
+        if self.distance_to_farthest_station is not None:
+            result += f"\tI\t{self.distance_to_farthest_station}"
+        return result
+
+
+class DatumCommand(CompassPlotCommand):
+    """Datum command (O).
+
+    Specifies the geodetic datum.
+
+    Attributes:
+        datum: Datum identifier
+    """
+
+    datum: Datum
+
+    @field_validator("datum", mode="before")
+    @classmethod
+    def normalize_datum(cls, value: str | Datum) -> Datum:
+        """Validate and normalize datum string to Datum enum.
+
+        Args:
+            value: Datum as string or Datum enum
+
+        Returns:
+            Datum enum value
+
+        Raises:
+            ValueError: If datum string is not recognized
+        """
+        if isinstance(value, Datum):
+            return value
+        return Datum.normalize(value)
+
+    def __str__(self) -> str:
+        """Format as PLT file syntax."""
+        return f"O{self.datum.value}"
+
+
+class UtmZoneCommand(CompassPlotCommand):
+    """UTM zone command (G).
+
+    Specifies the UTM zone.
+
+    Attributes:
+        utm_zone: UTM zone identifier (stored as string)
+    """
+
+    utm_zone: str
+
+    def __str__(self) -> str:
+        """Format as PLT file syntax."""
+        return f"G{self.utm_zone}"