Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Render PMI targets on associated faces

Yuechen Li97a2eaa589ee
diff --git a/Aetheris.Kernel.Firmament.Tests/ImportedPartPmiTests.cs b/Aetheris.Kernel.Firmament.Tests/ImportedPartPmiTests.cs
index a553033e..436f4c2b 100644
--- a/Aetheris.Kernel.Firmament.Tests/ImportedPartPmiTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/ImportedPartPmiTests.cs
@@ -1,5 +1,6 @@
using System.Text.Json;
using Aetheris.Kernel.Core.Brep.Tessellation;
+using Aetheris.Kernel.Core.Math;
using Aetheris.Kernel.Core.Step242;
using Aetheris.Kernel.Firmament.Assembly;
using Aetheris.Kernel.Firmament.Export;
@@ -71,13 +72,16 @@ public sealed class ImportedPartPmiTests
foreach (var binding in body.Bindings.FaceBindings)
Assert.Equal($"face-{binding.FaceId.Value}", map.FaceEntityToFaceId["#" + binding.SourceStepEntityId]);
}
- [Fact]
- public void AnnotatedGlb_RetainsBodyBuffersAndCarriesSemanticValuesAndSeparatePresentation()
+ [Theory]
+ [InlineData(24)]
+ [InlineData(32)]
+ public void AnnotatedGlb_RetainsBodyBuffersAndCarriesSemanticValuesAndSeparatePresentation(int segments)
{
var built = FirmamentBuildAndExport.CompileSource(Source(), Path.Combine(Repo(), "fixtures/Regression/ImportedPartPmi"));
Assert.True(built.IsSuccess, string.Join("; ", built.Diagnostics));
var body = built.Value.RuntimeBody!;
- var tess = BrepDisplayTessellator.Tessellate(body, DisplayTessellationOptions.Default).Value;
+ var options = new DisplayTessellationOptions(2*Math.PI/segments, .05, segments, segments);
+ var tess = BrepDisplayTessellator.Tessellate(body, options).Value;
var positions = new List<double>(); var normals = new List<double>(); var indices = new List<int>();
foreach (var patch in tess.FacePatches)
{
@@ -88,7 +92,7 @@ public sealed class ImportedPartPmiTests
}
var display = new AssemblyDisplayMeshDocument("aetheris/display-mesh/1", "Imported", "mm",
[new("part", "part", positions.ToArray(), normals.ToArray(), indices.ToArray())],
- [new("part:occurrence", "part", null, "part", [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1])]);
+ [new("part:occurrence", "part", null, "part", [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1])]) { TessellationOptions = options };
var baseline = AssemblyGlbExporter.Serialize(display);
var file = Assert.Single(ProductArtifactExporter.Export(new("Imported", built.Value.StepText, display), ["glb"], Path.GetTempPath()));
using var json = JsonDocument.Parse(file.Bytes.AsMemory(20, BitConverter.ToInt32(file.Bytes, 12)));
@@ -100,8 +104,21 @@ public sealed class ImportedPartPmiTests
Assert.Equal(.1, diameter.GetProperty("tolerancePlus").GetDouble());
Assert.Equal(.05, diameter.GetProperty("toleranceMinus").GetDouble());
Assert.Equal(1, diameter.GetProperty("stepFaceEntities").GetArrayLength());
+ var target = diameter.GetProperty("target");
+ var targetPoints = target.GetProperty("positions").EnumerateArray().Select(p => p.GetDouble()).ToArray();
+ var targetNormals = target.GetProperty("normals").EnumerateArray().Select(p => p.GetDouble()).ToArray();
+ var offset = target.GetProperty("surfaceOffset").GetDouble();
+ for (var i = 0; i < targetPoints.Length; i += 3)
+ {
+ var point = new Point3D(targetPoints[i]-offset*targetNormals[i], targetPoints[i+1]-offset*targetNormals[i+1], targetPoints[i+2]-offset*targetNormals[i+2]);
+ Assert.Contains(tess.FacePatches.SelectMany(p => p.Positions), p => (p-point).Length < 1e-8);
+ }
Assert.Equal(3, root.GetProperty("meshes").GetArrayLength());
Assert.All(root.GetProperty("meshes").EnumerateArray().Skip(1), mesh => Assert.Equal(1, mesh.GetProperty("primitives")[0].GetProperty("mode").GetInt32()));
+ Assert.All(root.GetProperty("meshes").EnumerateArray().Skip(1), mesh =>
+ Assert.Contains(mesh.GetProperty("primitives").EnumerateArray(), p => p.GetProperty("mode").GetInt32() == 4));
+ Assert.Equal("BLEND", root.GetProperty("materials")[0].GetProperty("alphaMode").GetString());
+ Assert.Equal(.78, root.GetProperty("materials")[0].GetProperty("pbrMetallicRoughness").GetProperty("baseColorFactor")[3].GetDouble());
// Body data is a byte-identical prefix; annotation curves are appended after it.
var beforeOffset = 28 + BitConverter.ToInt32(baseline, 12);
var afterOffset = 28 + BitConverter.ToInt32(file.Bytes, 12);
@@ -109,4 +126,63 @@ public sealed class ImportedPartPmiTests
Assert.Equal(baseline.AsSpan(beforeOffset, bodyLength).ToArray(), file.Bytes.AsSpan(afterOffset, bodyLength).ToArray());
Assert.All(PmiDisplayProjection.FromStep(built.Value.StepText), annotation => Assert.NotEmpty(annotation.Lines));
}
+
+ [Theory]
+ [InlineData("#51")]
+ [InlineData("#102")]
+ public void Presentation_AttachesInsideTheSelectedSupport_NotACornerOrCylinderChord(string datum)
+ {
+ var source = Source().Replace("face(\"#51\")", $"face(\"{datum}\")");
+ var built = FirmamentBuildAndExport.CompileSource(source, Path.Combine(Repo(), "fixtures/Regression/ImportedPartPmi"));
+ Assert.True(built.IsSuccess, string.Join("; ", built.Diagnostics));
+ var body = Step242Importer.ImportBody(built.Value.StepText).Value;
+ var tess = BrepDisplayTessellator.Tessellate(body).Value;
+ foreach (var annotation in PmiDisplayProjection.FromStep(built.Value.StepText))
+ {
+ var binding = body.Bindings.FaceBindings.Single(b => b.SourceStepEntityId == annotation.StepFaceEntities.Single());
+ body.TryGetFaceSurfaceGeometry(binding.FaceId, out var surface);
+ var anchor = Point(annotation.Anchor);
+ var target = Assert.IsType<PmiDisplayTarget>(annotation.Target);
+ var normal = new Vector3D(target.Normal[0], target.Normal[1], target.Normal[2]);
+ Assert.Equal(1, normal.Length, 9);
+ Assert.True((anchor - Point(annotation.Lines[0][1])).Cross(normal).Length < 1e-8);
+ Assert.True((Point(annotation.Lines[0][1]) - anchor).Dot(normal) > 0);
+ var patch = tess.FacePatches.Single(p => p.FaceId == binding.FaceId);
+ Assert.DoesNotContain(patch.Positions, p => (p-anchor).Length < 1e-6);
+ Assert.InRange(target.SurfaceOffset, 0, annotation.TextHeight*.002);
+ // Presentation is lifted very slightly to avoid coincident-surface GLB striping.
+ // Remove the disclosed offset when proving its relationship to exact geometry.
+ var marker = target.Positions.Chunk(3).Zip(target.Normals.Chunk(3), (p,n) =>
+ Point(p) - new Vector3D(n[0],n[1],n[2])*target.SurfaceOffset).ToArray();
+ Assert.NotEmpty(target.Indices);
+ if (surface!.Plane is { } plane)
+ {
+ Assert.Equal("PlanePatch", target.Kind);
+ Assert.All(marker.Append(anchor), p => Assert.True(Math.Abs((p-plane.Origin).Dot(plane.Normal.ToVector())) < 1e-8));
+ // Every marker corner is in material on this actual trimmed face, including
+ // its hole exclusion, not merely in the plane or the global box.
+ var seat = new Aetheris.Kernel.Core.Brep.Queries.BrepPlanarSeatQuery(body);
+ Assert.All(marker.Append(anchor), p => Assert.Contains(binding.FaceId, seat.FindFaces(p, normal)));
+ }
+ else
+ {
+ var cylinder = surface.Cylinder!.Value;
+ Assert.Equal("CylinderWall", target.Kind);
+ Assert.All(marker.Append(anchor), p => {
+ var delta = p-cylinder.Origin; var axial = delta.Dot(cylinder.Axis.ToVector());
+ Assert.Equal(cylinder.Radius, (delta-cylinder.Axis.ToVector()*axial).Length, 8);
+ });
+ var values = patch.Positions.Select(p => (p-cylinder.Origin).Dot(cylinder.Axis.ToVector())).ToArray();
+ var v = (anchor-cylinder.Origin).Dot(cylinder.Axis.ToVector());
+ Assert.InRange(v, values.Min() + (values.Max()-values.Min())*.2, values.Max() - (values.Max()-values.Min())*.2);
+ Assert.True(target.StemLength < cylinder.Radius);
+ Assert.NotEmpty(target.Lines);
+ Assert.All(target.Lines, line => {
+ var axial = line.Select(p => (Point(p)-cylinder.Origin).Dot(cylinder.Axis.ToVector())).ToArray();
+ Assert.True(axial.Max()-axial.Min() < 1e-8, "Only physical rims, never the axial parameter seam, should be highlighted.");
+ });
+ }
+ }
+ static Point3D Point(double[] p) => new(p[0], p[1], p[2]);
+ }
}
diff --git a/Aetheris.Kernel.Firmament/Assembly/AssemblyDisplayMeshExporter.cs b/Aetheris.Kernel.Firmament/Assembly/AssemblyDisplayMeshExporter.cs
index 86e2ec2d..5fa9f9f6 100644
--- a/Aetheris.Kernel.Firmament/Assembly/AssemblyDisplayMeshExporter.cs
+++ b/Aetheris.Kernel.Firmament/Assembly/AssemblyDisplayMeshExporter.cs
@@ -30,6 +30,10 @@ public sealed record ResolvedDisplayMaterial(double[] BaseColor, double Roughnes
public sealed record AssemblyDisplayMeshDocument(string Schema, string Name, string Units,
IReadOnlyList<AssemblyDisplayMeshDefinition> Definitions, IReadOnlyList<AssemblyDisplayMeshOccurrence> Occurrences)
{
+ /// <summary>Producer's sampling budget for downstream surface witnesses. Presentation
+ /// bookkeeping only; excluded from the serialized display-mesh contract.</summary>
+ [System.Text.Json.Serialization.JsonIgnore]
+ public DisplayTessellationOptions? TessellationOptions { get; init; }
public IReadOnlyList<Visualization.PmiDisplayAnnotation> Annotations { get; init; } = [];
public IReadOnlyList<DisplayCamera> Cameras { get; init; } = [];
public double[]? MinimumMm { get; init; }
diff --git a/Aetheris.Kernel.Firmament/Assembly/AssemblyGlbExporter.cs b/Aetheris.Kernel.Firmament/Assembly/AssemblyGlbExporter.cs
index bf217d33..3ed8c462 100644
--- a/Aetheris.Kernel.Firmament/Assembly/AssemblyGlbExporter.cs
+++ b/Aetheris.Kernel.Firmament/Assembly/AssemblyGlbExporter.cs
@@ -100,6 +100,8 @@ public static class AssemblyGlbExporter
throw new InvalidOperationException("assembly-glb-invalid-normal:" + d.Identity);
var appearance = appearances?.GetValueOrDefault(d.Identity) ?? new();
var m = appearance.Material ?? new();
+ // PMI inspection look only; engineering geometry and authored looks are retained.
+ if (display.Annotations.Count > 0 && appearance.Material is null) m = m with { Opacity = .78 };
if (new[] { m.Red, m.Green, m.Blue, m.Metallic, m.Roughness, m.Opacity, m.EmissiveRed, m.EmissiveGreen, m.EmissiveBlue }.Any(v => !double.IsFinite(v) || v < 0 || v > 1))
throw new InvalidOperationException("assembly-glb-invalid-material");
var pbr = new Dictionary<string, object> { ["baseColorFactor"] = new[] { m.Red, m.Green, m.Blue, m.Opacity }, ["metallicFactor"] = m.Metallic, ["roughnessFactor"] = m.Roughness };
@@ -169,8 +171,20 @@ public static class AssemblyGlbExporter
var positions = annotation.Lines.SelectMany(line => line.Zip(line.Skip(1), (a, b) => new[] { a, b })
.SelectMany(pair => pair).SelectMany(point => point)).ToArray();
if (positions.Length == 0) throw new InvalidOperationException("glb-pmi-presentation-empty:" + annotation.Name);
- materials.Add(new { name = "PMI " + annotation.Name, pbrMetallicRoughness = new { baseColorFactor = new[] { .05, .1, .18, 1 }, metallicFactor = 0, roughnessFactor = 1 } });
- meshes.Add(new { name = annotation.Id, primitives = new[] { new { attributes = new Dictionary<string, object> { ["POSITION"] = Floats(positions, 3, true) }, mode = 1, material = materials.Count - 1 } },
+ materials.Add(new { name = "PMI " + annotation.Name, pbrMetallicRoughness = new { baseColorFactor = new[] { .05, .1, .18, 1 }, metallicFactor = 0, roughnessFactor = 1 }, emissiveFactor = new[] { .05, .1, .18 } });
+ var primitives = new List<object> { new { attributes = new Dictionary<string, object> { ["POSITION"] = Floats(positions, 3, true) }, mode = 1, material = materials.Count - 1 } };
+ if (annotation.Target is { } target)
+ {
+ materials.Add(new { name = "PMI target " + target.Kind, doubleSided = true,
+ pbrMetallicRoughness = new { baseColorFactor = new[] { 1d, .68, .12, 1 }, metallicFactor = 0, roughnessFactor = 1 },
+ emissiveFactor = new[] { .3, .18, .02 } });
+ primitives.Add(new { attributes = new Dictionary<string, object> {
+ ["POSITION"] = Floats(target.Indices.SelectMany(i => target.Positions.Skip(i*3).Take(3)).ToArray(), 3, true),
+ ["NORMAL"] = Floats(target.Indices.SelectMany(i => target.Normals.Skip(i*3).Take(3)).ToArray(), 3) }, mode = 4, material = materials.Count - 1 });
+ var outline = target.Lines.SelectMany(line => line.Zip(line.Skip(1), (a,b) => a.Concat(b)).SelectMany(p => p)).ToArray();
+ primitives.Add(new { attributes = new Dictionary<string, object> { ["POSITION"] = Floats(outline, 3, true) }, mode = 1, material = materials.Count - 1 });
+ }
+ meshes.Add(new { name = annotation.Id, primitives,
extras = new { role = "PMI presentation", annotationId = annotation.Id } });
roots.Add(nodes.Count);
nodes.Add(new { name = annotation.Text, mesh = meshes.Count - 1, extras = new { pmi = JsonSerializer.SerializeToElement(annotation, pmiJsonOptions) } });
diff --git a/Aetheris.Kernel.Firmament/Export/ProductArtifactExporter.cs b/Aetheris.Kernel.Firmament/Export/ProductArtifactExporter.cs
index 6e2fcda8..03938074 100644
--- a/Aetheris.Kernel.Firmament/Export/ProductArtifactExporter.cs
+++ b/Aetheris.Kernel.Firmament/Export/ProductArtifactExporter.cs
@@ -71,7 +71,7 @@ public static class ProductArtifactExporter
case "step": bytes = Encoding.UTF8.GetBytes(source.StepText!); mediaType = "model/step"; break;
case "glb":
var annotatedDisplay = source.StepText is not null && source.Assembly is null && source.Scene is null
- ? source.Display with { Annotations = Visualization.PmiDisplayProjection.FromStep(source.StepText) } : source.Display;
+ ? source.Display with { Annotations = Visualization.PmiDisplayProjection.FromStep(source.StepText, source.Display.TessellationOptions) } : source.Display;
bytes = source.Scene is { } scene ? SceneExport.Glb(scene) : AssemblyGlbExporter.Serialize(annotatedDisplay,
occurrenceLooks: source.Assembly?.Instances.Where(i => i.Appearance is not null)
.ToDictionary(i => i.StableId, i => i.Appearance!, StringComparer.Ordinal));
diff --git a/Aetheris.Kernel.Firmament/Visualization/PmiDisplayProjection.cs b/Aetheris.Kernel.Firmament/Visualization/PmiDisplayProjection.cs
index 9ea78d3c..5db704ca 100644
--- a/Aetheris.Kernel.Firmament/Visualization/PmiDisplayProjection.cs
+++ b/Aetheris.Kernel.Firmament/Visualization/PmiDisplayProjection.cs
@@ -1,5 +1,8 @@
using System.Globalization;
+using Aetheris.Kernel.Core.Brep;
using Aetheris.Kernel.Core.Brep.Tessellation;
+using Aetheris.Kernel.Core.Geometry.Surfaces;
+using Aetheris.Kernel.Core.Math;
using Aetheris.Kernel.Core.Step242;
using Aetheris.Kernel.Firmament.Materializer;
@@ -9,11 +12,25 @@ namespace Aetheris.Kernel.Firmament.Visualization;
/// never from rounded display coordinates. Points are in Z-up millimetres.</summary>
public sealed record PmiDisplayAnnotation(string Id, string Kind, string Name, string Text,
double? Value, double? TolerancePlus, double? ToleranceMinus, IReadOnlyList<int> StepFaceEntities,
- double[] Anchor, double[] LabelPosition, double TextHeight, IReadOnlyList<double[][]> Lines);
+ double[] Anchor, double[] LabelPosition, double TextHeight, IReadOnlyList<double[][]> Lines)
+{
+ public PmiDisplayTarget? Target { get; init; }
+}
+
+/// <summary>A presentation witness on the associated support, not new engineering geometry.
+/// Plane patches stay inside a trimmed display triangle. Cylinders highlight their associated
+/// trimmed wall and physical rim wires; the leader evaluates the analytic support.</summary>
+public sealed record PmiDisplayTarget(string Kind, double[] Normal, double StemLength, double[] Positions,
+ double[] Normals, int[] Indices, IReadOnlyList<double[][]> Lines)
+{
+ /// <summary>Small outward presentation offset prevents coincident-surface striping in
+ /// ordinary glTF viewers. Anchor remains on the exact support; body buffers never move.</summary>
+ public double SurfaceOffset { get; init; }
+}
public static class PmiDisplayProjection
{
- public static IReadOnlyList<PmiDisplayAnnotation> FromStep(string step)
+ public static IReadOnlyList<PmiDisplayAnnotation> FromStep(string step, DisplayTessellationOptions? options = null)
{
var inspection = Step242SemanticPmiInspector.Inspect(step);
if (!inspection.Success) throw new InvalidOperationException("pmi-display-inspection-failed: " + string.Join("; ", inspection.Diagnostics));
@@ -21,7 +38,7 @@ public static class PmiDisplayProjection
var imported = Step242Importer.ImportBody(step);
if (!imported.IsSuccess) throw new InvalidOperationException("pmi-display-body-unavailable");
var body = imported.Value;
- var tessellation = BrepDisplayTessellator.Tessellate(body, DisplayTessellationOptions.Default);
+ var tessellation = BrepDisplayTessellator.Tessellate(body, options ?? DisplayTessellationOptions.Default);
if (!tessellation.IsSuccess) throw new InvalidOperationException("pmi-display-target-unavailable");
var patches = tessellation.Value.FacePatches.ToDictionary(p => p.FaceId.Value);
var sourceFaces = body.Bindings.FaceBindings.Where(b => b.SourceStepEntityId.HasValue)
@@ -29,26 +46,36 @@ public static class PmiDisplayProjection
var points = patches.Values.SelectMany(p => p.Positions).ToArray();
if (points.Length == 0) throw new InvalidOperationException("pmi-display-target-unavailable: No displayable faces are available for callouts.");
var minX = points.Min(p => p.X); var maxX = points.Max(p => p.X);
- var minY = points.Min(p => p.Y); var maxY = points.Max(p => p.Y); var maxZ = points.Max(p => p.Z);
- var height = Math.Clamp(Math.Max(maxX - minX, maxY - minY) / 25, .5, 8);
+ var minY = points.Min(p => p.Y); var maxY = points.Max(p => p.Y);
+ var minZ = points.Min(p => p.Z); var maxZ = points.Max(p => p.Z);
+ var height = Math.Clamp(Math.Max(Math.Max(maxX - minX, maxY - minY), maxZ - minZ) / 25, .5, 8);
var result = new List<PmiDisplayAnnotation>();
foreach (var item in inspection.Items)
{
if (item.Kind is not ("Datum" or "Diameter"))
throw new InvalidOperationException($"pmi-display-kind-unsupported: {item.Kind} '{item.Name}' has no qualified 3D callout yet.");
var targets = item.GeometricFaceEntityIds.Where(id => sourceFaces.TryGetValue(id, out var face)
- && patches.TryGetValue(face, out var patch) && patch.Positions.Count > 0)
+ && patches.TryGetValue(face, out var patch) && patch.Positions.Count > 0 && patch.TriangleIndices.Count >= 3)
.Select(id => patches[sourceFaces[id]]).ToArray();
if (targets.Length == 0 || targets.Length != item.GeometricFaceEntityIds.Count)
throw new InvalidOperationException($"pmi-display-target-unresolved: '{item.Name}' has no complete geometric face association.");
- var anchorPoint = targets[0].Positions[0];
- double[] anchor = [anchorPoint.X, anchorPoint.Y, anchorPoint.Z];
double[] label = [maxX + height * 3, maxY - result.Count * height * 2.5, maxZ + height];
+ // One marker for every association: a multi-face requirement must not silently
+ // display only the first target. Current datum/diameter authoring binds one face.
+ if (targets.Length != 1)
+ throw new InvalidOperationException($"pmi-display-target-multiple-unsupported: '{item.Name}' requires a multi-face presentation.");
+ var (anchorPoint, normal, target) = Target(body, tessellation.Value, targets[0], item.Kind, height, label);
+ double[] anchor = P(anchorPoint);
+ var stem = anchorPoint + normal * target.StemLength;
string N(double value) => value.ToString("G9", CultureInfo.InvariantCulture);
var text = item.Kind == "Datum" ? $"[{item.Name}]" : $"Ø{N(item.Value!.Value)}"
+ (item.TolerancePlus.HasValue && item.ToleranceMinus.HasValue ? $" +{N(item.TolerancePlus.Value)}/-{N(item.ToleranceMinus.Value)}" : "") + " mm";
var outlines = PlanarTextProfiles.PresentationContours(text, height);
- var lines = new List<double[][]> { new[] { anchor, new[] { label[0] - height, label[1], label[2] }, label } };
+ var lines = new List<double[][]> { new[] { anchor, P(stem), new[] { label[0] - height, label[1], label[2] }, label } };
+ // A small open arrow terminates at the actual support, along its face normal.
+ var side = Direction3D.Create(normal.Cross(Math.Abs(normal.Z) < .9 ? new(0,0,1) : new Vector3D(0,1,0))).ToVector();
+ lines.Add([P(anchorPoint + normal * target.StemLength * .35 + side * target.StemLength * .15), anchor,
+ P(anchorPoint + normal * target.StemLength * .35 - side * target.StemLength * .15)]);
foreach (var curve in outlines)
{
double[] P((double X, double Y) p) => [label[0] + p.X, label[1] + p.Y, label[2]];
@@ -65,8 +92,97 @@ public static class PmiDisplayProjection
});
}
result.Add(new("pmi:" + item.EntityId, item.Kind, item.AuthoredName ?? item.Name, text,
- item.Value, item.TolerancePlus, item.ToleranceMinus, item.GeometricFaceEntityIds, anchor, label, height, lines));
+ item.Value, item.TolerancePlus, item.ToleranceMinus, item.GeometricFaceEntityIds, anchor, label, height, lines) { Target = target });
}
return result;
}
+
+ private static double[] P(Point3D p) => [p.X, p.Y, p.Z];
+ private static double[] V(Vector3D v) => [v.X, v.Y, v.Z];
+
+ private static (Point3D Anchor, Vector3D Normal, PmiDisplayTarget Marker) Target(
+ BrepBody body, DisplayTessellationResult tessellation, DisplayFaceMeshPatch patch, string kind, double height, double[] label)
+ {
+ body.TryGetFaceSurfaceGeometry(patch.FaceId, out var surface);
+ if (kind == "Datum" && surface?.Plane is PlaneSurface plane)
+ {
+ // The largest triangle incircle is a bounded, deterministic interior witness.
+ // A vertex average of the whole face can land in a hole or outside a concavity.
+ var triangle = Triangles(patch).Select(t => Incenter(t.A, t.B, t.C)).MaxBy(t => t.Radius);
+ if (triangle.Radius <= 1e-9) throw new InvalidOperationException("pmi-display-target-degenerate");
+ var center = triangle.Center;
+ var normal = plane.Normal.ToVector();
+ if (normal.Dot(patch.Normals[0]) < 0) normal = -normal;
+ var u = plane.UAxis.ToVector(); var v = plane.VAxis.ToVector();
+ var size = Math.Min(height * .8, triangle.Radius * .6); // corners inside incircle
+ var offset = Math.Min(height * .002, size * .01);
+ var lifted = center + normal * offset;
+ Point3D[] corners = [lifted - u * size - v * size, lifted + u * size - v * size,
+ lifted + u * size + v * size, lifted - u * size + v * size];
+ return (center, normal, new("PlanePatch", V(normal), height, corners.SelectMany(P).ToArray(),
+ corners.SelectMany(_ => V(normal)).ToArray(), [0,1,2,0,2,3], [corners.Append(corners[0]).Select(P).ToArray(),
+ [P(lifted - u * size), P(lifted + u * size)], [P(lifted - v * size), P(lifted + v * size)]]) { SurfaceOffset = offset });
+ }
+ if (kind == "Diameter" && surface?.Cylinder is CylinderSurface cylinder)
+ {
+ // Unwrap each admitted display triangle locally, including the periodic seam.
+ // Select a substantial triangle away from the end rims; use the label-facing
+ // side only as a deterministic tie breaker, never as topology authority.
+ Point3D Uv(Point3D point)
+ {
+ var d = point - cylinder.Origin;
+ return new(Math.Atan2(d.Dot(cylinder.YAxis.ToVector()), d.Dot(cylinder.XAxis.ToVector())) * cylinder.Radius,
+ d.Dot(cylinder.Axis.ToVector()), 0);
+ }
+ Point3D Unwrap(Point3D p, double reference) => p with { X = reference + Math.IEEERemainder(p.X - reference, 2 * Math.PI * cylinder.Radius) };
+ Point3D Evaluate(Point3D uv) => cylinder.Evaluate(uv.X / cylinder.Radius, uv.Y);
+ var midV = (patch.Positions.Min(p => Uv(p).Y) + patch.Positions.Max(p => Uv(p).Y)) / 2;
+ var candidates = Triangles(patch).Select(t =>
+ {
+ var a = Uv(t.A); var b = Unwrap(Uv(t.B), a.X); var c = Unwrap(Uv(t.C), a.X);
+ var center = new Point3D((a.X+b.X+c.X)/3, (a.Y+b.Y+c.Y)/3, 0);
+ var area = (b-a).Cross(c-a).Length;
+ var radial = cylinder.Normal(center.X/cylinder.Radius).ToVector();
+ var facing = radial.Dot(new Point3D(label[0],label[1],label[2])-Evaluate(center));
+ return (center,area,facing);
+ }).Where(t => t.area > 1e-12).ToArray();
+ if (candidates.Length == 0) throw new InvalidOperationException("pmi-display-target-degenerate");
+ var largest = candidates.Max(t => t.area);
+ var chosen = candidates.Where(t => t.area >= largest * .5)
+ .OrderBy(t => Math.Round(Math.Abs(t.center.Y - midV)/height, 8)).ThenByDescending(t => t.facing).First();
+ var anchor = Evaluate(chosen.center);
+ var normal = cylinder.Normal(chosen.center.X/cylinder.Radius).ToVector();
+ // Compare at the same angular location to retain the imported face orientation.
+ var first = patch.Positions[patch.TriangleIndices[0]];
+ var sense = cylinder.Normal(Uv(first).X/cylinder.Radius).ToVector().Dot(patch.Normals[patch.TriangleIndices[0]]) < 0 ? -1 : 1;
+ normal *= sense;
+ // Highlight the associated trimmed wall, not a nearly invisible tessellation strip.
+ // Kernel edge wires identify its rims. An edge used twice by this face is a
+ // parameter seam, not a manufactured edge, so it receives no rim highlight.
+ var rims = body.Topology.GetFace(patch.FaceId).LoopIds.SelectMany(id => body.Topology.GetLoop(id).CoedgeIds)
+ .Select(id => body.Topology.GetCoedge(id).EdgeId).GroupBy(id => id).Where(g => g.Count() == 1).Select(g => g.Key).ToHashSet();
+ var stemLength = Math.Min(height, cylinder.Radius*.45);
+ var offset = Math.Min(height * .002, stemLength * .01);
+ double[] Lift(Point3D point) => P(point + cylinder.Normal(Uv(point).X/cylinder.Radius).ToVector() * sense * offset);
+ var outlines = tessellation.EdgePolylines.Where(edge => rims.Contains(edge.EdgeId)).Select(edge =>
+ (edge.IsClosed ? edge.Points.Append(edge.Points[0]) : edge.Points).Select(Lift).ToArray()).ToArray();
+ return (anchor, normal, new("CylinderWall", V(normal), stemLength, patch.Positions.SelectMany(Lift).ToArray(),
+ patch.Normals.SelectMany(V).ToArray(), patch.TriangleIndices.ToArray(), outlines) { SurfaceOffset = offset });
+ }
+ throw new InvalidOperationException($"pmi-display-target-kind-unsupported: {kind} requires its qualified plane or cylinder support.");
+ }
+
+ private static IEnumerable<(Point3D A, Point3D B, Point3D C)> Triangles(DisplayFaceMeshPatch patch)
+ {
+ for (var i = 0; i + 2 < patch.TriangleIndices.Count; i += 3)
+ yield return (patch.Positions[patch.TriangleIndices[i]], patch.Positions[patch.TriangleIndices[i+1]], patch.Positions[patch.TriangleIndices[i+2]]);
+ }
+
+ private static (Point3D Center, double Radius) Incenter(Point3D a, Point3D b, Point3D c)
+ {
+ var wa = (b-c).Length; var wb = (a-c).Length; var wc = (a-b).Length; var sum = wa+wb+wc;
+ if (sum <= 1e-12) return (a, 0);
+ return (new((a.X*wa+b.X*wb+c.X*wc)/sum, (a.Y*wa+b.Y*wb+c.Y*wc)/sum,
+ (a.Z*wa+b.Z*wb+c.Z*wc)/sum), (b-a).Cross(c-a).Length/sum);
+ }
}
diff --git a/Aetheris.Web.Runtime/Program.cs b/Aetheris.Web.Runtime/Program.cs
index b6f09a62..7c1958b4 100644
--- a/Aetheris.Web.Runtime/Program.cs
+++ b/Aetheris.Web.Runtime/Program.cs
@@ -591,7 +591,7 @@ public static partial class Program
var meshPhase = BuildPerfTrace.Phase("web.mesh-build");
IReadOnlyList<Aetheris.Kernel.Firmament.Visualization.PmiDisplayAnnotation> annotations;
IReadOnlyList<WebDiagnostic> presentationDiagnostics = [];
- try { annotations = Aetheris.Kernel.Firmament.Visualization.PmiDisplayProjection.FromStep(step); }
+ try { annotations = Aetheris.Kernel.Firmament.Visualization.PmiDisplayProjection.FromStep(step, WebMeshBuilder.TessellationOptions); }
catch (InvalidOperationException error) when (error.Message.StartsWith("pmi-display-", StringComparison.Ordinal))
{
// A missing presentation adapter cannot invalidate admitted engineering geometry.
@@ -806,6 +806,7 @@ internal static class ParameterInspector
internal static class WebMeshBuilder
{
+ internal static DisplayTessellationOptions TessellationOptions { get; } = new(double.Pi / 16, .3, 6, 64);
public static object Build(string name, string definitionId, string entityId, BrepBody body, out AssemblyDisplayMeshDocument exportDisplay,
Aetheris.Kernel.Firmament.Materializer.SemanticTopologyCorrespondence? correspondence = null,
WebSourceRef? source = null, int buildRevision = 0, IReadOnlyDictionary<string, WebSourceRef?>? featureSources = null,
@@ -816,7 +817,7 @@ internal static class WebMeshBuilder
// Browser WASM has no blocking monitor wait. Use the existing synchronous
// tessellator authority; the Worker transport supplies UI responsiveness.
var tessPhase = BuildPerfTrace.Phase("web.tessellation");
- var tessellation = BrepDisplayTessellator.Tessellate(body, new DisplayTessellationOptions(double.Pi / 16, .3, 6, 64));
+ var tessellation = BrepDisplayTessellator.Tessellate(body, TessellationOptions);
tessPhase.Dispose();
if (!tessellation.IsSuccess) throw new InvalidOperationException(string.Join("; ", tessellation.Diagnostics.Select(item => item.Message)));
BuildPerfTrace.Count("brep.faces", body.Topology.Faces.Count());
@@ -853,7 +854,7 @@ internal static class WebMeshBuilder
var transform = new double[] { 1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1 };
exportDisplay = new("aetheris/display-mesh/1", name, "mm",
[new(definitionId, entityId, positionArray, normalArray, indexArray)],
- [new(entityId + ":occurrence", name, null, definitionId, transform, entityId)]) { Annotations = annotations ?? [] };
+ [new(entityId + ":occurrence", name, null, definitionId, transform, entityId)]) { Annotations = annotations ?? [], TessellationOptions = TessellationOptions };
return new
{
schema = "aetheris/display-mesh/1",
diff --git a/Aetheris.Web.Runtime/sdk/README.md b/Aetheris.Web.Runtime/sdk/README.md
index 0f9fa7e5..c7051828 100644
--- a/Aetheris.Web.Runtime/sdk/README.md
+++ b/Aetheris.Web.Runtime/sdk/README.md
@@ -57,7 +57,14 @@ topology addressability: there is no synthetic native feature history.
`model.mesh.importedAsset` exposes asset path, SHA-256 and import qualification.
`model.mesh.annotations` projects AP242 datum/diameter requirements with exact
values, allowances and separate font-outline/leader curves in Z-up millimetres.
-Shared Telos WebGPU/WebGL adapters render those curves. Part GLB export retains
+Its additive `target` contains surface-marker geometry, a normal and stem length:
+an interior plane patch for datums or the associated cylindrical wall and physical
+rims for diameters. A disclosed `surfaceOffset` lifts only marker graphics to avoid
+coincident-surface striping; the leader anchor stays on the exact support.
+Parameter seams are not rim markers. Shared Telos WebGPU/WebGL
+adapters render the gold witnesses without intercepting engineering picks; the
+default body appearance is 78% opaque when PMI is present, preserving authored
+appearances. Part GLB export retains
the body buffers and appends separate annotation nodes plus structured metadata
under `asset.extras.pmi` (`aetheris/pmi-display/1`, `pmiUnits: mm`). An unsupported
callout projection warns in the viewport and rejects annotated GLB export;
diff --git a/Aetheris.Web.Runtime/sdk/src/index.d.ts b/Aetheris.Web.Runtime/sdk/src/index.d.ts
index 48ead4f4..fcb186fa 100644
--- a/Aetheris.Web.Runtime/sdk/src/index.d.ts
+++ b/Aetheris.Web.Runtime/sdk/src/index.d.ts
@@ -26,6 +26,9 @@ export interface PmiDisplayAnnotation {
readonly stepFaceEntities: readonly number[]; readonly anchor: readonly number[];
readonly labelPosition: readonly number[]; readonly textHeight: number;
readonly lines: readonly (readonly (readonly number[])[])[];
+ readonly target?: { readonly kind: 'PlanePatch' | 'CylinderWall'; readonly normal: readonly number[]; readonly stemLength: number; readonly surfaceOffset: number;
+ readonly positions: readonly number[]; readonly normals: readonly number[]; readonly indices: readonly number[];
+ readonly lines: readonly (readonly (readonly number[])[])[] } | null;
}
export interface MeshRange { readonly surfaceKind?: string | null; readonly diameterMm?: number | null }
export interface SelectionDescription { readonly surfaceKind?: string | null; readonly diameterMm?: number | null }
diff --git a/Aetheris.Web.Runtime/telos/src/contracts.ts b/Aetheris.Web.Runtime/telos/src/contracts.ts
index 4e4109f0..cbf9f39a 100644
--- a/Aetheris.Web.Runtime/telos/src/contracts.ts
+++ b/Aetheris.Web.Runtime/telos/src/contracts.ts
@@ -32,6 +32,8 @@ export interface TelosGeometry {
ranges?: readonly MeshRange[];
}
export interface TelosMesh {
+ /** Presentation witnesses must not intercept engineering face/edge picks. */
+ pickable?: boolean;
definition: TelosGeometry;
identity: TelosIdentity;
transform?: NumericArray;
diff --git a/Aetheris.Web.Runtime/telos/src/index.ts b/Aetheris.Web.Runtime/telos/src/index.ts
index a46f6706..ea07de67 100644
--- a/Aetheris.Web.Runtime/telos/src/index.ts
+++ b/Aetheris.Web.Runtime/telos/src/index.ts
@@ -12,4 +12,4 @@ export * from "./temporal.js";
export * from "./concepts.js";
export * from "./measurement.js";
export * from "./sketch.js";
-export { pmiLines, pmiGroup } from './pmi.js';
+export { pmiLines, pmiMeshes, pmiGroup, disposePmiGroup, pmiBodyMaterial } from './pmi.js';
diff --git a/Aetheris.Web.Runtime/telos/src/pick.ts b/Aetheris.Web.Runtime/telos/src/pick.ts
index 47e27a54..55f8cdda 100644
--- a/Aetheris.Web.Runtime/telos/src/pick.ts
+++ b/Aetheris.Web.Runtime/telos/src/pick.ts
@@ -103,7 +103,7 @@ export class TelosPick {
const ray = this.camera.worldRay(pixel);
this.raycaster.ray.set(ray.origin, ray.direction);
const intersections = this.raycaster.intersectObjects(
- this.proxies.filter((mesh) => mesh.userData.item.visible !== false),
+ this.proxies.filter((mesh) => mesh.userData.item.visible !== false && mesh.userData.item.pickable !== false),
false,
);
// Explicit authoring surfaces take priority over model faces. Equal priority uses distance.
diff --git a/Aetheris.Web.Runtime/telos/src/pmi.ts b/Aetheris.Web.Runtime/telos/src/pmi.ts
index fbb81567..da3c7027 100644
--- a/Aetheris.Web.Runtime/telos/src/pmi.ts
+++ b/Aetheris.Web.Runtime/telos/src/pmi.ts
@@ -1,21 +1,63 @@
-import { BufferGeometry, Float32BufferAttribute, Group, LineBasicMaterial, LineSegments } from 'three';
-import type { TelosLine } from './contracts.js';
+import { BufferGeometry, DoubleSide, Float32BufferAttribute, Group, LineBasicMaterial, LineSegments, Mesh, MeshBasicMaterial } from 'three';
+import type { TelosLine, TelosMaterial, TelosMesh } from './contracts.js';
/** Shared projection of compiler-supplied PMI. Neither adapter invents values or changes body meshes. */
-export interface PmiCurves { readonly id: string; readonly lines: readonly (readonly (readonly number[])[])[] }
+type Polylines = readonly (readonly (readonly number[])[])[];
+export interface PmiCurves {
+ readonly id: string; readonly lines: Polylines;
+ readonly target?: { readonly kind: string; readonly positions: readonly number[]; readonly normals: readonly number[];
+ readonly indices: readonly number[]; readonly lines: Polylines } | null;
+}
+/** Inspection appearance only. Explicit authored appearances retain their opacity. */
+export function pmiBodyMaterial<T extends Pick<TelosMaterial, 'opacity'>>(material: T, enabled: boolean, authored = false): T {
+ return enabled && !authored ? { ...material, opacity: Math.min(material.opacity, .78) } : material;
+}
export function pmiLines(annotations: readonly PmiCurves[] = []): TelosLine[] {
- return annotations.flatMap(annotation => annotation.lines.map((points, index) => ({
- id: `${annotation.id}:${index}`, points: points.flatMap(p => [...p]), identity: { occurrenceId: annotation.id, overlayId: annotation.id },
- color: [.04, .12, .24, 1], widthPixels: 1.5, overlay: true, depthMode: 'always-on-top' as const, pickable: false, includeInFit: true,
- })));
+ return annotations.flatMap(annotation => {
+ const identity = { occurrenceId: annotation.id, overlayId: annotation.id };
+ const labels: TelosLine[] = annotation.lines.map((points, index) => ({
+ id: `${annotation.id}:${index}`, points: points.flatMap(p => [...p]), identity,
+ color: [.04, .12, .24, 1], widthPixels: 1.5, overlay: true, depthMode: 'always-on-top', pickable: false, includeInFit: true,
+ }));
+ const targets = (annotation.target?.lines ?? []).flatMap((points, index): TelosLine[] => {
+ const line: TelosLine = { id: `${annotation.id}:target:${index}`, points: points.flatMap(p => [...p]), identity,
+ color: [1, .68, .12, 1], widthPixels: 2, overlay: true, depthMode: 'depth-biased', pickable: false, includeInFit: true };
+ return [{ ...line, id: line.id + ':halo', widthPixels: 7, color: [1, .62, .05, .12] }, line];
+ });
+ return [...labels, ...targets];
+ });
+}
+export function pmiMeshes(annotations: readonly PmiCurves[] = []): TelosMesh[] {
+ return annotations.flatMap(annotation => annotation.target ? [{
+ definition: { id: annotation.id + ':target', positions: annotation.target.positions, normals: annotation.target.normals, indices: annotation.target.indices },
+ identity: { occurrenceId: annotation.id, overlayId: annotation.id }, overlay: true, pickable: false, unlit: true, depthMode: 'depth-biased' as const,
+ material: { baseColor: [1, .68, .12], metallic: 0, roughness: 1, opacity: .65 },
+ }] : []);
}
export function pmiGroup(annotations: readonly PmiCurves[] = []): Group {
const group = new Group(); group.name = 'PMI presentation';
- for (const annotation of annotations) {
- const positions = annotation.lines.flatMap(line => line.slice(1).flatMap((point, i) => [...line[i], ...point]));
+ for (const line of pmiLines(annotations).filter(line => !line.id.endsWith(':halo'))) {
+ const points = Array.from(line.points); const positions: number[] = [];
+ for (let i = 3; i < points.length; i += 3) positions.push(...points.slice(i-3,i+3));
const geometry = new BufferGeometry().setAttribute('position', new Float32BufferAttribute(positions, 3));
- const object = new LineSegments(geometry, new LineBasicMaterial({ color: 0x153356, depthTest: false }));
- object.name = annotation.id; object.renderOrder = 10; object.raycast = () => undefined; group.add(object);
+ const target = line.id.includes(':target:');
+ const object = new LineSegments(geometry, new LineBasicMaterial({ color: target ? 0xffcb45 : 0x153356,
+ depthTest: target, depthWrite: false, toneMapped: false }));
+ object.name = line.id; object.renderOrder = 10; object.raycast = () => undefined; group.add(object);
+ }
+ for (const marker of pmiMeshes(annotations)) {
+ const geometry = new BufferGeometry().setAttribute('position', new Float32BufferAttribute(Array.from(marker.definition.positions), 3));
+ geometry.setIndex(Array.from(marker.definition.indices));
+ const object = new Mesh(geometry, new MeshBasicMaterial({ color: 0xffcb45, transparent: true, opacity: .65, side: DoubleSide,
+ depthTest: true, depthWrite: false, polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1, toneMapped: false }));
+ object.name = marker.definition.id; object.renderOrder = 9; object.raycast = () => undefined; group.add(object);
}
return group;
}
+export function disposePmiGroup(group: Group): void {
+ group.traverse(object => { if (object instanceof Mesh || object instanceof LineSegments) {
+ object.geometry.dispose(); const materials = Array.isArray(object.material) ? object.material : [object.material];
+ materials.forEach(material => material.dispose());
+ } });
+ group.removeFromParent(); group.clear();
+}
diff --git a/Aetheris.Web.Runtime/telos/tests/overlay.test.ts b/Aetheris.Web.Runtime/telos/tests/overlay.test.ts
index 123849b2..efd033d2 100644
--- a/Aetheris.Web.Runtime/telos/tests/overlay.test.ts
+++ b/Aetheris.Web.Runtime/telos/tests/overlay.test.ts
@@ -69,6 +69,14 @@ test("overlay priority, visibility, and engineering geometry identity", () => {
assert.equal(pick.pick([400, 300])?.faceId, "face(+Z)");
pick.dispose();
});
+test('presentation surface markers cannot replace the engineering face pick', () => {
+ const pick = new TelosPick(camera());
+ pick.setScene({ meshes: [mesh, { ...mesh, pickable: false,
+ identity: { occurrenceId: 'PMI', overlayId: 'datum:A' }, depthMode: 'always-on-top' }], lines: [], fields: [] });
+ assert.equal(pick.pick([400,300])?.faceId, 'face(+Z)');
+ assert.equal(pick.pick([400,300])?.overlayId, undefined);
+ pick.dispose();
+});
test("selection/filter updates retain CPU geometry; a rebuild replaces it and preserves stable face identity", () => {
const pick = new TelosPick(camera());
pick.setScene({ meshes: [mesh], lines: [], fields: [] });
diff --git a/Aetheris.Web.Runtime/telos/tests/pmi.test.ts b/Aetheris.Web.Runtime/telos/tests/pmi.test.ts
index 6dd74963..11e3ed6c 100644
--- a/Aetheris.Web.Runtime/telos/tests/pmi.test.ts
+++ b/Aetheris.Web.Runtime/telos/tests/pmi.test.ts
@@ -1,7 +1,6 @@
import test from 'node:test';
import assert from 'node:assert/strict';
-import { pmiGroup, pmiLines } from '../dist/pmi.js';
-import { disposeConceptWireframe } from '../dist/concepts.js';
+import { pmiGroup, pmiLines, pmiMeshes, pmiBodyMaterial, disposePmiGroup } from '../dist/pmi.js';
test('both display adapters retain compiler coordinates and keep PMI outside engineering picks', () => {
const annotations = [{ id: 'pmi:1', lines: [[[1,2,3], [4,5,6], [7,8,9]]] }];
@@ -14,7 +13,33 @@ test('both display adapters retain compiler coordinates and keep PMI outside eng
const geometry = (group.children[0] as import('three').LineSegments).geometry;
assert.deepEqual([...geometry.getAttribute('position').array], [1,2,3,4,5,6,4,5,6,7,8,9]);
assert.equal((group.children[0] as import('three').LineSegments).material instanceof Object, true);
- disposeConceptWireframe(group);
+ disposePmiGroup(group);
assert.equal(group.children.length, 0);
assert.deepEqual(annotations[0].lines[0][0], [1,2,3]);
});
+
+test('surface witnesses use compiler geometry, depth testing and release every mesh resource', () => {
+ const target = { kind: 'PlanePatch', positions: [0,0,0,1,0,0,0,1,0], normals: [0,0,1,0,0,1,0,0,1], indices: [0,1,2], lines: [[[0,0,0],[1,0,0],[0,1,0],[0,0,0]]] };
+ const annotations = [{ id: 'pmi:A', lines: [[[0,0,0],[0,0,1]]], target }];
+ const mesh = pmiMeshes(annotations)[0];
+ assert.equal(mesh.definition.positions, target.positions);
+ assert.equal(mesh.pickable, false);
+ assert.equal(mesh.depthMode, 'depth-biased');
+ assert.ok(pmiLines(annotations).filter(l => l.id.includes(':target:')).every(l => l.depthMode === 'depth-biased'));
+ const group = pmiGroup(annotations);
+ let geometries = 0, materials = 0;
+ for (const child of group.children as (import('three').Mesh | import('three').LineSegments)[]) {
+ child.geometry.addEventListener('dispose', () => geometries++);
+ const material = child.material as import('three').Material;
+ material.addEventListener('dispose', () => materials++);
+ }
+ const count = group.children.length;
+ disposePmiGroup(group);
+ assert.equal(geometries, count); assert.equal(materials, count);
+ assert.deepEqual(target.positions, [0,0,0,1,0,0,0,1,0]);
+ const material = { opacity: 1 };
+ assert.equal(pmiBodyMaterial(material, true).opacity, .78);
+ assert.equal(material.opacity, 1);
+ assert.equal(pmiBodyMaterial(material, true, true), material);
+ assert.equal(pmiBodyMaterial(material, false), material);
+});
diff --git a/docs/public/firmament/step-import.md b/docs/public/firmament/step-import.md
index 1e509f3a..394a0ed9 100644
--- a/docs/public/firmament/step-import.md
+++ b/docs/public/firmament/step-import.md
@@ -40,9 +40,18 @@ report `ImportedStable`, the source selector, surface kind and measured cylinder
diameter; these do not imply a native editable feature history.
GLB part export projects supported datum/diameter PMI into separate font-outline
-and leader line primitives plus structured `asset.extras.pmi` records
+and leader line primitives, surface witnesses and structured `asset.extras.pmi` records
(`aetheris/pmi-display/1`, millimetres). Body vertex/index buffers are preserved.
-Callouts are static XY-plane outlines; the viewport legend remains readable when
+Datum leaders terminate inside the selected plane on a small gold patch. Diameter
+leaders terminate on the analytic cylindrical wall, whose trimmed surface and
+physical rims are highlighted in gold; parameter seams are not highlighted as rims.
+A short surface-normal stem and arrow identify each attachment. The default body
+appearance is lightly translucent during PMI inspection/export; explicit authored
+appearances are retained. All markers are presentation only and do not intercept
+engineering picks. `target` metadata records the witness geometry, normal and a
+tiny `surfaceOffset` used only to prevent coincident-surface rendering artifacts.
+The leader anchor stays on the exact support; engineering geometry is not offset.
+Callout text uses static XY-plane outlines; the viewport legend remains readable when
the geometry text is edge-on. These are presentation assets, not AP242 semantics
or manufacturing approval.
Unsupported callout kinds/associations fail annotated GLB export explicitly;
diff --git a/docs/release/IMPORTED-PART-PMI-2026-10-20.md b/docs/release/IMPORTED-PART-PMI-2026-10-20.md
index 2b64379b..d160b671 100644
--- a/docs/release/IMPORTED-PART-PMI-2026-10-20.md
+++ b/docs/release/IMPORTED-PART-PMI-2026-10-20.md
@@ -95,7 +95,7 @@ Both historical inputs currently carry the importer's **Degraded** geometry
qualification, visibly retained in the inspector. Successful annotation and
unchanged geometry do not upgrade that assessment. This pass performs no healing.
-## Qualification
+## Initial MVP qualification
- Focused imported topology/PMI/resource/export, text-profile and cross-file
composition analysis: **85 passed**.
@@ -119,6 +119,89 @@ actual workspace/export archives, source/assets, CLI analyses, parity summaries,
workspace and exported STEP have the same basename, so they are inspected in
separate `bracket/workspace/` and `bracket/export/` directories.
+## Engineering presentation refinement
+
+The first MVP preserved semantic data but placed leaders at the first tessellation
+vertex. That often meant a datum on a three-plane corner and a hole callout that
+looked unattached inside the solid. Data preservation alone did not make those
+graphics unambiguous.
+
+The shared AP242 display projector now supplies explicit surface witnesses:
+
+- **Datum:** an interior point and a small square patch on its selected plane.
+ The patch fits inside a trimmed display triangle's incircle, avoiding hole voids,
+ concavities and the arbitrary first vertex. A normal stem and arrow terminate
+ at that point.
+- **Diameter:** an interior UV-triangle point evaluated on the analytic cylinder,
+ not a tessellation chord or rim vertex. The associated trimmed wall and physical
+ rim wires receive gold highlighting. Doubly used parameter seams are excluded
+ from the rim highlight. The normal stem is bounded by the cylinder radius.
+- **Presentation:** gold witnesses, restrained wide-line halos in WebGPU, and
+ 78% default body opacity for PMI inspection. Explicit authored appearances are
+ retained. GLB contains its own gold/emissive marker materials and translucent
+ default body material; these are not styling added by the qualification viewer.
+
+The additive `target` field in `aetheris/pmi-display/1` carries marker kind, normal,
+stem length and geometry. Shared Telos WebGPU and transitional WebGL adapters
+project the same compiler geometry. Filled markers and their wires cannot intercept
+engineering picks. WebGL marker meshes/materials have explicit disposal. Body
+buffers and STEP associations are unchanged. Multi-face requirements without an
+implemented multi-face presentation reject explicitly rather than marking only
+the first association.
+
+Independent GLB readback exposed intersecting approximations: the browser body
+used 32 cylinder segments while the original PMI projector used 24. The body
+producer now retains its sampling budget for the projector and GLB exporter;
+24- and 32-segment regressions require marker vertices to correspond to actual
+body display vertices. This bookkeeping is excluded from the serialized mesh
+contract. The projector also lifts only marker graphics a tiny distance
+along the oriented surface normal, bounded by text/marker size and cylinder radius.
+The additive `surfaceOffset` records that distance in millimetres. Leaders retain
+their exact support anchors. Regression checks remove this recorded offset before
+proving the markers lie on the selected plane/cylinder and within planar material.
+The same offset geometry is shared by both viewport adapters and GLB.
+
+The independent viewer fits camera clipping to the exported model's metre-scale
+bounds. Its initial 0.01 mm near / 1 km far clip range discarded close-up depth
+precision and produced additional striping. Standard glTF depth occlusion still
+applies: orbit to inspect a far-side attachment, and use the legend when static
+text is edge-on. The qualification viewer changes camera framing/clipping only;
+it adds no PMI, materials, transparency or target styling to the downloaded asset.
+
+These witnesses identify referenced **surfaces**. This pass does not add an
+edge-target PMI authoring family or imply that a cylinder parameter seam is a
+manufactured edge. Text still occupies a static plane. Markers are display
+approximations on already admitted geometry; they do not improve the importer's
+engineering qualification or constitute a released manufacturing drawing.
+
+### Refinement qualification
+
+- Focused source/PMI/export and surface-attachment regressions: **11 passed**.
+ Checks cover interior planar material, analytic cylinder radius, normal stems,
+ physical rims without a parameter seam, sampling parity at 24/32 segments,
+ exact semantic values and byte-identical body-buffer prefixes.
+- Core fast lane: **1,087 passed**. Full solution: **5,739 passed across 20
+ projects, zero failures or skips**, including **3,000 Firmament** tests.
+ Log: `artifacts/local/pmi-target-qualified-full-tests.log`.
+- SDK: **18 passed**. Shared Telos: **18 passed**, including marker pick exclusion,
+ geometry/material disposal and preserving authored appearance. Helios:
+ **126 passed**; final SDK packaging and Helios bundle/typecheck passed.
+- Real saved plate and L-bracket workspaces reopened in Helios, displayed gold
+ targets and exported STEP + GLB with no diagnostics. CLI admission is valid.
+ All **154 / 154** plate and **550 / 550** bracket baseline STEP entity records
+ remain identical. Plate topology remains **7/15/12** faces/edges/vertices;
+ bracket topology remains **16/42/28**. Source asset hashes are unchanged.
+- The downloaded plate GLB was decoded independently and inspected in isometric,
+ label-plane and reverse views. The bracket GLB additionally verifies its
+ nonhorizontal datum and differently oriented bore. No compiler or private
+ product state is available to that viewer.
+
+Current ignored evidence is under `artifacts/local/pmi-surface-markers/`:
+actual STEP/GLB exports, CLI analyses/admission, `qualification-summary.json`,
+`helios-final.png`, the three plate GLB views, and bracket UI/GLB screenshots.
+Temporary viewers and the development server were stopped; no .NET test hosts
+remain. **Verdict: Success** for this bounded surface-attachment refinement.
+
## Boundaries and next work
- Existing semantic PMI in a newly imported STEP is explicitly rejected rather
@@ -129,7 +212,7 @@ separate `bracket/workspace/` and `bracket/export/` directories.
- The first purpose-facing authoring form covers planar datum and cylindrical
diameter. Existing graph/source transactions edit created records; complete
GD&T, distance, angular and coordinate-dimension authoring are future slices.
-- GLB callouts are static XY-plane outline/leader geometry, not camera-facing
+- GLB callout text is static XY-plane outline geometry, not camera-facing
billboards or a production drawing layout. The viewport legend remains readable
when a static label is edge-on. AP242 remains semantic engineering authority.
This metadata is not a standardized glTF semantic PMI extension.