API 参考¶

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

计算功能是否可用取决于安装的平台和原生后端。提交任务前可使用 less.can_use() 或 scene.can_use() 检查；缺少实现时 LESS 会明确报错，不会静默切换到近似算法。

场景、对象与几何¶

API	用途
`less.Scene`	持久场景；管理几何、光照、后端和模拟生命周期。
`less.InstanceHandle`	修改已添加实例的位置、旋转和缩放。
`less.Object`	由一个或多个几何组件组成的场景对象。
`less.Terrain`	平坦地面、DEM 或网格地形。
`less.Geometry`	几何组件基类。
`less.Mesh`	显式三角网格。
`less.TurbidBoundary`	统计植被介质的封闭边界。
`less.TurbidSampling`	Turbid resident leaf sample 的质量、预算和随机种子配置。
`less.BoundaryValidationReport`	Turbid 边界验证结果。
`less.TurbidBoundaryError`	Turbid 边界无效时的异常。

Scene 生命周期与常用操作¶

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

scene = less.Scene(backend="auto", device=0)
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.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.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 级驻留数据控制为 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。使用前请通过 capability API 检查当前版本和后端支持情况。

光照与大气¶

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.RadiationFieldSensor`	`less.RadiationFieldProduct`
`less.IrradianceMapSensor`	`less.IrradianceMapProduct`
`less.MicrowaveRadiometer`	微波辐射测量产品；使用前检查 capability。
`less.RadarScatterometer`	雷达散射测量产品；使用前检查 capability。
`less.Instrument`	仪器和多波段响应配置。

过程与测量¶

API	用途
`less.RadiationFieldProcess`	计算场景辐射状态。
`less.EnergyBalanceProcess`	联合求解阳叶/阴叶温度和能量通量。
`less.PhotosynthesisProcess`	求解光合作用和气孔导度。
`less.SIFProcess`	求解太阳诱导叶绿素荧光。
`less.Measurement`	非辐射传输测量基类。
`less.LAIMeasurement`	计算叶面积指数。
`less.CHMMeasurement`	生成冠层高度模型。

过程相关结果和错误包括 less.EnergyBalanceResult、less.ComponentEnergyBalanceResult、less.JointThermoPhysiologySummary、less.ConvergenceError 和 less.SolveResult。

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.RadiationFieldProduct`	三维辐射场。
`less.IrradianceMapProduct`	上行/下行辐照度图。
`less.EnergyBalanceProduct`	温度和能量通量。
`less.RadiationFieldProcessProduct`	辐射过程状态。
`less.PhotosynthesisProcessProduct`	光合速率和气孔导度。
`less.SIFProcessProduct`	SIF 过程结果。
`less.CHMProduct`	冠层高度模型。
`less.SceneElementRef`、`less.SceneElementRows`	Mesh、Turbid 和 Terrain 的统一结果行。

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()。详见Scene 与 Project。

场景生成与辅助工具¶

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

后端、功能检查与异常¶

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`	请求的原生功能不可用且未执行 fallback。

公开 API 边界¶

本参考只包含用户可直接调用的接口。以下内容属于实现细节，不是公开 API：以下划线开头的名称、_native_optix、_native_vulkan、_native_embree、native scene manager、GPU buffer、artifact validator 和 debug hook。用户代码不应导入或依赖这些对象。