API
new Loom(options?, materials?)
Loom extends THREE.Group and adds two meshes: surface and borders.
| Option | Default | Contract |
|---|---|---|
points |
Four-point S curve | 2–128 tuples [x,y,z] or Three.Vector3 values; closed routes require at least 3. Coordinates are finite in ±1,000,000. |
closed |
false |
Boolean. Closing is automatic; do not duplicate the first point at the end. |
segments |
128 |
Integer from 8 to 4096. Surface subdivision and transported-frame resolution. |
width |
1.8 |
Number or profile; each value is from 0.001 to 1000 world units. |
bank |
0 |
Number or profile; radians from −π to π. |
up |
[0,1,0] |
Finite nonzero tuple/Vector3 defining the preferred initial up direction. Normalized internally. |
uvScale |
2 |
World units per longitudinal UV repeat; finite from 0.001 to 1,000,000. |
borderWidth |
0.09 |
Rectangular border thickness across the ribbon, from 0 to 100 world units. |
borderHeight |
0.16 |
Border height above the ribbon, from 0 to 100. Zero width or height disables both borders. |
A profile contains 2–128 { at, value } keys. Key positions must run strictly from 0 to 1. Unknown option/profile keys, sparse arrays, NaN, infinities, duplicate adjacent points, and near-collinear reversals are rejected. Adjacent point separation must be at least 0.00001 units. A sampled zero tangent also rejects construction. No silent coercion is performed. Omitted options use defaults; explicit undefined is not treated as an omitted value.
The second argument accepts { surface?: THREE.Material, borders?: THREE.Material }. If omitted, Loom creates a double-sided standard surface material and a metallic border material. A supplied material is shared by reference and remains caller-owned. Materials are never serialized in recipes. The two borders are one mesh; separate left/right materials are outside this version's scope.
Properties and methods
| Member | Meaning |
|---|---|
options |
Deep-frozen normalized options copied from input. |
length |
Approximate total centerline arc length in local world units. |
surface |
Mesh with indexed ribbon geometry, position/normal/UV attributes, and bounds. |
borders |
Mesh containing both rectangular edge borders; an empty geometry when disabled. Open border ends are capped. |
disposed |
Whether disposal has occurred. |
sample(u, target?) |
Sample by normalized arc length. Open routes clamp; closed routes wrap. Requires a finite number. |
sampleDistance(distance, target?) |
Sample by local centerline distance; same clamp/wrap policy. |
configure(partialOptions) |
Atomically replace route geometry/data while keeping the two mesh objects and materials; returns this. |
toRecipe() |
Independent JSON-compatible { schema, options } copy. |
Loom.fromRecipe(recipe, materials?) |
Construct from a recipe object or JSON string. Rejects unknown schemas or envelope properties. Missing option fields use defaults. |
dispose() |
Idempotent. Dispose owned geometries/default materials and detach the Loom group and its two meshes. |
After disposal, sampling, configuring, and recipe export throw. Caller-supplied materials remain valid. Arbitrary host children added to the group are neither disposed nor automatically reparented; the detached group still owns those children. The host owns those lifetimes. Do not replace the package-owned geometry references manually. Prefer recipes for copying; inherited Object3D.clone/copy are not Loom reconstruction APIs.
Sampling result
createLoomSample() creates a reusable output object for sample or sampleDistance. Omitting the output creates a new one. Supplying a reusable output avoids allocating the result's vectors/quaternion; no allocation-free performance guarantee is made.
| Field | Meaning |
|---|---|
u |
Clamped or wrapped fraction in [0,1] for open routes, [0,1) for closed routes. |
distance |
That fraction multiplied by route length, rather than an unwrapped travel counter. |
position |
Centerline position in Loom local space. |
tangent |
Unit forward vector. |
right, up |
Orthonormal frame vectors after banking. |
quaternion |
Orientation mapping model +X/right, +Y/up, +Z/forward into the frame. |
width, bank |
Evaluated width and bank at the returned distance. |
All returned vectors and the quaternion are independent mutable values. Changing them does not mutate Loom. Reusing the same sample object overwrites it, so copy values retained elsewhere.
Other exports
LOOM_DEFAULTS: deep-frozen normalized defaults.normalizeLoomOptions(options?): validate and copy without generating GPU geometry; returns normalized frozen options.LoomPoint,LoomProfile,ProfileKey,LoomOptions,NormalizedLoomOptions,LoomMaterials,LoomSample, andLoomRecipe: declaration types.