HyperbasisHyperbasisDocs
Home

Introduction

Hyperbasis is a spatial persistence SDK for iOS AR applications. It provides "Git for physical space" - the ability to save, load, and sync AR content that persists across app sessions and relocalizes to their original real-world positions.

The Problem

Every AR app faces the same challenge: AR content disappears when the app closes. Users place virtual objects in their space, but on the next launch, everything is gone. The room looks the same, but the app has forgotten.

Building persistence yourself means:

  • •Serializing ARWorldMap with NSKeyedArchiver
  • •Storing 4x4 transform matrices for each object
  • •Managing file storage and cleanup
  • •Handling relocalization states
  • •Syncing across devices (optional, but painful)

That's weeks of infrastructure work before you can focus on your actual AR experience.

The Solution

Hyperbasis handles all of this with three simple concepts:

ConceptWhat it does
SpaceCaptures and stores an ARWorldMap - your room's fingerprint
AnchorSaves an object's position, rotation, and custom metadata
StorageManages local files and optional cloud sync

Before & After

Without Hyperbasis:

// 50+ lines of NSKeyedArchiver, FileManager,
// transform flattening, error handling...
let data = try NSKeyedArchiver.archivedData(withRootObject: worldMap, requiringSecureCoding: true)
let url = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
    .appendingPathComponent("worldmap.data")
try data.write(to: url)
// ... and you still need to handle anchors, metadata, loading, relocalization

With Hyperbasis:

let space = try HBSpace(worldMap: worldMap)
try await storage.save(space)

let anchor = HBAnchor(spaceId: space.id, transform: matrix, metadata: ["text": .string("Hello")])
try await storage.save(anchor)

Three lines. Done.

Key Concepts

Space — A mapped environment (room) containing an ARWorldMap

Anchor — A placed object with 3D transform and custom metadata

Storage — Persistence engine handling local files and cloud sync

Relocalization — Process of AR session recognizing a previously mapped space

Versioning — Event-based history tracking with timeline navigation and rollback

Quick Example

import Hyperbasis
import ARKit

// Create storage
let storage = HBStorage()

// Create space from world map
let space = try HBSpace(worldMap: arWorldMap)
try await storage.save(space)

// Save anchors
let anchor = HBAnchor(
    spaceId: space.id,
    transform: entity.transform.matrix,
    metadata: ["text": .string("Hello AR")]
)
try await storage.save(anchor)

// Load on next launch
let spaces = try await storage.loadAllSpaces()
let worldMap = try spaces.first?.arWorldMap()
let anchors = try await storage.loadAnchors(spaceId: space.id)

// View history (v1.1+)
let timeline = try await storage.timeline(spaceId: space.id)
let yesterday = Calendar.current.date(byAdding: .day, value: -1, to: Date())!
let pastAnchors = timeline.state(at: yesterday)

Requirements

  • •iOS 17.0+
  • •Swift 5.9+
  • •ARKit-compatible device

Next Steps