Design Principles

Approach

Augmented reality glasses let us visualize geographic data in the places it represents. Traditional geospatial tools are built around 2D maps, where users can pan across a city or zoom between continents in seconds. Tile-based delivery and geospatial servers support this rapid movement between locations and scales. In AR, the viewpoint follows the person, so movement through the data is more local and gradual. This opens up a different approach to delivering that data.

Reality Import proposes a standardized way to handle geospatial data in augmented reality. Its design supports large datasets by allowing devices to retrieve only small geographic portions, without a dedicated geospatial server to process those queries. Reality Import also helps make rendering implementations as consistent as possible across SDKs, without compromising developers' control over how data is rendered in their AR applications.

The aim is to accommodate any geolocated data without tying it to a particular input format, engine, or device.

Components

A Reality Import project brings together layers and render definitions. Its manifest tells an application where to find the layer data and which renderers it needs to provide.

Manifest

The SDK loads the project manifest using its public key. Here is an abbreviated example for a project containing street trees:

{
  "name": "City trees",
  "render_definitions": {
    "tree": {
      "type": ["Point"]
    }
  },
  "layers": [
    {
      "name": "Street trees",
      "data_url": "https://assets.example.com/street-trees.fgb"
    }
  ]
}

The URL is illustrative. An application reads the returned data_url rather than constructing a file path itself.

See the manifest API reference for the complete response.

Layers

A layer is a collection of geographic data points, called features. These can represent locations, paths, or areas, so a data point does not have to be a single point on a map.

A layer often brings together the contents of a single GeoJSON file, such as a collection of street trees or building footprints. A project can combine multiple layers, allowing data from separate files to be used together while keeping each collection organized as its own layer.

Reality Import converts layer data into spatially indexed FlatGeobuf (.fgb) files. Applications query a bounding box and retrieve the relevant parts of the file through HTTP byte-range requests.

Features

A feature is an individual item within a layer. It combines geographic geometry with properties describing that item. A street tree, for example, might have a point location and properties such as its species and height. Other features can describe lines, polygons, or multipart geometries.

Each feature also carries a render-definition identifier, connecting it to a renderer in the application. This tree feature is shown as JSON for readability:

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [4.8952, 52.3702]
  },
  "properties": {
    "species": "Oak",
    "height": 12,
    "ardl:render_definition": "tree"
  }
}

Render definitions

A point tells an application where something is, but not how to render it. Render definitions provide a shared basis for implementing that rendering across SDKs. For the tree above, the tree definition connects the feature to a renderer registered under the same identifier in each application.

The definition declares the geometry types it accepts, while the renderer implements the visual behavior in its host environment. This shared definition helps developers keep implementations consistent across SDKs while retaining control over how the tree appears. A renderer can use feature properties to choose assets or styling.

Multiple layers can use the same definition and share a renderer. Both datasets and models require renderers: dataset renderers construct visuals from features, while model renderers load assets and apply their placement.

See render definitions for configuration and links to the SDK renderer guides.

Follow Get started to prepare a project and connect your application.