接口参考¶

本页列出 LESS 3.1.0 的公开 Python API。日常使用从 import less 开始；以下名称均可从 less 顶层命名空间访问。教程负责说明完整工作流程，本页用于快速查找接口、返回类型和相关章节。

某项功能能否在本机运行，可以用 less.can_use() 或 scene.can_use() 检查。

场景、对象与几何¶

API	用途
`less.Scene`	持久场景；管理几何、光照、后端和模拟生命周期。
`less.Sampler`	`Sampler(method="independent", seed=None)`；通过 `scene.sampler` 选择独立随机、分层或 Sobol 采样，见采样方式。
`less.InstanceHandle`	修改已添加实例的位置、旋转和缩放。
`less.Object`	由一个或多个几何组件组成的场景对象。
`less.Terrain`	平坦地面、DEM 或网格地形。
`less.Geometry`	几何组件基类。
`less.Mesh`	显式三角网格。
`less.TurbidBoundary`	统计植被或通用参与介质的封闭边界。
`less.TurbidSampling`	统计叶片采样的质量、预算和随机种子配置。
`less.BoundaryValidationReport`	Turbid 边界验证结果。
`less.TurbidBoundaryError`	Turbid 边界无效时的异常。

Scene 生命周期与常用操作¶

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()                 # 可选：提前准备几何；不需要光照或传感器
scene.rebuild()               # 强制重新读取几何并重建加速结构
scene.update_instances()      # 提交 InstanceHandle 的变换更新

常用公开方法：

方法	说明
`Scene.add(obj, positions=..., rotations=..., scales=...)`	添加一个或多个对象实例，返回 `InstanceHandle`。
`Scene.get_object(name)`	按名称获取对象。
`Scene.build()`	准备场景几何以便后续模拟；光谱属性在模拟时按实际波段准备。
`Scene.simulate(sensor_or_process, **kwargs)`	必要时自动构建，然后执行模拟或过程。
`Scene.measure(measurement)`	执行非辐射传输的几何测量。
`Scene.solve_energy_balance(...)`	求解场景能量平衡。
`Scene.update_property(path, property)`	更新指定场景元素的属性。
`Scene.apply_temperatures(product)` / `Scene.clear_temperatures()`	应用或清除温度状态。
`Scene.validate_turbid_boundaries()`	验证所有 Turbid 边界。
`Scene.can_use(feature, explain=False)`	检查当前场景与后端是否可执行功能。
`Scene.backend_info()`	返回实际后端和设备信息。
`Scene.inspect_recipe()`	模拟成功后返回可直接转为 JSON 的模拟类型、组件选择和缓存信息，便于诊断与复现实验。
`Scene.show(...)`	打开交互式场景查看器。
`Scene.save(path, pack=True)` / `Scene.load(path)`	保存和加载场景。

对象和地形常用方法包括 Object.add_component()、Object.set_property()、Object.get_property()、Terrain.set_property() 和 Terrain.height_at()。

属性¶

API	用途
`less.Property`	属性基类。
`less.OpticalVegetation`	双面植被光学属性基类。
`less.OrientationDistribution`、`less.LeafAngle`、`less.distributions`	叶片法线与圆柱轴的倾角分布(de Wit、Campbell 椭球、Goel–Strebel beta、正弦/余弦幂、固定角、表格),供湍流介质、树冠生成和微波组分共用。湍流光学介质支持 de Wit 分布。
`less.HomogeneousMedium`	均匀吸收、HG 散射和可选 LTE 温度的参与介质。
`less.VolumeField`	用于被动光学和热红外成像的稠密或 OpenVDB 非均匀密度与温度场。
`less.Lambertian`	朗伯反射属性。
`less.Prospect`	PROSPECT 叶片光学模型。
`less.Fluspect`	叶片反射、透射与荧光模型。
`less.RPV`	RPV 非朗伯反射模型。
`less.WaterSurface`	光学深水的风浪方向反射与可选离水项。
`less.CoxMunk`	由 10 m 风速和风向描述的 Cox–Munk 水面斜率统计。
`less.PrescribedRrs`	用户给定、已去除耀斑的水面上方遥感反射率。
`less.DeepWaterIOP`	根据吸收与后向散射系数估算深水离水项。
`less.SpectrumDB`	从光谱数据库获取属性。
`less.ThermalProperty`	温度、长波发射率及显式网格的漫透射率。
`less.BiophysicalProperty`	生理和能量平衡参数。
`less.Farquhar`	Farquhar 光合作用与气孔导度模型。
`less.Microclimate`	空气温度、湿度、风速和二氧化碳等环境条件。

空间纹理输入¶

纹理是具名 Property 参数的空间输入，并不是独立 Property。UV、GeoTIFF、RGB、热红外和序列化的完整示例见空间纹理与属性场。

API	用途
`less.Texture`	公共纹理声明的抽象基类。
`less.ScalarTexture`	每像素一个标量，例如单位为 K 的温度。
`less.SpectralTexture`	显式波长或元数据波长网格上的实测值。
`less.RGBTexture`	带显式经验光谱重建的 RGB 输入。
`less.WorldXY`	地理 world-X/Y 映射和栅格外策略。
`Property.with_field(name, texture)`	绑定一个纹理，同时保留 Property 的常量回退值。
`Property.with_fields(**textures)`	一次绑定多个具名纹理参数。

纹理常用控制包括 mapping、filter、wrap、nodata、missing_uv、outside_spectral_domain、raster_bands、scale 和 offset。ScalarTexture 与 SpectralTexture 还可用 class_values={类别码: 物理值} 解释土地覆盖等分类栅格。场景纹理内存控制为 Scene.texture_memory_budget_bytes 和 Scene.texture_tile_size。

微波域属性为 less.MicrowaveSoil、less.MicrowaveVegetation、less.MicrowaveTrunk、less.MicrowaveDisc、less.MicrowaveCylinder、less.MicrowaveLeaf、less.MicrowaveNeedle 和 less.MicrowaveBranch。场景要求与散射模型的适用范围见雷达和微波辐射计教程。

光照与大气¶

API	用途
`less.Illumination`	组合大气层顶辐射源与大气模型。
`less.Sun`	太阳方向和 TOA 束法向光谱辐照度。
`less.NoAtmosphere`	真空边界：直射不衰减、无天空散射。
`less.PrescribedAtmosphere`	用户指定直射束透射率和水平散射透射系数。
`less.SimpleSpectralAtmosphere`	快速简化光谱大气。
`less.HosekWilkieAtmosphere`	Hosek–Wilkie 方向性天空。
`less.SixSAtmosphere`	可选 6S 大气模型。
`less.Atmosphere`	LESS 内置分层大气和地表—传感器传播。
`less.CloudLayer`	1-D 热红外云层（覆盖度混合的平面平行薄层）。
`less.AtmosphericProfile`	分层大气廓线。
`less.AtmosphereDatabase`	内置大气、气溶胶和光谱数据库。
`less.AtmosphereResult`	大气求解结果。
`less.LibRadtranRunner`	调用可选的 libRadtran 计算大气。
`less.LibRadtranUnavailableError`	libRadtran 不可用时的异常。

完整的大气参数和单位见光照与大气。

投影、传感器与仪器¶

投影¶

API	用途
`less.Orthographic`	正射投影。
`less.Perspective`	透视投影。
`less.Fisheye`	鱼眼投影。
`less.Pushbroom`	卫星或航空推扫投影。

成像与非成像传感器¶

API	返回产品
`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`，光照/阴影 × 叶片/土壤的逐像元分类与各分量可见面积。仅接受 `Orthographic` 投影。
`less.IrradianceRadiometer`	`less.IrradianceProduct`，指定位置、方向与视场的余弦加权辐照度。
`less.MicrowaveRadiometer`	偏振亮温；见微波亮温。
`less.RadarScatterometer`	极化后向散射；见雷达后向散射。
`less.Instrument`	仪器和多波段响应配置。

两类微波传感器均接受 scattering_samples（默认 200_000，整数范围 2–16,777,216），用于散射角积分。它与控制每像元射线数的 quality 独立；收敛检查见微波教程。

过程与测量¶

API	用途
`less.RadiationFieldProcess`	计算场景辐射状态。
`less.EnergyBalanceProcess`	联合求解阳叶/阴叶温度和能量通量。
`less.PhotosynthesisProcess`	求解光合作用和气孔导度。
`less.SIFProcess`	求解太阳诱导叶绿素荧光。
`less.Measurement`	非辐射传输测量基类。
`less.LAIMeasurement`	按场景水平面积计算对象面积指数；用 `property_filter` 筛选叶片以计算 LAI。`scene.terrain` 中的地形不参与统计。
`less.CHMMeasurement`	生成冠层高度模型。

过程结果和错误包括 less.EnergyBalanceResult、less.ComponentEnergyBalanceResult、less.ConvergenceError 和 less.SolveResult。less.JointThermoPhysiologySummary 给出这次求解的迭代次数、最大温度变化和能量闭合。

LiDAR¶

API	用途
`less.Scanner`	扫描器配置。
`less.Platform`	平台基类。
`less.Aircraft`、`less.UAV`	航空平台。
`less.Tripod`、`less.Vehicle`	地面平台。
`less.Waypoint`、`less.ScanPosition`	航迹点和扫描位置。
`less.LiDARSurvey`	组合平台、扫描器和采集任务。
`less.PointCloud`	LiDAR 点云产品。

光谱与卫星波段¶

API	用途
`less.SpectralBands`	波段集合基类。
`less.DiscreteBands`	任意非均匀离散波段。
`less.Hyperspectral`	均匀高光谱采样。
`less.SRFBands`	带光谱响应函数的波段。
`less.gaussian_bands`	由中心波长和 FWHM 构造高斯 SRF。
`less.Sentinel2A`	Sentinel-2A 波段和 SRF。
`less.Landsat8_OLI`	Landsat 8 OLI 波段和 SRF。
`less.SpectralProfile`、`less.SpectralBand`	光谱响应描述。

产品¶

所有产品都携带科学数据和模拟条件记录，并通过自身的 save()/show() 方法完成导出和显示。

API	用途
`less.ImageProduct`	光学、热红外或 SIF 图像。
`less.InstrumentImageProduct`	保留仪器波段信息的图像。
`less.BRFProduct`	多方向 BRF。
`less.ForwardRadiationFieldProduct`	三维辐射场。
`less.IrradianceMapProduct`	上行/下行辐照度图。
`less.IrradianceProduct`	点式光谱辐照度与蒙特卡洛标准误差，W/m²/nm。
`less.EnergyBalanceProduct`	温度和能量通量。
`less.RadiationFieldProcessProduct`	辐射过程状态。
`less.PhotosynthesisProcessProduct`	光合速率和气孔导度。
`less.SIFProcessProduct`	SIF 过程结果。
`less.CHMProduct`	冠层高度模型。
`less.SceneElementRef`、`less.SceneElementRows`	Mesh、Turbid 和 Terrain 的统一结果行。

测量冠层高度¶

chm = scene.measure(less.CHMMeasurement(resolution=0.5))
heights = chm.heights                 # 相对地面的冠层高度，米
surface = chm.surface_elevation        # 对象最高表面的场景高程，米
ground = chm.terrain_elevation         # 地形高程，米

每个网格在中心位置取样，冠层高度为对象最高表面高程减去地形高程，小于零的结果记为零。有地面而没有对象的网格高度为零；地形缺口记为 NaN。没有设置地形时，以高程零作为地面。缩短的末端网格使用其实际中心取样。

LAI 和 CHM 会自动准备场景几何，不需要先调用 build()，也不需要设置光照或传感器。叶面积在 CPU 上统计；选择 OptiX 或 Vulkan 也不会为这项统计使用 GPU。冠层高度由场景所选后端计算。scene.last_execution 记录这次计算使用的后端。地形只提供高度参照，不计入 LAI；未经属性筛选的 LAI 包含树干等非叶片对象表面积。

可以在计算前查询场景是否支持这两项能力：

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

保存冠层高度产品¶

用 chm.save("chm.npz") 保存完整产品，再用 less.CHMProduct.load("chm.npz") 读取。NPZ 保留高度数组、网格范围、元数据及产品中已有的地表和表面高程数组。x_edges、y_edges 给出各网格的边界；场景尺寸不是分辨率的整数倍时，最后一行或一列会缩短。

chm.save("chm.tif") 需要安装 rasterio，输出以米为单位的浮点高度，并将 NaN 标记为无数据。坐标采用场景局部坐标：X 向东、Y 向南，不自动指定地图坐标系。GeoTIFF 要求等间距网格；含缩短末端网格的产品请保存为 NPZ。 PNG 用于预览，缺失网格透明；NPY 仅保存高度数组，不包含元数据。

LAI 和 CHM 的 property_filter 同时检查组件光学属性和统计冠层的代表性叶片属性。例如，less.Prospect 可以筛选显式叶片及使用 PROSPECT 叶片属性的统计冠层。

Project、资源与序列化¶

API	用途
`less.Project`	管理场景、命名传感器、资源和任务快照。
`less.ProjectValidationReport`、`less.ValidationIssue`	工程验证结果。
`less.SnapshotInfo`	远程任务快照信息。
`less.ProjectResource`、`less.ResourceRegistry`	工程资源和校验和管理。
`less.load_scene`	从文件加载场景。

Project 的主要方法包括 create()、open()、add_sensor()、build()、simulate()、validate()、save()、pack() 和 export_snapshot()。详见场景与工程。

场景生成与辅助工具¶

API	用途
`less.place`	网格、随机和泊松盘实例布置。
`less.asset_path`	按文件名定位随包分发的示例网格。
`less.CrownGenerator`、`less.CrownShape`	参数化树冠生成;`leaf_angle` 可取任意 `less.distributions` 分布。
`less.SunPosition`、`less.compute_sun_position`、`less.compute_day_of_year`	太阳位置计算。
`less.SolarSpectrum`、`less.SpectrumLibrary`	太阳、材料和光谱数据库。

后端、功能检查与异常¶

API	用途
`less.list_backends`	列出可发现的后端。
`less.list_backend_features`	列出功能名称。
`less.available_features`	列出当前环境可执行的功能。
`less.can_use`	判断功能是否可执行。
`less.feature_status`	返回功能状态和原因。
`less.backend_capability_matrix`	返回后端能力矩阵。
`less.BackendFeature`、`less.BackendFeatureStatus`、`less.BackendInfo`	功能和设备信息类型。
`less.BackendUnavailableError`	请求的后端不可用。
`less.BackendFeatureUnavailableError`	当前环境不能完成这项计算，LESS 不会改用别的算法代替。

公开 API 边界¶

本参考只列出用户可直接调用的接口。名称以下划线开头的对象不供用户代码使用。