@arvarus/perlin-noise 0.1.1

package/dist/index.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * @arvarus/perlin-noise
+ * Perlin noise implementation in TypeScript
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PerlinNoise = exports.getGradientAt = exports.generateGradientGrid = void 0;
+const grid_1 = require("./grid");
+const scalar_1 = require("./scalar");
+const interpolation_1 = require("./interpolation");
+var grid_2 = require("./grid");
+Object.defineProperty(exports, "generateGradientGrid", { enumerable: true, get: function () { return grid_2.generateGradientGrid; } });
+Object.defineProperty(exports, "getGradientAt", { enumerable: true, get: function () { return grid_2.getGradientAt; } });
+/**
+ * PerlinNoise class for generating Perlin noise values
+ */
+class PerlinNoise {
+    /**
+     * Creates a new PerlinNoise instance
+     *
+     * @param options - Configuration options (seed and grid size)
+     */
+    constructor(options) {
+        this.seed = options?.seed ?? Math.floor(Math.random() * 1000000);
+        this.gridSize = options?.gridSize ?? [64, 64, 64];
+        this.dimension = this.gridSize.length;
+        if (this.gridSize.length < 1 || this.gridSize.length > 10) {
+            throw new Error(`Grid size array length must be between 1 and 10, got ${this.gridSize.length}`);
+        }
+        this.grid = (0, grid_1.generateGradientGrid)(this.dimension, this.gridSize, this.seed);
+    }
+    /**
+     * Generate noise value at given coordinates
+     * Supports noise generation for any dimension (1 to 10)
+     *
+     * @param coordinates - Array of coordinates, length must match grid dimension
+     * @returns Noise value in the range approximately [-1, 1]
+     */
+    noise(coordinates) {
+        if (coordinates.length !== this.dimension) {
+            throw new Error(`Coordinates array length (${coordinates.length}) must match grid dimension (${this.dimension})`);
+        }
+        const point = coordinates;
+        const wrappedPoint = point.map((coord, i) => {
+            const size = this.gridSize[i];
+            const wrapped = ((coord % size) + size) % size;
+            return wrapped;
+        });
+        const scalarValues = (0, scalar_1.calculateScalarValues)(this.grid, wrappedPoint);
+        const noiseValue = (0, interpolation_1.interpolateScalarValues)(scalarValues, wrappedPoint);
+        return noiseValue;
+    }
+}
+exports.PerlinNoise = PerlinNoise;

package/dist/interpolation.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Interpolation for Perlin noise
+ * Interpolates between the 2^n scalar products calculated at the vertices of the cell
+ * containing point P. This ensures that the noise function returns 0 at the grid vertices.
+ *
+ * The interpolation uses a function whose first derivative (and possibly
+ * the second derivative) is zero at the 2^n grid nodes. This has the effect that
+ * the gradient of the resulting noise function at each grid node coincides
+ * with the precomputed random gradient vector.
+ */
+/**
+ * Classic smoothstep function used for interpolation
+ * This function ensures that the first derivative is zero at the endpoints (0 and 1)
+ *
+ * @param t - Interpolation value between 0 and 1
+ * @returns Interpolated value between 0 and 1
+ */
+export declare function smoothstep(t: number): number;
+/**
+ * Calculates the fractional coordinates of the point within its cell
+ * Fractional coordinates are in the interval [0, 1] for each dimension
+ *
+ * @param point - Point P as an array of coordinates
+ * @returns Array of fractional coordinates within the cell
+ */
+export declare function calculateFractionalCoordinates(point: number[]): number[];
+/**
+ * Interpolates between two values using smoothstep
+ * For n=1, this function interpolates between a0 at node 0 and a1 at node 1
+ * Formula: f(x) = a0 + smoothstep(x) * (a1 - a0) for 0 ≤ x ≤ 1
+ *
+ * @param a0 - Value at node 0
+ * @param a1 - Value at node 1
+ * @param t - Interpolation parameter between 0 and 1
+ * @returns Interpolated value
+ */
+export declare function interpolate1D(a0: number, a1: number, t: number): number;
+/**
+ * Interpolates between the 2^n scalar products calculated at the vertices of the cell
+ * containing point P. This function ensures that the noise returns 0 at the grid
+ * vertices thanks to the use of smoothstep.
+ *
+ * @param scalarValues - Array of scalar values at the cell vertices (2^n values)
+ * @param point - Point P as an array of coordinates
+ * @returns Interpolated noise value
+ */
+export declare function interpolateScalarValues(scalarValues: number[], point: number[]): number;
+/**
+ * Scales an interpolated value to be in the interval [-1.0, 1.0]
+ * Noise functions used in computer graphics typically produce
+ * values within this interval.
+ *
+ * @param value - Value to scale
+ * @param scaleFactor - Scale factor (default 1.0, no scaling)
+ * @returns Scaled value
+ */
+export declare function scaleNoiseValue(value: number, scaleFactor?: number): number;

package/dist/interpolation.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * Interpolation for Perlin noise
+ * Interpolates between the 2^n scalar products calculated at the vertices of the cell
+ * containing point P. This ensures that the noise function returns 0 at the grid vertices.
+ *
+ * The interpolation uses a function whose first derivative (and possibly
+ * the second derivative) is zero at the 2^n grid nodes. This has the effect that
+ * the gradient of the resulting noise function at each grid node coincides
+ * with the precomputed random gradient vector.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.smoothstep = smoothstep;
+exports.calculateFractionalCoordinates = calculateFractionalCoordinates;
+exports.interpolate1D = interpolate1D;
+exports.interpolateScalarValues = interpolateScalarValues;
+exports.scaleNoiseValue = scaleNoiseValue;
+/**
+ * Classic smoothstep function used for interpolation
+ * This function ensures that the first derivative is zero at the endpoints (0 and 1)
+ *
+ * @param t - Interpolation value between 0 and 1
+ * @returns Interpolated value between 0 and 1
+ */
+function smoothstep(t) {
+    const clamped = Math.max(0, Math.min(1, t));
+    // Smoothstep formula: t² * (3 - 2t)
+    return clamped * clamped * (3 - 2 * clamped);
+}
+/**
+ * Calculates the fractional coordinates of the point within its cell
+ * Fractional coordinates are in the interval [0, 1] for each dimension
+ *
+ * @param point - Point P as an array of coordinates
+ * @returns Array of fractional coordinates within the cell
+ */
+function calculateFractionalCoordinates(point) {
+    return point.map(coord => {
+        const cellCoord = Math.floor(coord);
+        return coord - cellCoord;
+    });
+}
+/**
+ * Interpolates between two values using smoothstep
+ * For n=1, this function interpolates between a0 at node 0 and a1 at node 1
+ * Formula: f(x) = a0 + smoothstep(x) * (a1 - a0) for 0 ≤ x ≤ 1
+ *
+ * @param a0 - Value at node 0
+ * @param a1 - Value at node 1
+ * @param t - Interpolation parameter between 0 and 1
+ * @returns Interpolated value
+ */
+function interpolate1D(a0, a1, t) {
+    const s = smoothstep(t);
+    return a0 + s * (a1 - a0);
+}
+/**
+ * Recursively interpolates between scalar values for a given dimension
+ * This function progressively reduces the number of values by interpolating
+ * dimension by dimension
+ *
+ * @param scalarValues - Array of scalar values (2^n values)
+ * @param fractionalCoords - Fractional coordinates of the point within the cell
+ * @param dimension - Current dimension to interpolate (starts at 0)
+ * @returns Final interpolated value
+ */
+function interpolateRecursive(scalarValues, fractionalCoords, dimension = 0) {
+    if (scalarValues.length === 1) {
+        return scalarValues[0];
+    }
+    if (dimension >= fractionalCoords.length) {
+        if (scalarValues.length === 2) {
+            return interpolate1D(scalarValues[0], scalarValues[1], fractionalCoords[dimension - 1] || 0);
+        }
+        // If we have more than 2 values, take the average (should not happen normally)
+        return scalarValues.reduce((sum, val) => sum + val, 0) / scalarValues.length;
+    }
+    const t = fractionalCoords[dimension];
+    const numValues = scalarValues.length;
+    const valuesPerHalf = numValues / 2;
+    const lowerValues = scalarValues.slice(0, valuesPerHalf);
+    const upperValues = scalarValues.slice(valuesPerHalf);
+    const lowerInterpolated = interpolateRecursive(lowerValues, fractionalCoords, dimension + 1);
+    const upperInterpolated = interpolateRecursive(upperValues, fractionalCoords, dimension + 1);
+    return interpolate1D(lowerInterpolated, upperInterpolated, t);
+}
+/**
+ * Interpolates between the 2^n scalar products calculated at the vertices of the cell
+ * containing point P. This function ensures that the noise returns 0 at the grid
+ * vertices thanks to the use of smoothstep.
+ *
+ * @param scalarValues - Array of scalar values at the cell vertices (2^n values)
+ * @param point - Point P as an array of coordinates
+ * @returns Interpolated noise value
+ */
+function interpolateScalarValues(scalarValues, point) {
+    // Check that the number of scalar values corresponds to 2^n where n is the dimension
+    const dimension = point.length;
+    const expectedCount = Math.pow(2, dimension);
+    if (scalarValues.length !== expectedCount) {
+        throw new Error(`The number of scalar values (${scalarValues.length}) must be equal to 2^${dimension} = ${expectedCount}`);
+    }
+    const fractionalCoords = calculateFractionalCoordinates(point);
+    return interpolateRecursive(scalarValues, fractionalCoords, 0);
+}
+/**
+ * Scales an interpolated value to be in the interval [-1.0, 1.0]
+ * Noise functions used in computer graphics typically produce
+ * values within this interval.
+ *
+ * @param value - Value to scale
+ * @param scaleFactor - Scale factor (default 1.0, no scaling)
+ * @returns Scaled value
+ */
+function scaleNoiseValue(value, scaleFactor = 1.0) {
+    return value * scaleFactor;
+}

package/dist/scalar.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Scalar calculation for Perlin noise
+ * Calculates noise value at a given point by computing dot products
+ * between gradient vectors and distance vectors
+ */
+import { GradientVector } from './grid';
+/**
+ * Calculates the dot product values for all vertices of the cell containing point P
+ *
+ * @param grid - The gradient grid
+ * @param point - The point P as an array of coordinates
+ * @returns An array of dot product values, one for each vertex of the cell
+ */
+export declare function calculateScalarValues(grid: Map<string, GradientVector>, point: number[]): number[];

package/dist/scalar.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Scalar calculation for Perlin noise
+ * Calculates noise value at a given point by computing dot products
+ * between gradient vectors and distance vectors
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateScalarValues = calculateScalarValues;
+const grid_1 = require("./grid");
+/**
+ * Calculates the dot product between two vectors
+ * For 1D case, treats the scalar as a vector of length 1
+ */
+function dotProduct(gradient, distanceVector) {
+    if (typeof gradient === 'number') {
+        // 1D case: gradient is a scalar, distanceVector has one element
+        return gradient * distanceVector[0];
+    }
+    else {
+        // Multi-dimensional case: both are vectors
+        if (gradient.length !== distanceVector.length) {
+            throw new Error(`Gradient vector length (${gradient.length}) must match distance vector length (${distanceVector.length})`);
+        }
+        return gradient.reduce((sum, val, i) => sum + val * distanceVector[i], 0);
+    }
+}
+/**
+ * Generates all vertices of a hypercube cell in n dimensions
+ * Each vertex is represented as an array of coordinates
+ * For a cell at [x0, x1, ..., xn], vertices are at [x0 or x0+1, x1 or x1+1, ..., xn or xn+1]
+ */
+function generateCellVertices(cellCoordinates) {
+    const dimension = cellCoordinates.length;
+    const vertices = [];
+    // Generate all 2^dimension combinations
+    const numVertices = Math.pow(2, dimension);
+    for (let i = 0; i < numVertices; i++) {
+        const vertex = [];
+        for (let d = 0; d < dimension; d++) {
+            // Use bit manipulation to determine if this dimension should be +1
+            const bit = (i >> d) & 1;
+            vertex.push(cellCoordinates[d] + bit);
+        }
+        vertices.push(vertex);
+    }
+    return vertices;
+}
+/**
+ * Calculates the distance vector from point P to a vertex
+ */
+function calculateDistanceVector(point, vertex) {
+    if (point.length !== vertex.length) {
+        throw new Error(`Point dimension (${point.length}) must match vertex dimension (${vertex.length})`);
+    }
+    return point.map((coord, i) => coord - vertex[i]);
+}
+/**
+ * Determines which cell of the grid contains the given point P
+ * Returns the cell coordinates (floor of each coordinate)
+ */
+function findCell(point) {
+    return point.map(coord => Math.floor(coord));
+}
+/**
+ * Calculates the dot product values for all vertices of the cell containing point P
+ *
+ * @param grid - The gradient grid
+ * @param point - The point P as an array of coordinates
+ * @returns An array of dot product values, one for each vertex of the cell
+ */
+function calculateScalarValues(grid, point) {
+    const cellCoordinates = findCell(point);
+    const vertices = generateCellVertices(cellCoordinates);
+    const scalarValues = [];
+    for (const vertex of vertices) {
+        const distanceVector = calculateDistanceVector(point, vertex);
+        const gradient = (0, grid_1.getGradientAt)(grid, vertex);
+        if (gradient === undefined) {
+            throw new Error(`Gradient not found at vertex ${vertex.join(',')}. Point may be outside grid bounds.`);
+        }
+        const dotProductValue = dotProduct(gradient, distanceVector);
+        scalarValues.push(dotProductValue);
+    }
+    return scalarValues;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@arvarus/perlin-noise",
+  "version": "0.1.1",
+  "description": "Perlin noise implementation in TypeScript",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "clean": "rm -rf dist",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "perlin",
+    "noise",
+    "procedural",
+    "generation"
+  ],
+  "author": "",
+  "license": "GPL-3.0",
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.50.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ]
+}