CrossAtlas

CrossAtlas is a cross-reality collaboration platform designed to help users share, communicate, and understand spatial references across VR and desktop environments using synchronized VR-PC views, bidirectional projection techniques, and shared spatial landmarks.

📄 Paper details coming soon

Features

• 🧭 Bidirectional Projection: Four projection techniques (Horizontal, Vertical, PCA, Equirectangular) that transform the VR user's 3D layout into a 2D desktop view in real time, with inverse unprojection so desktop clicks map back into 3D space.
• 🔄 Cross-View Synchronization: Real-time state sync between VR and PC clients using Yjs CRDTs over WebSocket, keeping selections, task progression, and visual feedback consistent across both views with no perceptible delay.
• 🌐 Configurable Spatial Layouts: Parameterized layout curvature from flat front-facing arrangements to fully surrounding Full-Sphere configurations, with angular-distance-based point sampling relative to the VR user's headset.
• 🥽 Browser-Based, Hardware-Agnostic: VR client built with Babylon.js and Anu.js running in WebXR; PC client in React.

Projection Techniques

CrossAtlas implements four bidirectional projection techniques across two families:

Planar

• Horizontal — Top-down (floor plane) view. Preserves lateral layout; collapses vertical structure.
• Vertical — Front-facing (wall plane) view. Preserves left-right and up-down; compresses depth.
• PCA — Adaptive plane maximizing point-cloud variance. Orientation is computed at task start; vertical gradient is used to establish a consistent "up."

Spherical

• Equirectangular — Maps each point to its angular position on a unit sphere around the VR user, then linearly maps longitude and latitude to a 2D rectangle. Provides a continuous 360° panoramic view of the full surrounding space.

For more details, please check out our paper.

Repository Structure

cross-atlas/
├── packages/
│   ├── client-2d/      # PC (2D) client — React + D3, Vite
│   ├── client-3d/      # VR (3D) client — Babylon.js + Anu.js + WebXR, Vite
│   └── shared/         # Shared task definitions, projection math, sync types, logging
├── scripts/
│   ├── dev.mjs                     # Orchestrates full dev stack
│   ├── yws-ssl-server.mjs          # Yjs WebSocket server
│   ├── generate-certs.mjs          # Self-signed SSL cert generation
│   └── generate-point-configs.ts   # Precomputed point selection generator
├── data/
│   └── point-selections.json       # Precomputed angular-distance point selections
└── certs/                          # SSL certificates (not committed)

Quick Start

1. Clone the Repository

git clone https://github.com/AlexanderHYang/cross-atlas.git
cd cross-atlas

2. Install Dependencies

npm install

3. Generate SSL Certificates

The dev server requires HTTPS for WebXR. On first run, certificates are generated automatically if OpenSSL is available:

npm run generate-certs

Certificates are written to certs/ and are not committed to version control.

4. Launch the Full Dev Stack

Start the Yjs WebSocket server and both Vite clients in one terminal:

npm run dev

This starts the Yjs server plus the 3D (VR) and 2D (PC) Vite dev servers. All logs stream in the same window. Ctrl+C stops everything.

• Open the 3D client (e.g. https://<your-ip>:5173) in your VR headset's browser. Accept the self-signed certificate, then click the headset icon to enter immersive mode.
• Open the 2D client (e.g. https://<your-ip>:5174) on a desktop browser.

CLI Flags

Flag	Description
--projection=<equirectangular|pca|vertical|horizontal>	Set projection mode (default: client-selected)
--layout=<spherical|hemispherical|planar>	Set point layout curvature
--tasks=<digits>	Enable specific tasks, e.g. --tasks=13 for Tasks 1 and 3
--require-calibration-orientation=<true|false>	Require VR user to face landmark during calibration
--random-selection=<true|false>	Use randomized angular-distance sampling instead of precomputed selections

Credits

❤️ CrossAtlas is a collaborative project between Georgia Tech and JPMorgan Chase, created by Alex Yang, Chenyang Zhang, Elliott H. Faa, Weijian Liu, Lily Chisholm, Benjamin Lee, David Saffo, Feiyu Lu, Blair MacIntyre, and Yalong Yang.

💙 CrossAtlas builds on WebXR, Babylon.js, and Anu.js (GitHub), an open-source immersive analytics toolkit by JPMorgan Chase. Real-time synchronization is powered by Yjs.

Citation

📚 Citation details coming soon

License

CrossAtlas is available under the MIT License. It uses WebXR (W3C Software and Document License), Babylon.js (Apache 2.0), Anu.js (Apache 2.0), and Yjs (MIT).