GLB Model Extractor

A web-based tool for extracting individual models from GLB collection files. Supports topology cleaning, island splitting, and automatic merging by name patterns.

Features

• Individual Model Extraction: Extract each mesh from a GLB collection as a separate file
• Topology Cleaning: Merge duplicate vertices and remove degenerate faces
• Island Splitting: Separate disconnected geometry parts into individual files
• Name Pattern Merging: Automatically merge models containing matching name patterns
• Dry Run Mode: Preview extraction results without exporting files
• Console Logging: Detailed console output showing extraction progress

Project Structure

3D-Modells/                      # Root folder (contains your 3D models)
│
└── glb-extractor/               # Project folder
    ├── README.md                # This file
    ├── package.json             # Node.js dependencies
    ├── package-lock.json        # Locked dependency versions
    ├── .gitignore               # Git ignore rules
    ├── tools/                   # Extraction tools
    │   ├── extract_glb_models.html # Web-based GUI tool (recommended)
    │   └── extract_glb_models.js   # Node.js CLI tool
    ├── docs/                    # Documentation
    │   ├── USAGE.md             # Detailed usage guide
    │   └── STRUCTURE.md         # Project structure reference
    └── node_modules/            # Dependencies (installed via npm)

Quick Start

Web-Based Tool (Standalone - No Installation Required)

The web tool is completely standalone - no installation, no server, no npm needed!

1. Navigate to the glb-extractor folder
2. Open tools/extract_glb_models.html in any modern web browser
   • Just double-click the file, or
   • Right-click → Open with → Browser
3. Click "Select GLB Collection File" and choose your GLB file
4. Configure extraction options:
   • Clean topology: Enable to merge duplicate vertices
   • Vertex Merge Threshold: Distance threshold for merging vertices
   • Split by islands: Separate disconnected parts
   • Name pattern: Comma-separated patterns to merge matching models
   • Dry run: Preview without exporting
5. Click "Extract Models"
6. Files will be downloaded automatically

Note: The HTML file loads Three.js from CDN, so you need an internet connection for the first use. All dependencies are loaded automatically - no installation required!

Node.js CLI Tool (Optional)

For command-line usage, Node.js installation is required:

# Navigate to project folder
cd glb-extractor

# Install dependencies (only needed for CLI tool)
npm install

# Run extraction
npm run extract <input.glb> [output-directory]

Example:

cd glb-extractor
npm run extract ../my_collection.glb ../extracted

Usage Guide

Topology Cleaning

When enabled, merges vertices that are closer than the specified threshold. Useful for:

• Fixing mesh artifacts
• Reducing vertex count
• Ensuring proper connectivity for island detection

Merge Threshold: Default is 0.0001 units. Smaller values = stricter merging.

Island Splitting

Separates disconnected geometry parts into individual files. Example:

• A GLB with 3 separate objects → 3 separate GLB files
• Each island gets a _part_N suffix

Name Pattern Merging

Automatically merge models whose names contain matching patterns:

Pattern Format: Comma-separated, case-insensitive

• tree → merges all models with "tree" in name
• tree, car, building → creates 3 groups: tree models, car models, building models

Example:

• Input: big_tree.glb, small_tree.glb, red_car.glb, blue_car.glb
• Pattern: tree, car
• Output: tree.glb (merged trees), car.glb (merged cars)

Dry Run Mode

Preview extraction without creating files:

• See what files would be created
• Check merge grouping
• Verify model counts
• No files downloaded

Technical Details

Web Tool (Standalone)

• No installation required: Just open the HTML file in a browser
• No server needed: Works with file:// protocol
• CDN dependencies: Three.js loaded from jsdelivr CDN
• Internet required: Only for initial CDN loading
• Self-contained: All code in single HTML file

CLI Tool (Requires Node.js)

• Requires Node.js v14+ and npm
• Needs npm install to install Three.js locally
• Dependencies: Three.js v0.160.0

Troubleshooting

Models Not Extracting

• Check browser console for errors
• Verify GLB file is valid
• Try disabling topology cleaning

Merge Pattern Not Working

• Ensure pattern text matches model names (case-insensitive)
• Use comma to separate multiple patterns
• Check console output for merge groups

Export Fails

• Check browser console for specific errors
• Verify disk space for downloads
• Try dry run mode first

Development

File Structure

• tools/extract_glb_models.html: Standalone HTML file with embedded JavaScript
• tools/extract_glb_models.js: Node.js CLI version
• Uses ES6 modules and Three.js CDN for web version

Extending Functionality

The HTML tool is self-contained and can be modified directly:

• Add new extraction options in the UI section
• Modify extraction logic in extractIndividualModels() function
• Add new processing steps before export

License

This project uses Three.js (MIT License). See Three.js license for details.

Contributing

Feel free to submit issues or improvements. The tool is designed to be simple and extensible.