# glb-extractor

**Repository Path**: SimZHM/glb-extractor

## Basic Information

- **Project Name**: glb-extractor
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-07
- **Last Updated**: 2026-04-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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:

```bash
# 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:
```bash
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.