Metadata-Version: 2.4
Name: openspeleo_lib
Version: 0.0.18
Summary: "A library to read/write and convert OpenSpeleo files"
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.13
Classifier: Programming Language :: Python :: 3 :: Only
License-File: LICENSE
Requires-Dist: argparse>=1.4,<1.5
Requires-Dist: dicttoxml2>=2.1.0,<2.2
Requires-Dist: frozendict>=2.4,<2.5
Requires-Dist: geojson>=3.2.0,<3.4
Requires-Dist: openspeleo_core>=0.0.5,<0.1.0
Requires-Dist: orjson>=3.11.8,<3.12
Requires-Dist: pyIGRF14>=1.0.3,<1.1.0
Requires-Dist: pydantic-extra-types>=2.10,<2.12
Requires-Dist: pydantic>=2.13.1,<2.14
Requires-Dist: pyproj>=3.7.1,<3.8
Requires-Dist: xmltodict>=1.0,<1.1
Requires-Dist: deepdiff>=7.0,<10.0 ; extra == "test"
Requires-Dist: hypothesis>=6.128,<6.156 ; extra == "test"
Requires-Dist: pytest>=8.0.0,<10.0.0 ; extra == "test"
Requires-Dist: pytest-cov>=5.0.0,<8.0.0 ; extra == "test"
Requires-Dist: pytest-env>=1.1.3,<2.0.0 ; extra == "test"
Requires-Dist: pytest-runner>=6.0.0,<7.0.0 ; extra == "test"
Requires-Dist: pytest-ordering>=0.6,<1.0.0 ; extra == "test"
Requires-Dist: parameterized>=0.9.0,<0.10 ; extra == "test"
Project-URL: Bug Reports, https://github.com/OpenSpeleo/pytool_open_speleo/issues
Project-URL: Homepage, https://pypi.org/project/openspeleo-lib/
Project-URL: Source, https://github.com/OpenSpeleo/pytool_open_speleo
Provides-Extra: test

# OpenSpeleoLib

OpenSpeleoLib reads, writes, validates, and converts cave-survey data.

## GeoJSON conversion

Convert an Ariane TML survey with:

```console
openspeleo convert -i survey.tml -o survey.geojson -f geojson
```

### Coordinate safety guard

A connected shot can contain both survey measurements and an explicit geographic
endpoint. During GeoJSON conversion, explicit coordinates remain authoritative, but
OpenSpeleoLib calculates where the shot should end from its length, depth, azimuth,
unit, and magnetic declination. If the supplied and calculated endpoints differ by
more than 500 metres, conversion raises `InconsistentShotCoordinatesError`.

For example, synthetic Shot ID `4242` with supplied coordinates `(-70, 40)` and a
calculated endpoint near `(40, -70)` produces an error containing:

```text
[Shot ID=4242]: Explicit coordinates are inconsistent with shot measurements
```

The 500-metre threshold is a fixed catastrophic-data guardrail, not a survey-quality
or GPS-accuracy guarantee. Coordinates within the threshold are accepted without
certifying their accuracy. Root anchors and connected anchors whose parents cannot be
resolved cannot be compared and retain their existing behavior.

The library never swaps coordinates, guesses a correction, or emits a partially
converted GeoJSON document. The CLI calculates and validates the complete document
before opening the output path: a failed conversion does not create a new output and
does not replace an existing output passed with `--overwrite`. Correct the source
survey and run the conversion again.

