dot-product

A high-performance 3D dot product library optimized for graphics programming (WebGL, Three.js, and real-time rendering pipelines). Designed for minimal overhead with support for ESM, CommonJS, and IIFE formats.

Features

• Dual Interfaces: dot for regular arrays and dot64 for Float64Array (optimized for numerical precision).
• Zero Allocation: Pure arithmetic operations—no temporary objects or garbage collection.
• Graphics-Focused: Tuned for 3D vector math in rendering (e.g., normal checks, lighting calculations).
• Multi-Format Support: Works in Node.js (CJS) and browsers (ESM/IIFE) with a global variable (gldot for IIFE).
• Type Safety: Strict TypeScript types included for type checking and IDE autocompletion.

Installation

Via npm

npm install dot-product

Via CDN (IIFE)

<script src="https://unpkg.com/dot-product@latest/dist/index.global.js"></script>
<!-- Exposes global variable: gldot -->

Usage

1. ESM (Modern Bundlers: Webpack, Vite, Rollup)

import { dot, dot64 } from 'dot-product';

// Regular array usage (simple 3D vectors)
const vectorA: [number, number, number] = [1, 2, 3];
const vectorB: [number, number, number] = [4, 5, 6];
const result = dot(vectorA, vectorB); 
console.log(result); // 32 (calculation: 1*4 + 2*5 + 3*6)

// Float64Array usage (high precision/performance)
const preciseA = new Float64Array([1.5, 2.5, 3.5]);
const preciseB = new Float64Array([4.5, 5.5, 6.5]);
const preciseResult = dot64(preciseA, preciseB);
console.log(preciseResult); // 42.5 (1.5*4.5 + 2.5*5.5 + 3.5*6.5)

2. CommonJS (Node.js)

const { dot } = require('dot-product');

const normal = [0, 1, 0]; // Upwards normal vector
const lightDir = [0, -1, 0]; // Light shining downward
const intensity = dot(normal, lightDir); 
console.log(intensity); // -1 (orthogonal in opposite directions)

3. IIFE (Browser Global)

<script src="https://unpkg.com/dot-product@latest/dist/index.global.js"></script>
<script>
  // Check if two vectors are perpendicular (dot product = 0)
  const xAxis = [1, 0, 0];
  const yAxis = [0, 1, 0];
  console.log(gldot.dot(xAxis, yAxis)); // 0 (perpendicular)
</script>

API

dot(a, b)

Computes the dot product of two 3D arrays.

• Parameters:

  • a: [number, number, number] — First 3D vector (x1, y1, z1).
  • b: [number, number, number] — Second 3D vector (x2, y2, z2).

• Returns: number — Dot product result (x1*x2 + y1*y2 + z1*z2).

dot64(a, b)

Computes the dot product of two 3D Float64Array vectors (optimized for precision/performance).

• Parameters:

  • a: Float64Array — First 3D vector (length 3: x1, y1, z1).
  • b: Float64Array — Second 3D vector (length 3: x2, y2, z2).

• Returns: number — Dot product result.

Performance

• Throughput: ~380 million operations/second (for dot64 in Node.js 20+ on Intel i7-12700H).
• Use Cases:
  • Lighting calculations (diffuse/specular intensity).
  • Normal vector comparisons (surface orientation checks).
  • Projection matrix math in 3D rendering.

Module Formats

• ESM: dist/esm/index.js (for modern browsers/bundlers).
• CommonJS: dist/cjs/index.js (for Node.js).
• IIFE: dist/iife/dot-product.js (unminified) / dist/iife/dot-product.min.js (minified, global: gldot).

License

MIT