Metadata-Version: 2.4
Name: lunadem
Version: 0.4.1
Summary: Lunar DEM generation, Kaguya scene analysis, metadata prediction, and rover-aware landing utilities.
Author: Kartavya Mahesh Suryawanshi
Author-email: kartavya suryawanshi <kartavya.xenon@gmail.com>
License: MIT License
        
        Copyright (c) 2026 LunarDEM Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/Kartavya728/Generation-of-High-resolution-Digital-Elevation-Model-from-Lunar-Images-using-Photoclinometry
Project-URL: Repository, https://github.com/Kartavya728/Generation-of-High-resolution-Digital-Elevation-Model-from-Lunar-Images-using-Photoclinometry
Project-URL: Documentation, https://github.com/Kartavya728/Generation-of-High-resolution-Digital-Elevation-Model-from-Lunar-Images-using-Photoclinometry/tree/main/docs
Project-URL: Issues, https://github.com/Kartavya728/Generation-of-High-resolution-Digital-Elevation-Model-from-Lunar-Images-using-Photoclinometry/issues
Keywords: dem,shape-from-shading,photoclinometry,lunar,planetary,stac,landing,kaguya
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.1,>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: rasterio>=1.3
Requires-Dist: imageio>=2.34
Requires-Dist: imageio-ffmpeg>=0.5
Requires-Dist: matplotlib>=3.8
Requires-Dist: plotly>=5.22
Requires-Dist: pygame>=2.6
Requires-Dist: pydantic>=2.8
Requires-Dist: requests>=2.32
Requires-Dist: typer>=0.12
Requires-Dist: PyYAML>=6.0
Requires-Dist: onnxruntime>=1.18
Provides-Extra: ml
Requires-Dist: torch>=2.2; extra == "ml"
Requires-Dist: onnx>=1.19; extra == "ml"
Requires-Dist: ml-dtypes>=0.5; extra == "ml"
Requires-Dist: scikit-learn>=1.5; extra == "ml"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.8; extra == "viz"
Requires-Dist: plotly>=5.22; extra == "viz"
Provides-Extra: pds
Requires-Dist: pvl>=1.3; extra == "pds"
Provides-Extra: native
Requires-Dist: pybind11>=2.12; extra == "native"
Requires-Dist: scikit-build-core>=0.10; extra == "native"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=8.2; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6.2; extra == "dev"
Requires-Dist: wheel>=0.45; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Requires-Dist: onnx>=1.19; extra == "dev"
Requires-Dist: ml-dtypes>=0.5; extra == "dev"
Requires-Dist: scikit-learn>=1.5; extra == "dev"
Requires-Dist: pybind11>=2.12; extra == "dev"
Requires-Dist: scikit-build-core>=0.10; extra == "dev"
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

# lunadem

`lunadem` is a lunar terrain analysis library for DEM reconstruction, Kaguya scene metadata understanding, offline metadata prediction, rover-aware landing analysis, and dual-backend visualization.

PyPI: https://pypi.org/project/lunadem/

## Install

```bash
pip install lunadem
```

Optional extras:

```bash
pip install "lunadem[ml]"
pip install "lunadem[viz]"
pip install "lunadem[pds]"
pip install "lunadem[dev]"
```

Canonical import and CLI name is `lunadem`.

Compatibility note:

- `import lunardem` still works as a deprecated compatibility shim.
- `lunardem` still exists as a compatibility CLI alias.

## Main Capabilities

- DEM generation from images with `sfs`, `multiscale_sfs`, `ml`, and `hybrid` methods.
- Memory-safe SFS and hybrid reconstruction for large Kaguya scenes through bounded working resolution.
- Kaguya scene loading from STAC `item.json` plus `camera.json`.
- Dozens of deterministic metadata helpers for centroid, bbox, footprint, coverage, transforms, angles, camera path, and sun geometry.
- Packaged shape-from-shading theory helpers through CLI and Python.
- Packaged offline ONNX metadata models for illumination, view geometry, and scene context prediction.
- Rover presets for `sojourner`, `spirit`, `opportunity`, `curiosity`, `perseverance`, `pragyan`, and `soraq`.
- Rover-aware landing-site search using slope, roughness, hazard, clearance, and optional sun geometry.
- Matplotlib plotting for visible local rendering and Plotly for hoverable 3D output and HTML export.
- Moon-globe, terrain-surface, landing-site, and scene-geometry visualization.
- `download --test` support for the official reference scene.

## Bundled Resources

- Kaguya dataset access helpers in `lunadem.datasets`.
- SFS theory files in `lunadem/assets/docs/`.
- Real packaged ONNX model weights in `lunadem/assets/models/`.
- Packaged metrics file describing the current model suite.
- Rover preset catalog in `lunadem.landing.rovers`.
- Optional C++ acceleration hook under `lunadem._native` when built with native support.
- Detailed generated references in [run.md](run.md), [lunar_data.md](lunar_data.md), [sfs.md](sfs.md), [documentation.txt](documentation.txt), and [update.md](update.md).

## Quick Start

```python
from lunadem import (
    ReconstructionConfig,
    build_scene_summary,
    find_safe_landing_site,
    generate_dem,
    get_rover_spec,
    load_kaguya_scene,
    plot_landing_site_2d,
    plot_moon_surface_3d,
    plot_scene_geometry_3d,
    predict_scene_metadata,
)

scene = load_kaguya_scene("TC1S2B0_01_07496N087E3020")
summary = build_scene_summary(scene)

config = ReconstructionConfig(
    output={"output_dir": "output", "base_name": "moon_demo"},
)

dem_result = generate_dem(scene.image_path, method="hybrid", config=config)
prediction = predict_scene_metadata(scene.image_path, max_patches=8)
landing = find_safe_landing_site(scene.image_path, rover=get_rover_spec("pragyan"), scene=scene)

plot_scene_geometry_3d(
    scene,
    backend="both",
    show=False,
    save_path="output/scene_geometry.png",
    html_path="output/scene_geometry.html",
)
plot_moon_surface_3d(
    scene,
    backend="both",
    show=False,
    save_path="output/moon_surface.png",
    html_path="output/moon_surface.html",
)
plot_landing_site_2d(
    scene.image_path,
    landing,
    backend="both",
    show=False,
    save_path="output/landing_2d.png",
    html_path="output/landing_2d.html",
)

print(summary["centroid"])
print(prediction.targets)
print(landing.summary)
```

## CLI Overview

```bash
lunadem download --test --output downloads
lunadem scene-summary TC1S2B0_01_07496N087E3020
lunadem sfs --maths
lunadem predict dataset/TC1S2B0_01_07496N087E3020/image/image.tif --kind all
lunadem generate dataset/TC1S2B0_01_07496N087E3020/image/image.tif --method hybrid --output output
lunadem plot-surface dataset/TC1S2B0_01_07496N087E3020/image/image.tif --backend both --show --reconstruct
lunadem plot-scene TC1S2B0_01_07496N087E3020 --backend both --show --output output/scene_geometry.png --output-html output/scene_geometry.html
lunadem landing-site dataset/TC1S2B0_01_07496N087E3020/image/image.tif --scene TC1S2B0_01_07496N087E3020 --rover pragyan --backend both --show --output-2d output/landing_2d.png --output-3d output/landing_3d.png --output-2d-html output/landing_2d.html --output-3d-html output/landing_3d.html
```

## Plotting Backends

- Use Matplotlib when you want visible local plots or static PNG output.
- Use Plotly when you want hoverable 3D interaction or HTML export.
- Use `backend="both"` for the scene, Moon, and landing plot helpers when you want both at once.
- Python plotting APIs default to `show=False` so scripts stay safe.
- CLI plot commands default to `--show`, which makes desktop visualization available immediately.

## Public API Scope

The current public package surface exposes more than 40 callable functions and helper APIs across:

- DEM generation and terrain analysis.
- Scene loading and metadata derivation.
- Coordinate and unit conversion.
- Metadata model inspection and prediction.
- Rover preset lookup and landing-site selection.
- Matplotlib and Plotly visualization helpers.
- File export helpers for GeoTIFF, OBJ, PLY, and manifest generation.

Full callable catalog and examples are in [run.md](run.md).

The long-form generated manual with parameter breakdowns and code templates is in [documentation.txt](documentation.txt).

## Packaged Model Metrics

The current wheel bundles real ONNX artifacts for the metadata suite. The metrics below come from grouped scene-level evaluation on the local 18-scene Kaguya dataset.

| Model | Target | MAE |
| --- | --- | ---: |
| `illumination_cnn` | `sun_azimuth_deg` | 1.608062 |
| `illumination_cnn` | `sun_elevation_deg` | 0.002216 |
| `view_geometry_cnn` | `off_nadir_deg` | 0.105210 |
| `view_geometry_cnn` | `view_azimuth_deg` | 0.051268 |
| `scene_context_cnn` | `gsd_m` | 0.082854 |
| `scene_context_cnn` | `centroid_lat_deg` | 3.149079 |
| `scene_context_cnn` | `centroid_lon_deg` | 0.509205 |

Important note:

- These models estimate scene metadata from imagery.
- They are not trained as ground-truth DEM regressors.
- They are not trained as supervised landing-safety classifiers.
- The local dataset is still small, so accuracy should be treated as a practical estimate rather than a broad benchmark.

## Reference Files

- [run.md](run.md): generated command and Python function catalog with examples.
- [documentation.txt](documentation.txt): long-form generated manual exceeding 2000 lines.
- [lunar_data.md](lunar_data.md): explanation of the Kaguya STAC and camera metadata concepts used by the library.
- [sfs.md](sfs.md): shape-from-shading concepts, mathematics, terms, and assumptions.
- [update.md](update.md): GitHub and PyPI release workflow.

## Development Notes

- The package version is sourced from `lunadem/__init__.py`.
- Native acceleration is optional and every accelerated path has a Python fallback.
- The ONNX model artifacts are bundled inside the package, so end users do not need to download weights separately.
- The official reference scene remains `TC1S2B0_01_07496N087E3020`.

## License

MIT License. See [LICENSE](LICENSE).
