表面与纹理#

**表面（surface）**描述实体渲染时的外观：颜色、光泽度、透明度和纹理贴图。每个实体最多可以有三份彼此独立的描述：

一个morph：几何体和初始位姿；
一个材质：物理行为（质量、刚度、摩擦）；
一个表面：视觉外观，也是本页的主题。

修改表面绝不会改变实体的运动或碰撞方式，只会改变渲染出的图像。如果省略表面，Genesis World 会使用 gs.surfaces.Default（一种 Disney 原理化 BSDF），并沿用资产文件中已定义的任何材质。

覆盖所有表面类型的可运行脚本是 examples/rendering/demo.py：

scene.add_entity(
    morph=gs.morphs.Mesh(file="meshes/sphere.obj", scale=0.5, pos=(0.0, -0.6, 0.0)),
    surface=gs.surfaces.Smooth(color=(0.6, 0.8, 1.0)),
)

选择表面#

每种表面都是基于物理的（PBR）材质，各类型之间的区别只在默认值。挑一个最接近你需求的类型，再覆盖单独的属性。

表面	说明	主要默认值
`gs.surfaces.Default`	Disney 原理化 BSDF；通用表面	`BSDF` 的别名
`gs.surfaces.Rough`	哑光塑料	`roughness=1.0`、`ior=1.5`
`gs.surfaces.Smooth`	亮面塑料	`roughness=0.1`、`ior=1.5`
`gs.surfaces.Reflective`	接近镜面的塑料	`roughness=0.01`、`ior=2.0`
`gs.surfaces.Metal`	带光谱色调的导体	`metal_type="iron"`、`roughness=0.1`
`gs.surfaces.Glass`	镜面反射与折射	`roughness=0.0`、`ior=1.5`
`gs.surfaces.Water`	针对水调校的玻璃	`ior=1.2`、`roughness=0.2`
`gs.surfaces.Emission`	发光；用作光源	—

Iron、Gold、Copper 和 Aluminium 是指定了对应 metal_type 的 Metal 快捷方式。metal_type 的完整取值集合为 "aluminium"、"gold"、"copper"、"brass"、"iron"、"titanium"、"vanadium" 和 "lithium"，每种都带有自己的折射率。

# both spheres are gold; the second spells out what the shortcut sets
scene.add_entity(morph=gold_sphere, surface=gs.surfaces.Gold())
scene.add_entity(morph=gold_sphere, surface=gs.surfaces.Metal(metal_type="gold"))

设置颜色和 PBR 属性#

每个 PBR 通道实质上都是一张纹理（见下文），但如果某个通道只存一个常量，就可以改用快捷参数，而不必传入纹理对象。常用的快捷参数有 color、roughness、opacity、emissive、metallic 和 ior：

surface = gs.surfaces.Default(
    color=(0.8, 0.2, 0.2),  # base (diffuse) color, RGB in [0, 1]
    roughness=0.4,          # 0 = mirror-smooth, 1 = fully matte
    metallic=0.0,           # 0 = dielectric, 1 = metal
)

快捷参数映射到通道的方式带来两个限制：

快捷参数和它对应的纹理不能同时设置：同时传入 color=... 与 diffuse_texture=... 会报错，因为纹理本身已经携带颜色。
快捷参数只对表面实际拥有的通道生效。metallic 在 Default/BSDF 上有意义；Metal、Glass 以及各种塑料会忽略它，因为它们的反射特性由其类型决定。

Genesis World 把颜色的第四个分量视为不透明度，因此 color=(r, g, b, a) 是让表面半透明的简洁写法：

# 50% transparent glossy plastic
gs.surfaces.Smooth(color=(1.0, 1.0, 1.0, 0.5))

纹理#

当某个属性在表面上各处不同时（木纹、喷绘标志、粗糙度贴图），应提供纹理而不是常量。纹理类位于 gs.textures 下：

gs.textures.ColorTexture(color=...)：单一均匀的颜色。等价于 color 快捷参数，在某个参数要求传入纹理对象时很有用。
gs.textures.ImageTexture(image_path=..., encoding=...)：按网格 UV 坐标采样的图像贴图。
gs.textures.BatchTexture：一叠纹理，每个环境一张，用于并行渲染。

把纹理赋给它所驱动的通道。基础色对应 diffuse_texture；数据贴图对应 roughness_texture、normal_texture、opacity_texture 等：

surface = gs.surfaces.Rough(
    diffuse_texture=gs.textures.ImageTexture(image_path="textures/checker.png"),
    roughness_texture=gs.textures.ImageTexture(image_path="rough.png", encoding="linear"),
    normal_texture=gs.textures.ImageTexture(image_path="normal.png", encoding="linear"),
)

Warning

凡是存储数据而非颜色的贴图（粗糙度、金属度、法线和透明度贴图），都要设置 encoding="linear"。默认的 encoding="srgb" 会施加 gamma 校正，这对彩色图像是正确的，但会破坏数据贴图。Genesis World 会把 .hdr 和 .exr 文件强制设为 linear。

Genesis World 先相对于你的工作目录解析图像路径，再相对于随包附带的资产目录（genesis/assets），因此 "textures/checker.png" 加载的是随库提供的棋盘格图像。加载的资产（例如 .glb 或带纹理的 .obj）会自带表面；只有当你想要覆盖它时，才需要向 add_entity 传入 surface。

为光线追踪场景打光#

在Nyx 光线追踪器中，灯光不是特殊对象：它们就是带有 Emission 表面的普通实体。环境贴图是把同样的思路用到背景上：一张包裹住场景的发光图像，为其中的一切提供光照。

下面这段代码摘自 examples/rendering/demo.py，它设置了一个 HDRI 风格的环境贴图和一盏面光源：

scene = gs.Scene(
    renderer=gs.renderers.RayTracer(
        env_surface=gs.surfaces.Emission(
            emissive_texture=gs.textures.ImageTexture(image_path="textures/indoor_bright.png"),
        ),
        env_radius=15.0,          # meters; the environment sphere's radius
        env_euler=(0, 0, 180),    # extrinsic x-y-z, degrees; rotates the map
        lights=[
            {"pos": (0.0, 0.0, 10.0), "radius": 3.0, "color": (15.0, 15.0, 15.0)},
        ],
    ),
)

Note

表面在交互式查看器的光栅化器和光线追踪器中都能渲染，但反射、折射、透射以及基于发光的照明只有光线追踪器才能完整呈现。选择与配置渲染器的方法见渲染。

可视化视觉网格之外的内容#

vis_mode 决定渲染器绘制实体的哪一套几何，与表面的材质无关。它对基于粒子的实体最为重要，这类实体的“形状”是点云而不是网格：

# draw a fluid entity as its raw particles
gs.surfaces.Rough(color=(0.6, 0.8, 1.0), vis_mode="particle")

# reconstruct a smooth surface mesh from those particles
gs.surfaces.Glass(color=(0.7, 0.85, 1.0, 0.7), vis_mode="recon")

可接受的取值为 "visual"、"collision"、"particle"、"sdf" 和 "recon"。用 "collision" 可以查看物理仿真实际看到的碰撞几何体。

泡沫与水花#

快速运动的粒子流体会夹带空气：破碎波峰上的白水、溅落时飞出的水花、被卷到水面以下的气泡。在光线追踪器中，Genesis World 把这些渲染为粒子流体周围的次级泡沫粒子。泡沫只是一种渲染效果，不会影响物理仿真，光栅化器也会忽略它。

在流体的表面上设置 generate_foam=True 即可启用，并通过 foam_options 对象调节外观：

scene.add_entity(
    material=gs.materials.SPH.Liquid(),
    morph=gs.morphs.Box(pos=(0.0, 0.0, 0.5), size=(0.4, 0.4, 0.4)),
    surface=gs.surfaces.Water(
        vis_mode="recon",  # foam sits on the reconstructed fluid surface
        generate_foam=True,
        foam_options=gs.options.FoamOptions(
            radius_scale=0.2,  # foam particle radius relative to a fluid particle
            k_foam=1000.0,  # foam particles generated per frame
            spray_decay=2.0,
            foam_decay=1.0,
            bubble_decay=5.0,
        ),
    ),
)

gs.options.FoamOptions 把效果拆成三个群体，每个群体有各自的消散速率（数值越大，该群体消失得越快）：

radius_scale： 泡沫粒子半径相对于流体粒子半径的比例。默认 0.2。
k_foam： 每帧生成的泡沫粒子数量。默认 1000.0。
spray_decay： 空中水花的消散速率。默认 2.0。
foam_decay： 浮于表面的泡沫的消散速率。默认 1.0。
bubble_decay： 水下气泡的消散速率。默认 5.0。
color： 泡沫粒子的 RGBA 色调。默认 (0.7, 0.7, 0.7, 0.7)。

另请参阅#

渲染：相机与渲染器的选择。
Nyx 渲染器：深入了解照片级真实感路径追踪。
USD 导入：加载自带表面的资产。