compass-lib 0.0.8__py3-none-any.whl

compass_lib/constants.py

@@ -0,0 +1,98 @@
+# -*- coding: utf-8 -*-
+"""Constants used throughout the compass_lib library.
+
+This module centralizes all constant values to ensure consistency
+and avoid magic numbers/strings scattered across the codebase.
+"""
+
+# -----------------------------------------------------------------------------
+# File Encodings
+# -----------------------------------------------------------------------------
+
+#: Default encoding for Compass files (Windows-1252 / CP1252)
+COMPASS_ENCODING = "cp1252"
+
+#: Encoding used for JSON files
+JSON_ENCODING = "utf-8"
+
+#: Encoding used when reading raw Compass files (ASCII with replacements)
+ASCII_ENCODING = "ascii"
+
+# -----------------------------------------------------------------------------
+# Unit Conversions
+# -----------------------------------------------------------------------------
+
+#: Conversion factor from feet to meters
+FEET_TO_METERS: float = 0.3048
+
+#: Conversion factor from meters to feet
+METERS_TO_FEET: float = 1.0 / FEET_TO_METERS
+
+# -----------------------------------------------------------------------------
+# Missing Data Indicators
+# -----------------------------------------------------------------------------
+
+#: Values >= this threshold indicate missing data for distances/measurements
+MISSING_VALUE_THRESHOLD: float = 990.0
+
+#: Values <= this threshold indicate missing data for angles
+MISSING_ANGLE_THRESHOLD: float = -900.0
+
+#: String representation of missing value in formatted output
+MISSING_VALUE_STRING: str = "-999.00"
+
+#: Null LRUD values used in PLT files (either 999.0 or 999.9 indicates missing)
+NULL_LRUD_VALUES: tuple[float, float] = (999.0, 999.9)
+
+# -----------------------------------------------------------------------------
+# Formatting Constants
+# -----------------------------------------------------------------------------
+
+#: Width of station name column in DAT files
+STATION_NAME_WIDTH: int = 13
+
+#: Width of numeric columns in DAT files
+NUMBER_WIDTH: int = 8
+
+#: Decimal precision for GeoJSON coordinates (WGS84)
+GEOJSON_COORDINATE_PRECISION: int = 7
+
+#: Decimal precision for elevation values in GeoJSON
+GEOJSON_ELEVATION_PRECISION: int = 2
+
+# -----------------------------------------------------------------------------
+# Shot Flag Characters
+# -----------------------------------------------------------------------------
+
+#: Mapping of shot flags to their character representations
+FLAG_CHARS: dict[str, str] = {
+    "exclude_distance": "L",
+    "exclude_from_plotting": "P",
+    "exclude_from_all_processing": "X",
+    "do_not_adjust": "C",
+}
+
+# -----------------------------------------------------------------------------
+# UTM Constants
+# -----------------------------------------------------------------------------
+
+#: Southern hemisphere UTM northing offset (10 million meters)
+#: Note: This constant represents the false northing added to southern hemisphere
+#: UTM coordinates. However, in Compass, hemisphere is determined by the ZONE SIGN
+#: (positive = north, negative = south), NOT by comparing northing to this threshold.
+#: This constant is kept for reference and potential future use.
+UTM_SOUTHERN_HEMISPHERE_OFFSET: float = 10_000_000.0
+
+# -----------------------------------------------------------------------------
+# Solver Constraints
+# -----------------------------------------------------------------------------
+
+#: Maximum relative change to a shot's tape length during traverse adjustment
+#: (0.05 = 5 %).  The solver will never stretch or shrink a shot by more than
+#: this fraction of the original survey measurement.
+SOLVER_MAX_LENGTH_CHANGE: float = 0.15
+
+#: Maximum relative change to a shot's compass heading during traverse
+#: adjustment (0.15 = 15 %).  The solver will never rotate a shot's bearing
+#: or inclination by more than this fraction of the original survey reading.
+SOLVER_MAX_HEADING_CHANGE: float = 0.15

compass_lib/enums.py

@@ -0,0 +1,394 @@
+# -*- coding: utf-8 -*-
+"""Enumerations for Compass file formats.
+
+This module contains all enumerations used in Compass survey data formats,
+including units for measurements, file types, and various classification types.
+"""
+
+from enum import StrEnum
+from math import radians
+from math import tan
+
+from compass_lib.constants import FEET_TO_METERS
+
+
+class FileFormat(StrEnum):
+    """File format types for conversion operations.
+
+    Attributes:
+        COMPASS: Native Compass binary/text format (.dat, .mak, .plt)
+        JSON: JSON serialization format
+        GEOJSON: GeoJSON geographic format
+    """
+
+    COMPASS = "compass"
+    JSON = "json"
+    GEOJSON = "geojson"
+
+
+class CompassFileType(StrEnum):
+    """Types of Compass files.
+
+    Attributes:
+        DAT: Survey data file containing shots
+        MAK: Project/make file linking DAT files
+        PLT: Plot file with processed survey data
+    """
+
+    DAT = "dat"
+    MAK = "mak"
+    PLT = "plt"
+
+    @property
+    def extension(self) -> str:
+        """Get the file extension for this type (with dot)."""
+        return {
+            CompassFileType.DAT: FileExtension.DAT.value,
+            CompassFileType.MAK: FileExtension.MAK.value,
+            CompassFileType.PLT: FileExtension.PLT.value,
+        }[self]
+
+    @classmethod
+    def from_extension(cls, ext: str) -> "CompassFileType | None":
+        """Get file type from extension.
+
+        Args:
+            ext: File extension (with or without dot, case-insensitive)
+
+        Returns:
+            CompassFileType or None if not recognized
+        """
+        ext_lower = ext.lower().lstrip(".")
+        mapping = {
+            "dat": cls.DAT,
+            "mak": cls.MAK,
+            "plt": cls.PLT,
+        }
+        return mapping.get(ext_lower)
+
+
+class FileExtension(StrEnum):
+    """File extensions for various file formats (with dot).
+
+    Attributes:
+        DAT: Compass survey data file extension
+        MAK: Compass project/make file extension
+        PLT: Compass plot file extension
+        JSON: JSON file extension
+        GEOJSON: GeoJSON file extension
+    """
+
+    DAT = ".dat"
+    MAK = ".mak"
+    PLT = ".plt"
+    JSON = ".json"
+    GEOJSON = ".geojson"
+
+
+class FormatIdentifier(StrEnum):
+    """Format identifiers used in JSON files.
+
+    Attributes:
+        COMPASS_DAT: Format identifier for DAT files in JSON
+        COMPASS_MAK: Format identifier for MAK/project files in JSON
+    """
+
+    COMPASS_DAT = "compass_dat"
+    COMPASS_MAK = "compass_mak"
+
+
+class AzimuthUnit(StrEnum):
+    """Unit for compass azimuth (bearing) measurements.
+
+    Attributes:
+        DEGREES: Standard degrees (0-360)
+        QUADS: Quadrant notation
+        GRADS: Gradians (400 per circle)
+    """
+
+    DEGREES = "D"
+    QUADS = "Q"
+    GRADS = "R"
+
+    @staticmethod
+    def convert(degrees: float | None, to_unit: "AzimuthUnit") -> float | None:
+        """Convert degrees to the target unit.
+
+        Args:
+            degrees: Value in degrees (or None)
+            to_unit: Target unit to convert to
+
+        Returns:
+            Converted value or None if input is None
+        """
+        if degrees is None:
+            return None
+        if to_unit == AzimuthUnit.GRADS:
+            return degrees * 400 / 360
+        return degrees
+
+
+class InclinationUnit(StrEnum):
+    """Unit for vertical angle (inclination) measurements.
+
+    Attributes:
+        DEGREES: Standard degrees (-90 to +90)
+        PERCENT_GRADE: Percentage gradient (tan(angle) * 100)
+        DEGREES_AND_MINUTES: Degrees with minutes notation
+        GRADS: Gradians
+        DEPTH_GAUGE: Delta depth (From_depth - To_depth) for underwater surveys.
+            Negative = descending (going deeper), positive = ascending.
+            Uses the same units as length measurements.
+    """
+
+    DEGREES = "D"
+    PERCENT_GRADE = "G"
+    DEGREES_AND_MINUTES = "M"
+    GRADS = "R"
+    DEPTH_GAUGE = "W"
+
+    @staticmethod
+    def convert(value: float | None, to_unit: "InclinationUnit") -> float | None:
+        """Convert degrees to the target unit.
+
+        Args:
+            value: Value in degrees (or None)
+            to_unit: Target unit to convert to
+
+        Returns:
+            Converted value or None if input is None
+        """
+        if value is None:
+            return None
+        if to_unit == InclinationUnit.PERCENT_GRADE:
+            return tan(radians(value)) * 100
+        if to_unit == InclinationUnit.GRADS:
+            return value * 200 / 180
+        return value
+
+
+class LengthUnit(StrEnum):
+    """Unit for distance measurements.
+
+    Attributes:
+        DECIMAL_FEET: Standard feet with decimals
+        FEET_AND_INCHES: Feet and inches notation
+        METERS: Metric meters
+    """
+
+    DECIMAL_FEET = "D"
+    FEET_AND_INCHES = "I"
+    METERS = "M"
+
+    @staticmethod
+    def convert(feet: float | None, to_unit: "LengthUnit") -> float | None:
+        """Convert feet to the target unit.
+
+        Args:
+            feet: Value in feet (or None)
+            to_unit: Target unit to convert to
+
+        Returns:
+            Converted value or None if input is None
+        """
+        if feet is None:
+            return None
+        if to_unit == LengthUnit.METERS:
+            return feet * FEET_TO_METERS
+        return feet
+
+
+class LrudAssociation(StrEnum):
+    """Indicates which station LRUD measurements are associated with.
+
+    Attributes:
+        FROM: LRUD measured at the FROM station
+        TO: LRUD measured at the TO station
+    """
+
+    FROM = "F"
+    TO = "T"
+
+
+class LrudItem(StrEnum):
+    """Individual LRUD dimension identifiers.
+
+    Attributes:
+        LEFT: Distance to left wall
+        RIGHT: Distance to right wall
+        UP: Distance to ceiling
+        DOWN: Distance to floor
+    """
+
+    LEFT = "L"
+    RIGHT = "R"
+    UP = "U"
+    DOWN = "D"
+
+
+class ShotItem(StrEnum):
+    """Components of a shot measurement for format ordering.
+
+    Attributes:
+        LENGTH: Distance between stations
+        FRONTSIGHT_AZIMUTH: Compass bearing forward
+        FRONTSIGHT_INCLINATION: Vertical angle forward
+        BACKSIGHT_AZIMUTH: Compass bearing backward
+        BACKSIGHT_INCLINATION: Vertical angle backward
+    """
+
+    LENGTH = "L"
+    FRONTSIGHT_AZIMUTH = "A"
+    FRONTSIGHT_INCLINATION = "D"
+    BACKSIGHT_AZIMUTH = "a"
+    BACKSIGHT_INCLINATION = "d"
+
+
+class Severity(StrEnum):
+    """Severity level for parse errors.
+
+    Attributes:
+        ERROR: Critical parsing error
+        WARNING: Non-fatal warning
+    """
+
+    ERROR = "error"
+    WARNING = "warning"
+
+
+class DrawOperation(StrEnum):
+    """Drawing operations for plot commands.
+
+    Attributes:
+        MOVE_TO: Move to location without drawing
+        LINE_TO: Draw line to location
+    """
+
+    MOVE_TO = "M"
+    LINE_TO = "D"
+
+
+class Datum(StrEnum):
+    """Geodetic datum values supported by Compass.
+
+    These are the standard datum values that can be used in MAK project files.
+    The enum values match the exact strings used in Compass MAK files.
+
+    Attributes:
+        ADINDAN: Adindan datum
+        ARC_1950: Arc 1950 datum
+        ARC_1960: Arc 1960 datum
+        AUSTRALIAN_1966: Australian 1966 datum
+        AUSTRALIAN_1984: Australian 1984 datum
+        CAMP_AREA_ASTRO: Camp Area Astro datum
+        CAPE: Cape datum
+        EUROPEAN_1950: European 1950 datum
+        EUROPEAN_1979: European 1979 datum
+        GEODETIC_1949: Geodetic 1949 datum
+        HONG_KONG_1963: Hong Kong 1963 datum
+        HU_TZU_SHAN: Hu Tzu Shan datum
+        INDIAN: Indian datum
+        NORTH_AMERICAN_1927: North American 1927 datum (NAD27)
+        NORTH_AMERICAN_1983: North American 1983 datum (NAD83)
+        OMAN: Oman datum
+        ORDNANCE_SURVEY_1936: Ordnance Survey 1936 datum
+        PULKOVO_1942: Pulkovo 1942 datum
+        SOUTH_AMERICAN_1956: South American 1956 datum
+        SOUTH_AMERICAN_1969: South American 1969 datum
+        TOKYO: Tokyo datum
+        WGS_1972: WGS 1972 datum
+        WGS_1984: WGS 1984 datum
+    """
+
+    ADINDAN = "Adindan"
+    ARC_1950 = "Arc 1950"
+    ARC_1960 = "Arc 1960"
+    AUSTRALIAN_1966 = "Australian 1966"
+    AUSTRALIAN_1984 = "Australian 1984"
+    CAMP_AREA_ASTRO = "Camp Area Astro"
+    CAPE = "Cape"
+    EUROPEAN_1950 = "European 1950"
+    EUROPEAN_1979 = "European 1979"
+    GEODETIC_1949 = "Geodetic 1949"
+    HONG_KONG_1963 = "Hong Kong 1963"
+    HU_TZU_SHAN = "Hu Tzu Shan"
+    INDIAN = "Indian"
+    NORTH_AMERICAN_1927 = "North American 1927"
+    NORTH_AMERICAN_1983 = "North American 1983"
+    OMAN = "Oman"
+    ORDNANCE_SURVEY_1936 = "Ordnance Survey 1936"
+    PULKOVO_1942 = "Pulkovo 1942"
+    SOUTH_AMERICAN_1956 = "South American 1956"
+    SOUTH_AMERICAN_1969 = "South American 1969"
+    TOKYO = "Tokyo"
+    WGS_1972 = "WGS 1972"
+    WGS_1984 = "WGS 1984"
+
+    def get_utm_epsg(self, zone: int, northern: bool) -> str:
+        """Get the EPSG code for a UTM zone with this datum.
+
+        Args:
+            zone: UTM zone number (1-60)
+            northern: True for northern hemisphere
+
+        Returns:
+            EPSG code string (e.g., "EPSG:26717" for NAD27 UTM Zone 17N)
+        """
+        zone = abs(zone)
+
+        match self:
+            case Datum.NORTH_AMERICAN_1927:
+                # NAD27 / UTM: EPSG:26701-26722 (zones 1-22 north)
+                return f"EPSG:{26700 + zone}"
+
+            case Datum.NORTH_AMERICAN_1983:
+                # NAD83 / UTM: EPSG:26901-26923 (zones 1-23 north)
+                return f"EPSG:{26900 + zone}"
+
+            case Datum.WGS_1972:
+                # WGS72 / UTM: EPSG:32201-32260 (north), EPSG:32301-32360 (south)
+                if northern:
+                    return f"EPSG:{32200 + zone}"
+                return f"EPSG:{32300 + zone}"
+
+            case Datum.WGS_1984:
+                # WGS84 / UTM: EPSG:32601-32660 (north), EPSG:32701-32760 (south)
+                if northern:
+                    return f"EPSG:{32600 + zone}"
+                return f"EPSG:{32700 + zone}"
+
+            case _:
+                raise NotImplementedError(f"This DATUM: `{self}` is not supported")
+
+    @classmethod
+    def normalize(cls, value: str | None) -> "Datum | None":
+        """Normalize and validate a datum string to a Datum enum value.
+
+        Performs case-insensitive matching with whitespace normalization.
+
+        Args:
+            value: The datum string to normalize (case-insensitive)
+
+        Returns:
+            The corresponding Datum enum value, or None if value is None
+
+        Raises:
+            ValueError: If the datum string is not recognized
+        """
+        if value is None:
+            return None
+
+        # Normalize: lowercase, strip whitespace, collapse multiple spaces
+        normalized = " ".join(value.strip().lower().split())
+
+        # Match against enum values (case-insensitive)
+        for datum in cls:
+            if datum.value.lower() == normalized:
+                return datum
+
+        raise ValueError(f"Unknown datum: {value!r}")
+
+    @classmethod
+    def from_string(cls, value: str | None) -> "Datum | None":
+        """Alias for normalize() for backwards compatibility."""
+        return cls.normalize(value)

compass_lib/errors.py

@@ -0,0 +1,86 @@
+# -*- coding: utf-8 -*-
+"""Error handling for Compass file parsing.
+
+This module provides error classes for tracking parsing errors with
+source location information for helpful error messages.
+"""
+
+from dataclasses import dataclass
+
+from compass_lib.enums import Severity
+
+
+@dataclass(frozen=True)
+class SourceLocation:
+    """Tracks the source location of text for error reporting.
+
+    Attributes:
+        source: The source file name or identifier
+        line: Line number (0-based)
+        column: Column number (0-based)
+        text: The text at this location
+    """
+
+    source: str
+    line: int
+    column: int
+    text: str
+
+    def __str__(self) -> str:
+        """Format as human-readable location string."""
+        return f"(in {self.source}, line {self.line + 1}, column {self.column + 1})"
+
+
+@dataclass(frozen=True)
+class CompassParseError:
+    """Represents a parsing error or warning with source location.
+
+    This is a data record for storing error information, not an exception.
+    Use CompassParseException for raising errors.
+
+    Attributes:
+        severity: ERROR or WARNING
+        message: Human-readable error message
+        location: Source location where error occurred (optional)
+    """
+
+    severity: Severity
+    message: str
+    location: SourceLocation | None = None
+
+    def __str__(self) -> str:
+        """Format as human-readable error string."""
+        base = f"{self.severity.value}: {self.message}"
+        if self.location:
+            base += f" {self.location}"
+            if self.location.text:
+                base += f"\n  {self.location.text}"
+        return base
+
+
+class CompassParseException(Exception):  # noqa: N818
+    """Exception raised for critical parsing errors.
+
+    Attributes:
+        message: Error message
+        location: Source location where error occurred
+    """
+
+    def __init__(self, message: str, location: SourceLocation | None = None):
+        self.message = message
+        self.location = location
+        super().__init__(str(self))
+
+    def __str__(self) -> str:
+        """Format as human-readable exception string."""
+        if self.location:
+            return f"{self.message} {self.location}"
+        return self.message
+
+    def to_error(self) -> CompassParseError:
+        """Convert exception to CompassParseError record."""
+        return CompassParseError(
+            severity=Severity.ERROR,
+            message=self.message,
+            location=self.location,
+        )

compass_lib/geo_utils.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import datetime
+
+import pyIGRF14 as pyIGRF
+from pydantic import BaseModel
+from pydantic_extra_types.coordinate import Latitude  # noqa: TC002
+from pydantic_extra_types.coordinate import Longitude  # noqa: TC002
+
+from compass_lib.constants import GEOJSON_COORDINATE_PRECISION
+
+
+class GeoLocation(BaseModel):
+    latitude: Latitude
+    longitude: Longitude
+
+    def as_tuple(self) -> tuple[float, float]:
+        """Return the latitude and longitude as a tuple.
+        # RFC 7946: (longitude, latitude)
+        """
+        return (
+            round(self.longitude, GEOJSON_COORDINATE_PRECISION),
+            round(self.latitude, GEOJSON_COORDINATE_PRECISION),
+        )
+
+
+def decimal_year(dt: datetime.datetime) -> float:
+    dt_start = datetime.datetime(  # noqa: DTZ001
+        year=dt.year, month=1, day=1, hour=0, minute=0, second=0
+    )
+    dt_end = datetime.datetime(  # noqa: DTZ001
+        year=dt.year + 1, month=1, day=1, hour=0, minute=0, second=0
+    )
+    return round(
+        dt.year + (dt - dt_start).total_seconds() / (dt_end - dt_start).total_seconds(),
+        ndigits=2,
+    )
+
+
+def get_declination(location: GeoLocation, dt: datetime.datetime) -> float:
+    declination, _, _, _, _, _, _ = pyIGRF.igrf_value(
+        location.latitude,
+        location.longitude,
+        alt=0.0,
+        year=decimal_year(dt),
+    )
+    return round(declination, 2)