ar-helper-lib

A small, dependency-free helper library for web-based Augmented Reality (AR) and 3D. Use it with WebXR, AR.js, Three.js, or any stack that needs 3D math, camera matrices, and coordinate conversion.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Subpath Imports
• API Reference
• License

Features

• Zero dependencies — Pure JavaScript; no runtime or peer dependencies.
• 3D math — Vectors (vec3), 4×4 matrices (mat4), quaternions (quat).
• Camera — Perspective projection, look-at view matrix, FOV helpers.
• Coordinates — World ↔ NDC ↔ screen, rays from NDC, WebXR transform helpers.
• WebXR — Session and feature detection (immersive-ar, inline, hit-test).
• Subpath exports — Import only what you need.

Requirements

• Node.js 14+ (for running tests or tooling); in the browser any modern environment is fine.

Installation

npm install ar-helper-lib

Quick Start

const {
  create: vec3Create,
  add,
  distance,
  normalize,
  perspective,
  lookAt,
  worldToScreen,
  positionFromXRRigidTransform,
  isImmersiveARSupported,
} = require('ar-helper-lib');

// 3D vectors
const a = vec3Create(1, 0, 0);
const b = vec3Create(0, 1, 0);
const c = add(a, b);           // [1, 1, 0]
const d = distance(a, b);       // ~1.414

// Camera matrices (e.g. for WebGL/WebXR)
const proj = perspective(60, 16/9, 0.1, 100);
const view = lookAt([0, 0, 5], [0, 0, 0], [0, 1, 0]);

// World position to screen (with your view*proj matrix)
const screen = worldToScreen(
  [0, 0, 0],
  viewProjMatrix,
  canvas.width,
  canvas.height
);

// WebXR: get position from frame pose
// positionFromXRRigidTransform(frame.getViewerPose(refSpace).transform)

// Feature detection
const arSupported = await isImmersiveARSupported();

Subpath Imports

const vec3 = require('ar-helper-lib/vec3');
const mat4 = require('ar-helper-lib/mat4');
const quat = require('ar-helper-lib/quat');
const camera = require('ar-helper-lib/camera');
const coordinates = require('ar-helper-lib/coordinates');
const session = require('ar-helper-lib/session');

API Reference

vec3 — ar-helper-lib/vec3

| Function | Description | |-------------|-------------| | create(x, y, z) | Create [x, y, z]. | | clone(v) | Copy vector. | | add(a, b) / subtract(a, b) / scale(v, s) | Arithmetic. | | dot(a, b) / cross(a, b) | Dot and cross product. | | length(v) / lengthSq(v) | Length. | | normalize(v, out?) | Unit vector. | | distance(a, b) / distanceSq(a, b) | Distance between points. | | lerp(a, b, t) | Linear interpolation. | | fromArray(arr, offset) / toArray(v, arr, offset) | Array conversion. | | ZERO, UNIT_X, UNIT_Y, UNIT_Z | Constants. |

mat4 — ar-helper-lib/mat4

| Function | Description | |-------------|-------------| | create() | New 4×4 Float32Array. | | identity(out?) | Identity matrix. | | clone(m) | Copy matrix. | | multiply(a, b, out?) | Matrix product. | | fromArray(arr, offset) / toArray(m, arr, offset) | Array conversion. | | getPosition(m, out?) | Extract position [x, y, z]. | | getScale(m, out?) | Extract scale vector. |

quat — ar-helper-lib/quat

| Function | Description | |-------------|-------------| | create(x, y, z, w) | Create quaternion. | | identity(out?) | Identity quaternion. | | fromEuler(xDeg, yDeg, zDeg, order?, out?) | From Euler angles (e.g. 'XYZ'). | | multiply(a, b, out?) | Quaternion product. | | length(q) / normalize(q, out?) | Length and normalize. | | slerp(a, b, t, out?) | Spherical interpolation. | | fromArray(arr, offset) | From array. |

camera — ar-helper-lib/camera

| Function | Description | |-------------|-------------| | perspective(fovY, aspect, near, far, out?) | Perspective projection (column-major). | | lookAt(eye, target, up, out?) | View matrix. | | verticalFovFromHorizontal(fovXDeg, aspect) | Vertical FOV from horizontal. | | horizontalFovFromVertical(fovYDeg, aspect) | Horizontal FOV from vertical. |

coordinates — ar-helper-lib/coordinates

| Function | Description | |-------------|-------------| | transformPoint(p, m, out?) | Transform point by 4×4 matrix. | | worldToNDC(worldPos, viewProj, out?) | World to normalized device coords. | | ndcToScreen(ndcX, ndcY, width, height) | NDC to pixel coordinates. | | worldToScreen(worldPos, viewProj, w, h, out?) | World to screen pixels. | | ndcToRay(ndcX, ndcY, invProj, out?) | Ray origin and direction from NDC. | | positionFromXRRigidTransform(transform) | [x,y,z] from WebXR transform. | | matrixFromXRRigidTransform(transform, out?) | 4×4 matrix from WebXR transform. |

session — ar-helper-lib/session

| Function | Description | |-------------|-------------| | isBrowser() | Whether running in a browser. | | isWebXRAvailable() | Whether navigator.xr exists. | | isSessionSupported(mode) | Promise: support for 'inline', 'immersive-vr', 'immersive-ar'. | | isImmersiveARSupported() | Promise: immersive AR supported. | | isInlineSupported() | Promise: inline session supported. | | REFERENCE_SPACE_TYPES | Object of reference space type names. | | HIT_TEST_FEATURES | Hit-test / plane feature names. |

License

MIT © ar-helper-lib