thinskin 0.1.0__tar.gz

thinskin-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+wheels/
+.venv/
+venv/
+env/
+
+# Packaging / tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# Generated analysis outputs
+*_narrow.stl
+*_narrow_coloured.obj
+*_annotated_views.png

thinskin-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SemiQuant (Jason Limberis)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

thinskin-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: thinskin
+Version: 0.1.0
+Summary: Identify and annotate thin (narrow) regions in STL meshes.
+Project-URL: Homepage, https://github.com/SemiQuant/ThinSkin
+Project-URL: Repository, https://github.com/SemiQuant/ThinSkin
+Project-URL: Issues, https://github.com/SemiQuant/ThinSkin/issues
+Author-email: SemiQuant <JasonLimberis@ucsf.edu>
+License: MIT
+License-File: LICENSE
+Keywords: 3d-printing,cad,mesh,stl,thickness,trimesh
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Manufacturing
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: numpy>=1.21
+Requires-Dist: rtree>=1.0
+Requires-Dist: scipy>=1.7
+Requires-Dist: trimesh>=3.20
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ThinSkin
+
+[![PyPI version](https://img.shields.io/pypi/v/thinskin.svg)](https://pypi.org/project/thinskin/)
+[![Python versions](https://img.shields.io/pypi/pyversions/thinskin.svg)](https://pypi.org/project/thinskin/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**ThinSkin** analyses an STL mesh and identifies regions where the local
+geometry is **thinner than a specified diameter threshold** — handy for
+checking 3D-print wall thickness, minimum feature sizes, and structurally
+fragile areas before manufacturing.
+
+## How it works
+
+For every vertex in the mesh, ThinSkin estimates the local *inscribed
+diameter* using two complementary approaches and takes the **minimum** of the
+two as the effective local diameter:
+
+1. **Ray-cast thickness** — casts a ray inward along the inverted vertex
+   normal and measures the distance to the nearest opposing surface.
+2. **Local curvature radius** — derived from the mean curvature at each vertex
+   via the cotangent-weighted Laplacian.
+
+Vertices whose effective diameter falls below the threshold are flagged as
+*narrow*.
+
+## Installation
+
+```bash
+pip install thinskin
+```
+
+ThinSkin uses [`trimesh`](https://trimesh.org/) for ray casting, which relies
+on [`rtree`](https://pypi.org/project/Rtree/) (bundled `libspatialindex`). If
+you hit native-library issues, install via conda/mamba:
+
+```bash
+micromamba install -c conda-forge rtree
+pip install thinskin
+```
+
+### From source
+
+```bash
+git clone https://github.com/SemiQuant/ThinSkin.git
+cd ThinSkin
+pip install -e ".[dev]"
+```
+
+## Usage
+
+### Command line
+
+```bash
+thinskin model.stl --diameter 2.0
+```
+
+Options:
+
+| Option | Alias | Default | Description |
+| --- | --- | --- | --- |
+| `--diameter` | `-d` | `2.0` | Minimum diameter threshold (mm). |
+| `--output` | `-o` | `<input>_narrow.stl` | Output STL path. |
+| `--version` | `-V` | | Print version and exit. |
+| `--help` | `-h` | | Show help and exit. |
+
+You can also run it as a module:
+
+```bash
+python -m thinskin model.stl -d 1.5
+```
+
+### Outputs
+
+For an input `model.stl`, ThinSkin writes (when narrow regions are found):
+
+| File | Description |
+| --- | --- |
+| `model_narrow.stl` | Mesh containing only the flagged (narrow) faces — overlay in MeshLab. |
+| `model_narrow_coloured.obj` | Full mesh with per-vertex colours (red = narrow, green = OK). |
+| `model_narrow_annotated_views.png` | CAD-style 2×2 multi-view annotated report. |
+
+The console also prints mesh stats, a results summary, and a diameter
+distribution histogram as tables.
+
+### Python API
+
+```python
+import thinskin
+
+mesh = thinskin.load_mesh("model.stl")
+eff_diam, thickness, curv_radius = thinskin.compute_effective_diameter(mesh)
+
+threshold = 2.0
+narrow = eff_diam < threshold
+print(f"{int(narrow.sum())} narrow vertices below {threshold} mm")
+
+# Render the annotated report
+thinskin.generate_annotated_report(mesh, eff_diam, threshold, "model_narrow.stl")
+```
+
+## Requirements
+
+- Python ≥ 3.9
+- `click`, `numpy`, `scipy`, `trimesh`, `rtree`, `matplotlib`
+
+## License
+
+[MIT](LICENSE) © SemiQuant (Jason Limberis)

thinskin-0.1.0/README.md

@@ -0,0 +1,108 @@
+# ThinSkin
+
+[![PyPI version](https://img.shields.io/pypi/v/thinskin.svg)](https://pypi.org/project/thinskin/)
+[![Python versions](https://img.shields.io/pypi/pyversions/thinskin.svg)](https://pypi.org/project/thinskin/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**ThinSkin** analyses an STL mesh and identifies regions where the local
+geometry is **thinner than a specified diameter threshold** — handy for
+checking 3D-print wall thickness, minimum feature sizes, and structurally
+fragile areas before manufacturing.
+
+## How it works
+
+For every vertex in the mesh, ThinSkin estimates the local *inscribed
+diameter* using two complementary approaches and takes the **minimum** of the
+two as the effective local diameter:
+
+1. **Ray-cast thickness** — casts a ray inward along the inverted vertex
+   normal and measures the distance to the nearest opposing surface.
+2. **Local curvature radius** — derived from the mean curvature at each vertex
+   via the cotangent-weighted Laplacian.
+
+Vertices whose effective diameter falls below the threshold are flagged as
+*narrow*.
+
+## Installation
+
+```bash
+pip install thinskin
+```
+
+ThinSkin uses [`trimesh`](https://trimesh.org/) for ray casting, which relies
+on [`rtree`](https://pypi.org/project/Rtree/) (bundled `libspatialindex`). If
+you hit native-library issues, install via conda/mamba:
+
+```bash
+micromamba install -c conda-forge rtree
+pip install thinskin
+```
+
+### From source
+
+```bash
+git clone https://github.com/SemiQuant/ThinSkin.git
+cd ThinSkin
+pip install -e ".[dev]"
+```
+
+## Usage
+
+### Command line
+
+```bash
+thinskin model.stl --diameter 2.0
+```
+
+Options:
+
+| Option | Alias | Default | Description |
+| --- | --- | --- | --- |
+| `--diameter` | `-d` | `2.0` | Minimum diameter threshold (mm). |
+| `--output` | `-o` | `<input>_narrow.stl` | Output STL path. |
+| `--version` | `-V` | | Print version and exit. |
+| `--help` | `-h` | | Show help and exit. |
+
+You can also run it as a module:
+
+```bash
+python -m thinskin model.stl -d 1.5
+```
+
+### Outputs
+
+For an input `model.stl`, ThinSkin writes (when narrow regions are found):
+
+| File | Description |
+| --- | --- |
+| `model_narrow.stl` | Mesh containing only the flagged (narrow) faces — overlay in MeshLab. |
+| `model_narrow_coloured.obj` | Full mesh with per-vertex colours (red = narrow, green = OK). |
+| `model_narrow_annotated_views.png` | CAD-style 2×2 multi-view annotated report. |
+
+The console also prints mesh stats, a results summary, and a diameter
+distribution histogram as tables.
+
+### Python API
+
+```python
+import thinskin
+
+mesh = thinskin.load_mesh("model.stl")
+eff_diam, thickness, curv_radius = thinskin.compute_effective_diameter(mesh)
+
+threshold = 2.0
+narrow = eff_diam < threshold
+print(f"{int(narrow.sum())} narrow vertices below {threshold} mm")
+
+# Render the annotated report
+thinskin.generate_annotated_report(mesh, eff_diam, threshold, "model_narrow.stl")
+```
+
+## Requirements
+
+- Python ≥ 3.9
+- `click`, `numpy`, `scipy`, `trimesh`, `rtree`, `matplotlib`
+
+## License
+
+[MIT](LICENSE) © SemiQuant (Jason Limberis)

thinskin-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "thinskin"
+version = "0.1.0"
+description = "Identify and annotate thin (narrow) regions in STL meshes."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "SemiQuant", email = "JasonLimberis@ucsf.edu" },
+]
+keywords = ["stl", "mesh", "3d-printing", "thickness", "cad", "trimesh"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Manufacturing",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Visualization",
+    "Topic :: Multimedia :: Graphics :: 3D Modeling",
+]
+dependencies = [
+    "click>=8.0",
+    "numpy>=1.21",
+    "scipy>=1.7",
+    "trimesh>=3.20",
+    "rtree>=1.0",
+    "matplotlib>=3.5",
+]
+
+[project.optional-dependencies]
+dev = [
+    "build",
+    "twine",
+    "pytest",
+]
+
+[project.urls]
+Homepage = "https://github.com/SemiQuant/ThinSkin"
+Repository = "https://github.com/SemiQuant/ThinSkin"
+Issues = "https://github.com/SemiQuant/ThinSkin/issues"
+
+[project.scripts]
+thinskin = "thinskin.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/thinskin"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/thinskin",
+    "README.md",
+    "LICENSE",
+]

thinskin-0.1.0/src/thinskin/__init__.py

@@ -0,0 +1,28 @@
+"""ThinSkin - identify thin (narrow) regions in STL meshes."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .core import (
+    AnalysisResult,
+    compute_effective_diameter,
+    diameter_breakdown,
+    estimate_curvature_radius,
+    estimate_thickness_raycasting,
+    export_coloured_obj,
+    load_mesh,
+)
+from .report import generate_annotated_report
+
+__all__ = [
+    "__version__",
+    "AnalysisResult",
+    "compute_effective_diameter",
+    "diameter_breakdown",
+    "estimate_curvature_radius",
+    "estimate_thickness_raycasting",
+    "export_coloured_obj",
+    "load_mesh",
+    "generate_annotated_report",
+]

thinskin-0.1.0/src/thinskin/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m thinskin`` to invoke the CLI."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

thinskin-0.1.0/src/thinskin/cli.py

@@ -0,0 +1,204 @@
+"""Command-line interface for ThinSkin (built on click)."""
+
+from __future__ import annotations
+
+import os
+
+import click
+import numpy as np
+
+from . import __version__
+from .core import (
+    AnalysisResult,
+    compute_effective_diameter,
+    diameter_breakdown,
+    export_coloured_obj,
+    load_mesh,
+)
+from .report import generate_annotated_report
+
+
+# -- small table helper --------------------------------------------------------
+
+def _render_table(rows, headers=None, aligns=None):
+    """Render a simple, dependency-free aligned text table as a string."""
+    cols = list(zip(*([headers] + rows))) if headers else list(zip(*rows))
+    widths = [max(len(str(c)) for c in col) for col in cols]
+    aligns = aligns or [">"] * len(widths)
+
+    def fmt_row(cells):
+        return "  ".join(
+            f"{str(c):{a}{w}}" for c, w, a in zip(cells, widths, aligns)
+        )
+
+    lines = []
+    if headers:
+        lines.append(fmt_row(headers))
+        lines.append("  ".join("-" * w for w in widths))
+    for r in rows:
+        lines.append(fmt_row(r))
+    return "\n".join("  " + ln for ln in lines)
+
+
+def _echo_table(rows, headers=None, aligns=None):
+    click.echo(_render_table(rows, headers=headers, aligns=aligns))
+
+
+# -- analysis orchestration ----------------------------------------------------
+
+def run_analysis(input_path: str, diameter_threshold: float,
+                 output_path: str) -> AnalysisResult:
+    """Run the full pipeline, emitting click progress/table output."""
+    click.echo()
+    click.secho("=" * 60, fg="cyan")
+    click.secho("  ThinSkin - STL Narrow Region Analyser", fg="cyan", bold=True)
+    click.secho("=" * 60, fg="cyan")
+    _echo_table(
+        [["Input", input_path], ["Threshold", f"\u00d8 {diameter_threshold} mm"]],
+        aligns=["<", "<"],
+    )
+
+    with click.progressbar(length=1, label="Loading mesh        ") as bar:
+        mesh = load_mesh(input_path)
+        bar.update(1)
+
+    click.echo()
+    click.secho("  Mesh info", bold=True)
+    bbox = mesh.bounding_box.extents
+    _echo_table(
+        [
+            ["Vertices", f"{len(mesh.vertices):,}"],
+            ["Faces", f"{len(mesh.faces):,}"],
+            ["Bbox (mm)", f"{bbox[0]:.2f} x {bbox[1]:.2f} x {bbox[2]:.2f}"],
+            ["Watertight", str(mesh.is_watertight)],
+        ],
+        aligns=["<", "<"],
+    )
+    click.echo()
+
+    with click.progressbar(length=2, label="Estimating thickness") as bar:
+        from .core import estimate_thickness_raycasting, estimate_curvature_radius
+        thickness = estimate_thickness_raycasting(mesh)
+        bar.update(1)
+        curv_radius = estimate_curvature_radius(mesh)
+        bar.update(1)
+    eff_diam = np.minimum(thickness, 2.0 * curv_radius)
+
+    narrow_mask = eff_diam < diameter_threshold
+    n_narrow = int(narrow_mask.sum())
+    pct = 100.0 * n_narrow / len(mesh.vertices)
+    finite_vals = eff_diam[np.isfinite(eff_diam)]
+
+    result = AnalysisResult(
+        mesh=mesh, eff_diam=eff_diam, thickness=thickness,
+        curv_radius=curv_radius, threshold=diameter_threshold,
+        narrow_mask=narrow_mask, n_narrow=n_narrow, pct_narrow=pct,
+    )
+
+    click.echo()
+    click.secho("  Results", bold=True)
+    res_rows = [["Flagged vertices", f"{n_narrow:,} ({pct:.1f}%)"]]
+    if finite_vals.size:
+        res_rows += [
+            ["Min \u00d8", f"{finite_vals.min():.3f} mm"],
+            ["Mean \u00d8", f"{finite_vals.mean():.3f} mm"],
+            ["Max \u00d8", f"{finite_vals.max():.3f} mm"],
+        ]
+    _echo_table(res_rows, aligns=["<", "<"])
+
+    # -- STL / OBJ export ------------------------------------------------------
+    if n_narrow == 0:
+        click.echo()
+        click.secho(f"  \u2713 No regions below {diameter_threshold} mm found.",
+                    fg="green")
+    else:
+        face_flags = narrow_mask[mesh.faces]
+        narrow_faces = np.where(face_flags.all(axis=1))[0]
+        if len(narrow_faces) == 0:
+            narrow_faces = np.where(face_flags.any(axis=1))[0]
+        highlight = mesh.submesh([narrow_faces], append=True)
+        highlight.export(output_path)
+        result.stl_path = output_path
+        result.written.append(output_path)
+
+        obj_path = output_path.replace(".stl", "_coloured.obj")
+        export_coloured_obj(mesh, eff_diam, diameter_threshold, obj_path)
+        result.obj_path = obj_path
+        result.written.append(obj_path)
+
+        click.echo()
+        click.secho(
+            f"  \u2713 Highlight STL \u2192 {output_path}  "
+            f"({len(narrow_faces):,} faces)", fg="green")
+        click.secho(f"  \u2713 Colour OBJ    \u2192 {obj_path}", fg="green")
+
+    # -- annotated PNG ---------------------------------------------------------
+    click.echo()
+    with click.progressbar(length=4, label="Rendering views     ") as bar:
+        png_path = generate_annotated_report(
+            mesh, eff_diam, diameter_threshold, output_path,
+            progress_each=lambda: bar.update(1),
+        )
+    result.png_path = png_path
+    result.written.append(png_path)
+    click.secho(f"  \u2713 Annotated PNG \u2192 {png_path}", fg="green")
+
+    # -- diameter histogram ----------------------------------------------------
+    rows = diameter_breakdown(eff_diam, diameter_threshold)
+    if rows:
+        click.echo()
+        click.secho("  Diameter distribution (mm)", bold=True)
+        total = max(1, int(np.isfinite(eff_diam).sum()))
+        table_rows = []
+        for lbl, count, is_narrow in rows:
+            bar_len = min(40, count // max(1, total // 40)) if total else 0
+            bar_str = "\u2588" * bar_len
+            marker = " <- NARROW" if is_narrow else ""
+            table_rows.append([f"{lbl} mm", f"{count:,}", bar_str + marker])
+        _echo_table(table_rows, headers=["range", "count", "histogram"],
+                    aligns=[">", ">", "<"])
+
+    click.echo()
+    click.secho("=" * 60, fg="cyan")
+    click.echo()
+    return result
+
+
+# -- click entry point ---------------------------------------------------------
+
+@click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.argument("input_stl", type=click.Path(exists=True, dir_okay=False))
+@click.option("--diameter", "-d", "diameter", type=float, default=2.0,
+              show_default=True,
+              help="Minimum diameter threshold in mm.")
+@click.option("--output", "-o", "output", type=click.Path(dir_okay=False),
+              default=None,
+              help="Output STL path (default: <input>_narrow.stl).")
+@click.version_option(__version__, "-V", "--version", prog_name="thinskin")
+def main(input_stl, diameter, output):
+    """Analyse an STL and highlight regions thinner than a given diameter.
+
+    \b
+    Outputs:
+      *_narrow.stl           Mesh of only the flagged faces
+      *_narrow_coloured.obj  Full mesh with red=narrow / green=OK colours
+      *_annotated_views.png  CAD-style multi-view annotated report
+    """
+    if output is None:
+        for ext in (".stl", ".STL"):
+            if input_stl.endswith(ext):
+                output = input_stl[: -len(ext)] + "_narrow.stl"
+                break
+        else:
+            output = input_stl + "_narrow.stl"
+    if os.path.abspath(output) == os.path.abspath(input_stl):
+        output = input_stl + "_narrow.stl"
+
+    try:
+        run_analysis(input_stl, diameter, output)
+    except RuntimeError as e:
+        raise click.ClickException(str(e))
+
+
+if __name__ == "__main__":
+    main()

thinskin-0.1.0/src/thinskin/core.py

@@ -0,0 +1,161 @@
+"""
+Core analysis for ThinSkin
+==========================
+Analyses an STL file and identifies regions where the local geometry is
+thinner than a specified diameter threshold.
+
+Method
+------
+For every vertex in the mesh we estimate the local "inscribed diameter"
+using two complementary approaches:
+  1. Ray-cast thickness  - cast rays inward along the inverted vertex normal
+     and find the nearest opposing surface hit.
+  2. Local curvature radius  - computed from the mean curvature at each
+     vertex via the cotangent-weighted Laplacian.
+
+The minimum of both estimates is used as the effective local diameter.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field
+from typing import Optional
+
+import numpy as np
+
+try:
+    import trimesh
+except ImportError:  # pragma: no cover
+    sys.exit("ERROR: trimesh not found.  Run:  pip install trimesh numpy scipy rtree")
+
+
+# -- thickness / curvature -----------------------------------------------------
+
+def estimate_thickness_raycasting(mesh: "trimesh.Trimesh") -> np.ndarray:
+    """Estimate per-vertex wall thickness by casting rays inward."""
+    vertices = mesh.vertices
+    normals = mesh.vertex_normals
+    thickness = np.full(len(vertices), np.inf)
+    ray_origins = vertices - normals * 1e-4
+    ray_directions = -normals
+
+    locations, index_ray, _ = mesh.ray.intersects_location(
+        ray_origins=ray_origins,
+        ray_directions=ray_directions,
+        multiple_hits=False,
+    )
+    if len(index_ray):
+        dists = np.linalg.norm(locations - ray_origins[index_ray], axis=1)
+        thickness[index_ray] = dists
+    return thickness
+
+
+def estimate_curvature_radius(mesh: "trimesh.Trimesh") -> np.ndarray:
+    """Estimate per-vertex curvature radius via the cotangent Laplacian."""
+    vertices = mesh.vertices
+    faces = mesh.faces
+    n = len(vertices)
+    area = np.zeros(n)
+    Lv = np.zeros((n, 3))
+
+    for i in range(3):
+        j = (i + 1) % 3
+        k = (i + 2) % 3
+        vi = vertices[faces[:, i]]
+        vj = vertices[faces[:, j]]
+        vk = vertices[faces[:, k]]
+        u = vi - vk
+        v = vj - vk
+        cos_k = np.einsum('ij,ij->i', u, v)
+        cross_k = np.cross(u, v)
+        sin_k = np.linalg.norm(cross_k, axis=1)
+        cot_k = np.where(sin_k > 1e-10, cos_k / sin_k, 0.0)
+        face_area = 0.5 * sin_k
+        for fi in range(3):
+            np.add.at(area, faces[:, fi], face_area / 3.0)
+        np.add.at(Lv, faces[:, i], cot_k[:, None] * (vi - vj))
+        np.add.at(Lv, faces[:, j], cot_k[:, None] * (vj - vi))
+
+    safe_area = np.where(area > 1e-12, area, 1e-12)
+    H = np.linalg.norm(Lv, axis=1) / (2.0 * safe_area)
+    return np.where(H > 1e-6, 1.0 / H, np.inf)
+
+
+# -- OBJ export ----------------------------------------------------------------
+
+def export_coloured_obj(mesh, eff_diam, threshold, path):
+    """Write the full mesh with red=narrow / green=OK vertex colours."""
+    verts = mesh.vertices
+    faces = mesh.faces
+    normals = mesh.vertex_normals
+    d_norm = np.clip(eff_diam / threshold, 0.0, 1.0)
+    with open(path, "w") as f:
+        f.write("# ThinSkin - colour-coded OBJ\n")
+        f.write(f"# Red vertices are below {threshold} mm effective diameter\n\n")
+        for v, d in zip(verts, d_norm):
+            r = 1.0 - d
+            g = d
+            b = 0.0
+            f.write(f"v {v[0]:.6f} {v[1]:.6f} {v[2]:.6f} {r:.3f} {g:.3f} {b:.3f}\n")
+        for vn in normals:
+            f.write(f"vn {vn[0]:.6f} {vn[1]:.6f} {vn[2]:.6f}\n")
+        for face in faces:
+            i0, i1, i2 = face + 1
+            f.write(f"f {i0}//{i0} {i1}//{i1} {i2}//{i2}\n")
+
+
+# Backwards-compatible private alias (kept so existing imports keep working).
+_export_coloured_obj = export_coloured_obj
+
+
+def diameter_breakdown(eff_diam, threshold):
+    """Return a list of (label, count, is_narrow) rows for the histogram."""
+    finite = eff_diam[np.isfinite(eff_diam)]
+    rows = []
+    if not len(finite):
+        return rows
+    bins = [0, 0.5, 1.0, 1.5, 2.0, 3.0, 5.0, 10.0, np.inf]
+    labels = ["<0.5", "0.5-1", "1-1.5", "1.5-2", "2-3", "3-5", "5-10", ">10"]
+    for lo, hi, lbl in zip(bins[:-1], bins[1:], labels):
+        count = int(((finite >= lo) & (finite < hi)).sum())
+        rows.append((lbl, count, hi <= threshold))
+    return rows
+
+
+# -- result container ----------------------------------------------------------
+
+@dataclass
+class AnalysisResult:
+    """Container for the outputs of :func:`analyse_mesh`."""
+    mesh: "trimesh.Trimesh"
+    eff_diam: np.ndarray
+    thickness: np.ndarray
+    curv_radius: np.ndarray
+    threshold: float
+    narrow_mask: np.ndarray
+    n_narrow: int
+    pct_narrow: float
+    stl_path: Optional[str] = None
+    obj_path: Optional[str] = None
+    png_path: Optional[str] = None
+    written: list = field(default_factory=list)
+
+
+def load_mesh(input_path: str) -> "trimesh.Trimesh":
+    """Load and validate an STL into a single Trimesh."""
+    try:
+        mesh = trimesh.load_mesh(input_path)
+    except Exception as e:  # noqa: BLE001
+        raise RuntimeError(f"loading STL: {e}") from e
+    if not isinstance(mesh, trimesh.Trimesh):
+        raise RuntimeError("loaded object is not a single Trimesh.")
+    return mesh
+
+
+def compute_effective_diameter(mesh: "trimesh.Trimesh"):
+    """Return (eff_diam, thickness, curv_radius) per vertex."""
+    thickness = estimate_thickness_raycasting(mesh)
+    curv_radius = estimate_curvature_radius(mesh)
+    eff_diam = np.minimum(thickness, 2.0 * curv_radius)
+    return eff_diam, thickness, curv_radius

thinskin-0.1.0/src/thinskin/report.py

@@ -0,0 +1,300 @@
+"""
+Annotated CAD-style report rendering for ThinSkin.
+
+Produces a 2x2 grid of annotated orthographic views saved as a PNG:
+  *_annotated_views.png - CAD-style multi-view annotated report image
+"""
+
+from __future__ import annotations
+
+import sys
+
+import numpy as np
+
+try:
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+    import matplotlib.patches as mpatches
+except ImportError:  # pragma: no cover
+    sys.exit("ERROR: matplotlib not found.  Run:  pip install matplotlib")
+
+
+# -- projection helpers --------------------------------------------------------
+
+def project_vertices(vertices, view: str) -> np.ndarray:
+    """Return (N,2) 2-D projection for a named orthographic view."""
+    x, y, z = vertices[:, 0], vertices[:, 1], vertices[:, 2]
+    if view == "top":
+        return np.column_stack([x, y])
+    if view == "front":
+        return np.column_stack([x, z])
+    if view == "side":
+        return np.column_stack([y, z])
+    if view == "isometric":
+        a = np.radians(30)
+        xi = x * np.cos(a) - y * np.cos(a)
+        yi = x * np.sin(a) + y * np.sin(a) + z
+        return np.column_stack([xi, yi])
+    raise ValueError(f"Unknown view: {view}")
+
+
+def _face_projected_depth(vertices, faces, view):
+    """Return per-face depth for painter's-algorithm sorting."""
+    tri = vertices[faces]
+    cx, cy, cz = tri[:, :, 0].mean(1), tri[:, :, 1].mean(1), tri[:, :, 2].mean(1)
+    if view == "top":
+        return -cy
+    if view == "front":
+        return -cy
+    if view == "side":
+        return cx
+    if view == "isometric":
+        return -(cx + cy - cz)
+    return np.zeros(len(faces))
+
+
+# -- annotated view renderer ---------------------------------------------------
+
+VIEWS = ["isometric", "top", "front", "side"]
+VIEW_LABELS = {
+    "isometric": "Isometric",
+    "top": "Top (XY)",
+    "front": "Front (XZ)",
+    "side": "Side (YZ)",
+}
+
+# CAD-style colour palette
+BG_COLOR = "#dff0f7"
+PANEL_BG = "#e8f4f8"
+MESH_OK = "#c8860a"
+MESH_NARROW = "#cc2222"
+EDGE_COLOR = "#7a5500"
+GRID_COLOR = "#b0cdd8"
+ANNOT_BOX_BG = "#ffffcc"
+ANNOT_BOX_ED = "#333333"
+AXIS_X = "#cc2222"
+AXIS_Y = "#228822"
+AXIS_Z = "#2255cc"
+
+
+def _render_view(ax, mesh, eff_diam, threshold, view, show_grid=True):
+    """Render one orthographic view onto a matplotlib Axes."""
+    verts = mesh.vertices
+    faces = mesh.faces
+
+    proj = project_vertices(verts, view)
+    depths = _face_projected_depth(verts, faces, view)
+    order = np.argsort(depths)
+
+    narrow_v = eff_diam < threshold
+
+    polys_ok = []
+    polys_narrow = []
+    for fi in order:
+        tri2d = proj[faces[fi]]
+        is_narrow = narrow_v[faces[fi]].any()
+        if is_narrow:
+            polys_narrow.append(tri2d)
+        else:
+            polys_ok.append(tri2d)
+
+    from matplotlib.collections import PolyCollection
+
+    if polys_ok:
+        pc_ok = PolyCollection(polys_ok, facecolor=MESH_OK,
+                               edgecolor=EDGE_COLOR, linewidth=0.15, alpha=0.85)
+        ax.add_collection(pc_ok)
+
+    if polys_narrow:
+        pc_n = PolyCollection(polys_narrow, facecolor=MESH_NARROW,
+                              edgecolor="#880000", linewidth=0.2, alpha=0.95, zorder=3)
+        ax.add_collection(pc_n)
+
+    ax.set_facecolor(BG_COLOR)
+    if show_grid:
+        ax.grid(True, color=GRID_COLOR, linewidth=0.5, linestyle="--", alpha=0.6)
+
+    pad = (proj.max() - proj.min()) * 0.12 + 0.5
+    ax.set_xlim(proj[:, 0].min() - pad, proj[:, 0].max() + pad)
+    ax.set_ylim(proj[:, 1].min() - pad, proj[:, 1].max() + pad)
+    ax.set_aspect("equal")
+    ax.tick_params(labelsize=6, color=GRID_COLOR)
+    for spine in ax.spines.values():
+        spine.set_edgecolor(GRID_COLOR)
+
+    _draw_axis_indicator(ax, view)
+    _annotate_narrow_regions(ax, proj, narrow_v, eff_diam, threshold, view)
+
+    ax.set_title(VIEW_LABELS[view], fontsize=8, fontweight="bold",
+                 color="#223344", pad=3)
+
+
+def _draw_axis_indicator(ax, view):
+    """Draw a small WCS triad in the bottom-left corner."""
+    xl, xr = ax.get_xlim()
+    yb, yt = ax.get_ylim()
+    ox = xl + (xr - xl) * 0.07
+    oy = yb + (yt - yb) * 0.07
+    L = (xr - xl) * 0.08
+
+    labels = {
+        "top": [("X", L, 0, AXIS_X), ("Y", 0, L, AXIS_Y)],
+        "front": [("X", L, 0, AXIS_X), ("Z", 0, L, AXIS_Z)],
+        "side": [("Y", L, 0, AXIS_Y), ("Z", 0, L, AXIS_Z)],
+        "isometric": [("X", L * 0.87, -L * 0.5, AXIS_X),
+                      ("Y", -L * 0.87, -L * 0.5, AXIS_Y),
+                      ("Z", 0, L, AXIS_Z)],
+    }
+    arrs = labels.get(view, [])
+    for lbl, dx, dy, col in arrs:
+        ax.annotate("", xy=(ox + dx, oy + dy), xytext=(ox, oy),
+                    arrowprops=dict(arrowstyle="-|>", color=col, lw=1.2),
+                    zorder=10)
+        ax.text(ox + dx * 1.25, oy + dy * 1.25, lbl, fontsize=5, color=col,
+                ha="center", va="center", fontweight="bold", zorder=10)
+    ax.plot(ox, oy, "o", color="#334455", markersize=2, zorder=11)
+
+
+# module-level stash so cluster fn can access it
+_eff_diam_global = None
+
+
+def eff_diam_for_cluster(indices):
+    if _eff_diam_global is None:
+        return 0.0
+    vals = _eff_diam_global[indices]
+    finite = vals[np.isfinite(vals)]
+    return float(finite.min()) if len(finite) else 0.0
+
+
+def _cluster_narrow_points(proj_narrow, max_annotations=6):
+    """Group nearby narrow vertices into clusters so we don't spam annotations."""
+    if len(proj_narrow) == 0:
+        return []
+    from scipy.spatial import cKDTree
+    tree = cKDTree(proj_narrow)
+    radius = (proj_narrow.max() - proj_narrow.min()) * 0.08 + 0.5
+    visited = np.zeros(len(proj_narrow), bool)
+    clusters = []
+    for i in range(len(proj_narrow)):
+        if visited[i]:
+            continue
+        idxs = tree.query_ball_point(proj_narrow[i], radius)
+        for idx in idxs:
+            visited[idx] = True
+        clusters.append(idxs)
+    clusters.sort(key=len, reverse=True)
+    result = []
+    for cl in clusters[:max_annotations]:
+        pts = proj_narrow[cl]
+        result.append((pts[:, 0].mean(), pts[:, 1].mean(),
+                       len(cl), eff_diam_for_cluster(cl)))
+    return result
+
+
+def _annotate_narrow_regions(ax, proj, narrow_v, eff_diam, threshold, view):
+    """Place leader-line callouts on each cluster of narrow vertices."""
+    global _eff_diam_global
+    _eff_diam_global = eff_diam
+
+    proj_narrow = proj[narrow_v]
+    if len(proj_narrow) == 0:
+        return
+
+    clusters = _cluster_narrow_points(proj_narrow)
+    if not clusters:
+        return
+
+    xl, xr = ax.get_xlim()
+    yb, yt = ax.get_ylim()
+    w = xr - xl
+    h = yt - yb
+
+    offsets = [
+        (0.22, 0.22), (-0.22, 0.22),
+        (0.22, -0.22), (-0.22, -0.22),
+        (0.30, 0.05), (-0.30, 0.05),
+    ]
+
+    for idx, (cx, cy, count, min_d) in enumerate(clusters):
+        odx, ody = offsets[idx % len(offsets)]
+        tx = cx + w * odx
+        ty = cy + h * ody
+
+        tx = np.clip(tx, xl + w * 0.05, xr - w * 0.05)
+        ty = np.clip(ty, yb + h * 0.05, yt - h * 0.05)
+
+        label = f"\u00d8 {min_d:.2f} mm"
+
+        ax.annotate(
+            label,
+            xy=(cx, cy),
+            xytext=(tx, ty),
+            fontsize=6.5,
+            fontweight="bold",
+            color="#111111",
+            bbox=dict(boxstyle="round,pad=0.3", fc=ANNOT_BOX_BG,
+                      ec=ANNOT_BOX_ED, lw=0.8, alpha=0.92),
+            arrowprops=dict(
+                arrowstyle="-|>",
+                color="#cc2222",
+                lw=1.0,
+                connectionstyle="arc3,rad=0.15",
+            ),
+            zorder=20,
+        )
+
+        ax.plot(cx, cy, "o", color="#cc2222", markersize=3,
+                markeredgecolor="#880000", markeredgewidth=0.5, zorder=21)
+
+
+# -- main annotated report -----------------------------------------------------
+
+def generate_annotated_report(mesh, eff_diam, threshold, base_path: str,
+                              progress_each=None):
+    """Produce a 2x2 grid of annotated orthographic views saved as a PNG.
+
+    ``progress_each`` is an optional callable invoked once per rendered view,
+    used by the CLI to drive a progress bar without coupling to ``click``.
+    """
+    fig = plt.figure(figsize=(16, 12), facecolor=PANEL_BG)
+    fig.patch.set_facecolor(PANEL_BG)
+
+    narrow_count = int((eff_diam < threshold).sum())
+    finite = eff_diam[np.isfinite(eff_diam)]
+    min_d = float(finite.min()) if len(finite) else 0.0
+    title = (f"ThinSkin Narrow Region Analysis  -  threshold: \u00d8 {threshold:.2f} mm  "
+             f"|  {narrow_count:,} flagged vertices  |  min \u00d8 {min_d:.3f} mm")
+    fig.suptitle(title, fontsize=11, fontweight="bold", color="#223344", y=0.97)
+
+    axes_positions = [
+        (0.02, 0.50, 0.46, 0.44),
+        (0.52, 0.50, 0.46, 0.44),
+        (0.02, 0.04, 0.46, 0.44),
+        (0.52, 0.04, 0.46, 0.44),
+    ]
+
+    for view, pos in zip(VIEWS, axes_positions):
+        ax = fig.add_axes(pos)
+        _render_view(ax, mesh, eff_diam, threshold, view)
+        if progress_each is not None:
+            progress_each()
+
+    legend_ax = fig.add_axes([0.02, 0.945, 0.96, 0.03])
+    legend_ax.set_axis_off()
+    legend_ax.set_facecolor(PANEL_BG)
+
+    handles = [
+        mpatches.Patch(color=MESH_OK, label=f"OK  (\u00d8 \u2265 {threshold:.2f} mm)"),
+        mpatches.Patch(color=MESH_NARROW, label=f"NARROW  (\u00d8 < {threshold:.2f} mm)"),
+    ]
+    legend_ax.legend(handles=handles, loc="center", ncol=2,
+                     fontsize=8, frameon=True,
+                     facecolor=ANNOT_BOX_BG, edgecolor=ANNOT_BOX_ED)
+
+    png_path = base_path.replace(".stl", "_annotated_views.png")
+    fig.savefig(png_path, dpi=150, bbox_inches="tight",
+                facecolor=PANEL_BG, edgecolor="none")
+    plt.close(fig)
+    return png_path