Metadata-Version: 2.3
Name: lithovox-exports
Version: 0.1.0
Summary: Export LithoVox corridor voxel models (model.nc) to D-Stability, D-Geo Flow, XSLOPE, DXF, GLB, 3D Tiles and LAZ
Keywords: geotechnics,voxel model,d-stability,d-geo flow,xslope,dxf,subsoil
Author: LithoVox
Author-email: LithoVox <lithovox@pm.me>
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Requires-Dist: d-geolib>=2.9.1
Requires-Dist: ezdxf>=1.4
Requires-Dist: h5py>=3.16.0
Requires-Dist: laspy[lazrs]>=2.7.0
Requires-Dist: numpy>=2.5.3
Requires-Dist: openpyxl>=3.1
Requires-Dist: pyproj>=3.8.0
Requires-Dist: scipy>=1.18
Requires-Dist: shapely>=2.1.2
Requires-Python: >=3.12
Project-URL: Homepage, https://www.lithovox.com
Description-Content-Type: text/markdown

# lithovox-exports

Turn the voxel models LithoVox delivers (`model.nc`) into input for your own
software: D-Stability, D-Geo Flow, XSLOPE and DXF cross-sections, and GLB,
3D Tiles and LAZ for the whole model.

This is the same code the LithoVox viewer exports with, so a file made here
is identical to one downloaded from the viewer.

## Installation

```
pip install lithovox-exports
```

or, in a uv project, `uv add lithovox-exports`. Python 3.12 or newer.

## Quick start

```python
from lithovox_exports import Model

model = Model("model.nc")
print(model.name, model.length, model.soils)

# A cross-section at chainage 250 m, as a D-Stability model
section = model.cross_section(250)
section.to_dstability("km0.250.stix")
```

## Cross-sections

A cross-section lies square to the model's chainage line, at the model
column nearest the chainage you ask for. Its soil boundaries are traced from
the voxels and smoothed into polygons that share their points exactly with
their neighbours and have no holes (as D-Stability requires).

```python
section = model.cross_section(250)               # smoothed boundaries
blocky = model.cross_section(250, smoothing=0)   # the voxels' staircase

section.to_dstability("km0.250.stix")   # D-Stability
section.to_dgeoflow("km0.250.flox")     # D-Geo Flow
section.to_xslope("km0.250.zip")        # XSLOPE: .xlsx + its colours, zipped
section.to_xslope("km0.250.xlsx")       # or the .xlsx with *_styles.json beside it
section.to_dxf("km0.250.dxf")           # DXF (e.g. GEO5, CAD)
```

Every 50 m along the whole model:

```python
for chainage in range(0, int(model.length) + 1, 50):
    section = model.cross_section(chainage)
    section.to_dstability(f"{section.label}.stix")   # km0.000.stix, km0.050.stix, ...
```

### Your own soil parameters (D-Stability, XSLOPE)

By default the soils have names only. Pass a D-Stability file with your soil
library to use its soils and parameters. A model soil gets the library soil
with the same code or name (ignoring case, spaces, `_` and `-`), or the one you
name in `mapping` (model soil name → library soil code; `None` for none):

```python
section.to_dstability(
    "km0.250.stix",
    soils="my_soils.stix",
    mapping={"Klei siltig": "K_siltig", "Veen": "V_mineraalarm"},
)
section.to_xslope("km0.250.zip", soils="my_soils.stix", mapping={"Veen": "V_mineraalarm"})
```

XSLOPE materials take the unit weights and, for Mohr-Coulomb soils, c and phi.

Water levels, loads, meshes and calculation settings are always left to you.

## The whole model

```python
model.to_glb("model.glb")      # 3D mesh, e.g. Blender or a 3D viewer
model.to_tiles("tiles.zip")    # OGC 3D Tiles (3d/tileset.json), e.g. Cesium, ArcGIS
model.to_laz("model.laz")      # point cloud, e.g. QGIS, ArcGIS
```

Each takes `voxel_width` and `voxel_height` (m; default 1.0 and 0.2): the model
is shown with voxels of about that size, each getting the soil most of its
model voxels have. Larger voxels make smaller files.

## Coordinates

- Cross-sections: x is the offset from the chainage line (m, positive
  inwards), z is the height (m NAP). `section.start` and `section.end` give
  the RD coordinates of the cross-section's ends.
- The whole model: RD New + NAP (EPSG:7415). The LAZ file has a point per
  voxel, classified as 64 + the soil's code (`model.soils[code]`).

## More

`section.polygons` holds the soil polygons themselves (`soil` is an index
into `model.soils`, `points` the outline as (x, z)), and `model.metadata` all
of the model's metadata, if you want to make your own export.

Questions or a format you need: lithovox@pm.me, https://www.lithovox.com.
