@papit/quaternion 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,138 @@
-# Temporary Holding Version
+# @papit/quaternion
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Quaternion math for 3D rotations that compose and blend without gimbal lock. Reach for it when Euler angles fail in cameras, bones or animation.
+
+![Logo](https://raw.githubusercontent.com/onkelhoy/papit/refs/heads/main/asset/logo.svg)
+
+---
+
+![Type](https://img.shields.io/badge/Type-math:algebra-orange)
+[![Tests](https://github.com/onkelhoy/papit/actions/workflows/pull-request.yml/badge.svg)](https://github.com/onkelhoy/papit/actions/workflows/pull-request.yml)
+[![NPM version](https://img.shields.io/npm/v/@papit/quaternion.svg?logo=npm)](https://www.npmjs.com/package/@papit/quaternion)
+
+---
+
+## Installation
+
+```bash
+npm install @papit/quaternion
+```
+
+## Usage
+
+```js
+import { Quaternion } from "@papit/quaternion";
+
+const turn = Quaternion.fromAxisAngle([0, 0, 1], Math.PI / 2);
+turn.rotate([1, 0, 0]); // about [0, 1, 0]
+```
+
+Combine rotations, `b` runs first:
+
+```js
+import { Quaternion } from "@papit/quaternion";
+
+const a = Quaternion.fromAxisAngle([0, 0, 1], .5);
+const b = Quaternion.fromAxisAngle([1, 0, 0], .25);
+
+const both = Quaternion.multiplyInto(Quaternion.identity, a, b);
+```
+
+Aim one direction at another:
+
+```js
+import { Quaternion } from "@papit/quaternion";
+
+const aim = Quaternion.fromTo([1, 0, 0], [0, 3, 4]);
+```
+
+Blend two rotations and hand the result to a `Matrix4`:
+
+```js
+import { Quaternion } from "@papit/quaternion";
+import { Matrix4 } from "@papit/matrix";
+
+const from = Quaternion.identity;
+const to = Quaternion.fromAxisAngle([0, 1, 0], 2);
+
+const matrix = from.slerp(to, .5).writeMatrix(new Matrix4(), [10, 0, 0]);
+```
+
+## API
+
+### Quaternion
+
+```ts
+class Quaternion extends Vector
+```
+
+Stored as x, y, z, w in a `Float32Array`. Everything below is O(1). Instance methods change the quaternion and return it, except `rotate` and `writeMatrix`, which return their target.
+
+#### Create
+
+| Member | Purpose |
+| --- | --- |
+| `Quaternion.identity` | A new quaternion with no rotation. |
+| `Quaternion.fromAxisAngle(axis, angle)` | A turn in radians around an axis of any length. |
+| `Quaternion.fromTo(from, to)` | The shortest rotation from one direction to another. |
+| `identity()` | Resets to no rotation. |
+| `setAxisAngle(x, y, z, angle)` | `fromAxisAngle` without allocating. |
+| `setFromTo(from, to)` | `fromTo` without allocating. |
+
+#### Combine
+
+| Member | Purpose |
+| --- | --- |
+| `Quaternion.multiplyInto(out, a, b)` | Writes `a * b`, which applies `b` first. `out` can be `a` or `b`. |
+| `conjugate()` | Flips to the inverse, for a unit quaternion. |
+| `normalize()` | Scales to length 1. Do this now and then after many products. |
+| `rotate(point)` | Rotates a 3D point in place. |
+
+#### Blend
+
+| Member | Purpose |
+| --- | --- |
+| `nlerp(target, t)` | Fast blend, the speed isn't constant over large angles. |
+| `slerp(target, t)` | Blend at a constant speed. |
+
+Both take the short way round and return a unit quaternion.
+
+#### Output
+
+```ts
+writeMatrix(out: Float32Array, position?: ArrayLike<number>)
+```
+
+Writes the rotation and position into a column-major 4x4 matrix, such as a `Matrix4`.
+
+### Degenerate input
+
+| Input | Result |
+| --- | --- |
+| Zero axis or zero vector | The identity |
+| Zero quaternion in `normalize` | The identity |
+| Opposite directions in `fromTo` | A half turn around a perpendicular axis |
+
+## Design notes
+
+- `rotate`, `conjugate`, `nlerp`, `slerp` and `writeMatrix` expect a unit quaternion, which everything in Create gives you.
+- `multiply` and `lerp` are inherited from `Vector` and work per component. Use `multiplyInto` to combine rotations and `nlerp` or `slerp` to blend them.
+- Instance methods and `multiplyInto` don't allocate, so they're safe in a frame loop. The static `identity`, `fromAxisAngle` and `fromTo` create a new quaternion.
+
+## License
+
+Licensed under the @Papit License 1.0 - Copyright (c) 2024 Henry Pap (@onkelhoy)
+
+**Key points:**
+
+- ✅ Free to use in commercial projects
+- ✅ Free to modify and distribute
+- ✅ Attribution required
+- ❌ Cannot resell the component itself as a standalone product
+
+See the [LICENSE](https://github.com/onkelhoy/papit/blob/main/LICENSE) file for full details.
+
+## Related
+
+- [@papit/vector](https://github.com/onkelhoy/papit/tree/main/packages/algorithms/math/algebra/vector)
+- [@papit/matrix](https://github.com/onkelhoy/papit/tree/main/packages/algorithms/math/algebra/matrix)

package/asset/translations/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "region": "GB",
+    "language": "en"
+  }
+}

package/lib/bundle.d.ts

@@ -0,0 +1,48 @@
+import { Vector } from '@papit/vector';
+
+declare type Point = ArrayLike<number>;
+
+/**
+ * A 3D rotation stored as x, y, z, w, where a unit quaternion is
+ * `axis * sin(angle / 2), cos(angle / 2)`.
+ * Create one with `Quaternion.identity`, `fromAxisAngle` or `fromTo`.
+ * `multiply` and `lerp` are still Vector's component-wise ones,
+ * use `multiplyInto` to combine rotations and `nlerp` or `slerp` to blend them.
+ */
+export declare class Quaternion extends Vector {
+    /** Sets this to no rotation. */
+    identity(): this;
+    /** Scales to length 1. A zero quaternion isn't a rotation, so it becomes the identity. */
+    normalize(): this;
+    /** Sets this to a turn of `angle` radians around an axis of any length. A zero axis gives the identity. */
+    setAxisAngle(x: number, y: number, z: number, angle: number): this;
+    /**
+     * Sets this to the shortest rotation that turns direction `from` onto direction `to`.
+     * A zero vector has no direction, so it gives the identity.
+     */
+    setFromTo(from: Point, to: Point): this;
+    /** Flips this to its inverse, which undoes a unit quaternion. */
+    conjugate(): this;
+    /** Rotates a 3D point in place and returns it. This has to be a unit quaternion. */
+    rotate<T extends Float32Array | number[]>(point: T): T;
+    /** Moves this towards `target` the short way, normalized: 0 stays, 1 lands on it. Fast, a good fit for small steps. */
+    nlerp(target: Quaternion, t: number): this;
+    /** Moves this towards `target` the short way at a constant speed: 0 stays, 1 lands on it. */
+    slerp(target: Quaternion, t: number): this;
+    /** Writes this rotation and an optional position into a column-major 4x4 matrix. This has to be a unit quaternion. */
+    writeMatrix<T extends Float32Array>(out: T, position?: Point): T;
+    /**
+     * A half turn around the axis `x, y, z` leans on the least, made perpendicular to `x, y, z`.
+     * For a direction in a plane that's the plane's normal, so 2D stays 2D.
+     */
+    private setHalfTurn;
+    /** Writes the Hamilton product `a * b`, which applies `b` first and then `a`. `out` can be `a` or `b`. */
+    static multiplyInto<T extends Float32Array>(out: T, a: Float32Array, b: Float32Array): T;
+    /** A turn of `angle` radians around an axis of any length. */
+    static fromAxisAngle(axis: Point, angle: number): Quaternion;
+    /** The shortest rotation that turns direction `from` onto direction `to`. */
+    static fromTo(from: Point, to: Point): Quaternion;
+    static get identity(): Quaternion;
+}
+
+export { }

package/lib/bundle.js

@@ -0,0 +1 @@
+import{Vector as u}from"@papit/vector";var y=1e-6,d=.9995,m=class b extends u{identity(){return this[0]=0,this[1]=0,this[2]=0,this[3]=1,this}normalize(){let t=Math.hypot(this[0],this[1],this[2],this[3]);return t===0?this.identity():(this[0]/=t,this[1]/=t,this[2]/=t,this[3]/=t,this)}setAxisAngle(t,i,s,h){let n=Math.hypot(t,i,s);if(n===0)return this.identity();let r=Math.sin(h/2)/n;return this[0]=t*r,this[1]=i*r,this[2]=s*r,this[3]=Math.cos(h/2),this}setFromTo(t,i){let s=t[0],h=t[1],n=t[2],r=i[0],e=i[1],c=i[2],a=Math.hypot(s,h,n)*Math.hypot(r,e,c);if(a===0)return this.identity();let o=a+s*r+h*e+n*c;return o<y*a?this.setHalfTurn(s,h,n):(this[0]=h*c-n*e,this[1]=n*r-s*c,this[2]=s*e-h*r,this[3]=o,this.normalize())}conjugate(){return this[0]=-this[0],this[1]=-this[1],this[2]=-this[2],this}rotate(t){let i=this[0],s=this[1],h=this[2],n=this[3],r=t[0],e=t[1],c=t[2],a=2*(s*c-h*e),o=2*(h*r-i*c),l=2*(i*e-s*r);return t[0]=r+n*a+s*l-h*o,t[1]=e+n*o+h*a-i*l,t[2]=c+n*l+i*o-s*a,t}nlerp(t,i){let s=this.dot(t)<0?-1:1;return this[0]+=(t[0]*s-this[0])*i,this[1]+=(t[1]*s-this[1])*i,this[2]+=(t[2]*s-this[2])*i,this[3]+=(t[3]*s-this[3])*i,this.normalize()}slerp(t,i){let s=this.dot(t),h=s<0?-1:1,n=s*h;if(n>d)return this.nlerp(t,i);let r=Math.acos(n),e=Math.sin((1-i)*r),c=Math.sin(i*r)*h;return this[0]=this[0]*e+t[0]*c,this[1]=this[1]*e+t[1]*c,this[2]=this[2]*e+t[2]*c,this[3]=this[3]*e+t[3]*c,this.normalize()}writeMatrix(t,i){let s=this[0],h=this[1],n=this[2],r=this[3];return t[0]=1-2*(h*h+n*n),t[1]=2*(s*h+n*r),t[2]=2*(s*n-h*r),t[3]=0,t[4]=2*(s*h-n*r),t[5]=1-2*(s*s+n*n),t[6]=2*(h*n+s*r),t[7]=0,t[8]=2*(s*n+h*r),t[9]=2*(h*n-s*r),t[10]=1-2*(s*s+h*h),t[11]=0,t[12]=i?i[0]:0,t[13]=i?i[1]:0,t[14]=i?i[2]:0,t[15]=1,t}setHalfTurn(t,i,s){let h=Math.abs(t),n=Math.abs(i),r=Math.abs(s),e=(r<=h&&r<=n?s:n<=h?i:t)/(t*t+i*i+s*s);return this.setAxisAngle((r>h&&n>h?1:0)-t*e,(n<=h&&n<r?1:0)-i*e,(r<=h&&r<=n?1:0)-s*e,Math.PI)}static multiplyInto(t,i,s){let h=i[0],n=i[1],r=i[2],e=i[3],c=s[0],a=s[1],o=s[2],l=s[3];return t[0]=e*c+h*l+n*o-r*a,t[1]=e*a-h*o+n*l+r*c,t[2]=e*o+h*a-n*c+r*l,t[3]=e*l-h*c-n*a-r*o,t}static fromAxisAngle(t,i){return b.identity.setAxisAngle(t[0],t[1],t[2],i)}static fromTo(t,i){return b.identity.setFromTo(t,i)}static get identity(){return new b(0,0,0,1)}};export{m as Quaternion};

package/package.json

@@ -1,6 +1,80 @@
 {
   "name": "@papit/quaternion",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Quaternion math for 3D rotations that compose and blend without gimbal lock. Reach for it when Euler angles fail in cameras, bones or animation.",
+  "keywords": [
+    "papit",
+    "quaternion",
+    "rotation",
+    "3d",
+    "math",
+    "game"
+  ],
+  "version": "0.0.1",
+  "scripts": {
+    "build": "npx @papit/build -- --error --ancestors",
+    "watch": "tsc -w",
+    "start": "npm run build -- --dev && node ./lib/bundle.js",
+    "test": "node --test tests/**/*.test.js",
+    "test:only": "node --test --test-only tests/**/*.test.js",
+    "preversion": "papit-version",
+    "postversion": "papit-version",
+    "component": "npm create @papit -- --component"
+  },
+  "main": "./lib/bundle.js",
+  "types": "./lib/bundle.d.ts",
+  "type": "module",
+  "files": [
+    "asset/",
+    "lib/"
+  ],
+  "exports": {
+    ".": {
+      "import": "./lib/bundle.js",
+      "types": "./lib/bundle.d.ts"
+    }
+  },
+  "author": "henry",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "LicenseRef-Papit-1.0",
+  "homepage": "https://github.com/onkelhoy/papit/tree/main/packages/algorithms/math/algebra/quaternion",
+  "bugs": {
+    "url": "https://github.com/onkelhoy/papit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onkelhoy/papit.git",
+    "directory": "packages/algorithms/math/algebra/quaternion"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@papit/vector": "0.0.2"
+  },
+  "devDependencies": {
+    "@papit/matrix": "0.0.2",
+    "@types/node": "22.10.2",
+    "typescript": "5.9.3"
+  },
+  "browserslist": [
+    "defaults",
+    "not IE 11",
+    "not dead"
+  ],
+  "papit": {
+    "publish": true,
+    "type": "node",
+    "main": "quaternion",
+    "components": {
+      "quaternion": {
+        "className": "Quaternion",
+        "htmlprefix": "pap"
+      }
+    }
+  }
 }