hullprod 1.0.0__py3-none-any.whl

hullprod/__init__.py

@@ -0,0 +1,17 @@
+from ._version import __version__
+from .api import assess, assess_hull
+from .mesh_quality import analyze_mesh_quality
+from .schema import FIELD_SCHEMA_VERSION, OUTPUT_LAYOUT_VERSION, SCHEMA_VERSION
+from .types import MetricResult, ProducibilityConfig
+
+__all__ = [
+    "FIELD_SCHEMA_VERSION",
+    "OUTPUT_LAYOUT_VERSION",
+    "SCHEMA_VERSION",
+    "MetricResult",
+    "ProducibilityConfig",
+    "__version__",
+    "analyze_mesh_quality",
+    "assess",
+    "assess_hull",
+]

hullprod/_version.py

@@ -0,0 +1,3 @@
+"""Authoritative HullProd package version."""
+
+__version__ = "1.0.0"

hullprod/api.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import replace
+from datetime import datetime, timezone
+from pathlib import Path
+from time import perf_counter
+
+from ._version import __version__
+from .backends import backend_for_path
+from .brep_geometry import sha256_file
+from .export import export_visualization_fields
+from .plotting import save_default_plots
+from .report import write_outputs
+from .types import ProducibilityConfig
+
+
+def assess_hull(
+    geometry: str | Path,
+    config: ProducibilityConfig | None = None,
+    n_stations: int | None = None,
+    out_dir: str | Path | None = None,
+    make_plots: bool = False,
+    largest_component: bool = False,
+    backend: str | None = None,
+    progress: Callable[[str], None] | None = None,
+    overwrite: bool = False,
+):
+    """Assess a mesh or native CAD BRep through the appropriate backend."""
+    if config is None:
+        config = ProducibilityConfig()
+    if n_stations is not None:
+        config.n_stations = n_stations
+
+    started = perf_counter()
+    emit = progress or (lambda _message: None)
+    geometry = Path(geometry).resolve()
+    if not geometry.exists():
+        raise FileNotFoundError(f"Input file not found: {geometry}")
+    if not geometry.is_file():
+        raise ValueError(f"Input path is not a file: {geometry}")
+    output_path = Path(out_dir).resolve() if out_dir is not None else None
+    if output_path is not None and output_path.is_dir() and any(output_path.iterdir()):
+        if not overwrite:
+            raise FileExistsError(
+                f"Output directory is not empty: {output_path}. "
+                "Choose --out elsewhere or pass --overwrite."
+            )
+    selected_backend = backend_for_path(geometry, override=backend)
+    assessment = selected_backend.assess(
+        geometry,
+        config,
+        largest_component=largest_component,
+        progress=progress,
+    )
+    result = assessment.result
+    result.metadata["hullprod_version"] = __version__
+    result.metadata["input_geometry"] = {
+        "path": str(geometry),
+        "name": geometry.name,
+        "extension": geometry.suffix.lower(),
+        "sha256": sha256_file(geometry),
+    }
+    result.metadata["run_timestamp_utc"] = datetime.now(timezone.utc).isoformat()
+
+    if output_path is not None:
+        out_dir = output_path
+        if assessment.visualization_mesh is not None:
+            emit("Writing visualization fields...")
+            fields_started = perf_counter()
+            field_paths = export_visualization_fields(
+                assessment.visualization_mesh,
+                result,
+                out_dir / "fields",
+            )
+            result.metadata.setdefault("output_paths", {}).update(field_paths)
+            geometry_dir = out_dir / "geometry"
+            geometry_dir.mkdir(parents=True, exist_ok=True)
+            assessment.visualization_mesh.export(geometry_dir / "display_mesh.stl")
+            result.metadata.setdefault("phase_timings", {})["visualization_fields_seconds"] = (
+                perf_counter() - fields_started
+            )
+            if make_plots:
+                emit("Generating plots...")
+                plots_started = perf_counter()
+                plot_paths = save_default_plots(
+                    assessment.visualization_mesh,
+                    result,
+                    out_dir / "plots",
+                    experimental=config.experimental_metrics,
+                )
+                result.metadata.setdefault("output_paths", {}).update(plot_paths)
+                result.metadata["phase_timings"]["plots_seconds"] = perf_counter() - plots_started
+        else:
+            raise RuntimeError(
+                "Distributed field export requires a visualization surface; "
+                "enable the BRep display tessellation."
+            )
+        emit("Writing report and manifests...")
+        result.metadata.setdefault("phase_timings", {})["total_elapsed_seconds"] = (
+            perf_counter() - started
+        )
+        output_paths = write_outputs(result, out_dir)
+        result.metadata.setdefault("output_paths", {}).update(output_paths)
+
+    result.metadata.setdefault("phase_timings", {})["total_elapsed_seconds"] = perf_counter() - started
+    return result
+
+
+def assess(
+    geometry: str | Path,
+    *,
+    out_dir: str | Path | None = None,
+    lref: float | None = None,
+    plots: bool = False,
+    experimental: bool = False,
+    overwrite: bool = False,
+    config: ProducibilityConfig | None = None,
+    largest_component: bool = False,
+    progress: Callable[[str], None] | None = None,
+):
+    """Assess one BRep or mesh file through the public HullProd 1.0 pipeline.
+
+    The file extension selects the native BRep or triangle-mesh backend.  When
+    ``out_dir`` is supplied, the same artifacts used by the CLI are written.
+    """
+    resolved = replace(config) if config is not None else ProducibilityConfig()
+    if lref is not None:
+        resolved.length_ref = float(lref)
+    if experimental:
+        resolved.experimental_metrics = True
+        if resolved.n_stations == 0:
+            resolved.n_stations = 80
+    return assess_hull(
+        geometry,
+        config=resolved,
+        out_dir=out_dir,
+        make_plots=plots,
+        largest_component=largest_component,
+        progress=progress,
+        overwrite=overwrite,
+    )

hullprod/backends.py

@@ -0,0 +1,195 @@
+"""Representation-specific backends behind HullProd's common assessment API."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from time import perf_counter
+from typing import Any, Protocol
+
+import trimesh
+
+from .io import clean_mesh, load_mesh
+from .mesh_ops import largest_connected_component
+from .metrics import compute_metrics
+from .types import MetricResult, ProducibilityConfig
+from .units import mesh_unit_metadata
+
+MESH_SUFFIXES = frozenset({".stl", ".obj", ".ply"})
+BREP_SUFFIXES = frozenset({".igs", ".iges", ".stp", ".step"})
+
+
+@dataclass(frozen=True)
+class BackendAssessment:
+    """Common result plus the optional geometry used only for output drawing."""
+
+    result: MetricResult
+    visualization_mesh: trimesh.Trimesh | None
+
+
+class GeometryBackend(Protocol):
+    """Minimal contract shared by the mesh and native-BRep implementations."""
+
+    name: str
+    representation: str
+
+    def assess(
+        self,
+        geometry: Path,
+        config: ProducibilityConfig,
+        *,
+        largest_component: bool,
+        progress: Callable[[str], None] | None = None,
+    ) -> BackendAssessment: ...
+
+
+class MeshBackend:
+    """Stable 1.0 triangulated-surface backend."""
+
+    name = "mesh_rusinkiewicz"
+    representation = "mesh"
+
+    def assess(
+        self,
+        geometry: Path,
+        config: ProducibilityConfig,
+        *,
+        largest_component: bool,
+        progress: Callable[[str], None] | None = None,
+    ) -> BackendAssessment:
+        emit = progress or (lambda _message: None)
+        emit("Loading triangle mesh...")
+        mesh = clean_mesh(load_mesh(geometry))
+        if len(mesh.vertices) == 0 or len(mesh.faces) == 0 or mesh.area <= 0.0:
+            raise ValueError(f"Mesh is empty or has no positive-area surface: {geometry}")
+        if largest_component:
+            mesh = largest_connected_component(mesh)
+        emit(f"Loaded {len(mesh.vertices):,} vertices and {len(mesh.faces):,} triangles.")
+        result = compute_metrics(mesh, config=config, progress=progress)
+        result.metadata.setdefault("representation", self.representation)
+        result.metadata.setdefault("backend", self.name)
+        result.metadata.setdefault("source_format", geometry.suffix.lower().lstrip("."))
+        result.metadata.setdefault("canonical_metrics_depend_on_display_mesh", False)
+        result.metadata.setdefault("units", mesh_unit_metadata())
+        return BackendAssessment(result=result, visualization_mesh=mesh)
+
+
+class BRepBackend:
+    """Direct parametric-surface backend; its display mesh is non-canonical."""
+
+    name = "brep_native"
+    representation = "brep"
+
+    def assess(
+        self,
+        geometry: Path,
+        config: ProducibilityConfig,
+        *,
+        largest_component: bool,
+        progress: Callable[[str], None] | None = None,
+    ) -> BackendAssessment:
+        if largest_component:
+            raise ValueError(
+                "--largest-component is mesh-specific; select BRep roots explicitly "
+                "with brep_root_indices"
+            )
+        from .brep_display import generate_brep_display
+        from .brep_geometry import load_brep
+        from .brep_metrics import compute_brep_metrics
+        from .cache import brep_cache_key, load_cached_result, save_cached_result
+        from .reference_length import reference_length_preflight
+        from .units import brep_unit_metadata
+
+        emit = progress or (lambda _message: None)
+        emit("Loading native BRep...")
+        load_started = perf_counter()
+        model = load_brep(geometry, root_indices=config.brep_root_indices)
+        load_elapsed = perf_counter() - load_started
+        emit(f"Loaded {len(model.faces)} faces in {load_elapsed:.1f} s.")
+        cache_key = brep_cache_key(model.metadata["source_sha256"], config)
+        cache_started = perf_counter()
+        cached = load_cached_result(cache_key) if config.brep_cache else None
+        cache_elapsed = perf_counter() - cache_started
+        if cached is not None:
+            preflight_messages, reference_warning = reference_length_preflight(
+                cached.metadata["reference_length"],
+                brep_unit_metadata(model.metadata),
+            )
+            for message in preflight_messages:
+                emit(message)
+            if reference_warning:
+                emit(f"WARNING: {reference_warning}")
+            emit("Using cached native BRep metric integrals and exact sections.")
+            display_mesh = None
+            cached.metadata["cache"] = {"enabled": True, "key": cache_key, "hit": True}
+            phase_timings = {
+                "native_brep_load_seconds": load_elapsed,
+                "canonical_cache_lookup_seconds": cache_elapsed,
+            }
+            if config.brep_display_mesh:
+                quality = config.brep_display_quality.upper()
+                emit(f"Generating {quality} display tessellation...")
+                display_started = perf_counter()
+                length_ref = float(cached.metrics["length_ref"])
+                display = generate_brep_display(model, config, length_ref=length_ref)
+                display_elapsed = perf_counter() - display_started
+                display_mesh = display.mesh
+                cached.local_fields = display.local_fields
+                cached.metadata["display_mesh"] = display.metadata
+                phase_timings["display_tessellation_seconds"] = display_elapsed
+                emit(
+                    "Display tessellation completed: "
+                    f"{len(display_mesh.faces):,} triangles in {display_elapsed:.1f} s."
+                )
+            else:
+                cached.metadata["display_mesh"] = {
+                    "generated": False,
+                    "display_quality": config.brep_display_quality,
+                    "canonical_metrics_depend_on_display_mesh": False,
+                }
+            cached.metadata["phase_timings"] = phase_timings
+            return BackendAssessment(result=cached, visualization_mesh=display_mesh)
+        assessment = compute_brep_metrics(model, config=config, progress=progress)
+        assessment.result.metadata.setdefault("phase_timings", {})["native_brep_load_seconds"] = (
+            load_elapsed
+        )
+        assessment.result.metadata["phase_timings"]["canonical_cache_lookup_seconds"] = (
+            cache_elapsed
+        )
+        assessment.result.metadata["cache"] = {
+            "enabled": bool(config.brep_cache),
+            "key": cache_key,
+            "hit": False,
+        }
+        if config.brep_cache:
+            save_cached_result(cache_key, assessment.result)
+        return BackendAssessment(
+            result=assessment.result,
+            visualization_mesh=assessment.display_mesh,
+        )
+
+
+def backend_for_path(path: str | Path, *, override: str | None = None) -> GeometryBackend:
+    """Select a validated backend from an explicit override or file extension."""
+    suffix = Path(path).suffix.lower()
+    if override is not None:
+        normalized = override.strip().lower()
+        if normalized == "mesh":
+            return MeshBackend()
+        if normalized in {"brep", "cad"}:
+            return BRepBackend()
+        raise ValueError(f"Unknown geometry backend: {override}")
+    if suffix in MESH_SUFFIXES:
+        return MeshBackend()
+    if suffix in BREP_SUFFIXES:
+        return BRepBackend()
+    supported = ", ".join(sorted(MESH_SUFFIXES | BREP_SUFFIXES))
+    raise ValueError(
+        f"Unsupported geometry format {suffix!r}. Supported: {supported}"
+    )
+
+
+def backend_summary(backend: GeometryBackend) -> dict[str, Any]:
+    """Return stable backend identity metadata for reports and services."""
+    return {"representation": backend.representation, "backend": backend.name}

hullprod/brep_display.py

@@ -0,0 +1,317 @@
+"""Visualization-only tessellation and native BRep field sampling."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+import trimesh
+
+from .brep_geometry import BRepModel, evaluate_surface_differential
+from .schema import CurvatureClassID
+from .types import ProducibilityConfig
+
+DISPLAY_QUALITY_PRESETS: dict[str, dict[str, float]] = {
+    "draft": {
+        "linear_deflection_span_fraction": 2.0e-3,
+        "angular_deflection": 0.25,
+    },
+    "standard": {
+        "linear_deflection_span_fraction": 7.5e-4,
+        "angular_deflection": 0.12,
+    },
+    "fine": {
+        "linear_deflection_span_fraction": 3.5e-4,
+        "angular_deflection": 0.075,
+    },
+}
+
+
+@dataclass(frozen=True)
+class BRepDisplay:
+    """A non-canonical drawing mesh with fields sampled from the BRep."""
+
+    mesh: trimesh.Trimesh
+    local_fields: dict[str, np.ndarray]
+    metadata: dict[str, Any]
+
+
+def sample_brep_reference_points(model: BRepModel) -> tuple[np.ndarray, dict[str, Any]]:
+    """Return controlled BRep tessellation points used only for automatic ``L_ref``.
+
+    Deflection is scaled by the square root of exact BRep area, which is
+    translation/rotation invariant and scales with model length.  The returned
+    samples do not participate in the canonical native-BRep integrations.
+    """
+    from OCP.BRep import BRep_Tool
+    from OCP.BRepMesh import BRepMesh_IncrementalMesh
+    from OCP.BRepTools import BRepTools
+    from OCP.TopLoc import TopLoc_Location
+
+    area = float(model.metadata.get("independent_surface_area", 0.0))
+    if not np.isfinite(area) or area <= 0.0:
+        raise ValueError("Positive BRep surface area is required for automatic reference length")
+    area_length_scale = float(np.sqrt(area))
+    area_scale_fraction = 2.0e-3
+    linear_deflection = max(area_scale_fraction * area_length_scale, 1.0e-12)
+    angular_deflection = 0.25
+
+    BRepTools.Clean_s(model.shape)
+    mesher = BRepMesh_IncrementalMesh(
+        model.shape,
+        linear_deflection,
+        False,
+        angular_deflection,
+        True,
+    )
+    mesher.Perform()
+    if not mesher.IsDone():
+        raise RuntimeError("OpenCascade automatic-reference sampling failed")
+
+    vertices: list[list[float]] = []
+    for face in model.faces:
+        location = TopLoc_Location()
+        triangulation = BRep_Tool.Triangulation_s(face, location)
+        if triangulation is None:
+            continue
+        transformation = location.Transformation()
+        for node_index in range(1, triangulation.NbNodes() + 1):
+            point = triangulation.Node(node_index).Transformed(transformation)
+            vertices.append([point.X(), point.Y(), point.Z()])
+    if len(vertices) < 2:
+        raise RuntimeError("OpenCascade automatic-reference sampling produced too few points")
+    return np.asarray(vertices, dtype=float), {
+        "representation": "controlled_BRep_tessellation",
+        "purpose": "automatic_reference_length_only",
+        "canonical_metrics_depend_on_sampling": False,
+        "linear_deflection": linear_deflection,
+        "linear_deflection_area_length_fraction": area_scale_fraction,
+        "area_length_scale": area_length_scale,
+        "angular_deflection": angular_deflection,
+    }
+
+
+def resolve_display_settings(
+    config: ProducibilityConfig,
+    *,
+    geometric_max_span: float,
+) -> dict[str, Any]:
+    """Resolve visualization-only preset values and explicit overrides."""
+    quality = str(config.brep_display_quality).strip().lower()
+    if quality not in DISPLAY_QUALITY_PRESETS:
+        choices = ", ".join(DISPLAY_QUALITY_PRESETS)
+        raise ValueError(f"Unknown display quality {quality!r}; expected one of: {choices}")
+    if not np.isfinite(geometric_max_span) or geometric_max_span <= 0.0:
+        raise ValueError("Geometric maximum span must be positive for display tessellation")
+    preset = DISPLAY_QUALITY_PRESETS[quality]
+    span_fraction = float(preset["linear_deflection_span_fraction"])
+    linear = (
+        float(config.brep_display_linear_deflection)
+        if config.brep_display_linear_deflection is not None
+        else max(span_fraction * geometric_max_span, 1.0e-8)
+    )
+    angular = (
+        float(config.brep_display_angular_deflection)
+        if config.brep_display_angular_deflection is not None
+        else float(preset["angular_deflection"])
+    )
+    if not np.isfinite(linear) or linear <= 0.0:
+        raise ValueError("Display linear deflection must be positive")
+    if not np.isfinite(angular) or angular <= 0.0:
+        raise ValueError("Display angular deflection must be positive")
+    return {
+        "display_quality": quality,
+        "linear_deflection": linear,
+        "angular_deflection": angular,
+        "linear_deflection_span_fraction": linear / geometric_max_span,
+        "preset_linear_deflection_span_fraction": span_fraction,
+        "preset_angular_deflection": float(preset["angular_deflection"]),
+        "linear_deflection_source": (
+            "explicit_override"
+            if config.brep_display_linear_deflection is not None
+            else "display_quality_preset"
+        ),
+        "angular_deflection_source": (
+            "explicit_override"
+            if config.brep_display_angular_deflection is not None
+            else "display_quality_preset"
+        ),
+        "relative_deflection": False,
+    }
+
+
+def generate_brep_display(
+    model: BRepModel,
+    config: ProducibilityConfig,
+    *,
+    length_ref: float,
+) -> BRepDisplay:
+    """Tessellate for drawing, then sample fields from exact face derivatives."""
+    from OCP.BRep import BRep_Tool
+    from OCP.BRepAdaptor import BRepAdaptor_Surface
+    from OCP.BRepMesh import BRepMesh_IncrementalMesh
+    from OCP.BRepTools import BRepTools
+    from OCP.TopAbs import TopAbs_REVERSED
+    from OCP.TopLoc import TopLoc_Location
+
+    bounds = np.asarray(model.metadata["bounds"], dtype=float)
+    span = float(np.max(np.ptp(bounds, axis=0)))
+    settings = resolve_display_settings(config, geometric_max_span=span)
+    deflection = float(settings["linear_deflection"])
+    # OpenCascade caches polygonal representations on the shape.  Clear only
+    # that non-geometric cache so a requested display resolution is honored;
+    # this does not alter the source BRep surfaces or topology.
+    BRepTools.Clean_s(model.shape)
+    mesher = BRepMesh_IncrementalMesh(
+        model.shape,
+        deflection,
+        False,
+        float(settings["angular_deflection"]),
+        True,
+    )
+    mesher.Perform()
+    if not mesher.IsDone():
+        raise RuntimeError("OpenCascade visualization tessellation failed")
+
+    vertices: list[list[float]] = []
+    uv_values: list[tuple[float, float]] = []
+    face_indices: list[int] = []
+    triangles: list[list[int]] = []
+    for face_index, face in enumerate(model.faces):
+        location = TopLoc_Location()
+        triangulation = BRep_Tool.Triangulation_s(face, location)
+        if triangulation is None or triangulation.NbTriangles() == 0:
+            continue
+        if not triangulation.HasUVNodes():
+            continue
+        offset = len(vertices)
+        transformation = location.Transformation()
+        for node_index in range(1, triangulation.NbNodes() + 1):
+            point = triangulation.Node(node_index).Transformed(transformation)
+            uv = triangulation.UVNode(node_index)
+            vertices.append([point.X(), point.Y(), point.Z()])
+            uv_values.append((uv.X(), uv.Y()))
+            face_indices.append(face_index)
+        reversed_face = face.Orientation() == TopAbs_REVERSED
+        for triangle_index in range(1, triangulation.NbTriangles() + 1):
+            n1, n2, n3 = triangulation.Triangle(triangle_index).Get()
+            values = [offset + n1 - 1, offset + n2 - 1, offset + n3 - 1]
+            if reversed_face:
+                values[1], values[2] = values[2], values[1]
+            triangles.append(values)
+    if not triangles:
+        raise RuntimeError("Visualization tessellation produced no UV-mapped triangles")
+    mesh = trimesh.Trimesh(
+        vertices=np.asarray(vertices, dtype=float),
+        faces=np.asarray(triangles, dtype=np.int64),
+        process=False,
+    )
+
+    h_threshold = (
+        config.h_threshold
+        if config.h_threshold is not None
+        else config.h_threshold_factor / length_ref
+    )
+    k_threshold = (
+        config.k_threshold
+        if config.k_threshold is not None
+        else config.k_threshold_factor / length_ref**2
+    )
+    count = len(vertices)
+    mean = np.full(count, np.nan)
+    gaussian = np.full(count, np.nan)
+    gradient_squared = np.full(count, np.nan)
+    normal = np.full((count, 3), np.nan)
+    valid = np.zeros(count, dtype=float)
+    fairness_valid = np.zeros(count, dtype=float)
+    classes = np.full(count, int(CurvatureClassID.INVALID), dtype=np.int8)
+    surfaces = [BRepAdaptor_Surface(face, True) for face in model.faces]
+    for index, ((u, v), face_index) in enumerate(zip(uv_values, face_indices, strict=True)):
+        try:
+            value = evaluate_surface_differential(
+                model.faces[face_index],
+                u,
+                v,
+                need_third=config.brep_compute_fairness,
+                surface=surfaces[face_index],
+            )
+            mean[index] = value.mean_curvature
+            gaussian[index] = value.gaussian_curvature
+            normal[index] = value.normal
+            valid[index] = 1.0
+            if config.brep_compute_fairness and value.gradient_mean_squared is not None:
+                gradient_squared[index] = value.gradient_mean_squared
+                fairness_valid[index] = 1.0
+            if abs(gaussian[index]) <= k_threshold and abs(mean[index]) <= h_threshold:
+                classes[index] = int(CurvatureClassID.FLAT)
+            elif abs(gaussian[index]) <= k_threshold:
+                classes[index] = int(CurvatureClassID.SINGLE_CURVATURE)
+            elif gaussian[index] > k_threshold:
+                classes[index] = int(CurvatureClassID.ELLIPTIC_DOUBLE_CURVATURE)
+            else:
+                classes[index] = int(CurvatureClassID.SADDLE_REVERSE_DOUBLE_CURVATURE)
+        except Exception:
+            try:
+                value = evaluate_surface_differential(
+                    model.faces[face_index],
+                    u,
+                    v,
+                    need_third=False,
+                    surface=surfaces[face_index],
+                )
+                mean[index] = value.mean_curvature
+                gaussian[index] = value.gaussian_curvature
+                normal[index] = value.normal
+                valid[index] = 1.0
+            except Exception:
+                pass
+    sample_valid = valid.astype(bool)
+    classes[sample_valid & (np.abs(gaussian) <= k_threshold) & (np.abs(mean) <= h_threshold)] = int(
+        CurvatureClassID.FLAT
+    )
+    classes[sample_valid & (np.abs(gaussian) <= k_threshold) & (np.abs(mean) > h_threshold)] = int(
+        CurvatureClassID.SINGLE_CURVATURE
+    )
+    classes[sample_valid & (gaussian > k_threshold)] = int(
+        CurvatureClassID.ELLIPTIC_DOUBLE_CURVATURE
+    )
+    classes[sample_valid & (gaussian < -k_threshold)] = int(
+        CurvatureClassID.SADDLE_REVERSE_DOUBLE_CURVATURE
+    )
+    principal_offset = np.sqrt(np.maximum(mean**2 - gaussian, 0.0))
+    threshold_mask = np.full(count, -1, dtype=np.int8)
+    threshold_mask[sample_valid] = (np.abs(gaussian[sample_valid]) > k_threshold).astype(np.int8)
+    local_fields = {
+        "H": mean,
+        "K": gaussian,
+        "principal_curvature_k1": mean + principal_offset,
+        "principal_curvature_k2": mean - principal_offset,
+        "H_valid": valid.astype(np.uint8),
+        "K_valid": valid.astype(np.uint8),
+        "surface_normal_x": normal[:, 0],
+        "surface_normal_y": normal[:, 1],
+        "surface_normal_z": normal[:, 2],
+        "developability_density": np.abs(gaussian) * length_ref**2,
+        "developability_positive_density": np.maximum(gaussian, 0.0) * length_ref**2,
+        "developability_negative_density": np.maximum(-gaussian, 0.0) * length_ref**2,
+        "developability_threshold_mask": threshold_mask,
+        "curvature_class_id": classes,
+        "brep_face_index": np.asarray(face_indices, dtype=np.int32),
+    }
+    if config.experimental_metrics or config.n_stations > 0 or config.brep_compute_fairness:
+        local_fields["curvature_energy_density"] = (mean * length_ref) ** 2
+    if config.brep_compute_fairness:
+        local_fields["curvature_fairness_density"] = gradient_squared * length_ref**4
+        local_fields["fairness_valid"] = fairness_valid.astype(np.uint8)
+    metadata = {
+        **settings,
+        "generated": True,
+        "purpose": "visualization_export_and_mesh_vs_brep_verification_only",
+        "canonical_metrics_depend_on_display_mesh": False,
+        "vertex_count": len(mesh.vertices),
+        "face_count": len(mesh.faces),
+        "triangle_count": len(mesh.faces),
+        "field_source": "direct_BRep_face_UV_differential_evaluation",
+    }
+    return BRepDisplay(mesh=mesh, local_fields=local_fields, metadata=metadata)