Skip to content

Integration with a 3D Engine

To integrate the ARDK with a 3D engine, you can use the ARState class, which exposes the transformation matrices and frame-related data needed to align the virtual scene with the current AR camera.

ARState represents the state of the current augmented reality frame. It provides access to:

  • the texture coordinate transform for the camera image,
  • the camera view matrix,
  • the camera projection matrix,
  • the world-to-AR transform,
  • color correction parameters,
  • depth buffer size information.

These values can be used with virtually any rendering engine or custom renderer.

If you use the GiPStech AuRea library, this integration is handled automatically. Simply pass the ARSession to AuWorld, and the library will take care of rendering the objects on top of the camera stream.

Catalog

The Catalog class is a utility for managing marker definitions provided as auxiliary files from the GiPStech MDK, specifically designed for AR use cases.

It simplifies the workflow of loading, detecting, and attaching markers within an active Session.

Catalog is intended to:

  • load marker configurations from MDK auxiliary files (JSON),
  • convert geographic data into the AR local coordinate system,
  • manage marker metadata (MarkerInfo),
  • handle marker detection and automatic attachment,
  • provide ready-to-use Marker objects once fully attached.

It acts as a bridge between static marker definitions (from MDK files) and runtime AR operations.

Initialization

val catalog = Catalog(origin, session)
  • origin: reference point used to build the local tangent plane for coordinate conversion
  • session: active AR Session used for detection and attachment

Loading markers

catalog.load(filename)

Loads and parses a JSON file coming from the GiPStech MDK.

Supported structures:

  • outdoor markers (markers)
  • indoor markers (buildings → floors → markers)

During loading, the catalog:

  • converts geographic coordinates to local coordinates (LocalTangentPlane)
  • computes marker orientation (Quatf)
  • stores all markers internally as MarkerInfo

Requesting markers

catalog.requestAttachedMarkers { marker ->
    // marker ready to use
}

Behavior:

  • listens to detection events from the session
  • when a marker is DETECTED, it is automatically attached
  • when ATTACH_COMPLETED, the callback is invoked

This abstracts the full lifecycle: detection → attachment → ready-to-use marker

Requesting device location

catalog.requestLocation { state, hookState, location, quaternion ->
    // use location
}

Returns:

  • tracking state
  • hook state
  • device location in WGS84 (Coord3D)
  • device orientation (Quatf)

The position is converted from AR local space to geographic coordinates using the internal local tangent plane.

Notes

  • Designed to work directly with GiPStech MDK auxiliary files
  • Handles both indoor and outdoor marker definitions
  • Automatically applies floor heading and mount type when computing orientation
  • Reduces boilerplate for marker lifecycle management