notso-glb 0.1.0__py3-none-any.whl

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/__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/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/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/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}

notso_glb/analyzers/duplicates.py

@@ -0,0 +1,71 @@
+"""Duplicate name detection for glTF export issues."""
+
+from collections import Counter, defaultdict
+
+import bpy
+
+from notso_glb.utils import sanitize_gltf_name
+
+
+def analyze_duplicate_names() -> list[dict[str, object]]:
+    """
+    Detect duplicate names that will cause glTF export issues.
+
+    Checks both:
+    1. Exact duplicates in Blender
+    2. Names that collide after glTF sanitization (e.g., 'Cube.155' and 'Cube_155')
+
+    Returns list of duplicates grouped by type.
+    """
+    duplicates: list[dict[str, object]] = []
+
+    def check_collection(items, type_name: str) -> None:
+        """Check a collection for exact and sanitized duplicates."""
+        names = [item.name for item in items]
+
+        # 1. Exact duplicates
+        for name, count in Counter(names).items():
+            if count > 1:
+                duplicates.append({
+                    "type": type_name,
+                    "name": name,
+                    "count": count,
+                    "issue": "EXACT_DUPLICATE",
+                })
+
+        # 2. Sanitization collisions
+        sanitized_map: dict[str, list[str]] = defaultdict(list)
+        for name in names:
+            sanitized = sanitize_gltf_name(name)
+            sanitized_map[sanitized].append(name)
+
+        for sanitized, originals in sanitized_map.items():
+            if len(originals) > 1:
+                unique_originals = set(originals)
+                if len(unique_originals) > 1:
+                    duplicates.append({
+                        "type": type_name,
+                        "name": f"{sanitized} <- {list(unique_originals)}",
+                        "count": len(originals),
+                        "issue": "SANITIZATION_COLLISION",
+                    })
+
+    # Check all relevant collections
+    check_collection(bpy.data.objects, "OBJECT")
+    check_collection(bpy.data.meshes, "MESH")
+    check_collection(bpy.data.materials, "MATERIAL")
+    check_collection(bpy.data.actions, "ACTION")
+
+    # Special handling for bones (per armature)
+    for arm in bpy.data.armatures:
+        bone_names = [bone.name for bone in arm.bones]
+        for name, count in Counter(bone_names).items():
+            if count > 1:
+                duplicates.append({
+                    "type": "BONE",
+                    "name": f"{arm.name}/{name}",
+                    "count": count,
+                    "issue": "EXACT_DUPLICATE",
+                })
+
+    return duplicates

notso_glb/analyzers/skinned_mesh.py

@@ -0,0 +1,47 @@
+"""Skinned mesh parent hierarchy analysis."""
+
+import bpy
+
+
+def analyze_skinned_mesh_parents() -> list[dict[str, object]]:
+    """
+    Detect skinned meshes that are not at scene root.
+
+    glTF spec: parent transforms don't affect skinned meshes, so non-root
+    skinned meshes can have unexpected positioning.
+
+    Returns list of warnings for each non-root skinned mesh.
+    """
+    warnings: list[dict[str, object]] = []
+
+    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
+
+        # Check if it has a parent (not at root)
+        parent = obj.parent
+        if parent is not None:
+            # Check if parent has non-identity transform
+            has_transform = (
+                parent.location.length > 0.0001
+                or parent.rotation_euler.x != 0
+                or parent.rotation_euler.y != 0
+                or parent.rotation_euler.z != 0
+                or abs(parent.scale.x - 1) > 0.0001
+                or abs(parent.scale.y - 1) > 0.0001
+                or abs(parent.scale.z - 1) > 0.0001
+            )
+
+            warnings.append({
+                "mesh": obj.name,
+                "parent": parent.name,
+                "has_transform": has_transform,
+                "severity": "CRITICAL" if has_transform else "WARNING",
+            })
+
+    return warnings

notso_glb/analyzers/uv_maps.py

@@ -0,0 +1,59 @@
+"""Unused UV map detection."""
+
+from typing import cast
+
+import bpy
+from bpy.types import ShaderNodeUVMap
+
+from notso_glb.utils import get_mesh_data
+
+
+def analyze_unused_uv_maps() -> list[dict[str, object]]:
+    """
+    Detect UV maps that aren't used by any material.
+
+    Unused TEXCOORD attributes bloat the glTF file.
+    Returns list of meshes with unused UV maps.
+    """
+    warnings: list[dict[str, object]] = []
+
+    for obj in bpy.data.objects:
+        if obj.type != "MESH":
+            continue
+
+        mesh = get_mesh_data(obj)
+        if not mesh.uv_layers:
+            continue
+
+        # Get UV maps used by materials
+        used_uvs: set[str] = set()
+        for mat_slot in obj.material_slots:
+            if not mat_slot.material or not mat_slot.material.use_nodes:
+                continue
+            node_tree = mat_slot.material.node_tree
+            if node_tree is None:
+                continue
+            for node in node_tree.nodes:
+                if node.type == "UVMAP":
+                    uv_node = cast(ShaderNodeUVMap, node)
+                    if uv_node.uv_map:
+                        used_uvs.add(uv_node.uv_map)
+                # Image textures default to first UV if no explicit UV node
+                if node.type == "TEX_IMAGE":
+                    if not used_uvs and mesh.uv_layers:
+                        used_uvs.add(mesh.uv_layers[0].name)
+
+        # If no explicit UV usage found, assume first UV is used
+        if not used_uvs and mesh.uv_layers:
+            used_uvs.add(mesh.uv_layers[0].name)
+
+        # Find unused UV maps
+        unused = [uv.name for uv in mesh.uv_layers if uv.name not in used_uvs]
+        if unused:
+            warnings.append({
+                "mesh": obj.name,
+                "unused_uvs": unused,
+                "total_uvs": len(mesh.uv_layers),
+            })
+
+    return warnings

notso_glb/cleaners/__init__.py

@@ -0,0 +1,23 @@
+"""Cleaners for mesh, bones, textures, and vertex groups."""
+
+from notso_glb.cleaners.bones import (
+    delete_bone_shape_objects,
+    mark_static_bones_non_deform,
+)
+from notso_glb.cleaners.duplicates import auto_fix_duplicate_names
+from notso_glb.cleaners.mesh import auto_fix_bloat, cleanup_mesh_bmesh, decimate_mesh
+from notso_glb.cleaners.textures import resize_textures
+from notso_glb.cleaners.uv_maps import remove_unused_uv_maps
+from notso_glb.cleaners.vertex_groups import clean_vertex_groups
+
+__all__ = [
+    "auto_fix_bloat",
+    "auto_fix_duplicate_names",
+    "clean_vertex_groups",
+    "cleanup_mesh_bmesh",
+    "decimate_mesh",
+    "delete_bone_shape_objects",
+    "mark_static_bones_non_deform",
+    "remove_unused_uv_maps",
+    "resize_textures",
+]

notso_glb/cleaners/bones.py

@@ -0,0 +1,49 @@
+"""Bone cleanup functions."""
+
+import bpy
+from bpy.types import Object
+
+from notso_glb.analyzers.bones import get_bones_used_for_skinning
+from notso_glb.utils import get_armature_data
+
+
+def mark_static_bones_non_deform(static_bones: set[str]) -> tuple[int, int]:
+    """Mark static bones as non-deform, but KEEP bones used for skinning."""
+    armature: Object | None = None
+    for obj in bpy.data.objects:
+        if obj.type == "ARMATURE":
+            armature = obj
+            break
+
+    if not armature:
+        return 0, 0
+
+    # CRITICAL: Don't mark bones as non-deform if they're weighted to meshes
+    skinning_bones = get_bones_used_for_skinning()
+    safe_to_mark = static_bones - skinning_bones
+    skipped = len(static_bones & skinning_bones)
+
+    arm_data = get_armature_data(armature)
+    marked = 0
+    for bone_name in safe_to_mark:
+        bone = arm_data.bones.get(bone_name)
+        if not bone or not bone.use_deform:
+            continue
+        bone.use_deform = False
+        marked += 1
+
+    return marked, skipped
+
+
+def delete_bone_shape_objects() -> int:
+    """Remove objects used as bone custom shapes (Icosphere, etc.)."""
+    deleted = 0
+    shape_names = ["icosphere", "bone_shape", "widget", "wgt_"]
+
+    for obj in list(bpy.data.objects):
+        name_lower = obj.name.lower()
+        if any(s in name_lower for s in shape_names):
+            bpy.data.objects.remove(obj, do_unlink=True)
+            deleted += 1
+
+    return deleted

notso_glb/cleaners/duplicates.py

@@ -0,0 +1,110 @@
+"""Duplicate name auto-fix functions."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import bpy
+
+# Type alias for rename result
+RenameRecord = dict[str, str]
+
+
+def _get_collection(dtype: str) -> Any | None:
+    """Get the appropriate bpy.data collection for a data type."""
+    collections = {
+        "OBJECT": bpy.data.objects,
+        "MESH": bpy.data.meshes,
+        "MATERIAL": bpy.data.materials,
+        "ACTION": bpy.data.actions,
+    }
+    return collections.get(dtype)
+
+
+def _get_ptr_suffix(item: Any) -> str:
+    """Get short unique suffix from memory pointer (last 4 hex digits)."""
+    return format(item.as_pointer() & 0xFFFF, "04x")
+
+
+def _parse_colliding_names(name_field: str) -> list[str]:
+    """Parse collision info string to extract list of colliding names."""
+    match = re.search(r"\[([^\]]+)\]", name_field)
+    if not match:
+        return []
+    names_str = match.group(1)
+    return [n.strip().strip("'\"") for n in names_str.split(",")]
+
+
+def _fix_exact_duplicates(
+    collection: Any,
+    name: str,
+    dtype: str,
+    processed_ids: set[int],
+    renames: list[RenameRecord],
+) -> None:
+    """Rename exact duplicates by appending pointer suffix."""
+    matching = [item for item in collection if item.name == name]
+    for item in matching[1:]:
+        if id(item) in processed_ids:
+            continue
+        old_name = item.name
+        new_name = f"{name}_{_get_ptr_suffix(item)}"
+        item.name = new_name
+        processed_ids.add(id(item))
+        renames.append({"type": dtype, "old": old_name, "new": new_name})
+
+
+def _fix_sanitization_collision(
+    collection: Any,
+    name_field: str,
+    dtype: str,
+    processed_ids: set[int],
+    renames: list[RenameRecord],
+) -> None:
+    """Rename colliding names from sanitization by appending pointer suffix."""
+    colliding_names = _parse_colliding_names(name_field)
+    for name in colliding_names[1:]:
+        item = collection.get(name)
+        if not item or id(item) in processed_ids:
+            continue
+        base = re.sub(r"\.", "_", name)
+        new_name = f"{base}_{_get_ptr_suffix(item)}"
+        item.name = new_name
+        processed_ids.add(id(item))
+        renames.append({"type": dtype, "old": name, "new": new_name})
+
+
+def auto_fix_duplicate_names(
+    duplicates: list[dict[str, object]],
+) -> list[RenameRecord]:
+    """
+    Automatically rename duplicates by appending memory pointer suffix.
+
+    Uses as_pointer() for deterministic, session-stable unique IDs.
+    Handles both exact duplicates and sanitization collisions.
+    Returns list of renames performed.
+    """
+    renames: list[RenameRecord] = []
+    processed_ids: set[int] = set()
+
+    for dup in duplicates:
+        dtype = str(dup["type"])
+        if dtype == "BONE":
+            continue
+
+        collection = _get_collection(dtype)
+        if not collection:
+            continue
+
+        issue = dup.get("issue", "EXACT_DUPLICATE")
+        name_field = str(dup["name"])
+
+        if issue == "EXACT_DUPLICATE":
+            _fix_exact_duplicates(collection, name_field, dtype, processed_ids, renames)
+        elif issue == "SANITIZATION_COLLISION":
+            _fix_sanitization_collision(
+                collection, name_field, dtype, processed_ids, renames
+            )
+
+    return renames