Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
feat(uv): map projectUV to a fixed physical length (#216) (#230)
Matthew Kissinger9cdd01ac331b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e4b1c2d2..aefcbac7 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -69,6 +69,13 @@ does not publish a package.contract lists them too. The new `kiln validate <program.js|ref> [--json]` serves the same`kiln_validate` check from the CLI, prints the `programRef` and exits 1 when the source isinvalid; the generic rejection advice names both forms.+- Add metric UV projection ([#216](https://github.com/instruktlabs/kiln/issues/216)).+ `projectUV` accepts `metersPerUnit`: one UV unit maps to that length, measured from the+ frame origin, so parts of different size tile at the same texel density and pieces that+ share a frame keep the same phase. A full cylindrical wrap rounds to whole tiles at the+ largest radius so the seam stays continuous. Calls without it are unchanged. The contract+ and geometry docs say to weld the non-indexed output with `mergeVertices` where the+ projection is continuous.## 1.3.1 (2026-10-17)diff --git a/dist/agent-run.mjs b/dist/agent-run.mjsindex 981821b3..160cb8b1 100644--- a/dist/agent-run.mjs+++ b/dist/agent-run.mjs@@ -5581,7 +5581,7 @@ var REMOVED_AUTHORING_HELPERS, geometryPrimitives;var init_geometry_catalog = __esm(() => {REMOVED_AUTHORING_HELPERS = Object.freeze({boxUnwrap: 'Preserve existing UVs with direct geometry sharing or copyGeometry. Generate new face mappings explicitly with projectUV(geo, { projection: "box", frame? }); planar projection is a separate mode.',- cylinderUnwrap: 'Preserve valid built-in UVs with direct sharing or copyGeometry. For cylindrical mapping use projectUV(geo, { projection: "cylindrical", frame?, seamDegrees?, angularRange?, caps? }); partial arcs need an explicit angularRange.',+ cylinderUnwrap: 'Preserve valid built-in UVs with direct sharing or copyGeometry. For cylindrical mapping use projectUV(geo, { projection: "cylindrical", frame?, seamDegrees?, angularRange?, caps?, metersPerUnit? }); partial arcs need an explicit angularRange; metersPerUnit fixes texel density.',planeUnwrap: 'Use projectUV(geo, { projection: "planar", frame? }) to generate frame-XY UVs. Preserve existing UVs with direct sharing or copyGeometry instead.',cloneGeometry: "Pass the original geometry directly for intentional sharing. Use copyGeometry only for independent editable buffers; the removed helper returned its input.",cloneMaterial: "Pass the original material directly for intentional sharing. Use copyMaterial for independent properties; referenced textures remain shared.",@@ -5591,10 +5591,10 @@ var init_geometry_catalog = __esm(() => {geometryPrimitives = [{name: "projectUV",- signature: "projectUV(geometry: BufferGeometry, opts: { projection: 'planar'|'box'|'cylindrical', frame?: { origin?: [x,y,z], rotation?: [xDeg,yDeg,zDeg] }, seamDegrees?: number, angularRange?: [startDeg,sweepDeg], caps?: 'planar'|'side' })",+ signature: "projectUV(geometry: BufferGeometry, opts: { projection: 'planar'|'box'|'cylindrical', frame?: { origin?: [x,y,z], rotation?: [xDeg,yDeg,zDeg] }, seamDegrees?: number, angularRange?: [startDeg,sweepDeg], caps?: 'planar'|'side', metersPerUnit?: number })",returns: "THREE.BufferGeometry (owned, non-indexed triangle corners)",category: "uv",- description: "Generates UV0 explicitly in a rigid geometry-local frame. Planar maps XY; box maps each face; cylindrical wraps frame Y with separate caps and split angular seams. Replaces existing UVs and removes stale tangents. To preserve good UVs use direct sharing or copyGeometry instead.",+ description: "Generates UV0 explicitly in a rigid geometry-local frame. Planar maps XY; box maps each face; cylindrical wraps frame Y with separate caps and split angular seams. Replaces existing UVs and removes stale tangents. metersPerUnit maps one UV unit to a fixed length so parts of different size tile at the same density. To preserve good UVs use direct sharing or copyGeometry instead.",example: "const mapped = projectUV(rawGeometry, { projection: 'cylindrical', frame: { rotation: [0,0,-90] }, seamDegrees: 180 });"},{@@ -29872,7 +29872,7 @@ var init_uv = __esm(() => {// src/uv-project.tsimport * as THREE46 from "three";function projectUV(geometry, options) {- if (!options || typeof options !== "object" || Array.isArray(options) || !["planar", "box", "cylindrical"].includes(options.projection) || Object.keys(options).some((key) => !["projection", "frame", "seamDegrees", "angularRange", "caps"].includes(key)))+ if (!options || typeof options !== "object" || Array.isArray(options) || !["planar", "box", "cylindrical"].includes(options.projection) || Object.keys(options).some((key) => !["projection", "frame", "seamDegrees", "angularRange", "caps", "metersPerUnit"].includes(key)))throw new Error("projectUV: select an explicit planar, box or cylindrical projection with documented options.");const cylinder = options.projection === "cylindrical";if (!cylinder && [options.seamDegrees, options.angularRange, options.caps].some((value) => value !== undefined))@@ -29883,6 +29883,9 @@ function projectUV(geometry, options) {throw new Error("projectUV: angularRange must be [finite start degrees, positive sweep <=360].");if (options.caps !== undefined && options.caps !== "planar" && options.caps !== "side")throw new Error("projectUV: caps must be planar or side.");+ const metric = options.metersPerUnit;+ if (metric !== undefined && !(typeof metric === "number" && Number.isFinite(metric) && metric > 0))+ throw new Error("projectUV: metersPerUnit must be a positive finite length.");const inverse = geometryFrameMatrix(options.frame).invert();const positions = geometry.getAttribute("position");if (positions?.itemSize !== 3 || positions.count < 1 || positions.count > MAX_CORNERS)@@ -29917,13 +29920,19 @@ function projectUV(geometry, options) {bounds.expandByPoint(point);}const extent = bounds.getSize(new THREE46.Vector3);- const fit = (point, axis) => extent[axis] > 0 ? (point[axis] - bounds.min[axis]) / extent[axis] : 0.5;+ const fit = (point, axis) => metric !== undefined ? point[axis] / metric : extent[axis] > 0 ? (point[axis] - bounds.min[axis]) / extent[axis] : 0.5;+ const flip = (point, axis) => metric !== undefined ? -point[axis] / metric : 1 - fit(point, axis);const outputUVs = new Float32Array(corners * 2);const startDegrees = options.angularRange?.[0] ?? options.seamDegrees ?? 180;const start = startDegrees % 360 * Math.PI / 180;const sweep = (options.angularRange?.[1] ?? 360) * Math.PI / 180;const fullWrap = options.angularRange === undefined || options.angularRange[1] === 360;const wrap = (angle) => (angle % (2 * Math.PI) + 2 * Math.PI) % (2 * Math.PI);+ let uScale = 1;+ if (metric !== undefined) {+ const radius = points.reduce((max, point) => Math.max(max, Math.hypot(point.x, point.z)), 0);+ uScale = fullWrap ? Math.max(1, Math.round(2 * Math.PI * radius / metric)) : sweep * radius / metric;+ }const normal = new THREE46.Vector3;const edge = new THREE46.Vector3;for (let i = 0;i < corners; i += 3) {@@ -29947,17 +29956,17 @@ function projectUV(geometry, options) {}if (fullWrap && Math.max(...angles) - Math.min(...angles) > 0.5 + 0.000001)throw new Error("projectUV: side triangle spans more than half a revolution; add profile segments to resolve the mapping.");- pairs = triangle.map((point, j) => [angles[j], fit(point, "y")]);+ pairs = triangle.map((point, j) => [angles[j] * uScale, fit(point, "y")]);} else if (cap) {pairs = triangle.map((point) => [fit(point, "x"), fit(point, "z")]);} else if (options.projection === "box") {const axis = Math.abs(normal.x) >= Math.abs(normal.y) && Math.abs(normal.x) >= Math.abs(normal.z) ? "x" : Math.abs(normal.y) >= Math.abs(normal.z) ? "y" : "z";pairs = triangle.map((point) => {if (axis === "x")- return [normal.x > 0 ? 1 - fit(point, "z") : fit(point, "z"), fit(point, "y")];+ return [normal.x > 0 ? flip(point, "z") : fit(point, "z"), fit(point, "y")];if (axis === "y")- return [fit(point, "x"), normal.y > 0 ? 1 - fit(point, "z") : fit(point, "z")];- return [normal.z < 0 ? 1 - fit(point, "x") : fit(point, "x"), fit(point, "y")];+ return [fit(point, "x"), normal.y > 0 ? flip(point, "z") : fit(point, "z")];+ return [normal.z < 0 ? flip(point, "x") : fit(point, "x"), fit(point, "y")];});} elsepairs = triangle.map((point) => [fit(point, "x"), fit(point, "y")]);@@ -42612,7 +42621,8 @@ define2("projectUV", {axes: "Rigid frame in geometry-local coordinates: planar XY, box face planes, cylindrical around Y. Euler XYZ rotations are degrees.",origin: "Frame origin is explicit, default [0,0,0]; geometry positions are preserved.",parameters: [- "Planar/box axes and cylindrical height normalize each geometry extent to 0..1. This is not metre-scaled UV mapping; a shared frame does not preserve texel density or texture continuity across separate pieces. Preserve authored physical UVs or map each face with explicit dimensions when that is required.",+ "By default planar/box axes and cylindrical height normalize each geometry extent to 0..1, so texel density changes with part size. metersPerUnit (positive length) instead maps one UV unit to that length measured from the frame origin: parts of any size tile at the same density, and parts sharing a frame keep the same phase. A full cylindrical wrap rounds its circumference at the largest radius to whole tiles so the seam stays continuous; a partial angularRange uses the exact arc length.",+ "Output is non-indexed. Weld with mergeVertices afterwards where the projection is continuous (one planar face, cylindrical sides); it keeps corners split where UVs or normals differ, such as box faces and the cylindrical seam.","projection is required. frame uses origin/rotation. Cylinder seamDegrees defaults to 180, measured from +X toward +Z; angularRange is [start degrees, positive sweep <=360] instead of seamDegrees.","Cylindrical caps default to planar for triangle normals within 1e-6 of frame Y; caps:side uses side mapping. Partial ranges must cover side vertices, allowing 1e-6 radians of Float32 boundary roundoff.","Nonempty finite positions, valid triangle indices and matching per-vertex attributes; morph targets are unsupported. At most 2000000 source samples/corners and 128 MiB expanded attribute storage."@@ -42625,8 +42635,17 @@ define2("projectUV", {}, {...uvMetadata,references: ["src/uv-project.ts"],- aliases: ["planar projection", "box mapping", "cylindrical UVs", "rotated UV frame"],- intents: ["generate directional texture coordinates in an explicit frame"],+ aliases: [+ "planar projection",+ "box mapping",+ "cylindrical UVs",+ "rotated UV frame",+ "metric UVs"+ ],+ intents: [+ "generate directional texture coordinates in an explicit frame",+ "keep the same texel density on parts of different size"+ ],limitations: ["Full-wrap seam corners may use U above 1 and require repeat sampling. Side triangles spanning more than half a revolution fail; subdivide the profile. Zero extent maps to 0.5. This is projection, not an atlas or a stretch-free guarantee."],diff --git a/dist/build.json b/dist/build.jsonindex d338f6c1..05b2596a 100644--- a/dist/build.json+++ b/dist/build.json@@ -2,10 +2,10 @@"schemaVersion": 1,"entries": {"worker": {- "identity": "sha256:975ae61072c000ce3395c036d57f3c6f41d1ded3fed4ce91249a17769f9354e4",+ "identity": "sha256:30d934d80e37799159bb656bc76edcbabb256fb903af065833cad20ba09ee7a2","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "50cbb3fa726a380b6da9ba91b4afb78b10f8a84ee6bcd90250591cbaac0b0958",+ "sourceHash": "cc66db80ad8d09fd170de4896b49ab1bba756ef982d4b76085759951340f82dc","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -37,13 +37,13 @@},"target": "node","file": "evaluator-worker.mjs",- "bundleHash": "sha256:21ee8409de7902ed7c93f4e9f30ecd774c82811a7a456f1ff5a995fef2c265b2"+ "bundleHash": "sha256:f467cfb2d687775eaac65fc713d5deb92b912844e6e418467ca345d7dfaf3244"},"agent-run": {- "identity": "sha256:975ae61072c000ce3395c036d57f3c6f41d1ded3fed4ce91249a17769f9354e4",+ "identity": "sha256:30d934d80e37799159bb656bc76edcbabb256fb903af065833cad20ba09ee7a2","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "50cbb3fa726a380b6da9ba91b4afb78b10f8a84ee6bcd90250591cbaac0b0958",+ "sourceHash": "cc66db80ad8d09fd170de4896b49ab1bba756ef982d4b76085759951340f82dc","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -75,13 +75,13 @@},"target": "node","file": "agent-run.mjs",- "bundleHash": "sha256:a21ac1b7169718520bfd9f7cf9b0ea2001cdd14d69167166da2fca09c0a59c3d"+ "bundleHash": "sha256:6077d9e31e214dc97a6383eb591f95e9dd88aff36ee5466486533a163162e07f"},"agent-providers": {- "identity": "sha256:975ae61072c000ce3395c036d57f3c6f41d1ded3fed4ce91249a17769f9354e4",+ "identity": "sha256:30d934d80e37799159bb656bc76edcbabb256fb903af065833cad20ba09ee7a2","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "50cbb3fa726a380b6da9ba91b4afb78b10f8a84ee6bcd90250591cbaac0b0958",+ "sourceHash": "cc66db80ad8d09fd170de4896b49ab1bba756ef982d4b76085759951340f82dc","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -116,10 +116,10 @@"bundleHash": "sha256:9d6faf03d307321bc2e3bd5ce5bdee0bbbf61e0ebed8bfebfa1fb072287b83fa"},"mcp": {- "identity": "sha256:975ae61072c000ce3395c036d57f3c6f41d1ded3fed4ce91249a17769f9354e4",+ "identity": "sha256:30d934d80e37799159bb656bc76edcbabb256fb903af065833cad20ba09ee7a2","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "50cbb3fa726a380b6da9ba91b4afb78b10f8a84ee6bcd90250591cbaac0b0958",+ "sourceHash": "cc66db80ad8d09fd170de4896b49ab1bba756ef982d4b76085759951340f82dc","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -154,10 +154,10 @@"bundleHash": "sha256:a246b2c79d629a332cef4430dbe742b0c4a0d2f04f0281e673c3c60ff22706da"},"cli": {- "identity": "sha256:975ae61072c000ce3395c036d57f3c6f41d1ded3fed4ce91249a17769f9354e4",+ "identity": "sha256:30d934d80e37799159bb656bc76edcbabb256fb903af065833cad20ba09ee7a2","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "50cbb3fa726a380b6da9ba91b4afb78b10f8a84ee6bcd90250591cbaac0b0958",+ "sourceHash": "cc66db80ad8d09fd170de4896b49ab1bba756ef982d4b76085759951340f82dc","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -189,13 +189,13 @@},"target": "node","file": "cli.mjs",- "bundleHash": "sha256:110504876178fa48e5f88a1b7b477de457c8a11140fd9fcc0a17283435e4dff1"+ "bundleHash": "sha256:2d905a68e31ee6aa97f0c303d51246aa4f8f4414b28f907335f7acac91a5a01b"},"engine": {- "identity": "sha256:975ae61072c000ce3395c036d57f3c6f41d1ded3fed4ce91249a17769f9354e4",+ "identity": "sha256:30d934d80e37799159bb656bc76edcbabb256fb903af065833cad20ba09ee7a2","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "50cbb3fa726a380b6da9ba91b4afb78b10f8a84ee6bcd90250591cbaac0b0958",+ "sourceHash": "cc66db80ad8d09fd170de4896b49ab1bba756ef982d4b76085759951340f82dc","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -227,7 +227,7 @@},"target": "node","file": "mcp-engine.mjs",- "bundleHash": "sha256:fefb37ae96bde71ed5b9b273de4c03ec2c6bed46ec5ba1db445e79acb797ba92"+ "bundleHash": "sha256:970aad4330d6b90fb28441312f9add1784d7c8f96ac0cbdee9666d925c6f2832"}}}diff --git a/dist/cli.mjs b/dist/cli.mjsindex 8870e015..894904ad 100644--- a/dist/cli.mjs+++ b/dist/cli.mjs@@ -27542,7 +27542,7 @@ var init_uv = __esm(() => {// src/uv-project.tsimport * as THREE46 from "three";function projectUV(geometry, options) {- if (!options || typeof options !== "object" || Array.isArray(options) || !["planar", "box", "cylindrical"].includes(options.projection) || Object.keys(options).some((key) => !["projection", "frame", "seamDegrees", "angularRange", "caps"].includes(key)))+ if (!options || typeof options !== "object" || Array.isArray(options) || !["planar", "box", "cylindrical"].includes(options.projection) || Object.keys(options).some((key) => !["projection", "frame", "seamDegrees", "angularRange", "caps", "metersPerUnit"].includes(key)))throw new Error("projectUV: select an explicit planar, box or cylindrical projection with documented options.");const cylinder = options.projection === "cylindrical";if (!cylinder && [options.seamDegrees, options.angularRange, options.caps].some((value) => value !== undefined))@@ -27553,6 +27553,9 @@ function projectUV(geometry, options) {throw new Error("projectUV: angularRange must be [finite start degrees, positive sweep <=360].");if (options.caps !== undefined && options.caps !== "planar" && options.caps !== "side")throw new Error("projectUV: caps must be planar or side.");+ const metric = options.metersPerUnit;+ if (metric !== undefined && !(typeof metric === "number" && Number.isFinite(metric) && metric > 0))+ throw new Error("projectUV: metersPerUnit must be a positive finite length.");const inverse = geometryFrameMatrix(options.frame).invert();const positions = geometry.getAttribute("position");if (positions?.itemSize !== 3 || positions.count < 1 || positions.count > MAX_CORNERS)@@ -27587,13 +27590,19 @@ function projectUV(geometry, options) {bounds.expandByPoint(point);}const extent = bounds.getSize(new THREE46.Vector3);- const fit = (point, axis) => extent[axis] > 0 ? (point[axis] - bounds.min[axis]) / extent[axis] : 0.5;+ const fit = (point, axis) => metric !== undefined ? point[axis] / metric : extent[axis] > 0 ? (point[axis] - bounds.min[axis]) / extent[axis] : 0.5;+ const flip = (point, axis) => metric !== undefined ? -point[axis] / metric : 1 - fit(point, axis);const outputUVs = new Float32Array(corners * 2);const startDegrees = options.angularRange?.[0] ?? options.seamDegrees ?? 180;const start = startDegrees % 360 * Math.PI / 180;const sweep = (options.angularRange?.[1] ?? 360) * Math.PI / 180;const fullWrap = options.angularRange === undefined || options.angularRange[1] === 360;const wrap = (angle) => (angle % (2 * Math.PI) + 2 * Math.PI) % (2 * Math.PI);+ let uScale = 1;+ if (metric !== undefined) {+ const radius = points.reduce((max, point) => Math.max(max, Math.hypot(point.x, point.z)), 0);+ uScale = fullWrap ? Math.max(1, Math.round(2 * Math.PI * radius / metric)) : sweep * radius / metric;+ }const normal = new THREE46.Vector3;const edge = new THREE46.Vector3;for (let i = 0;i < corners; i += 3) {@@ -27617,17 +27626,17 @@ function projectUV(geometry, options) {}if (fullWrap && Math.max(...angles) - Math.min(...angles) > 0.5 + 0.000001)throw new Error("projectUV: side triangle spans more than half a revolution; add profile segments to resolve the mapping.");- pairs = triangle.map((point, j) => [angles[j], fit(point, "y")]);+ pairs = triangle.map((point, j) => [angles[j] * uScale, fit(point, "y")]);} else if (cap) {pairs = triangle.map((point) => [fit(point, "x"), fit(point, "z")]);} else if (options.projection === "box") {const axis = Math.abs(normal.x) >= Math.abs(normal.y) && Math.abs(normal.x) >= Math.abs(normal.z) ? "x" : Math.abs(normal.y) >= Math.abs(normal.z) ? "y" : "z";pairs = triangle.map((point) => {if (axis === "x")- return [normal.x > 0 ? 1 - fit(point, "z") : fit(point, "z"), fit(point, "y")];+ return [normal.x > 0 ? flip(point, "z") : fit(point, "z"), fit(point, "y")];if (axis === "y")- return [fit(point, "x"), normal.y > 0 ? 1 - fit(point, "z") : fit(point, "z")];- return [normal.z < 0 ? 1 - fit(point, "x") : fit(point, "x"), fit(point, "y")];+ return [fit(point, "x"), normal.y > 0 ? flip(point, "z") : fit(point, "z")];+ return [normal.z < 0 ? flip(point, "x") : fit(point, "x"), fit(point, "y")];});} elsepairs = triangle.map((point) => [fit(point, "x"), fit(point, "y")]);@@ -29740,7 +29749,7 @@ var REMOVED_AUTHORING_HELPERS, geometryPrimitives;var init_geometry_catalog = __esm(() => {REMOVED_AUTHORING_HELPERS = Object.freeze({boxUnwrap: 'Preserve existing UVs with direct geometry sharing or copyGeometry. Generate new face mappings explicitly with projectUV(geo, { projection: "box", frame? }); planar projection is a separate mode.',- cylinderUnwrap: 'Preserve valid built-in UVs with direct sharing or copyGeometry. For cylindrical mapping use projectUV(geo, { projection: "cylindrical", frame?, seamDegrees?, angularRange?, caps? }); partial arcs need an explicit angularRange.',+ cylinderUnwrap: 'Preserve valid built-in UVs with direct sharing or copyGeometry. For cylindrical mapping use projectUV(geo, { projection: "cylindrical", frame?, seamDegrees?, angularRange?, caps?, metersPerUnit? }); partial arcs need an explicit angularRange; metersPerUnit fixes texel density.',planeUnwrap: 'Use projectUV(geo, { projection: "planar", frame? }) to generate frame-XY UVs. Preserve existing UVs with direct sharing or copyGeometry instead.',cloneGeometry: "Pass the original geometry directly for intentional sharing. Use copyGeometry only for independent editable buffers; the removed helper returned its input.",cloneMaterial: "Pass the original material directly for intentional sharing. Use copyMaterial for independent properties; referenced textures remain shared.",@@ -29750,10 +29759,10 @@ var init_geometry_catalog = __esm(() => {geometryPrimitives = [{name: "projectUV",- signature: "projectUV(geometry: BufferGeometry, opts: { projection: 'planar'|'box'|'cylindrical', frame?: { origin?: [x,y,z], rotation?: [xDeg,yDeg,zDeg] }, seamDegrees?: number, angularRange?: [startDeg,sweepDeg], caps?: 'planar'|'side' })",+ signature: "projectUV(geometry: BufferGeometry, opts: { projection: 'planar'|'box'|'cylindrical', frame?: { origin?: [x,y,z], rotation?: [xDeg,yDeg,zDeg] }, seamDegrees?: number, angularRange?: [startDeg,sweepDeg], caps?: 'planar'|'side', metersPerUnit?: number })",returns: "THREE.BufferGeometry (owned, non-indexed triangle corners)",category: "uv",- description: "Generates UV0 explicitly in a rigid geometry-local frame. Planar maps XY; box maps each face; cylindrical wraps frame Y with separate caps and split angular seams. Replaces existing UVs and removes stale tangents. To preserve good UVs use direct sharing or copyGeometry instead.",+ description: "Generates UV0 explicitly in a rigid geometry-local frame. Planar maps XY; box maps each face; cylindrical wraps frame Y with separate caps and split angular seams. Replaces existing UVs and removes stale tangents. metersPerUnit maps one UV unit to a fixed length so parts of different size tile at the same density. To preserve good UVs use direct sharing or copyGeometry instead.",example: "const mapped = projectUV(rawGeometry, { projection: 'cylindrical', frame: { rotation: [0,0,-90] }, seamDegrees: 180 });"},{@@ -45941,7 +45950,8 @@ var init_helper_contracts = __esm(() => {axes: "Rigid frame in geometry-local coordinates: planar XY, box face planes, cylindrical around Y. Euler XYZ rotations are degrees.",origin: "Frame origin is explicit, default [0,0,0]; geometry positions are preserved.",parameters: [- "Planar/box axes and cylindrical height normalize each geometry extent to 0..1. This is not metre-scaled UV mapping; a shared frame does not preserve texel density or texture continuity across separate pieces. Preserve authored physical UVs or map each face with explicit dimensions when that is required.",+ "By default planar/box axes and cylindrical height normalize each geometry extent to 0..1, so texel density changes with part size. metersPerUnit (positive length) instead maps one UV unit to that length measured from the frame origin: parts of any size tile at the same density, and parts sharing a frame keep the same phase. A full cylindrical wrap rounds its circumference at the largest radius to whole tiles so the seam stays continuous; a partial angularRange uses the exact arc length.",+ "Output is non-indexed. Weld with mergeVertices afterwards where the projection is continuous (one planar face, cylindrical sides); it keeps corners split where UVs or normals differ, such as box faces and the cylindrical seam.","projection is required. frame uses origin/rotation. Cylinder seamDegrees defaults to 180, measured from +X toward +Z; angularRange is [start degrees, positive sweep <=360] instead of seamDegrees.","Cylindrical caps default to planar for triangle normals within 1e-6 of frame Y; caps:side uses side mapping. Partial ranges must cover side vertices, allowing 1e-6 radians of Float32 boundary roundoff.","Nonempty finite positions, valid triangle indices and matching per-vertex attributes; morph targets are unsupported. At most 2000000 source samples/corners and 128 MiB expanded attribute storage."@@ -45954,8 +45964,17 @@ var init_helper_contracts = __esm(() => {}, {...uvMetadata,references: ["src/uv-project.ts"],- aliases: ["planar projection", "box mapping", "cylindrical UVs", "rotated UV frame"],- intents: ["generate directional texture coordinates in an explicit frame"],+ aliases: [+ "planar projection",+ "box mapping",+ "cylindrical UVs",+ "rotated UV frame",+ "metric UVs"+ ],+ intents: [+ "generate directional texture coordinates in an explicit frame",+ "keep the same texel density on parts of different size"+ ],limitations: ["Full-wrap seam corners may use U above 1 and require repeat sampling. Side triangles spanning more than half a revolution fail; subdivide the profile. Zero extent maps to 0.5. This is projection, not an atlas or a stretch-free guarantee."],diff --git a/dist/evaluator-worker.mjs b/dist/evaluator-worker.mjsindex de19a330..e276d7a7 100644--- a/dist/evaluator-worker.mjs+++ b/dist/evaluator-worker.mjs@@ -24296,7 +24296,7 @@ var init_uv = __esm(() => {// src/uv-project.tsimport * as THREE46 from "three";function projectUV(geometry, options) {- if (!options || typeof options !== "object" || Array.isArray(options) || !["planar", "box", "cylindrical"].includes(options.projection) || Object.keys(options).some((key) => !["projection", "frame", "seamDegrees", "angularRange", "caps"].includes(key)))+ if (!options || typeof options !== "object" || Array.isArray(options) || !["planar", "box", "cylindrical"].includes(options.projection) || Object.keys(options).some((key) => !["projection", "frame", "seamDegrees", "angularRange", "caps", "metersPerUnit"].includes(key)))throw new Error("projectUV: select an explicit planar, box or cylindrical projection with documented options.");const cylinder = options.projection === "cylindrical";if (!cylinder && [options.seamDegrees, options.angularRange, options.caps].some((value) => value !== undefined))@@ -24307,6 +24307,9 @@ function projectUV(geometry, options) {throw new Error("projectUV: angularRange must be [finite start degrees, positive sweep <=360].");if (options.caps !== undefined && options.caps !== "planar" && options.caps !== "side")throw new Error("projectUV: caps must be planar or side.");+ const metric = options.metersPerUnit;+ if (metric !== undefined && !(typeof metric === "number" && Number.isFinite(metric) && metric > 0))+ throw new Error("projectUV: metersPerUnit must be a positive finite length.");const inverse = geometryFrameMatrix(options.frame).invert();const positions = geometry.getAttribute("position");if (positions?.itemSize !== 3 || positions.count < 1 || positions.count > MAX_CORNERS)@@ -24341,13 +24344,19 @@ function projectUV(geometry, options) {bounds.expandByPoint(point);}const extent = bounds.getSize(new THREE46.Vector3);- const fit = (point, axis) => extent[axis] > 0 ? (point[axis] - bounds.min[axis]) / extent[axis] : 0.5;+ const fit = (point, axis) => metric !== undefined ? point[axis] / metric : extent[axis] > 0 ? (point[axis] - bounds.min[axis]) / extent[axis] : 0.5;+ const flip = (point, axis) => metric !== undefined ? -point[axis] / metric : 1 - fit(point, axis);const outputUVs = new Float32Array(corners * 2);const startDegrees = options.angularRange?.[0] ?? options.seamDegrees ?? 180;const start = startDegrees % 360 * Math.PI / 180;const sweep = (options.angularRange?.[1] ?? 360) * Math.PI / 180;const fullWrap = options.angularRange === undefined || options.angularRange[1] === 360;const wrap = (angle) => (angle % (2 * Math.PI) + 2 * Math.PI) % (2 * Math.PI);+ let uScale = 1;+ if (metric !== undefined) {+ const radius = points.reduce((max, point) => Math.max(max, Math.hypot(point.x, point.z)), 0);+ uScale = fullWrap ? Math.max(1, Math.round(2 * Math.PI * radius / metric)) : sweep * radius / metric;+ }const normal = new THREE46.Vector3;const edge = new THREE46.Vector3;for (let i = 0;i < corners; i += 3) {@@ -24371,17 +24380,17 @@ function projectUV(geometry, options) {}if (fullWrap && Math.max(...angles) - Math.min(...angles) > 0.5 + 0.000001)throw new Error("projectUV: side triangle spans more than half a revolution; add profile segments to resolve the mapping.");- pairs = triangle.map((point, j) => [angles[j], fit(point, "y")]);+ pairs = triangle.map((point, j) => [angles[j] * uScale, fit(point, "y")]);} else if (cap) {pairs = triangle.map((point) => [fit(point, "x"), fit(point, "z")]);} else if (options.projection === "box") {const axis = Math.abs(normal.x) >= Math.abs(normal.y) && Math.abs(normal.x) >= Math.abs(normal.z) ? "x" : Math.abs(normal.y) >= Math.abs(normal.z) ? "y" : "z";pairs = triangle.map((point) => {if (axis === "x")- return [normal.x > 0 ? 1 - fit(point, "z") : fit(point, "z"), fit(point, "y")];+ return [normal.x > 0 ? flip(point, "z") : fit(point, "z"), fit(point, "y")];if (axis === "y")- return [fit(point, "x"), normal.y > 0 ? 1 - fit(point, "z") : fit(point, "z")];- return [normal.z < 0 ? 1 - fit(point, "x") : fit(point, "x"), fit(point, "y")];+ return [fit(point, "x"), normal.y > 0 ? flip(point, "z") : fit(point, "z")];+ return [normal.z < 0 ? flip(point, "x") : fit(point, "x"), fit(point, "y")];});} elsepairs = triangle.map((point) => [fit(point, "x"), fit(point, "y")]);@@ -26508,7 +26517,7 @@ var REMOVED_AUTHORING_HELPERS, geometryPrimitives;var init_geometry_catalog = __esm(() => {REMOVED_AUTHORING_HELPERS = Object.freeze({boxUnwrap: 'Preserve existing UVs with direct geometry sharing or copyGeometry. Generate new face mappings explicitly with projectUV(geo, { projection: "box", frame? }); planar projection is a separate mode.',- cylinderUnwrap: 'Preserve valid built-in UVs with direct sharing or copyGeometry. For cylindrical mapping use projectUV(geo, { projection: "cylindrical", frame?, seamDegrees?, angularRange?, caps? }); partial arcs need an explicit angularRange.',+ cylinderUnwrap: 'Preserve valid built-in UVs with direct sharing or copyGeometry. For cylindrical mapping use projectUV(geo, { projection: "cylindrical", frame?, seamDegrees?, angularRange?, caps?, metersPerUnit? }); partial arcs need an explicit angularRange; metersPerUnit fixes texel density.',planeUnwrap: 'Use projectUV(geo, { projection: "planar", frame? }) to generate frame-XY UVs. Preserve existing UVs with direct sharing or copyGeometry instead.',cloneGeometry: "Pass the original geometry directly for intentional sharing. Use copyGeometry only for independent editable buffers; the removed helper returned its input.",cloneMaterial: "Pass the original material directly for intentional sharing. Use copyMaterial for independent properties; referenced textures remain shared.",@@ -26518,10 +26527,10 @@ var init_geometry_catalog = __esm(() => {geometryPrimitives = [{name: "projectUV",- signature: "projectUV(geometry: BufferGeometry, opts: { projection: 'planar'|'box'|'cylindrical', frame?: { origin?: [x,y,z], rotation?: [xDeg,yDeg,zDeg] }, seamDegrees?: number, angularRange?: [startDeg,sweepDeg], caps?: 'planar'|'side' })",+ signature: "projectUV(geometry: BufferGeometry, opts: { projection: 'planar'|'box'|'cylindrical', frame?: { origin?: [x,y,z], rotation?: [xDeg,yDeg,zDeg] }, seamDegrees?: number, angularRange?: [startDeg,sweepDeg], caps?: 'planar'|'side', metersPerUnit?: number })",returns: "THREE.BufferGeometry (owned, non-indexed triangle corners)",category: "uv",- description: "Generates UV0 explicitly in a rigid geometry-local frame. Planar maps XY; box maps each face; cylindrical wraps frame Y with separate caps and split angular seams. Replaces existing UVs and removes stale tangents. To preserve good UVs use direct sharing or copyGeometry instead.",+ description: "Generates UV0 explicitly in a rigid geometry-local frame. Planar maps XY; box maps each face; cylindrical wraps frame Y with separate caps and split angular seams. Replaces existing UVs and removes stale tangents. metersPerUnit maps one UV unit to a fixed length so parts of different size tile at the same density. To preserve good UVs use direct sharing or copyGeometry instead.",example: "const mapped = projectUV(rawGeometry, { projection: 'cylindrical', frame: { rotation: [0,0,-90] }, seamDegrees: 180 });"},{diff --git a/dist/mcp-engine.mjs b/dist/mcp-engine.mjsindex 863abb6a..79502dda 100644--- a/dist/mcp-engine.mjs+++ b/dist/mcp-engine.mjs@@ -27106,7 +27106,7 @@ var init_uv = __esm(() => {// src/uv-project.tsimport * as THREE47 from "three";function projectUV(geometry, options) {- if (!options || typeof options !== "object" || Array.isArray(options) || !["planar", "box", "cylindrical"].includes(options.projection) || Object.keys(options).some((key) => !["projection", "frame", "seamDegrees", "angularRange", "caps"].includes(key)))+ if (!options || typeof options !== "object" || Array.isArray(options) || !["planar", "box", "cylindrical"].includes(options.projection) || Object.keys(options).some((key) => !["projection", "frame", "seamDegrees", "angularRange", "caps", "metersPerUnit"].includes(key)))throw new Error("projectUV: select an explicit planar, box or cylindrical projection with documented options.");const cylinder = options.projection === "cylindrical";if (!cylinder && [options.seamDegrees, options.angularRange, options.caps].some((value) => value !== undefined))@@ -27117,6 +27117,9 @@ function projectUV(geometry, options) {throw new Error("projectUV: angularRange must be [finite start degrees, positive sweep <=360].");if (options.caps !== undefined && options.caps !== "planar" && options.caps !== "side")throw new Error("projectUV: caps must be planar or side.");+ const metric = options.metersPerUnit;+ if (metric !== undefined && !(typeof metric === "number" && Number.isFinite(metric) && metric > 0))+ throw new Error("projectUV: metersPerUnit must be a positive finite length.");const inverse = geometryFrameMatrix(options.frame).invert();const positions = geometry.getAttribute("position");if (positions?.itemSize !== 3 || positions.count < 1 || positions.count > MAX_CORNERS)@@ -27151,13 +27154,19 @@ function projectUV(geometry, options) {bounds.expandByPoint(point);}const extent = bounds.getSize(new THREE47.Vector3);- const fit = (point, axis) => extent[axis] > 0 ? (point[axis] - bounds.min[axis]) / extent[axis] : 0.5;+ const fit = (point, axis) => metric !== undefined ? point[axis] / metric : extent[axis] > 0 ? (point[axis] - bounds.min[axis]) / extent[axis] : 0.5;+ const flip = (point, axis) => metric !== undefined ? -point[axis] / metric : 1 - fit(point, axis);const outputUVs = new Float32Array(corners * 2);const startDegrees = options.angularRange?.[0] ?? options.seamDegrees ?? 180;const start = startDegrees % 360 * Math.PI / 180;const sweep = (options.angularRange?.[1] ?? 360) * Math.PI / 180;const fullWrap = options.angularRange === undefined || options.angularRange[1] === 360;const wrap = (angle) => (angle % (2 * Math.PI) + 2 * Math.PI) % (2 * Math.PI);+ let uScale = 1;+ if (metric !== undefined) {+ const radius = points.reduce((max, point) => Math.max(max, Math.hypot(point.x, point.z)), 0);+ uScale = fullWrap ? Math.max(1, Math.round(2 * Math.PI * radius / metric)) : sweep * radius / metric;+ }const normal = new THREE47.Vector3;const edge = new THREE47.Vector3;for (let i = 0;i < corners; i += 3) {@@ -27181,17 +27190,17 @@ function projectUV(geometry, options) {}if (fullWrap && Math.max(...angles) - Math.min(...angles) > 0.5 + 0.000001)throw new Error("projectUV: side triangle spans more than half a revolution; add profile segments to resolve the mapping.");- pairs = triangle.map((point, j) => [angles[j], fit(point, "y")]);+ pairs = triangle.map((point, j) => [angles[j] * uScale, fit(point, "y")]);} else if (cap) {pairs = triangle.map((point) => [fit(point, "x"), fit(point, "z")]);} else if (options.projection === "box") {const axis = Math.abs(normal.x) >= Math.abs(normal.y) && Math.abs(normal.x) >= Math.abs(normal.z) ? "x" : Math.abs(normal.y) >= Math.abs(normal.z) ? "y" : "z";pairs = triangle.map((point) => {if (axis === "x")- return [normal.x > 0 ? 1 - fit(point, "z") : fit(point, "z"), fit(point, "y")];+ return [normal.x > 0 ? flip(point, "z") : fit(point, "z"), fit(point, "y")];if (axis === "y")- return [fit(point, "x"), normal.y > 0 ? 1 - fit(point, "z") : fit(point, "z")];- return [normal.z < 0 ? 1 - fit(point, "x") : fit(point, "x"), fit(point, "y")];+ return [fit(point, "x"), normal.y > 0 ? flip(point, "z") : fit(point, "z")];+ return [normal.z < 0 ? flip(point, "x") : fit(point, "x"), fit(point, "y")];});} elsepairs = triangle.map((point) => [fit(point, "x"), fit(point, "y")]);@@ -29304,7 +29313,7 @@ var REMOVED_AUTHORING_HELPERS, geometryPrimitives;var init_geometry_catalog = __esm(() => {REMOVED_AUTHORING_HELPERS = Object.freeze({boxUnwrap: 'Preserve existing UVs with direct geometry sharing or copyGeometry. Generate new face mappings explicitly with projectUV(geo, { projection: "box", frame? }); planar projection is a separate mode.',- cylinderUnwrap: 'Preserve valid built-in UVs with direct sharing or copyGeometry. For cylindrical mapping use projectUV(geo, { projection: "cylindrical", frame?, seamDegrees?, angularRange?, caps? }); partial arcs need an explicit angularRange.',+ cylinderUnwrap: 'Preserve valid built-in UVs with direct sharing or copyGeometry. For cylindrical mapping use projectUV(geo, { projection: "cylindrical", frame?, seamDegrees?, angularRange?, caps?, metersPerUnit? }); partial arcs need an explicit angularRange; metersPerUnit fixes texel density.',planeUnwrap: 'Use projectUV(geo, { projection: "planar", frame? }) to generate frame-XY UVs. Preserve existing UVs with direct sharing or copyGeometry instead.',cloneGeometry: "Pass the original geometry directly for intentional sharing. Use copyGeometry only for independent editable buffers; the removed helper returned its input.",cloneMaterial: "Pass the original material directly for intentional sharing. Use copyMaterial for independent properties; referenced textures remain shared.",@@ -29314,10 +29323,10 @@ var init_geometry_catalog = __esm(() => {geometryPrimitives = [{name: "projectUV",- signature: "projectUV(geometry: BufferGeometry, opts: { projection: 'planar'|'box'|'cylindrical', frame?: { origin?: [x,y,z], rotation?: [xDeg,yDeg,zDeg] }, seamDegrees?: number, angularRange?: [startDeg,sweepDeg], caps?: 'planar'|'side' })",+ signature: "projectUV(geometry: BufferGeometry, opts: { projection: 'planar'|'box'|'cylindrical', frame?: { origin?: [x,y,z], rotation?: [xDeg,yDeg,zDeg] }, seamDegrees?: number, angularRange?: [startDeg,sweepDeg], caps?: 'planar'|'side', metersPerUnit?: number })",returns: "THREE.BufferGeometry (owned, non-indexed triangle corners)",category: "uv",- description: "Generates UV0 explicitly in a rigid geometry-local frame. Planar maps XY; box maps each face; cylindrical wraps frame Y with separate caps and split angular seams. Replaces existing UVs and removes stale tangents. To preserve good UVs use direct sharing or copyGeometry instead.",+ description: "Generates UV0 explicitly in a rigid geometry-local frame. Planar maps XY; box maps each face; cylindrical wraps frame Y with separate caps and split angular seams. Replaces existing UVs and removes stale tangents. metersPerUnit maps one UV unit to a fixed length so parts of different size tile at the same density. To preserve good UVs use direct sharing or copyGeometry instead.",example: "const mapped = projectUV(rawGeometry, { projection: 'cylindrical', frame: { rotation: [0,0,-90] }, seamDegrees: 180 });"},{@@ -46727,7 +46736,8 @@ define2("projectUV", {axes: "Rigid frame in geometry-local coordinates: planar XY, box face planes, cylindrical around Y. Euler XYZ rotations are degrees.",origin: "Frame origin is explicit, default [0,0,0]; geometry positions are preserved.",parameters: [- "Planar/box axes and cylindrical height normalize each geometry extent to 0..1. This is not metre-scaled UV mapping; a shared frame does not preserve texel density or texture continuity across separate pieces. Preserve authored physical UVs or map each face with explicit dimensions when that is required.",+ "By default planar/box axes and cylindrical height normalize each geometry extent to 0..1, so texel density changes with part size. metersPerUnit (positive length) instead maps one UV unit to that length measured from the frame origin: parts of any size tile at the same density, and parts sharing a frame keep the same phase. A full cylindrical wrap rounds its circumference at the largest radius to whole tiles so the seam stays continuous; a partial angularRange uses the exact arc length.",+ "Output is non-indexed. Weld with mergeVertices afterwards where the projection is continuous (one planar face, cylindrical sides); it keeps corners split where UVs or normals differ, such as box faces and the cylindrical seam.","projection is required. frame uses origin/rotation. Cylinder seamDegrees defaults to 180, measured from +X toward +Z; angularRange is [start degrees, positive sweep <=360] instead of seamDegrees.","Cylindrical caps default to planar for triangle normals within 1e-6 of frame Y; caps:side uses side mapping. Partial ranges must cover side vertices, allowing 1e-6 radians of Float32 boundary roundoff.","Nonempty finite positions, valid triangle indices and matching per-vertex attributes; morph targets are unsupported. At most 2000000 source samples/corners and 128 MiB expanded attribute storage."@@ -46740,8 +46750,17 @@ define2("projectUV", {}, {...uvMetadata,references: ["src/uv-project.ts"],- aliases: ["planar projection", "box mapping", "cylindrical UVs", "rotated UV frame"],- intents: ["generate directional texture coordinates in an explicit frame"],+ aliases: [+ "planar projection",+ "box mapping",+ "cylindrical UVs",+ "rotated UV frame",+ "metric UVs"+ ],+ intents: [+ "generate directional texture coordinates in an explicit frame",+ "keep the same texel density on parts of different size"+ ],limitations: ["Full-wrap seam corners may use U above 1 and require repeat sampling. Side triangles spanning more than half a revolution fail; subdivide the profile. Zero extent maps to 0.5. This is projection, not an atlas or a stretch-free guarantee."],diff --git a/docs/geometry.md b/docs/geometry.mdindex ac9a9c89..1ddac364 100644--- a/docs/geometry.md+++ b/docs/geometry.md@@ -549,17 +549,27 @@ parallel to frame XZ use planar UVs by default; `caps: 'side'` opts into side maFull-wrap seam triangles may use U above 1, requiring repeat texture sampling.Triangles spanning more than half a revolution fail with a subdivision hint.-Planar/box coordinates and cylindrical height normalize each geometry's extents-to 0..1. They do not use metres per texture repeat. A shared frame does not make-separate wall pieces share texel density or continuous brick courses. Preserve-existing physical UVs, or map faces with explicit dimensions; a planar XY face-can use `remapUV` with scales `[width / tileWidth, height / tileHeight]` and an-explicit offset to align its phase. Box faces use different axis pairs, so one-uniform remap does not establish equal density on every face.+By default, planar/box coordinates and cylindrical height normalize each geometry's+extents to 0..1, so texel density changes with part size. Pass `metersPerUnit` to map+one UV unit to a fixed length instead, measured from the frame origin:++```js+const wall = projectUV(wallGeometry, { projection: 'box', metersPerUnit: 0.5 });+```++Parts of any size then tile at the same density, and wall pieces that share a frame+continue the same brick courses. A full cylindrical wrap rounds its circumference at+the largest radius to a whole number of tiles, so the seam meets itself; on a cone the+narrower rings are compressed accordingly. A partial `angularRange` uses the exact arc+length at the largest radius.Output is owned and non-indexed to separate triangle-corner UVs. Positions, normals,matching attributes, material groups, draw range and triangle order are preserved;-tangents are removed with a diagnostic. Zero projection extent maps to 0.5.+tangents are removed with a diagnostic. Zero projection extent maps to 0.5. Where the+projection is continuous (one planar face, cylindrical sides), weld the result with+`mergeVertices`: it rejoins corners that share position, normal and UV and keeps box+faces and the cylindrical seam split. Per-triangle UVs left unwelded multiply vertex+count and file size.Inputs must be finite triangle geometry with matching per-vertex attributes;morph targets require a separate contract. Limits are two million source samplesand output corners plus 128 MiB of expanded attributes. This projection does notdiff --git a/src/__tests__/__snapshots__/prompt-api.test.ts.snap b/src/__tests__/__snapshots__/prompt-api.test.ts.snapindex 99547ac8..9258cffe 100644--- a/src/__tests__/__snapshots__/prompt-api.test.ts.snap+++ b/src/__tests__/__snapshots__/prompt-api.test.ts.snap@@ -690,11 +690,12 @@ bezierCurve(controlPoints: [x,y,z][], samples?: 32)// curveToMesh(path, 0.1);// UV unwrapping-projectUV(geometry: BufferGeometry, opts: { projection: 'planar'|'box'|'cylindrical', frame?: { origin?: [x,y,z], rotation?: [xDeg,yDeg,zDeg] }, seamDegrees?: number, angularRange?: [startDeg,sweepDeg], caps?: 'planar'|'side' })+projectUV(geometry: BufferGeometry, opts: { projection: 'planar'|'box'|'cylindrical', frame?: { origin?: [x,y,z], rotation?: [xDeg,yDeg,zDeg] }, seamDegrees?: number, angularRange?: [startDeg,sweepDeg], caps?: 'planar'|'side', metersPerUnit?: number })// Generates UV0 explicitly in a rigid geometry-local frame. Planar maps XY; box maps each// face; cylindrical wraps frame Y with separate caps and split angular seams. Replaces- // existing UVs and removes stale tangents. To preserve good UVs use direct sharing or- // copyGeometry instead.+ // existing UVs and removes stale tangents. metersPerUnit maps one UV unit to a fixed length+ // so parts of different size tile at the same density. To preserve good UVs use direct+ // sharing or copyGeometry instead.// e.g. const mapped = projectUV(rawGeometry, { projection: 'cylindrical', frame: { rotation:// [0,0,-90] }, seamDegrees: 180 });remapUV(geometry: BufferGeometry, opts?: { scale?: [u, v], offset?: [u, v] })diff --git a/src/__tests__/uv-projection.test.ts b/src/__tests__/uv-projection.test.tsindex feaaf23f..0185b660 100644--- a/src/__tests__/uv-projection.test.ts+++ b/src/__tests__/uv-projection.test.ts@@ -201,3 +201,74 @@ test('projected UVs and material face coverage survive both GLB converters', asyelse process.env['KILN_GLTF_EXPORTER'] = previous;}});++test('metersPerUnit maps one UV unit to a fixed length from the frame origin', () => {+ const extents = (geometry: THREE.BufferGeometry) => {+ const uv = geometry.getAttribute('uv');+ const u = Array.from({ length: uv.count }, (_, i) => uv.getX(i));+ const v = Array.from({ length: uv.count }, (_, i) => uv.getY(i));+ return [Math.max(...u) - Math.min(...u), Math.max(...v) - Math.min(...v)];+ };+ // Two crates of different size get the same texel density: 0.5 m per tile.+ const small = projectUV(new THREE.BoxGeometry(1, 1, 1), {+ projection: 'box',+ metersPerUnit: 0.5,+ });+ const large = projectUV(new THREE.BoxGeometry(3, 2, 3), {+ projection: 'box',+ metersPerUnit: 0.5,+ });+ expect(extents(small)).toEqual([2, 2]);+ expect(extents(large)).toEqual([6, 6]);+ // Wall pieces sharing a frame continue the same courses: U is measured from the frame origin.+ const left = projectUV(new THREE.PlaneGeometry(2, 1).translate(1, 0.5, 0), {+ projection: 'planar',+ metersPerUnit: 0.25,+ });+ const right = projectUV(new THREE.PlaneGeometry(2, 1).translate(3, 0.5, 0), {+ projection: 'planar',+ metersPerUnit: 0.25,+ });+ const u = (geometry: THREE.BufferGeometry) =>+ Array.from({ length: geometry.getAttribute('uv').count }, (_, i) =>+ geometry.getAttribute('uv').getX(i),+ );+ expect(Math.max(...u(left))).toBe(8);+ expect(Math.min(...u(right))).toBe(8);+ expect(Math.max(...u(right))).toBe(16);+ for (const metersPerUnit of [0, -1, Number.NaN, Number.POSITIVE_INFINITY])+ expect(() => projectUV(new THREE.BoxGeometry(), { projection: 'box', metersPerUnit })).toThrow(+ 'metersPerUnit',+ );+});++test('metric cylindrical projection keeps the full-wrap seam on a whole tile', () => {+ // Circumference 2*pi*0.4 = 2.513 m at 0.3 m per tile is 8.38 tiles; the wrap rounds to 8.+ const source = new THREE.CylinderGeometry(0.4, 0.4, 0.9, 24, 1, true);+ const projected = projectUV(source, { projection: 'cylindrical', metersPerUnit: 0.3 });+ const uv = projected.getAttribute('uv');+ const p = projected.getAttribute('position');+ let seam = 0;+ for (let i = 0; i < uv.count; i++) {+ expect(uv.getX(i)).toBeGreaterThanOrEqual(0);+ expect(uv.getX(i)).toBeLessThanOrEqual(8);+ // The default seam is the -X direction: those corners sit exactly on 0 or 8.+ if (Math.abs(p.getZ(i)) < 1e-6 && p.getX(i) < 0) {+ seam++;+ expect([0, 8]).toContain(uv.getX(i));+ }+ expect(uv.getY(i)).toBeCloseTo(p.getY(i) / 0.3, 5);+ }+ expect(seam).toBeGreaterThan(0);+ // A partial arc has no seam to close: U is the arc length at the largest radius.+ const halfShell = new THREE.CylinderGeometry(0.4, 0.4, 0.9, 12, 1, true, Math.PI / 2, Math.PI);+ const half = projectUV(halfShell, {+ projection: 'cylindrical',+ angularRange: [180, 180],+ metersPerUnit: 0.3,+ });+ const halfU = Array.from({ length: half.getAttribute('uv').count }, (_, i) =>+ half.getAttribute('uv').getX(i),+ );+ expect(Math.max(...halfU)).toBeCloseTo((Math.PI * 0.4) / 0.3, 5);+});diff --git a/src/discovery/helper-contracts.ts b/src/discovery/helper-contracts.tsindex dce70fc7..fed0b665 100644--- a/src/discovery/helper-contracts.ts+++ b/src/discovery/helper-contracts.ts@@ -2597,7 +2597,8 @@ define(axes: 'Rigid frame in geometry-local coordinates: planar XY, box face planes, cylindrical around Y. Euler XYZ rotations are degrees.',origin: 'Frame origin is explicit, default [0,0,0]; geometry positions are preserved.',parameters: [- 'Planar/box axes and cylindrical height normalize each geometry extent to 0..1. This is not metre-scaled UV mapping; a shared frame does not preserve texel density or texture continuity across separate pieces. Preserve authored physical UVs or map each face with explicit dimensions when that is required.',+ 'By default planar/box axes and cylindrical height normalize each geometry extent to 0..1, so texel density changes with part size. metersPerUnit (positive length) instead maps one UV unit to that length measured from the frame origin: parts of any size tile at the same density, and parts sharing a frame keep the same phase. A full cylindrical wrap rounds its circumference at the largest radius to whole tiles so the seam stays continuous; a partial angularRange uses the exact arc length.',+ 'Output is non-indexed. Weld with mergeVertices afterwards where the projection is continuous (one planar face, cylindrical sides); it keeps corners split where UVs or normals differ, such as box faces and the cylindrical seam.','projection is required. frame uses origin/rotation. Cylinder seamDegrees defaults to 180, measured from +X toward +Z; angularRange is [start degrees, positive sweep <=360] instead of seamDegrees.','Cylindrical caps default to planar for triangle normals within 1e-6 of frame Y; caps:side uses side mapping. Partial ranges must cover side vertices, allowing 1e-6 radians of Float32 boundary roundoff.','Nonempty finite positions, valid triangle indices and matching per-vertex attributes; morph targets are unsupported. At most 2000000 source samples/corners and 128 MiB expanded attribute storage.',@@ -2611,8 +2612,17 @@ define({...uvMetadata,references: ['src/uv-project.ts'],- aliases: ['planar projection', 'box mapping', 'cylindrical UVs', 'rotated UV frame'],- intents: ['generate directional texture coordinates in an explicit frame'],+ aliases: [+ 'planar projection',+ 'box mapping',+ 'cylindrical UVs',+ 'rotated UV frame',+ 'metric UVs',+ ],+ intents: [+ 'generate directional texture coordinates in an explicit frame',+ 'keep the same texel density on parts of different size',+ ],limitations: ['Full-wrap seam corners may use U above 1 and require repeat sampling. Side triangles spanning more than half a revolution fail; subdivide the profile. Zero extent maps to 0.5. This is projection, not an atlas or a stretch-free guarantee.',],diff --git a/src/geometry-catalog.ts b/src/geometry-catalog.tsindex 9f0af2d3..aa50db3d 100644--- a/src/geometry-catalog.ts+++ b/src/geometry-catalog.ts@@ -5,7 +5,7 @@ export const REMOVED_AUTHORING_HELPERS: Readonly<Record<string, string>> = ObjecboxUnwrap:'Preserve existing UVs with direct geometry sharing or copyGeometry. Generate new face mappings explicitly with projectUV(geo, { projection: "box", frame? }); planar projection is a separate mode.',cylinderUnwrap:- 'Preserve valid built-in UVs with direct sharing or copyGeometry. For cylindrical mapping use projectUV(geo, { projection: "cylindrical", frame?, seamDegrees?, angularRange?, caps? }); partial arcs need an explicit angularRange.',+ 'Preserve valid built-in UVs with direct sharing or copyGeometry. For cylindrical mapping use projectUV(geo, { projection: "cylindrical", frame?, seamDegrees?, angularRange?, caps?, metersPerUnit? }); partial arcs need an explicit angularRange; metersPerUnit fixes texel density.',planeUnwrap:'Use projectUV(geo, { projection: "planar", frame? }) to generate frame-XY UVs. Preserve existing UVs with direct sharing or copyGeometry instead.',cloneGeometry:@@ -23,11 +23,11 @@ export const geometryPrimitives: readonly HelperSpec[] = [{name: 'projectUV',signature:- "projectUV(geometry: BufferGeometry, opts: { projection: 'planar'|'box'|'cylindrical', frame?: { origin?: [x,y,z], rotation?: [xDeg,yDeg,zDeg] }, seamDegrees?: number, angularRange?: [startDeg,sweepDeg], caps?: 'planar'|'side' })",+ "projectUV(geometry: BufferGeometry, opts: { projection: 'planar'|'box'|'cylindrical', frame?: { origin?: [x,y,z], rotation?: [xDeg,yDeg,zDeg] }, seamDegrees?: number, angularRange?: [startDeg,sweepDeg], caps?: 'planar'|'side', metersPerUnit?: number })",returns: 'THREE.BufferGeometry (owned, non-indexed triangle corners)',category: 'uv',description:- 'Generates UV0 explicitly in a rigid geometry-local frame. Planar maps XY; box maps each face; cylindrical wraps frame Y with separate caps and split angular seams. Replaces existing UVs and removes stale tangents. To preserve good UVs use direct sharing or copyGeometry instead.',+ 'Generates UV0 explicitly in a rigid geometry-local frame. Planar maps XY; box maps each face; cylindrical wraps frame Y with separate caps and split angular seams. Replaces existing UVs and removes stale tangents. metersPerUnit maps one UV unit to a fixed length so parts of different size tile at the same density. To preserve good UVs use direct sharing or copyGeometry instead.',example:"const mapped = projectUV(rawGeometry, { projection: 'cylindrical', frame: { rotation: [0,0,-90] }, seamDegrees: 180 });",},diff --git a/src/uv-project.ts b/src/uv-project.tsindex 827dea5e..98d12873 100644--- a/src/uv-project.ts+++ b/src/uv-project.ts@@ -11,6 +11,12 @@ export interface ProjectUVOptions {angularRange?: readonly [number, number];/** Cylindrical cap triangles parallel to frame XZ use planar UVs by default. */caps?: 'planar' | 'side';+ /**+ * Physical length of one UV unit, in geometry units, measured from the frame origin so+ * pieces sharing a frame share density and phase. A full cylindrical wrap rounds to whole+ * tiles at the largest radius so its seam stays continuous. Default: fit extents to 0..1.+ */+ metersPerUnit?: number;}const MAX_CORNERS = 2_000_000;@@ -26,7 +32,10 @@ export function projectUV(Array.isArray(options) ||!['planar', 'box', 'cylindrical'].includes(options.projection) ||Object.keys(options).some(- (key) => !['projection', 'frame', 'seamDegrees', 'angularRange', 'caps'].includes(key),+ (key) =>+ !['projection', 'frame', 'seamDegrees', 'angularRange', 'caps', 'metersPerUnit'].includes(+ key,+ ),))throw new Error(@@ -58,6 +67,12 @@ export function projectUV();if (options.caps !== undefined && options.caps !== 'planar' && options.caps !== 'side')throw new Error('projectUV: caps must be planar or side.');+ const metric = options.metersPerUnit;+ if (+ metric !== undefined &&+ !(typeof metric === 'number' && Number.isFinite(metric) && metric > 0)+ )+ throw new Error('projectUV: metersPerUnit must be a positive finite length.');const inverse = geometryFrameMatrix(options.frame).invert();const positions = geometry.getAttribute('position');if (positions?.itemSize !== 3 || positions.count < 1 || positions.count > MAX_CORNERS)@@ -103,13 +118,29 @@ export function projectUV(}const extent = bounds.getSize(new THREE.Vector3());const fit = (point: THREE.Vector3, axis: 'x' | 'y' | 'z') =>- extent[axis] > 0 ? (point[axis] - bounds.min[axis]) / extent[axis] : 0.5;+ metric !== undefined+ ? point[axis] / metric+ : extent[axis] > 0+ ? (point[axis] - bounds.min[axis]) / extent[axis]+ : 0.5;+ // Mirrored faces keep their reading direction: 1 - u when fitted, -u when metric.+ const flip = (point: THREE.Vector3, axis: 'x' | 'y' | 'z') =>+ metric !== undefined ? -point[axis] / metric : 1 - fit(point, axis);const outputUVs = new Float32Array(corners * 2);const startDegrees = options.angularRange?.[0] ?? options.seamDegrees ?? 180;const start = ((startDegrees % 360) * Math.PI) / 180;const sweep = ((options.angularRange?.[1] ?? 360) * Math.PI) / 180;const fullWrap = options.angularRange === undefined || options.angularRange[1] === 360;const wrap = (angle: number) => ((angle % (2 * Math.PI)) + 2 * Math.PI) % (2 * Math.PI);+ // U per unit of angular fraction: 1 when fitted; metric arc length at the largest radius,+ // rounded to whole tiles on a full wrap so the seam meets itself.+ let uScale = 1;+ if (metric !== undefined) {+ const radius = points.reduce((max, point) => Math.max(max, Math.hypot(point.x, point.z)), 0);+ uScale = fullWrap+ ? Math.max(1, Math.round((2 * Math.PI * radius) / metric))+ : (sweep * radius) / metric;+ }const normal = new THREE.Vector3();const edge = new THREE.Vector3();for (let i = 0; i < corners; i += 3) {@@ -139,7 +170,7 @@ export function projectUV(throw new Error('projectUV: side triangle spans more than half a revolution; add profile segments to resolve the mapping.',);- pairs = triangle.map((point, j) => [angles[j]!, fit(point, 'y')]);+ pairs = triangle.map((point, j) => [angles[j]! * uScale, fit(point, 'y')]);} else if (cap) {pairs = triangle.map((point) => [fit(point, 'x'), fit(point, 'z')]);} else if (options.projection === 'box') {@@ -151,10 +182,10 @@ export function projectUV(: 'z';pairs = triangle.map((point) => {if (axis === 'x')- return [normal.x > 0 ? 1 - fit(point, 'z') : fit(point, 'z'), fit(point, 'y')];+ return [normal.x > 0 ? flip(point, 'z') : fit(point, 'z'), fit(point, 'y')];if (axis === 'y')- return [fit(point, 'x'), normal.y > 0 ? 1 - fit(point, 'z') : fit(point, 'z')];- return [normal.z < 0 ? 1 - fit(point, 'x') : fit(point, 'x'), fit(point, 'y')];+ return [fit(point, 'x'), normal.y > 0 ? flip(point, 'z') : fit(point, 'z')];+ return [normal.z < 0 ? flip(point, 'x') : fit(point, 'x'), fit(point, 'y')];});} else pairs = triangle.map((point) => [fit(point, 'x'), fit(point, 'y')]);for (let j = 0; j < 3; j++) {