notso-glb 0.1.0__tar.gz

notso_glb-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.3
+Name: notso-glb
+Version: 0.1.0
+Summary: GLB Export Optimizer for Mascot Models
+Keywords: 3d,blender,compression,draco,glb,gltf,mascot,optimization,webgl
+Author: Kaj Kowalski
+Author-email: Kaj Kowalski <info@kajkowalski.nl>
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
+Requires-Dist: bpy>=5,<6 ; python_full_version == '3.11.*'
+Requires-Dist: rich>=14.2.0
+Requires-Dist: typer>=0.20.1
+Requires-Dist: wasmtime>=41.0.0
+Requires-Python: ~=3.11.0
+Project-URL: Homepage, https://github.com/kjanat/notso-glb
+Project-URL: Issues, https://github.com/kjanat/notso-glb/issues
+Project-URL: Repository, https://github.com/kjanat/notso-glb.git
+Description-Content-Type: text/markdown
+
+# GLB Export Optimizer for Mascot Models
+
+> Cleans up Blender files and exports optimized GLB for web delivery.
+
+```bash
+uvx notso-glb [OPTIONS] FILE
+```
+
+<p align="center">
+  <a href="https://github.com/kjanat/notso-glb/blob/master/CLI.md" target="_blank" rel="noopener" title="View CLI Options">
+    <img alt="Screenshot with cli options" width="100%" src="https://raw.githubusercontent.com/kjanat/notso-glb/refs/heads/master/screenshot.webp">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/notso-glb/"><img src="https://img.shields.io/pypi/v/notso-glb" alt="PyPI"></a>
+  <a href="https://pypi.org/project/notso-glb/"><img src="https://img.shields.io/pypi/dm/notso-glb" alt="Downloads"></a>  <!--<a href="https://github.com/kjanat/notso-glb/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/kjanat/notso-glb/ci.yml?branch=master" alt="CI"></a>-->
+  <a href="https://github.com/kjanat/notso-glb/blob/master/LICENSE"><img src="https://img.shields.io/github/license/kjanat/notso-glb" alt="License"></a>  <!--<a href="https://notso-glb.kjanat.com"><img src="https://img.shields.io/badge/docs-mkdocs-blue" alt="Docs"></a>-->
+  <img src="https://img.shields.io/badge/python-3.11-blue" alt="Python 3.11">
+</p>
+
+## Install
+
+```bash
+uv tool install notso-glb
+```
+
+```bash
+# 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
+
+```bash
+uv tool upgrade notso-glb
+```
+
+## 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)
+- Exports with Draco mesh 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:
+
+```bash
+# 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.
+
+[Khronos Resources]: https://github.khronos.org/
+[glTF 2.0 Specification]: https://www.khronos.org/gltf/#gltf-spec
+[glTF 2.0 API Reference Guide]: https://www.khronos.org/files/gltf20-reference-guide.pdf
+[Blender 5.0 Reference Manual]: https://docs.blender.org/manual/en/latest
+[Blender 5.0 glTF 2.0]: https://docs.blender.org/manual/en/5.0/addons/import_export/scene_gltf2.html
+[Blender 5.0 Python API Documentation]: https://docs.blender.org/api/current/index.html
+[Blender]: https://www.blender.org/
+[CLI.md]: https://github.com/kjanat/notso-glb/blob/master/CLI.md
+[LICENSE]: https://github.com/kjanat/notso-glb/blob/master/LICENSE
+
+<!-- markdownlint-disable-file MD033 -->

notso_glb-0.1.0/README.md

@@ -0,0 +1,124 @@
+# GLB Export Optimizer for Mascot Models
+
+> Cleans up Blender files and exports optimized GLB for web delivery.
+
+```bash
+uvx notso-glb [OPTIONS] FILE
+```
+
+<p align="center">
+  <a href="https://github.com/kjanat/notso-glb/blob/master/CLI.md" target="_blank" rel="noopener" title="View CLI Options">
+    <img alt="Screenshot with cli options" width="100%" src="https://raw.githubusercontent.com/kjanat/notso-glb/refs/heads/master/screenshot.webp">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/notso-glb/"><img src="https://img.shields.io/pypi/v/notso-glb" alt="PyPI"></a>
+  <a href="https://pypi.org/project/notso-glb/"><img src="https://img.shields.io/pypi/dm/notso-glb" alt="Downloads"></a>  <!--<a href="https://github.com/kjanat/notso-glb/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/kjanat/notso-glb/ci.yml?branch=master" alt="CI"></a>-->
+  <a href="https://github.com/kjanat/notso-glb/blob/master/LICENSE"><img src="https://img.shields.io/github/license/kjanat/notso-glb" alt="License"></a>  <!--<a href="https://notso-glb.kjanat.com"><img src="https://img.shields.io/badge/docs-mkdocs-blue" alt="Docs"></a>-->
+  <img src="https://img.shields.io/badge/python-3.11-blue" alt="Python 3.11">
+</p>
+
+## Install
+
+```bash
+uv tool install notso-glb
+```
+
+```bash
+# 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
+
+```bash
+uv tool upgrade notso-glb
+```
+
+## 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)
+- Exports with Draco mesh 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:
+
+```bash
+# 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.
+
+[Khronos Resources]: https://github.khronos.org/
+[glTF 2.0 Specification]: https://www.khronos.org/gltf/#gltf-spec
+[glTF 2.0 API Reference Guide]: https://www.khronos.org/files/gltf20-reference-guide.pdf
+[Blender 5.0 Reference Manual]: https://docs.blender.org/manual/en/latest
+[Blender 5.0 glTF 2.0]: https://docs.blender.org/manual/en/5.0/addons/import_export/scene_gltf2.html
+[Blender 5.0 Python API Documentation]: https://docs.blender.org/api/current/index.html
+[Blender]: https://www.blender.org/
+[CLI.md]: https://github.com/kjanat/notso-glb/blob/master/CLI.md
+[LICENSE]: https://github.com/kjanat/notso-glb/blob/master/LICENSE
+
+<!-- markdownlint-disable-file MD033 -->

notso_glb-0.1.0/pyproject.toml

@@ -0,0 +1,90 @@
+[project]
+name            = "notso-glb"
+version         = "0.1.0"
+description     = "GLB Export Optimizer for Mascot Models"
+readme          = "README.md"
+requires-python = "~=3.11.0"
+authors         = [{ name = "Kaj Kowalski", email = "info@kajkowalski.nl" }]
+keywords        = ["3d", "blender", "compression", "draco", "glb", "gltf", "mascot", "optimization", "webgl"]
+classifiers     = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Topic :: Multimedia :: Graphics :: 3D Modeling",
+  "Topic :: Multimedia :: Graphics :: Graphics Conversion"
+]
+dependencies    = [
+  "bpy>=5,<6; python_version ~= '3.11.0'",
+  "rich>=14.2.0",
+  "typer>=0.20.1",
+  "wasmtime>=41.0.0",
+]
+
+[project.urls]
+Homepage   = "https://github.com/kjanat/notso-glb"
+Issues     = "https://github.com/kjanat/notso-glb/issues"
+Repository = "https://github.com/kjanat/notso-glb.git"
+
+[project.scripts]
+notso-glb = "notso_glb:main"
+
+[dependency-groups]
+dev   = [
+  { include-group = "lint" },
+  { include-group = "test" },
+  { include-group = "types" },
+]
+lint  = [
+  "ruff>=0.14.10",
+  "tombi>=0.7.26",
+  "ty>=0.0.5",
+]
+test  = [
+  "pytest>=9.0.2",
+  "pytest-cov>=7.0.0",
+]
+types = [
+  "fake-bpy-module>=20251003",
+  "ty>=0.0.5",
+]
+
+[build-system]
+requires      = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.pytest]
+addopts    = ["--cov", "--import-mode=importlib", "-ra"]
+minversion = "9.0"
+strict     = true
+testpaths  = ["tests"]
+
+[tool.ruff]
+line-length    = 88
+indent-width   = 4
+target-version = "py311"
+
+[tool.ruff.lint]
+preview   = true
+select    = ["E4", "E7", "E9", "F", "F", "B", "UP"]
+ignore    = []
+fixable   = ["ALL"]
+unfixable = []
+
+[tool.ruff.format]
+preview                    = true
+quote-style                = "double"
+indent-style               = "space"
+skip-magic-trailing-comma  = false
+line-ending                = "lf"
+docstring-code-format      = true
+docstring-code-line-length = "dynamic"
+
+[tool.uv]
+default-groups = "all"
+
+[tool.uv.build-backend]
+source-include = ["src/notso_glb/wasm/**"]

notso_glb-0.1.0/src/notso_glb/__init__.py

@@ -0,0 +1,38 @@
+"""
+GLB Export Optimizer for Mascot Models
+======================================
+Cleans up Blender files and exports optimized GLB for web delivery.
+
+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)
+- Exports with Draco mesh compression
+- Exports with WebP textures
+
+Usage:
+    CLI:
+        notso-glb model.glb -o output.glb
+        notso-glb model.blend --format gltf-embedded
+        notso-glb model.gltf --no-draco --max-texture 2048
+
+    Python:
+        from notso_glb import main
+        main()
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from notso_glb.cli import main
+
+try:
+    __version__ = version("notso-glb")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+__all__ = ["main"]

notso_glb-0.1.0/src/notso_glb/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as python -m notso_glb."""
+
+from notso_glb.cli import main
+
+if __name__ == "__main__":
+    main()

notso_glb-0.1.0/src/notso_glb/analyzers/__init__.py

@@ -0,0 +1,20 @@
+"""Analyzers for mesh bloat, bones, duplicates, and UV maps."""
+
+from notso_glb.analyzers.bloat import analyze_mesh_bloat, count_mesh_islands
+from notso_glb.analyzers.bones import (
+    analyze_bone_animation,
+    get_bones_used_for_skinning,
+)
+from notso_glb.analyzers.duplicates import analyze_duplicate_names
+from notso_glb.analyzers.skinned_mesh import analyze_skinned_mesh_parents
+from notso_glb.analyzers.uv_maps import analyze_unused_uv_maps
+
+__all__ = [
+    "analyze_bone_animation",
+    "analyze_duplicate_names",
+    "analyze_mesh_bloat",
+    "analyze_skinned_mesh_parents",
+    "analyze_unused_uv_maps",
+    "count_mesh_islands",
+    "get_bones_used_for_skinning",
+]

notso_glb-0.1.0/src/notso_glb/analyzers/bloat.py

@@ -0,0 +1,117 @@
+"""Mesh bloat analysis for detecting overly complex geometry."""
+
+import bpy
+
+from notso_glb.utils import get_mesh_data
+from notso_glb.utils.constants import BLOAT_THRESHOLDS
+
+
+def count_mesh_islands(obj) -> int:
+    """Count disconnected mesh parts (islands) using BFS."""
+    import bmesh
+
+    bm = bmesh.new()
+    bm.from_mesh(obj.data)
+    bm.verts.ensure_lookup_table()
+
+    visited: set[int] = set()
+    islands = 0
+
+    for v in bm.verts:
+        if v.index in visited:
+            continue
+        islands += 1
+        stack = [v]
+        while stack:
+            current = stack.pop()
+            if current.index in visited:
+                continue
+            visited.add(current.index)
+            for edge in current.link_edges:
+                other = edge.other_vert(current)
+                if other.index not in visited:
+                    stack.append(other)
+
+    bm.free()
+    return islands
+
+
+def analyze_mesh_bloat() -> list[dict[str, object]]:
+    """
+    Detect unreasonably complex meshes for web delivery.
+
+    Returns list of warnings with severity levels:
+    - CRITICAL: Must fix before web deployment
+    - WARNING: Should review, likely bloated
+    - INFO: Notable but may be intentional
+    """
+    warnings: list[dict[str, object]] = []
+
+    total_verts = 0
+    for obj in bpy.data.objects:
+        if obj.type != "MESH":
+            continue
+
+        mesh = get_mesh_data(obj)
+        verts = len(mesh.vertices)
+        total_verts += verts
+
+        if verts < 100:
+            continue
+
+        # Check if skinned (character mesh vs prop)
+        is_skinned = any(mod.type == "ARMATURE" for mod in obj.modifiers)
+
+        # Count islands for non-skinned meshes (expensive operation)
+        islands = 1
+        if not is_skinned and verts < 20000:
+            islands = count_mesh_islands(obj)
+
+        verts_per_island = verts / max(islands, 1)
+
+        # Bloat detection rules
+        if not is_skinned:
+            if verts > BLOAT_THRESHOLDS["prop_critical"]:
+                warnings.append({
+                    "severity": "CRITICAL",
+                    "object": obj.name,
+                    "issue": "BLOATED_PROP",
+                    "detail": f"{verts:,} verts (limit: {BLOAT_THRESHOLDS['prop_critical']:,})",
+                    "suggestion": "Decimate or replace with baked texture",
+                })
+            elif verts > BLOAT_THRESHOLDS["prop_warning"]:
+                warnings.append({
+                    "severity": "WARNING",
+                    "object": obj.name,
+                    "issue": "HIGH_VERT_PROP",
+                    "detail": f"{verts:,} verts",
+                    "suggestion": "Consider simplifying",
+                })
+
+            if (
+                islands > BLOAT_THRESHOLDS["repetitive_islands"]
+                and verts_per_island > BLOAT_THRESHOLDS["repetitive_verts"]
+            ):
+                warnings.append({
+                    "severity": "CRITICAL",
+                    "object": obj.name,
+                    "issue": "REPETITIVE_DETAIL",
+                    "detail": f"{islands} islands x {verts_per_island:.0f} verts each",
+                    "suggestion": "Merge islands or use instancing/texture",
+                })
+
+    # Scene-level check
+    if total_verts > BLOAT_THRESHOLDS["scene_total"]:
+        warnings.append({
+            "severity": "WARNING",
+            "object": "SCENE",
+            "issue": "HIGH_TOTAL_VERTS",
+            "detail": f"{total_verts:,} verts (target: <{BLOAT_THRESHOLDS['scene_total']:,})",
+            "suggestion": "Review all meshes for optimization opportunities",
+        })
+
+    # Sort by severity
+    severity_order = {"CRITICAL": 0, "WARNING": 1, "INFO": 2}
+    warnings.sort(key=lambda w: severity_order.get(str(w["severity"]), 99))
+
+    return warnings

notso_glb-0.1.0/src/notso_glb/analyzers/bones.py

@@ -0,0 +1,100 @@
+"""Bone animation analysis for detecting static bones."""
+
+import bpy
+from bpy.types import Object
+
+from notso_glb.utils import get_scene, get_view_layer
+from notso_glb.utils.logging import log_debug
+
+
+def get_bones_used_for_skinning() -> set[str]:
+    """Find all bones that have vertex weights on skinned meshes."""
+    used_bones: set[str] = set()
+
+    for obj in bpy.data.objects:
+        if obj.type != "MESH":
+            continue
+
+        # Check if mesh is skinned (has armature modifier)
+        has_armature = any(mod.type == "ARMATURE" for mod in obj.modifiers)
+        if not has_armature:
+            continue
+
+        # All vertex groups on skinned meshes are bone references
+        for vg in obj.vertex_groups:
+            used_bones.add(vg.name)
+
+    return used_bones
+
+
+def analyze_bone_animation() -> set[str]:
+    """Find bones that never animate across all actions.
+
+    Optimized to batch frame evaluations - evaluates all bones at once per frame
+    instead of switching frames per-bone, reducing scene updates from O(bones*actions)
+    to O(actions).
+    """
+    armature: Object | None = None
+    for obj in bpy.data.objects:
+        if obj.type == "ARMATURE":
+            armature = obj
+            break
+
+    if not armature or not armature.animation_data or not armature.pose:
+        log_debug("No armature with animation data found")
+        return set()
+
+    scene = get_scene()
+    view_layer = get_view_layer()
+    bone_movement: dict[str, float] = {b.name: 0.0 for b in armature.pose.bones}
+    num_bones = len(armature.pose.bones)
+    num_actions = len(bpy.data.actions)
+
+    log_debug(f"Analyzing {num_bones} bones across {num_actions} actions")
+
+    orig_action = armature.animation_data.action
+    orig_frame = scene.frame_current
+
+    for action in bpy.data.actions:
+        armature.animation_data.action = action
+        frame_start = int(action.frame_range[0])
+        frame_end = int(action.frame_range[1])
+
+        # Evaluate start frame ONCE for all bones
+        scene.frame_set(frame_start)
+        view_layer.update()
+        start_poses: dict[str, tuple] = {}
+        for bone in armature.pose.bones:
+            start_poses[bone.name] = (
+                bone.location.copy(),
+                bone.rotation_quaternion.copy(),
+                bone.rotation_euler.copy(),
+                bone.rotation_mode,
+            )
+
+        # Evaluate end frame ONCE for all bones
+        scene.frame_set(frame_end)
+        view_layer.update()
+
+        # Now calculate diffs without any frame switching
+        for bone in armature.pose.bones:
+            start_loc, start_rot_q, start_rot_e, rot_mode = start_poses[bone.name]
+            end_loc = bone.location.copy()
+            end_rot_q = bone.rotation_quaternion.copy()
+            end_rot_e = bone.rotation_euler.copy()
+
+            loc_diff = (end_loc - start_loc).length
+            if rot_mode == "QUATERNION":
+                rot_diff = (end_rot_q - start_rot_q).magnitude
+            else:
+                rot_diff = (
+                    end_rot_e.to_quaternion() - start_rot_e.to_quaternion()
+                ).magnitude
+
+            bone_movement[bone.name] += loc_diff + rot_diff
+
+    if orig_action:
+        armature.animation_data.action = orig_action
+    scene.frame_set(orig_frame)
+
+    return {name for name, movement in bone_movement.items() if movement < 0.01}