kjanat/notso-glb repository overview

⁠GLB Export Optimizer for Mascot Models

uvx notso-glb [OPTIONS] FILE

⁠

⁠Install

uv tool install notso-glb

# Or install directly from GitHub:
uv tool install -p3.11 git+https://github.com/kjanat/notso-glb

then just run notso-glb from the command line.

⁠Upgrade

uv tool upgrade notso-glb

⁠Docker

Available from Docker Hub⁠ and GitHub Container Registry⁠:

# Docker Hub
docker pull kjanat/notso-glb

# GitHub Container Registry
docker pull ghcr.io/kjanat/notso-glb

⁠Usage (docker)

Mount your files directory to /data:

# Process a file (output to input_optimized.glb by default)
docker run --rm -v "$(pwd)":/data kjanat/notso-glb model.blend

# Specify output file
docker run --rm -v "$(pwd)":/data kjanat/notso-glb input.glb -o output.glb

# With options
docker run --rm -v "$(pwd)":/data kjanat/notso-glb model.blend --no-draco --no-webp

# Show help
docker run --rm kjanat/notso-glb --help

⁠Features

Optimizations:

• Detects bloated props (high-vert non-skinned meshes, repetitive geometry)
• Detects skinned meshes with non-root parents (glTF spec issue)
• Detects unused UV maps (TEXCOORD bloat)
• Detects duplicate names and sanitization collisions
• Removes unused vertex groups (bone weight bloat)
• Marks static bones as non-deform (animation bloat)
• Removes bone shape objects (Icosphere artifacts)
• Resizes textures to max 1024px (optional POT enforcement)
• Compresses meshes with gltfpack by default (bundled WASM fallback); falls back to Draco when gltfpack is unavailable, and auto-detects existing Draco to avoid double compression
• Exports with WebP textures

Bloat Detection:

• CRITICAL: Props >2000 verts, repetitive detail (many islands with high verts)
• WARNING: Props >1000 verts, scene total >15000 verts, non-root skinned meshes

Experimental Auto-fix (--autofix):

• BMesh cleanup (remove doubles, degenerate geometry, loose verts)
• Decimate bloated props to ~1600 verts
• Auto-rename duplicate objects/meshes/materials/actions (using pointer ID)
• Remove unused UV maps

⁠Usage

See CLI.md⁠

⁠Requirements

• Blender 5.0+
• Python 3.11 (same as bundled with Blender)
• uv (optional, for easy install/upgrade)
• gltfpack (optional, for extra compression - WASM fallback included)

⁠Development Setup

For local development, download the gltfpack WASM binary:

# Download latest WASM from npm
uv run scripts/update_wasm.py

# Or check current version
uv run scripts/update_wasm.py --show-version

# Download specific version
uv run scripts/update_wasm.py --version 1.0.0

The WASM binary (src/notso_glb/wasm/gltfpack.wasm) is not committed to git and must be downloaded locally. CI/CD pipelines handle this automatically.

⁠Useful Links

• glTF 2.0 Specification⁠
• glTF 2.0 API Reference Guide⁠
• Khronos Resources⁠
• Blender 5.0 glTF 2.0⁠
• Blender 5.0 Python API Documentation⁠
• Blender 5.0 Reference Manual⁠

⁠License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE⁠ file for details.

This project uses Blender⁠ as a Python module (bpy), which is also GPL-3.0 licensed.