02 - 安装与环境配置¶

当前候选版本为 LESS 3.0.0rc1。版本后缀和产品命名见模型介绍；场景复用方式见核心概念，方法签名见API 参考。

硬件要求¶

LESS 提供 Embree CPU、Vulkan Ray Query GPU 和 NVIDIA OptiX 三个后端，安装后自动检测当前机器可用的路径。

要求	Embree CPU	Vulkan GPU	OptiX GPU
硬件	现代 x86_64 CPU	支持 Vulkan Ray Query 的 NVIDIA、AMD 或 Intel GPU	兼容 OptiX 的 NVIDIA GPU
内存	系统内存	4 GB+ 显存（推荐 8 GB+）	4 GB+ 显存（推荐 8 GB+）
驱动	无 GPU 驱动要求	对应厂商的较新显卡驱动	较新的 NVIDIA 驱动
操作系统	Windows 10/11、Linux	Windows 10/11、Linux	Windows 10/11、Linux
Python	3.10–3.13	3.10–3.13	3.10–3.13

没有兼容 GPU：自动使用 Embree，可运行全部公开模拟工作流
有 AMD / Intel GPU：驱动支持 Ray Query 时可使用 Vulkan 后端
有 NVIDIA GPU：可根据功能和性能选择 OptiX 或 Vulkan；生产计算通常优先 OptiX
功能一致：已发布的能量平衡、三维生理耦合、SIF 和 LiDAR 工作流也可在 Embree CPU 上运行

安装¶

使用 pip 直接安装：

pip install less3d

预编译 wheel 已包含三个后端的程序模块、OptiX PTX、Vulkan SPIR-V 以及 Embree 运行库。普通用户不需要安装 CUDA Toolkit、OptiX SDK 或 Vulkan SDK；使用 GPU 时仍需安装对应厂商的显卡驱动。

可选扩展（extras）¶

部分子模块对外部库有额外依赖，不随 less3d 默认安装。按需加 [...]：

Extra	何时需要	装的东西
`lidar`	从 `.las/.laz` 点云重建 3D 场景（见第 17 章）	`laspy`、`cloth-simulation-filter`（SciPy 和 trimesh 已随主包安装）
`atmosphere`	使用 `less.SixSAtmosphere`；原生 `less.Atmosphere` 不需要此扩展（见大气模型）	`Py6S`
`dev`	跑 `tests/run_all_tests.py` 做回归测试（普通用户用不上）	`pytest`

pip install less3d[lidar]          # 装 lidar 依赖
pip install less3d[lidar] -U       # 已经装过，更新到最新

验证安装¶

import less

# 打印版本号
print(f"LESS version: {less.__version__}")

# 检查三个后端在本机是否可用
for backend in less.list_backends(probe=True):
    print(backend.name, backend.available,
          backend.unavailable_reason or "")

如果一切正常，您将看到类似输出：

LESS version: 3.0.0rc1
optix True
embree True
vulkan True

后端与设备选择¶

LESS 提供三个后端：NVIDIA OptiX、跨厂商 Vulkan Ray Query 和 CPU Embree。默认 Scene() 会根据当前环境和所需功能自动选择：

scene = less.Scene()                          # 默认 'auto'：按功能和本机环境自动选择
scene = less.Scene(backend='optix')           # 强制 NVIDIA OptiX；不可用则直接报错
scene = less.Scene(backend='vulkan')          # 强制 Vulkan；支持 NVIDIA / AMD / Intel GPU
scene = less.Scene(backend='embree')          # 强制 CPU（多线程 Embree）
scene = less.Scene(backend='vulkan', device=1) # 选择第二个兼容的 Vulkan 设备

参数	默认	含义
`backend`	`'auto'`	`'auto'` / `'optix'` / `'vulkan'` / `'embree'`。历史别名 `gpu`/`cuda` 特指 OptiX，并不代表所有 GPU；`vk` → Vulkan，`cpu` → Embree
`device`	`0`	所选 GPU 后端内部的兼容设备序号；OptiX 与 Vulkan 的编号不保证相同

三个后端的取舍：

OptiX：NVIDIA GPU 上的生产首选，通常性能最好
Vulkan：跨 NVIDIA、AMD、Intel GPU，当前仍标记为 Experimental；主要工作流已有跨后端回归
Embree：无需 GPU 的 CPU 路径，也适合作为数值参照
物理一致性：共同工作流在解析容差或蒙特卡罗噪声范围内对照验证；不同后端不保证逐位相同
功能检查：用 less.can_use("功能名") 判断当前安装环境能否直接使用；用 less.available_features() 列出当前可用功能

用户通常只需要知道“当前能不能运行”。可以直接查看：

print(less.list_backends(probe=True))
print(less.can_use("lidar_waveform", backend="vulkan"))

scene = less.Scene(backend="vulkan")
print(scene.can_use("energy_balance"))

can_use() 会同时考虑代码实现、安装包编译内容以及本机驱动；用户无需分别判断原因。

示例：在你的机器上对比三个后端的耗时¶

import time
import less

def run(backend):
    scene = less.Scene(backend=backend)
    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.SimpleSpectralAtmosphere(turbidity=2.0))
    sensor = less.OpticalImager(
        less.Orthographic(image_size=256),
        bands=[650, 550, 450], quality=64)
    scene.simulate(sensor)                        # 首次调用自动构建并预热
    t0 = time.perf_counter()
    scene.simulate(sensor)
    return time.perf_counter() - t0

for b in ['optix', 'vulkan', 'embree']:
    try:
        print(f"  {b}: {run(b)*1000:.1f} ms")
    except Exception as e:
        print(f"  {b}: 不可用 ({type(e).__name__})")

GPU 后端可用时，第一次 scene.simulate() 会自动构建场景并打印实际设备名称。例如 NVIDIA、AMD 或 Intel 设备可能分别显示为：

GPU: NVIDIA GeForce RTX 4080 (... MB free)
GPU: AMD Radeon ... (... MB device-local)
GPU: Intel Arc ... (... MB device-local)

这里只表示检测到了设备。最终能否运行某项功能，请以 scene.can_use(...) 的返回值为准。

自动选择会优先尝试适合当前工作流的可用后端。若需要可重复的性能测试或明确指定硬件，请显式设置 backend，不要依赖 auto。

显式选择的后端不可用时会直接给出原因，例如缺少编译支持、驱动不兼容或设备不支持 Ray Query，而不会静默改用另一个后端。

查看内置示例¶

LESS 自带几个演示场景，可以快速验证安装是否正常：

import less

# 列出所有内置示例
less.examples.list()

# 运行秋季森林示例（打开交互式查看器）
less.examples.run("autumn_forest")

# 运行玉米田示例
less.examples.run("maize_field")

如果交互式查看器正常打开并显示三维场景，说明安装成功。

常见问题¶

没有 GPU 能用吗？¶

可以。LESS 在没有兼容 GPU 的机器上会自动使用 Embree CPU 后端，并可运行与 GPU 后端相同的公开工作流。大型蒙特卡罗任务在 CPU 上通常更慢，但不会静默省略物理过程或返回不完整产品。

GPU 加速未生效¶

先运行 less.list_backends(probe=True) 查看 OptiX、Vulkan 和 Embree 的实际可用状态。NVIDIA GPU 可使用 OptiX 或 Vulkan；AMD、Intel GPU 使用 Vulkan。如果目标 GPU 后端不可用，请更新对应厂商的显卡驱动并确认设备支持 Vulkan Ray Query。NVIDIA 用户还可用 nvidia-smi 检查驱动和设备状态。

显存不足¶

RuntimeError: Out of GPU memory

原因：场景过大（三角面片数过多）或显存被其他程序占用。
解决：减小场景规模，关闭其他占用显存的程序，或切换到 CPU 模式。

`image.show()` / `result.show()` 不出图¶

症状：在 PyCharm（尤其老版本）或某些 Linux 桌面环境下，image.show() 调用后窗口不弹出、IDE 也不显示，但程序无报错继续往下走。

原因：matplotlib 选了一个不可交互的后端（如 Agg、module://backend_interagg）。LESS 把可视化交给 matplotlib，自身不挑后端。

解决：在脚本最顶端、import matplotlib 之前显式选一个交互后端：

import matplotlib
matplotlib.use('TkAgg')      # 通用首选；conda 环境自带 Tk
# 或: matplotlib.use('Qt5Agg')  # 已装 PyQt5 / PySide2
import matplotlib.pyplot as plt

import less                   # 之后 less 内部的 plt 调用就会用 TkAgg

不要在 less 库里硬写 matplotlib.use(...) —— 那样会破坏无头服务器环境（CI / 远程跑批）。后端的选择是用户脚本的责任。

如果你只是想保存图不需要弹窗，直接 image.save("out.png") / result.save("out.csv") 即可，不依赖 matplotlib 后端。

下一步¶

03 - 坐标系与场景几何