Metadata-Version: 2.2
Name: lunadem
Version: 0.3.0
Summary: Lunar DEM generation, Kaguya scene analysis, metadata prediction, and rover-aware landing utilities.
Keywords: dem,shape-from-shading,photoclinometry,lunar,planetary,stac,landing,kaguya
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.
         
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
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
Requires-Python: >=3.9
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.16; 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.16; 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"
Description-Content-Type: text/markdown

# lunadem

`lunadem` is a lunar analysis toolkit for shape-from-shading DEM reconstruction, Kaguya scene metadata parsing, packaged metadata prediction, rover-aware landing safety scoring, and interactive 3D 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 Python import is now `lunadem`.

Backward compatibility:

- `import lunardem` still works, but it is deprecated.
- `lunardem` remains available as a compatibility CLI alias.

## What It Includes

- DEM generation from image input with `sfs`, `multiscale_sfs`, `ml`, and `hybrid`
- STAC + `camera.json` loaders for the bundled Kaguya dataset
- Deterministic metadata derivation helpers for geometry, timing, coverage, and coordinate conversion
- Packaged SFS explainers via CLI and Python
- Packaged metadata prediction APIs with ONNX-ready runtime hooks and baseline fallback metadata priors
- Rover preset library for Sojourner, Spirit, Opportunity, Curiosity, Perseverance, Pragyan, and SORA-Q
- Safe landing-site selection from an image or DEM
- Interactive Plotly visualizations for surfaces, landing sites, and Moon/footprint/camera/sun geometry
- `download --test` to fetch the official reference scene

## Quick Start

```python
from lunadem import (
    ReconstructionConfig,
    find_safe_landing_site,
    generate_dem,
    load_kaguya_scene,
    predict_scene_metadata,
    plot_scene_geometry_3d,
)

scene = load_kaguya_scene("TC1S2B0_01_07496N087E3020")

cfg = ReconstructionConfig(
    output={"output_dir": "output", "base_name": "moon_run"},
)
dem_result = generate_dem(scene.image_path, method="hybrid", config=cfg)

metadata_prediction = predict_scene_metadata(scene.image_path)
landing_site = find_safe_landing_site(scene.image_path, rover="pragyan", scene=scene)

figure = plot_scene_geometry_3d(scene, save_path="output/scene_geometry.html")

print(dem_result.exports)
print(metadata_prediction.targets)
print(landing_site.summary)
```

## CLI Examples

```bash
lunadem generate dataset/TC1S2B0_01_07496N087E3020/image/image.tif --method hybrid --output output
lunadem scene-summary TC1S2B0_01_07496N087E3020
lunadem sfs --maths
lunadem predict dataset/TC1S2B0_01_07496N087E3020/image/image.tif --kind all
lunadem landing-site dataset/TC1S2B0_01_07496N087E3020/image/image.tif --rover pragyan --scene TC1S2B0_01_07496N087E3020
lunadem download --test --output downloads
```

## Metadata Suite Accuracy

The bundled 18-scene Kaguya metadata suite currently ships baseline packaged statistics and ONNX-ready runtime hooks. The table below shows mean absolute error against the local dataset targets used by the packaged metrics file.

| Target | MAE |
| --- | ---: |
| `sun_azimuth_deg` | 1.5308 |
| `sun_elevation_deg` | 0.0022 |
| `off_nadir_deg` | 0.1052 |
| `view_azimuth_deg` | 0.0513 |
| `gsd_m` | 0.0808 |
| `centroid_lat_deg` | 3.0003 |
| `centroid_lon_deg` | 0.5092 |

Important note:

- The current dataset is small and scene-level labels are limited.
- These predictors estimate scene metadata, not ground-truth DEM quality or landing safety labels.
- Running `tools/train_metadata_cnns.py` in a healthy Python environment will replace the packaged baseline with exported ONNX models and refreshed metrics.

## Main Public APIs

- `generate_dem(...)`
- `analyze_dem(...)`
- `assess_landing(...)`
- `load_stac_item(...)`
- `load_camera_model(...)`
- `load_kaguya_scene(...)`
- `summarize_scene_metadata(...)`
- `predict_illumination(...)`
- `predict_view_geometry(...)`
- `predict_scene_location(...)`
- `predict_scene_metadata(...)`
- `get_rover_spec(...)`
- `find_safe_landing_site(...)`
- `plot_3d_surface_interactive(...)`
- `plot_landing_site_2d(...)`
- `plot_landing_site_3d(...)`
- `plot_scene_geometry_3d(...)`

## Reference Files

- [sfs.md](sfs.md)
- [lunar_data.md](lunar_data.md)
- [run.md](run.md)
- [update.md](update.md)

## License

MIT License. See [LICENSE](LICENSE).
