Duplicate-Resilient Mesh Cleanup

Create a module that loads STL meshes, filters out zero-area triangles, and handles duplicate polygons according to a caller-selected policy. The module should summarize how many triangles were kept or discarded and persist the cleaned mesh alongside a short report.

Capabilities

Respect duplicate policy

• Given an STL containing two identical triangles at vertices (0,0,0)-(1,0,0)-(0,1,0) plus a collinear zero-area triangle (0,0,0)-(1,0,0)-(2,0,0), calling the loader with duplicate_policy="keep" and remove_degenerate=True keeps both identical triangles, removes the zero-area triangle, and reports removed_duplicates=0, removed_degenerate=1, kept=2. @test

Collapse duplicates once

• With the same input file, calling the loader with duplicate_policy="keep-one" collapses the identical triangles into a single face while still removing the zero-area triangle, reporting removed_duplicates=1, removed_degenerate=1, kept=1. @test

Drop all duplicates

• For an STL containing three triangles where two are identical at (0,0,0)-(1,0,0)-(0,1,0) and the third is distinct at (0,0,1)-(1,0,1)-(0,1,1), calling the loader with duplicate_policy="drop-all" removes both duplicates entirely, retains the distinct triangle, and reports removed_duplicates=2, removed_degenerate=0, kept=1. @test

Optional degenerate retention

• When remove_degenerate=False on a file containing the degenerate triangle (0,0,0)-(1,0,0)-(2,0,0) and one valid triangle, the loader retains both triangles and reports removed_degenerate=0, kept=2. @test

Implementation

@generates

API

from dataclasses import dataclass
from enum import Enum

class DuplicatePolicy(str, Enum):
    KEEP = "keep"
    KEEP_ONE = "keep-one"
    DROP_ALL = "drop-all"

@dataclass
class MeshSummary:
    total: int
    kept: int
    removed_duplicates: int
    removed_degenerate: int

def load_and_clean(
    path: str,
    duplicate_policy: DuplicatePolicy = DuplicatePolicy.KEEP_ONE,
    remove_degenerate: bool = True,
) -> MeshSummary:
    """
    Load an STL file from `path`, apply duplicate handling and degenerate triangle filtering,
    and return a summary of the cleaned mesh. Triangles are duplicates when they share the same
    vertex coordinates regardless of ordering. When remove_degenerate is True, zero-area triangles
    are excluded. Save the cleaned mesh to disk with the suffix `.cleaned.stl` and write a
    text report (same stem, `.txt`) that lists totals and removal counts.
    """

Dependencies { .dependencies }

numpy-stl { .dependency }

Provides STL mesh loading, duplicate control policies, and filtering helpers.