Mirador 两种 POI 配置方式实战对比：代码编写 vs JSON 文件，该如何选择？

Mirador 两种 POI 配置方式实战对比代码编写 vs JSON 文件该如何选择【免费下载链接】MiradorMirador makes it easy to build impressive “Point of Interest” AR experiences, on Apples new RealityKit framework.项目地址: https://gitcode.com/gh_mirrors/mi/MiradorMirador 是一个基于 Apple RealityKit 框架的开源 Swift 库让你轻松构建兴趣点POIAR 体验——手机对准眼前的地标城市 POI 标签就会悬浮在真实场景中。本文实战对比它的两种 POI 数据配置方式代码编写与JSON 文件帮你在自己的项目里选对方案。Mirador 是什么为什么 POI 配置是关键一步旅游导览、城市观景台、制高点打卡……这些场景都要把信息钉在真实地理位置上。难点在于 RealityKit 这类 AR 框架是位置无关的它只跟踪设备的相对运动不懂 GPS 坐标而手机 GPS 和指南针又常年不准位置偏几十米、朝向偏 90° 是常态。Mirador 的解法是用一张视觉锚点图片眼前的地标或铭牌来定位设备和朝向再把每个 POI 按真实坐标渲染到正确位置。锚点位置更新还会经过卡尔曼滤波KalmanFilter.swift平滑画面不会抖动。整个上手只有 3 步配置兴趣点POI——用代码或 JSON本文的主角提供锚点图片——放入 Assets文件名与锚点名一致运行 MiradorView——前台调run()后台调pause()库要求iOS 16包定义见 Package.swift。如何用代码配置 POI最小可用示例适合原型验证、POI 数量少≤10 个、数据需要动态生成。核心就三类对象LocationAnchor视觉锚点。名称、真实宽度、GPS 坐标、朝向角弧度、摆放方向水平/垂直PointOfInterest单个兴趣点。名称 位置MiradorView传入锚点调用run()完整定义见 LocationAnchor.swift经纬度换算Haversine 距离、方位角在 Location.swift。最小示例let anchor LocationAnchor( name: greenwich, // 必须与 Assets 中锚点图片同名 physicalWidth: 0.5, // 锚点真实宽度米 location: Location(coordinate: Coordinate(latitude: 51.477878, longitude: -0.000846), altitude: 46), bearing: Float(-30).degreesToRadians, orientation: .horizontal) let poi PointOfInterest(name: Canary Wharf, location: Location(coordinate: Coordinate(latitude: 51.504937, longitude: -0.019480), altitude: 50)) anchor.pointsOfInterest.append(poi) let view MiradorView(locationAnchor: anchor) view.run()示例工程逐行演示了这条路见 ContentView.swiftSwiftUI 项目改用MiradorViewContainer(locationAnchor:)嵌入即可。✅优点编译器全程类型检查可随时叠加addPOIImage()/addPOIEntity()自定义元素 ❌缺点样板代码多几十上百个 POI 手写会非常痛苦如何用 JSON 文件配置 POI一个文件搞定POI 一多Mirador 支持用单个 JSON 文件配置整个体验固定结构 一个anchor块 一个points_of_interest数组。官方样例 greenwich.json 里配置了 6 个 POI{ anchor: { name: greenwich, physical_width: 0.5, coordinate: [-0.00084588, 51.47787836], altitude: 46.0, bearing_degrees: -30, orientation: horizontal }, points_of_interest: [ { name: Canary Wharf, coordinate: [-0.01948017, 51.50493780], altitude: 235 } ], version: 1.0 }加载只需要几行if let path Bundle.main.path(forResource: greenwich, ofType: .json), let anchor LocationAnchor.anchorFromFile(atPath: path) { let view MiradorView(locationAnchor: anchor) view.run() }解码逻辑含方位角度转弧度在 LocationAnchorJSON.swift它还提供anchorFromJSONData(jsonData:)直接解析Data适合从服务端拉取 POI 数据。示例工程的 JSON 路线见 ContentView.swift。✅优点改 POI 不用重编译非程序员也能维护批量管理和多视角扩展都更顺手 ❌缺点无编译期检查字段名、坐标顺序写错只能在运行时发现POI 配置对比清单一张表看懂该选哪个对比维度代码编写JSON 文件推荐 POI 数量≤ 10 个10 个以上数据维护改代码 重新编译改 JSON 即可谁来维护开发者运营 / 内容人员可上手动态数据服务端下发✅ 容易✅anchorFromJSONData直接解析类型安全✅ 编译期检查⚠️ 解析失败返回 nil叠加自定义元素✅ 随时调用addPOIImage⚠️ 需加载后再补充学习成本需理解几个核心类看懂 JSON 结构即可POI 配置避坑指南5 个高频错误坐标顺序和代码相反JSON 的coordinate是[经度, 纬度]而代码里Coordinate(latitude:longitude:)纬度在前——这是第一高频错误。bearing 单位不同代码传弧度Float(-30).degreesToRadiansJSON 传角度bearing_degrees: -30。️锚点图片必须同名Assets 里要有一张与LocationAnchor.name同名的图片。示例工程用的是格林尼治地面铭牌的照片3024×4032 实拍图拍摄要点正对拍摄、避开阴影与反光RealityKit 认不出被透视变形过的图。铭牌贴地这类场景用horizontal投在屏幕上用vertical。细节别漏Info.plist 加NSCameraUsageDescriptionRealityKit 依赖摄像头必须真机运行模拟器无效。如何选择按场景对号入座原型验证 / POI ≤ 10 个→ 代码编写类型安全、调试方便旅游导览 / 城市观景台 / POI 成百上千→ JSON 文件内容团队独立维护坐标POI 由服务端动态下发→ 沿用 JSON 结构走anchorFromJSONData(jsonData:)本地与远程一套解析多视角多锚点应用→ 每个视角一个 JSON 文件比代码里堆一堆锚点好维护两种路线最终都汇聚到同一个LocationAnchor对象随时可以切换或混用更完整的配置细节锚点拍摄、录制 RealityKit 会话在家回放调试等见 README.md。关键文件清单核心类锚点 / POISources/Mirador/LocationAnchor.swiftJSON 解码Sources/Mirador/LocationAnchorJSON.swiftAR 视图与run()/pause()Sources/Mirador/MiradorView.swift地理坐标计算Sources/Mirador/Location.swift样例 POI 数据Demo/greenwich.json示例入口两种写法并存Demo/ContentView.swift一句话总结POI 少用代码换类型安全POI 多上 JSON 换可维护性——两条路殊途同归按需切换即可。【免费下载链接】MiradorMirador makes it easy to build impressive “Point of Interest” AR experiences, on Apples new RealityKit framework.项目地址: https://gitcode.com/gh_mirrors/mi/Mirador创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考