track: polish runtime sampling defaults

Quantum.Debug/BankingProfileTrainPoseFixtures.cs

@@ -12,6 +12,9 @@ namespace Quantum.Debug
 {
     public sealed class BankingProfileTrainPoseFixture
     {
+        private readonly TrackEvaluator _runtimeEvaluator;
+        private readonly TrainCarTransformProvider _runtimeProvider;
+
         public BankingProfileTrainPoseFixture(
             string name,
             TrackDocument document,
@@ -42,6 +45,8 @@ public BankingProfileTrainPoseFixture(
             Definition = definition ?? throw new ArgumentNullException(nameof(definition));
             LeadDistance = leadDistance;
             CenterlineSampleDistances = Array.AsReadOnly(sampleDistances);
+            _runtimeEvaluator = new TrackEvaluator(new CompiledTrackRuntime(Document));
+            _runtimeProvider = new TrainCarTransformProvider(_runtimeEvaluator);
         }
 
         public string Name { get; }
@@ -58,9 +63,7 @@ public BankingProfileTrainPoseFixture(
 
         public TrainPoseResult EvaluateTrainPose()
         {
-            var evaluator = new TrackEvaluator(Document);
-            var provider = new TrainCarTransformProvider(evaluator);
-            return provider.EvaluateTrainPose(
+            return _runtimeProvider.EvaluateTrainPose(
                 LeadDistance,
                 Definition,
                 BankingProfile);
@@ -74,7 +77,7 @@ public TrainPoseExportV1Dto ExportTrainPose()
         public DebugViewportSnapshotV1Dto BuildDebugViewportSnapshot()
         {
             ExportTrackFrame[] sampledFrames = BankingProfileSampler.SampleFramesAtDistances(
-                Document,
+                _runtimeEvaluator,
                 BankingProfile,
                 CenterlineSampleDistances);
             TrainPoseResult trainPose = EvaluateTrainPose();

Quantum.Debug/ProfileBankedHeartlineProofScenario.cs

@@ -215,10 +215,11 @@ private static double MeasureLength(IReadOnlyList<Vector3d> controlPoints)
             var points = controlPoints.ToList();
             var weights = Enumerable.Repeat(1.0, points.Count).ToList();
             var curve = new GSharkNurbsCurveAdapter(points, weights, SpatialDegree);
+            TrackSamplingOptions samplingOptions = TrackSamplingOptions.Default;
             return new ArcLengthLUT(
                 curve,
-                TrackSamplingOptions.DefaultArcLengthSamples,
-                TrackSamplingOptions.DefaultArcLengthTolerance).TotalLength;
+                samplingOptions.ArcLengthSamples,
+                samplingOptions.ArcLengthTolerance).TotalLength;
         }
 
         private static double[] BuildSampleDistances()

Quantum.Debug/SpatialLayoutProofScenario.cs

@@ -177,10 +177,11 @@ private static double MeasureLength(IReadOnlyList<Vector3d> controlPoints)
             var points = controlPoints.ToList();
             var weights = Enumerable.Repeat(1.0, points.Count).ToList();
             var curve = new GSharkNurbsCurveAdapter(points, weights, SpatialDegree);
+            TrackSamplingOptions samplingOptions = TrackSamplingOptions.Default;
             return new ArcLengthLUT(
                 curve,
-                TrackSamplingOptions.DefaultArcLengthSamples,
-                TrackSamplingOptions.DefaultArcLengthTolerance).TotalLength;
+                samplingOptions.ArcLengthSamples,
+                samplingOptions.ArcLengthTolerance).TotalLength;
         }
 
         private static double[] BuildFrameDistances()

Quantum.Tests/Debug/DebugViewportSnapshotV1FromTrackLayoutPackageV2CommandTests.cs

@@ -305,10 +305,11 @@ private static double MeasureSpatialLength(Vector3d[] points)
             points.ToList(),
             Enumerable.Repeat(1.0, points.Length).ToList(),
             degree: 3);
+        TrackSamplingOptions samplingOptions = TrackSamplingOptions.Default;
         return new ArcLengthLUT(
             curve,
-            TrackSamplingOptions.DefaultArcLengthSamples,
-            TrackSamplingOptions.DefaultArcLengthTolerance).TotalLength;
+            samplingOptions.ArcLengthSamples,
+            samplingOptions.ArcLengthTolerance).TotalLength;
     }
 
     private static TrackLayoutVector3dV2Dto Vector(double x, double y, double z)

Quantum.Tests/IO/TrackLayoutPackageV1ProofFixtures.cs

@@ -262,8 +262,8 @@ private static double MeasureNurbsLength(
                 new List<Vector3d>(controlPoints),
                 new List<double>(weights),
                 degree),
-            TrackSamplingOptions.DefaultArcLengthSamples,
-            TrackSamplingOptions.DefaultArcLengthTolerance);
+            TrackSamplingOptions.Default.ArcLengthSamples,
+            TrackSamplingOptions.Default.ArcLengthTolerance);
         return curve.Length;
     }
 

Quantum.Tests/Track/CanonicalTransportedFrameTests.cs

@@ -218,6 +218,59 @@ public void TrainBodiesAndBogies_MatchCanonicalFramesAtTheirStations()
         }
     }
 
+    [Fact]
+    public void DefaultTransportDensity_ImplicitAndExplicitRuntimeOptionsMatch()
+    {
+        TrackDocument document = CreateThreeDimensionalDensityDocument();
+        double[] distances = BuildUniformDistances(document.TotalLength, sampleCount: 21);
+
+        ExportTrackFrame[] implicitDefault = new TrackEvaluator(
+                new CompiledTrackRuntime(document))
+            .EvaluateFramesAtDistances(distances);
+        ExportTrackFrame[] explicitDefault = new TrackEvaluator(
+                new CompiledTrackRuntime(document, TrackSamplingOptions.Default))
+            .EvaluateFramesAtDistances(distances);
+
+        for (int i = 0; i < distances.Length; i++)
+        {
+            AssertFrameNear(implicitDefault[i], explicitDefault[i]);
+        }
+    }
+
+    [Fact]
+    public void TransportSampleDensity_PreservesCenterlineAndConvergesOrientation()
+    {
+        TrackDocument document = CreateThreeDimensionalDensityDocument();
+        double[] distances = BuildUniformDistances(document.TotalLength, sampleCount: 31);
+
+        ExportTrackFrame[] sparse = SampleWithTransportSamples(
+            document,
+            transportSamplesPerSegment: 2,
+            distances);
+        ExportTrackFrame[] medium = SampleWithTransportSamples(
+            document,
+            transportSamplesPerSegment: 16,
+            distances);
+        ExportTrackFrame[] dense = SampleWithTransportSamples(
+            document,
+            transportSamplesPerSegment: 128,
+            distances);
+
+        AssertCenterlineSamplesNear(sparse, dense);
+        AssertCenterlineSamplesNear(medium, dense);
+
+        double sparseToDense = MaxNormalOrBinormalAngleDeltaRadians(sparse, dense);
+        double mediumToDense = MaxNormalOrBinormalAngleDeltaRadians(medium, dense);
+
+        Assert.True(
+            sparseToDense > 1e-4,
+            $"Expected sparse transport density to produce a measurable orientation delta, got {sparseToDense:R} radians.");
+        Assert.True(
+            mediumToDense < sparseToDense,
+            $"Expected denser transport sampling to converge: sparse={sparseToDense:R}, medium={mediumToDense:R}.");
+        Assert.InRange(mediumToDense, 0.0, 0.05);
+    }
+
     private static TrackDocument CreateSmoothTwoSegmentDocument()
     {
         var first = new CubicBezierCurve(
@@ -238,6 +291,98 @@ private static TrackDocument CreateSmoothTwoSegmentDocument()
         });
     }
 
+    private static TrackDocument CreateThreeDimensionalDensityDocument()
+    {
+        var curve = new CubicBezierCurve(
+            new Vector3d(0.0, 0.0, 0.0),
+            new Vector3d(12.0, -4.0, 18.0),
+            new Vector3d(-6.0, 22.0, 30.0),
+            new Vector3d(28.0, 16.0, 44.0));
+
+        return new TrackDocument(new TrackSegment[]
+        {
+            new CurvedSegment(
+                new ArcLengthLUT(curve).TotalLength,
+                id: "transport-density-3d",
+                spline: curve)
+        });
+    }
+
+    private static double[] BuildUniformDistances(double totalLength, int sampleCount)
+    {
+        var distances = new double[sampleCount];
+        for (int i = 0; i < distances.Length; i++)
+        {
+            distances[i] = totalLength * i / (sampleCount - 1.0);
+        }
+
+        distances[distances.Length - 1] = totalLength;
+        return distances;
+    }
+
+    private static ExportTrackFrame[] SampleWithTransportSamples(
+        TrackDocument document,
+        int transportSamplesPerSegment,
+        IReadOnlyList<double> distances)
+    {
+        var options = new TrackSamplingOptions(
+            TrackSamplingOptions.Default.ArcLengthSamples,
+            TrackSamplingOptions.Default.ArcLengthTolerance,
+            transportSamplesPerSegment);
+        var evaluator = new TrackEvaluator(new CompiledTrackRuntime(document, options));
+        return evaluator.EvaluateFramesAtDistances(distances);
+    }
+
+    private static void AssertCenterlineSamplesNear(
+        IReadOnlyList<ExportTrackFrame> expected,
+        IReadOnlyList<ExportTrackFrame> actual)
+    {
+        Assert.Equal(expected.Count, actual.Count);
+        for (int i = 0; i < expected.Count; i++)
+        {
+            AssertNear(expected[i].Distance, actual[i].Distance);
+            AssertVectorNear(expected[i].Position, actual[i].Position);
+            AssertVectorNear(expected[i].Tangent, actual[i].Tangent);
+        }
+    }
+
+    private static double MaxNormalOrBinormalAngleDeltaRadians(
+        IReadOnlyList<ExportTrackFrame> expected,
+        IReadOnlyList<ExportTrackFrame> actual)
+    {
+        Assert.Equal(expected.Count, actual.Count);
+        double max = 0.0;
+
+        for (int i = 0; i < expected.Count; i++)
+        {
+            max = System.Math.Max(max, AngleDeltaRadians(expected[i].Normal, actual[i].Normal));
+            max = System.Math.Max(max, AngleDeltaRadians(expected[i].Binormal, actual[i].Binormal));
+        }
+
+        return max;
+    }
+
+    private static double AngleDeltaRadians(Vector3d expected, Vector3d actual)
+    {
+        double dot = Vector3d.Dot(expected.Normalized(), actual.Normalized());
+        return System.Math.Acos(Clamp(dot, -1.0, 1.0));
+    }
+
+    private static double Clamp(double value, double min, double max)
+    {
+        if (value < min)
+        {
+            return min;
+        }
+
+        if (value > max)
+        {
+            return max;
+        }
+
+        return value;
+    }
+
     private static void AssertValidFrame(ExportTrackFrame frame)
     {
         Assert.True(IsFinite(frame.Position));

Quantum.Tests/Track/SpatialSectionTrackAuthoringTests.cs

@@ -296,10 +296,11 @@ private static double MeasureLength(
     {
         weights ??= Enumerable.Repeat(1.0, controlPoints.Count).ToList();
         var curve = new GSharkNurbsCurveAdapter(controlPoints, weights, degree);
+        TrackSamplingOptions samplingOptions = TrackSamplingOptions.Default;
         return new ArcLengthLUT(
             curve,
-            TrackSamplingOptions.DefaultArcLengthSamples,
-            TrackSamplingOptions.DefaultArcLengthTolerance).TotalLength;
+            samplingOptions.ArcLengthSamples,
+            samplingOptions.ArcLengthTolerance).TotalLength;
     }
 
     private static TrackStartPose CreateArbitraryStartPose()

Quantum.Tests/Track/TrackAuthoringGeometryContinuityDiagnosticsTests.cs

@@ -470,10 +470,11 @@ private static SpatialSectionDefinition CreateSpatial(
         var points = controlPoints.ToList();
         var weights = Enumerable.Repeat(1.0, points.Count).ToList();
         var curve = new GSharkNurbsCurveAdapter(points, weights, degree);
+        TrackSamplingOptions samplingOptions = TrackSamplingOptions.Default;
         double length = new ArcLengthLUT(
             curve,
-            TrackSamplingOptions.DefaultArcLengthSamples,
-            TrackSamplingOptions.DefaultArcLengthTolerance).TotalLength;
+            samplingOptions.ArcLengthSamples,
+            samplingOptions.ArcLengthTolerance).TotalLength;
         return new SpatialSectionDefinition(id, length, points, degree, weights);
     }
 

Quantum.Tests/Track/TrainRuntimeIntegrationTests.cs

@@ -157,6 +157,25 @@ public void RepeatedRuntimePoseEvaluation_DoesNotRereadArcLengthCompilationMetad
         Assert.Equal(readsAfterCompilation, curve.LengthReadCount);
     }
 
+    [Fact]
+    public void DocumentProviderPoseEvaluation_CompilesOneRuntimeSnapshotPerCall()
+    {
+        var curve = new CountingArcLengthLineCurve(30.0);
+        var document = new TrackDocument(new[]
+        {
+            new StraightSegment(curve.Length, "counting", spline: curve)
+        });
+        var provider = new TrainCarTransformProvider(new TrackEvaluator(document));
+        TrainConsistDefinition definition = CreateConsistDefinition();
+        int readsBeforePoseEvaluation = curve.LengthReadCount;
+
+        provider.EvaluateTrainPose(24.0, definition);
+        Assert.Equal(readsBeforePoseEvaluation + 1, curve.LengthReadCount);
+
+        provider.EvaluateTrainPose(24.0, definition);
+        Assert.Equal(readsBeforePoseEvaluation + 2, curve.LengthReadCount);
+    }
+
     [Fact]
     public void InvalidTrainDistances_DocumentAndRuntimeProvidersThrowEquivalentExceptions()
     {