Metadata-Version: 2.4
Name: lunadem
Version: 1.0.1
Summary: Lightweight lunar terrain analysis: DEM generation, terrain analysis, and rover landing safety.
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,landing,terrain-analysis,moon,chandrayaan,isro
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
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: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: imageio>=2.34
Requires-Dist: matplotlib>=3.8
Provides-Extra: geo
Requires-Dist: rasterio>=1.3; extra == "geo"
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"
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"
Dynamic: license-file

# lunadem 🌕

**Lightweight Lunar Terrain Analysis Toolkit**

[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-1.0.1-brightgreen.svg)](pyproject.toml)

> *From image to landing site in one import.*

`lunadem` transforms raw lunar images into Digital Elevation Models, terrain analysis, and rover-aware landing safety assessments — all with a four-line install and a single `import lunadem as ld`.

No Kaguya. No ONNX. No internet. No configuration required.

---

## Installation

```bash
pip install lunadem
```

For GeoTIFF export support:

```bash
pip install "lunadem[geo]"
```

**Runtime dependencies:** `numpy`, `scipy`, `imageio`, `matplotlib` — nothing else.

---

## Quick Start

```python
import lunadem as ld

# 1. Load a packaged sample image (no internet required)
moon = ld.load_sample(1)

# 2. Convert format
moon = ld.transform(moon, to="png")

# 3. Describe the image
print(ld.describe(moon))

# 4. Estimate scene metadata
metadata = ld.load_metadata(moon)

# 5. Generate a Digital Elevation Model
dem = ld.generate_dem(moon, method="hybrid")

# 6. Visualise the DEM (2D heatmap + 3D surface)
ld.plot(dem)

# 7. Run terrain analysis
analysis = ld.analyze(dem)
print(analysis)

# 8. Evaluate landing safety for Pragyan rover
score = ld.safety_score(rover="pragyan", dem=dem, metadata=metadata)
print(score)

# 9. Find and mark the best landing site
marked = ld.mark_landing_spot(dem, rover="pragyan")

# 10. Visualise landing site
ld.plot(marked)

# 11. Export to PNG
ld.export(marked, "landing_result.png")
```

---

## Features

| Feature | Description |
|---|---|
| **5 Sample Images** | Packaged synthetic lunar terrain — no download needed |
| **4 DEM Methods** | SFS, Multi-scale SFS, ML prior, Hybrid blend |
| **Terrain Analysis** | Slope, roughness, curvature, histograms |
| **Landing Safety** | Rover-aware scoring with real physical constraints |
| **9 Rover Presets** | Pragyan, Perseverance, Curiosity, Spirit, and more |
| **Auto-plotting** | One function, adapts to object type automatically |
| **Export** | PNG, JPEG, TIFF; GeoTIFF with optional rasterio |
| **Zero config** | All defaults are physically calibrated |

---

## Architecture

```
lunadem/
│
├── __init__.py          ← 14 public names. Nothing else.
│
├── models/              ← 6 public @dataclass types
│   ├── MoonImage
│   ├── Metadata
│   ├── DEM
│   ├── TerrainAnalysis
│   ├── SafetyResult
│   └── LandingSite
│
├── functions/           ← 1 public function per file
│   ├── load.py          load_sample(), load()
│   ├── transform.py     transform()
│   ├── describe.py      describe()
│   ├── metadata.py      load_metadata()
│   ├── dem.py           generate_dem()
│   ├── analysis.py      analyze()
│   ├── landing.py       safety_score(), mark_landing_spot(), available_rovers()
│   ├── plotting.py      plot()
│   └── export.py        save(), export()
│
├── internal/            ← All implementation detail (never import directly)
│   ├── algorithms/      SFS, multi-scale, ML, hybrid
│   ├── terrain/         slope, roughness, site-finding
│   ├── image_processing/ loader, transforms
│   ├── visualization/   matplotlib rendering
│   ├── utils/           arrays, lighting
│   └── rovers.py        rover preset registry
│
└── sample_data/         ← 5 × 256×256 PNG lunar terrain images
    moon1.png … moon5.png
```

---

## API Reference

### Loading

| Function | Description |
|---|---|
| `ld.load_sample(n)` | Load packaged sample image (n = 1–5) |
| `ld.load(path)` | Load external image from disk |

### Image Operations

| Function | Description |
|---|---|
| `ld.transform(image, ...)` | Format, resize, rotate, flip, normalise |
| `ld.describe(image)` | Width, height, statistics, illumination |
| `ld.save(image, path)` | Save image to PNG/JPEG/TIFF |

### Metadata

| Function | Description |
|---|---|
| `ld.load_metadata(image)` | Estimate sun angles, resolution, location |

### DEM Generation

| Function | Description |
|---|---|
| `ld.generate_dem(image, method=)` | `"sfs"` / `"multiscale"` / `"ml"` / `"hybrid"` |

### Terrain Analysis

| Function | Description |
|---|---|
| `ld.analyze(dem)` | Slope, roughness, curvature, histograms |

### Landing Safety

| Function | Description |
|---|---|
| `ld.safety_score(rover=, dem=, metadata=)` | Overall + per-metric safety scores |
| `ld.mark_landing_spot(dem, rover=)` | Find + annotate the optimal landing site |
| `ld.available_rovers()` | List all rover preset names |

### Output

| Function | Description |
|---|---|
| `ld.plot(obj)` | Auto-visualise any lunadem object |
| `ld.export(obj, path)` | Export any lunadem object to file |

---

## Rover Presets

| Key | Display Name | Mission | Agency |
|---|---|---|---|
| `pragyan` | Pragyan *(default)* | Chandrayaan-3 | ISRO |
| `pragyan_prototype` | Pragyan Prototype | Chandrayaan-2 | ISRO |
| `future_indian_rover` | Future Indian Rover | ISRO Future Mission | ISRO |
| `viper` | VIPER | Volatiles Investigating Polar Exploration | NASA |
| `yutu` | Yutu | Chang'e 3 | CNSA |
| `yutu2` | Yutu-2 | Chang'e 4 | CNSA |
| `lunokhod1` | Lunokhod 1 | Luna 17 | Soviet space program |
| `lunokhod2` | Lunokhod 2 | Luna 21 | Soviet space program |
| `perseverance` | Perseverance | Mars 2020 | NASA |
| `curiosity` | Curiosity | Mars Science Laboratory | NASA |
| `spirit` | Spirit | Mars Exploration Rover A | NASA |
| `opportunity` | Opportunity | Mars Exploration Rover B | NASA |
| `sojourner` | Sojourner | Mars Pathfinder | NASA |

```python
ld.available_rovers()
# ['curiosity', 'future_indian_rover', 'lunokhod1', 'lunokhod2', 'opportunity',
#  'perseverance', 'pragyan', 'pragyan_prototype', 'sojourner', 'spirit',
#  'viper', 'yutu', 'yutu2']
```

---

## Sample Images

Five synthetic-but-physically-realistic 256×256 lunar terrain images are included:

| Sample | Scene |
|---|---|
| `ld.load_sample(1)` | Classic cratered terrain — medium craters on rolling plain |
| `ld.load_sample(2)` | Highland ridges — diagonal ridgeline with sparse craters |
| `ld.load_sample(3)` | Flat maria — low-relief dark plain with long shadows |
| `ld.load_sample(4)` | Multi-crater overlap — complex overlapping impact history |
| `ld.load_sample(5)` | Heavily shadowed terrain — dramatic low-sun-angle scene |

Generated using Lambertian reflectance + directional lighting — no real mission data required.

---

## Return Types

All functions return typed dataclasses:

```python
@dataclass
class MoonImage:
    pixels: np.ndarray   # float32, shape (H, W), values in [0, 1]
    format: str          # "png" | "jpg" | "tiff" | "grayscale"
    source: str          # file path or "sample:<n>"
    width: int
    height: int

@dataclass
class DEM:
    elevation: np.ndarray   # float32 metres, shape (H, W)
    method: str             # "sfs" | "multiscale" | "ml" | "hybrid"
    pixel_scale_m: float

@dataclass
class SafetyResult:
    overall_score: float    # 0–100
    recommended: bool
    slope_score: float
    roughness_score: float
    hazard_score: float
    safe_fraction: float
    rover: str
```

---

## Roadmap

- [ ] `ld.compare(dem_a, dem_b)` — visual DEM difference map
- [ ] `ld.export(dem, "surface.obj")` — 3-D mesh export
- [ ] Custom rover specs via `ld.mark_landing_spot(dem, rover={"length_m": 1.2, ...})`
- [ ] Real LROC/Chandrayaan image loader (optional plugin)
- [ ] Interactive Plotly rendering (optional `lunadem[interactive]`)

---

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/my-feature`)
3. Follow the existing code style (Black + ruff)
4. Add tests for new functionality
5. Submit a pull request

```bash
# Development setup
pip install -e ".[dev]"
pytest tests/ -v
```

---

## License

MIT © Kartavya Suryawanshi

See [LICENSE](LICENSE) for the full text.
