Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add M15 picking contracts and tessellation picker

Yuechen Liecd4d75eea31
diff --git a/Aetheris.Kernel.Core.Tests/Brep/Picking/BrepPickerTests.cs b/Aetheris.Kernel.Core.Tests/Brep/Picking/BrepPickerTests.cs
new file mode 100644
index 00000000..77a62bda
--- /dev/null
+++ b/Aetheris.Kernel.Core.Tests/Brep/Picking/BrepPickerTests.cs
@@ -0,0 +1,165 @@
+using Aetheris.Kernel.Core.Brep;
+using Aetheris.Kernel.Core.Brep.Picking;
+using Aetheris.Kernel.Core.Brep.Tessellation;
+using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Topology;
+
+namespace Aetheris.Kernel.Core.Tests.Brep.Picking;
+
+public sealed class BrepPickerTests
+{
+ [Fact]
+ public void Pick_FaceHitOnBox_ReturnsFaceContractWithPointNormalAndDistance()
+ {
+ var box = BrepPrimitives.CreateBox(2d, 2d, 2d).Value;
+ var tessellation = BrepDisplayTessellator.Tessellate(box).Value;
+ var ray = new Ray3D(new Point3D(0d, 0d, 3d), Direction3D.Create(new Vector3D(0d, 0d, -1d)));
+
+ var result = BrepPicker.Pick(box, tessellation, ray);
+
+ Assert.True(result.IsSuccess);
+ var firstFaceHit = Assert.Single(result.Value.Where(h => h.EntityKind == SelectionEntityKind.Face));
+ Assert.Equal(new FaceId(2), firstFaceHit.FaceId);
+ Assert.Equal(2d, firstFaceHit.T, 8);
+ Assert.Equal(0d, firstFaceHit.Point.X, 8);
+ Assert.Equal(0d, firstFaceHit.Point.Y, 8);
+ Assert.Equal(1d, firstFaceHit.Point.Z, 8);
+ Assert.True(firstFaceHit.Normal.HasValue);
+ Assert.Equal(1d, firstFaceHit.Normal.Value.Z, 8);
+ }
+
+ [Fact]
+ public void Pick_RayMiss_ReturnsSuccessfulEmptyHitList()
+ {
+ var box = BrepPrimitives.CreateBox(2d, 2d, 2d).Value;
+ var tessellation = BrepDisplayTessellator.Tessellate(box).Value;
+ var ray = new Ray3D(new Point3D(0d, 0d, 3d), Direction3D.Create(new Vector3D(0d, 1d, 0d)));
+
+ var result = BrepPicker.Pick(box, tessellation, ray);
+
+ Assert.True(result.IsSuccess);
+ Assert.Empty(result.Value);
+ }
+
+ [Fact]
+ public void Pick_NearestOnly_IsDeterministic()
+ {
+ var box = BrepPrimitives.CreateBox(2d, 2d, 2d).Value;
+ var ray = new Ray3D(new Point3D(0d, 0d, 3d), Direction3D.Create(new Vector3D(0d, 0d, -1d)));
+ var options = PickQueryOptions.Default with { NearestOnly = true };
+
+ var first = BrepPicker.Pick(box, ray, pickOptions: options);
+ var second = BrepPicker.Pick(box, ray, pickOptions: options);
+
+ Assert.True(first.IsSuccess);
+ Assert.True(second.IsSuccess);
+ Assert.Single(first.Value);
+ Assert.Single(second.Value);
+ Assert.Equal(first.Value[0], second.Value[0]);
+ }
+
+ [Fact]
+ public void Pick_BackfaceIsCulledByDefault_AndCanBeEnabled()
+ {
+ var box = BrepPrimitives.CreateBox(2d, 2d, 2d).Value;
+ var tessellation = BrepDisplayTessellator.Tessellate(box).Value;
+ var ray = new Ray3D(new Point3D(0d, 0d, 0d), Direction3D.Create(new Vector3D(0d, 0d, 1d)));
+
+ var culled = BrepPicker.Pick(box, tessellation, ray);
+ var includeBackfaces = BrepPicker.Pick(box, tessellation, ray, PickQueryOptions.Default with { IncludeBackfaces = true });
+
+ Assert.True(culled.IsSuccess);
+ Assert.True(includeBackfaces.IsSuccess);
+ Assert.Empty(culled.Value.Where(h => h.EntityKind == SelectionEntityKind.Face));
+ Assert.NotEmpty(includeBackfaces.Value.Where(h => h.EntityKind == SelectionEntityKind.Face));
+ }
+
+ [Fact]
+ public void Pick_RayNearEdgePolyline_ReturnsEdgeHit()
+ {
+ var box = BrepPrimitives.CreateBox(2d, 2d, 2d).Value;
+ var tessellation = BrepDisplayTessellator.Tessellate(box).Value;
+ var ray = new Ray3D(new Point3D(1.01d, -1d, 0d), Direction3D.Create(new Vector3D(0d, 1d, 0d)));
+
+ var result = BrepPicker.Pick(box, tessellation, ray, PickQueryOptions.Default with { EdgeTolerance = 0.02d });
+
+ Assert.True(result.IsSuccess);
+ var edgeHit = Assert.Single(result.Value.Where(h => h.EntityKind == SelectionEntityKind.Edge));
+ Assert.True(edgeHit.EdgeId.HasValue);
+ Assert.Equal(1d, edgeHit.Point.X, 3);
+ Assert.Equal(-1d, edgeHit.Point.Y, 3);
+ }
+
+ [Fact]
+ public void Pick_EdgeToleranceControlsEdgeHits()
+ {
+ var box = BrepPrimitives.CreateBox(2d, 2d, 2d).Value;
+ var tessellation = BrepDisplayTessellator.Tessellate(box).Value;
+ var ray = new Ray3D(new Point3D(1.01d, -1d, 0d), Direction3D.Create(new Vector3D(0d, 1d, 0d)));
+
+ var result = BrepPicker.Pick(box, tessellation, ray, PickQueryOptions.Default with { EdgeTolerance = 0.005d });
+
+ Assert.True(result.IsSuccess);
+ Assert.Empty(result.Value.Where(h => h.EntityKind == SelectionEntityKind.Edge));
+ }
+
+ [Fact]
+ public void Pick_MultipleEdgeCandidates_AreSortedDeterministicallyByT()
+ {
+ var box = BrepPrimitives.CreateBox(2d, 2d, 2d).Value;
+ var tessellation = BrepDisplayTessellator.Tessellate(box).Value;
+ var ray = new Ray3D(new Point3D(1d, -2d, 1d), Direction3D.Create(new Vector3D(0d, 1d, 0d)));
+
+ var result = BrepPicker.Pick(box, tessellation, ray, PickQueryOptions.Default with { IncludeBackfaces = true, EdgeTolerance = 1e-6d });
+
+ Assert.True(result.IsSuccess);
+ var edges = result.Value.Where(h => h.EntityKind == SelectionEntityKind.Edge).ToArray();
+ Assert.True(edges.Length >= 2);
+ Assert.True(edges[0].T <= edges[1].T);
+ }
+
+ [Fact]
+ public void Pick_FaceEdgeTie_UsesEdgeFirstOrdering_AndNearestOnlyMatches()
+ {
+ var body = BrepPrimitives.CreateBox(2d, 2d, 2d).Value;
+ var tessellation = BrepDisplayTessellator.Tessellate(body).Value;
+ var ray = new Ray3D(new Point3D(1d, 1d, 3d), Direction3D.Create(new Vector3D(0d, 0d, -1d)));
+
+ var allHits = BrepPicker.Pick(body, tessellation, ray, PickQueryOptions.Default with { IncludeBackfaces = true, EdgeTolerance = 1e-6d, SortTieTolerance = 1e-5d });
+ var nearest = BrepPicker.Pick(body, tessellation, ray, PickQueryOptions.Default with { IncludeBackfaces = true, EdgeTolerance = 1e-6d, SortTieTolerance = 1e-5d, NearestOnly = true });
+
+ Assert.True(allHits.IsSuccess);
+ Assert.True(nearest.IsSuccess);
+ Assert.NotEmpty(allHits.Value);
+ Assert.Equal(SelectionEntityKind.Edge, allHits.Value[0].EntityKind);
+ Assert.Single(nearest.Value);
+ Assert.Equal(SelectionEntityKind.Edge, nearest.Value[0].EntityKind);
+ }
+
+ [Fact]
+ public void Pick_EmptyTessellation_ReturnsInvalidArgumentDiagnostic()
+ {
+ var box = BrepPrimitives.CreateBox(2d, 2d, 2d).Value;
+ var empty = new DisplayTessellationResult([], []);
+ var ray = new Ray3D(new Point3D(0d, 0d, 3d), Direction3D.Create(new Vector3D(0d, 0d, -1d)));
+
+ var result = BrepPicker.Pick(box, empty, ray);
+
+ Assert.False(result.IsSuccess);
+ Assert.Contains(result.Diagnostics, d => d.Code == KernelDiagnosticCode.InvalidArgument);
+ }
+
+ [Fact]
+ public void Pick_InvalidOptions_ReturnFailureWithoutThrowing()
+ {
+ var box = BrepPrimitives.CreateBox(2d, 2d, 2d).Value;
+ var tessellation = BrepDisplayTessellator.Tessellate(box).Value;
+ var ray = new Ray3D(new Point3D(0d, 0d, 3d), Direction3D.Create(new Vector3D(0d, 0d, -1d)));
+
+ var result = BrepPicker.Pick(box, tessellation, ray, PickQueryOptions.Default with { EdgeTolerance = -1d });
+
+ Assert.False(result.IsSuccess);
+ Assert.Contains(result.Diagnostics, d => d.Code == KernelDiagnosticCode.InvalidArgument);
+ }
+}
diff --git a/Aetheris.Kernel.Core/Brep/Picking/BrepPicker.cs b/Aetheris.Kernel.Core/Brep/Picking/BrepPicker.cs
new file mode 100644
index 00000000..cec23ea1
--- /dev/null
+++ b/Aetheris.Kernel.Core/Brep/Picking/BrepPicker.cs
@@ -0,0 +1,424 @@
+using Aetheris.Kernel.Core.Brep.Tessellation;
+using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Numerics;
+using Aetheris.Kernel.Core.Results;
+using Aetheris.Kernel.Core.Topology;
+
+namespace Aetheris.Kernel.Core.Brep.Picking;
+
+public static class BrepPicker
+{
+ public static KernelResult<IReadOnlyList<PickHit>> Pick(
+ BrepBody body,
+ Ray3D ray,
+ DisplayTessellationOptions? tessellationOptions = null,
+ PickQueryOptions? pickOptions = null,
+ ToleranceContext? tolerance = null)
+ {
+ if (body is null)
+ {
+ return KernelResult<IReadOnlyList<PickHit>>.Failure([CreateInvalidArgument("body must be provided.")]);
+ }
+
+ var tessellationResult = BrepDisplayTessellator.Tessellate(body, tessellationOptions);
+ if (!tessellationResult.IsSuccess)
+ {
+ return KernelResult<IReadOnlyList<PickHit>>.Failure(tessellationResult.Diagnostics);
+ }
+
+ return Pick(body, tessellationResult.Value, ray, pickOptions, tolerance);
+ }
+
+ public static KernelResult<IReadOnlyList<PickHit>> Pick(
+ BrepBody body,
+ DisplayTessellationResult tessellation,
+ Ray3D ray,
+ PickQueryOptions? options = null,
+ ToleranceContext? tolerance = null)
+ {
+ if (body is null)
+ {
+ return KernelResult<IReadOnlyList<PickHit>>.Failure([CreateInvalidArgument("body must be provided.")]);
+ }
+
+ if (tessellation is null)
+ {
+ return KernelResult<IReadOnlyList<PickHit>>.Failure([CreateInvalidArgument("tessellation must be provided.")]);
+ }
+
+ if (tessellation.FacePatches.Count == 0 && tessellation.EdgePolylines.Count == 0)
+ {
+ return KernelResult<IReadOnlyList<PickHit>>.Failure([CreateInvalidArgument("tessellation must contain at least one face patch or edge polyline.")]);
+ }
+
+ var context = tolerance ?? ToleranceContext.Default;
+ var effectiveOptions = options ?? PickQueryOptions.Default;
+ var optionDiagnostics = effectiveOptions.Validate();
+ if (optionDiagnostics.Count > 0)
+ {
+ return KernelResult<IReadOnlyList<PickHit>>.Failure(optionDiagnostics);
+ }
+
+ var bodyId = body.Topology.Bodies.OrderBy(b => b.Id.Value).Select(b => (BodyId?)b.Id).FirstOrDefault();
+ var hits = new List<PickHit>();
+
+ hits.AddRange(CollectFaceHits(tessellation.FacePatches, ray, effectiveOptions, context, bodyId));
+ hits.AddRange(CollectEdgeHits(tessellation.EdgePolylines, ray, effectiveOptions, context, bodyId));
+
+ var ordered = hits
+ .OrderBy(hit => hit.T)
+ .ThenBy(hit => hit.EntityKind == SelectionEntityKind.Edge ? 0 : hit.EntityKind == SelectionEntityKind.Face ? 1 : 2)
+ .ThenBy(hit => hit.FaceId?.Value ?? int.MaxValue)
+ .ThenBy(hit => hit.EdgeId?.Value ?? int.MaxValue)
+ .ToList();
+
+ // Edge wins over face when T is effectively tied.
+ ordered.Sort((a, b) => CompareHits(a, b, effectiveOptions.SortTieTolerance));
+
+ if (effectiveOptions.NearestOnly)
+ {
+ return KernelResult<IReadOnlyList<PickHit>>.Success(ordered.Take(1).ToList());
+ }
+
+ return KernelResult<IReadOnlyList<PickHit>>.Success(ordered);
+ }
+
+ private static IEnumerable<PickHit> CollectFaceHits(
+ IReadOnlyList<DisplayFaceMeshPatch> patches,
+ Ray3D ray,
+ PickQueryOptions options,
+ ToleranceContext tolerance,
+ BodyId? bodyId)
+ {
+ var results = new List<PickHit>();
+
+ for (var patchIndex = 0; patchIndex < patches.Count; patchIndex++)
+ {
+ var patch = patches[patchIndex];
+ if (patch.Positions.Count == 0 || patch.TriangleIndices.Count == 0)
+ {
+ continue;
+ }
+
+ PickHit? bestPatchHit = null;
+
+ for (var triangleIndex = 0; triangleIndex + 2 < patch.TriangleIndices.Count; triangleIndex += 3)
+ {
+ var i0 = patch.TriangleIndices[triangleIndex];
+ var i1 = patch.TriangleIndices[triangleIndex + 1];
+ var i2 = patch.TriangleIndices[triangleIndex + 2];
+
+ if (!TryGetTriangle(patch, i0, i1, i2, out var p0, out var p1, out var p2))
+ {
+ continue;
+ }
+
+ if (!TryIntersectTriangle(ray, p0, p1, p2, tolerance, out var t, out var u, out var v))
+ {
+ continue;
+ }
+
+ var clampedT = ToleranceMath.ClampToZero(t, tolerance.Linear);
+ if (options.MaxDistance.HasValue && clampedT > options.MaxDistance.Value + tolerance.Linear)
+ {
+ continue;
+ }
+
+ var hitPoint = ray.PointAt(clampedT);
+ var normal = TryInterpolateNormal(patch, i0, i1, i2, u, v) ?? TryCreateTriangleNormal(p0, p1, p2);
+ if (!options.IncludeBackfaces && normal.HasValue)
+ {
+ var facing = normal.Value.ToVector().Dot(ray.Direction.ToVector());
+ if (facing > tolerance.Linear)
+ {
+ continue;
+ }
+ }
+
+ var hit = new PickHit(
+ clampedT,
+ hitPoint,
+ normal,
+ SelectionEntityKind.Face,
+ patch.FaceId,
+ EdgeId: null,
+ bodyId,
+ SourcePatchIndex: patchIndex,
+ SourcePrimitiveIndex: triangleIndex / 3);
+
+ if (bestPatchHit is null || CompareHits(hit, bestPatchHit, options.SortTieTolerance) < 0)
+ {
+ bestPatchHit = hit;
+ }
+ }
+
+ if (bestPatchHit is not null)
+ {
+ results.Add(bestPatchHit);
+ }
+ }
+
+ return results;
+ }
+
+ private static IEnumerable<PickHit> CollectEdgeHits(
+ IReadOnlyList<DisplayEdgePolyline> polylines,
+ Ray3D ray,
+ PickQueryOptions options,
+ ToleranceContext tolerance,
+ BodyId? bodyId)
+ {
+ var results = new List<PickHit>();
+
+ for (var polylineIndex = 0; polylineIndex < polylines.Count; polylineIndex++)
+ {
+ var polyline = polylines[polylineIndex];
+ if (polyline.Points.Count < 2)
+ {
+ continue;
+ }
+
+ PickHit? bestEdgeHit = null;
+ for (var segmentIndex = 0; segmentIndex < polyline.Points.Count - 1; segmentIndex++)
+ {
+ var start = polyline.Points[segmentIndex];
+ var end = polyline.Points[segmentIndex + 1];
+
+ if (!TryIntersectRayWithSegment(ray, start, end, tolerance, out var t, out var hitPoint, out var distance))
+ {
+ continue;
+ }
+
+ if (distance > options.EdgeTolerance + tolerance.Linear)
+ {
+ continue;
+ }
+
+ if (options.MaxDistance.HasValue && t > options.MaxDistance.Value + tolerance.Linear)
+ {
+ continue;
+ }
+
+ var hit = new PickHit(
+ t,
+ hitPoint,
+ Normal: null,
+ SelectionEntityKind.Edge,
+ FaceId: null,
+ polyline.EdgeId,
+ bodyId,
+ SourcePatchIndex: polylineIndex,
+ SourcePrimitiveIndex: segmentIndex);
+
+ if (bestEdgeHit is null || CompareHits(hit, bestEdgeHit, options.SortTieTolerance) < 0)
+ {
+ bestEdgeHit = hit;
+ }
+ }
+
+ if (bestEdgeHit is not null)
+ {
+ results.Add(bestEdgeHit);
+ }
+ }
+
+ return results;
+ }
+
+ private static bool TryIntersectTriangle(
+ Ray3D ray,
+ Point3D p0,
+ Point3D p1,
+ Point3D p2,
+ ToleranceContext tolerance,
+ out double t,
+ out double u,
+ out double v)
+ {
+ t = 0d;
+ u = 0d;
+ v = 0d;
+
+ var edge1 = p1 - p0;
+ var edge2 = p2 - p0;
+ var pvec = ray.Direction.ToVector().Cross(edge2);
+ var determinant = edge1.Dot(pvec);
+
+ if (ToleranceMath.AlmostZero(determinant, tolerance))
+ {
+ return false;
+ }
+
+ var invDet = 1d / determinant;
+ var tvec = ray.Origin - p0;
+ u = tvec.Dot(pvec) * invDet;
+ if (u < -tolerance.Linear || u > 1d + tolerance.Linear)
+ {
+ return false;
+ }
+
+ var qvec = tvec.Cross(edge1);
+ v = ray.Direction.ToVector().Dot(qvec) * invDet;
+ if (v < -tolerance.Linear || u + v > 1d + tolerance.Linear)
+ {
+ return false;
+ }
+
+ t = edge2.Dot(qvec) * invDet;
+ return t >= -tolerance.Linear;
+ }
+
+ private static Direction3D? TryInterpolateNormal(DisplayFaceMeshPatch patch, int i0, int i1, int i2, double u, double v)
+ {
+ if (!TryGetNormal(patch, i0, out var n0)
+ || !TryGetNormal(patch, i1, out var n1)
+ || !TryGetNormal(patch, i2, out var n2))
+ {
+ return null;
+ }
+
+ var w = 1d - u - v;
+ var normal = (n0 * w) + (n1 * u) + (n2 * v);
+ return Direction3D.TryCreate(normal, out var direction) ? direction : null;
+ }
+
+ private static Direction3D? TryCreateTriangleNormal(Point3D p0, Point3D p1, Point3D p2)
+ {
+ var normal = (p1 - p0).Cross(p2 - p0);
+ return Direction3D.TryCreate(normal, out var direction) ? direction : null;
+ }
+
+ private static bool TryIntersectRayWithSegment(
+ Ray3D ray,
+ Point3D segmentStart,
+ Point3D segmentEnd,
+ ToleranceContext tolerance,
+ out double rayT,
+ out Point3D rayPoint,
+ out double distance)
+ {
+ rayT = 0d;
+ rayPoint = Point3D.Origin;
+ distance = 0d;
+
+ var d = ray.Direction.ToVector();
+ var v = segmentEnd - segmentStart;
+ var w0 = ray.Origin - segmentStart;
+
+ var a = d.Dot(d);
+ var b = d.Dot(v);
+ var c = v.Dot(v);
+ var d0 = d.Dot(w0);
+ var e = v.Dot(w0);
+
+ if (ToleranceMath.AlmostZero(c, tolerance))
+ {
+ return false;
+ }
+
+ var denominator = (a * c) - (b * b);
+ double u;
+ double s;
+
+ if (ToleranceMath.AlmostZero(denominator, tolerance))
+ {
+ u = System.Math.Clamp(e / c, 0d, 1d);
+ s = 0d;
+ }
+ else
+ {
+ s = ((b * e) - (c * d0)) / denominator;
+ u = ((a * e) - (b * d0)) / denominator;
+
+ if (u < 0d || u > 1d)
+ {
+ u = System.Math.Clamp(u, 0d, 1d);
+ s = -(d0 + (b * u)) / a;
+ }
+ }
+
+ if (s < -tolerance.Linear)
+ {
+ return false;
+ }
+
+ rayT = ToleranceMath.ClampToZero(s, tolerance.Linear);
+ var segmentPoint = segmentStart + (v * u);
+ rayPoint = ray.PointAt(rayT);
+ distance = (rayPoint - segmentPoint).Length;
+ return true;
+ }
+
+ private static bool TryGetTriangle(DisplayFaceMeshPatch patch, int i0, int i1, int i2, out Point3D p0, out Point3D p1, out Point3D p2)
+ {
+ p0 = Point3D.Origin;
+ p1 = Point3D.Origin;
+ p2 = Point3D.Origin;
+
+ if (i0 < 0 || i0 >= patch.Positions.Count
+ || i1 < 0 || i1 >= patch.Positions.Count
+ || i2 < 0 || i2 >= patch.Positions.Count)
+ {
+ return false;
+ }
+
+ p0 = patch.Positions[i0];
+ p1 = patch.Positions[i1];
+ p2 = patch.Positions[i2];
+ return true;
+ }
+
+ private static bool TryGetNormal(DisplayFaceMeshPatch patch, int index, out Vector3D normal)
+ {
+ normal = Vector3D.Zero;
+ if (index < 0 || index >= patch.Normals.Count)
+ {
+ return false;
+ }
+
+ normal = patch.Normals[index];
+ return true;
+ }
+
+ private static int CompareHits(PickHit left, PickHit right, double tieTolerance)
+ {
+ if (System.Math.Abs(left.T - right.T) > tieTolerance)
+ {
+ return left.T.CompareTo(right.T);
+ }
+
+ var leftRank = EntityRank(left.EntityKind);
+ var rightRank = EntityRank(right.EntityKind);
+ if (leftRank != rightRank)
+ {
+ return leftRank.CompareTo(rightRank);
+ }
+
+ var faceCompare = (left.FaceId?.Value ?? int.MaxValue).CompareTo(right.FaceId?.Value ?? int.MaxValue);
+ if (faceCompare != 0)
+ {
+ return faceCompare;
+ }
+
+ var edgeCompare = (left.EdgeId?.Value ?? int.MaxValue).CompareTo(right.EdgeId?.Value ?? int.MaxValue);
+ if (edgeCompare != 0)
+ {
+ return edgeCompare;
+ }
+
+ return (left.SourcePrimitiveIndex ?? int.MaxValue).CompareTo(right.SourcePrimitiveIndex ?? int.MaxValue);
+ }
+
+ private static int EntityRank(SelectionEntityKind kind)
+ => kind switch
+ {
+ SelectionEntityKind.Edge => 0,
+ SelectionEntityKind.Face => 1,
+ SelectionEntityKind.Body => 2,
+ _ => 3,
+ };
+
+ private static KernelDiagnostic CreateInvalidArgument(string message)
+ => new(KernelDiagnosticCode.InvalidArgument, KernelDiagnosticSeverity.Error, message, Source: nameof(BrepPicker));
+}
diff --git a/Aetheris.Kernel.Core/Brep/Picking/PickContracts.cs b/Aetheris.Kernel.Core/Brep/Picking/PickContracts.cs
new file mode 100644
index 00000000..606fd885
--- /dev/null
+++ b/Aetheris.Kernel.Core/Brep/Picking/PickContracts.cs
@@ -0,0 +1,64 @@
+using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Topology;
+
+namespace Aetheris.Kernel.Core.Brep.Picking;
+
+public enum SelectionEntityKind
+{
+ Unknown = 0,
+ Face = 1,
+ Edge = 2,
+ Body = 3,
+}
+
+public sealed record PickHit(
+ double T,
+ Point3D Point,
+ Direction3D? Normal,
+ SelectionEntityKind EntityKind,
+ FaceId? FaceId,
+ EdgeId? EdgeId,
+ BodyId? BodyId,
+ int? SourcePatchIndex = null,
+ int? SourcePrimitiveIndex = null);
+
+public sealed record PickQueryOptions(
+ bool NearestOnly,
+ bool IncludeBackfaces,
+ double EdgeTolerance,
+ double SortTieTolerance,
+ double? MaxDistance)
+{
+ public static PickQueryOptions Default { get; } = new(
+ NearestOnly: false,
+ IncludeBackfaces: false,
+ EdgeTolerance: 0.05d,
+ SortTieTolerance: 1e-6d,
+ MaxDistance: null);
+
+ public IReadOnlyList<KernelDiagnostic> Validate()
+ {
+ var diagnostics = new List<KernelDiagnostic>();
+
+ if (!double.IsFinite(EdgeTolerance) || EdgeTolerance <= 0d)
+ {
+ diagnostics.Add(CreateInvalidOption("EdgeTolerance must be finite and greater than zero."));
+ }
+
+ if (!double.IsFinite(SortTieTolerance) || SortTieTolerance < 0d)
+ {
+ diagnostics.Add(CreateInvalidOption("SortTieTolerance must be finite and greater than or equal to zero."));
+ }
+
+ if (MaxDistance.HasValue && (!double.IsFinite(MaxDistance.Value) || MaxDistance.Value < 0d))
+ {
+ diagnostics.Add(CreateInvalidOption("MaxDistance must be null or a finite value greater than or equal to zero."));
+ }
+
+ return diagnostics;
+ }
+
+ private static KernelDiagnostic CreateInvalidOption(string message)
+ => new(KernelDiagnosticCode.InvalidArgument, KernelDiagnosticSeverity.Error, message, Source: nameof(PickQueryOptions));
+}
diff --git a/docs/milestones.md b/docs/milestones.md
index fffd18f5..f922a694 100644
--- a/docs/milestones.md
+++ b/docs/milestones.md
@@ -125,3 +125,13 @@
- [x] Support edge tessellation for `Line3Curve` (2-point polyline) and `Circle3Curve` (deterministic sampled closed polyline).
- [x] Return structured `NotImplemented` diagnostics for unsupported trims/layouts; fail the full tessellation result on the first unsupported bound face/edge case.
- [x] Explicitly defer general trimmed-surface tessellation (including arbitrary holes/multi-loop trims), NURBS/spline surfaces, volumetric/analysis meshing, and renderer/GPU integration.
+
+## M15 — Picking Data + Selection Query Contracts v1
+
+- [x] Add explicit picking/selection contracts under `Brep.Picking` (`SelectionEntityKind`, `PickHit`, `PickQueryOptions`) with topology references (`FaceId`, `EdgeId`, optional `BodyId`) and viewer-friendly hit payloads (`t`, point, optional normal).
+- [x] Add `BrepPicker.Pick(...)` entry points that work against display tessellation (either precomputed or generated on demand) and return `KernelResult<IReadOnlyList<PickHit>>`.
+- [x] Support tessellation-driven face picking (ray/triangle) and edge picking (ray/segment closest approach with tolerance), including deterministic hit sorting.
+- [x] Lock deterministic policy: sort by ascending `t`; when `|Δt| <= SortTieTolerance`, edge hits are ordered before face hits; `NearestOnly` returns the first hit from that deterministic ordering.
+- [x] Default backface handling is culling (`IncludeBackfaces = false`), with opt-in backface inclusion.
+- [x] Add focused unit tests for face hits/misses, edge tolerance behavior, face-vs-edge precedence, nearest-only determinism, and structured diagnostics for malformed input.
+- [x] Explicitly defer UI/backend integration, interaction tools, acceleration structures, and caching/performance optimizations.