OPX Technical Documentation

Introduction

OPX is an open, extensible reality capture format built around a spatially indexed block container. It is intended to serve as both an exchange format and a native working format for large geospatial and reality capture datasets.

Container structure

The OPX file is composed of a Superblock, Root Directory and typed payload blocks. Blocks are independently versioned and aligned for efficient range access.

Binary layout

All current OPX structures are serialized explicitly field-by-field in little-endian order. Raw struct dumps are avoided to maintain stable binary compatibility across compilers and platforms.

OPX Container
├─ Superblock
├─ RootDirectory
├─ CRS Block
├─ Metadata Block
├─ SpatialIndex Block
├─ LOD Summary Block
├─ PointTile Blocks
├─ Image Blocks
├─ VectorLayer Blocks
├─ Survey Blocks
├─ Grid Blocks
└─ Unknown Optional Blocks

Coordinates & CRS

OPX uses an integer coordinate model suitable for large coordinate values and micrometer-level precision.

real_coordinate = crs_origin + tile_origin + integer_delta * scale

CRS payloads may store EPSG codes, WKT2 strings, PROJJSON strings, vertical CRS text, local engineering CRS names and coordinate epoch metadata.

Point tiles

Point data is stored in tile-local Struct-of-Arrays streams. This supports efficient filtering, compression, GPU upload paths and attribute-specific access.

• Position deltas as int32 or int64
• Attribute schema with standard and custom attributes
• Optional per-stream compression descriptors
• Backward-compatible PointTile 1.0 reading

Spatial index & LOD

The current implementation provides a spatial tile index, bounding box queries, fixed-grid and adaptive octree building, and optional LOD summary blocks.

• Leaf-only adaptive octree builder
• Deterministic node IDs
• LOD summaries using deterministic sample indices
• Adaptive query options with max point budgets

Images

Image blocks support panoramas, perspective images and orthophotos. OPX stores encoded image bytes and metadata but intentionally does not decode image formats in the core SDK.

• Pose and quaternion orientation
• Camera intrinsics and distortion model
• Orthophoto georeferencing
• Links to PointTile UUIDs

Vector layers

Vector layers store lines, polygons, multilines, multipolygons and text labels using survey-grade int64 coordinates and feature attributes.

Survey and control networks

Survey blocks model control points, checkpoints, tie points, scan setups, observations, residuals and accuracy metadata.

Grids and transformations

Grid blocks store geoid height grids, horizontal or vertical shift grids, combined transformation grids and transformation definitions. Evaluation of transformations is planned for future versions.

Metadata

Metadata blocks provide typed key/value entries: string, int64, uint64, float64, bool and null. Nested namespaces are represented through dot-separated keys.

Streaming and cloud layout

OPX includes RangeReader, FileRangeReader, CachedRangeReader and a cloud-optimized layout profile. HTTP support is prepared through an optional stub but not yet implemented as a production backend.

Web API export

The reference implementation can export deterministic JSON summaries for dataset info, tiles, schemas, images, vectors, control points, grids and metadata. This prepares future server-side and cloud-native APIs.

C++ SDK

The reference SDK is C++20 and can be consumed with CMake using find_package(OPX CONFIG REQUIRED).

auto dataset = opx::open_dataset("survey.opx");
opx::Box3i bounds{min, max};
auto batches = dataset.query_points(bounds);

CLI tools

LAS interoperability

OPX 0.2.0-dev introduces an interoperability preview for LAS-based workflows. The import/export tools are intended to make OPX easier to evaluate with existing survey and point cloud datasets while preserving the OPX block model for spatial access and future extension.

• opx-import-las converts LAS input into OPX point tiles.
• opx-export-las exports OPX point data for compatibility with existing tools.
• Current documentation and release packages are aligned to the 0.2.0-dev package naming.

Compatibility

Unknown optional blocks are preserved during rewrite. Unknown required blocks fail validation. Payload versions and feature flags allow controlled format evolution.

Known limitations

• No production ZSTD codec yet
• No real HTTP backend yet
• No Python or C# bindings yet
• LAS import/export is available as an interoperability preview; LAZ and E57 remain roadmap items
• PDAL support is currently a plugin skeleton, not a finished production reader/writer
• No coordinate transformation evaluation yet
• No vector spatial index yet
• No production-scale benchmarks yet
• The free OPX Viewer is a product concept, not yet a shipped application