compass-lib 0.0.8__tar.gz → 0.0.9__tar.gz

compass_lib-0.0.9/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.5
+Name: compass_lib
+Version: 0.0.9
+Summary: Compass Parser Library.
+Keywords: cave,survey,karst
+Author-email: Jonathan Dekhtiar <jonathan@dekhtiar.com>
+Maintainer-email: Jonathan Dekhtiar <jonathan@dekhtiar.com>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Information Technology
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+License-File: LICENSE
+Requires-Dist: geojson>=3.2,<4
+Requires-Dist: numpy>=2.4.4,<3
+Requires-Dist: scipy>=1.17.1,<2
+Requires-Dist: orjson>=3.12,<4
+Requires-Dist: pydantic>=2.13,<3
+Requires-Dist: pydantic-extra-types>=2.11.1,<3
+Requires-Dist: pyIGRF14>=1.0.4,<2
+Requires-Dist: pyproj>=3.7.2,<4
+Requires-Dist: shapely>=2.1.2,<3
+Requires-Dist: utm>=0.8.1,<1
+Requires-Dist: cryptography>=50.0.0,<51 ; extra == "test"
+Requires-Dist: python-dotenv>=1.2.2,<2 ; extra == "test"
+Requires-Dist: deepdiff>=7.0,<10 ; extra == "test"
+Requires-Dist: pytest>=9.0.3,<10 ; extra == "test"
+Requires-Dist: pytest-cov>=7.1.0,<8 ; extra == "test"
+Requires-Dist: pytest-env>=1.6.0,<2 ; extra == "test"
+Requires-Dist: pytest-runner>=6.0.1,<7 ; extra == "test"
+Requires-Dist: pytest-ordering>=0.6,<1 ; extra == "test"
+Requires-Dist: parameterized>=0.9.0,<1 ; extra == "test"
+Project-URL: Bug Reports, https://github.com/OpenSpeleo/pytool_compass_lib/issues
+Project-URL: Homepage, https://pypi.org/project/compass-lib/
+Project-URL: Source, https://github.com/OpenSpeleo/pytool_compass_lib
+Provides-Extra: test
+Import-Name: compass_lib
+
+# Compass Python Lib
+
+## Conversion commands:
+
+```bash
+# Install in dev mod
+pip install -e ".[dev,test]"
+
+# Install latest stable version
+pip install compass_lib
+
+# run some commands
+compass convert --input_file=./tests/artifacts/fulford.dat  --output_file=fulford.json --format=json --overwrite
+compass convert --input_file=./tests/artifacts/random.dat  --output_file=random.json --format=json --overwrite
+```
+
+## GeoJSON section colors
+
+GeoJSON survey legs include `properties.color`, an opaque CSS `#rrggbb` color.
+Every shot in a DAT survey block receives the same generated section color.
+Sections sharing a station have different colors, including across MAK-linked
+DAT files. Names alone do not identify sections or station connections: the
+existing MAK station-scoping rules remain authoritative. Geometric crossings
+without a shared station do not create a color constraint.
+
+The palette lives in `compass_lib/constants.py` as `SURVEY_COLORS`: vivid red,
+orange, yellow, lime, green, mint, cyan, blue, purple, and hot pink. Both
+palette colors and generated overflow colors have HSV saturation of at least 80%
+and value of at least 90%, excluding black, white, gray, and muted shades.
+
+Assignment uses ordinary random choices in at most 16 iterative passes, without
+hashing, a fixed seed, or algorithm versioning. It stops on completion or no
+improvement. Remaining sections receive distinct vibrant colors using a finite
+fallback budget sized to the input, so reaching the pass limit does not leave
+touching sections with the same viewer fallback color. Colors can change when
+GeoJSON is regenerated and remain fixed in each stored artifact.
+
+See [GeoJSON section coloring](docs/geojson-section-colors.md) for pass
+semantics, fallback bounds, the color-space limit, export behavior, and test
+coverage.
+
+`CompassSurvey.color` is derived metadata assigned during coordinate
+computation; it is excluded from source JSON and DAT/MAK serialization.
+`SurveyLeg.color` carries it through coordinate propagation and adjustment.
+Passage polygons and clipped passage fragments inherit their leg's color.
+Station/anchor and misclosure styling retain their existing semantics.
+
+The `color` property is independent of `color_by_origin` and CLI `--no-colors`,
+which still control origin-based simplestyle `stroke`/`marker-color` styling.
+Clients can use `color` for shot rendering and fall back to the survey color for
+legacy data without it. Existing saved GeoJSON must be regenerated to gain these
+properties; no source files are rewritten. Palette changes also require
+regenerating stored GeoJSON; existing artifacts retain the colors recorded when
+they were exported.
+
+Portable regression coverage lives in `tests/test_section_colors.py`, including
+duplicate names, linked/scoped stations, crowded junctions, solver paths, round
+trips, CLI/API exports, vibrant colors, and safe budget exhaustion. Private
+fixtures remain additional coverage and are never required for these guarantees.
+

compass_lib-0.0.9/README.md

@@ -0,0 +1,59 @@
+# Compass Python Lib
+
+## Conversion commands:
+
+```bash
+# Install in dev mod
+pip install -e ".[dev,test]"
+
+# Install latest stable version
+pip install compass_lib
+
+# run some commands
+compass convert --input_file=./tests/artifacts/fulford.dat  --output_file=fulford.json --format=json --overwrite
+compass convert --input_file=./tests/artifacts/random.dat  --output_file=random.json --format=json --overwrite
+```
+
+## GeoJSON section colors
+
+GeoJSON survey legs include `properties.color`, an opaque CSS `#rrggbb` color.
+Every shot in a DAT survey block receives the same generated section color.
+Sections sharing a station have different colors, including across MAK-linked
+DAT files. Names alone do not identify sections or station connections: the
+existing MAK station-scoping rules remain authoritative. Geometric crossings
+without a shared station do not create a color constraint.
+
+The palette lives in `compass_lib/constants.py` as `SURVEY_COLORS`: vivid red,
+orange, yellow, lime, green, mint, cyan, blue, purple, and hot pink. Both
+palette colors and generated overflow colors have HSV saturation of at least 80%
+and value of at least 90%, excluding black, white, gray, and muted shades.
+
+Assignment uses ordinary random choices in at most 16 iterative passes, without
+hashing, a fixed seed, or algorithm versioning. It stops on completion or no
+improvement. Remaining sections receive distinct vibrant colors using a finite
+fallback budget sized to the input, so reaching the pass limit does not leave
+touching sections with the same viewer fallback color. Colors can change when
+GeoJSON is regenerated and remain fixed in each stored artifact.
+
+See [GeoJSON section coloring](docs/geojson-section-colors.md) for pass
+semantics, fallback bounds, the color-space limit, export behavior, and test
+coverage.
+
+`CompassSurvey.color` is derived metadata assigned during coordinate
+computation; it is excluded from source JSON and DAT/MAK serialization.
+`SurveyLeg.color` carries it through coordinate propagation and adjustment.
+Passage polygons and clipped passage fragments inherit their leg's color.
+Station/anchor and misclosure styling retain their existing semantics.
+
+The `color` property is independent of `color_by_origin` and CLI `--no-colors`,
+which still control origin-based simplestyle `stroke`/`marker-color` styling.
+Clients can use `color` for shot rendering and fall back to the survey color for
+legacy data without it. Existing saved GeoJSON must be regenerated to gain these
+properties; no source files are rewritten. Palette changes also require
+regenerating stored GeoJSON; existing artifacts retain the colors recorded when
+they were exported.
+
+Portable regression coverage lives in `tests/test_section_colors.py`, including
+duplicate names, linked/scoped stations, crowded junctions, solver paths, round
+trips, CLI/API exports, vibrant colors, and safe budget exhaustion. Private
+fixtures remain additional coverage and are never required for these guarantees.

{compass_lib-0.0.8 → compass_lib-0.0.9}/compass_lib/__init__.py

@@ -21,7 +21,7 @@ Usage:
     directives = read_mak_file(Path("project.MAK"))
 """
 
-__version__ = "0.0.8"
+__version__ = "0.0.9"
 
 # Constants
 from compass_lib.constants import COMPASS_ENCODING

{compass_lib-0.0.8 → compass_lib-0.0.9}/compass_lib/constants.py

@@ -15,6 +15,25 @@ COMPASS_ENCODING = "cp1252"
 #: Encoding used for JSON files
 JSON_ENCODING = "utf-8"
 
+#: Bright, saturated palette shared by section colors and origin debug styling.
+#: No black, white, gray, brown, or muted shades.
+SURVEY_COLORS: tuple[str, ...] = (
+    "#ff1744",  # vivid red
+    "#ff6d00",  # bright orange
+    "#ffea00",  # electric yellow
+    "#aaff00",  # lime
+    "#00e676",  # spring green
+    "#00ffb3",  # bright mint
+    "#00e5ff",  # cyan
+    "#2979ff",  # electric blue
+    "#d500f9",  # purple
+    "#ff00a8",  # hot pink
+)
+
+#: HSV bounds also enforced when crowded junctions require additional colors.
+SURVEY_COLOR_MIN_SATURATION: float = 0.8
+SURVEY_COLOR_MIN_VALUE: float = 0.9
+
 #: Encoding used when reading raw Compass files (ASCII with replacements)
 ASCII_ENCODING = "ascii"
 

{compass_lib-0.0.8 → compass_lib-0.0.9}/compass_lib/geojson.py

@@ -55,10 +55,12 @@ from compass_lib.constants import FEET_TO_METERS
 from compass_lib.constants import GEOJSON_COORDINATE_PRECISION
 from compass_lib.constants import JSON_ENCODING
 from compass_lib.constants import METERS_TO_FEET
+from compass_lib.constants import SURVEY_COLORS
 from compass_lib.enums import Datum
 from compass_lib.geo_utils import GeoLocation
 from compass_lib.geo_utils import get_declination
 from compass_lib.io import load_project
+from compass_lib.section_colors import assign_section_colors
 from compass_lib.solver.models import SurveyNetwork
 
 if TYPE_CHECKING:
@@ -139,6 +141,9 @@ class SurveyLeg:
     but measurement deltas do not).
     """
 
+    color: str | None = None
+    """Derived source-section color, independent of propagation origin."""
+
 
 @dataclass
 class MisclosureLeg:
@@ -185,18 +190,7 @@ class ComputedSurvey:
 #: stations can be visually distinguished by their propagation source.
 #: Viewers that support the simplestyle spec (geojson.io, GitHub, QGIS,
 #: Mapbox, …) will render these automatically.
-ORIGIN_COLORS: list[str] = [
-    "#1f77b4",  # blue
-    "#ff7f0e",  # orange
-    "#2ca02c",  # green
-    "#d62728",  # red
-    "#9467bd",  # purple
-    "#8c564b",  # brown
-    "#e377c2",  # pink
-    "#7f7f7f",  # grey
-    "#bcbd22",  # olive
-    "#17becf",  # cyan
-]
+ORIGIN_COLORS: list[str] = list(SURVEY_COLORS)
 
 
 # -----------------------------------------------------------------------------
@@ -757,6 +751,9 @@ def propagate_coordinates(
     Returns:
         ComputedSurvey with all computed stations and legs
     """
+    assign_section_colors(
+        project, ([edge[3] for edge in edges] for edges in adjacency.values())
+    )
     result = ComputedSurvey()
 
     # Set metadata
@@ -957,6 +954,7 @@ def propagate_coordinates(
                     inclination=shot.frontsight_inclination,
                     file=file_name,
                     survey=survey_name,
+                    color=survey.color,
                     left=shot.left,
                     right=shot.right,
                     up=shot.up,
@@ -997,6 +995,7 @@ def propagate_coordinates(
                         inclination=shot.frontsight_inclination,
                         file=file_name,
                         survey=survey_name,
+                        color=survey.color,
                         left=shot.left,
                         right=shot.right,
                         up=shot.up,
@@ -1027,6 +1026,7 @@ def propagate_coordinates(
                         inclination=shot.frontsight_inclination,
                         file=file_name,
                         survey=survey_name,
+                        color=survey.color,
                         left=shot.left,
                         right=shot.right,
                         up=shot.up,
@@ -1240,6 +1240,7 @@ def propagate_coordinates(
                             inclination=shot.frontsight_inclination,
                             file=file_name,
                             survey=survey_name,
+                            color=survey.color,
                             left=shot.left,
                             right=shot.right,
                             up=shot.up,
@@ -1259,6 +1260,7 @@ def propagate_coordinates(
                             inclination=shot.frontsight_inclination,
                             file=file_name,
                             survey=survey_name,
+                            color=survey.color,
                             left=shot.left,
                             right=shot.right,
                             up=shot.up,
@@ -1415,6 +1417,7 @@ def propagate_coordinates(
                     inclination=shot.frontsight_inclination,
                     file=file_name,
                     survey=survey_name,
+                    color=survey.color,
                     left=shot.left,
                     right=shot.right,
                     up=shot.up,
@@ -1676,6 +1679,7 @@ def leg_to_feature(
             "id": str(uuid.uuid5(uuid.NAMESPACE_OID, leg.to_station.name)),
             "depth": abs(depth_ft),  # Compass depth is < 0
             "name": leg.survey,
+            **({"color": leg.color} if leg.color is not None else {}),
         },
     )
 
@@ -1886,6 +1890,7 @@ def passage_to_feature(
         ),
         properties={
             "type": "passage",
+            **({"color": leg.color} if leg.color is not None else {}),
             "from": leg.from_station.name,
             "to": leg.to_station.name,
             "left_ft": leg.left,

compass_lib-0.0.9/compass_lib/section_colors.py

@@ -0,0 +1,104 @@
+"""Bounded coloring passes respecting the computed station topology."""
+
+from __future__ import annotations
+
+import logging
+import random
+from itertools import islice
+from typing import TYPE_CHECKING
+
+from compass_lib.constants import SURVEY_COLOR_MIN_SATURATION
+from compass_lib.constants import SURVEY_COLOR_MIN_VALUE
+from compass_lib.constants import SURVEY_COLORS
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+    from collections.abc import Iterator
+
+    from compass_lib.project.models import CompassMakFile
+    from compass_lib.survey.models import CompassSurvey
+
+logger = logging.getLogger(__name__)
+
+MAX_COLORING_PASSES = 16
+RGB_COLOR_COUNT = 1 << 24
+
+
+def _additional_colors() -> Iterator[str]:
+    """Visit distinct RGB values, accepting only bright, saturated colors."""
+    for index in range(RGB_COLOR_COUNT):
+        # The odd multiplier visits every RGB value once without a growing set.
+        rgb = (0x68BDEB + index * 0x9E3779) % RGB_COLOR_COUNT
+        channels = ((rgb >> 16) & 255, (rgb >> 8) & 255, rgb & 255)
+        peak = max(channels)
+        if peak / 255 < SURVEY_COLOR_MIN_VALUE:
+            continue
+        saturation = (peak - min(channels)) / peak
+        if saturation >= SURVEY_COLOR_MIN_SATURATION:
+            yield f"#{rgb:06x}"
+
+
+def assign_section_colors(
+    project: CompassMakFile,
+    station_sections: Iterable[Iterable[CompassSurvey]],
+) -> None:
+    """Try random palette assignments in bounded passes, then use vivid extras.
+
+    Each DAT survey block is a separate section, even when names repeat. The
+    existing station graph supplies connectivity, including MAK station scopes.
+    Only conflict-free candidates coloring more sections improve the assignment;
+    no-progress and pass-budget exhaustion lead to a bounded fallback.
+    """
+    sections = [
+        section
+        for directive in project.file_directives
+        if directive.data is not None
+        for section in directive.data.surveys
+    ]
+    section_indices = {id(section): index for index, section in enumerate(sections)}
+    neighbors: list[set[int]] = [set() for _ in sections]
+    for owners in station_sections:
+        indices = {section_indices[id(section)] for section in owners}
+        for index in indices:
+            neighbors[index].update(indices - {index})
+
+    order = sorted(range(len(sections)), key=lambda index: -len(neighbors[index]))
+    colors: dict[int, str] = {}
+    for _ in range(MAX_COLORING_PASSES):
+        candidate: dict[int, str] = {}
+        for index in order:
+            forbidden = {
+                candidate[other] for other in neighbors[index] if other in candidate
+            }
+            available = [color for color in SURVEY_COLORS if color not in forbidden]
+            if available:
+                candidate[index] = random.choice(available)
+        if len(candidate) <= len(colors):
+            break
+        colors = candidate
+        if len(colors) == len(sections):
+            break
+
+    # Finish unresolved sections with distinct bright colors. The generator is
+    # unique, so at most len(used) candidates can collide with assigned colors.
+    # This input-sized bound completes the fallback without an arbitrary cap
+    # leaving touching sections to render the same survey fallback color.
+    used = set(colors.values())
+    candidate_budget = len(sections) - len(colors) + len(used)
+    extras = iter(islice(_additional_colors(), candidate_budget))
+    for index in order:
+        if index in colors:
+            continue
+        color = next((value for value in extras if value not in used), None)
+        if color is None:
+            logger.warning(
+                "Vibrant RGB color space exhausted; %s sections use viewer fallback",
+                len(sections) - len(colors),
+            )
+            break
+        colors[index] = color
+        used.add(color)
+
+    for index, section in enumerate(sections):
+        # Omit unassigned colors instead of exporting a conflicting color.
+        section.color = colors.get(index)

{compass_lib-0.0.8 → compass_lib-0.0.9}/compass_lib/survey/models.py

@@ -100,6 +100,8 @@ class CompassSurvey(BaseModel):
 
     header: CompassSurveyHeader
     shots: list[CompassShot] = Field(default_factory=list)
+    # Derived project-wide display metadata, never written into source files.
+    color: str | None = Field(default=None, exclude=True)
 
 
 class CompassDatFile(BaseModel):

compass_lib-0.0.8/PKG-INFO

@@ -1,63 +0,0 @@
-Metadata-Version: 2.5
-Name: compass_lib
-Version: 0.0.8
-Summary: Compass Parser Library.
-Keywords: cave,survey,karst
-Author-email: Jonathan Dekhtiar <jonathan@dekhtiar.com>
-Maintainer-email: Jonathan Dekhtiar <jonathan@dekhtiar.com>
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Intended Audience :: Science/Research
-Classifier: Intended Audience :: Information Technology
-Classifier: Topic :: Software Development :: Build Tools
-Classifier: Topic :: Scientific/Engineering
-Classifier: Topic :: Software Development :: Libraries
-Classifier: Topic :: Utilities
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-License-File: LICENSE
-Requires-Dist: geojson>=3.2,<4
-Requires-Dist: numpy>=2.4.4,<3
-Requires-Dist: scipy>=1.17.1,<2
-Requires-Dist: orjson>=3.12,<4
-Requires-Dist: pydantic>=2.13,<3
-Requires-Dist: pydantic-extra-types>=2.11.1,<3
-Requires-Dist: pyIGRF14>=1.0.4,<2
-Requires-Dist: pyproj>=3.7.2,<4
-Requires-Dist: shapely>=2.1.2,<3
-Requires-Dist: utm>=0.8.1,<1
-Requires-Dist: cryptography>=50.0.0,<51 ; extra == "test"
-Requires-Dist: python-dotenv>=1.2.2,<2 ; extra == "test"
-Requires-Dist: deepdiff>=7.0,<10 ; extra == "test"
-Requires-Dist: pytest>=9.0.3,<10 ; extra == "test"
-Requires-Dist: pytest-cov>=7.1.0,<8 ; extra == "test"
-Requires-Dist: pytest-env>=1.6.0,<2 ; extra == "test"
-Requires-Dist: pytest-runner>=6.0.1,<7 ; extra == "test"
-Requires-Dist: pytest-ordering>=0.6,<1 ; extra == "test"
-Requires-Dist: parameterized>=0.9.0,<1 ; extra == "test"
-Project-URL: Bug Reports, https://github.com/OpenSpeleo/pytool_compass_lib/issues
-Project-URL: Homepage, https://pypi.org/project/compass-lib/
-Project-URL: Source, https://github.com/OpenSpeleo/pytool_compass_lib
-Provides-Extra: test
-Import-Name: compass_lib
-
-# Compass Python Lib
-
-## Conversion commands:
-
-```bash
-# Install in dev mod
-pip install -e ".[dev,test]"
-
-# Install latest stable version
-pip install compass_lib
-
-# run some commands
-compass convert --input_file=./tests/artifacts/fulford.dat  --output_file=fulford.json --format=json --overwrite
-compass convert --input_file=./tests/artifacts/random.dat  --output_file=random.json --format=json --overwrite
-```
-

compass_lib-0.0.8/README.md

@@ -1,15 +0,0 @@
-# Compass Python Lib
-
-## Conversion commands:
-
-```bash
-# Install in dev mod
-pip install -e ".[dev,test]"
-
-# Install latest stable version
-pip install compass_lib
-
-# run some commands
-compass convert --input_file=./tests/artifacts/fulford.dat  --output_file=fulford.json --format=json --overwrite
-compass convert --input_file=./tests/artifacts/random.dat  --output_file=random.json --format=json --overwrite
-```