@needle-tools/gltf-build-pipeline 2.14.0-alpha → 2.14.0-next.66c769b

package/README.md

@@ -23,9 +23,103 @@ To load progressively enhanced glTF files in any three.js based engine see examp
 
 `npx @needle-tools/gltf-build-pipeline@latest`
 
+### CLI Commands
+
+- `stats <input> <output>` - Calculate basic stats
+- `detailed-stats <input>` - Analyze file structure, component counts, and mesh merging potential
+- `mesh-merge <input> <output> [options]` - Merge meshes with shared materials to reduce draw calls
+  - `--min-vertices <n>` - Only merge meshes with >n vertices
+  - `--max-vertices <n>` - Target max vertices per merged mesh (default: 65535)
+  - `--dry-run` - Analyze potential without writing file
+- `transform <input> <output> [options]` - Generate LODs and compress
+- `clear-caches` - Clear all caches
+
 ### Commands
 - `help` - use help to view options
 
+## Development
+
+### Building
+
+```bash
+cd package
+npm install
+npx tsc
+```
+
+### Running the CLI locally
+
+After building, you can run the CLI directly with node:
+
+```bash
+# Transform a GLB file
+node dist/cli/index.js transform <input.glb> <output-directory> [options]
+
+# Example with verbose output
+node dist/cli/index.js transform "path/to/model.glb" "path/to/output" --verbose True
+
+# View help
+node dist/cli/index.js help
+```
+
+**Note:** On Windows, using `node` directly avoids path issues with special characters (spaces, `&`, etc.) that can occur with `npx`.
+
+### Running Tests
+
+```bash
+cd package
+
+# Run all tests (uses Node.js built-in test runner)
+npm test
+
+# Run tests directly
+node --test src/tests/
+```
+
+### Test Files
+
+Test files are located in `src/tests/`:
+- `transform-paths.test.mjs` - Tests path handling with special characters (spaces, commas, ampersands, parentheses)
+- `path-handling.test.mjs` - Additional path handling tests
+
+### Clearing the Cache
+
+The build pipeline caches processed meshes and textures. To force reprocessing:
+
+```powershell
+# Windows
+Remove-Item "$env:LOCALAPPDATA\Temp\Needle\build-pipeline-cache" -Recurse -Force
+
+# Or find the cache location from the log output:
+# "Limit cache size to X MB at C:\Users\...\Temp\Needle\build-pipeline-cache"
+```
+
+### Performance Profiling
+
+When processing large files, the pipeline outputs detailed performance statistics:
+- Mesh processing throughput (meshes/s, vertices/s)
+- Cache hit/miss rates
+- Time breakdown (simplification, I/O, hashing)
+
+Example output:
+```
+[NEEDLE_progressive]: ═══════════════════════════════════════════════════════════
+[NEEDLE_progressive]: MESH PROCESSING SUMMARY for "model.glb"
+[NEEDLE_progressive]: ───────────────────────────────────────────────────────────
+[NEEDLE_progressive]: Total time: 45.23s
+[NEEDLE_progressive]: Meshes: 150 processed, 20 skipped (of 170 total)
+[NEEDLE_progressive]: Vertices: 1,234,567 input → 456,789 output
+[NEEDLE_progressive]: LOD levels generated: 450
+[NEEDLE_progressive]: Cache: 100 hits, 350 misses
+[NEEDLE_progressive]: Time breakdown:
+[NEEDLE_progressive]:   - Simplification: 30.12s
+[NEEDLE_progressive]:   - I/O Write: 10.45s
+[NEEDLE_progressive]:   - I/O Read (cache): 2.34s
+[NEEDLE_progressive]:   - Hashing: 2.32s
+[NEEDLE_progressive]: Throughput: 27,293 vertices/s
+[NEEDLE_progressive]: ═══════════════════════════════════════════════════════════
+```
+
 # Contact
 
 For licensing questions please contact us.

package/dist/cli/index.js

@@ -2,6 +2,8 @@
 import { program } from '@donmccurdy/caporal';
 import { calculateStats, packGLTF } from "../scripts/index.js";
 import { printStats, writeFileStatsToFile } from '../utils/stats.js';
+import { calculateDetailedStats, printDetailedStats } from '../scripts/detailed-stats.js';
+import { runMeshMerge } from '../scripts/mesh-merge.js';
 import { getVersion } from '../utils/version.js';
 import { UsecaseOptions, createConfig, getConfig } from '../config/index.js';
 import { isLOD, make_progressive } from '../transforms/needle_progressive.js';
@@ -50,6 +52,58 @@ Caches are limited to ${cacheSizeLimit} MB disc space by default.
     }
     logger.info("Writing stats to: " + output);
     writeFileStatsToFile(filestats, output);
+})
+    .command("detailed-stats", "Calculate detailed glTF stats with top N items")
+    .help(`
+Analyzes a glTF/GLB/VRM file and prints detailed statistics including:
+- File size and load time
+- Extensions used
+- Hierarchy depth/breadth
+- Top 5 biggest meshes, accessors, textures
+- Needle component counts
+`)
+    .argument('<input>', "Path to a glTF, GLB or VRM file")
+    .action(async ({ logger, args }) => {
+    logger.level = "info";
+    const input = args.input.toString();
+    console.log(`\nAnalyzing: ${input}`);
+    console.log('Please wait...\n');
+    try {
+        const stats = await calculateDetailedStats(input);
+        printDetailedStats(stats);
+        // Explicitly exit to ensure hanging promises (like meshopt/draco) don't keep process alive
+        process.exit(0);
+    }
+    catch (error) {
+        logger.error(`Failed to analyze file: ${error}`);
+        process.exit(1);
+    }
+})
+    .command("mesh-merge", "Merge meshes with shared materials")
+    .help(`
+Merges primitives that share the same material and vertex attributes.
+Reduces draw calls but may increase file size slightly due to less reuse of shared accessors.
+`)
+    .argument('<input>', "Path to input glTF/GLB file")
+    .argument('<output>', "Path to output glTF/GLB file")
+    .option('--min-vertices <n>', 'Minimum vertices to include in merge', { validator: program.NUMBER, default: 0 })
+    .option('--max-vertices <n>', 'Maximum vertices per merged mesh', { validator: program.NUMBER, default: 65535 })
+    .option('--dry-run', 'Analyze only, do not merge', { validator: program.BOOLEAN, default: false })
+    .action(async ({ logger, args, options }) => {
+    logger.level = "info";
+    try {
+        await runMeshMerge(args.input.toString(), args.output.toString(), {
+            minVertices: Number(options.minVertices),
+            maxVerticesPerMesh: Number(options.maxVertices),
+            dryRun: !!options.dryRun,
+            logger
+        });
+        process.exit(0);
+    }
+    catch (error) {
+        logger.error(`Failed to merge meshes: ${error}`);
+        process.exit(1);
+    }
 })
     .command("transform", "Transform (progressive loading) and compress glTF, GLB or VRM files")
     .help(`

package/dist/scripts/detailed-stats.d.ts

@@ -0,0 +1,180 @@
+import { type MeshMergeAnalysis } from "../transforms/needle_mesh_merge.js";
+/**
+ * Distribution band for histogram display
+ */
+export interface DistributionBand {
+    label: string;
+    min: number;
+    max: number;
+    count: number;
+    percentage: number;
+}
+/**
+ * Detailed stats analysis for a glTF file
+ */
+export interface DetailedStats {
+    file: {
+        path: string;
+        sizeBytes: number;
+        sizeMB: number;
+        loadTimeMs: number;
+    };
+    extensions: {
+        used: string[];
+        required: string[];
+    };
+    hierarchy: {
+        nodeCount: number;
+        maxDepth: number;
+        maxBreadth: number;
+        sceneCount: number;
+        rootNodeCount: number;
+    };
+    meshes: {
+        count: number;
+        primitiveCount: number;
+        totalVertices: number;
+        totalTriangles: number;
+        memoryBytes: number;
+        top5ByVertices: {
+            name: string;
+            vertices: number;
+            triangles: number;
+            primitives: number;
+        }[];
+        distribution: DistributionBand[];
+    };
+    accessors: {
+        count: number;
+        totalBytes: number;
+        top5BySize: {
+            name: string;
+            type: string;
+            count: number;
+            bytes: number;
+        }[];
+    };
+    buffers: {
+        count: number;
+        totalBytes: number;
+        top5BySize: {
+            name: string;
+            bytes: number;
+        }[];
+    };
+    textures: {
+        count: number;
+        totalMemoryBytes: number;
+        totalGPUBytes: number;
+        mimeTypeMismatchCount: number;
+        top5ByPixelArea: {
+            name: string;
+            width: number;
+            height: number;
+            pixelArea: number;
+            mimeType: string;
+            mismatch: boolean;
+            bytes: number;
+            gpuBytes: number;
+        }[];
+        top5ByFileSize: {
+            name: string;
+            bytes: number;
+            mimeType: string;
+        }[];
+        formats: string[];
+        distribution: DistributionBand[];
+    };
+    materials: {
+        count: number;
+        top5ByTextureCount: {
+            name: string;
+            textureCount: number;
+        }[];
+        top5ByUsage: {
+            name: string;
+            usageCount: number;
+        }[];
+    };
+    animations: {
+        count: number;
+        channelCount: number;
+        totalBytes: number;
+    };
+    nodesWithExtensions: {
+        count: number;
+        extensionCounts: Record<string, number>;
+    };
+    needleComponents: {
+        nodeCount: number;
+        componentCount: number;
+        componentTypes: Record<string, number>;
+    };
+    validation: {
+        errorCount: number;
+        warningCount: number;
+        infoCount: number;
+        top5Errors: string[];
+        top5Warnings: string[];
+    };
+    emptyNodes: {
+        count: number;
+        examples: string[];
+    };
+    tinyMeshes: {
+        count: number;
+        examples: {
+            name: string;
+            vertices: number;
+            triangles: number;
+        }[];
+        dedupAnalysis?: {
+            uniqueGeometries: number;
+            uniqueStructural: number;
+            uniqueByteHashes: number;
+            dedupPotentialPct: string;
+            topDuplicates: {
+                count: number;
+                uniqueMaterials: number;
+                materials: string[];
+            }[];
+        };
+    };
+    allMeshesDedupAnalysis?: {
+        totalMeshes: number;
+        totalVertices: number;
+        uniqueByContent: number;
+        uniqueByBytes: number;
+        uniqueByStructure: number;
+        dedupPotentialPct: string;
+        topDuplicates: {
+            hash: string;
+            count: number;
+        }[];
+        perBucketStats: {
+            bucket: string;
+            meshes: number;
+            uniqueContent: number;
+            uniqueStructural: number;
+            dedupPotentialPct: string;
+        }[];
+    };
+    meshMergeAnalysis?: MeshMergeAnalysis;
+    materialBuckets: {
+        bucketCount: number;
+        totalMaterialsInBuckets: number;
+        top5Buckets: {
+            baseColor: string;
+            materialCount: number;
+            names: string[];
+        }[];
+    };
+}
+/**
+ * Calculate detailed stats for a glTF file
+ */
+export declare function calculateDetailedStats(inputFile: string): Promise<DetailedStats>;
+/**
+ * Print detailed stats to console
+ */
+export declare function printDetailedStats(stats: DetailedStats): void;