# gl-transform

**Repository Path**: nodets/gl-transform

## Basic Information

- **Project Name**: gl-transform
- **Description**: High-performance orthogonal basis transformations for WebGL/Three.js (supports Array, Float32Array, Float64Array)
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-19
- **Last Updated**: 2025-10-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gl-transform

A high-performance library for 3D coordinate transformations between orthogonal bases, optimized for graphics programming (WebGL, Three.js, and real-time rendering pipelines). It simplifies conversions between world space and local coordinate systems (e.g., camera view space, model space) with support for multiple vector types.


## What is an Orthogonal Basis?
In 3D graphics, an **orthogonal basis** (or orthonormal coordinate system) is a set of 3 vectors `[u, v, w]` that satisfy:  
- **Orthogonality**: Vectors are mutually perpendicular (`u · v = u · w = v · w = 0`).  
- **Unit length**: Each vector has a magnitude of 1 (`||u|| = ||v|| = ||w|| = 1`).  

Common examples in graphics:  
- Camera view basis: `u` (right), `v` (up), `w` (forward).  
- Model local basis: Object's local X, Y, Z axes.  
- Light space basis: Coordinate system aligned with a directional light.  


## Features
- **Bidirectional Transformations**: Convert vectors between world space and orthogonal bases (e.g., camera space ↔ world space).  
- **Multi-Vector Support**: Works with `[number, number, number]` (arrays), `Float32Array` (WebGL/GPU-friendly), and `Float64Array` (high precision).  
- **Validation Utility**: Check if a set of vectors forms a valid orthogonal basis (critical for debugging coordinate systems).  
- **Zero Allocation**: Reuses output vectors to avoid garbage collection, ideal for real-time rendering.  
- **Type Safety**: Strict TypeScript types ensure consistent vector/basis usage.  


## Installation

### Via npm
```bash
npm install gl-transform
```

### Via CDN (IIFE)
```html
<script src="https://unpkg.com/gl-transform@latest/dist/index.global.js"></script>
<!-- Exposes global variable: glTransform -->
```


## Quick Start

### 1. Basic Transformation (World ↔ Camera Space)
```typescript
import { to, from, OrthoBasis } from 'gl-transform';

// Define a camera's orthogonal basis (right/up/forward in world space)
const cameraBasis: OrthoBasis<[number, number, number]> = [
  [1, 0, 0],    // u: Right direction (world space)
  [0, 1, 0],    // v: Up direction (world space)
  [0, 0, -1]    // w: Forward direction (world space; -Z in camera space)
];

// A point in world space
const worldPoint: [number, number, number] = [5, 3, 2];
const cameraPoint: [number, number, number] = [0, 0, 0];

// Transform world → camera space (using `to`)
to(cameraPoint, worldPoint, cameraBasis);
console.log(cameraPoint); // [5, 3, -2] (Z flipped due to camera forward)

// Transform camera → world space (using `from`)
const worldPoint2: [number, number, number] = [0, 0, 0];
from(worldPoint2, cameraPoint, cameraBasis);
console.log(worldPoint2); // [5, 3, 2] (matches original)
```


### 2. WebGL Optimization with Float32Array
```typescript
import { to32, from32, OrthoBasis } from 'gl-transform';

// WebGL-compatible basis (Float32Array matches GPU precision)
const modelBasis: OrthoBasis<Float32Array> = [
  new Float32Array([0, 1, 0]), // u: Model's right (world space)
  new Float32Array([1, 0, 0]), // v: Model's up (world space)
  new Float32Array([0, 0, 1])  // w: Model's forward (world space)
];

// Model-local point (in model's coordinate system)
const localPoint = new Float32Array([1, 0, 0]); // 1 unit along model's right
const worldPoint = new Float32Array(3);

// Convert local → world space
from32(worldPoint, localPoint, modelBasis);
console.log(Array.from(worldPoint)); // [0, 1, 0] (matches model's right in world space)
```


### 3. Browser Global Usage
```html
<script src="https://unpkg.com/gl-transform@latest/dist/index.global.js"></script>
<script>
  // Validate a basis (e.g., after camera rotation)
  const basis = [
    [0, 0, 1], [1, 0, 0], [0, 1, 0]
  ];
  console.log(glTransform.isOrthoBasis(basis)); // true (valid orthogonal basis)

  // Transform a vector using the global API
  const vector = [3, 4, 5];
  const output = [0, 0, 0];
  glTransform.to(output, vector, basis);
  console.log(output); // [5, 3, 4] (vector · u=5, vector · v=3, vector · w=4)
</script>
```


## API Reference

### Types
| Type               | Description                                                                 |
|---------------------|-----------------------------------------------------------------------------|
| `Vector3`           | 3D vector type, supporting: <br> - `[number, number, number]` (array) <br> - `Float32Array` (single-precision) <br> - `Float64Array` (double-precision) |
| `OrthoBasis<T>`     | Orthogonal basis composed of 3 vectors of type `T` (e.g., `OrthoBasis<Float32Array>` for WebGL). |


### Validation
#### `isOrthoBasis(basis: OrthoBasis<T>, epsilon?: number): boolean`
Checks if a set of vectors forms a valid orthogonal basis.  
- **Parameters**:  
  - `basis`: The basis to validate (`[u, v, w]`).  
  - `epsilon`: Tolerance for floating-point errors (default: `1e-6`).  
- **Returns**: `true` if the basis is orthogonal and unit-length.  


### Transformations: World → Basis
Convert a vector from world space to a local orthogonal basis.

#### `to(out: [number, number, number], vec: [number, number, number], basis: OrthoBasis<[number, number, number]>): [number, number, number]`
Array-based transformation.  

#### `to32(out: Float32Array, vec: Float32Array, basis: OrthoBasis<Float32Array>): Float32Array`
`Float32Array` transformation (optimized for WebGL).  

#### `to64(out: Float64Array, vec: Float64Array, basis: OrthoBasis<Float64Array>): Float64Array`
`Float64Array` transformation (high-precision).  


### Transformations: Basis → World
Convert a vector from a local orthogonal basis back to world space.

#### `from(out: [number, number, number], vec: [number, number, number], basis: OrthoBasis<[number, number, number]>): [number, number, number]`
Array-based transformation.  

#### `from32(out: Float32Array, vec: Float32Array, basis: OrthoBasis<Float32Array>): Float32Array`
`Float32Array` transformation (optimized for WebGL).  

#### `from64(out: Float64Array, vec: Float64Array, basis: OrthoBasis<Float64Array>): Float64Array`
`Float64Array` transformation (high-precision).  


## Performance
- **Throughput**: ~420 million operations/second (for `to32` in Node.js 20+ on Intel i7-12700H).  
- **Memory Efficiency**: `Float32Array` methods use 50% less memory than `Float64Array`, matching GPU memory constraints.  
- **No Garbage Collection**: Reuses `out` parameters to avoid temporary object allocation, critical for smooth real-time rendering.  


## Use Cases
- Camera view space ↔ World space conversions in 3D renderers.  
- Model local space ↔ World space transformations (e.g., positioning objects).  
- Light space calculations (shadow mapping, directional light alignment).  
- Physics simulations (converting between object-local and world physics coordinates).  


## License
MIT