API 参考

本文按对象和用途说明 Lambda Sim 的常用 Python API、参数、返回值和调用约束。完整操作流程见快速开始，本页不重复机器人示例和环境安装步骤。

Lambda Sim 接口以 src/lambdasim/ 当前源码为准；LambdaRenderer、RenderConfig 和 RenderOutput 来自匹配版本的 path-tracer。签名摘要省略 self 和部分低频参数，... 表示仍有其他参数，不是需要传入的值。

1. API 概览

使用场景	模块	常用接口
场景导入与生命周期	lambdasim.scene.scene	Scene、add_usd()、add_rigid_usd()、add_solid_usd()、finalize()
状态、控制与推进	lambdasim.scene.scene	get_model()、get_simdata()、add_solver()、upload_control()、step()
相机与渲染	lambdasim.scene.scene、path_tracer	add_sensor_camera()、LambdaRenderer、RenderConfig、RenderOutput
刚体与机器人求解	lambdasim.solvers.solver_mujoco	SolverMuJoCoMusa
布料求解	lambdasim.solvers.solver_verafiber	SolverVeraFiber
刚体与布料单向耦合	lambdasim.solvers.solver_mujoco_verafiber_oneway	SolverMuJoCoToVeraFiberOneWay
程序化场景构建	lambdasim.scene.builder	Builder
几何与 USD 工具	lambdasim.geometry、lambdasim.usd	Mesh、GeoType、get_mesh()、get_transform()
辅助数据处理	lambdasim.data_synth、lambdasim.data_synth_stitch	render_usd_camera_images()、stitch_data_synth_sequence()

常用顺序为：构建或导入场景 → finalize() → 按需注册求解器 → 更新控制并推进状态 → 更新渲染器并生成图像。只做静态渲染或 USD 动画回放时，不需要注册动力学求解器。

项目依赖包括 ektro、alphacore-ektro、path-tracer、usd-core、imageio、imageio-ffmpeg 和 OpenImageIO；MuJoCo 流程还需要对应后端的 mujoco-warp。具体版本见 pyproject.toml。设备支持取决于所用组件，不能把数组支持 CPU 等同于整个渲染或求解流程支持 CPU。

2. 场景导入与生命周期

2.1 创建场景

from lambdasim.scene.scene import Scene

scene = Scene()

Scene() 返回空场景。导入和构建阶段准备场景数据，finalize() 创建运行时对象；两者都不会自动开始物理求解。

2.2 选择导入接口

接口	主要用途	返回值
Scene.add_usd()	场景展示、渲染和已有 USD 动画回放	导入结果；常用auto、rigid、solid 路径返回字典
Scene.add_rigid_usd()	通过刚体装配路径导入物体或关节机器人	刚体导入结果字典
Scene.add_solid_usd()	导入固体力学所需的几何与约束，例如布料和软体	几何与约束导入结果字典

导入结果中的 Stage、路径映射和统计信息随入口而异，不是 Model 或 SimData。运行时对象应在 finalize() 后通过对应 getter 获取。

Scene.add_usd()

签名：

add_usd(
    usd_path, prim_path="/", namespace="auto", imports=None,
    ignore_paths=None, rigid_read_only=True,
    time_code_mode="start", time_code=None,
    hide_collision_shapes=False, force_show_colliders=False, static=False
)

参数	默认值	说明
usd_path	必填	USD、USDA 或 USDC 文件路径
prim_path	"/"	导入根 Prim 路径
namespace	"auto"	常用值为auto、rigid、solid；auto 按场景内容组织导入
imports	None	显式导入列表，条目可包含root_path、namespace 和路径过滤信息
ignore_paths	None	忽略的 Prim 路径
rigid_read_only	True	使用刚体只读导入路径，适合展示和回放
time_code_mode	"start"	default、start 或 explicit
time_code	None	explicit 模式使用的时间码
hide_collision_shapes	False	隐藏碰撞形状的渲染显示
force_show_colliders	False	强制显示碰撞形状
static	False	是否导入到静态场景构建器

显式 imports 的命名空间仅支持 rigid 和 solid。重叠根路径等不符合导入契约的配置会被拒绝。

namespace="auto" 不等于自动装配可控制的机器人。交互式刚体或机器人应使用 add_rigid_usd()；namespace="rigid"、未提供 imports 且 rigid_read_only=False 的调用会被拒绝。

Scene.add_rigid_usd()

签名摘要：

add_rigid_usd(
    usd_path, prim_path="/", pos=(0, 0, 0), quat=(0, 0, 0, 1),
    floating=None, base_joint=None, parent_body=-1,
    collapse_fixed_joints=False, enable_self_collisions=True,
    apply_up_axis_from_stage=False, joint_ordering="dfs",
    skip_mesh_approximation=True, hide_collision_shapes=False, ...
)

参数	默认值	说明
usd_path、prim_path	必填、"/"	输入文件及导入根 Prim
pos、quat	零平移、单位四元数	导入时施加的根变换；四元数顺序为(x, y, z, w)
floating	None	是否为根节点创建自由关节；None 使用导入器默认处理
parent_body	-1	根节点关联的父 body；-1 为世界
collapse_fixed_joints	False	是否合并固定关节连接的 body
enable_self_collisions	True	是否允许导入结构内部的自碰撞
joint_ordering	"dfs"	关节遍历顺序，可选dfs 或 bfs
skip_mesh_approximation	True	是否跳过 USD 中声明的碰撞网格近似
hide_collision_shapes	False	是否隐藏碰撞几何的渲染显示
body_gravcomp	0.0	刚体重力补偿系数
joint_armature、joint_passive_damping、joint_friction	None	关节惯性、被动阻尼和摩擦覆盖参数
joint_limits、locked_joints	None	关节限位覆盖和锁定关节列表

驱动模式、增益、关节布局及碰撞数据应与求解器匹配。导入成功不表示已经建立了控制器或完成了物理参数验证。

Scene.add_solid_usd()

签名：

add_solid_usd(
    geometry_usd, *, constraint_usd=None,
    pos=(0, 0, 0), quat=(0, 0, 0, 1),
    geometry_prim_path=None, constraint_prim_path="/",
    constraint_mode="usd", apply_up_axis_from_stage=False,
    time_code_mode="start", time_code=None, import_uvs=True, static=False
)

参数	默认值	说明
geometry_usd	必填	几何 USD
constraint_usd	None	约束 USD；默认约束模式下必须提供
geometry_prim_path	None	几何根路径；当前实现将None 解析为 /Geometry/SimMesh
constraint_prim_path	"/"	约束根路径
constraint_mode	"usd"	从 USD 加载约束；"none" 表示不加载约束
pos、quat	零平移、单位四元数	导入变换
import_uvs	True	是否导入 UV
apply_up_axis_from_stage	False	是否应用 USD Stage 的 up-axis 变换

constraint_mode="usd" 缺少 constraint_usd 时会报错；"generated" 当前抛出 NotImplementedError，不能用来自动生成约束。几何、属性和约束必须满足实际求解器的数据要求。

2.3 创建和释放运行时对象

接口	返回值	说明
finalize(device, env_num, primvar_map={})	None	创建指定设备和环境数量的Model、SimData、RenderScene
get_model()	Model	获取模型与物理参数
get_simdata()	SimData	获取运行时状态和控制数据
get_render_scene()	RenderScene	获取渲染场景
close()	None	关闭场景运行时资源，保留 host 侧构建器数据

device 和 env_num 是 finalize() 的必填参数。primvar_map 用于传递自定义属性映射，通常可以省略。获取运行时对象、注册求解器或推进前必须完成 finalize()；关闭场景后不要继续使用原运行时对象。

3. 状态、控制与推进

3.1 模型和状态对象

对象	获取方式	职责
Model	scene.get_model()	场景结构、物理参数、标签及索引关系
SimData	scene.get_simdata()	刚体位姿、关节状态、固体状态及控制缓冲区
RenderScene	scene.get_render_scene()	渲染几何、变换、材质、相机和灯光

物理状态与渲染状态不是同一个对象。直接修改 SimData 不等于渲染器已经接收到更新；必要时需要同步渲染状态并调用渲染器的 update_scene()。

3.2 求解器注册与物理推进

接口	返回值	前提与行为
add_solver(solver)	注册的求解器对象	先完成finalize()；内部调用 solver.initialize(sim_data)
remove_solver(*, close=True)	原求解器或None	移除当前求解器；默认调用其close()，保留场景运行时状态
upload_control()	None	将当前控制数据交给已注册求解器
step(dt, sync_render=True)	None	调用已注册求解器推进，默认同步渲染状态
sync_render_from_sim_data()	None	将运行时物理状态同步到渲染场景

dt 必须为正的有限数值，表示此次推进的仿真时间。Scene 同时只允许一个活动求解器；耦合场景应注册组合求解器，而不是重复调用 add_solver()。

Scene.step() 已有动力学推进实现，但只有注册求解器后才会调用物理求解。未注册求解器时，不会自动生成物体运动。

使用 step(dt, sync_render=False) 时，通常应在需要输出图像前调用一次 sync_render_from_sim_data()；若启用了 USD 序列导出，捕获帧时仍会按导出需要同步状态。

3.3 关节控制与状态读取

以下方法均要求场景已完成 finalize()：

接口	返回值或用途
get_joint_positions(joint_ids, env_index=0)	返回所选关节的位置坐标 NumPy 数组
get_joint_velocities(joint_ids, env_index=0)	返回所选关节的速度自由度 NumPy 数组
set_joint_position_targets(joint_ids, values, env_index=None)	写入关节位置控制目标，返回None
set_joint_velocity_targets(joint_ids, values, env_index=None)	写入关节速度控制目标，返回None
set_joint_effort_targets(joint_ids, values, env_index=None)	写入力矩或力目标，返回None
get_link_world_pose(body_id, env_index=0)	返回(px, py, pz, qx, qy, qz, qw)

joint_ids 是关节索引，不是展开后的自由度索引。位置状态按关节坐标数量组织，控制目标按关节自由度组织；不能假定每个关节都只对应一个数值。写入方法的 env_index=None 可作用于所有环境，数组形状必须匹配目标缓冲区。

控制目标应与关节驱动模式一致。设置目标后，通过 upload_control() 上传，再用 step() 推进；这不同于直接覆盖关节状态。

3.4 USD 动画回放

接口	返回值	说明
update_by_frame(frame=None)	None	按 USD 时间采样更新场景状态
GetStartTimeCode()	float 或 None	已导入回放数据的最小起始时间码
GetEndTimeCode()	float 或 None	已导入回放数据的最大结束时间码

时间码不等于秒。update_by_frame() 回放已有 USD 数据，不运行控制器或动力学积分；物理推进应使用 step()。

4. 相机与渲染

4.1 相机接口

接口	返回值	说明
add_sensor_camera(pos=(0, 0, 0), lookat=(0, 0, -1), up=(0, 1, 0), vfov=60.0, focal_length=35.0, static=True)	相机索引int	添加传感器相机；相机索引从0 开始
set_camera_transform(camera_index, transform, env_index=None)	None	设置相机额外的世界空间变换，要求已完成finalize()
get_light_list()	list[int]	获取当前渲染场景的灯光索引

set_camera_transform() 的 transform 是 7 个数值组成的序列，顺序为 (px, py, pz, qx, qy, qz, qw)。env_index=None 更新模型中的相机变换并同步所有环境；指定环境索引时只修改该环境的渲染变换。

相机选择与相机位姿修改是不同操作。set_camera_index() 只选择已有相机，不创建相机，也不改变其位姿。

4.2 渲染器接口

导入路径：

from path_tracer.config import EnvironmentLightMode, RenderConfig, RenderOutput
from path_tracer.lambda_renderer import LambdaRenderer

调用形式	作用
LambdaRenderer(render_scene, env_index, device_id=0)	创建指定环境和 GPU 编号的渲染器
set_render_config(config)	应用渲染配置
update_scene(render_scene, light_indices)	更新场景和灯光，不接收相机索引
set_camera_index(camera_index)	选择本次渲染使用的传感器相机
render()	执行渲染，返回以输出通道名为键的字典

env_index 是场景环境索引，device_id 是 GPU 编号，二者不是相机索引。渲染设备应与模型使用的后端和设备匹配。

4.3 渲染配置与输出

下表列的是常用字段和示例配置值，不是全部字段的默认值。外部 path-tracer 的默认值和可用字段取决于安装版本。

字段	示例值	说明
enable_path_tracing	True	启用路径追踪
width、height	640、480	输出分辨率
spp	32	每像素采样数
max_bounces	6	路径最大反弹深度
output_mask	RenderOutput.COLOR	选择需要返回的输出通道
use_env_light	True	环境光开关
environment_light_mode	EnvironmentLightMode.DOME	使用场景 Dome 环境；也可选择BUILTIN
enable_denoising	False	ReLAX 降噪开关
enable_taa	False	TAA 开关
taa_max_accumulated_frames	6	TAA 历史累积长度
enable_oidn_denoising	True	OIDN 降噪开关，需要渲染器包含对应支持
ssaa	1	超采样倍率，需安装版本支持

新版时序处理使用 enable_taa；不应继续用旧的 use_temp_denoiser 字段说明如何控制 TAA。向普通配置对象赋一个属性成功，并不能证明渲染器支持该字段。

RenderOutput 可以组合选择通道：

标志	返回字典的键	数据说明
RenderOutput.COLOR	"color"	彩色图像，当前接口测试使用(height, width, 3)
RenderOutput.DEPTH	"depth"	深度数组，形状为(height, width)
RenderOutput.SEGMENTATION	"segmentation"	分割标识数组，当前接口测试使用(height, width, 2)

例如 RenderOutput.COLOR | RenderOutput.DEPTH 请求彩色和深度。只读取已启用的返回键，不要将整个返回字典传给图像保存函数。

4.4 最小渲染调用

以下片段要求 scene 已完成 finalize(device="musa:0", env_num=1)，包含可用相机，并且尚未关闭：

from path_tracer.config import RenderConfig, RenderOutput
from path_tracer.lambda_renderer import LambdaRenderer

renderer = LambdaRenderer(scene.get_render_scene(), 0, device_id=0)
config = RenderConfig()
config.enable_path_tracing = True
config.width = 640
config.height = 480
config.spp = 32
config.output_mask = RenderOutput.COLOR
renderer.set_render_config(config)

renderer.update_scene(scene.get_render_scene(), scene.get_light_list())
renderer.set_camera_index(0)
outputs = renderer.render()
image = outputs["color"]

物理推进后先确保渲染状态已同步，再更新渲染器。多相机输出时，同一物理时刻更新一次场景，然后遍历相机索引，逐个选择相机并渲染；不要为不同相机分别推进物理时间。

5. 单求解器与耦合求解器

5.1 统一接入方式

求解器构造函数接收已经完成 finalize() 的模型，返回求解器对象。用户通常通过 Scene 驱动以下生命周期，不需要重复手动调用 initialize()：

求解器方法	通常由谁调用	用途
initialize(sim_data)	scene.add_solver(solver)	初始化运行时状态与适配器
upload_control(sim_data)	scene.upload_control()	上传控制目标，具体行为由求解器决定
step(sim_data, dt)	scene.step(dt)	推进物理状态
close()	场景关闭或移除求解器时	执行该求解器提供的清理逻辑

最小接入片段，要求 scene 已包含匹配的刚体模型并完成初始化：

from lambdasim.solvers.solver_mujoco import SolverMuJoCoMusa

solver = SolverMuJoCoMusa(scene.get_model(), device="musa:0", env_num=1)
scene.add_solver(solver)
scene.upload_control()
scene.step(1.0 / 300.0)

5.2 SolverMuJoCoMusa

导入路径：

from lambdasim.solvers.solver_mujoco import SolverMuJoCoMusa

签名摘要：

SolverMuJoCoMusa(
    model, *, device="musa:0", env_num=None,
    nconmax=None, njmax=None, iterations=100, ls_iterations=50,
    ccd_iterations=35, solver="newton", integrator="implicitfast",
    cone="pyramidal", disable_contacts=False, ...
)

参数	默认值	说明
model	必填	完成finalize() 的场景模型
device	"musa:0"	求解设备
env_num	None	未指定时从模型获取环境数量
nconmax、njmax	None	接触和约束容量配置；未指定时由转换与后端处理
iterations、ls_iterations	100、50	主迭代和线搜索迭代参数
ccd_iterations	35	CCD 迭代参数
solver、integrator、cone	"newton"、"implicitfast"、"pyramidal"	MuJoCo 求解配置
disable_contacts	False	是否禁用接触
use_musa_graph	False	是否启用对应的图执行路径
collision_filter_mode	"legacy"	可选legacy 或 exact

该类用于刚体和关节机器人。关节控制模式、驱动增益及目标数据必须在正确阶段配置，构造求解器本身不会生成动作。脚本显式传入的迭代数可能不同于上述类默认值。

5.3 SolverVeraFiber

导入路径：

from lambdasim.solvers.solver_verafiber import SolverVeraFiber

签名摘要：

SolverVeraFiber(
    model, *, device="musa:0", env_num=1, env_index=0,
    core="xpbd", constraint_iterations=20, collision_passes=4,
    ipc_abd_collider_mode="control", collider_labels=None,
    fixed_collider_labels=None, ...
)

参数	默认值	说明
env_num、env_index	1、0	当前只支持这组单环境配置
core	"xpbd"	可选xpbd 或 ipc；快速开始示例显式选择 ipc
constraint_iterations	20	约束迭代数
collision_passes	4	碰撞处理轮数
collider_labels	None	模型中真实且唯一的形状标签序列
ipc_abd_collider_mode	"control"	IPC ABD 碰撞体模式，可选control 或 fixed
fixed_collider_labels	None	在control 模式下另行指定固定碰撞形状
enable_self_collision	True	布料自碰撞开关

场景需准备匹配的粒子拓扑、属性和约束。IPC 模式必须提供碰撞体对象或标签，不能只设置 core="ipc" 而不提供碰撞体配置。

静态盒子示例使用 ipc_abd_collider_mode="fixed" 和 collider_labels=("vera_box_collider",)，该标签对应 body=-1 的静态形状。fixed_collider_labels 不是该参数组合的替代写法，它要求 ipc_abd_collider_mode="control"。

collider_labels 不接受单个字符串，应该传列表或元组。动态碰撞体需要通过耦合求解器推进；单独调用本类的 step() 会拒绝相应动态碰撞体场景。当前 upload_control() 不执行操作。

5.4 SolverMuJoCoToVeraFiberOneWay

导入路径：

from lambdasim.solvers.solver_mujoco_verafiber_oneway import (
    SolverMuJoCoToVeraFiberOneWay,
)

签名摘要：

SolverMuJoCoToVeraFiberOneWay(
    model, *, device="musa:0", env_num=1, verafiber_gravity,
    nconmax=256, njmax=512, iterations=50, ls_iterations=20,
    mujoco_substeps=1, verafiber_substeps=1,
    verafiber_core="ipc", collider_labels=None, ...
)

参数	默认值	说明
model	必填	同时包含匹配刚体和布料数据的模型
verafiber_gravity	必填	布料侧重力，必须是ek.vec3，例如 ek.vec3(0, 0, -9.81)
env_num	1	受 VeraFiber 限制，当前使用单环境
mujoco_substeps、verafiber_substeps	1、1	两侧子步数，必须为正整数
verafiber_core	"ipc"	内部 VeraFiber 使用的求解核心
collider_labels	None	从模型中选择参与传递的碰撞形状
nconmax、njmax	256、512	传给内部 MuJoCo 的容量配置
iterations、ls_iterations	50、20	传给内部 MuJoCo 的迭代参数

耦合类与独立 SolverMuJoCoMusa 的参数默认值并不完全相同，不应混用两张参数表。

注册时只调用一次 scene.add_solver(coupled_solver)，不要再单独注册它内部的两个求解器。每次推进先计算 MuJoCo 刚体状态，再同步 VeraFiber 碰撞体状态或目标，最后推进布料。

两侧子步分别覆盖同一段 dt：子步时长为 dt / mujoco_substeps 和 dt / verafiber_substeps，不能相加解释为更长的仿真时间。upload_control() 转发给 MuJoCo。

该类是 MuJoCo → VeraFiber 单向耦合。当前不将布料接触反作用力回传到 MuJoCo，不能据此期待双向力反馈。

6. Builder、几何与 USD 工具

6.1 Builder

from lambdasim.scene.builder import Builder

通过 Scene 使用时，通常操作 scene.builder 并最终调用 scene.finalize()。直接使用独立 Builder 属于较底层的构建方式。

接口摘要	返回值	说明
Builder(up_axis=Axis.Z, gravity=-9.81)	Builder	创建构建器
set_env_num(num_envs)	None	设置环境数量
add_usd(source, *, namespace="rigid", rigid_read_only=True, ...)	导入结果字典	底层 USD 导入；只读参数默认是True
add_body(xform=None, armature=None, com=None, inertia=None, mass=0.0, label=None, ...)	body 索引int	添加独立刚体
add_link(xform=None, armature=None, com=None, inertia=None, mass=0.0, label=None, ...)	body 索引int	添加关节结构中的 link
add_joint(joint_type, parent, child, linear_axes=None, angular_axes=None, ...)	关节索引int	添加通用关节
add_articulation(joints, label=None, custom_attributes=None)	None	将给定连续关节索引组织为 articulation
add_shape_plane(plane=(0, 0, 1, 0), xform=None, width=10.0, length=10.0, body=-1, ...)	shape 索引int	添加平面
add_shape_sphere(body, xform=None, radius=1.0, cfg=None, as_site=False, ...)	shape 索引int	添加球体
add_shape_box(body, xform=None, hx=0.5, hy=0.5, hz=0.5, ...)	shape 索引int	添加盒体，尺寸参数为半尺寸
add_shape_mesh(body, xform=None, mesh=None, scale=None, cfg=None, ...)	shape 索引int	添加网格形状
finalize(device, env_num, primvar_map)	(Model, SimData)	不负责构建完整RenderScene，与 Scene.finalize() 不同

body=-1 的形状连接到世界。物理参数、碰撞、驱动和自定义属性的完整选项以 src/lambdasim/scene/builder.py 为准，不把示例脚本中的配置值当作 API 默认值。

6.2 几何接口

from lambdasim.geometry import GeoType, Heightfield, Mesh

GeoType 常用成员包括 PLANE、SPHERE、CAPSULE、ELLIPSOID、CYLINDER、CONE、BOX、MESH、CONVEX_MESH 和 HFIELD。

接口摘要	返回值	说明
Mesh(vertices, indices, normals=None, uvs=None, compute_inertia=True, is_solid=True, ...)	Mesh	从顶点与索引创建网格，可携带材质信息
Mesh.create_sphere(radius=1.0, *, num_latitudes=32, num_longitudes=32, ...)	Mesh	创建球体网格
Mesh.create_box(hx, hy=None, hz=None, *, ...)	Mesh	根据半尺寸创建盒体网格
Mesh.create_plane(width, length, *, ...)	Mesh	创建平面网格
mesh.build_sdf(*, narrow_band_range=None, target_voxel_size=None, max_resolution=None, margin=None, thickness=0.0, scale=None)	SDF	构建并附加距离场
Heightfield(data, nrow, ncol, hx=1.0, hy=1.0, min_z=None, max_z=None)	Heightfield	创建二维高程网格

6.3 USD 读取接口

from lambdasim.usd import (
    get_attribute,
    get_mesh,
    get_scale,
    get_transform,
    has_attribute,
)

接口摘要	返回值	说明
get_transform(prim, local=True, xform_cache=None, time_code=None)	ek.transform	读取平移和旋转
get_scale(prim, local=True, xform_cache=None, time_code=None)	ek.vec3	读取缩放
get_mesh(prim, load_normals=False, load_uvs=False, time_code=None, ..., return_uv_indices=False)	Mesh	读取 USD Mesh 并处理拓扑
get_mesh(..., return_uv_indices=True)	(Mesh, uv_indices)	同时返回 UV 索引，UV 索引可能为None
get_attribute(prim, name, default=None, time_code=None)	属性值或默认值	读取指定属性
has_attribute(prim, name)	bool	判断属性是否存在且有值

这些工具接收已有 USD Prim，不替代场景级导入。time_code 通常为 Usd.TimeCode；读取动画值时应与目标采样时间一致。

7. 命令行入口

7.1 主渲染入口

安装后的 lambdasim 命令对应 lambdasim.lambdasim_main:main。也可以像快速开始一样，在仓库根目录运行：

python src/lambdasim/lambdasim_main.py \
  tests/assets/shaderball.usda \
  --camera-indices 0 \
  --render-outputs color \
  --width 640 --height 480 --spp 32 \
  --device musa:0 \
  --output-dir outputs/api_reference/static

参数	默认行为或默认值	说明
usd_path	必填位置参数	输入 USD 文件，不使用--usd-path
--device	None，由设备解析逻辑选择	建议显式指定目标设备
--env-num	1	场景环境数量；该入口创建渲染器时选择环境索引0
--camera-indices	所有传感器相机	支持空格或逗号分隔索引
--camera-index	None	已弃用的单相机别名，不能与--camera-indices 同时使用
--render-outputs、--outputs	color depth segmentation	选择输出通道
--light-indices	场景灯光索引	指定灯光列表
--width、--height、--spp	640、480、128	分辨率与采样数
--max-bounces	6	最大反弹深度
--environment-light-mode	dome	dome 或 builtin
--output-dir	仓库根目录下的outputs/<usd_stem>/	保存输出
--output-name	<usd_stem>.png	静态预览文件名，不改变相机与通道分组目录
--sequence	关闭	按 USD 时间码生成序列
--frame-start、--frame-end	使用 USD 起止时间码	左闭右开，结束时间码不包含在内
--frame-step	1	正整数步长
--video	关闭	要求启用--sequence，为各相机各通道生成视频
--dump-musv	关闭	导出 MUSV 场景或序列

主入口输出按相机和通道分目录保存。例如上面的静态命令生成：

outputs/api_reference/static/
`-- camera_000/
    `-- color/
        `-- shaderball.png

多通道输出时，color/、depth/ 和 segmentation/ 分别存放各自结果。深度和分割除 PNG 预览外，还保存同名 .npy 原始数据；不能用预览图替代原始深度或分割标识。

序列文件名为 frame_0000.png 等，位于对应通道目录；启用视频时，各通道目录下生成 <usd_stem>.mp4。该入口当前固定使用 24 fps，不会根据 USD 时间码速率或 frame_step 自动调整视频帧率。其输出规则不同于第 8 节的 data_synth 辅助接口。

7.2 降噪与抗锯齿参数

参数	作用
--denoise	启用 ReLAX 路径追踪降噪
--oidn-denoise	启用非时序 CPU OIDN 降噪
--taa	启用 TAA，可独立于--denoise 请求
--taa-max-accumulated-frames	TAA 历史长度，默认6，范围 1～255
--ssaa [SCALE]	默认倍率1；只传开关时使用 2
--temp-denoise	旧版兼容参数；新版本可转换为 TAA 请求
--disable-path-tracing	使用光栅模式而不是路径追踪

降噪和 TAA 要求路径追踪及 color 输出。--temp-denoise 还要求 --denoise，且不能与 --oidn-denoise 同用。主入口会检查安装版本是否声明相关字段，不支持的显式请求可能被拒绝；应安装与当前 LambdaSim 匹配的渲染器。

8. 辅助数据处理接口

这两个接口仍然存在，可用于只生成彩色图像或处理已有帧序列。它们不是主渲染入口的同名包装，返回值和目录约定需要分别使用。

8.1 render_usd_camera_images()

from lambdasim.data_synth import render_usd_camera_images

签名：

render_usd_camera_images(
    usd_path, output_dir, camera_indices, width, height, *,
    spp=128, device=None, gpu_id=None,
    frame_start=None, frame_end=None, frame_step=None
) -> list[Path]

参数	默认值	说明
usd_path、output_dir	必填	USD 文件和图像输出目录
camera_indices	必填	从0 开始的相机索引序列，不能重复或为负
width、height	必填	正整数分辨率
spp	128	正整数采样数
device	None	设备选择；是否可运行取决于实际渲染后端
gpu_id	None	当前设备解析逻辑将其解释为musa:<gpu_id>，不能与 device 冲突
frame_start、frame_end	None	请求序列时，可从 USD 时间码补齐未提供的端点
frame_step	None	请求序列后默认按1 取帧；显式值必须为正

函数会自行创建场景、完成初始化并渲染彩色图像，不复用调用方已有的 Scene。USD 必须包含有效传感器相机和灯光；该接口会拒绝无灯光的输入。

返回所有已生成彩色图像的 Path 列表：

静态图像：<output_dir>/camera_000.png
图像序列：<output_dir>/camera_000/frame_0000.png

三个帧参数全部省略时输出静态图像；只要提供其中一个，就进入序列模式。范围遵循 range(frame_start, frame_end, frame_step)，总图像数为选中时间码数量乘以相机数量。

8.2 stitch_data_synth_sequence()

from lambdasim.data_synth_stitch import stitch_data_synth_sequence

签名：

stitch_data_synth_sequence(
    input_dir, output_dir, *,
    export_video=False, video_path=None
) -> list[Path]

参数	默认值	说明
input_dir	必填	包含camera_<index>/frame_<index>.png 的目录
output_dir	必填	拼接帧保存目录
export_video	False	是否额外编码 MP4
video_path	None	指定后即启用视频导出；启用导出但未指定路径时使用<output_dir>/stitched.mp4

返回拼接帧的 Path 列表，不包含视频路径。所有相机必须包含相同帧编号，同一帧的图像形状必须一致，包括宽、高和通道数。相机按编号排序后拼成网格。

视频使用固定 24 fps，没有 fps 参数。主渲染入口的帧位于 camera_<index>/<channel>/，不能未经整理就直接作为这个函数的输入；静态 camera_000.png 也不是它所需的帧序列结构。

8.3 辅助命令

命令	对应接口
lambdasim_data_synth	render_usd_camera_images()
lambdasim_data_synth_stitch	stitch_data_synth_sequence()

主渲染、单求解器、耦合求解器及机器人任务的完整用法见快速开始。术语与排障说明分别见术语表和常见问题。