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

compass_lib/constants.py

@@ -0,0 +1,84 @@
+# -*- 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

compass_lib/enums.py

@@ -1,112 +1,356 @@
+# -*- 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 Enum
+from math import radians
+from math import tan
+
+from compass_lib.constants import FEET_TO_METERS
+
+
+class FileFormat(str, Enum):
+    """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(str, Enum):
+    """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]
 
-class CustomEnum(Enum):
     @classmethod
-    def reverse(cls, name):
-        return cls._value2member_map_[name]
+    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)
+
 
-# ============================== Azimuth ============================== #
+class FileExtension(str, Enum):
+    """File extensions for various file formats (with dot).
 
-# export const azimuthUnits: { [string]: DisplayAzimuthUnit } = {
-#   D: 'degrees',
-#   Q: 'quads',
-#   G: 'gradians',
-# }
+    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(str, Enum):
+    """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(str, Enum):
+    """Unit for compass azimuth (bearing) measurements.
+
+    Attributes:
+        DEGREES: Standard degrees (0-360)
+        QUADS: Quadrant notation
+        GRADS: Gradians (400 per circle)
+    """
 
-class AzimuthUnits(CustomEnum):
     DEGREES = "D"
     QUADS = "Q"
-    GRADIANS = "G"
+    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
 
-# ============================== Inclination Unit ============================== #
 
-# export const inclinationUnits: { [string]: DisplayInclinationUnit } = {
-#   D: 'degrees',
-#   G: 'percentGrade',
-#   M: 'degreesAndMinutes',
-#   R: 'gradians',
-#   W: 'depthGauge',
-# }
+class InclinationUnit(str, Enum):
+    """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: Depth gauge reading
+    """
 
-class InclinationUnits(CustomEnum):
     DEGREES = "D"
     PERCENT_GRADE = "G"
     DEGREES_AND_MINUTES = "M"
-    GRADIANS = "R"
+    GRADS = "R"
     DEPTH_GAUGE = "W"
 
-# ============================== Length Unit ============================== #
+    @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
 
 
-# export const lengthUnits: { [string]: DisplayLengthUnit } = {
-#   D: 'decimalFeet',
-#   I: 'feetAndInches',
-#   M: 'meters',
-# }
+class LengthUnit(str, Enum):
+    """Unit for distance measurements.
+
+    Attributes:
+        DECIMAL_FEET: Standard feet with decimals
+        FEET_AND_INCHES: Feet and inches notation
+        METERS: Metric meters
+    """
 
-class LengthUnits(CustomEnum):
     DECIMAL_FEET = "D"
     FEET_AND_INCHES = "I"
     METERS = "M"
 
-# ============================== LRUD ============================== #
+    @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(str, Enum):
+    """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(str, Enum):
+    """Individual LRUD dimension identifiers.
 
-# export const lrudItems: { [string]: LrudItem } = {
-#   L: 'left',
-#   R: 'right',
-#   U: 'up',
-#   D: 'down',
-# }
+    Attributes:
+        LEFT: Distance to left wall
+        RIGHT: Distance to right wall
+        UP: Distance to ceiling
+        DOWN: Distance to floor
+    """
 
-class LRUD(CustomEnum):
     LEFT = "L"
     RIGHT = "R"
     UP = "U"
     DOWN = "D"
 
-# ============================== ShotItem ============================== #
 
-# export const shotMeasurementItems: { [string]: ShotMeasurementItem } = {
-#   L: 'length',
-#   A: 'frontsightAzimuth',
-#   D: 'frontsightInclination',
-#   a: 'backsightAzimuth',
-#   d: 'backsightInclination',
-# }
+class ShotItem(str, Enum):
+    """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
+    """
 
-class ShotItem(CustomEnum):
     LENGTH = "L"
     FRONTSIGHT_AZIMUTH = "A"
     FRONTSIGHT_INCLINATION = "D"
     BACKSIGHT_AZIMUTH = "a"
     BACKSIGHT_INCLINATION = "d"
 
-# ============================== StationSide ============================== #
 
-# export const stationSides: { [string]: StationSide } = {
-#   F: 'from',
-#   T: 'to',
-# }
+class Severity(str, Enum):
+    """Severity level for parse errors.
 
-class StationSide(CustomEnum):
-    FROM = "F"
-    TO = "T"
+    Attributes:
+        ERROR: Critical parsing error
+        WARNING: Non-fatal warning
+    """
 
+    ERROR = "error"
+    WARNING = "warning"
 
-# ============================== ShotFlag ============================== #
 
-class ShotFlag(CustomEnum):
-    EXCLUDE_PLOTING = "P"
-    EXCLUDE_CLOSURE = "C"
-    EXCLUDE_LENGTH = "L"
-    TOTAL_EXCLUSION = "X"
-    SPLAY = "S"
+class DrawOperation(str, Enum):
+    """Drawing operations for plot commands.
 
-    __start_token__ = r"#\|"
-    __end_token__ = r"#"
+    Attributes:
+        MOVE_TO: Move to location without drawing
+        LINE_TO: Draw line to location
+    """
 
+    MOVE_TO = "M"
+    LINE_TO = "D"
 
 
-if __name__ == "__main__":
-    print(StationSide.FROM.value)
-    print(StationSide.reverse("F"))
+class Datum(str, Enum):
+    """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"
+
+    @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)