@driftengine/assets 3.61.0

package/dist/fbxMaterial.js

@@ -0,0 +1,345 @@
+/**
+ * FBX materials and the textures they name. One responsibility: what a surface looks like.
+ *
+ * Split from `fbx.ts` because reading a record tree and interpreting a shading model are
+ * different jobs with different ways of being wrong. The container either parses or it does
+ * not; a material silently comes out the wrong colour.
+ *
+ * **This resolves nothing from disk.** A texture is reported as the string the file wrote,
+ * and turning that into bytes belongs to the caller, which is the only party that knows
+ * whether it is reading a folder, a zip or a URL. The same reasoning as the injected
+ * `Inflate` in `fbx.ts`, for the same reason: this module is part of an engine that runs in
+ * a browser and must not reach for a filesystem.
+ *
+ * **Why the declared path is the only one worth keeping.** These records carry an absolute
+ * `FileName` as well, and it is the author's own machine: the asset this was built against
+ * says `G:\SketchfabRipper_v1.18.0-b2\tools\blender-292\_sfTemp\textures\carbon.jpg`. That
+ * path is dead everywhere except one computer that no longer has the file either. The
+ * `RelativeFilename` beside it says `textures\carbon.jpg`, which is true relative to the
+ * model and is what every other reader uses.
+ */
+/** The engine's own defaults, for a property a material does not state. */
+const DEFAULT_COLOR = [0.8, 0.8, 0.8];
+const DEFAULT_ROUGHNESS = 0.4277;
+/**
+ * What a surface with no material at all is shaded as.
+ *
+ * Exported so the geometry reader has no null to branch on. A geometry can genuinely reach
+ * the reader wearing nothing, and a fallback stated once here is better than the same three
+ * defaults spelled out at each use, which is how two of them end up disagreeing.
+ */
+export const FALLBACK_MATERIAL = {
+    name: '',
+    color: DEFAULT_COLOR,
+    specular: 0,
+    roughness: DEFAULT_ROUGHNESS,
+    emissive: 0,
+    opacity: 1,
+    reflectivity: 0,
+    normalMap: -1,
+    ormMap: -1,
+    emissiveMap: -1,
+    roughnessScale: 1,
+    metallicScale: 1,
+    occlusionStrength: 0,
+    cutout: 0,
+    emissiveColor: [-1, -1, -1],
+    albedo: -1,
+};
+/** A record's first property, when it is a string. */
+function stringChild(node, name) {
+    const value = node.children.find((child) => child.name === name)?.properties[0];
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+/**
+ * The bytes of an embedded image, if this video carries one.
+ *
+ * A `Content` record with nothing in it is common and means "this image lives outside the
+ * file" rather than "this image is empty", so a zero length payload has to read as absent.
+ * Treating it as present embeds a zero byte texture, which decodes to nothing and takes the
+ * place of the path that would have worked.
+ */
+function contentOf(video) {
+    const value = video.children.find((child) => child.name === 'Content')?.properties[0];
+    return value instanceof Uint8Array && value.length > 0 ? value : undefined;
+}
+function propertiesOf(node) {
+    const out = new Map();
+    for (const child of node.children) {
+        if (child.name !== 'Properties70')
+            continue;
+        for (const property of child.children) {
+            const name = property.properties[0];
+            if (typeof name === 'string')
+                out.set(name, property.properties.slice(4));
+        }
+    }
+    return out;
+}
+function numberAt(values, at, fallback) {
+    const value = values?.[at];
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+function triple(values, fallback, scale = 1) {
+    if (values === undefined)
+        return [fallback[0], fallback[1], fallback[2]];
+    return normaliseColor([
+        numberAt(values, 0, fallback[0]) * scale,
+        numberAt(values, 1, fallback[1]) * scale,
+        numberAt(values, 2, fallback[2]) * scale,
+    ]);
+}
+/**
+ * A colour whose components exceed one is a fraction that lost its decimal point.
+ *
+ * Measured in the asset this was built against, which stores `silver` as
+ * `815686, 815686, 815686` and `copper` as `235294, 184314, 137255`. Those are not colours
+ * and they are not a scale factor either: they are `0.815686` and `0.235294, 0.184314,
+ * 0.137255` written as their fractional digits alone. Every one is six digits, which is what
+ * makes the repair well defined rather than a guess, and `calipers` proves the reading —
+ * it stores `8, 564706, 160784`, where the `8` is `000008` with its leading zeros lost the
+ * moment it was read as a number.
+ *
+ * **Each channel is divided by its own digit count**, because each is its own fraction. That
+ * is settled by the asset rather than argued: read this way the calipers come out
+ * `0.8, 0.564706, 0.160784`, a gold, and the vendor's own reference render shows gold brake
+ * calipers. A shared divisor taken from the largest channel was tried first, on the theory
+ * that the `8` was `000008` with its leading zeros lost, and it produces a green caliper.
+ * Looking at the reference is what decided it, which is the whole lesson of this pipeline.
+ *
+ * A component above one is never legitimate here: FBX's `DiffuseColor` is defined over nought
+ * to one, and this engine has no high dynamic range material input for it to mean instead. So
+ * the test cannot fire on a colour somebody meant.
+ */
+function normaliseColor(color) {
+    const digits = (value) => {
+        if (!(value > 1))
+            return value;
+        let divisor = 1;
+        while (value / divisor > 1)
+            divisor *= 10;
+        return value / divisor;
+    };
+    return [digits(color[0]), digits(color[1]), digits(color[2])];
+}
+/**
+ * A Phong exponent as a roughness.
+ *
+ * The two describe the same thing from opposite ends: the exponent says how *tightly* a
+ * highlight is gathered and rises without bound, roughness says how widely it is spread over
+ * nought to one. `sqrt(2 / (n + 2))` is the usual correspondence and it lands where intuition
+ * expects at both ends, with a mirror-like 1000 arriving at 0.04 and a flat 2 at 0.7.
+ *
+ * It is an approximation between two different shading models and is stated as one. What it
+ * must not do is default to zero: an unstated exponent read as a mirror makes every surface
+ * in an imported scene a black mirror, which reads as a lighting fault rather than a material
+ * one.
+ */
+/**
+ * How opaque a surface is, from whichever of the two spellings a writer used.
+ *
+ * They mean opposite things and that is the trap: `TransparencyFactor` is how *transparent*
+ * a surface is, so opacity is one minus it, while `Opacity` is already what it says. Reading
+ * one as the other turns every solid surface in an export invisible, and an invisible model
+ * reads as a failed load rather than as a material fault.
+ *
+ * Silence means opaque. Defaulting the other way would make every material in a file that
+ * omits both vanish, which is most files.
+ */
+function opacityOf(p) {
+    const clamp = (value) => Math.min(1, Math.max(0, value));
+    if (p.has('TransparencyFactor'))
+        return clamp(1 - numberAt(p.get('TransparencyFactor'), 0, 0));
+    if (p.has('Opacity'))
+        return clamp(numberAt(p.get('Opacity'), 0, 1));
+    return 1;
+}
+function roughnessFromShininess(exponent) {
+    if (!(exponent > 0))
+        return DEFAULT_ROUGHNESS;
+    return Math.min(1, Math.max(0.02, Math.sqrt(2 / (exponent + 2))));
+}
+/**
+ * Materials, their textures, and which model wears which.
+ *
+ * Textures reach a material through an `OP` connection, which is FBX for "this object feeds
+ * that object's *named property*" — the property being `DiffuseColor`, `NormalMap`,
+ * `SpecularColor` and so on. Only the albedo is used, because it is the only one this
+ * renderer has a slot for; the rest are counted and reported rather than dropped in silence,
+ * so a model that looks flatter than it should says why.
+ */
+export function readMaterials(root, warnings) {
+    const materialNodes = new Map();
+    const textureNodes = new Map();
+    const videoNodes = new Map();
+    for (const objects of root.children.filter((child) => child.name === 'Objects')) {
+        for (const node of objects.children) {
+            const id = node.properties[0];
+            if (typeof id !== 'number')
+                continue;
+            if (node.name === 'Material')
+                materialNodes.set(id, node);
+            else if (node.name === 'Texture')
+                textureNodes.set(id, node);
+            else if (node.name === 'Video')
+                videoNodes.set(id, node);
+        }
+    }
+    /*
+     * Which video backs which texture, from the connection table.
+     *
+     * A `Media` property naming the video by string exists too and is what older writers use,
+     * so it is the fallback. The connection is preferred because a name is a name and an id is
+     * a fact: two videos may be called the same thing, and only one of them is connected.
+     */
+    const videoOfTexture = new Map();
+    for (const connections of root.children.filter((child) => child.name === 'Connections')) {
+        for (const c of connections.children) {
+            const [kind, from, to] = c.properties;
+            if (kind !== 'OO' || typeof from !== 'number' || typeof to !== 'number')
+                continue;
+            const video = videoNodes.get(from);
+            if (video !== undefined && textureNodes.has(to))
+                videoOfTexture.set(to, video);
+        }
+    }
+    for (const [id, node] of textureNodes) {
+        if (videoOfTexture.has(id))
+            continue;
+        const media = stringChild(node, 'Media');
+        if (media === undefined)
+            continue;
+        for (const [, video] of videoNodes) {
+            if (String(video.properties[1] ?? '') === media) {
+                videoOfTexture.set(id, video);
+                break;
+            }
+        }
+    }
+    /*
+     * Texture id to an index in the reference list, deduplicated by what it resolves to.
+     *
+     * **FBX embeds its images as often as it points at them**, and the two look nothing alike.
+     * An embedded texture's `RelativeFilename` is `*0`, a reference into the file's own video
+     * list rather than a path, and the bytes live in the matching `Video` record's `Content`.
+     * Treating that as a filename produces a hunt for a file called `*0`, which fails, and a
+     * model that draws untextured while the image it needs sits inside the file being read.
+     */
+    const textures = [];
+    const candidates = new Map();
+    for (const [id, node] of textureNodes) {
+        const declared = stringChild(node, 'RelativeFilename') ?? stringChild(node, 'FileName') ?? '';
+        const video = videoOfTexture.get(id);
+        const content = video === undefined ? undefined : contentOf(video);
+        /* An embedded image names itself by its video's filename, because `*0` names nothing. */
+        const name = content !== undefined
+            ? (stringChild(video, 'RelativeFilename') ??
+                stringChild(video, 'Filename') ??
+                declared)
+            : declared;
+        if (content === undefined && (name === '' || name.startsWith('*'))) {
+            warnings.push(name.startsWith('*')
+                ? `texture "${name}" is embedded but its image is missing from the file; it will draw untextured`
+                : 'a texture record states no filename and was skipped');
+            continue;
+        }
+        /*
+         * Held as a candidate, not embedded yet.
+         *
+         * **A file names far more textures than this renderer can use.** One test character
+         * carries normal, roughness and metallic maps beside every colour map, and embedding all
+         * of them produced a 401 MB asset against the 94 MB the same model makes through OBJ —
+         * three quarters of it maps that were reported as ignored in the same run. Nothing was
+         * wrong with the ignoring; the list was simply built from every `Texture` record rather
+         * than from the ones a material actually reaches. So an entry earns its place below, when
+         * something binds it.
+         */
+        candidates.set(id, {
+            reference: content === undefined ? { name } : { name, bytes: content },
+            key: content === undefined ? `path:${name}` : `embedded:${id}`,
+        });
+    }
+    /* Which texture feeds which material, and through which of the material's properties. */
+    const albedoOfMaterial = new Map();
+    const ignoredSlots = new Map();
+    /** Allocate a slot for a texture the first time something actually binds it. */
+    const claim = new Map();
+    for (const connections of root.children.filter((child) => child.name === 'Connections')) {
+        for (const c of connections.children) {
+            const [kind, from, to, slot] = c.properties;
+            if (kind !== 'OP' || typeof from !== 'number' || typeof to !== 'number')
+                continue;
+            const candidate = candidates.get(from);
+            if (candidate === undefined || !materialNodes.has(to))
+                continue;
+            if (slot !== 'DiffuseColor') {
+                if (typeof slot === 'string')
+                    ignoredSlots.set(slot, (ignoredSlots.get(slot) ?? 0) + 1);
+                continue;
+            }
+            let at = claim.get(candidate.key);
+            if (at === undefined) {
+                at = textures.length;
+                claim.set(candidate.key, at);
+                textures.push(candidate.reference);
+            }
+            albedoOfMaterial.set(to, at);
+        }
+    }
+    for (const [slot, count] of ignoredSlots) {
+        warnings.push(`${count} ${slot} texture${count === 1 ? '' : 's'} ignored; this renderer has one texture slot, for colour`);
+    }
+    const byId = new Map();
+    for (const [id, node] of materialNodes) {
+        const p = propertiesOf(node);
+        const emissiveColor = triple(p.get('EmissiveColor'), [0, 0, 0], numberAt(p.get('EmissiveFactor'), 0, 1));
+        const emissive = Math.min(1, Math.max(emissiveColor[0], emissiveColor[1], emissiveColor[2]));
+        byId.set(id, {
+            name: typeof node.properties[1] === 'string'
+                ? (node.properties[1].split('\u0000')[0] ?? '')
+                : '',
+            color: triple(p.get('DiffuseColor'), DEFAULT_COLOR, numberAt(p.get('DiffuseFactor'), 0, 1)),
+            specular: Math.min(1, Math.max(0, numberAt(p.get('SpecularFactor'), 0, 0))),
+            roughness: roughnessFromShininess(numberAt(p.get('ShininessExponent'), 0, numberAt(p.get('Shininess'), 0, 0))),
+            /*
+             * FBX states how transparent a surface is, so opacity is one minus it. Both
+             * spellings are read because writers disagree, and a file that says nothing is
+             * opaque rather than invisible: defaulting the other way would make every material
+             * in an export that omits it disappear.
+             */
+            opacity: opacityOf(p),
+            /* FBX states this directly, and it is the property that decides whether paint reads as
+               paint. Read past until now, which is why an imported car looked flat. */
+            reflectivity: Math.min(1, Math.max(0, numberAt(p.get('ReflectionFactor'), 0, 0))),
+            normalMap: -1,
+            ormMap: -1,
+            emissiveMap: -1,
+            roughnessScale: 1,
+            metallicScale: 1,
+            occlusionStrength: 0,
+            cutout: 0,
+            emissive,
+            /* A negative component means "inherit the albedo", which is the engine's own default
+               and the right answer for a surface that names no emissive colour of its own. */
+            emissiveColor: emissive > 0 ? emissiveColor : [-1, -1, -1],
+            albedo: albedoOfMaterial.get(id) ?? -1,
+        });
+    }
+    /* Model to its materials, in file order, because that order is what an index means. */
+    const ofModel = new Map();
+    for (const connections of root.children.filter((child) => child.name === 'Connections')) {
+        for (const c of connections.children) {
+            const [kind, from, to] = c.properties;
+            if (kind !== 'OO' || typeof from !== 'number' || typeof to !== 'number')
+                continue;
+            if (!byId.has(from))
+                continue;
+            const list = ofModel.get(to);
+            if (list === undefined)
+                ofModel.set(to, [from]);
+            else
+                list.push(from);
+        }
+    }
+    return { byId, ofModel, textures };
+}

package/dist/fbxRig.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The rig inside an FBX: a skeleton, what it is bound to, and the takes that move it.
+ *
+ * **Split from `fbx.ts` on the terms `fbxMaterial.ts` already set.** That file reads geometry and
+ * knows nothing about deformers; this one reads deformers and knows nothing about polygons. They
+ * meet over two small things — a control point's influences, and which model each joint is — and
+ * keeping them apart is what stops the mesh loop growing a second subject.
+ *
+ * **What FBX calls a skin is three record kinds and four connections.** A `Deformer` of subtype
+ * `Skin` hangs off a `Geometry`; a `Deformer` of subtype `Cluster` hangs off that skin, one per
+ * bone; and a `Model` of subtype `LimbNode` hangs off each cluster. The weights live on the
+ * cluster, keyed by control point, which is why they are read here and applied where the corners
+ * are walked.
+ *
+ * **The bind pose is two matrices and not one.** A cluster carries `TransformLink`, where the bone
+ * was when the mesh was bound, and `Transform`, where the *mesh* was. The engine's `inverseBind`
+ * takes a vertex from model space into the joint's bind space, so it is the inverse of the first
+ * times the second. Taking `TransformLink` alone is right exactly while the mesh sits at the
+ * origin with no rotation, which is what a hand-made test file does and what a bought character
+ * does not — the failure is a figure that is correctly posed and standing in the wrong place.
+ *
+ * **This is tier 2 and says so.** What it does not read: `PostRotation`, rotation orders other than
+ * the default, blend-shape channels driven by curves, and the `Take` records of pre-7000 files.
+ * Each is named where it is refused rather than silently approximated.
+ */
+import type { AnimationClip, Joint } from '@driftengine/drft';
+import type { FbxNode } from './fbx.ts';
+/**
+ * An object's own name, with the class the container tags it with taken off.
+ *
+ * **The two forms are not the same string, and only one of them looks like a separator.** ASCII FBX
+ * writes `Model::spine_01`, which is what a reader tends to be written against because it is what
+ * the specification's examples show. Binary FBX — which is the only form this reader accepts —
+ * writes `spine_01\0\x01Model`: the name first, then a null and a `\x01`, then the class. Knowing
+ * only the ASCII form left every joint of a bought character named
+ * `rp_nathan_animated_003_walking_spine_01\0\x01Model` and its take named `Take 001\0\x01AnimStack`.
+ *
+ * Nothing fails on a name, which is why it survived: `Joint.name` is what **retargeting matches
+ * on**, so a rig whose every joint carries a class suffix matches nothing, one subsystem away from
+ * the reader that wrote it.
+ */
+export declare function bareName(raw: unknown, fallback: string): string;
+/** Every `Objects` child, by id, with the class the record's third property names. */
+export interface FbxObjects {
+    readonly byId: Map<number, FbxNode>;
+    /** child id to every parent it names, in file order. A bone names its cluster *and* its parent. */
+    readonly parentsOf: Map<number, number[]>;
+    /** `OP` connections: child id to the [parent, property] pairs it drives. */
+    readonly drives: Map<number, {
+        readonly parent: number;
+        readonly property: string;
+    }[]>;
+}
+export declare function indexObjects(root: FbxNode): FbxObjects;
+/** A skin, as this reader hands it on: the skeleton, and the influences keyed by control point. */
+export interface FbxSkin {
+    readonly joints: readonly Joint[];
+    readonly inverseBind: Float32Array;
+    /**
+     * Control point index to its influences, as [joint, weight] pairs.
+     *
+     * A map rather than a dense array because a cluster covers the control points it covers: a
+     * character's rig leaves nothing unweighted, and a prop bound to one bone leaves almost
+     * everything out of every cluster but one.
+     */
+    readonly influences: Map<number, {
+        joint: number;
+        weight: number;
+    }[]>;
+    /** Model id of each joint, in the sorted order, so a curve can find the track it belongs to. */
+    readonly modelOfJoint: readonly number[];
+}
+/**
+ * The skin bound to one geometry, or null where nothing is.
+ *
+ * **The joints are sorted parents-first here**, because this is also the layer that can remap
+ * every index naming one — the mesh's own joint attribute is written from `influences` afterwards.
+ * `Skeleton` refuses an unsorted rig rather than sorting it, for exactly that reason.
+ */
+export declare function readSkin(objects: FbxObjects, geometryId: number, 
+/**
+ * Where the mesh this skin deforms sits, from the node graph.
+ *
+ * **This is the half a cluster's own `Transform` claims to be and cannot be trusted for.** The
+ * SDK documents `Transform` as the mesh's global transform at bind time, which makes it one
+ * matrix for the whole skin — and a bought character measured here has **sixty-eight of its
+ * sixty-nine weight-bearing clusters disagreeing about it**, each holding something close to the
+ * inverse of its own `TransformLink` instead. Composed as documented, the bone's frame goes in
+ * twice: the inverse bind for that character's hip came back as a pure translation of
+ * `(0, -94.4, +94.4)` where the joint is at `(0, 94.4, 0)`, so inverting it put every joint on a
+ * mirror of the skeleton that no geometry occupies.
+ *
+ * So the mesh's bind transform is taken from the one authority this reader already has for where
+ * anything is, which is the same walk every static mesh goes through. It is also what the other
+ * readers of this format settle on, and for the same reason.
+ */
+meshWorld: readonly number[], warnings: string[]): FbxSkin | null;
+/**
+ * One control point's four influences, largest first, normalised, written into a caller's arrays.
+ *
+ * **Four is the shader's number and the file's is unbounded.** A rig authored with six influences
+ * on a shoulder is ordinary, so the four largest are kept and renormalised rather than the first
+ * four taken: dropping by *order* would discard whichever the exporter happened to write last,
+ * which on a shoulder is as likely to be the dominant one as not.
+ *
+ * Returns true where something was dropped or rescaled, so the caller can say so once for the mesh
+ * rather than once per vertex.
+ */
+export declare function writeInfluences(influences: readonly {
+    joint: number;
+    weight: number;
+}[] | undefined, joints: Float32Array, weights: Float32Array, at: number): {
+    dropped: boolean;
+    rescaled: boolean;
+};
+/**
+ * Every take in the file, as clips over the joints a skin named.
+ *
+ * **A curve is per channel and a track is per joint**, so the three curves under one curve node are
+ * merged onto one timeline: the union of their key times, each channel read at that time. A key a
+ * channel does not have is held at its neighbour rather than interpolated, which is what a stepped
+ * read of a curve gives and is exact wherever the exporter wrote all three channels together —
+ * which is what every exporter does for a joint it is baking.
+ *
+ * **Rotation arrives as Euler degrees and leaves as a quaternion**, in the file's default XYZ
+ * order. A joint carrying a `PreRotation` or a non-default `RotationOrder` is named in a warning
+ * rather than approximated: both are silent when read wrongly, and a limb that is ninety degrees
+ * out reads as a broken clip rather than as an unread field.
+ */
+export declare function readClips(objects: FbxObjects, jointOfModel: ReadonlyMap<number, number>, warnings: string[]): AnimationClip[];