AR Session Recorder

To generate an AR Session file that can be uploaded to the /ar-sessions endpoint, or an AR Lidar Session file to be uploaded to the /ar-lidar-sessions endpoint, you need to use the EPARSessionRecorder iOS framework. Once this framework has been incorporated into your iOS application, it will allow you to convert ARKit session data into a format that can be uploaded and processed by EveryPoint.

Download

Click here to download the EPARSessionRecorder iOS framework. In order for the download link to work, you will need to log in to your account if you have not done so already.

ARSessionRecorder

The ARSessionRecorder class allows you to capture relevant data from an ARSession and store it in a single file. This class leverages ARFrame, CMDeviceMotion, and CLLocation data for generating the recorded file, and requires a minimum iOS version of 13.0.

ARSessionRecorder supports two types of sessions: one with lidar data (ARKitLidarSession), and one without (ARKitSession). A session's type determines the file extension that is used for the recording, as well as the associated API endpoint that is used to upload the data:

• ARKitSession
  • EPARS file extension (EveryPoint AR Session)
  • /ar-sessions endpoint
• ARKitLidarSession
  • EPARLS file extension (EveryPoint AR Lidar Session)
  • /ar-lidar-sessions endpoint

Initializer

init(
  outputFolder:URL,
  firstFrame:ARFrame,
  sessionType:SessionType = .ARKitLidarSession)

This is a convenience initializer to create an instance of ARSessionRecorder. Each recording should create its own instance of ARSessionRecorder, and only one instance needs to be created for a single recording.

Parameters:

• outputFolder:URL - The folder in which the output recording file should be created. This can be the documents directory of the application or any other custom directory where the application has write permissions.
• firstFrame:ARFrame - Pass the first ARFrame that your ARSessionDelegate received in the session didUpdate method. The data from the frame is only used to configure the recording session, and is not automatically added to the recording itself.
• sessionType:SessionType - The type of AR session to record. This defaults to ARKitLidarSession, though if the recording iOS device does not have a lidar sensor, you should use ARKitSession instead.

Record a frame of data

func recordFrame(
  frame:ARFrame,
  deviceMotion:CMDeviceMotion,
  location:CLLocation)
-> Bool

This method is used to append a new frame to the recording. Typically, once an ARSession has been started, you will invoke this method each time your ARSessionDelgate’s session didUpdate method is called.

Parameters:

• frame:ARFrame - An instance of ARFrame that your ARSessionDelegate received in the session didUpdate method.
• deviceMotion:CMDeviceMotion: An instance of CMDeviceMotion recorded at the same time that ARSessionDelegate received the above frame (e.g. avoid using a cached value of the device's motion). For example, you could use the CMMotionManager’s deviceMotion property to capture this data. You should set the deviceMotionUpdateInterval to 1/60^th of a second or higher, as well as set the attitude reference frame to xTrueNorthZVertical when starting device motion updates.
• location:CLLocation - An instance of CLLocation recorded at the same time that ARSessionDelegate received the above frame (e.g. avoid using a cached value of the device's location).

Return value:

• A boolean value that when true, indicates that the provided ARFrame had valid data and was recorded. When false, it means that the frame was not recorded (for instance, the lidar data was empty because the sensor is overheating). Note: A single invalid frame may still result in a recording that is useful. However, if too many consecutive frames are invalid, this will result in a large gap in the recording. If you detect that a large gap has occurred, you should typically abandon the recording and start again. The exact threshold to use to detect large gaps in the recording is application dependent, as the impact of that gap will depend on the speed of the camera's movement as well as the speed of the scene's content. As a starting point, a large gap could be classified as 10-30 consecutive frames of invalid data.

Finish recording

func finishRecording(
  parameters:[String:AnyObject]?,
  progress:((Int)->())?,
  complete:@escaping(fileURL:URL?, error:Error?)->())
-> Int

This method is used to indicate that the recording is finished and no additional frames will be added. This method validates the recorded data, and in the case that there are no errors, it creates the output recording file within the outputFolder specified in the init method.

Parameters:

• parameters:[String:AnyObject]? - An optional dictionary of recording-related parameters that can be included with the recording. There are no specifications published for this as of now.
• progress:((Int)->())? - An optional progress block which indicates the remaining number of data packets that are yet to be recorded. This value will decrease down to 0 when all packets have been successfully written to disk.
• complete:@escaping(fileURL:URL?, error:Error?)->() - A completion block that will be invoked when the recording process has finished. In the case that no errors are reported, the path to the recorded file is returned via the fileURL parameter.

Return value:

• An integer value indicating the total number of data packets that are yet to be recorded. As the remaining packets are written, updated values will be provided via the progress block.