Metadata-Version: 2.4
Name: less3d
Version: 3.0.0
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 :: 5 - Production/Stable
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
Requires-Dist: rasterio>=1.3
Requires-Dist: scipy>=1.10
Requires-Dist: trimesh>=4.0
Provides-Extra: service
Requires-Dist: aiohttp<4,>=3.9; extra == "service"
Provides-Extra: lidar
Requires-Dist: laspy>=2.0; extra == "lidar"
Requires-Dist: cloth-simulation-filter>=1.1; extra == "lidar"
Provides-Extra: atmosphere
Requires-Dist: Py6S>=1.9; extra == "atmosphere"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Description-Content-Type: text/markdown

# LESS

**3D Radiative Transfer Model**

Version 3.0.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)

LESS is a GPU- and CPU-accelerated 3D radiative transfer model for quantitative remote sensing. It combines a Python interface with NVIDIA OptiX, Vulkan Ray Query, and Intel Embree native backends for optical, thermal, solar-induced fluorescence (SIF), vegetation photosynthesis, energy-balance, and LiDAR simulations.

LESS 3.x is a completely new native implementation of the original [LESS model](http://lessrt.org). The original LESS 2.x implementation remains available at [lessrt.org](http://lessrt.org).

## Highlights

- **Remote-sensing-oriented Python API** — describe a scene using terrain, objects, optical properties, illumination, sensors, and products.
- **Three native backends** — OptiX for NVIDIA GPUs, Vulkan Ray Query for supported GPUs, and Embree for CPU execution to accelerate simulations for various platforms .
- **Persistent scenes** — geometry is prepared automatically on the first simulation and reused when only illumination, spectra, or properties change.
- **Mesh and turbid vegetation** — simulate explicit geometry, volume canopies, or mixed scenes.
- **Imaging and biophysical products** — optical and thermal imagery, BRF, radiation fields, irradiance maps, SIF, photosynthesis, energy balance, and LiDAR.
- **Sensor effects** — pushbroom geometry, spectral response, PSF/MTF, detector noise, ADC quantisation, and geolocation.
- **Interactive inspection** — use `scene.show()` to explore scenes and products in a browser-based viewer.

## Installation

```bash
pip install less3d
```

Prebuilt wheels are provided for Windows and Linux with Python 3.10–3.13. A compiler and CUDA toolkit are not required. Compatible graphics drivers are still required for GPU backends.

| Backend          | Typical hardware         | Recommended memory | Suggested use                          |
| ---------------- | ------------------------ | ------------------:| -------------------------------------- |
| Embree           | x86-64 CPU               | System RAM         | CPU simulation and comparison          |
| Vulkan Ray Query | Vulkan 1.2 Ray Query GPU | 4 GB+ VRAM         | Supported non-CUDA GPU workflows       |
| OptiX + CUDA     | Compatible NVIDIA GPU    | 8 GB+ VRAM         | High-throughput Monte Carlo simulation |

Check whether a feature can run with a particular backend on the current computer:

```python
import less

less.can_use("optical_imaging", backend="optix")
less.can_use("irradiance_map", backend="embree")
```

After creating a scene, `scene.can_use("feature")` performs the same check using that scene's selected backend.

## Available in 3.0.0

The following workflows are available with OptiX, Vulkan, and Embree when the selected backend meets its hardware and driver requirements:

| Domain                | Capabilities                                                               |
| --------------------- | -------------------------------------------------------------------------- |
| Optical               | Mesh and turbid-medium imaging, BRF, radiation fields, and irradiance maps |
| Scene layout          | Dynamic instances, repetitive scenes, and terrain-following placement      |
| Thermal               | Thermal imaging and per-primitive temperatures                             |
| Vegetation physiology | SIF imaging and processes, photosynthesis, and energy balance              |
| LiDAR                 | Point clouds, full waveforms, and turbid-volume returns                    |



Repetitive scenes require flat, statistically homogeneous terrain and cannot be combined with `terrain_following=True`. Moving a `TurbidBoundary` instance requires `scene.rebuild()`; ordinary property and illumination changes do not.

## 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.Illumination(
    source=less.Sun(zenith=30, azimuth=150),
    atmosphere=less.NoAtmosphere(),
)

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

Change the illumination and simulate again; the prepared geometry is reused automatically:

```python
scene.illumination = less.Illumination(
    source=less.Sun(zenith=60, azimuth=90),
    atmosphere=less.NoAtmosphere(),
)
image2 = scene.simulate(sensor)
```

## Forest 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.Illumination(
    source=less.Sun(zenith=35, azimuth=225),
    atmosphere=less.NoAtmosphere(),
)

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),
)

xy = np.random.default_rng(42).random((50, 2)) * 30
scene.add(birch, positions=np.c_[xy, np.zeros(50)])

image = scene.simulate(less.OpticalImager(
    less.Orthographic(image_size=512),
    bands=[550, 670, 800],
    quality=256,
))
image.save("forest.tif")
```

GeoTIFF output preserves the physical values of the simulated product.

## Examples and viewer

```python
import less

less.examples.list()
less.examples.run("autumn_forest")
less.examples.run("maize_field")

scene.show()
```

## Validation

LESS is cross-validated against LESS 2.x on reference scenes:

| Scene | Description                    | Maximum RRMSE |
| ----- | ------------------------------ | -------------:|
| Val01 | Lambertian ground              | 0.02%         |
| Val02 | Box canopy                     | 0.22%         |
| Val03 | Ellipsoid forest               | 0.83%         |
| Val04 | Forest with diffuse sky        | 2.17%         |
| Val05 | PROSPECT-D leaves              | 0.24%         |
| Val06 | fPAR versus solar zenith angle | 0.62%         |

## Documentation

Start with the public tutorials:

- [中文：安装](docs/tutorials/zh/02-installation.md)
- [中文：核心概念与场景生命周期](docs/tutorials/zh/04-concepts.md)
- [中文：API 参考](docs/tutorials/zh/api-reference.md)
- [English: Installation](docs/tutorials/en/02-installation.md)
- [English: Concepts and scene lifecycle](docs/tutorials/en/04-concepts.md)
- [English: API reference](docs/tutorials/en/api-reference.md)

## Citation

If you use LESS in your research, please cite:

> Qi, J., Xie, D., Yin, T., Yan, G., Gastellu-Etchegorry, J.-P., Li, L., Zhang, W., Mu, X., and 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.

## License

LESS is distributed under the [MIT License](LICENSE).
