接口参考¶
本页列出 LESS 3.1.1 的公开 Python API。使用 import less 后,即可从 less 访问以下接口。
某项功能能否在本机运行,可以用 less.can_use() 或 scene.can_use() 检查。
场景、对象与几何¶
| API | 用途 |
|---|---|
less.Scene |
持久场景;管理几何、光照、后端和模拟生命周期。 |
less.Sampler |
Sampler(method="auto", seed=None, preparation_method=None);通过 scene.sampler 选择输运策略,preparation_method 可单独控制微波角度积分。支持 independent、stratified、sobol、ldsampler,见采样方式。 |
less.InstanceHandle |
修改已添加实例的位置、旋转和缩放。 |
less.Object |
由一个或多个几何组件组成的场景对象。 |
less.Terrain |
平坦地面、DEM 或网格地形。 |
less.Geometry |
几何组件基类。 |
less.Mesh |
显式三角网格。 |
less.TurbidBoundary |
统计植被或通用参与介质的封闭边界。 |
less.WaterBoundary |
水域几何:WaterBoundary(extent=(宽, 长), depth=None) 或 WaterBoundary("water.obj", group="water");与普通 Object 和组件属性配合使用。 |
less.RegularWaves |
规则重力波:RegularWaves(height, wavelength, direction=0, phase=0, dispersion_depth=None);通过 WaterBoundary(waves=..., extent=..., depth=..., time=0, mesh_spacing=None) 定义波面。 |
less.TurbidSampling |
统计叶片采样 的质量、预算和随机种子配置。 |
less.BoundaryValidationReport |
Turbid 边界验证结果。 |
less.TurbidBoundaryError |
Turbid 边界无效时的异常。 |
Scene 生命周期与常用操作¶
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.sampling_info(sensor_or_process) |
不执行模拟,查看所选采样方式、种子及适用的采样环节。 |
Scene.inspect_recipe() |
模拟成功后返回可直接转为 JSON 的模拟类型、组件选择和缓存信息,便于诊断与复现实验。 |
Scene.show(...) |
打开交互式场景查看器。 |
Scene.save(path, pack=True) / Scene.load(path) |
保存和加载场景。 |
对象和地形常用方法包括 Object.add_component()、Object.set_geometry(component, geometry)、Object.set_property()、Object.get_property()、Object.remove_property(component, domain)、Terrain.set_property() 和 Terrain.height_at()。替换几何后调用 Scene.rebuild(),组件属性与实例位置保持原样。移除组件属性后,对象的默认属性仍按原有规则生效。
采样器¶
通过 scene.sampler 设置,适用于光学、热红外、荧光、微波成像及辐射场和能量过程。
日常使用保留默认设置即可;需要固定种子时,设置:
| 参数 | 默认值 | 说明 |
|---|---|---|
method |
"auto" |
按模拟任务选择;也可指定 "independent"、"stratified"、"sobol"、"ldsampler"。 |
seed |
None |
沿用传感器或过程的种子;整数取值为 0 <= seed < 2**32,场景种子优先。 |
preparation_method |
None |
微波散射表角度积分的采样方式。None 跟随当前方式,也可单独指定上述四种方式。 |
"auto" 对光学、热红外、荧光和被动微波成像,以及光学 BRF、辐照度图和正向辐射场选择 Sobol;
对叶面辐射场、长波、叶温、光合作用、主动微波和四分量影像选择独立随机采样。
LiDAR 使用扫描器设置的加权光束积分。光学 standard_error 使用独立随机采样。
手动选择方式,或分别设置微波影像和角度积分:
scene.sampler = less.Sampler("ldsampler", seed=17)
scene.sampler = less.Sampler(
"sobol", seed=17, preparation_method="independent")
quality 和 num_photons 继续由传感器设置。Sobol 建议使用 2 的整数次幂采样数。
修改采样器后直接再次模拟即可;采样配置随场景保存和加载。
scene.sampler = None 恢复默认设置。
查询与结果信息¶
settings = scene.sampling_info(sensor_or_process)
product = scene.simulate(sensor_or_process)
settings_used = product.metadata["sampler"]
Scene.sampling_info(sensor_or_process) 返回字典,用于在模拟前查看设置。
常用字段如下:
| 字段 | 含义 |
|---|---|
method |
所选采样方式,如 "sobol"。 |
seed |
所选随机种子,或 None。 |
requested_method |
场景设置的方式,如 "auto"。 |
primary_domains |
该模拟涉及的初始采样环节。 |
preparation_sampling |
微波散射表角度积分的采样方式,见微波任务的查询结果。 |
完整示例和各方式的说明见采样方式。
属性¶
| 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 |
深水的风浪反射与离水项;mode="interface", roughness=None 描述水域的平滑反射折射界面。 |
less.WaterThermal |
不透明平滑水面的温度与光谱复折射率,用于热红外发射和环境反射。 |
less.WaterMicrowave |
水温、盐度或复介电常数及表面粗糙度,用于极化微波散射与亮温。 |
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 |
仪器和多波段响应配置。 |
MicrowaveRadiometer 与 RadarScatterometer 接受 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 的统一结果行。 |
ForwardRadiationFieldProduct.absorption_grid 是给定网格内的吸收,outside_grid_absorbed 是网格外各波段的吸收功率,单位为 W/nm。energy_closure 包含两者、地表吸收、逃逸及追踪上限处的剩余能量。网格范围不会截断光子的传播。
测量冠层高度¶
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 包含树干等非叶片对象表面积。
可以在计算前查询场景是否支持这两项能力:
保存冠层高度产品¶
用 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 边界¶
本参考只列出用户可直接调用的接口。名称以下划线开头的对象不供用户代码使用。