@genart-dev/projection 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,301 @@
+/** 2D vector. */
+interface Vec2 {
+    readonly x: number;
+    readonly y: number;
+}
+/** 3D vector. Y-up, right-handed coordinate system. */
+interface Vec3 {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+/**
+ * 4x4 matrix stored as a 16-element Float64Array in column-major order.
+ *
+ * Column-major layout (OpenGL convention):
+ * ```
+ * | m[0]  m[4]  m[8]   m[12] |
+ * | m[1]  m[5]  m[9]   m[13] |
+ * | m[2]  m[6]  m[10]  m[14] |
+ * | m[3]  m[7]  m[11]  m[15] |
+ * ```
+ */
+type Mat4 = Float64Array;
+/** Camera definition. Perspective or orthographic projection. */
+interface Camera {
+    /** Camera position in world space. */
+    readonly position: Vec3;
+    /** Look-at target in world space. */
+    readonly target: Vec3;
+    /** Up vector. Default (0, 1, 0). */
+    readonly up: Vec3;
+    /** Vertical field of view in degrees (perspective mode). */
+    readonly fov: number;
+    /** Near clip distance. */
+    readonly near: number;
+    /** Far clip distance. */
+    readonly far: number;
+    /** Projection type. */
+    readonly projection: "perspective" | "orthographic";
+    /** World units visible vertically (orthographic mode only). */
+    readonly orthoScale?: number;
+}
+/** Screen viewport rectangle. */
+interface Viewport {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** Result of projecting a 3D point to screen space. */
+interface ProjectedPoint {
+    /** Screen X coordinate. */
+    readonly x: number;
+    /** Screen Y coordinate. */
+    readonly y: number;
+    /** Normalized depth: 0 (near) to 1 (far). For sorting and atmosphere. */
+    readonly depth: number;
+    /** World-to-screen scale factor at this depth. */
+    readonly scale: number;
+    /** Whether the point is within the camera frustum. */
+    readonly visible: boolean;
+    /** World-unit distance from camera position. */
+    readonly distance: number;
+}
+/** Axis-aligned bounding box in 3D. */
+interface BoundingBox3D {
+    readonly min: Vec3;
+    readonly max: Vec3;
+}
+
+/** Create a Vec3. */
+declare function vec3(x: number, y: number, z: number): Vec3;
+/** Add two vectors. */
+declare function add(a: Vec3, b: Vec3): Vec3;
+/** Subtract b from a. */
+declare function sub(a: Vec3, b: Vec3): Vec3;
+/** Scale a vector by a scalar. */
+declare function scale(v: Vec3, s: number): Vec3;
+/** Dot product. */
+declare function dot(a: Vec3, b: Vec3): number;
+/** Cross product. */
+declare function cross(a: Vec3, b: Vec3): Vec3;
+/** Vector length. */
+declare function length(v: Vec3): number;
+/** Squared length (avoids sqrt). */
+declare function lengthSq(v: Vec3): number;
+/** Normalize to unit length. Returns zero vector if input is zero length. */
+declare function normalize(v: Vec3): Vec3;
+/** Negate a vector. */
+declare function negate(v: Vec3): Vec3;
+/** Linear interpolation between two vectors. */
+declare function lerp(a: Vec3, b: Vec3, t: number): Vec3;
+/** Distance between two points. */
+declare function distance(a: Vec3, b: Vec3): number;
+/** Squared distance (avoids sqrt). */
+declare function distanceSq(a: Vec3, b: Vec3): number;
+
+/** Create an identity matrix. */
+declare function identity(): Mat4;
+/**
+ * Build a view matrix (world-to-camera transform).
+ * Uses right-handed convention: camera looks along -Z in view space.
+ */
+declare function lookAt(eye: Vec3, target: Vec3, up: Vec3): Mat4;
+/** Build a perspective projection matrix. */
+declare function perspectiveMatrix(fovDegrees: number, aspect: number, near: number, far: number): Mat4;
+/** Build an orthographic projection matrix. */
+declare function orthographicMatrix(left: number, right: number, bottom: number, top: number, near: number, far: number): Mat4;
+/** Multiply two 4x4 matrices: result = a * b. */
+declare function multiply(a: Mat4, b: Mat4): Mat4;
+/**
+ * Invert a 4x4 matrix. Returns null if the matrix is singular.
+ * Uses cofactor expansion.
+ */
+declare function invert(m: Mat4): Mat4 | null;
+/** Transform a Vec3 by a Mat4 as a point (w=1). Returns the projected Vec3 after w-divide. */
+declare function transformPoint(m: Mat4, v: Vec3): Vec3;
+/** Transform a Vec3 by a Mat4 as a direction (w=0). No w-divide. */
+declare function transformDirection(m: Mat4, v: Vec3): Vec3;
+/**
+ * Transform a Vec3 by a Mat4 and return the raw clip-space coordinates
+ * (x, y, z, w) before w-divide. Used by projection.
+ */
+declare function transformPointRaw(m: Mat4, v: Vec3): {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+};
+
+/** Create a camera with sensible defaults. */
+declare function createCamera(options?: Partial<Camera>): Camera;
+/** Create a new camera with updated properties. */
+declare function updateCamera(camera: Camera, updates: Partial<Camera>): Camera;
+/** Compute the combined view-projection matrix for a camera and viewport. */
+declare function viewProjectionMatrix(camera: Camera, viewport: Viewport): Mat4;
+
+/**
+ * Project a world-space point to screen coordinates.
+ *
+ * Screen coordinates: (0,0) = top-left of viewport, (width, height) = bottom-right.
+ * Depth: 0 = near plane, 1 = far plane.
+ */
+declare function project(point: Vec3, camera: Camera, viewport: Viewport): ProjectedPoint;
+/**
+ * Project a world-space point using a precomputed view-projection matrix.
+ * Use this when projecting many points with the same camera to avoid
+ * recomputing the matrix for each point.
+ */
+declare function projectWithMatrix(point: Vec3, vpMatrix: Mat4, camera: Camera, viewport: Viewport): ProjectedPoint;
+/**
+ * Project many points efficiently using a single precomputed matrix.
+ */
+declare function projectMany(points: Vec3[], camera: Camera, viewport: Viewport): ProjectedPoint[];
+/**
+ * Unproject a screen point back to world space.
+ *
+ * @param screenX - Screen X coordinate
+ * @param screenY - Screen Y coordinate
+ * @param depth - Normalized depth 0 (near) to 1 (far)
+ * @param camera - Camera
+ * @param viewport - Viewport
+ * @returns World-space position, or null if the matrix is singular
+ */
+declare function unproject(screenX: number, screenY: number, depth: number, camera: Camera, viewport: Viewport): Vec3 | null;
+
+/**
+ * Test if a point is inside the camera frustum (after projection, inside NDC cube).
+ */
+declare function frustumContainsPoint(point: Vec3, camera: Camera, viewport: Viewport): boolean;
+/**
+ * Test a bounding box against the camera frustum.
+ * Returns 'inside' if fully contained, 'intersect' if partially visible, 'outside' if not visible.
+ *
+ * Uses a conservative test: projects all 8 corners and checks NDC bounds.
+ */
+declare function frustumContainsBox(box: BoundingBox3D, camera: Camera, viewport: Viewport): "inside" | "intersect" | "outside";
+/**
+ * Test if a face is a back face (facing away from the camera).
+ * Uses the dot product between the face normal and the camera-to-face direction.
+ */
+declare function isBackFace(faceNormal: Vec3, faceCenter: Vec3, camera: Camera): boolean;
+/**
+ * Get the world-to-screen scale factor at a given world point.
+ * Returns how many screen pixels correspond to 1 world unit at that depth.
+ */
+declare function scaleAtDepth(worldPoint: Vec3, camera: Camera, viewport: Viewport): number;
+/**
+ * Get the normalized depth (0 = near plane, 1 = far plane) of a world point.
+ */
+declare function normalizedDepth(point: Vec3, camera: Camera, viewport: Viewport): number;
+/**
+ * Get the world-unit distance from the camera to a point.
+ */
+declare function distanceTo(point: Vec3, camera: Camera): number;
+/**
+ * Compute the screen Y coordinate of the horizon line.
+ * The horizon is where the camera's look direction intersects Y = camera.position.y
+ * at infinite distance, projected to screen space.
+ */
+declare function horizonScreenY(camera: Camera, viewport: Viewport): number;
+/**
+ * Derive vanishing point screen positions from a camera.
+ *
+ * - `left`: VP for lines parallel to the world X axis (projects to screen position)
+ * - `right`: VP for lines parallel to the world -X axis (same point, opposite direction)
+ * - `vertical`: VP for lines parallel to the world Y axis (only meaningful for 3-point perspective)
+ *
+ * Returns undefined for a VP direction if it projects behind the camera.
+ */
+declare function deriveVanishingPoints(camera: Camera, viewport: Viewport): {
+    left?: Vec2;
+    right?: Vec2;
+    vertical?: Vec2;
+};
+
+/**
+ * Sort items by depth (back-to-front by default: farthest first).
+ * Uses squared distance to avoid sqrt per item.
+ */
+declare function depthSort<T>(items: T[], positionFn: (item: T) => Vec3, camera: Camera): T[];
+/**
+ * Return indices sorted by depth (back-to-front: farthest first).
+ */
+declare function depthSortIndices(positions: Vec3[], camera: Camera): number[];
+
+/**
+ * Landscape camera — standing eye-height, looking toward distant horizon.
+ * Default: 1.7m eye height, 60° FOV, looking slightly above horizon.
+ */
+declare function landscapeCamera(options?: {
+    eyeHeight?: number;
+    lookDistance?: number;
+    lookElevation?: number;
+    fov?: number;
+}): Camera;
+/**
+ * Aerial camera — elevated position looking down at an angle.
+ * Default: 200m altitude, 45° down, 50° FOV.
+ */
+declare function aerialCamera(options?: {
+    altitude?: number;
+    lookAngle?: number;
+    fov?: number;
+}): Camera;
+/**
+ * Street-level camera — eye-height, optionally rotated horizontally.
+ * Default: 1.7m, straight ahead, 55° FOV (natural perspective).
+ */
+declare function streetCamera(options?: {
+    eyeHeight?: number;
+    lookDirection?: number;
+    fov?: number;
+}): Camera;
+/**
+ * Worm's-eye camera — low position looking upward.
+ * Default: 0.3m height, 60° tilt upward, 75° FOV (dramatic).
+ */
+declare function wormEyeCamera(options?: {
+    groundLevel?: number;
+    tiltAngle?: number;
+    fov?: number;
+}): Camera;
+/**
+ * Isometric camera — orthographic projection at a fixed angle.
+ * Default: 30° angle, 100 units visible vertically.
+ */
+declare function isometricCamera(options?: {
+    angle?: number;
+    distance?: number;
+    orthoScale?: number;
+}): Camera;
+
+/** Linear interpolation between two cameras. */
+declare function lerpCamera(a: Camera, b: Camera, t: number): Camera;
+/**
+ * Orbit the camera around a center point.
+ *
+ * @param camera - Current camera
+ * @param angleX - Horizontal rotation in radians (positive = rotate right)
+ * @param angleY - Vertical rotation in radians (positive = rotate up)
+ * @param center - Orbit center (defaults to camera target)
+ */
+declare function orbitCamera(camera: Camera, angleX: number, angleY: number, center?: Vec3): Camera;
+/**
+ * Dolly the camera forward/backward along its look direction.
+ *
+ * @param camera - Current camera
+ * @param distance - Positive = move toward target, negative = move away
+ */
+declare function dollyCamera(camera: Camera, distance: number): Camera;
+/**
+ * Pan the camera (shift left/right/up/down) without changing the look direction.
+ *
+ * @param camera - Current camera
+ * @param dx - World units to move right (negative = left)
+ * @param dy - World units to move up (negative = down)
+ */
+declare function panCamera(camera: Camera, dx: number, dy: number): Camera;
+
+export { type BoundingBox3D, type Camera, type Mat4, type ProjectedPoint, type Vec2, type Vec3, type Viewport, add, aerialCamera, createCamera, cross, depthSort, depthSortIndices, deriveVanishingPoints, distance, distanceSq, distanceTo, dollyCamera, dot, frustumContainsBox, frustumContainsPoint, horizonScreenY, identity, invert, isBackFace, isometricCamera, landscapeCamera, length, lengthSq, lerpCamera, lerp as lerpVec3, lookAt, multiply, negate, normalize, normalizedDepth, orbitCamera, orthographicMatrix, panCamera, perspectiveMatrix, project, projectMany, projectWithMatrix, scaleAtDepth, scale as scaleVec3, streetCamera, sub, transformDirection, transformPoint, transformPointRaw, unproject, updateCamera, vec3, viewProjectionMatrix, wormEyeCamera };