Metadata-Version: 2.4
Name: less3d
Version: 0.3.1
Summary: GPU-accelerated 3D radiative transfer model for remote sensing
Keywords: remote-sensing,radiative-transfer,ray-tracing,GPU,OptiX,vegetation,LiDAR,LAI
Author: LESS Development Team
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Programming Language :: Python :: 3
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: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Project-URL: Homepage, https://cnb.cool/lessrt3d/LESSPRO
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: pillow>=9.0
Requires-Dist: viser>=0.2.0
Requires-Dist: matplotlib>=3.5
Provides-Extra: geo
Requires-Dist: rasterio; extra == "geo"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Description-Content-Type: text/markdown

# LESS 3.0

[![PyPI version](https://img.shields.io/pypi/v/less3d.svg)](https://pypi.org/project/less3d/)
[![Python](https://img.shields.io/pypi/pyversions/less3d.svg)](https://pypi.org/project/less3d/)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey)](https://pypi.org/project/less3d/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

**GPU + CPU accelerated 3D radiative transfer model for remote sensing simulation**

LESS 3.0 is a complete reimplementation of the [LESS model](http://lessrt.org) — a widely-used 3D radiative transfer framework in quantitative remote sensing research. Built from the ground up with NVIDIA OptiX ray tracing and a modern Python API, LESS 3.0 inherits the physical foundations of the original LESS while adding GPU acceleration, a redesigned scripting interface, and full physical coupling of energy balance, photosynthesis, and solar-induced chlorophyll fluorescence (SIF).

The original LESS remains available at [lessrt.org](http://lessrt.org). LESS 3.0 is the recommended path for new projects.

---

## Key Features

- **GPU + CPU dual backend** — Runs on any machine. With an NVIDIA GPU, simulation is typically 10–50× faster; without one, most features still work via the Embree CPU backend.
- **Clean Python API** — Designed for remote sensing scientists. Build a scene in 10 lines of code.
- **Digital twin architecture** — Build the scene once, simulate many times. Update illumination or surface properties without rebuilding geometry.
- **Multi-sensor support** — Optical imager (RGB / multispectral / hyperspectral), thermal infrared, LiDAR point cloud (ALS + TLS), and SIF fluorescence imager.
- **Full physical coupling** — 3D radiation field → energy balance → photosynthesis → SIF, all tightly coupled to the Monte Carlo ray tracing engine.
- **Interactive 3D viewer** — `scene.show()` opens a browser-based viewer to inspect the scene and preview simulation results.

---

## Installation

```bash
pip install less3d
```

Pre-built wheels for Windows and Linux are provided for Python 3.10–3.13. No compiler, CUDA toolkit, or additional runtime installation required.

| | CPU mode | GPU mode (recommended) |
|---|---|---|
| Processor | Any modern x86-64 | NVIDIA GPU, compute capability ≥ 5.0 |
| VRAM | — | 4 GB+ (8 GB+ recommended) |
| GPU driver | — | NVIDIA driver ≥ 535 |
| OS | Windows 10/11, Linux | Windows 10/11, Linux |
| Python | 3.10 – 3.13 | 3.10 – 3.13 |

> 3D energy balance solving currently requires a GPU. All other features (optical, thermal, LiDAR, SIF) run on CPU.

---

## Quick Start

```python
import less

# Create a 10 m × 10 m bare-soil scene
scene = less.Scene()
scene.size = 10.0
scene.terrain = less.Terrain(property=less.Lambertian(reflectance=0.3))
scene.illumination = less.DirectDiffuse(sun_zenith=30, sun_azimuth=150)
scene.build()

# Simulate a nadir RGB image
image = scene.simulate(less.OpticalImager(
    less.Orthographic(image_size=256),
    bands=[650, 550, 450],   # R, G, B (nm)
    quality=128,
))
image.save("output.png")
```

Thanks to the digital twin architecture, updating scene parameters does not require a rebuild:

```python
# Change sun angle and re-simulate — no rebuild needed
scene.illumination = less.DirectDiffuse(sun_zenith=60, sun_azimuth=90)
image2 = scene.simulate(sensor)
```

---

## Simulation Capabilities

| Domain | What you can simulate |
|---|---|
| **Optical** | RGB, multispectral, and hyperspectral images; BRF / BRDF angular sampling; NDVI and vegetation indices |
| **Thermal infrared** | Per-component temperature scenes (sunlit/shaded leaf, soil, trunk); thermal radiance images |
| **LiDAR** | Airborne laser scanning (ALS) and terrestrial laser scanning (TLS) point clouds |
| **Vegetation physiology** | 3D PAR radiation field, full energy balance, photosynthesis, solar-induced chlorophyll fluorescence (SIF) imaging |

---

## Forest Scene Example

```python
import less
import numpy as np

scene = less.Scene()
scene.size = 30.0
scene.terrain = less.Terrain(property=less.Lambertian(reflectance=0.12))
scene.illumination = less.DirectDiffuse(sun_zenith=35, sun_azimuth=225)

# Broadleaf tree with PROSPECT leaf optical properties
birch = less.Object("birch", mesh="birch.obj")
birch.set_property("leaves", less.Prospect(cab=40, car=8, cw=0.012, cm=0.009, N=1.5))

# Random planting positions
xy = np.random.rand(50, 2) * 30
positions = np.c_[xy, np.zeros(50)]
scene.add(birch, positions=positions)
scene.build()

# Multispectral image (green, red, NIR)
image = scene.simulate(less.OpticalImager(
    less.Orthographic(image_size=512),
    bands=[550, 670, 800],
    quality=256,
))
image.save("forest.tif")   # GeoTIFF preserves physical radiance values
```

---

## Built-in Examples and Viewer

```python
import less

less.examples.list()                  # list all built-in scenes
less.examples.run("autumn_forest")    # launch interactive viewer
less.examples.run("maize_field")
```

```python
scene.show()   # open 3D viewer in browser (Scene / Simulate / Products tabs)
```

---

## Validation

LESS 3.0 is cross-validated against the original LESS on reference scenes:

| Scene | Description | Max RRMSE |
|---|---|---|
| Val01 | Lambertian ground | 0.02% |
| Val02 | Box canopy | 0.22% |
| Val03 | Ellipsoid forest | 0.83% |
| Val04 | Forest + diffuse sky | 2.17% |
| Val05 | PROSPECT-D leaves | 0.24% |
| Val06 | fPAR vs sun zenith angle | 0.62% |
| Val07 | Thermal IR | 0.17% |

Full validation reports are regenerated on each release. See `tests/validation/`.

---

## Documentation and Tutorials

Full documentation with step-by-step tutorials: 

Topics covered: coordinate system · terrain and surface properties · illumination models · optical imaging · BRDF/BRF sampling · thermal infrared · LiDAR · energy balance · photosynthesis · SIF · visualization · scene serialization

---

## Citing

If you use LESS 3.0 in your research, please cite the original LESS paper:

> Qi, J., Xie, D., Yin, T., Yan, G., Gastellu-Etchegorry, J.P., Li, L., Zhang, W., Mu, X., Norford, L.K. (2019). LESS: LargE-Scale remote sensing data and image Simulation framework over heterogeneous 3D scenes. *Remote Sensing of Environment*, 221, 695–706.

---
