Centralize temporal evidence lowering

This commit is contained in:
Meta Vens 2026-05-19 14:09:40 +01:00
commit d3dfb065be
7 changed files with 172 additions and 66 deletions

View file

@ -31,6 +31,10 @@ The Gaussian field is one backend for this reservoir, not the reservoir's
identity. Fractal SDF probes, visual point-cloud features, and future acoustic
constraints can all enter as stable keyed spatial evidence as long as each
producer declares confidence, time, bounds, and payload lowering rules.
`TemporalSpatialEvidenceLowering` owns the current packet conversions for
`TemporalGaussianObservation`, `AquariumTemporalSdfGaussian`, and
`AquariumGpuFusionSeed`; consumers should use those helpers instead of packing
payload vectors privately.
The D3D12 renderer lowers the field into `D3D12TemporalGaussianPacket`, uploads
the active packet span into a 1,048,576-entry structured buffer, and renders an

View file

@ -38,20 +38,7 @@ public sealed class TemporalGaussianAccumulator
public void Observe(IEnumerable<TemporalGaussianObservation> observations)
{
reservoir.Observe(observations.Select(observation => new TemporalSpatialEvidenceObservation(
observation.StableKey,
observation.Center,
observation.Radii,
observation.Orientation,
observation.ColorOpacity,
new Vector4(
MathF.Max(0.0001f, observation.Falloff),
MathF.Max(0.0001f, observation.ShapePower),
0.0f,
0.0f),
observation.Confidence,
observation.ObservedTimeSeconds,
observation.FieldId)));
reservoir.Observe(observations.Select(TemporalSpatialEvidenceLowering.FromGaussianObservation));
}
public AquariumTemporalGaussianField BuildField(float renderTimeSeconds)
@ -61,21 +48,7 @@ public sealed class TemporalGaussianAccumulator
for (var index = 0; index < snapshot.Samples.Count; index++)
{
var sample = snapshot.Samples[index];
gaussians[index] = new AquariumTemporalSdfGaussian(
sample.StableKey,
sample.Center,
sample.PreviousCenter,
sample.Velocity,
sample.Radii,
sample.Orientation,
sample.Payload0,
sample.Confidence,
sample.HistoryWeight,
sample.LastObservedTimeSeconds,
sample.Payload1.X,
sample.Payload1.Y,
sample.FieldId);
gaussians[index] = TemporalSpatialEvidenceLowering.ToTemporalGaussian(snapshot.Samples[index]);
}
return new AquariumTemporalGaussianField

View file

@ -0,0 +1,77 @@
using System.Numerics;
using Aquarium.Engine.Render;
namespace Aquarium.Engine.Fractal.Temporal;
public static class TemporalSpatialEvidenceLowering
{
public static TemporalSpatialEvidenceObservation FromGaussianObservation(TemporalGaussianObservation observation)
{
return new TemporalSpatialEvidenceObservation(
observation.StableKey,
observation.Center,
observation.Radii,
observation.Orientation,
observation.ColorOpacity,
new Vector4(
MathF.Max(0.0001f, observation.Falloff),
MathF.Max(0.0001f, observation.ShapePower),
0.0f,
0.0f),
observation.Confidence,
observation.ObservedTimeSeconds,
observation.FieldId);
}
public static AquariumTemporalSdfGaussian ToTemporalGaussian(TemporalSpatialEvidenceSample sample)
{
return new AquariumTemporalSdfGaussian(
sample.StableKey,
sample.Center,
sample.PreviousCenter,
sample.Velocity,
sample.Radii,
sample.Orientation,
sample.Payload0,
sample.Confidence,
sample.HistoryWeight,
sample.LastObservedTimeSeconds,
MathF.Max(0.0001f, sample.Payload1.X),
MathF.Max(0.0001f, sample.Payload1.Y),
sample.FieldId);
}
public static TemporalSpatialEvidenceObservation FromGpuFusionSeed(AquariumGpuFusionSeed seed, float observedTimeSeconds)
{
return new TemporalSpatialEvidenceObservation(
seed.StableKey,
seed.Center,
seed.Radii,
Quaternion.Identity,
seed.ColorOpacity,
new Vector4(
MathF.Max(0.0001f, seed.Falloff),
MathF.Max(0.0001f, seed.ShapePower),
seed.HistoryWeight,
0.0f),
seed.Confidence,
observedTimeSeconds,
seed.FieldId);
}
public static AquariumGpuFusionSeed ToGpuFusionSeed(TemporalSpatialEvidenceSample sample)
{
return new AquariumGpuFusionSeed(
sample.StableKey,
sample.Center,
sample.PreviousCenter,
sample.Velocity,
sample.Radii,
sample.Payload0,
sample.Confidence,
sample.HistoryWeight,
MathF.Max(0.0001f, sample.Payload1.X),
MathF.Max(0.0001f, sample.Payload1.Y),
sample.FieldId);
}
}

View file

@ -1,4 +1,3 @@
using System.Numerics;
using Aquarium.Engine.Fractal.Temporal;
using Aquarium.Engine.Render;
@ -28,7 +27,7 @@ public sealed class LocalCastGpuFusionAccumulator
{
var field = mapper.Map(frame);
var frameTimeSeconds = mapper.ToTimelineSeconds(frame.SourceTimeMaxNs);
reservoir.Observe(field.Seeds.Select(seed => ToObservation(seed, frameTimeSeconds)));
reservoir.Observe(field.Seeds.Select(seed => TemporalSpatialEvidenceLowering.FromGpuFusionSeed(seed, frameTimeSeconds)));
}
public AquariumGpuFusionField BuildField(float renderTimeSeconds)
@ -37,43 +36,9 @@ public sealed class LocalCastGpuFusionAccumulator
return new AquariumGpuFusionField
{
Seeds = snapshot.Samples.Select(ToSeed).ToArray(),
Seeds = snapshot.Samples.Select(TemporalSpatialEvidenceLowering.ToGpuFusionSeed).ToArray(),
AccumulationWindowSeconds = historySeconds,
PresentationDelaySeconds = PresentationDelaySeconds,
};
}
private static TemporalSpatialEvidenceObservation ToObservation(AquariumGpuFusionSeed seed, float frameTimeSeconds)
{
return new TemporalSpatialEvidenceObservation(
seed.StableKey,
seed.Center,
seed.Radii,
Quaternion.Identity,
seed.ColorOpacity,
new Vector4(
MathF.Max(0.0001f, seed.Falloff),
MathF.Max(0.0001f, seed.ShapePower),
seed.HistoryWeight,
0.0f),
seed.Confidence,
frameTimeSeconds,
seed.FieldId);
}
private static AquariumGpuFusionSeed ToSeed(TemporalSpatialEvidenceSample sample)
{
return new AquariumGpuFusionSeed(
sample.StableKey,
sample.Center,
sample.PreviousCenter,
sample.Velocity,
sample.Radii,
sample.Payload0,
sample.Confidence,
sample.HistoryWeight,
MathF.Max(0.0001f, sample.Payload1.X),
MathF.Max(0.0001f, sample.Payload1.Y),
sample.FieldId);
}
}

View file

@ -154,3 +154,4 @@
{"timestamp":"2026-05-19T14:20:00+01:00","topic":"zyphos-fractal-resource-observability","lesson":"Zyphos exposes `zyphos-fractal-plan`, a command-level dump of the current fractal selected cut and resource plan. Keep this kind of budget/cut observability alongside renderer work: pixels alone are not enough to validate stochastic LOD, residency, or cache behavior.","files":["src/Aquarium.Zyphos/ZyphosFractalTerrain.cs","src/Aquarium.Zyphos/ZyphosRuntime.cs","tests/Aquarium.Engine.Fractal.Tests/ZyphosFractalTerrainTests.cs"],"source":"third implementation slice after adding resource planning; the machine needs to explain itself without screenshot divination"}
{"timestamp":"2026-05-19T14:43:00+01:00","topic":"fractal-contribution-cache-live-loop","lesson":"Fractal contribution planning now has a live cache loop. `FractalContributionCache` builds a resource plan from current summaries and cached states, stochastically observes only budgeted update nodes, updates estimator confidence, and lets Zyphos reuse compiled brush packets by selected-cut key instead of freezing the whole render plan by camera bucket. Static plan caches are not acceptable for stochastic LOD because they stop learning.","files":["src/Aquarium.Engine.Fractal/Lod/FractalContributionCache.cs","src/Aquarium.Zyphos/ZyphosFractalTerrain.cs","tests/Aquarium.Engine.Fractal.Tests/FractalContributionCacheTests.cs"],"source":"follow-up after resource observability revealed the old bucket plan cache prevented continual cache updates"}
{"timestamp":"2026-05-19T15:12:00+01:00","topic":"localcast-shared-temporal-reservoir","lesson":"LocalCast fallback GPU fusion history now delegates to `TemporalSpatialEvidenceReservoir`. `LocalCastGpuFusionAccumulator` maps LocalCast GPU fusion seeds into shared evidence observations and lowers reservoir samples back into `AquariumGpuFusionSeed`; it no longer owns separate stable-key history, smoothing, expiry, or max-count logic. This is the first consumer-side takeover of duplicated temporal reservoir code.","files":["src/Aquarium.LocalCast/LocalCastGpuFusionAccumulator.cs","src/Aquarium.Engine.Fractal/Temporal/TemporalSpatialEvidenceReservoir.cs","docs/temporal-sdf-gaussian-field.md"],"source":"user made Aquarium responsible for resolving temporal reservoir sampling architecturally and taking over consumer half-versions"}
{"timestamp":"2026-05-19T15:29:00+01:00","topic":"temporal-evidence-lowering-boundary","lesson":"Shared temporal evidence now has named lowering helpers. `TemporalSpatialEvidenceLowering` converts Gaussian observations and GPU fusion seeds to/from reservoir samples, so consumer adapters do not privately pack Payload0/Payload1 conventions. Keep new reservoir consumers on this lowering seam unless they need a genuinely new payload contract.","files":["src/Aquarium.Engine.Fractal/Temporal/TemporalSpatialEvidenceLowering.cs","src/Aquarium.Engine.Fractal/Temporal/TemporalGaussianAccumulator.cs","src/Aquarium.LocalCast/LocalCastGpuFusionAccumulator.cs","tests/Aquarium.Engine.Fractal.Tests/TemporalSpatialEvidenceLoweringTests.cs"],"source":"follow-up after moving LocalCast history onto the shared reservoir; adapter payload packing needed to become a tested engine boundary"}

View file

@ -82,6 +82,7 @@
"Aquarium's fractal renderer and Mimir-style sensor fusion share a deeper shape: both accumulate confidence-weighted spatial evidence into temporal reservoirs, then render a resolved surface/volume field. Keep the budget planner vocabulary general enough for CPU update work, GPU packet cost, RAM residency, and SSD request pressure; do not trap the future shared machinery inside renderer-only folklore.",
"Temporal Gaussian splats lower through TemporalSpatialEvidenceReservoir: stable keyed observations become delayed, smoothed, confidence-weighted tracks with velocity prediction, expiry, and max-track eviction before backend packet lowering. Treat Gaussian fields, fractal SDF probes, and Mimir sensor-fusion features as different evidence producers for this reservoir shape, not separate accumulator folklore.",
"LocalCastGpuFusionAccumulator must remain a thin adapter over TemporalSpatialEvidenceReservoir. LocalCast may own mapping from visual points/seeds into evidence payloads, but it must not grow a second stable-key history, smoothing, expiry, or sample-budget algorithm.",
"TemporalSpatialEvidenceLowering owns conversion between shared evidence samples and backend packets such as TemporalGaussianObservation, AquariumTemporalSdfGaussian, and AquariumGpuFusionSeed. Consumers should not pack Payload0/Payload1 by private convention when a lowering helper exists.",
"Zyphos fractal stress data should keep authored topology richer than the first renderer backend: both Zyphos and Umbros expose lat/long, surface, object-scale, and cube-tile domains in `.aquageo`, with explicit continent/forest/tree/leaf/coast/pebble and crater/boulder/pebble recursion. The current D3D12 height-field stress table uploads 64 shaped 2D brushes and the SDF planet shaders carry separate cheap bounded quadtree-style relief.",
"The `.aquageo` compiler must preserve each tile declaration as its own ownership-tree node. Collapsing every claim under the final tile makes the authored multi-domain world a lie even if the brush count looks impressive.",
"Zyphos passes cube-tile domain metadata through height brush packets and binds those packets into the SDF pass. The planet shader may use authored brush packets for post-hit material/detail evaluation; traced geometry must wait for selected-cut/resident packet policy so SDF distance loops do not evaluate every brush at every step.",

View file

@ -0,0 +1,85 @@
using System.Numerics;
using Aquarium.Engine.Fractal.Temporal;
using Aquarium.Engine.Render;
namespace Aquarium.Engine.Fractal.Tests;
public sealed class TemporalSpatialEvidenceLoweringTests
{
[Fact]
public void GaussianLoweringRoundTripsKernelPayload()
{
var observation = new TemporalGaussianObservation(
"gaussian/a",
Vector3.One,
new Vector3(0.2f, 0.3f, 0.4f),
Quaternion.Identity,
new Vector4(0.1f, 0.2f, 0.3f, 0.4f),
Confidence: 0.75f,
ObservedTimeSeconds: 12.0f,
Falloff: 5.0f,
ShapePower: 1.8f,
FieldId: 44);
var lowered = TemporalSpatialEvidenceLowering.FromGaussianObservation(observation);
var sample = new TemporalSpatialEvidenceSample(
lowered.StableKey,
lowered.Center,
lowered.Center,
Vector3.Zero,
lowered.Radii,
lowered.Orientation,
lowered.Payload0,
lowered.Payload1,
lowered.Confidence,
HistoryWeight: 0.6f,
lowered.ObservedTimeSeconds,
lowered.FieldId);
var gaussian = TemporalSpatialEvidenceLowering.ToTemporalGaussian(sample);
Assert.Equal(observation.StableKey, gaussian.StableKey);
Assert.Equal(observation.ColorOpacity, gaussian.ColorOpacity);
Assert.Equal(5.0f, gaussian.Falloff);
Assert.Equal(1.8f, gaussian.ShapePower);
Assert.Equal(44, gaussian.FieldId);
}
[Fact]
public void GpuFusionLoweringRoundTripsSeedPayload()
{
var seed = new AquariumGpuFusionSeed(
"fusion/a",
Vector3.One,
Vector3.Zero,
new Vector3(0.1f, 0.0f, 0.0f),
new Vector3(0.2f),
new Vector4(0.4f, 0.5f, 0.6f, 0.7f),
Confidence: 0.8f,
HistoryWeight: 0.65f,
Falloff: 4.4f,
ShapePower: 2.1f,
FieldId: 91);
var lowered = TemporalSpatialEvidenceLowering.FromGpuFusionSeed(seed, observedTimeSeconds: 3.0f);
var sample = new TemporalSpatialEvidenceSample(
lowered.StableKey,
lowered.Center,
seed.PreviousCenter,
seed.Velocity,
lowered.Radii,
lowered.Orientation,
lowered.Payload0,
lowered.Payload1,
lowered.Confidence,
lowered.Payload1.Z,
lowered.ObservedTimeSeconds,
lowered.FieldId);
var roundTrip = TemporalSpatialEvidenceLowering.ToGpuFusionSeed(sample);
Assert.Equal(seed.StableKey, roundTrip.StableKey);
Assert.Equal(seed.ColorOpacity, roundTrip.ColorOpacity);
Assert.Equal(seed.Falloff, roundTrip.Falloff);
Assert.Equal(seed.ShapePower, roundTrip.ShapePower);
Assert.Equal(seed.FieldId, roundTrip.FieldId);
}
}