RealityKit：解决Entity在不规则表面移动抖动、丢失及NaN错误问题

核心问题分析 #

控制台输出的Call to RETransformComponentSetLocalSRT contains NaN. Skipping.错误，本质是射线检测返回的变换数据（位置、旋转、缩放）出现非数值（NaN），导致实体的Transform组件无法正常更新，进而引发抖动、位置偏移甚至被甩出屏幕的问题。这种情况通常出现在不规则表面的边缘或法线突变区域，射线检测无法稳定获取有效表面信息。

具体修复方案 #

1. 过滤无效射线检测结果 #

处理CollisionCastHit时，增加对结果有效性的判断，过滤法线异常、位置数据无效的情况：

func updateEntityPosition(with hit: CollisionCastHit?) {
    guard let hit = hit else { return }
    // 校验位置和法线是否为有效数值
    guard !hit.position.isNaN && !hit.normal.isNaN else {
        print("无效命中数据，跳过更新")
        return
    }
    // 校验法线长度是否接近1，避免异常法线
    guard hit.normal.lengthSquared > 0.9 else {
        print("法线向量异常，跳过更新")
        return
    }
    // 更新实体位置与旋转
    let targetTransform = Transform(matrix: hit.transform)
    yourModelEntity.transform = targetTransform
}

2. 增加位置平滑过渡 #

不直接将实体transform设置为检测结果，通过插值实现平滑过渡，避免位置突变：

var previousValidTransform: Transform?

func updateEntityPosition(with hit: CollisionCastHit?) {
    guard let hit = hit, !hit.position.isNaN, !hit.normal.isNaN else {
        // 无有效结果时，沿用上次有效位置
        if let prevTransform = previousValidTransform {
            yourModelEntity.transform = prevTransform
        }
        return
    }
    
    let targetTransform = Transform(matrix: hit.transform)
    // 线性插值平滑过渡，0.2可根据需求调整平滑度
    yourModelEntity.transform = yourModelEntity.transform.interpolated(to: targetTransform, fraction: 0.2)
    previousValidTransform = targetTransform
}

3. 限制射线检测范围与目标 #

• 缩小射线检测距离，避免检测过远或无关表面；
• 通过CollisionFilter指定仅检测特定类型表面（如桌面、墙面、地面对应的碰撞层），减少无关结果干扰：

let raycastQuery = CollisionCastQueryType.face
// 自定义碰撞组和掩码，仅检测目标表面
let collisionFilter = CollisionFilter(group: .init(rawValue: 1 << 0), mask: .init(rawValue: 1 << 1))

let hits = arView.scene.performCollisionCast(
    origin: cameraTransform.translation,
    direction: cameraTransform.forward,
    length: 5.0, // 限制检测距离
    query: raycastQuery,
    filter: collisionFilter
)

4. 优化表面切换时的旋转适配 #

切换不同表面时，手动修正旋转角度，避免法线突变导致的旋转异常：

func adjustRotationForSurface(_ normal: SIMD3<Float>) {
    let upVector = SIMD3<Float>(0, 1, 0)
    let dotProduct = dot(normal, upVector)
    var targetRotation: simd_quatf
    
    // 根据法线与世界上方向的夹角判断表面类型
    if abs(dotProduct) > 0.8 {
        // 地面/桌面（接近水平）
        targetRotation = simd_quatf(angle: 0, axis: upVector)
    } else if abs(dotProduct) < 0.2 {
        // 墙面（接近垂直）
        targetRotation = simd_quatf(angle: .pi/2, axis: SIMD3<Float>(1, 0, 0))
    } else {
        // 倾斜表面，用法线计算旋转
        targetRotation = simd_quatf(from: upVector, to: normal)
    }
    
    yourModelEntity.transform.rotation = targetRotation
}

额外调试建议 #

• 控制台打印每次射线检测的hit.position、hit.normal和hit.transform数据，观察不规则表面时参数变化，定位NaN来源；
• 添加射线可视化调试，直观查看检测范围和命中位置：

// 绘制调试射线
let rayEntity = ModelEntity(mesh: .generateLine(from: cameraTransform.translation, to: cameraTransform.translation + cameraTransform.forward * 5))
arView.scene.addAnchor(rayEntity)
// 注意下次更新前移除旧调试实体

内容的提问来源于stack exchange，提问作者Chinchan Zu