@metamesh/modeling 0.19.0 → 0.20.0

package/dist/geometry/paths/resampling.js

@@ -1,16 +1,13 @@
-import { curveFailure, normalizeCurveDirection, validateCurvePoint3, } from "../curves/evaluation.js";
+import { curveFailure, validateCurvePoint3 } from "../curves/evaluation.js";
 import { assertSampleVertexCount, createPlanarSampleWriter, createSpatialSampleWriter, resolveSamplingBudget, } from "../curves/sampling.js";
-import { resolveGeometryResolution } from "../resolution.js";
-import { assertSamplingCount, resolveGeometrySamplingLimits } from "../sampling-limits.js";
-const z = (point) => point[2] ?? 0;
-const distance = (a, b) => {
-    const value = Math.hypot(b[0] - a[0], b[1] - a[1], z(b) - z(a));
-    if (!Number.isFinite(value))
-        curveFailure("NON_FINITE_VALUE", "Curve extent exceeds finite arithmetic.");
-    return value;
-};
-function resamplePolyline(path, dimensions, options, createWriter, includeTangents = true) {
+import { assertSamplingCount, resolveGeometrySamplingLimits } from "../sampling/limits.js";
+import { resolveGeometryResolution } from "../sampling/resolution.js";
+import { createPathTraversal, locatePathDistance, pathEdgeLength, writePathPoint, writePathTangent, } from "./traversal.js";
+const isArray = (value) => Array.isArray(value);
+function resamplePolyline(path, dimensions, options, createWriter, output = {}) {
     const maximum = resolveSamplingBudget(options);
+    if (!isArray(path))
+        curveFailure("INVALID_ARGUMENT", "Polyline points must be an array.");
     if (options.closed !== undefined && typeof options.closed !== "boolean")
         curveFailure("INVALID_ARGUMENT", "closed must be a boolean.");
     const closed = options.closed ?? false;
@@ -19,42 +16,35 @@ function resamplePolyline(path, dimensions, options, createWriter, includeTangen
     assertSamplingCount(path.length, "sampleCurve", resolveGeometrySamplingLimits(options.limits).maxPathPoints, "Polyline input exceeds the configured path point ceiling.");
     if (options.segments !== undefined)
         assertSampleVertexCount(options.segments + (closed ? 0 : 1), maximum);
-    // Keep caller point references only within this synchronous operation. Unlike 2D promotion,
-    // normalization needs no extra 3D vector for every input point.
     const points = [];
-    const lengths = [];
-    let total = 0;
-    for (const input of path) {
-        if (input.length !== dimensions)
+    const count = path.length;
+    for (let index = 0; index < count; index++) {
+        const input = path[index];
+        if (!isArray(input) || input.length !== dimensions)
             curveFailure(dimensions === 2 ? "INVALID_ARGUMENT" : "NON_FINITE_VALUE", dimensions === 2
                 ? "Planar curve points must have two coordinates."
                 : "Curve coordinates must be finite three-dimensional points.");
-        if (!input.every(Number.isFinite))
+        const point = output.ownedInput
+            ? input
+            : dimensions === 2
+                ? [input[0], input[1]]
+                : [input[0], input[1], input[2]];
+        if (!output.ownedInput && !point.every(Number.isFinite))
             curveFailure("NON_FINITE_VALUE", "Curve coordinates must be finite three-dimensional points.");
         const previous = points.at(-1);
-        const length = previous === undefined ? 0 : distance(previous, input);
-        if (previous !== undefined && length === 0)
+        if (previous !== undefined && pathEdgeLength(previous, point) === 0)
             continue;
-        total += length;
-        if (!Number.isFinite(total))
-            curveFailure("NON_FINITE_VALUE", "Polyline length exceeds finite arithmetic.");
-        points.push(input);
-        lengths.push(total);
+        points.push(point);
     }
     if (closed) {
-        if (points.length > 1 && distance(points[0], points.at(-1)) === 0) {
+        if (points.length > 1 && pathEdgeLength(points[0], points.at(-1)) === 0) {
             points.pop();
-            lengths.pop();
-            total = lengths.at(-1) ?? 0;
         }
         if (points.length < 3)
             curveFailure("DEGENERATE_GEOMETRY", "A closed polyline needs at least three distinct consecutive points.");
-        total += distance(points.at(-1), points[0]);
-        if (!Number.isFinite(total))
-            curveFailure("NON_FINITE_VALUE", "Polyline length exceeds finite arithmetic.");
-        points.push(points[0]);
-        lengths.push(total);
     }
+    const traversal = createPathTraversal(points, closed);
+    const total = traversal.length;
     if (total === 0)
         curveFailure("DEGENERATE_GEOMETRY", "A zero-length polyline cannot be resampled.");
     const policy = options.segments === undefined
@@ -62,7 +52,7 @@ function resamplePolyline(path, dimensions, options, createWriter, includeTangen
         : undefined;
     const segments = options.segments ??
         (policy?.maxSegmentLength === undefined
-            ? points.length - 1
+            ? points.length - (closed ? 0 : 1)
             : Math.max(closed ? 3 : 1, Math.ceil(total / policy.maxSegmentLength)));
     if (closed && segments < 3)
         curveFailure("INVALID_ARGUMENT", "Closed polyline sampling needs at least three segments.");
@@ -70,39 +60,29 @@ function resamplePolyline(path, dimensions, options, createWriter, includeTangen
     assertSampleVertexCount(vertexCount, maximum);
     const writer = createWriter();
     const point = [0, 0, 0], tangent = [0, 0, 0];
-    let source = 1;
+    let source = 0;
     for (let i = 0; i < vertexCount; i++) {
         const at = total * (i / segments);
-        // At an exact source vertex choose its outgoing edge; the last open endpoint uses its incoming edge.
-        while (source < points.length - 1 && lengths[source] <= at)
-            source++;
-        const a = points[source - 1], b = points[source];
-        if (i === 0 || i === segments) {
-            const endpoint = i === 0 ? points[0] : points.at(-1);
-            point[0] = endpoint[0];
-            point[1] = endpoint[1];
-            point[2] = z(endpoint);
-        }
-        else {
-            const t = (at - lengths[source - 1]) / (lengths[source] - lengths[source - 1]);
-            // Preserve the original direct interpolation order used by existing mechanical paths.
-            point[0] = a[0] + (b[0] - a[0]) * t;
-            point[1] = a[1] + (b[1] - a[1]) * t;
-            point[2] = z(a) + (z(b) - z(a)) * t;
-        }
+        const location = locatePathDistance(traversal, at, source);
+        source = location.edgeIndex;
+        writePathPoint(traversal, location, point);
         validateCurvePoint3(point);
-        if (includeTangents) {
-            tangent[0] = b[0] - a[0];
-            tangent[1] = b[1] - a[1];
-            tangent[2] = z(b) - z(a);
-            normalizeCurveDirection(tangent, tangent);
-        }
+        if (closed &&
+            i === vertexCount - 1 &&
+            point.every((coordinate, axis) => coordinate === (points[0][axis] ?? 0)))
+            curveFailure("DEGENERATE_GEOMETRY", "Closed resampling must not repeat its seam point; select a different segment count.");
+        if (output.tangents !== false)
+            writePathTangent(traversal, location, tangent);
         writer.append(point, tangent);
     }
     return writer.finish();
 }
 /**
  * Resamples a spatial polyline at equal arc lengths with directed outgoing tangents.
+ *
+ * @param path - XYZ points in millimetres; duplicate neighbors are removed.
+ * @param options - Closure and exact intervals or physical edge spacing.
+ *
  * @remarks Open paths retain both endpoints; closed paths include the closing edge and omit the
  * repeated seam. Repeated adjacent inputs and explicit closing duplicates are removed. Physical
  * maxSegmentLength bounds arc-length intervals; exact counts override that policy. Output edges
@@ -115,7 +95,12 @@ function resamplePolyline(path, dimensions, options, createWriter, includeTangen
 export function resamplePolyline3(path, options = {}) {
     return resamplePolyline(path, 3, options, createSpatialSampleWriter);
 }
-/** Resamples a planar polyline with the same point, tangent, seam and budget guarantees as 3D.
+/**
+ * Resamples a planar polyline with the same point, tangent, seam and budget guarantees as 3D.
+ *
+ * @param path - XY points in millimetres; duplicate neighbors are removed.
+ * @param options - Closure and exact intervals or physical edge spacing.
+ *
  * @remarks Only final 2D output vectors are copied and frozen. No immutable 3D intermediate is built.
  * @example
  * ```ts
@@ -133,7 +118,7 @@ export function resamplePath2Points(path, options) {
             points.push([point[0], point[1]]);
         },
         finish: () => points,
-    }), false);
+    }), { tangents: false, ownedInput: true });
 }
 /** Internal points-only writer; avoids calculating and allocating tangents discarded by Path3. */
 export function resamplePath3Points(path, options) {
@@ -143,5 +128,5 @@ export function resamplePath3Points(path, options) {
             points.push([point[0], point[1], point[2]]);
         },
         finish: () => points,
-    }), false);
+    }), { tangents: false, ownedInput: true });
 }

package/dist/geometry/paths/{planar.js → rounding.js}

@@ -1,7 +1,7 @@
 import { GeometryError } from "../errors.js";
 import { length3, normalize3, subtract3 } from "../math/vector3.js";
-import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
-import { path3InputData } from "./path-value.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling/limits.js";
+import { path3InputData } from "./value.js";
 const invalidPath = (message, operation) => {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation });
 };
@@ -12,69 +12,6 @@ const requireFinitePathValues = (values, operation) => {
         });
     }
 };
-const segmentLengths = (path, closed) => path.map((point, index) => {
-    if (!closed && index === path.length - 1)
-        return 0;
-    const next = path[(index + 1) % path.length];
-    const delta = subtract3(next, point);
-    return Math.hypot(delta[0], delta[1], delta[2]);
-});
-/**
- * Places an exact item count at equal arc-length intervals along a sampled path.
- *
- * Coordinates are unit-agnostic. Closed paths must omit their duplicated seam;
- * open paths include both endpoints when `count` is greater than one.
- * Coordinates and total length must be finite. Input points and output placements are each
- * limited by maxPathPoints (default 100000); exact counts exceeding that ceiling reject before length calculation.
- * Closure defaults to the path value's metadata, or false for tuples. An explicit conflicting closure rejects.
- * Invalid arguments and degenerate paths throw GeometryError.
- */
-export const distributeAlongPath = (input, count, closed, limits = {}) => {
-    if (!Number.isInteger(count) || count < 1) {
-        invalidPath("Path distribution count must be a positive integer.", "distributeAlongPath");
-    }
-    const maximum = resolveGeometrySamplingLimits(limits).maxPathPoints;
-    assertSamplingCount(count, "distributeAlongPath", maximum);
-    const { points: path, closed: closePath } = path3InputData(input, closed, limits);
-    if (path.length < (closePath ? 3 : 2)) {
-        invalidPath(`${closePath ? "Closed" : "Open"} distribution paths need more points.`, "distributeAlongPath");
-    }
-    if (closePath && path[0].every((coordinate, axis) => coordinate === path.at(-1)[axis]))
-        invalidPath("Closed distribution paths omit their repeated seam point.", "distributeAlongPath");
-    const lengths = segmentLengths(path, closePath);
-    const total = lengths.reduce((sum, length) => sum + length, 0);
-    requireFinitePathValues([total], "distributeAlongPath");
-    if (!(total > 0))
-        throw new GeometryError("DEGENERATE_GEOMETRY", "Cannot distribute along a zero-length path.", {
-            operation: "distributeAlongPath",
-        });
-    const denominator = closePath ? count : Math.max(1, count - 1);
-    let traversed = 0;
-    let segment = 0;
-    return Array.from({ length: count }, (_, itemIndex) => {
-        const target = total * (itemIndex / denominator);
-        for (; segment < lengths.length; segment += 1) {
-            const length = lengths[segment];
-            if (length === 0)
-                continue;
-            if (target <= traversed + length || segment === lengths.length - 1) {
-                const start = path[segment];
-                const end = path[(segment + 1) % path.length];
-                const amount = Math.min(1, Math.max(0, (target - traversed) / length));
-                return {
-                    position: [
-                        start[0] + (end[0] - start[0]) * amount,
-                        start[1] + (end[1] - start[1]) * amount,
-                        start[2] + (end[2] - start[2]) * amount,
-                    ],
-                    tangent: normalize3(subtract3(end, start)),
-                };
-            }
-            traversed += length;
-        }
-        return invalidPath("Path distribution invariant failed.", "distributeAlongPath");
-    });
-};
 /**
  * Replaces each vertex of a non-duplicated closed polyline with a sampled
  * quadratic corner in the same coordinate system as the input.
@@ -82,8 +19,12 @@ export const distributeAlongPath = (input, count, closed, limits = {}) => {
  * `radius` is the desired tangent distance for a right angle and is capped to
  * 45% of adjacent segment lengths to prevent neighboring corners from crossing.
  * The returned path does not duplicate its closing point.
- * Coordinates and radius must be finite; input and output are each limited by maxPathPoints (default 100000).
- * Requires a closed path value; raw tuples are interpreted as closed. Invalid inputs throw GeometryError.
+ * Invalid coordinates, topology, dimensions, or exhausted budgets throw GeometryError.
+ *
+ * @param input - Closed XYZ path or points in millimetres, without a repeated seam.
+ * @param radius - Positive right-angle tangent distance in millimetres.
+ * @param segmentsPerCorner - Quadratic intervals per corner; a positive integer.
+ * @param limits - Limits on input and rounded path points.
  */
 export const roundClosedPolylinePath = (input, radius, segmentsPerCorner, limits = {}) => {
     const maximum = resolveGeometrySamplingLimits(limits).maxPathPoints;

package/dist/geometry/paths/spline.js

@@ -0,0 +1,116 @@
+import { sampleCubicControlPoints } from "../curves/sampling.js";
+import { GeometryError } from "../errors.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling/limits.js";
+import { pathEdgeLength } from "./traversal.js";
+import { path2, path2InputData, path3, path3InputData, } from "./value.js";
+const fail = (message) => {
+    throw new GeometryError("INVALID_ARGUMENT", message, { operation: "spline" });
+};
+function optionsPolicy(options, input) {
+    if (typeof options !== "object" || options === null || Array.isArray(options))
+        fail("Spline options must be an object.");
+    if (options.closed !== undefined && typeof options.closed !== "boolean")
+        fail("Spline closed must be a boolean.");
+    if (options.segmentsPerSpan !== undefined &&
+        (!Number.isSafeInteger(options.segmentsPerSpan) || options.segmentsPerSpan < 1))
+        fail("segmentsPerSpan must be a positive safe integer.");
+    const maximum = resolveGeometrySamplingLimits(options.limits).maxPathPoints;
+    if (Array.isArray(input) && options.segmentsPerSpan !== undefined)
+        assertSamplingCount((input.length - (options.closed ? 0 : 1)) * options.segmentsPerSpan +
+            (options.closed ? 0 : 1), "spline", maximum);
+    return maximum;
+}
+/** Converts one centripetal Catmull–Rom span into equivalent cubic Bézier controls. */
+function controls(points, edge, closed) {
+    const count = points.length;
+    const start = points[edge], end = points[(edge + 1) % count];
+    const before = points[(edge - 1 + count) % count], after = points[(edge + 2) % count];
+    // Square-root chord lengths define the knots; one-sided secants avoid extrapolated endpoints.
+    const span = Math.sqrt(pathEdgeLength(start, end));
+    const previous = !closed && edge === 0 ? span : Math.sqrt(pathEdgeLength(before, start));
+    const next = !closed && edge === count - 2 ? span : Math.sqrt(pathEdgeLength(end, after));
+    const first = [], second = [];
+    for (let axis = 0; axis < 3; axis++) {
+        const a = start[axis] ?? 0, b = end[axis] ?? 0;
+        const delta = b - a;
+        const incoming = !closed && edge === 0 ? delta : a - (before[axis] ?? 0);
+        const outgoing = !closed && edge === count - 2 ? delta : (after[axis] ?? 0) - b;
+        // Unit-span derivatives become Bézier controls at one third of each endpoint tangent.
+        const firstTangent = (incoming / previous) * span * (span / (previous + span)) +
+            delta * (previous / (previous + span));
+        const secondTangent = delta * (next / (span + next)) + (outgoing / next) * span * (span / (span + next));
+        first.push(a + firstTangent / 3);
+        second.push(b - secondTangent / 3);
+    }
+    return [
+        [start[0], start[1], start[2] ?? 0],
+        first,
+        second,
+        [end[0], end[1], end[2] ?? 0],
+    ];
+}
+function splinePoints(points, closed, options, maximum) {
+    if (points.length < (closed ? 3 : 2))
+        fail("Open splines need two waypoints; closed splines need three.");
+    const spans = points.length - (closed ? 0 : 1);
+    // Every span needs an output edge, even before adaptive physical refinement.
+    assertSamplingCount(spans * (options.segmentsPerSpan ?? 1) + (closed ? 0 : 1), "spline", maximum);
+    for (let edge = 0; edge < spans; edge++)
+        if (pathEdgeLength(points[edge], points[(edge + 1) % points.length]) === 0)
+            fail("Spline waypoints must not contain adjacent duplicates or a repeated closed seam.");
+    const result = [points[0]];
+    for (let edge = 0; edge < spans; edge++) {
+        const omitSeam = closed && edge === spans - 1;
+        // Reserve one endpoint for each later span; the final closed endpoint is not retained.
+        const reserved = spans - edge - 1 - (closed ? 1 : 0);
+        const budget = maximum - result.length - reserved + 1;
+        sampleCubicControlPoints(controls(points, edge, closed), {
+            ...(options.segmentsPerSpan === undefined ? {} : { segments: options.segmentsPerSpan }),
+            ...(options.resolution === undefined ? {} : { resolution: options.resolution }),
+            limits: options.limits ?? {},
+            maxVertices: budget,
+        }, (sample, endpoint) => {
+            if (omitSeam && endpoint)
+                return;
+            result.push((points[0].length === 2
+                ? [sample[0], sample[1]]
+                : [sample[0], sample[1], sample[2]]));
+        });
+    }
+    return result;
+}
+/**
+ * Samples an immutable XY centripetal Catmull–Rom path through every waypoint in traversal order.
+ * Open endpoints use one-sided secants; closed paths are periodic and omit their repeated seam.
+ * Adjacent duplicate waypoints reject. The default physical policy bounds each cubic control hull;
+ * segmentsPerSpan instead selects exact uniform parameters per span. Sampling never coarsens to fit
+ * maxPathPoints. Invalid topology, nonfinite arithmetic, and exhausted budgets throw GeometryError.
+ *
+ * @param input - XY waypoints in millimetres; path values retain closure.
+ *
+ * @example
+ * ```ts
+ * const route = spline2([[0, 0], [10, 8], [25, 0]], { resolution: { maxChordError: 0.02 } });
+ * ```
+ */
+export function spline2(input, options = {}) {
+    const maximum = optionsPolicy(options, input);
+    const data = path2InputData(input, options.closed, options.limits);
+    return path2(splinePoints(data.points, data.closed, options, maximum), {
+        closed: data.closed,
+        limits: options.limits ?? {},
+    });
+}
+/**
+ * Samples an immutable XYZ centripetal Catmull–Rom path with the same interpolation, seam, sampling, and ceiling rules as spline2.
+ *
+ * @param input - XYZ waypoints in millimetres; path values retain closure.
+ */
+export function spline3(input, options = {}) {
+    const maximum = optionsPolicy(options, input);
+    const data = path3InputData(input, options.closed, options.limits);
+    return path3(splinePoints(data.points, data.closed, options, maximum), {
+        closed: data.closed,
+        limits: options.limits ?? {},
+    });
+}

package/dist/geometry/paths/traversal.js

@@ -0,0 +1,107 @@
+import { GeometryError } from "../errors.js";
+import { interpolateCoordinate } from "../math/interpolation.js";
+const fail = (message, code) => {
+    throw new GeometryError(code, message, { operation: "path" });
+};
+/** Internal finite edge length without a temporary vector. */
+export function pathEdgeLength(a, b) {
+    const length = Math.hypot(b[0] - a[0], b[1] - a[1], (b[2] ?? 0) - (a[2] ?? 0));
+    if (!Number.isFinite(length))
+        fail("Path extent exceeds finite arithmetic.", "NON_FINITE_VALUE");
+    return length;
+}
+/** Internal allocation-free measurement for paths that do not need an arc-length index. */
+export function measurePathLength(points, closed) {
+    let length = 0;
+    const count = closed ? points.length : Math.max(0, points.length - 1);
+    for (let edge = 0; edge < count; edge++) {
+        length += pathEdgeLength(points[edge], points[(edge + 1) % points.length]);
+        if (!Number.isFinite(length))
+            fail("Path length exceeds finite arithmetic.", "NON_FINITE_VALUE");
+    }
+    return length;
+}
+/** Internal index over already captured coordinates; no caller data is retained by public factories. */
+export function createPathTraversal(points, closed) {
+    const cumulative = [0];
+    const count = closed ? points.length : Math.max(0, points.length - 1);
+    let length = 0;
+    let lastNonzeroEdge = -1;
+    for (let edge = 0; edge < count; edge++) {
+        const edgeLength = pathEdgeLength(points[edge], points[(edge + 1) % points.length]);
+        if (edgeLength > 0)
+            lastNonzeroEdge = edge;
+        length += edgeLength;
+        if (!Number.isFinite(length))
+            fail("Path length exceeds finite arithmetic.", "NON_FINITE_VALUE");
+        cumulative.push(length);
+    }
+    return { points, closed, cumulative, length, lastNonzeroEdge };
+}
+/** Internal strict distance check; callers must not silently clamp authored ranges. */
+export function validatePathDistance(distance, length) {
+    if (!Number.isFinite(distance))
+        fail("Path distance must be finite.", "NON_FINITE_VALUE");
+    if (distance < 0 || distance > length)
+        fail("Path distance must be between zero and its total length.", "INVALID_ARGUMENT");
+}
+/**
+ * Internal outgoing-edge lookup. Zero-length edges are skipped; an open final endpoint uses its
+ * incoming edge, and a closed final endpoint uses the outgoing seam. A cursor keeps ordered scans linear.
+ */
+export function locatePathDistance(traversal, distance, cursor) {
+    const { cumulative, length, closed } = traversal;
+    validatePathDistance(distance, length);
+    if (length === 0)
+        fail("A zero-length path has no usable edge.", "DEGENERATE_GEOMETRY");
+    const count = cumulative.length - 1;
+    if (distance === length && !closed) {
+        return { edgeIndex: traversal.lastNonzeroEdge, fraction: 1 };
+    }
+    const target = distance === length ? 0 : distance;
+    let edgeIndex;
+    if (cursor !== undefined && target >= cumulative[cursor]) {
+        edgeIndex = cursor;
+        while (edgeIndex < count - 1 && cumulative[edgeIndex + 1] <= target)
+            edgeIndex++;
+    }
+    else {
+        // Upper bound selects the outgoing edge and skips repeated cumulative distances.
+        let low = 0, high = count - 1;
+        while (low < high) {
+            const middle = Math.floor((low + high) / 2);
+            if (cumulative[middle + 1] <= target)
+                low = middle + 1;
+            else
+                high = middle;
+        }
+        edgeIndex = low;
+    }
+    return {
+        edgeIndex,
+        fraction: (target - cumulative[edgeIndex]) / (cumulative[edgeIndex + 1] - cumulative[edgeIndex]),
+    };
+}
+/** Internal interpolation into owned scratch or output coordinates, preserving exact vertices. */
+export function writePathPoint(traversal, location, result) {
+    const a = traversal.points[location.edgeIndex], b = traversal.points[(location.edgeIndex + 1) % traversal.points.length];
+    for (let axis = 0; axis < 3; axis++)
+        result[axis] = interpolateCoordinate(a[axis] ?? 0, b[axis] ?? 0, location.fraction);
+}
+/** Internal unit edge tangent; coordinate units do not introduce a normalization threshold. */
+export function writePathTangent(traversal, location, result) {
+    const a = traversal.points[location.edgeIndex], b = traversal.points[(location.edgeIndex + 1) % traversal.points.length];
+    let length = pathEdgeLength(a, b);
+    let x = b[0] - a[0], y = b[1] - a[1], z = (b[2] ?? 0) - (a[2] ?? 0);
+    if (length < 2 ** -1022) {
+        // Subnormal hypotenuses lose relative precision; normalize their scaled components instead.
+        const maximum = Math.max(Math.abs(x), Math.abs(y), Math.abs(z));
+        x /= maximum;
+        y /= maximum;
+        z /= maximum;
+        length = Math.hypot(x, y, z);
+    }
+    result[0] = x / length;
+    result[1] = y / length;
+    result[2] = z / length;
+}