企业官网建设流程全解析

• 物理引擎
• 游戏开发
• 机器人

这篇指南以 Rapier 仓库中 Python 绑定几何 API 文档 为骨架，系统讲解rapier3dPython 绑定中几何模块的全部类型：碰撞体（Collider）及其构造器、完整形状族（SharedShape与各类具体形状）、包围体（AABB / BoundingSphere）、网格工具（MeshConverter/TriMeshFlags）、交互过滤（Group/InteractionGroups/ActiveEvents），以及接触事件与流形、Broad/Narrow 相位类型。读完本文，你将掌握如何用 Python 为刚体装配任意形状的碰撞体、配置材质与交互过滤规则、读取接触与碰撞事件，并理解这些 API 在底层 Rust 引擎（geometry.rs）中的实现脉络，可直接用于游戏、机器人仿真与数字孪生场景。

1. 几何模块概览

Rapier 的 Python 绑定只面向 3D，模块名为rapier3d。几何模块承载了物理世界中"看得见、碰得着"的那部分数据：碰撞体（Collider）定义了物体占据的空间范围，形状（Shape）定义了碰撞体的几何细节，碰撞管线（Broad/Narrow Phase）则负责发现并求解这些几何之间的相互作用。

从仓库结构看，Python 绑定分为两层：

• 类型声明层：bindings/python/rapier-py-3d/python/rapier3d/_rapier3d.pyi是 pyi 类型存根，完整声明了所有类的属性与方法签名（本文所述 API 签名均以该文件为准）；
• Rust 实现层：bindings/python/rapier-py-3d/src/geometry.rs（共 5130 行）通过 pyo3 将 Rapier 核心几何类型逐一导出，形状构造、质量属性计算、碰撞组过滤等逻辑都在这里与 C 引擎联动。

配套测试位于bindings/python/tests/test_geometry.py，覆盖了球、长方体、胶囊、圆柱、圆锥、网格、凸包、复合形状、碰撞组、事件与序列化等路径，是验证本文示例正确性的直接依据。

2. Colliders：碰撞体体系

Collider 是"刚体 + 形状 + 材质 + 过滤规则"的组合体。Rapier 将其拆为三类核心类型：

2.1 ColliderBuilder：从形状静态方法到链式配置

最常用的入口是Collider的系列静态方法，它们直接返回ColliderBuilder。测试 test_geometry.py 展示了典型用法：

# 球体，默认密度 1.0 coll = ns.Collider.ball(0.5).build() # 球体 + 材质 + 传感器标记 coll = ns.Collider.ball(0.7, density=2.0, friction=0.3, sensor=True).build() # 长方体：参数为三个半轴长 coll = ns.Collider.cuboid(1.0, 2.0, 3.0, density=4.0, sensor=True).build() # 胶囊：半高 + 半径；圆柱/圆锥：半高 + 半径 coll = ns.Collider.capsule(0.5, 0.2).build() coll = ns.Collider.cylinder(0.5, 0.3).build() coll = ns.Collider.cone(0.5, 0.3).build()

ColliderBuilder的全部链式方法（见 pyi 存根）包括：

2.2 Collider：只读快照与常用属性

Collider实例的属性覆盖了构造器配置的全部结果（pyi 存根）：position/translation/rotation（相对父刚体的位姿）、shape（SharedShape）、density/mass/mass_properties、friction/restitution及其combine_rule、is_sensor、is_enabled、active_events/active_hooks/active_collision_types、collision_groups/solver_groups、contact_skin、contact_force_event_threshold、user_data。

另有一组"相对父刚体"的派生属性：position_wrt_parent/translation_wrt_parent/rotation_wrt_parent（可读写），以及parent（返回所属RigidBodyHandle，无父体时为None）。ColliderParent（pyi 存根）正是"父刚体句柄 + 相对位姿"这一组合的数据结构；ColliderPosition（pyi 存根）则只封装位姿本身。

材质参数汇总在ColliderMaterial结构（pyi 存根）中：friction、restitution与两个CoefficientCombineRule。而ColliderFlags（pyi 存根）则是collision_groups、solver_groups、active_hooks、active_events、active_collision_types的聚合容器。

2.3 ColliderType / ColliderEnabled / ColliderMassProps

• ColliderType（pyi 存根）只有两个值：SOLID与SENSOR，is_sensor属性即源于此；
• ColliderEnabled（pyi 存根）三态：ENABLED、DISABLED_BY_PARENT（父刚体被禁用）、DISABLED；
• ColliderMassProps（pyi 存根）通过三个静态工厂Density(d)/Mass(m)/MassProperties(mp)提供质量属性来源，底层对应 Rust 的ColliderMassProps::Density/Mass/MassProperties枚举变体（geometry.rs#L5041-L5066）。

2.4 ColliderSet：插入、查询与移除

colliders = ns.ColliderSet() # 插入独立碰撞体（无父刚体），返回句柄 h1 = colliders.insert(ns.Collider.ball(0.5).build()) h2 = colliders.insert(ns.Collider.cuboid(1, 1, 1).build()) # 查询 c = colliders.get(h1) # -> Collider | None c = colliders[h1] # 下标访问，等价 get h1 in colliders # 成员判断 for handle, coll in colliders: # 迭代所有 (句柄, 碰撞体) ... # 移除：需要关联的 IslandManager 与 RigidBodySet（wake_up=True 唤醒受影响的刚体） coll = colliders.remove(h1, islands, bodies)

关键方法与签名（pyi 存根）：

• insert(builder)：插入普通碰撞体；insert_with_parent(builder, parent, bodies)：插入并绑定父刚体；insert_deformable(builder, binding, parent, bodies, soft_bodies)：插入绑定软体网格的可变形碰撞体；
• remove(handle, islands, bodies, wake_up=True, soft_bodies=None, *, wake_parent=None)：移除并返回被移除的 Collider，需同时传入孤岛管理器与刚体集以维护内部一致性；
• clear()/is_empty()/handles()/__len__()：容器管理；to_bytes()/from_bytes(blob)：整体序列化。

3. Shapes：形状族与 SharedShape

形状是几何模块的核心数据。SharedShape是"共享形状"的统一句柄，任何具体形状都可以包装成它；反过来，任意SharedShape都可以用as_ball()/as_cuboid()/as_trimesh()等一族方法做向下转型（见 pyi 存根），拿不到对应类型时返回None。

3.1 ShapeType 枚举

ShapeType（pyi 存根）列出了引擎支持的全部形状类别：BALL、CUBOID、CAPSULE、SEGMENT、TRIANGLE、VOXELS、TRIMESH、POLYLINE、HALFSPACE、HEIGHTFIELD、COMPOUND、CONVEX_POLYGON、CONVEX_POLYHEDRON、CYLINDER、CONE，以及带圆角（round）的系列ROUND_CUBOID/ROUND_TRIANGLE/ROUND_CYLINDER/ROUND_CONE/ROUND_CONVEX_POLYHEDRON/ROUND_CONVEX_POLYGON和CUSTOM。Rust 侧通过模式匹配把内部形状枚举映射到这些值（geometry.rs#L298 附近），所以SharedShape.shape_type总能给出精确类别。

3.2 SharedShape 静态构造器大全

SharedShape提供了一组静态构造器（pyi 存根）：

基础形状：

SharedShape.ball(radius) SharedShape.cuboid(hx, hy, hz) # 半轴长 SharedShape.capsule(a, b, radius) # 由两端点 + 半径定义 SharedShape.capsule_x/y/z(half_height, radius) # 沿轴对齐的快捷构造 SharedShape.cylinder(half_height, radius) SharedShape.cone(half_height, radius) SharedShape.triangle(a, b, c) SharedShape.halfspace(outward_normal) # 无限半空间，常用作地面 SharedShape.segment(a, b) SharedShape.polyline(vertices, indices=None)

圆角变体（border radius 提升求解稳定性）：

SharedShape.round_cuboid(hx, hy, hz, border_radius) SharedShape.round_cylinder(half_height, radius, border_radius) SharedShape.round_cone(half_height, radius, border_radius) SharedShape.round_triangle(a, b, c, border_radius) SharedShape.round_convex_hull(points, border_radius) SharedShape.round_convex_mesh(vertices, indices, border_radius)

网格与凸包：

SharedShape.trimesh(vertices, indices, flags=None) # 三角形网格，flags 见 TriMeshFlags SharedShape.convex_hull(points) # 点云凸包（自动提取凸壳） SharedShape.convex_polyhedron(points) # 显式凸多面体 SharedShape.convex_decomposition(vertices, indices) # VHACD 凸分解，适合任意凹网格 SharedShape.convex_mesh(vertices, indices) # 按给定索引构建凸网格

体素（Voxels）：

SharedShape.voxels(voxel_size, grid_coords) # 网格坐标 + 单元尺寸 SharedShape.voxels_from_points(voxel_size, points) # 由点云自动栅格化 SharedShape.voxelized_mesh(vertices, indices, voxel_size, fill_mode=None)

地形与复合体：

SharedShape.heightfield(heights, scale) # 高度场，见 3.5 SharedShape.compound(parts) # [(IsometryLike, SharedShape), ...]

通用能力：

shape.compute_aabb(pose) -> Aabb # 在给定位姿下计算 AABB shape.compute_bounding_sphere(pose) -> BoundingSphere shape.compute_mass_properties(density) -> MassProperties # 依据形状体积 + 密度计算质量属性 shape.shape_type -> ShapeType shape.to_bytes() / SharedShape.from_bytes(blob) # 序列化

其中compute_mass_properties在 Rust 侧直接委托给引擎的mass_properties(density)（geometry.rs#L2380-L2385），因此 Collider 的密度-质量换算与SharedShape完全一致。

3.3 具体形状类速查

所有具体形状均位于 pyi 存根。to_trimesh()系列方法返回(N,3)顶点数组与索引数组，便于可视化或导出。

3.4 TriMesh 与 TriMeshFlags

TriMesh直接暴露vertices、indices、flags与三角形/顶点计数。构建网格时可传入TriMeshFlags（pyi 存根）进行预处理，常用标志：

构造示例（测试 test_geometry.py）：

verts = np.array([...], dtype=np.float32) # (N, 3) idx = np.array([...], dtype=np.int32) # (M, 3) coll = ns.Collider.trimesh(verts, idx).build() # 带标志的 SharedShape 版本 s = ns.SharedShape.trimesh(verts, idx, ns.TriMeshFlags.FIX_INTERNAL_EDGES)

3.5 HeightField：地形高度场

HeightField由heights（(nrows, ncols)的高度网格，float32/float64 ndarray）与scale（Vec3，水平与垂直缩放）定义，测试中通过SharedShape.heightfield(heights, scale)构造。它适合表达大地形，Rust 侧导出时要求高度数组为二维规则网格（geometry.rs#L143 附近有对(nrows, ncols)的提取逻辑）。to_trimesh()可将其转化为网格用于调试渲染。

3.6 Voxels 与 FillMode

体素形状把三维空间离散为规则单元，适合不可形变的"像素化"几何（如 Minecraft 风格场景、程序化地形）。Voxels类暴露voxel_size、centers（所有填充体素的中心）、num_voxels()（填充体素数）与to_trimesh()（填充体素边界网格），其 Rust 实现见 geometry.rs#L2025-L2061。

voxelized_mesh依赖FillMode（pyi 存根）决定哪些体素被填充：

• FillMode.SURFACE_ONLY：只填充与网格表面相交的体素（中空外壳）；
• FillMode.flood_fill(detect_cavities=False)：泛洪填充实体内部，detect_cavities=True时保留封闭空腔。

Rust 侧对此有明确语义注释（geometry.rs#L2072-L2074）。另外，SharedShape.voxels会对voxel_size做合法性校验，要求其"正且有限"，否则返回运行时错误（geometry.rs#L132-L140）。

4. Bounding Volumes：包围体

Aabb与BoundingSphere是包围体查询的基础类型：

# Aabb：由最小/最大角点定义 aabb = ns.Aabb(mins=(0.0, 0.0, 0.0), maxs=(1.0, 1.0, 1.0)) aabb.mins # -> Point3 aabb.maxs # -> Point3 aabb.center # -> Point3 aabb.half_extents # -> Vec3 aabb.volume # -> float # BoundingSphere：球心 + 半径 sph = ns.BoundingSphere(center=(0.0, 0.0, 0.0), radius=1.0) sph.center; sph.radius

SharedShape.compute_aabb(pose)返回的就是Aabb（pyi 存根），可用于对任意形状做空间预查询；Collider.compute_aabb()则直接返回碰撞体当前位姿下的 AABB。

5. Mesh Utilities：网格转换工具

MeshConverter（pyi 存根）把任意三角形网格转换成更利于物理仿真的形状，提供五种策略常量与一个带标志的工厂方法：

conv = ns.MeshConverter.CONVEX_DECOMPOSITION shape, iso = conv.build(vertices, indices) # -> (SharedShape, Isometry3) coll = ns.Collider.converted_trimesh(vertices, indices, conv).build()

build()返回(SharedShape, Isometry3)，其中Isometry3是转换过程中计算出的居中校正位姿（如 OBB 的中心与旋转），需要一并用于ColliderBuilder.position()，保证网格在场景中的位置不漂移。

6. Interaction & Filtering：交互过滤体系

Rapier 的碰撞过滤分两阶段：宽相位（broad phase）用collision_groups过滤候选对，求解器（solver）再用solver_groups过滤实际产生接触的对。

6.1 Group：32 位成员组

Group（pyi 存根）提供GROUP_0～GROUP_31共 32 个位、ALL、NONE，以及位运算支持：

g = ns.Group.GROUP_0 | ns.Group.GROUP_2 # 两个成员位 g.bits # 底层位掩码 g.contains(ns.Group.GROUP_2) # True ns.Group.from_bits(0b101) # 由整数重建

6.2 InteractionGroups：成员组 + 过滤组

InteractionGroups（pyi 存根）由三部分组成：

• memberships：本碰撞体所属的组（Group）；
• filter：本碰撞体愿意与哪些组交互（Group）；
• test_mode：InteractionTestMode.AND（成员组与过滤组都匹配才交互）或OR（任一匹配即可）。DEFAULT与ONLY_DYNAMIC是AND的兼容别名（pyi 存根）。

groups = ns.InteractionGroups( memberships=ns.Group.GROUP_0, filter=ns.Group.ALL, test_mode=ns.InteractionTestMode.AND, ) # 或链式： groups = ns.InteractionGroups.all().with_membership(ns.Group.GROUP_0).with_filter(ns.Group.GROUP_1) coll = ns.Collider.ball(0.5).collision_groups(groups).build()

to_bytes()/from_bytes(blob)支持跨进程/跨语言传递碰撞组配置。测试 test_geometry.py 演示了collision_groups在 Builder 中的应用。

6.3 ActiveEvents / ActiveHooks / ActiveCollisionTypes

这三个位标志型类型控制"何时通知、如何过滤"：

• ActiveEvents（pyi 存根）：COLLISION_EVENTS（开始/停止碰撞事件）、CONTACT_FORCE_EVENTS（接触力事件）、NONE；提供all_events()、empty()与位运算。测试 test_geometry.py 展示了active_events用法；
• ActiveHooks（pyi 存根）：FILTER_CONTACT_PAIR/FILTER_CONTACT_PAIRS（接触对过滤回调）、FILTER_INTERSECTION_PAIR（相交对过滤）、MODIFY_SOLVER_CONTACTS（修改求解接触点），对应引擎中的物理钩子（PhysicsHooks）；
• ActiveCollisionTypes（pyi 存根）：按刚体类型组合启用碰撞，如DYNAMIC_DYNAMIC、DYNAMIC_KINEMATIC、DYNAMIC_FIXED、KINEMATIC_KINEMATIC、KINEMATIC_FIXED、FIXED_FIXED；default_types()为默认组合，all()全开。

6.4 CollisionEventFlags

CollisionEventFlags（pyi 存根）标记事件附加信息：SENSOR（涉及传感器）、REMOVED（碰撞体被移除导致的终止事件）。

7. Contact Events & Manifolds：接触事件与流形

7.1 事件类

• CollisionEvent（pyi 存根）：字段started（是否开始接触）、collider1/collider2、flags；便捷属性stopped/sensor/removed；静态工厂STARTED(c1, c2, flags)/STOPPED(c1, c2, flags)。配合ActiveEvents.COLLISION_EVENTS使用，即"接触开始/停止"通知；
• ContactForceEvent（pyi 存根）：当接触力超过contact_force_event_threshold时派发，字段含total_force（Vec3）、total_force_magnitude、max_force_direction/max_force_magnitude（最大力方向与大小），用于力反馈、触觉等应用。

7.2 接触数据结构

• ContactPair（pyi 存根）：一对碰撞体之间的全部接触信息，collider1/collider2、manifolds（list[ContactManifold]）、has_any_active_contact、find_deepest_contact()（最深穿透点）、total_impulse()/total_impulse_magnitude()（累积冲量）；
• ContactManifold（pyi 存根）：一个法线方向上的接触点集合，含data（ContactManifoldData）、points（list[ContactData]）、local_n1/local_n2（双方局部法线）、subshape1/subshape2（复合形状中的子形状索引）；
• ContactManifoldData（pyi 存根）：rigid_body1/rigid_body2（句柄，可为 None）、normal、num_active_contacts、relative_dominance、user_data，以及solver_contacts（求解器接触点列表）与solver_contact_world_points(contact, bodies)（把求解接触点换算到世界坐标）；
• ContactData（pyi 存根）：单个接触点，local_p1/local_p2（双方局部坐标）、dist（穿透距离）、fid1/fid2（特征 ID）、impulse、tangent_impulse（切向冲量二元组）、contact_id；
• SolverContact（pyi 存根）：求解器视角的接触点，含point/point2、dist、tangent_velocity、contact_id、is_new；
• IntersectionPair（pyi 存根）：collider1/collider2/intersecting（布尔相交结果）；
• ColliderPair（pyi 存根）：无顺序敏感的一对碰撞体句柄，支持下标访问与len()；
• BroadPhasePairEvent（pyi 存根）：宽相位候选对事件，added(pair)/removed(pair)两个静态工厂，is_added/is_removed/removed_属性判断事件类型，用于观察宽相位对增删。

7.3 接触事件的接入方式

要接收这些事件，需要在 Collider 上启用对应ActiveEvents，并通过EventQueue（事件队列）与物理管线配合：COLLISION_EVENTS产生CollisionEvent，CONTACT_FORCE_EVENTS产生ContactForceEvent。详细的事件投递流程见 events_hooks 文档，几何侧的完整字段语义以本节的 pyi 存根为准。

8. Broad / Narrow Phase：宽相位与窄相位

碰撞检测被分为两个阶段，Python 绑定分别暴露了可独立操作的类型：

• BroadPhaseBvh（pyi 存根）：宽相位 BVH，负责快速找出可能相交的碰撞体对。构造默认实例或用optimized_for(strategy)指定优化策略；clear()/to_bytes()/from_bytes(blob)用于生命周期与序列化管理；
• BvhOptimizationStrategy（pyi 存根）：AUTO、NO_OPTIMIZATION、OPTIMIZE_FOR_INTERACTIONS、OPTIMIZE_FOR_SPATIAL_QUERIES、SUBTREE_OPTIMIZER、NONE，用于权衡"碰撞交互性能"与"空间查询性能"；
• NarrowPhase（pyi 存根）：窄相位，对候选对做精确几何求交并生成接触流形。常用查询：

np_ = ns.NarrowPhase() pair = np_.contact_pair(h1, h2) # 两碰撞体间的 ContactPair | None ok = np_.intersection_pair(h1, h2) # 是否相交 | None pairs = np_.contact_pairs() # 所有接触对 list[ContactPair] inters = np_.intersection_pairs() # 所有相交对 with_c = np_.contact_pairs_with(h1) # 与指定碰撞体接触的所有对

窄相位在PhysicsPipeline内部默认创建，NarrowPhase公开暴露的目的在于：自定义管线、调试接触生成，以及读取"上一步"的接触状态。两者都支持to_bytes()/from_bytes(blob)，可整体序列化保存。

9. 实战小结：组装一个完整的碰撞场景

把以上类型串起来，一个典型的几何装配流程如下（与World/RigidBodySet配合，见 world 文档）：

import rapier3d as ns import numpy as np # 1) 形状 ground = ns.SharedShape.cuboid(10.0, 0.5, 10.0) ball_shape = ns.SharedShape.ball(0.5) # 2) Collider（材质 + 过滤 + 事件） ground_collider = ( ns.Collider.cuboid(10.0, 0.5, 10.0, friction=0.8, restitution=0.0) .collision_groups(ns.InteractionGroups.all().with_membership(ns.Group.GROUP_0)) .build() ) ball_collider = ( ns.Collider.ball(0.5, density=2.0) .active_events(ns.ActiveEvents.CONTACT_FORCE_EVENTS) .contact_force_event_threshold(0.1) .solver_groups(ns.InteractionGroups.all()) .build() ) # 3) 包围体查询 aabb = ball_shape.compute_aabb(ns.Isometry3.identity()) # 4) 插入刚体（略，见 RigidBody API）

无论做碰撞检测还是力反馈，核心心智模型始终是：SharedShape描述"长什么样"，ColliderBuilder配置"怎么碰、和谁碰、要不要通知"，ColliderSet+NarrowPhase负责"在哪儿碰、碰多重"。其余类型（AABB、MeshConverter、InteractionGroups、ContactManifold家族）都是围绕这一主线提供查询、预处理与观测能力的配套工具。

• 物理引擎
• 游戏开发
• 机器人