MapBox 3D Puck模型无法显示问题求助

问题描述 #

按官方文档配置MapBox 3D定位Puck，但模型始终无法显示：

• 已尝试更换.gltf、.glb、.usdz格式模型，文件导入正常且未触发fatalError，说明MapBox已成功加载模型
• 将puckType改为.puck2D()时，Puck可正常显示
• 调整modelScale、modelOpacity、orientation参数均无效果

相关代码：

class MapViewController: UIViewController {
    var mapView: MapView!
    private var cancelables = Set<AnyCancelable>()
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        let options = MapInitOptions()
        mapView = MapView(frame: view.bounds, mapInitOptions: options)
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(mapView)
        
        mapView.mapboxMap.onStyleLoaded.observeNext { _ in
            self.configureMapView()
        }.store(in: &cancelables)
                
        setupGestureRecognizers()
    }
    
    private func configureMapView() {
        // Fetch the asset
        guard let uri = Bundle.main.url(forResource: "truck", withExtension: "gltf") else {
            fatalError("Failed to locate glb model in asset catalog")
        }
        
        // Instantiate the model
        let myModel = Model(uri: uri, orientation: [0, 0, 180])
        
        let configuration = Puck3DConfiguration(
            model: myModel,
            modelScale: .constant([10, 10, 10])
        )
                
        mapView.location.options.puckType = .puck3D(configuration)
        mapView.location.options.puckBearing = .course
        mapView.location.options.puckBearingEnabled = true
        
        mapView.location.onLocationChange.observeNext { [weak mapView] newLocation in
            guard let location = newLocation.last, let mapView else { return }
            mapView.camera.ease(
                to: CameraOptions(
                    center: location.coordinate,
                    zoom: 15,
                    bearing: 0,
                    pitch: 55),
                duration: 1,
                curve: .linear,
                completion: nil
            )
        }.store(in: &cancelables)
    }
}

排查方案 #

• 调整模型位置偏移：多数3D模型的原点不在底部中心，会导致模型被埋在地图地面以下。尝试给Model添加Z轴偏移，将模型抬至地面之上：

  let myModel = Model(uri: uri, orientation: [0, 0, 180], position: [0, 0, 5])
  

• 校验模型缩放比例：MapBox的3D模型缩放基于米制单位，[10,10,10]可能过大导致模型超出视野范围，先尝试小比例测试：

  let configuration = Puck3DConfiguration(
      model: myModel,
      modelScale: .constant([1, 1, 1])
  )
  

• 调整图层层级：自定义地图样式可能导致3D puck被其他图层遮挡，强制将puck图层置顶：

  mapView.mapboxMap.style.setLayerProperty(for: "location-indicator-layer", property: "z-index", value: 1000)
  

• 测试官方示例模型：用MapBox提供的官方3D模型替换自定义模型，验证是否为模型本身的兼容性问题。
• 确认位置数据有效性：在onLocationChange回调中打印location信息，确保拿到的坐标是有效的，3D puck的显示依赖精准的位置数据。

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