Metadata-Version: 2.5
Name: openspeleo_lib
Version: 0.0.19
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,<2
Requires-Dist: dicttoxml2>=2.1.0,<3
Requires-Dist: frozendict>=2.4,<3
Requires-Dist: geojson>=3.2.0,<4
Requires-Dist: openspeleo_core>=0.0.5,<1
Requires-Dist: orjson>=3.12,<4
Requires-Dist: pyIGRF14>=1.0.3,<2
Requires-Dist: pydantic-extra-types>=2.10,<3
Requires-Dist: pydantic>=2.13.1,<3
Requires-Dist: pyproj>=3.7.1,<4
Requires-Dist: xmltodict>=1.0,<2
Requires-Dist: deepdiff>=7.0,<10 ; extra == "test"
Requires-Dist: hypothesis>=6.128,<7 ; extra == "test"
Requires-Dist: pytest>=8.0.0,<10 ; extra == "test"
Requires-Dist: pytest-cov>=5.0.0,<8 ; extra == "test"
Requires-Dist: pytest-env>=1.1.3,<2 ; extra == "test"
Requires-Dist: pytest-runner>=6.0.0,<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_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
Import-Name: openspeleo_lib

# 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.

