lunadem 1.0.1

Lightweight lunar terrain analysis: DEM generation, terrain analysis, and rover landing safety.

lunadem 🌕

Lightweight Lunar Terrain Analysis Toolkit

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

pip install lunadem

For GeoTIFF export support:

pip install "lunadem[geo]"

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

---

Quick Start

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

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:

@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

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

---

License

MIT © Kartavya Suryawanshi

See LICENSE for the full text.