Mirador 自定义 AR 元素全解addPOIImage、addPOIEntity 与 addLocationEntity 用法实战【免费下载链接】MiradorMirador makes it easy to build impressive “Point of Interest” AR experiences, on Apples new RealityKit framework.项目地址: https://gitcode.com/gh_mirrors/mi/MiradorMirador 是一个基于 RealityKit 的开源 iOS 库专为在 AR 中标注兴趣点Point of Interest而设计。本文通过实战讲解它的三个核心 API——addPOIImage、addPOIEntity与addLocationEntity帮助你快速在 AR 场景中显示自定义图片和 3D 元素打造城市导览、观景台标注等沉浸式体验。一、为什么需要这三个方法在 AR 中标注兴趣点有两个天然难题RealityKit 不感知真实位置它只跟踪设备在 xyz 空间的运动没有 GPS 概念GPS 和指南针都不够准误差 10 米、偏航 90° 是家常便饭。Mirador 的解法是用一张视觉锚点图片比如观景台的地面标识来定位设备然后由库自动把 AR 元素摆放正确。定位就绪后接下来就是你关心的如何往这个 AR 世界里塞入自己的内容。这正是三个方法分工的地方方法显示什么屏幕缩放ScreenScale面向相机FaceCamera适用场景addPOIImage一张 UIImage支持透明、投影✅✅图标、卡片、文字标签addPOIEntity任意 RealityKit Entity✅✅3D 模型、自定义 UIaddLocationEntity任意 RealityKit Entity❌❌需要真实大小/朝向的场景元素三个方法的完整实现都在Sources/Mirador/MiradorView.swift中源码非常易读强烈建议通读一遍。二、addPOIImage最常用的一键图片标注适用场景在 AR 空间里显示一张图片——地标图标、信息卡片、甚至你用 SwiftUI 渲染的 UI。let cityLocation Location( coordinate: Coordinate(latitude: 51.51438463, longitude: -0.08024839), altitude: 200 ) let image UIImage(named: skyline)! miradorView.addPOIImage(location: cityLocation, image: image)就这么简单。它的特性值得展开说说支持透明PNG 透明通道完全可用还能带投影效果屏幕缩放图片设计成多大屏幕上就显示多大。比如 300×300 像素的图片无论离相机多远视觉上始终是 300×300 点始终面向相机转身、走动时元素自动回头看着你底部带一根立杆spoke白色细杆从地面位置延伸到图片底部让悬浮的图像有了插在地上的锚定感这是官方默认 POI 外观的精髓颜色不失真RealityKit 内容在真实光照下容易发暗Mirador 内部用 PBR 自发光 透明混合材质解决了这个问题渲染细节见setupRealityKitPlane()Sources/Mirador/MiradorView.swift第 146-199 行。小技巧想显示自定义 UI按钮、卡片可以直接用 SwiftUI 的ImageRenderer把视图渲染成图片再传入。官方自带的addPOILabel()第 201-231 行就是现成的范例——它把兴趣点名称渲染成圆角白底标签。三、addPOIEntity放入任意 RealityKit 实体当图片不够用需要 3D 模型或更复杂的实体组合时用addPOIEntitylet building try! ModelEntity.loadModel(named: building) miradorView.addPOIEntity(location: cityLocation, entity: building)它会把你的 Entity 包进两层功能壳里同时获得屏幕缩放和面向相机两个能力你的 Entity └── ScreenScaleEntity 每帧动态缩放保持屏幕尺寸恒定 └── FaceCameraEntity每帧转向相机 └── LocationEntity锚定到 GPS 坐标这个包装过程在addPOIEntity()中完成Sources/Mirador/MiradorView.swift第 251-261 行。ScreenScaleEntity和FaceCameraEntity的定义非常简洁位于Sources/Mirador/Entities.swift——它们本质上只是身份标记真正的每帧计算由MiradorView在场景更新循环里统一完成。四、addLocationEntity只定位、不包装如果你要的元素需要真实世界的大小和朝向——比如一座 1:1 比例的建筑模型、一片固定朝向的旗帜——就不该加屏幕缩放和转向。这时直接用addLocationEntitylet landmark try! ModelEntity.loadModel(named: landmark) miradorView.addLocationEntity(location: cityLocation, entity: landmark)它只做一件事创建LocationEntity并把你的实体挂上去交给定位系统摆放。实现只有 6 行第 264-269 行是整个 API 的地基——事实上前两个方法内部最终都会调用它。五、幕后机制元素是如何钉在正确位置的理解了调用链再来看看定位是如何工作的锚点识别run()启动 AR 会话时锚点图片被注册为ARReferenceImage。ARKit 认出它后生成图像锚点locationAnchorEntity随即挂到锚点上方向平滑相机每帧更新锚点朝向但边缘帧的精度很差。Mirador 用一个卡尔曼滤波Sources/Mirador/KalmanFilter.swift对朝向估计做平滑消除 AR 内容抖动屏幕缩放计算每帧根据相机内参算出视野 FOV再推算1 米处屏幕上 1 点对应的真实距离据此缩放所有 ScreenScale 实体第 71-79 行远距离压缩RealityKit 对超过约 1000 米的实体不渲染。对 250 米以外的元素Mirador 会把距离对数压缩进 250-500 米区间第 94-113 行保证远处的兴趣点也能显示。六、快速上手三步跑起来第 1 步安装通过 Swift Package Manager 添加依赖或者克隆仓库git clone https://gitcode.com/gh_mirrors/mi/Mirador把Sources/Mirador/拖进你的工程。第 2 步配置兴趣点两种方式任选代码方式构造Location、LocationAnchor和PointOfInterest数组完整示例见Demo/ContentView.swiftJSON 方式兴趣点多时更清爽官方示例文件是Demo/greenwich.json用LocationAnchor.anchorFromFile(atPath:)一行加载。第 3 步提供锚点图片并运行在 Assets 里放一张与LocationAnchor.name同名的清晰图片尽量正面拍摄、无阴影反光然后let miradorView MiradorView(locationAnchor: locationAnchor) miradorView.run() // App 回到前台时调用 miradorView.pause() // App 退到后台时调用⚠️ 两个新手高频踩坑点记得在 Info.plist 中添加NSCameraUsageDescription必须在真机上运行——RealityKit 需要相机模拟器中不可用。不出门也能开发把锚点图片显示在电脑屏幕上用 App 扫描它就能在家快速调试 AR 元素的显示效果。官方示例的锚点就是格林尼治地标那块世界遗产地面铭牌上图。七、选型建议与常见疑问三个方法怎么选有现成图片素材、追求最快出效果 →addPOIImage有 3D 模型但仍希望图标化显示大小恒定、始终看镜头→addPOIEntity需要真实比例或固定朝向的场景资产 →addLocationEntity。它们可以混用同一场景里地标用 3D 模型addPOIEntity说明文字用渲染图片addPOIImage地面装饰用真实比例实体addLocationEntity。常见问题图片发灰发暗检查是否走了addPOIImage的自发光渲染路径自定义材质时参考setupRealityKitPlane()的混合设置。元素一闪一闪这是锚点更新的正常现象卡尔曼滤波已内置若仍明显可增大测量不确定性参数。元素超过 250 米远库会自动压缩距离但建议对超远元素使用屏幕缩放类方法视觉更稳定。总结Mirador 把定位 摆放这些脏活累活全包了留给你的只有三个干净利落的 APIaddPOIImage显示图片、addPOIEntity包装实体、addLocationEntity纯定位。理解屏幕缩放 面向相机这两个可选能力你就掌握了自定义 AR 元素的全部门道。动手试试吧下一个城市导览 AR 应用就是你 【免费下载链接】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），仅供参考 Mirador 自定义 AR 元素全解：addPOIImage、addPOIEntity 与 addLocationEntity 用法实战
Mirador 自定义 AR 元素全解addPOIImage、addPOIEntity 与 addLocationEntity 用法实战【免费下载链接】MiradorMirador makes it easy to build impressive “Point of Interest” AR experiences, on Apples new RealityKit framework.项目地址: https://gitcode.com/gh_mirrors/mi/MiradorMirador 是一个基于 RealityKit 的开源 iOS 库专为在 AR 中标注兴趣点Point of Interest而设计。本文通过实战讲解它的三个核心 API——addPOIImage、addPOIEntity与addLocationEntity帮助你快速在 AR 场景中显示自定义图片和 3D 元素打造城市导览、观景台标注等沉浸式体验。一、为什么需要这三个方法在 AR 中标注兴趣点有两个天然难题RealityKit 不感知真实位置它只跟踪设备在 xyz 空间的运动没有 GPS 概念GPS 和指南针都不够准误差 10 米、偏航 90° 是家常便饭。Mirador 的解法是用一张视觉锚点图片比如观景台的地面标识来定位设备然后由库自动把 AR 元素摆放正确。定位就绪后接下来就是你关心的如何往这个 AR 世界里塞入自己的内容。这正是三个方法分工的地方方法显示什么屏幕缩放ScreenScale面向相机FaceCamera适用场景addPOIImage一张 UIImage支持透明、投影✅✅图标、卡片、文字标签addPOIEntity任意 RealityKit Entity✅✅3D 模型、自定义 UIaddLocationEntity任意 RealityKit Entity❌❌需要真实大小/朝向的场景元素三个方法的完整实现都在Sources/Mirador/MiradorView.swift中源码非常易读强烈建议通读一遍。二、addPOIImage最常用的一键图片标注适用场景在 AR 空间里显示一张图片——地标图标、信息卡片、甚至你用 SwiftUI 渲染的 UI。let cityLocation Location( coordinate: Coordinate(latitude: 51.51438463, longitude: -0.08024839), altitude: 200 ) let image UIImage(named: skyline)! miradorView.addPOIImage(location: cityLocation, image: image)就这么简单。它的特性值得展开说说支持透明PNG 透明通道完全可用还能带投影效果屏幕缩放图片设计成多大屏幕上就显示多大。比如 300×300 像素的图片无论离相机多远视觉上始终是 300×300 点始终面向相机转身、走动时元素自动回头看着你底部带一根立杆spoke白色细杆从地面位置延伸到图片底部让悬浮的图像有了插在地上的锚定感这是官方默认 POI 外观的精髓颜色不失真RealityKit 内容在真实光照下容易发暗Mirador 内部用 PBR 自发光 透明混合材质解决了这个问题渲染细节见setupRealityKitPlane()Sources/Mirador/MiradorView.swift第 146-199 行。小技巧想显示自定义 UI按钮、卡片可以直接用 SwiftUI 的ImageRenderer把视图渲染成图片再传入。官方自带的addPOILabel()第 201-231 行就是现成的范例——它把兴趣点名称渲染成圆角白底标签。三、addPOIEntity放入任意 RealityKit 实体当图片不够用需要 3D 模型或更复杂的实体组合时用addPOIEntitylet building try! ModelEntity.loadModel(named: building) miradorView.addPOIEntity(location: cityLocation, entity: building)它会把你的 Entity 包进两层功能壳里同时获得屏幕缩放和面向相机两个能力你的 Entity └── ScreenScaleEntity 每帧动态缩放保持屏幕尺寸恒定 └── FaceCameraEntity每帧转向相机 └── LocationEntity锚定到 GPS 坐标这个包装过程在addPOIEntity()中完成Sources/Mirador/MiradorView.swift第 251-261 行。ScreenScaleEntity和FaceCameraEntity的定义非常简洁位于Sources/Mirador/Entities.swift——它们本质上只是身份标记真正的每帧计算由MiradorView在场景更新循环里统一完成。四、addLocationEntity只定位、不包装如果你要的元素需要真实世界的大小和朝向——比如一座 1:1 比例的建筑模型、一片固定朝向的旗帜——就不该加屏幕缩放和转向。这时直接用addLocationEntitylet landmark try! ModelEntity.loadModel(named: landmark) miradorView.addLocationEntity(location: cityLocation, entity: landmark)它只做一件事创建LocationEntity并把你的实体挂上去交给定位系统摆放。实现只有 6 行第 264-269 行是整个 API 的地基——事实上前两个方法内部最终都会调用它。五、幕后机制元素是如何钉在正确位置的理解了调用链再来看看定位是如何工作的锚点识别run()启动 AR 会话时锚点图片被注册为ARReferenceImage。ARKit 认出它后生成图像锚点locationAnchorEntity随即挂到锚点上方向平滑相机每帧更新锚点朝向但边缘帧的精度很差。Mirador 用一个卡尔曼滤波Sources/Mirador/KalmanFilter.swift对朝向估计做平滑消除 AR 内容抖动屏幕缩放计算每帧根据相机内参算出视野 FOV再推算1 米处屏幕上 1 点对应的真实距离据此缩放所有 ScreenScale 实体第 71-79 行远距离压缩RealityKit 对超过约 1000 米的实体不渲染。对 250 米以外的元素Mirador 会把距离对数压缩进 250-500 米区间第 94-113 行保证远处的兴趣点也能显示。六、快速上手三步跑起来第 1 步安装通过 Swift Package Manager 添加依赖或者克隆仓库git clone https://gitcode.com/gh_mirrors/mi/Mirador把Sources/Mirador/拖进你的工程。第 2 步配置兴趣点两种方式任选代码方式构造Location、LocationAnchor和PointOfInterest数组完整示例见Demo/ContentView.swiftJSON 方式兴趣点多时更清爽官方示例文件是Demo/greenwich.json用LocationAnchor.anchorFromFile(atPath:)一行加载。第 3 步提供锚点图片并运行在 Assets 里放一张与LocationAnchor.name同名的清晰图片尽量正面拍摄、无阴影反光然后let miradorView MiradorView(locationAnchor: locationAnchor) miradorView.run() // App 回到前台时调用 miradorView.pause() // App 退到后台时调用⚠️ 两个新手高频踩坑点记得在 Info.plist 中添加NSCameraUsageDescription必须在真机上运行——RealityKit 需要相机模拟器中不可用。不出门也能开发把锚点图片显示在电脑屏幕上用 App 扫描它就能在家快速调试 AR 元素的显示效果。官方示例的锚点就是格林尼治地标那块世界遗产地面铭牌上图。七、选型建议与常见疑问三个方法怎么选有现成图片素材、追求最快出效果 →addPOIImage有 3D 模型但仍希望图标化显示大小恒定、始终看镜头→addPOIEntity需要真实比例或固定朝向的场景资产 →addLocationEntity。它们可以混用同一场景里地标用 3D 模型addPOIEntity说明文字用渲染图片addPOIImage地面装饰用真实比例实体addLocationEntity。常见问题图片发灰发暗检查是否走了addPOIImage的自发光渲染路径自定义材质时参考setupRealityKitPlane()的混合设置。元素一闪一闪这是锚点更新的正常现象卡尔曼滤波已内置若仍明显可增大测量不确定性参数。元素超过 250 米远库会自动压缩距离但建议对超远元素使用屏幕缩放类方法视觉更稳定。总结Mirador 把定位 摆放这些脏活累活全包了留给你的只有三个干净利落的 APIaddPOIImage显示图片、addPOIEntity包装实体、addLocationEntity纯定位。理解屏幕缩放 面向相机这两个可选能力你就掌握了自定义 AR 元素的全部门道。动手试试吧下一个城市导览 AR 应用就是你 【免费下载链接】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），仅供参考