Developer Docs

Getting Started

Overview

The TorchKit SDK allows any iOS application to load and execute Torch AR project export packages. The quickest way to see a running example of the SDK is to open and run the sample app. Detailed API documentation is available here.

This guide covers:

  • Running the SDK sample
  • Integrating using sample classes
  • Integrating manually with the TorchKit API

The TorchKit integration is free for development & testing purposes. Public exports and live projects require a paid Publish plan. Contact us to learn more.

Prerequisites

Working with the Torch SDK requires the following:

  • Xcode 10.3 or higher
  • macOS 10.14 or higher (required by XCode)

Run the SDK Sample

To try the sample, clone the Samples Github Repo, navigate to the ios/scenekit/swift/project-chooser directory in a Terminal. The sample app mimics a simple product catalog. In this case, it is a gallery of Torch projects. The sample app includes a check to make sure the user’s device supports ARKit, if the device is not compatible, the app does not allow access to the AR experience.

To run the sample application:

  1. The sample application uses CocoaPods to initialize the workspace run pod install in the ios/scenekit/swift/project-chooser directory.
  2. Navigate to the Torch api page and copy the API key into the step below.
  3. Open AppDelegate.swift and replace the API key in this line: TorchKit.shared.initSDK(apiKey: "INSERT API KEY HERE")
  4. Update the Signing Settings under Build Settings to use your Apple account.
  5. Run the sample application on a device.

Integrate using the SDK sample classes

The SDK sample contains a few helper classes that streamline the integration process of the Torch SDK into any application. This integration path has the fewest steps and fits into applications that meet this criteria:

  • If the target application only needs to present a new view controller with the Torch project running in it.
  • If the target application doesn’t have an existing view controller with SceneKit integrated.

Using the SDK helper classes also cover setting the project anchor which the raw SDK integration skips over.

  1. Export the Torch Project that is going to be used as a .torchkitproj and add it to the XCode project.
  2. Add TorchKit to your project.

    With CocoaPods:

    Simply add the following line to your Podfile:

    pod 'TorchKit', :http => "https://artifacts.torch.dev/torchkit/TorchKit_0_3_1.zip"

    And then run pod install

    Without CocoaPods:

    Download TorchKit from the following location:

    https://artifacts.torch.dev/torchkit/TorchKit_0_3_1.zip

    Unzip the downloaded file and drag the resulting TorchKit.framework file into the “Embedded Binaries” section of your Xcode project’s properties.

  3. Copy TorchProjectViewController.swift, ProjectAnchorManager.swift, Plane.swift, envmap.png into the project.

  4. Navigate to the Torch api page and copy the API key into the step below.

  5. Import TorchKit into the file that implements AppDelegate then add the following to AppDelegate.application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool, replacing YOUR_API_KEY with your Torch API key.

    do {
      try TorchKit.shared.initSDK(apiKey: "YOUR_API_KEY")
    } catch {
      os_log(OSLogType.default, "Init failed!")
    }
  6. Add the following to AppDelegate.applicationWillTerminate(...):

    TorchKit.shared.shutdownSDK()
  7. Add a camera permission message—add a string variable to the application’s Info.plist with the key of NSCameraUsageDescription and a value containing the message to display to the user when camera permissions are required.

  8. Finally, when the application needs to launch the Torch AR view controller, add the following code:

    if let projectURL = Bundle.main.url(forResource: "myproject", withExtension: "torchkitproj") {
      let vc = TorchProjectViewController(projectURL: projectURL)
      self.present(vc, animated: true, completion: nil)
    }

TorchProjectViewController can be used as the basis of a new UIViewController for the target application.

Integrate Manually

This is every detail needed to integrate a Torch project viewer in an application. This includes integration steps that are handled by the TorchViewController above. Setting the project anchor is not documented in this section, see ProjectAnchorManager.swift in the sample application for a method to handle this.

The TorchKit API uses SceneKit and ARKit to run Torch Projects. The API has been designed to work with the target application even if it is already using SceneKit or ARKit. These integration points will be called out below.

  1. Export the Torch Project that is going to be used as a .torchkitproj and add it to the XCode project.
  2. Navigate to the Torch api page and copy the API key into the step below.
  3. Add TorchKit to your project.

    With CocoaPods:

    Simply add the following line to your Podfile:

    pod 'TorchKit', :http => "https://artifacts.torch.dev/torchkit/TorchKit_0_3_1.zip"

    And then run pod install

    Without CocoaPods:

    Download TorchKit from the following location:

    https://artifacts.torch.dev/torchkit/TorchKit_0_3_1.zip

    Unzip the downloaded file and drag the resulting TorchKit.framework file into the “Embedded Binaries” section of your Xcode project’s properties.

  4. Import TorchKit into the file that implements AppDelegate then add the following to AppDelegate.application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool, replacing YOUR_API_KEY with your Torch API key:

    do {
     try TorchKit.shared.initSDK(apiKey: "YOUR_API_KEY")
    } catch {
     os_log(OSLogType.default, "Init failed!")
    }
  5. Add the following to AppDelegate.applicationWillTerminate(...):

    TorchKit.shared.shutdownSDK()
  6. Add a camera permission message— Input a string variable to the application’s Info.plist with the key of NSCameraUsageDescription and a value containing the message to display to the user when camera permissions are required.

  7. Add an ARSCNView to the target view controller to display a SceneKit scene and use ARKit to control the camera.

  8. In the ViewController displaying the ARSCNView viewDidAppear method, call TorchGestureManager.addGestureRecognizers(to:) to add gesture recognizers for tap and object manipulation.

    TorchGestureManager.shared.addGestureRecognizers(to: sceneView)
  9. Create a TorchProjectNode passing the path to the .torchkitproj in.

    self.torchProject = try TorchProjectNode(withProjectURL: projectURL, andDevice: self.sceneView.device!, arSession: self.sceneView.session)

    If the target application is already using ARKit, pass the current ARKit session into the constructor.

  10. Set the ARSessionDelegate of the current ARKit session to the arSessionDelegate of torchProject.

    // Set the ARSessionDelegate to the torchProj ar session delegate, needed
    // for image tracking.  If you need to have access to the ARSessionDelegate
    // information, hook your ARSessionDelegate here and pass calls through to
    // the torchProj.arSesssionDelegate.
    self.sceneView.session.delegate = torchProj.arSessionDelegate ?? nil
  11. Add the TorchProjectNode to the SceneKit scene:

    sceneView.scene.rootNode.addChildNode(torchProj)

    If the target application is already using SceneKit, add the torchProj node to the existing SceneKit scene.

  12. Set up a SCNRendererDelegate to call TorchProjectNode.tick(...) to advance project state.

    func init() {
      self.sceneView.delegate = self
    }
    
    func renderer(_ renderer: SCNSceneRenderer, updateAtTime time: TimeInterval) {
      let dt = self.lastTime != 0 ? time - self.lastTime : 0
      self.lastTime = time
    
      self.viewLock.lock()
      let viewCenter = self.viewCenter
      self.viewLock.unlock()
      let hits = self.sceneView.hitTest(viewCenter, options: nil)
      let gazedNode: SCNNode? = !hits.isEmpty ? hits.first!.node : nil
      self.torchProj!.tick(delta: dt, cameraTransform: self.sceneView.session.currentFrame!.camera.transform, currentGazedNode: gazedNode)
    }

Find Help