API reference¶

This page lists the public Python API for LESS 3.1.0. User code starts with import less; every name below is available from the top-level less namespace. Tutorials explain complete workflows, while this page provides a searchable inventory of interfaces, result types, and related chapters.

Use less.can_use() or scene.can_use() to check whether a feature can run on this machine.

Scenes, objects, and geometry¶

API	Purpose
`less.Scene`	Persistent scene that owns geometry, illumination, backend selection, and simulation lifecycle.
`less.Sampler`	`Sampler(method="independent", seed=None)`; set `scene.sampler` to select independent, stratified or Sobol sampling. See sampling method for supported domains.
`less.InstanceHandle`	Updates position, rotation, and scale of placed instances.
`less.Object`	Scene object containing one or more geometry components.
`less.Terrain`	Flat, DEM, or mesh terrain.
`less.Geometry`	Base class for geometry components.
`less.Mesh`	Explicit triangle mesh.
`less.TurbidBoundary`	Closed boundary for statistical vegetation or a general participating medium.
`less.TurbidSampling`	Quality, budget, and seed configuration for statistical leaf sampling.
`less.BoundaryValidationReport`	Turbid boundary validation result.
`less.TurbidBoundaryError`	Raised for an invalid Turbid boundary.

Scene lifecycle and common operations¶

Scene.simulate(sensor_or_process, **kwargs)
Scene.build()
Scene.rebuild()
Scene.update_instances()

import less

scene = less.Scene(backend="auto", device=0)
scene.terrain = less.Terrain(property=less.Lambertian(reflectance=0.2))
scene.illumination = less.Illumination(
    source=less.Sun(zenith=30), atmosphere=less.NoAtmosphere())
sensor_or_process = less.OpticalImager(
    less.Orthographic(image_size=64), bands=[550, 850], quality=16)
product = scene.simulate(sensor_or_process)

scene.build()                 # Optional geometry preparation; no illumination or sensor needed
scene.rebuild()               # Force geometry reload and acceleration rebuild
scene.update_instances()      # Commit InstanceHandle transform changes

Common public methods:

Method	Description
`Scene.add(obj, positions=..., rotations=..., scales=...)`	Adds one or more instances and returns an `InstanceHandle`.
`Scene.get_object(name)`	Returns a named object.
`Scene.build()`	Prepares scene geometry for subsequent simulations; spectral properties are prepared for the actual simulation bands.
`Scene.simulate(sensor_or_process, **kwargs)`	Builds when required, then executes a simulation or process.
`Scene.measure(measurement)`	Runs a non-radiative geometric measurement.
`Scene.solve_energy_balance(...)`	Solves scene energy balance.
`Scene.update_property(path, property)`	Updates the property of a selected scene element.
`Scene.apply_temperatures(product)` / `Scene.clear_temperatures()`	Applies or clears temperature state.
`Scene.validate_turbid_boundaries()`	Validates all Turbid boundaries.
`Scene.can_use(feature, explain=False)`	Checks whether the scene and backend can execute a feature.
`Scene.backend_info()`	Returns the selected backend and device information.
`Scene.inspect_recipe()`	After a successful simulation, returns JSON-safe simulation type, component selection and cache information for diagnostics.
`Scene.show(...)`	Opens the interactive scene viewer.
`Scene.save(path, pack=True)` / `Scene.load(path)`	Saves and loads a scene.

Common object and terrain methods include Object.add_component(), Object.set_property(), Object.get_property(), Terrain.set_property(), and Terrain.height_at().

Properties¶

API	Purpose
`less.Property`	Base property class.
`less.OpticalVegetation`	Base class for two-sided vegetation optics.
`less.OrientationDistribution`, `less.LeafAngle`, `less.distributions`	Inclination distributions of leaf normals and cylinder axes (de Wit, Campbell ellipsoidal, Goel–Strebel beta, sine/cosine powers, fixed, tabulated), shared by turbid media, crown generation and microwave constituents. Turbid optical media accept the de Wit forms.
`less.HomogeneousMedium`	Participating medium with uniform absorption, HG scattering, and optional LTE temperature.
`less.VolumeField`	Dense or OpenVDB-authored heterogeneous density and temperature for passive optical and thermal imaging.
`less.Lambertian`	Lambertian reflectance.
`less.Prospect`	PROSPECT leaf optical model.
`less.Fluspect`	Leaf reflectance, transmittance, and fluorescence.
`less.RPV`	RPV non-Lambertian reflectance model.
`less.WaterSurface`	Wind-dependent directional reflection and an optional water-leaving term for optically deep water.
`less.CoxMunk`	Cox–Munk water-surface slope statistics from 10 m wind speed and direction.
`less.PrescribedRrs`	User-supplied, glint-removed above-water remote-sensing reflectance.
`less.DeepWaterIOP`	Deep-water water-leaving estimate from absorption and backscattering coefficients.
`less.SpectrumDB`	Property values from a spectral database.
`less.ThermalProperty`	Temperature, longwave emissivity and explicit Mesh diffuse transmittance.
`less.BiophysicalProperty`	Physiology and energy-balance parameters.
`less.Farquhar`	Farquhar photosynthesis and stomatal-conductance model.
`less.Microclimate`	Air temperature, humidity, wind, carbon dioxide, and related conditions.

Spatial texture inputs¶

Textures are spatial inputs to named Property parameters; they are not standalone properties. See Spatial textures and property fields for complete UV, GeoTIFF, RGB, thermal, and serialization examples.

API	Purpose
`less.Texture`	Abstract base type for public texture declarations.
`less.ScalarTexture`	One scalar value per pixel, including temperature in K.
`less.SpectralTexture`	Measured values on an explicit or metadata wavelength grid.
`less.RGBTexture`	RGB input with explicit empirical spectral reconstruction.
`less.WorldXY`	Georeferenced world-X/Y mapping and outside-raster policy.
`Property.with_field(name, texture)`	Attaches one texture while retaining the Property's constant fallback.
`Property.with_fields(**textures)`	Attaches multiple named texture parameters.

Common texture controls are mapping, filter, wrap, nodata, missing_uv, outside_spectral_domain, raster_bands, scale, and offset. ScalarTexture and SpectralTexture also accept class_values={class_code: physical_value} for categorical rasters such as land cover. Scene-level texture-memory controls are Scene.texture_memory_budget_bytes and Scene.texture_tile_size.

Microwave-domain properties are less.MicrowaveSoil, less.MicrowaveVegetation, less.MicrowaveTrunk, less.MicrowaveDisc, less.MicrowaveCylinder, less.MicrowaveLeaf, less.MicrowaveNeedle, and less.MicrowaveBranch. See the radar and microwave radiometer tutorials for scene requirements and valid scattering models.

Illumination and atmosphere¶

API	Purpose
`less.Illumination`	Combines a top-of-atmosphere source with an atmosphere model.
`less.Sun`	Solar direction and TOA beam-normal spectral irradiance.
`less.NoAtmosphere`	Vacuum boundary: unattenuated direct beam and no diffuse sky.
`less.PrescribedAtmosphere`	User-specified direct-beam and diffuse-horizontal transmittance.
`less.SimpleSpectralAtmosphere`	Fast simplified spectral atmosphere.
`less.HosekWilkieAtmosphere`	Directional Hosek–Wilkie sky.
`less.SixSAtmosphere`	Optional 6S atmosphere.
`less.Atmosphere`	Built-in layered atmosphere and surface-to-sensor transport.
`less.CloudLayer`	1-D thermal cloud slab with independent-pixel cover mixing.
`less.AtmosphericProfile`	Layered atmospheric profile.
`less.AtmosphereDatabase`	Built-in atmosphere, aerosol, and spectral database.
`less.AtmosphereResult`	Atmospheric solver result.
`less.LibRadtranRunner`	Optional libRadtran atmosphere calculation.
`less.LibRadtranUnavailableError`	Raised when libRadtran is unavailable.

See Illumination and atmosphere for model parameters and units.

Projections, sensors, and instruments¶

Projections¶

API	Purpose
`less.Orthographic`	Orthographic projection.
`less.Perspective`	Perspective projection.
`less.Fisheye`	Fisheye projection.
`less.Pushbroom`	Satellite or airborne pushbroom projection.

Imaging and non-imaging sensors¶

API	Product
`less.OpticalImager`	`less.ImageProduct`
`less.ThermalImager`	`less.ImageProduct`
`less.SIFImager`	`less.ImageProduct`
`less.BRFSensor`	`less.BRFProduct`
`less.ForwardRadiationFieldSensor`	`less.ForwardRadiationFieldProduct`
`less.IrradianceMapSensor`	`less.IrradianceMapProduct`
`less.FourComponentImager`	`less.FourComponentProduct` — per-pixel sunlit/shaded x leaf/soil classification and the visible area of each component. Orthographic projection only.
`less.IrradianceRadiometer`	`less.IrradianceProduct`: cosine-weighted irradiance at a point within a specified FOV.
`less.MicrowaveRadiometer`	Polarized brightness temperature; see Microwave brightness temperature.
`less.RadarScatterometer`	Polarimetric backscatter; see Radar backscatter.
`less.Instrument`	Instrument and multi-band response configuration.

Both microwave sensors accept scattering_samples (default 200_000, integer 2–16,777,216) for angular scattering integration. This is independent of the per-pixel quality budget. See the microwave tutorials for convergence guidance.

Processes and measurements¶

API	Purpose
`less.RadiationFieldProcess`	Computes scene radiation state.
`less.EnergyBalanceProcess`	Jointly solves sunlit/shaded temperatures and energy fluxes.
`less.PhotosynthesisProcess`	Solves photosynthesis and stomatal conductance.
`less.SIFProcess`	Solves solar-induced chlorophyll fluorescence.
`less.Measurement`	Base class for non-radiative measurements.
`less.LAIMeasurement`	Computes object area per unit scene horizontal area; use `property_filter` to select leaves for LAI. Terrain assigned to `scene.terrain` is excluded.
`less.CHMMeasurement`	Produces a canopy height model.

Related results and errors include less.EnergyBalanceResult, less.ComponentEnergyBalanceResult, less.ConvergenceError, and less.SolveResult. less.JointThermoPhysiologySummary reports the iteration count, largest temperature change, and energy closure of one solve.

LiDAR¶

API	Purpose
`less.Scanner`	Scanner configuration.
`less.Platform`	Base platform class.
`less.Aircraft`, `less.UAV`	Airborne platforms.
`less.Tripod`, `less.Vehicle`	Terrestrial platforms.
`less.Waypoint`, `less.ScanPosition`	Flight waypoints and scan positions.
`less.LiDARSurvey`	Combines a platform, scanner, and acquisition plan.
`less.PointCloud`	LiDAR point-cloud product.

Spectral configuration and satellite bands¶

API	Purpose
`less.SpectralBands`	Base spectral-band collection.
`less.DiscreteBands`	Arbitrary non-uniform discrete bands.
`less.Hyperspectral`	Uniform hyperspectral sampling.
`less.SRFBands`	Bands with spectral response functions.
`less.gaussian_bands`	Gaussian SRFs from centre wavelength and FWHM.
`less.Sentinel2A`	Sentinel-2A bands and SRFs.
`less.Landsat8_OLI`	Landsat 8 OLI bands and SRFs.
`less.SpectralProfile`, `less.SpectralBand`	Spectral response descriptions.

Products¶

Products carry scientific arrays and simulation provenance. Use each product's save() and show() methods for export and visualization.

API	Purpose
`less.ImageProduct`	Optical, thermal, or SIF image.
`less.InstrumentImageProduct`	Image retaining instrument-band metadata.
`less.BRFProduct`	Multi-direction BRF.
`less.ForwardRadiationFieldProduct`	Three-dimensional radiation field.
`less.IrradianceMapProduct`	Upwelling and downwelling irradiance maps.
`less.IrradianceProduct`	Point spectral irradiance and Monte Carlo standard error, W/m²/nm.
`less.EnergyBalanceProduct`	Temperatures and energy fluxes.
`less.RadiationFieldProcessProduct`	Radiation-process state.
`less.PhotosynthesisProcessProduct`	Photosynthetic rate and stomatal conductance.
`less.SIFProcessProduct`	SIF process result.
`less.CHMProduct`	Canopy height model.
`less.SceneElementRef`, `less.SceneElementRows`	Unified rows for Mesh, Turbid, and Terrain results.

Measuring canopy height¶

chm = scene.measure(less.CHMMeasurement(resolution=0.5))
heights = chm.heights                 # Height relative to terrain, metres
surface = chm.surface_elevation        # Highest object surface elevation, metres
ground = chm.terrain_elevation         # Terrain elevation, metres

Each cell is sampled at its centre. Canopy height is the highest selected object surface elevation minus terrain elevation, clipped to zero. Cells with ground but no object have zero height; terrain holes produce NaN. Without explicit terrain, ground elevation is zero. Shortened edge cells use their actual centres.

LAI and CHM prepare scene geometry automatically: neither build() nor illumination or a sensor is required. Leaf area is computed on the CPU. Choosing OptiX or Vulkan does not use the GPU for that measurement. Canopy height uses the scene's selected backend. scene.last_execution records the backend that performed the measurement. Terrain provides the height reference and is excluded from LAI. Without a property filter, LAI includes non-leaf object surfaces such as stems.

You can query both capabilities before measuring:

assert scene.can_use("lai_measurement")
assert scene.can_use("chm_measurement")

Saving canopy height products¶

Use chm.save("chm.npz") to save the complete product and less.CHMProduct.load("chm.npz") to read it. NPZ retains the heights, grid extent, metadata, and any terrain and surface elevation arrays present in the product. x_edges and y_edges describe cell boundaries. The final row or column is shorter when the scene size is not a multiple of the resolution.

chm.save("chm.tif") requires rasterio and writes floating-point heights in metres, with NaN marked as no data. Coordinates are local scene coordinates: X increases eastward and Y southward; no map CRS is assigned automatically. GeoTIFF requires uniform cell spacing, so save products with shortened edge cells as NPZ. PNG is a preview with transparent missing cells. NPY stores only the height array, without metadata.

The LAI and CHM property_filter checks both component optical properties and representative leaf properties in statistical canopies. For example, less.Prospect selects explicit leaves and statistical canopies whose leaf properties use PROSPECT.

Projects, resources, and serialization¶

API	Purpose
`less.Project`	Manages a scene, named sensors, resources, and task snapshots.
`less.ProjectValidationReport`, `less.ValidationIssue`	Project validation results.
`less.SnapshotInfo`	Remote-task snapshot metadata.
`less.ProjectResource`, `less.ResourceRegistry`	Project resources and checksums.
`less.load_scene`	Loads a scene from a file.

Principal Project methods are create(), open(), add_sensor(), build(), simulate(), validate(), save(), pack(), and export_snapshot(). See Scenes and projects.

Scene generation and utilities¶

API	Purpose
`less.place`	Grid, random, and Poisson-disc instance placement.
`less.asset_path`	Locates a bundled example mesh by filename.
`less.CrownGenerator`, `less.CrownShape`	Parametric crown generation; `leaf_angle` takes any `less.distributions` family.
`less.SunPosition`, `less.compute_sun_position`, `less.compute_day_of_year`	Solar-position calculations.
`less.SolarSpectrum`, `less.SpectrumLibrary`	Solar, material, and spectral databases.

Backends, capability checks, and errors¶

API	Purpose
`less.list_backends`	Lists discoverable backends.
`less.list_backend_features`	Lists feature names.
`less.available_features`	Lists features executable in the current environment.
`less.can_use`	Tests whether a feature can execute.
`less.feature_status`	Returns feature status and explanation.
`less.backend_capability_matrix`	Returns the backend capability matrix.
`less.BackendFeature`, `less.BackendFeatureStatus`, `less.BackendInfo`	Feature and device information types.
`less.BackendUnavailableError`	Requested backend is unavailable.
`less.BackendFeatureUnavailableError`	The requested calculation is unavailable here. LESS does not substitute another method.

Public API boundary¶

This reference lists the interfaces meant for user code. Names that begin with an underscore are not for user code.