Gaussian splats: the source
Open the live demo · Read the guide · View on GitHub
Regions the guide quotes: rows (line 44), decode (line 62), contributor (line 65), gpu (line 81), gpu-check (line 97), check (line 107), ply (line 121).
1/// A small Gaussian cloud, written to a binary PLY and read back the way a
2/// capture would arrive.
3library;
5import 'dart:convert';
6import 'dart:math' as math;
7import 'dart:typed_data';
9import 'package:flutter3d/flutter3d.dart';
10import 'package:flutter3d_core/flutter3d_core.dart' show splatShC0;
11import 'package:flutter3d_showcase/src/demo/demo.dart';
13typedef _SplatRow = ({
14 Vector3 position,
15 Vector3 color,
16 double opacity,
17 double scale,
18});
20/// The `gaussian-splats` page: a small Gaussian cloud written to binary PLY,
21/// read back and drawn. Its check is that the cloud is drawn, in GPU order
22/// exactly when the GPU sort is asked for and available.
23final class GaussianSplatsDemo extends ShowcaseDemo {
24 late final SplatCloud _cloud;
25 late final SplatContributor _contributor;
26 late final GraphicsDevice _device;
28 /// Whether the splats are sorted on the GPU where the device can; the CPU
29 /// sorts them otherwise.
30 bool gpuSort = true;
32 static const int _count = 35;
35 void configureView(DemoContext context) {
36 context.orbit
37 ..distance = 5.0
38 ..pitch = 0.18
39 ..yaw = 0.4;
40 }
43 Scene build(DemoContext context) {
44 final List<_SplatRow> rows = <_SplatRow>[
45 for (var i = 0; i < _count; i++)
46 (
47 position: Vector3(
48 (i % 7 - 3) * 0.5,
49 0.4 * math.sin(i * 0.6),
50 (i ~/ 7 - 2) * 0.5,
51 ),
52 color: Vector3(
53 0.3 + 0.5 * (i / _count),
54 0.4,
55 0.9 - 0.5 * (i / _count),
56 ),
57 opacity: 0.85,
58 scale: 0.16,
59 ),
60 ];
62 final Uint8List bytes = _splatPlyBytes(rows);
63 _cloud = parseSplatPly(bytes);
65 _contributor = SplatContributor(_cloud);
66 context.renderer.renderSteps.addContributor(_contributor);
67 _device = context.device;
69 final Scene scene = Scene()
70 ..ambientColor = LinearColor(0.4, 0.46, 0.6)
71 ..ambientIntensity = 0.24 * LightNode.legacyUnit
72 ..add(
73 LightNode(name: 'key', intensity: 1.2 * LightNode.legacyUnit)
74 ..setLocalForward(Vector3(-0.4, -0.7, -0.5)),
75 );
76 return scene;
77 }
80 void update(DemoContext context, double dt) {
81 // On by default: the device sorts where it can compute, the CPU
82 // everywhere else. Off sorts on the CPU even where the device could.
83 _contributor.gpuSort = gpuSort;
84 }
87 List<DemoControl> controls(DemoContext context) => <DemoControl>[
88 ToggleControl(
89 'GPU sort',
90 value: () => gpuSort,
91 onChanged: (bool v) => gpuSort = v,
92 ),
93 ];
96 void verify(Scene scene, FrameResult frame) {
97 // The cloud was drawn in the GPU's order exactly when the toggle is on
98 // and this device can run the sort: never on the software device, which
99 // has no compute.
100 final bool gpuExpected = gpuSort && SplatGpuSort.availableOn(_device);
101 if (_contributor.didDrawGpuOrder != gpuExpected) {
102 throw StateError(
103 'drew in the GPU order: ${_contributor.didDrawGpuOrder}, '
104 'expected $gpuExpected',
105 );
106 }
107 final Int32List order = _cloud.sortedBackToFront(
108 Vector3(0.0, 0.0, -5.0),
109 Vector3(0.0, 0.0, 1.0),
110 );
111 final Set<int> seen = order.toSet();
112 if (_cloud.count != _count ||
113 seen.length != _count ||
114 !_contributor.isActive ||
115 frame.drawCalls < 1) {
116 throw StateError('the splat cloud was not decoded and drawn');
117 }
118 }
119}
121/// A binary PLY holding [rows], in exactly the properties `parseSplatPly`
122/// requires: `x y z`, `f_dc_0..2`, `opacity`, `scale_0..2`, `rot_0..3`.
123Uint8List _splatPlyBytes(List<_SplatRow> rows) {
124 const List<String> properties = <String>[
125 'x',
126 'y',
127 'z',
128 'f_dc_0',
129 'f_dc_1',
130 'f_dc_2',
131 'opacity',
132 'scale_0',
133 'scale_1',
134 'scale_2',
135 'rot_0',
136 'rot_1',
137 'rot_2',
138 'rot_3',
139 ];
140 final StringBuffer header = StringBuffer()
141 ..writeln('ply')
142 ..writeln('format binary_little_endian 1.0')
143 ..writeln('element vertex ${rows.length}');
144 for (final String name in properties) {
145 header.writeln('property float $name');
146 }
147 header.writeln('end_header');
148 final List<int> headerBytes = ascii.encode(header.toString());
150 final ByteData body = ByteData(rows.length * properties.length * 4);
151 var offset = 0;
152 // The inverse of `splatChannel` and `splatOpacity`: a readable 0..1 colour
153 // and probability, converted back to the coefficient and the logit the
154 // file stores.
155 double coefficientFor(double channel01) => (channel01 - 0.5) / splatShC0;
156 double logitFor(double probability) =>
157 math.log(probability / (1.0 - probability));
158 void writeFloat(double value) {
159 body.setFloat32(offset, value, Endian.little);
160 offset += 4;
161 }
163 for (final _SplatRow row in rows) {
164 writeFloat(row.position.x);
165 writeFloat(row.position.y);
166 writeFloat(row.position.z);
167 writeFloat(coefficientFor(row.color.x));
168 writeFloat(coefficientFor(row.color.y));
169 writeFloat(coefficientFor(row.color.z));
170 writeFloat(logitFor(row.opacity));
171 writeFloat(math.log(row.scale));
172 writeFloat(math.log(row.scale));
173 writeFloat(math.log(row.scale));
174 // rot_0..3 is w, x, y, z in the file's own order; the identity rotation
175 // leaves every ellipsoid axis-aligned.
176 writeFloat(1.0);
177 writeFloat(0.0);
178 writeFloat(0.0);
179 writeFloat(0.0);
180 }
182 final Uint8List result = Uint8List(headerBytes.length + body.lengthInBytes);
183 result.setRange(0, headerBytes.length, headerBytes);
184 result.setRange(headerBytes.length, result.length, body.buffer.asUint8List());
185 return result;
186}