Logo
适用于 iOS 的 SAP Fiori AR


安装 | 示例 | API 文档 | 更新日志

Build Status Conventional Commits Commitizen friendly REUSE status

此项目是 适用于 iOS 的 SAP Fiori 设计指南中增强现实 (AR) 模式的 SwiftUI 实现。

当前支持

要求

您必须配置技术用户和密码才能解析包!

依赖项

安装

该软件包旨在通过 Swift Package Manager 使用。 要将该软件包添加到您的应用程序目标,请导航至 File > Add Packages... >,然后添加存储库 URL。

您可以选择以下软件包产品之一添加到您的应用程序/框架目标。

软件包产品 何时使用
FioriAR 您尚未嵌入来自 SAP BTP SDK for iOS 的二进制框架
FioriAR-requiresToEmbedXCFrameworks 您已将 SAPCommonSAPFoundation 二进制框架嵌入到您的目标中

迁移 FioriAR 1.0 到 FioriAR 2.0

FioriAR 2.0 与之前的版本不完全兼容。 但是,迁移并不困难。 当您准备升级项目中的 FioriAR 时,请遵循迁移指南

AR 注释

CarEngineVid.mp4

AR 注释是指与真实世界中图像或对象相关的 标记相匹配的卡片。 要在世界视图中查看注释,用户使用 AR 扫描仪扫描图像/对象。

不需要 3D 建模来表示 AR 注释,因为相应的控件(ARScanViewMarkerViewCardView)已在此软件包中使用 SwiftUI 实现。

应用程序开发人员需要提供一个相对于 ImageObject 锚点的标记场景。 这种场景创建是可能的

根据场景的存储位置和方式(.rcproject.reality.usdz 文件或 SAP Mobile Services),应用程序开发人员必须指定适当的加载策略来填充场景和相关的卡片数据。

卡片和标记支持 SwiftUI ViewBuilder 以允许自定义设计。

依赖于 SAP Mobile Services 的应用内处理

FioriAR 提供了可重用的视图和实用程序,可直接从您的应用程序创建/更新/删除带有 AR 注释的场景。 考虑到创建和处理 AR 注释的容易程度,这是推荐的方法。

场景信息将远程存储在 SAP Mobile Services 中。 作为先决条件,需要将功能 Mobile Augmented Reality 分配给 SAP Mobile Services cockpit 中的应用程序。

SAP Mobile Services 允许管理员 编辑增强现实场景,这有助于维护多种语言的 AR 注释文本。

合成场景

呈现 SceneAuthoringView 将提供一个用户界面,您的用户可以在其中创建 AR 注释,并指定它们相对于图像锚点的位置。

import FioriAR
import SAPFoundation

struct ARCardAuthoringContentView: View {
	public var serverUrl: URL
	public var sapURLSession: SAPURLSession
	public var sceneId: Int? // nil in case of you want to create a new scene

    var body: some View {
        SceneAuthoringView(title: "Annotations",
                           serviceURL: serverUrl,
                           sapURLSession: sapURLSession,
                           sceneIdentifier: SceneIdentifyingAttribute.id(sceneId))
            .onSceneEdit { sceneEdit in
                switch sceneEdit {
                case .created(card: let card):
                    print("Card locally created: \(card.title_)")
                case .updated(card: let card):
                    print("Card locally updated: \(card.title_)")
                case .deleted(card: let card):
                    print("Card locally deleted: \(card.title_)")
                case .published(sceneID: let sceneID):
                    print("Scene \(sceneID) created/updated")
                }
            }
    }
}

查看场景

使用 ServiceStrategy 从 SAP Mobile Services 获取场景信息,并在 AR 世界中使用 ARAnnotationsView 呈现其 AR 注释。

struct ARCardsServiceView: View {
    @StateObject var arModel = ARAnnotationViewModel<CodableCardItem>()
    @StateObject var asyncStrategy = ServiceStrategy<CodableCardItem>!

	init(serverURL: URL, sapURLSession: SAPURLSession, sceneId: Int) {
		_asyncStrategy = ServiceStrategy<CodableCardItem>(
        serviceURL: serviceURL,
        sapURLSession: sapURLSession,
        sceneIdentifier: SceneIdentifyingAttribute.id(sceneId)
		)
    }

    var body: some View {
        ARAnnotationsView(arModel: arModel,
                          cardAction: { id in
                              print("Action for card \(id) was triggered")
                          })
            .onAppear(perform: loadInitialData)
    }
    
    func loadInitialData() {
        do {
            try self.arModel.loadAsync(loadingStrategy: self.asyncStrategy)
        } catch {
            print(error)
        }
    }
}

Reality Composer

FioriAR 可以处理使用 Apple 的 Reality Composer 创建的 AR 体验,但 AR 注释的处理更加复杂,因为

合成场景

  1. 打开 Reality Composer 应用程序并创建一个带有图像或对象锚点的场景
  2. 选择一个图像或扫描一个对象,并给场景一个名称,例如 ExampleScene
  3. 将球体放置在所需的位置
  4. 在 AR 中预览以进行微调
  5. 使用符合 LosslessStringConvertable 的类型命名球体
  6. 球体的名称将对应于 CardItemModel id
  7. 将场景导出为
    • .usdz 文件(在首选项或 iOS 应用程序设置中启用 usdz 导出)
    • .reality 文件或
    • 将整个项目另存为带有单个场景的 .rcproject

注意:

rcDemo1        rcDemo2

查看场景

此 Swift 软件包提供了各种加载策略,具体取决于您用于导出场景的文件格式。

加载策略接受元素数组,每个元素都符合 CardItemModel 协议,以填充卡片相关数据。 模型的 *id* 属性必须对应于 Reality Composer 中实体(球体)的 *name*。

每个加载策略还有一个初始化器,用于接受由 JSON 数组表示的 Data

// JSON key/value:
"id": String,
"title_": String,
"subtitle_": String?,
"detailImage_": Data?, // base64 encoding of Image
"actionText_": String?,
"icon_": String? // systemName of SFSymbol

除了场景和卡片相关数据之外,支持的加载策略(UsdzFileStrategyRealityFileStrategyRCProjectStrategy)还需要有关用于检测场景的锚点的信息。 使用 Image 锚点需要应用程序开发人员提供 anchorImage 及其 physicalWidth 作为初始化器参数。 对于 Object 锚点,anchorImage 和 physicalWidth 参数可以为 nil。

场景可以用不同的文件类型表示,并且每个策略都需要不同的数据和设置。

注意:

用法示例:创建 ContentView 并加载数据

import FioriAR

struct FioriARKCardsExample: View {
    @StateObject var arModel = ARAnnotationViewModel<CodableCardItem>()
    
    var body: some View {
    /**
     Initializes an AR Experience with a Scanning View flow with Markers and Cards upon anchor discovery

     - Parameters:
        - arModel: The View Model which handles the logic for the AR Experience
        - guideImage:  image to display for anchor detection in the Scanning View, if nil then the image anchor will be used by default
        - cardAction: Card Action
    */
        ARAnnotationsView(arModel: arModel, guideImage: Image("qrImage"), cardAction: { id in
            // action to pass to corresponding card from the CardItemModel id
        })
        .onAppear(perform: loadInitialData)
    }
// Example to use a `UsdzFileStrategy` to populate scene related information (stored in a .usdz file which could have been fetched from a remote server during runtime) as well as card-related information (stored in a .json file which could have been fetched from a remote server as well)
    func loadInitialData() {
        let usdzFilePath = FileManager.default.getDocumentsDirectory().appendingPathComponent(FileManager.usdzFiles).appendingPathComponent("ExampleRC.usdz")
        guard let anchorImage = UIImage(named: "qrImage"), 
              let jsonUrl = Bundle.main.url(forResource: "Tests", withExtension: "json") else { return }
        
        do {
            let jsonData = try Data(contentsOf: jsonUrl)
            let strategy = try UsdzFileStrategy(jsonData: jsonData, anchorImage: anchorImage, physicalWidth: 0.1, usdzFilePath: usdzFilePath)
            arModel.load(loadingStrategy: strategy)
        } catch {
            print(error)
        }
    }
}

如何获得支持

创建 GitHub issue 以创建错误报告、提交功能请求或提问。

贡献

如果您想贡献代码,请查看贡献指南

示例

可以使用此软件包中已有的演示应用程序进一步探索功能 (Apps/Examples/Examples.xcodeproj)。 有关更多信息,请参阅其 README