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.

