Omni SpatialQR
The Bridge Between the Physical and Digital Worlds.
The physical world is static. The digital world is limitless. Omni SpatialQR is the bridge between them.
Until now, Augmented Reality required massive friction: forcing users to download heavy apps, scanning weird proprietary markers, or waiting for bloated 3D engines to load. Omni SpatialQR changes the paradigm. It turns standard, everyday QR codes—on business cards, restaurant menus, retail packaging, and real estate signs—into instant, zero-friction spatial interfaces directly in the mobile browser.
README.md
A JavaScript library that calculates camera pose homography from BarcodeDetector API data to project HTML DOM elements and Three.js WebGL models onto physical QR codes via CSS matrix3d transforms.
Installation
<script src="omni-spatial-qr.js"></script>
Minimal Quick Start
const visionAR = new OmniSpatialQR({
container: '#ar-wrapper',
type: 'dynamic'
});
visionAR.start();
The Data Resolution Pipeline
To keep physical QR codes microscopic and fast to scan, you can extract IDs from URLs or use Custom URIs, fetching the heavy data via backend API.
const visionAR = new OmniSpatialQR({
type: 'dynamic',
uriPrefix: 'omni', // Captures "omni:user123"
parseParam: ['id'], // Captures "https://...?id=user123"
assetResolver: async (payload) => {
// Payload is "user123". Hit database.
return { title: "Jane Doe", buttons: [...] };
}
});
Configuration Object API
- container (String): DOM selector for the AR viewport.
- type (String): 'dynamic', 'square', 'text', 'card', 'image', 'video', 'audio', '3d', 'youtube'
- scale (Number): Base scale multiplier (Default 1.0).
- position (String): 'center', 'top', 'bottom', 'left', 'right'.
- gap (Number): Pixel offset if position is not center.
- overlayResolution (Number): Base CSS render matrix (Default 100).
- autoPlay (Boolean): Auto-plays injected media loops.
- showControls (Boolean): Toggles custom SVG HUD overlays.
- textTruncate (Boolean): Truncates strings vs wrapping to paragraph block.
- cameraFacing (String): 'environment' or 'user'.
- enable3D (Boolean): Requires true to dynamically fetch Three.js.
- autoRotate3D (Boolean): Rotates models on Y-axis.
- templates (Object): Maps IDs to hidden DOM elements for custom HTML rendering.
Lifecycle Hooks
- onDetect(data): Fires when payload is extracted.
- onTrackingRestored(): Fires when AR locks physical square.
- onTrackingLost(): Fires when AR loses physical square.
- onClick(data): Fires when UI is tapped.
- onError(err): Captures Camera, WebWorker, and Resolver failures.
Static Generator
const qr = await OmniSpatialQR.generate({
data: 'omni:promo1',
type: 'soft',
size: 300,
color: '#18181b',
bgColor: '#ffffff',
logo: '/logo.png'
});
document.body.appendChild(qr);