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

compass_lib/models.py

@@ -0,0 +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
+
+from typing import Annotated
+
+from pydantic import BaseModel
+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.
+
+        Accepts either a string (which will be normalized) or a Datum enum value.
+
+        Args:
+            value: Datum as string or Datum enum, or None
+
+        Returns:
+            Datum enum value or None
+
+        Raises:
+            ValueError: If datum string is not recognized
+        """
+        if value is None or isinstance(value, Datum):
+            return value
+
+        # Normalize string to Datum enum
+        return Datum.normalize(value)
+
+    # -----------------------------
+    # Properties
+    # -----------------------------
+
+    @property
+    def is_northern_hemisphere(self) -> bool:
+        """Check if this location is in the northern hemisphere.
+
+        Returns:
+            True if northern hemisphere (zone > 0), False if southern (zone < 0)
+        """
+        return self.zone > 0
+
+    @property
+    def zone_number(self) -> int:
+        """Get the absolute zone number (1-60).
+
+        Returns:
+            Absolute value of the zone number
+        """
+        return abs(self.zone)
+
+    # -----------------------------
+    # Methods
+    # -----------------------------
+
+    def to_latlon(self) -> tuple[float, float]:
+        """
+        Convert this UTM location to GPS coordinates (latitude, longitude).
+
+        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.
+
+        The hemisphere is determined by the sign of the zone:
+        - Positive zone (1-60): Northern hemisphere
+        - Negative zone (-1 to -60): Southern hemisphere
+
+        Args:
+            None
+
+        Returns:
+            (lat, lon) in decimal degrees
+        """  # noqa: E501
+
+        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
+        )
+
+        transformer = Transformer.from_crs(
+            utm_crs,
+            geographic_crs,
+            always_xy=True,
+        )
+
+        lon, lat = transformer.transform(self.easting, self.northing)
+        return lat, lon
+
+
+class Location(BaseModel):
+    """3D plot location with northing, easting, and vertical components.
+
+    Used for plot file commands. Values are in feet.
+
+    Attributes:
+        northing: North-South coordinate (feet)
+        easting: East-West coordinate (feet)
+        vertical: Vertical coordinate (feet)
+    """
+
+    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})"
+        )
+
+
+class Bounds(BaseModel):
+    """Bounding box with lower and upper bounds.
+
+    Attributes:
+        lower: Lower bound location
+        upper: Upper bound location
+    """
+
+    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}"