@flighthq/scene3d-formats 0.2.1-next.840.857425c

package/dist/shared.js

@@ -0,0 +1,143 @@
+import { CANONICAL_SKINNED_MESH_GEOMETRY_LAYOUT } from '@flighthq/mesh';
+import { createTexture } from '@flighthq/texture';
+import { ResourceResolutionState, ImageResourceReferenceKind } from '@flighthq/types';
+export const CANONICAL_FLOATS_PER_VERTEX = 12;
+export const CANONICAL_LAYOUT = {
+    attributes: [
+        { byteOffset: 0, format: 'float32x3', semantic: 'position' },
+        { byteOffset: 12, format: 'float32x3', semantic: 'normal' },
+        { byteOffset: 24, format: 'float32x4', semantic: 'tangent' },
+        { byteOffset: 40, format: 'float32x2', semantic: 'uv0' },
+    ],
+    stride: 48,
+};
+// Floats per vertex in the canonical skinned record (position/normal/tangent/uv0/joints0/weights0),
+// derived from the shared skinned layout so no importer's interleave stride can drift from it.
+export const SKINNED_FLOATS_PER_VERTEX = CANONICAL_SKINNED_MESH_GEOMETRY_LAYOUT.stride / 4;
+// The joint influences per vertex the skinned layout carries (linear-blend skinning's standard 4).
+// Source formats may list more influences per vertex (AWD's shambler uses 8); the top four by weight
+// are kept and renormalized. See packSkinInfluences.
+export const MAX_SKIN_INFLUENCES = 4;
+export function buildEmbeddedImageResourceReference(bytes, mimeType) {
+    return {
+        bytes,
+        failure: null,
+        kind: ImageResourceReferenceKind.Embedded,
+        mimeType,
+        state: ResourceResolutionState.Unresolved,
+    };
+}
+export function buildExternalImageResourceReference(uri, basePath = null) {
+    return {
+        basePath,
+        failure: null,
+        kind: ImageResourceReferenceKind.External,
+        mimeType: null,
+        state: ResourceResolutionState.Unresolved,
+        uri,
+    };
+}
+// Flight uses a right-handed Y-up coordinate system with CCW front faces. Importers for formats
+// that use different conventions apply the conversions below at parse time so every scene enters
+// the graph in Flight's native frame. Every coordinate-space operation passes through one of
+// these helpers so the reason for each transformation is explicit and grep-locatable.
+// Right-handed Z-up → right-handed Y-up: a -90° rotation about X, (x, y, z) → (x, z, -y). The
+// determinant is +1, so triangle winding and cross-product normals are unchanged and no reflection
+// (mirroring) is introduced. Used by every RH Z-up importer — MD2, MD5, and 3DS. stride/offset walk
+// interleaved vertex buffers.
+export function convertPositionsZUpToYUp(values, stride = 3, offset = 0) {
+    for (let i = offset; i + 2 < values.length; i += stride) {
+        const y = values[i + 1];
+        values[i + 1] = values[i + 2];
+        values[i + 2] = -y + 0;
+    }
+}
+// Quaternion companion to convertPositionsZUpToYUp: applies the same -90°-about-X rotation to the
+// vector part (qx, qy, qz) → (qx, qz, -qy), leaving qw. Used for MD5 animation rotations.
+export function convertQuaternionsZUpToYUp(values, stride = 4, offset = 0) {
+    for (let i = offset; i + 3 < values.length; i += stride) {
+        const qy = values[i + 1];
+        values[i + 1] = values[i + 2];
+        values[i + 2] = -qy + 0;
+    }
+}
+export function convertTransformLhToRh(transform) {
+    // AWD 12-float layout: [c0x c0y c0z  c1x c1y c1z  c2x c2y c2z  tx ty tz]
+    // S·M·S negates: c0z(2), c1z(5), c2x(6), c2y(7), tz(11). Index 8 (c2z) stays — double negation.
+    transform[2] = -transform[2] + 0;
+    transform[5] = -transform[5] + 0;
+    transform[6] = -transform[6] + 0;
+    transform[7] = -transform[7] + 0;
+    transform[11] = -transform[11] + 0;
+}
+// Wraps already-in-hand encoded image bytes (a payload carved out of a container, e.g. a PNG inside a
+// GLB buffer or an AWD texture block) as an Unresolved Embedded resource ref on a fresh Texture. The
+// parser carries the bytes but does not decode them — @flighthq/scene3d-resources decodes on resolve.
+// `mimeType` is null when the container did not declare one (the resolver sniffs it from the bytes).
+export function createEmbeddedTextureRef(bytes, mimeType, resources) {
+    let resource = resources?.find((candidate) => candidate.kind === ImageResourceReferenceKind.Embedded &&
+        candidate.bytes === bytes &&
+        candidate.mimeType === mimeType);
+    if (resource === undefined) {
+        resource = buildEmbeddedImageResourceReference(bytes, mimeType);
+        resources?.push(resource);
+    }
+    return createTexture({ resource });
+}
+// Wraps a texture file path/URI declared by a model format as an Unresolved External resource ref on
+// a fresh Texture. The parser references the image, it does not load or decode it — @flighthq/scene3d-
+// resources resolves the ref later, joining a relative `uri` against `basePath` (the directory the
+// container loaded from, null when the format carried none). Shared by the OBJ/MD5/3DS/MD2/glTF
+// material decoders.
+export function createExternalTextureRef(uri, basePath = null, resources) {
+    let resource = resources?.find((candidate) => candidate.kind === ImageResourceReferenceKind.External &&
+        candidate.uri === uri &&
+        candidate.basePath === basePath);
+    if (resource === undefined) {
+        resource = buildExternalImageResourceReference(uri, basePath);
+        resources?.push(resource);
+    }
+    return createTexture({ resource });
+}
+// Left-handed Y-up ↔ right-handed Y-up: negates Z (a reflection across the XY plane, det = -1) on a
+// vec3 stream (positions, normals, tangents). A reflection flips triangle winding, so a caller must
+// pair this with reverseTriangleWinding to keep front faces front-facing. Used by AWD/Stage3D.
+export function negateVec3Z(values) {
+    for (let i = 2; i < values.length; i += 3) {
+        values[i] = -values[i] + 0;
+    }
+}
+// Reduces a vertex's joint influences to the 4-slot joints0/weights0 form linear-blend skinning
+// consumes: keeps the (up to) four highest-weight influences and renormalizes their weights to sum 1,
+// so dropping smaller influences does not dim the vertex. Writes joint indices into `outJoints` and
+// weights into `outWeights` (both length 4), zero-filling unused slots. A vertex with no influence
+// keeps all weights zero (it stays at its bind position). This is the single influence-packing seam
+// every skinned-mesh importer (MD5, AWD) feeds — per-format extraction differs, the emit is shared.
+export function packSkinInfluences(influences, outJoints, outWeights) {
+    for (let i = 0; i < MAX_SKIN_INFLUENCES; i++) {
+        outJoints[i] = 0;
+        outWeights[i] = 0;
+    }
+    // Descending by weight; per-vertex influence counts are tiny, so Array.sort is simplest.
+    influences.sort((a, b) => b.weight - a.weight);
+    const kept = Math.min(influences.length, MAX_SKIN_INFLUENCES);
+    let sum = 0;
+    for (let i = 0; i < kept; i++)
+        sum += influences[i].weight;
+    for (let i = 0; i < kept; i++) {
+        outJoints[i] = influences[i].jointIndex;
+        outWeights[i] = sum > 0 ? influences[i].weight / sum : 0;
+    }
+}
+// Reverses each triangle's winding (swaps v1 and v2). Use whenever a source's front-face winding is
+// opposite to Flight's counter-clockwise-front convention: either paired with a det = -1 reflection
+// such as negateVec3Z (AWD/Stage3D) or on its own for a format whose native winding is clockwise
+// (MD5/id Tech 4, whose Z-up→Y-up rotation preserves the source's clockwise winding).
+export function reverseTriangleWinding(indices) {
+    for (let i = 0; i + 2 < indices.length; i += 3) {
+        const tmp = indices[i + 1];
+        indices[i + 1] = indices[i + 2];
+        indices[i + 2] = tmp;
+    }
+}
+//# sourceMappingURL=shared.js.map

package/dist/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"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"}

package/dist/threeDsParse.d.ts

@@ -0,0 +1,4 @@
+import type { ImportDiagnostic, Scene3D, Scene3DDocument } from '@flighthq/types';
+export declare function createScene3DFrom3ds(bytes: Readonly<Uint8Array>, diagnostics?: ImportDiagnostic[]): Scene3D;
+export declare function parse3ds(bytes: Readonly<Uint8Array>, diagnostics?: ImportDiagnostic[]): Scene3DDocument;
+//# sourceMappingURL=threeDsParse.d.ts.map

package/dist/threeDsParse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"threeDsParse.d.ts","sourceRoot":"","sources":["../src/threeDsParse.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,gBAAgB,EAIhB,OAAO,EACP,eAAe,EAMhB,MAAM,iBAAiB,CAAC;AAoDzB,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAE3G;AAOD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,EAAE,gBAAgB,EAAE,GAAG,eAAe,CAqDvG"}