oda-engine 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (204) hide show
  1. package/README.md +151 -2
  2. package/bin/nowhere.mjs +352 -0
  3. package/lib/account.mjs +57 -0
  4. package/lib/agentModules.mjs +57 -0
  5. package/lib/devServer.mjs +351 -0
  6. package/lib/headless.mjs +231 -0
  7. package/lib/headlessPreview.mjs +212 -0
  8. package/lib/keys.mjs +517 -0
  9. package/lib/make.mjs +855 -0
  10. package/lib/mcp.mjs +537 -0
  11. package/lib/open.mjs +22 -0
  12. package/lib/preview.mjs +87 -0
  13. package/lib/previewRpc.mjs +134 -0
  14. package/lib/project.mjs +359 -0
  15. package/lib/publishFlow.mjs +90 -0
  16. package/lib/resources.mjs +50 -0
  17. package/lib/rules.mjs +60 -0
  18. package/lib/scaffold.mjs +42 -0
  19. package/lib/setup.mjs +59 -0
  20. package/lib/tools.mjs +668 -0
  21. package/package.json +51 -4
  22. package/template/game.config.json +9 -0
  23. package/template/scene.json +4 -0
  24. package/template/src/main.ts +11 -0
  25. package/vendor/DOCS.md +447 -0
  26. package/vendor/agent/appRun.mjs +520 -0
  27. package/vendor/agent/assets/brief.mjs +242 -0
  28. package/vendor/agent/assets/collider.mjs +531 -0
  29. package/vendor/agent/assets/environments/index.mjs +12 -0
  30. package/vendor/agent/assets/environments/worldlabs.mjs +161 -0
  31. package/vendor/agent/assets/fetch.mjs +168 -0
  32. package/vendor/agent/assets/footprint.mjs +13 -0
  33. package/vendor/agent/assets/gltf.mjs +547 -0
  34. package/vendor/agent/assets/hdr.mjs +269 -0
  35. package/vendor/agent/assets/imageOps.mjs +171 -0
  36. package/vendor/agent/assets/images/codex.mjs +307 -0
  37. package/vendor/agent/assets/images/fal.mjs +75 -0
  38. package/vendor/agent/assets/images/gemini.mjs +84 -0
  39. package/vendor/agent/assets/images/index.mjs +25 -0
  40. package/vendor/agent/assets/images/openai.mjs +75 -0
  41. package/vendor/agent/assets/images/stability.mjs +71 -0
  42. package/vendor/agent/assets/images/views.mjs +31 -0
  43. package/vendor/agent/assets/import.mjs +1352 -0
  44. package/vendor/agent/assets/inspect.mjs +465 -0
  45. package/vendor/agent/assets/jobs.mjs +196 -0
  46. package/vendor/agent/assets/ktx2.mjs +290 -0
  47. package/vendor/agent/assets/ledger.mjs +466 -0
  48. package/vendor/agent/assets/net.mjs +254 -0
  49. package/vendor/agent/assets/prices.json +39 -0
  50. package/vendor/agent/assets/providers/fal.mjs +115 -0
  51. package/vendor/agent/assets/providers/index.mjs +22 -0
  52. package/vendor/agent/assets/providers/meshy.mjs +119 -0
  53. package/vendor/agent/assets/providers/tripo.mjs +188 -0
  54. package/vendor/agent/assets/sources/ambientcg.mjs +129 -0
  55. package/vendor/agent/assets/sources/index.mjs +23 -0
  56. package/vendor/agent/assets/sources/polyhaven.mjs +237 -0
  57. package/vendor/agent/assets/sources/polypizza.mjs +121 -0
  58. package/vendor/agent/assets/splat.mjs +631 -0
  59. package/vendor/agent/assets/targets.mjs +122 -0
  60. package/vendor/agent/assets/tile.mjs +261 -0
  61. package/vendor/agent/assets/unzip.mjs +180 -0
  62. package/vendor/agent/blender/cleanup.py +360 -0
  63. package/vendor/agent/blender/convert.py +167 -0
  64. package/vendor/agent/blender/find.mjs +192 -0
  65. package/vendor/agent/blender/nw_export.py +104 -0
  66. package/vendor/agent/blender/nw_rubric.py +426 -0
  67. package/vendor/agent/blender/run.mjs +193 -0
  68. package/vendor/agent/blender/runner.py +252 -0
  69. package/vendor/agent/blender/sheet.py +743 -0
  70. package/vendor/agent/depth.mjs +134 -0
  71. package/vendor/agent/director/board.mjs +451 -0
  72. package/vendor/agent/director/contracts.mjs +663 -0
  73. package/vendor/agent/director/director.mjs +2365 -0
  74. package/vendor/agent/director/estimate.mjs +200 -0
  75. package/vendor/agent/director/gate.mjs +802 -0
  76. package/vendor/agent/director/limits.json +16 -0
  77. package/vendor/agent/director/methods.mjs +457 -0
  78. package/vendor/agent/director/policy.json +33 -0
  79. package/vendor/agent/director/prompts.mjs +244 -0
  80. package/vendor/agent/director/reading.mjs +341 -0
  81. package/vendor/agent/director/router.mjs +184 -0
  82. package/vendor/agent/director/seams.mjs +243 -0
  83. package/vendor/agent/director/session.mjs +643 -0
  84. package/vendor/agent/director/store.mjs +119 -0
  85. package/vendor/agent/director/taskGate.mjs +110 -0
  86. package/vendor/agent/director/teamLedger.mjs +118 -0
  87. package/vendor/agent/director/triage.mjs +63 -0
  88. package/vendor/agent/downloads.cjs +363 -0
  89. package/vendor/agent/flow.mjs +78 -0
  90. package/vendor/agent/guard.mjs +613 -0
  91. package/vendor/agent/host.mjs +1736 -0
  92. package/vendor/agent/language.mjs +58 -0
  93. package/vendor/agent/ledger.mjs +360 -0
  94. package/vendor/agent/locale.cjs +186 -0
  95. package/vendor/agent/loop/capacity.mjs +74 -0
  96. package/vendor/agent/loop/compose.mjs +127 -0
  97. package/vendor/agent/loop/gate.mjs +205 -0
  98. package/vendor/agent/loop/judge.mjs +189 -0
  99. package/vendor/agent/loop/levels.mjs +273 -0
  100. package/vendor/agent/loop/state.mjs +358 -0
  101. package/vendor/agent/notes.cjs +278 -0
  102. package/vendor/agent/pace.mjs +258 -0
  103. package/vendor/agent/panels.mjs +431 -0
  104. package/vendor/agent/prompt.mjs +342 -0
  105. package/vendor/agent/reference/board.mjs +410 -0
  106. package/vendor/agent/reference/compose.mjs +364 -0
  107. package/vendor/agent/reference/decode.mjs +56 -0
  108. package/vendor/agent/reference/facts.mjs +1874 -0
  109. package/vendor/agent/reference/png.mjs +107 -0
  110. package/vendor/agent/reference/records.mjs +63 -0
  111. package/vendor/agent/reference/web.mjs +252 -0
  112. package/vendor/agent/roles/artist.mjs +69 -0
  113. package/vendor/agent/roles/builder.mjs +79 -0
  114. package/vendor/agent/roles/checks.mjs +223 -0
  115. package/vendor/agent/roles/common.mjs +188 -0
  116. package/vendor/agent/roles/critic.mjs +171 -0
  117. package/vendor/agent/roles/index.mjs +39 -0
  118. package/vendor/agent/roles/modeller.mjs +142 -0
  119. package/vendor/agent/roles/qa.mjs +58 -0
  120. package/vendor/agent/roles/rubrics.mjs +79 -0
  121. package/vendor/agent/roles/sound.mjs +69 -0
  122. package/vendor/agent/rounds.cjs +333 -0
  123. package/vendor/agent/shared.mjs +284 -0
  124. package/vendor/agent/stopGate.mjs +574 -0
  125. package/vendor/agent/subagents.mjs +129 -0
  126. package/vendor/agent/tools/assets.mjs +499 -0
  127. package/vendor/agent/tools/blender.mjs +754 -0
  128. package/vendor/agent/tools/cards.mjs +479 -0
  129. package/vendor/agent/tools/choices.mjs +479 -0
  130. package/vendor/agent/tools/compose.mjs +74 -0
  131. package/vendor/agent/tools/environment.mjs +488 -0
  132. package/vendor/agent/tools/eyes.mjs +733 -0
  133. package/vendor/agent/tools/generate.mjs +338 -0
  134. package/vendor/agent/tools/guide.mjs +46 -0
  135. package/vendor/agent/tools/harness.mjs +193 -0
  136. package/vendor/agent/tools/image.mjs +643 -0
  137. package/vendor/agent/tools/index.mjs +162 -0
  138. package/vendor/agent/tools/look.mjs +578 -0
  139. package/vendor/agent/tools/loop.mjs +858 -0
  140. package/vendor/agent/tools/others.mjs +123 -0
  141. package/vendor/agent/tools/pictures.mjs +535 -0
  142. package/vendor/agent/tools/reference.mjs +366 -0
  143. package/vendor/agent/transcripts.mjs +118 -0
  144. package/vendor/agent-loop.mjs +602 -0
  145. package/vendor/agent-plugin/.claude-plugin/plugin.json +5 -0
  146. package/vendor/agent-plugin/skills/art-direction/SKILL.md +82 -0
  147. package/vendor/agent-plugin/skills/asset-legality/SKILL.md +101 -0
  148. package/vendor/agent-plugin/skills/asset-sources/SKILL.md +111 -0
  149. package/vendor/agent-plugin/skills/blender-modeling/SKILL.md +97 -0
  150. package/vendor/agent-plugin/skills/look-dev/SKILL.md +104 -0
  151. package/vendor/agent-plugin/skills/playtesting/SKILL.md +74 -0
  152. package/vendor/agent-plugin/skills/reference-loop/SKILL.md +102 -0
  153. package/vendor/agent-plugin/skills/sound-design/SKILL.md +60 -0
  154. package/vendor/agent-plugin/skills/style/SKILL.md +35 -0
  155. package/vendor/agent-plugin/skills/tsl-r185/SKILL.md +107 -0
  156. package/vendor/auth.cjs +570 -0
  157. package/vendor/build.cjs +953 -0
  158. package/vendor/catalog.json +455 -0
  159. package/vendor/connectors.cjs +688 -0
  160. package/vendor/eyes.mjs +733 -0
  161. package/vendor/gameExports.json +1390 -0
  162. package/vendor/git.cjs +222 -0
  163. package/vendor/models.json +57 -0
  164. package/vendor/publish.cjs +1018 -0
  165. package/vendor/refBoard.cjs +301 -0
  166. package/vendor/schema/dist/assets.d.ts +335 -0
  167. package/vendor/schema/dist/assets.js +439 -0
  168. package/vendor/schema/dist/brief.d.ts +357 -0
  169. package/vendor/schema/dist/brief.js +302 -0
  170. package/vendor/schema/dist/common.d.ts +9 -0
  171. package/vendor/schema/dist/common.js +13 -0
  172. package/vendor/schema/dist/config.d.ts +406 -0
  173. package/vendor/schema/dist/config.js +355 -0
  174. package/vendor/schema/dist/contract.d.ts +599 -0
  175. package/vendor/schema/dist/contract.js +1146 -0
  176. package/vendor/schema/dist/index.d.ts +14 -0
  177. package/vendor/schema/dist/index.js +21 -0
  178. package/vendor/schema/dist/look.d.ts +463 -0
  179. package/vendor/schema/dist/look.js +681 -0
  180. package/vendor/schema/dist/lookStats.d.ts +230 -0
  181. package/vendor/schema/dist/lookStats.js +768 -0
  182. package/vendor/schema/dist/pilot.d.ts +32 -0
  183. package/vendor/schema/dist/pilot.js +44 -0
  184. package/vendor/schema/dist/publish.d.ts +214 -0
  185. package/vendor/schema/dist/publish.js +291 -0
  186. package/vendor/schema/dist/scene.d.ts +75 -0
  187. package/vendor/schema/dist/scene.js +120 -0
  188. package/vendor/schema/dist/skyLight.d.ts +141 -0
  189. package/vendor/schema/dist/skyLight.js +436 -0
  190. package/vendor/schema/dist/style.d.ts +131 -0
  191. package/vendor/schema/dist/style.js +155 -0
  192. package/vendor/schema/package.json +1 -0
  193. package/vendor/selectionPrompt.mjs +51 -0
  194. package/vendor/useTools.mjs +195 -0
  195. package/vendor/userMessage.mjs +26 -0
  196. package/web-dist/assets/GaussianSplatUtils-CB77cP9U.js +1 -0
  197. package/web-dist/assets/KTX2Loader-6OIWUF7s.js +2 -0
  198. package/web-dist/assets/SPZLoader-zYj0Alfv.js +1 -0
  199. package/web-dist/assets/gaussianSplat-CJTI1sEh.js +1 -0
  200. package/web-dist/assets/index-CcjyyQco.css +1 -0
  201. package/web-dist/assets/index-DMyJcoZJ.js +693 -0
  202. package/web-dist/assets/meshopt_decoder.module-BvwdjiD3.js +1 -0
  203. package/web-dist/assets/zstddec.module-CfFeQW7d.js +1 -0
  204. package/web-dist/index.html +34 -0
@@ -0,0 +1,631 @@
1
+ // Gaussian splats in and out of the one format a planet carries: .spz,
2
+ // version 3, gzip. Pure JavaScript (node's zlib for gzip and zstd), so it runs
3
+ // in the studio, the CLI and the checks alike, with nothing to download.
4
+ //
5
+ // readSplat(bytes, name) .spz (versions 1 to 4), a 3DGS .ply (binary, as
6
+ // the INRIA trainer, Polycam, Scaniverse, Luma and
7
+ // World Labs write it) or an antimatter15 .splat,
8
+ // into one plain form (below)
9
+ // transformSplat(s, t) into metres, ground at y = 0, y up: a scale, a
10
+ // half turn about x (OpenCV's y-down frame, which
11
+ // most captures, World Labs and three's own
12
+ // examples use) and an offset, baked in so the
13
+ // splat and its collider sit where they are drawn
14
+ // encodeSpz(s) the planet's .spz: version 3 and gzip, which
15
+ // three's SPZLoader reads with fflate, never the
16
+ // zstd of version 4, whose decoder is WebAssembly
17
+ // a planet page may not run
18
+ // splatStats(s) count, bounds, where the floor seems to be
19
+ //
20
+ // The plain form, every array per splat in file order:
21
+ // count, shDegree (0 to 3), antialiased
22
+ // positions Float32Array(count * 3)
23
+ // scales Float32Array(count * 3) log of the radius, as 3DGS keeps it
24
+ // rotations Float32Array(count * 4) x, y, z, w, unit, w >= 0
25
+ // alphas Float32Array(count) opacity 0..1 (after the sigmoid)
26
+ // colors Float32Array(count * 3) the 0th SH coefficient (f_dc)
27
+ // sh Float32Array(count * N*3) the rest, N = 3, 8 or 15 per degree,
28
+ // each coefficient's r, g, b together, as .spz and three keep
29
+ // them (a .ply keeps each channel's run apart)
30
+ //
31
+ // The SPZ layout is Niantic's (github.com/nianticlabs/spz), checked against
32
+ // three r186's SPZLoader, which is what draws it: a file written here and read
33
+ // by that loader gives the same splats it would from the original.
34
+
35
+ import zlib from 'node:zlib'
36
+ import { createRequire } from 'node:module'
37
+ import { pathToFileURL } from 'node:url'
38
+
39
+ export const SPZ_MAGIC = 0x5053474e
40
+ const SPZ_HEADER = 16
41
+ const SH_DIM = [0, 3, 8, 15]
42
+ /** Niantic's colour scale: an SPZ colour byte holds f_dc * 0.15 + 0.5. */
43
+ const COLOR_SCALE = 0.15
44
+ const SH_C0 = 0.28209479177387814
45
+ const FLAG_ANTIALIASED = 0x1
46
+ const FLAG_LOD = 0x80
47
+ /** What one decompressed file may grow to, so a gzip bomb stops early:
48
+ * 3 million splats of degree 3 are 195 MB. */
49
+ const MAX_RAW = 512 * 1024 * 1024
50
+
51
+ const sigmoid = (x) => 1 / (1 + Math.exp(-x))
52
+
53
+ function empty(count, shDegree) {
54
+ return {
55
+ count,
56
+ shDegree,
57
+ antialiased: false,
58
+ positions: new Float32Array(count * 3),
59
+ scales: new Float32Array(count * 3),
60
+ rotations: new Float32Array(count * 4),
61
+ alphas: new Float32Array(count),
62
+ colors: new Float32Array(count * 3),
63
+ sh: new Float32Array(count * SH_DIM[shDegree] * 3),
64
+ }
65
+ }
66
+
67
+ /** A unit quaternion with w >= 0, in place at offset o. A zero one is the
68
+ * identity. */
69
+ function normalizeQuat(q, o) {
70
+ let x = q[o]
71
+ let y = q[o + 1]
72
+ let z = q[o + 2]
73
+ let w = q[o + 3]
74
+ const len = Math.hypot(x, y, z, w)
75
+ if (!(len > 1e-12) || !Number.isFinite(len)) {
76
+ q[o] = 0
77
+ q[o + 1] = 0
78
+ q[o + 2] = 0
79
+ q[o + 3] = 1
80
+ return
81
+ }
82
+ const s = (w < 0 ? -1 : 1) / len
83
+ x *= s
84
+ y *= s
85
+ z *= s
86
+ w *= s
87
+ q[o] = x
88
+ q[o + 1] = y
89
+ q[o + 2] = z
90
+ q[o + 3] = w
91
+ }
92
+
93
+ // ---------------------------------------------------------------- .spz in
94
+
95
+ let zstdFallback = null
96
+ /** zstd for version 4: node's own (22.15 and later), else three's decoder
97
+ * (WebAssembly, fine here in node; never on a planet page). */
98
+ async function zstdDecode(compressed, size) {
99
+ if (typeof zlib.zstdDecompressSync === 'function') {
100
+ const out = zlib.zstdDecompressSync(compressed, { maxOutputLength: Math.max(size, 1) })
101
+ return new Uint8Array(out.buffer, out.byteOffset, out.byteLength)
102
+ }
103
+ zstdFallback ??= (async () => {
104
+ const require = createRequire(import.meta.url)
105
+ let file
106
+ try {
107
+ file = require.resolve('three/examples/jsm/libs/zstddec.module.js')
108
+ } catch {
109
+ // The npm CLI carries no three of its own: say what to do, not which
110
+ // module was missing.
111
+ throw new Error(`a version 4 SPZ (zstd inside) needs Node 22.15 or later to be read here, and this is Node ${process.versions.node}. Update Node, or export the splat as SPZ version 3 or as a .ply`)
112
+ }
113
+ const { ZSTDDecoder } = await import(pathToFileURL(file).href)
114
+ const decoder = new ZSTDDecoder()
115
+ await decoder.init()
116
+ return decoder
117
+ })()
118
+ return (await zstdFallback).decode(compressed, size)
119
+ }
120
+
121
+ function readInt24(b, o) {
122
+ return ((b[o] << 8) | (b[o + 1] << 16) | (b[o + 2] << 24)) >> 8
123
+ }
124
+
125
+ function halfToFloat(h) {
126
+ const s = h & 0x8000 ? -1 : 1
127
+ const e = (h >> 10) & 0x1f
128
+ const f = h & 0x3ff
129
+ if (e === 0) return s * 2 ** -14 * (f / 1024)
130
+ if (e === 31) return f ? NaN : s * Infinity
131
+ return s * 2 ** (e - 15) * (1 + f / 1024)
132
+ }
133
+
134
+ function fromSpzStreams({ count, version, shDegree, fractionalBits, flags, positions, alphas, colors, scales, rotations, sh }) {
135
+ const out = empty(count, shDegree)
136
+ out.antialiased = (flags & FLAG_ANTIALIASED) !== 0
137
+ const fixed = 1 / (1 << fractionalBits)
138
+ for (let i = 0; i < count; i++) {
139
+ const i3 = i * 3
140
+ if (version === 1) {
141
+ const r = i * 6
142
+ out.positions[i3] = halfToFloat(positions[r] | (positions[r + 1] << 8))
143
+ out.positions[i3 + 1] = halfToFloat(positions[r + 2] | (positions[r + 3] << 8))
144
+ out.positions[i3 + 2] = halfToFloat(positions[r + 4] | (positions[r + 5] << 8))
145
+ } else {
146
+ const r = i * 9
147
+ out.positions[i3] = readInt24(positions, r) * fixed
148
+ out.positions[i3 + 1] = readInt24(positions, r + 3) * fixed
149
+ out.positions[i3 + 2] = readInt24(positions, r + 6) * fixed
150
+ }
151
+ out.alphas[i] = alphas[i] / 255
152
+ for (let c = 0; c < 3; c++) {
153
+ out.colors[i3 + c] = (colors[i3 + c] / 255 - 0.5) / COLOR_SCALE
154
+ out.scales[i3 + c] = scales[i3 + c] / 16 - 10
155
+ }
156
+ const q = out.rotations
157
+ const i4 = i * 4
158
+ if (version >= 3) {
159
+ const packed = (rotations[i4] | (rotations[i4 + 1] << 8) | (rotations[i4 + 2] << 16) | (rotations[i4 + 3] << 24)) >>> 0
160
+ const largest = packed >>> 30
161
+ let rest = packed
162
+ let sum = 0
163
+ // The low ten bits are the highest remaining index, the top ten the lowest.
164
+ for (let k = 3; k >= 0; k--) {
165
+ if (k === largest) continue
166
+ const v = rest & 1023
167
+ rest = Math.floor(rest / 1024)
168
+ const mag = Math.SQRT1_2 * ((v & 511) / 511)
169
+ const value = v & 512 ? -mag : mag
170
+ q[i4 + k] = value
171
+ sum += value * value
172
+ }
173
+ q[i4 + largest] = Math.sqrt(Math.max(0, 1 - sum))
174
+ } else {
175
+ const x = rotations[i3] / 127.5 - 1
176
+ const y = rotations[i3 + 1] / 127.5 - 1
177
+ const z = rotations[i3 + 2] / 127.5 - 1
178
+ q[i4] = x
179
+ q[i4 + 1] = y
180
+ q[i4 + 2] = z
181
+ q[i4 + 3] = Math.sqrt(Math.max(0, 1 - x * x - y * y - z * z))
182
+ }
183
+ normalizeQuat(q, i4)
184
+ }
185
+ const n = out.sh.length
186
+ for (let k = 0; k < n; k++) out.sh[k] = (sh[k] - 128) / 128
187
+ return out
188
+ }
189
+
190
+ /** One .spz file (any version three reads: 1, 2, 3 under gzip, 4 under zstd). */
191
+ export async function readSpz(bytes) {
192
+ const buf = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)
193
+ const head = new DataView(buf.buffer, buf.byteOffset, buf.byteLength)
194
+ if (buf.byteLength >= 20 && head.getUint32(0, true) === SPZ_MAGIC) {
195
+ const version = head.getUint32(4, true)
196
+ if (version !== 4) throw new Error(`it is an uncompressed SPZ of version ${version}, which nothing writes`)
197
+ const count = head.getUint32(8, true)
198
+ const storedDegree = head.getUint8(12)
199
+ if (storedDegree > 3) throw new Error(`its colour detail is of degree ${storedDegree}; three draws up to 3`)
200
+ const fractionalBits = head.getUint8(13)
201
+ const flags = head.getUint8(14)
202
+ const numStreams = head.getUint8(15)
203
+ const toc = head.getUint32(16, true)
204
+ const shSize = count * SH_DIM[storedDegree] * 3
205
+ const sizes = [count * 9, count, count * 3, count * 3, count * 4, shSize]
206
+ if (sizes.reduce((a, b) => a + b, 0) > MAX_RAW) throw new Error(`it holds ${count.toLocaleString('en-US')} splats, far more than a planet can draw`)
207
+ let at = toc + numStreams * 16
208
+ let entry = 0
209
+ const streams = []
210
+ for (const size of sizes) {
211
+ if (size === 0) {
212
+ streams.push(new Uint8Array(0))
213
+ continue
214
+ }
215
+ if (entry >= numStreams) throw new Error('it has fewer streams than its header says')
216
+ const compressed = Number(head.getBigUint64(toc + entry * 16, true))
217
+ entry++
218
+ if (at + compressed > buf.byteLength) throw new Error('it ends early')
219
+ const raw = await zstdDecode(buf.subarray(at, at + compressed), size)
220
+ if (raw.byteLength !== size) throw new Error('a stream is not the size its header says')
221
+ streams.push(raw)
222
+ at += compressed
223
+ }
224
+ const [positions, alphas, colors, scales, rotations, sh] = streams
225
+ return fromSpzStreams({ count, version: 4, shDegree: storedDegree, fractionalBits, flags, positions, alphas, colors, scales, rotations, sh })
226
+ }
227
+ let raw
228
+ try {
229
+ raw = zlib.gunzipSync(buf, { maxOutputLength: MAX_RAW })
230
+ } catch (err) {
231
+ throw new Error(`it is not a gzip SPZ (${err?.code === 'ERR_BUFFER_TOO_LARGE' ? 'it unpacks to more than a planet can draw' : (err?.message ?? err)})`)
232
+ }
233
+ const b = new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength)
234
+ if (b.byteLength < SPZ_HEADER) throw new Error('it is shorter than its header')
235
+ const v = new DataView(b.buffer, b.byteOffset, b.byteLength)
236
+ if (v.getUint32(0, true) !== SPZ_MAGIC) throw new Error('it is not an SPZ (no NGSP mark)')
237
+ const version = v.getUint32(4, true)
238
+ if (version < 1 || version > 3) throw new Error(`SPZ version ${version} is not one three reads`)
239
+ const count = v.getUint32(8, true)
240
+ const shDegree = v.getUint8(12)
241
+ if (shDegree > 3) throw new Error(`its colour detail is of degree ${shDegree}; three draws up to 3`)
242
+ const fractionalBits = v.getUint8(13)
243
+ const flags = v.getUint8(14)
244
+ const posSize = count * 3 * (version === 1 ? 2 : 3)
245
+ const rotSize = count * (version === 3 ? 4 : 3)
246
+ const shSize = count * SH_DIM[shDegree] * 3
247
+ const lodSize = flags & FLAG_LOD ? count * 6 : 0
248
+ const expected = SPZ_HEADER + posSize + count + count * 3 + count * 3 + rotSize + shSize + lodSize
249
+ if (b.byteLength !== expected) throw new Error(`its length (${b.byteLength}) does not match its ${count} splats (${expected})`)
250
+ let o = SPZ_HEADER
251
+ const take = (n) => {
252
+ const s = b.subarray(o, o + n)
253
+ o += n
254
+ return s
255
+ }
256
+ const positions = take(posSize)
257
+ const alphas = take(count)
258
+ const colors = take(count * 3)
259
+ const scales = take(count * 3)
260
+ const rotations = take(rotSize)
261
+ const sh = take(shSize)
262
+ return fromSpzStreams({ count, version, shDegree, fractionalBits, flags, positions, alphas, colors, scales, rotations, sh })
263
+ }
264
+
265
+ // ---------------------------------------------------------------- .ply in
266
+
267
+ const PLY_TYPES = {
268
+ char: ['getInt8', 1],
269
+ int8: ['getInt8', 1],
270
+ uchar: ['getUint8', 1],
271
+ uint8: ['getUint8', 1],
272
+ short: ['getInt16', 2],
273
+ int16: ['getInt16', 2],
274
+ ushort: ['getUint16', 2],
275
+ uint16: ['getUint16', 2],
276
+ int: ['getInt32', 4],
277
+ int32: ['getInt32', 4],
278
+ uint: ['getUint32', 4],
279
+ uint32: ['getUint32', 4],
280
+ float: ['getFloat32', 4],
281
+ float32: ['getFloat32', 4],
282
+ double: ['getFloat64', 8],
283
+ float64: ['getFloat64', 8],
284
+ }
285
+
286
+ /** A 3DGS .ply: binary little-endian, one vertex element with x, y, z,
287
+ * f_dc_0..2, opacity (logit), scale_0..2 (log), rot_0..3 (w first) and
288
+ * f_rest_* (0, 9, 24 or 45 of them). Other elements are skipped by size. */
289
+ export function readPly(bytes) {
290
+ const buf = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)
291
+ const headEnd = (() => {
292
+ const limit = Math.min(buf.byteLength, 64 * 1024)
293
+ const text = Buffer.from(buf.buffer, buf.byteOffset, limit).toString('latin1')
294
+ const m = /end_header\r?\n/.exec(text)
295
+ return m ? { text: text.slice(0, m.index), offset: m.index + m[0].length } : null
296
+ })()
297
+ if (!headEnd || !headEnd.text.startsWith('ply')) throw new Error('it is not a PLY file (no header)')
298
+ const lines = headEnd.text.split(/\r?\n/).map((l) => l.trim())
299
+ const format = lines.find((l) => l.startsWith('format '))
300
+ if (!format) throw new Error('its header has no format line')
301
+ if (!/^format binary_little_endian 1\.0$/.test(format)) {
302
+ throw new Error(`it is ${format.slice(7)}; splat PLY files are binary_little_endian (export it again as a binary PLY)`)
303
+ }
304
+ const elements = []
305
+ for (const l of lines) {
306
+ const p = l.split(/\s+/)
307
+ if (p[0] === 'element') elements.push({ name: p[1], count: Number(p[2]), props: [] })
308
+ else if (p[0] === 'property') {
309
+ const el = elements[elements.length - 1]
310
+ if (!el) throw new Error('a property comes before any element')
311
+ if (p[1] === 'list') throw new Error(`its ${el.name} element has a list property; a splat PLY has none`)
312
+ const type = PLY_TYPES[p[1]]
313
+ if (!type) throw new Error(`its property type ${p[1]} is not one PLY has`)
314
+ el.props.push({ name: p[2], get: type[0], size: type[1] })
315
+ }
316
+ }
317
+ const vertex = elements.find((e) => e.name === 'vertex')
318
+ if (!vertex) throw new Error('it has no vertex element')
319
+ const names = new Map(vertex.props.map((p, i) => [p.name, i]))
320
+ const need = ['x', 'y', 'z', 'f_dc_0', 'f_dc_1', 'f_dc_2', 'opacity', 'scale_0', 'scale_1', 'scale_2', 'rot_0', 'rot_1', 'rot_2', 'rot_3']
321
+ const missing = need.filter((n) => !names.has(n))
322
+ if (missing.length) {
323
+ const compressed = elements.some((e) => e.name === 'chunk')
324
+ throw new Error(
325
+ compressed
326
+ ? 'it is a compressed PLY (SuperSplat or PlayCanvas chunks); export it as an uncompressed PLY or an .spz'
327
+ : `it is not a Gaussian splat PLY: it has no ${missing.slice(0, 4).join(', ')} (a mesh or a point cloud, not splats)`,
328
+ )
329
+ }
330
+ let rest = 0
331
+ while (names.has(`f_rest_${rest}`)) rest++
332
+ const shDegree = [0, 9, 24, 45].indexOf(rest)
333
+ if (shDegree < 0) throw new Error(`it has ${rest} f_rest values; 0, 9, 24 or 45 is a splat's colour detail`)
334
+ const count = vertex.count
335
+ if (!Number.isInteger(count) || count < 1) throw new Error('its vertex count is not a number')
336
+ // Where the vertex element starts: after every element written before it.
337
+ let offset = headEnd.offset
338
+ for (const e of elements) {
339
+ if (e === vertex) break
340
+ offset += e.count * e.props.reduce((n, p) => n + p.size, 0)
341
+ }
342
+ const stride = vertex.props.reduce((n, p) => n + p.size, 0)
343
+ if (offset + stride * count > buf.byteLength) throw new Error('it ends before its last splat')
344
+ const at = []
345
+ let o = 0
346
+ for (const p of vertex.props) {
347
+ at.push(o)
348
+ o += p.size
349
+ }
350
+ const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength)
351
+ const read = (row, name) => {
352
+ const i = names.get(name)
353
+ const p = vertex.props[i]
354
+ return view[p.get](row + at[i], true)
355
+ }
356
+ const out = empty(count, shDegree)
357
+ const dim = SH_DIM[shDegree]
358
+ for (let i = 0; i < count; i++) {
359
+ const row = offset + i * stride
360
+ const i3 = i * 3
361
+ const i4 = i * 4
362
+ out.positions[i3] = read(row, 'x')
363
+ out.positions[i3 + 1] = read(row, 'y')
364
+ out.positions[i3 + 2] = read(row, 'z')
365
+ out.colors[i3] = read(row, 'f_dc_0')
366
+ out.colors[i3 + 1] = read(row, 'f_dc_1')
367
+ out.colors[i3 + 2] = read(row, 'f_dc_2')
368
+ out.alphas[i] = sigmoid(read(row, 'opacity'))
369
+ out.scales[i3] = read(row, 'scale_0')
370
+ out.scales[i3 + 1] = read(row, 'scale_1')
371
+ out.scales[i3 + 2] = read(row, 'scale_2')
372
+ // INRIA's order is w, x, y, z.
373
+ out.rotations[i4 + 3] = read(row, 'rot_0')
374
+ out.rotations[i4] = read(row, 'rot_1')
375
+ out.rotations[i4 + 1] = read(row, 'rot_2')
376
+ out.rotations[i4 + 2] = read(row, 'rot_3')
377
+ normalizeQuat(out.rotations, i4)
378
+ // Each channel's run apart in the PLY, each coefficient's r, g, b together here.
379
+ for (let k = 0; k < dim; k++) {
380
+ for (let c = 0; c < 3; c++) out.sh[(i * dim + k) * 3 + c] = read(row, `f_rest_${c * dim + k}`)
381
+ }
382
+ }
383
+ return out
384
+ }
385
+
386
+ // ---------------------------------------------------------------- .splat in
387
+
388
+ /** antimatter15's .splat: 32 bytes a splat, position and linear scale as
389
+ * floats, colour and opacity as bytes, rotation as bytes w, x, y, z. No
390
+ * colour detail past the 0th coefficient. */
391
+ export function readDotSplat(bytes) {
392
+ const buf = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)
393
+ if (buf.byteLength === 0 || buf.byteLength % 32 !== 0) throw new Error('its length is not a whole number of 32-byte splats')
394
+ const count = buf.byteLength / 32
395
+ const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength)
396
+ const out = empty(count, 0)
397
+ for (let i = 0; i < count; i++) {
398
+ const r = i * 32
399
+ const i3 = i * 3
400
+ const i4 = i * 4
401
+ for (let c = 0; c < 3; c++) {
402
+ out.positions[i3 + c] = view.getFloat32(r + c * 4, true)
403
+ out.scales[i3 + c] = Math.log(Math.max(1e-12, view.getFloat32(r + 12 + c * 4, true)))
404
+ out.colors[i3 + c] = (buf[r + 24 + c] / 255 - 0.5) / SH_C0
405
+ }
406
+ out.alphas[i] = buf[r + 27] / 255
407
+ out.rotations[i4 + 3] = (buf[r + 28] - 128) / 128
408
+ out.rotations[i4] = (buf[r + 29] - 128) / 128
409
+ out.rotations[i4 + 1] = (buf[r + 30] - 128) / 128
410
+ out.rotations[i4 + 2] = (buf[r + 31] - 128) / 128
411
+ normalizeQuat(out.rotations, i4)
412
+ }
413
+ return out
414
+ }
415
+
416
+ /** Any of the three, by name and by what the bytes start with. */
417
+ export async function readSplat(bytes, name = '') {
418
+ const buf = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)
419
+ const ext = (/\.[a-z0-9]+$/i.exec(String(name))?.[0] ?? '').toLowerCase()
420
+ const startsPly = buf[0] === 0x70 && buf[1] === 0x6c && buf[2] === 0x79
421
+ if (ext === '.ply' || startsPly) return { ...readPly(buf), from: 'ply' }
422
+ if (ext === '.splat') return { ...readDotSplat(buf), from: 'splat' }
423
+ return { ...(await readSpz(buf)), from: 'spz' }
424
+ }
425
+
426
+ // ---------------------------------------------------------------- transform
427
+
428
+ /** The sign each SH coefficient takes under a half turn about x (y and z
429
+ * negated), in the order 3DGS, .spz and three keep them: y, z, x; then xy,
430
+ * yz, 3z^2 - 1, xz, x^2 - y^2; then the seven of degree 3. Niantic's spz
431
+ * converts between frames with the same table. */
432
+ const HALF_TURN_X_SH = [-1, -1, 1, -1, 1, 1, -1, 1, -1, 1, -1, -1, 1, -1, 1]
433
+
434
+ /**
435
+ * Bakes a frame into the splats, in place: each centre p becomes
436
+ * R(scale * p) + offset, where R is a half turn about x when `flip` (the
437
+ * y-down frame to three's y-up one) and nothing otherwise; each radius is
438
+ * multiplied by `scale`; each rotation and each colour coefficient turns
439
+ * with R, so the splats look as they did, only upright and in metres.
440
+ */
441
+ export function transformSplat(s, { flip = false, scale = 1, offset = [0, 0, 0] } = {}) {
442
+ if (!(scale > 0) || !Number.isFinite(scale)) throw new Error(`the scale ${scale} is not a positive number`)
443
+ const logScale = Math.log(scale)
444
+ const dim = SH_DIM[s.shDegree]
445
+ for (let i = 0; i < s.count; i++) {
446
+ const i3 = i * 3
447
+ const i4 = i * 4
448
+ const x = s.positions[i3] * scale
449
+ const y = s.positions[i3 + 1] * scale
450
+ const z = s.positions[i3 + 2] * scale
451
+ s.positions[i3] = x + offset[0]
452
+ s.positions[i3 + 1] = (flip ? -y : y) + offset[1]
453
+ s.positions[i3 + 2] = (flip ? -z : z) + offset[2]
454
+ s.scales[i3] += logScale
455
+ s.scales[i3 + 1] += logScale
456
+ s.scales[i3 + 2] += logScale
457
+ if (flip) {
458
+ // (1, 0, 0, 0) * (x, y, z, w): the half turn applied after the splat's own.
459
+ const qx = s.rotations[i4]
460
+ const qy = s.rotations[i4 + 1]
461
+ const qz = s.rotations[i4 + 2]
462
+ const qw = s.rotations[i4 + 3]
463
+ s.rotations[i4] = qw
464
+ s.rotations[i4 + 1] = -qz
465
+ s.rotations[i4 + 2] = qy
466
+ s.rotations[i4 + 3] = -qx
467
+ normalizeQuat(s.rotations, i4)
468
+ for (let k = 0; k < dim; k++) {
469
+ const sign = HALF_TURN_X_SH[k]
470
+ if (sign > 0) continue
471
+ const o = (i * dim + k) * 3
472
+ s.sh[o] = -s.sh[o]
473
+ s.sh[o + 1] = -s.sh[o + 1]
474
+ s.sh[o + 2] = -s.sh[o + 2]
475
+ }
476
+ }
477
+ }
478
+ return s
479
+ }
480
+
481
+ // ---------------------------------------------------------------- .spz out
482
+
483
+ const clampByte = (v) => (v < 0 ? 0 : v > 255 ? 255 : Math.round(v))
484
+
485
+ /** Niantic's quantisation of the colour detail: degree 1 to 5 bits, the rest
486
+ * to 4, which costs nothing anyone sees and lets gzip halve it. */
487
+ function shByte(v, bucket) {
488
+ let q = Math.round(v * 128) + 128
489
+ q = Math.floor((q + bucket / 2) / bucket) * bucket
490
+ return q < 0 ? 0 : q > 255 ? 255 : q
491
+ }
492
+
493
+ /** The planet's .spz bytes: version 3, gzip. */
494
+ export function encodeSpz(s) {
495
+ const { count, shDegree } = s
496
+ let reach = 0
497
+ for (let k = 0; k < s.positions.length; k++) {
498
+ const a = Math.abs(s.positions[k])
499
+ if (a > reach && Number.isFinite(a)) reach = a
500
+ }
501
+ // As fine as the farthest centre allows in 24 bits, and no finer than
502
+ // Niantic's 12 (a quarter of a millimetre).
503
+ const fractionalBits = Math.max(0, Math.min(12, Math.floor(Math.log2((2 ** 23 - 1) / Math.max(reach, 1e-6)))))
504
+ if (reach * 2 ** fractionalBits >= 2 ** 23) throw new Error(`a splat is ${Math.round(reach)} m from the centre, too far for an SPZ`)
505
+ const dim = SH_DIM[shDegree]
506
+ const size = SPZ_HEADER + count * (9 + 1 + 3 + 3 + 4 + dim * 3)
507
+ const b = new Uint8Array(size)
508
+ const v = new DataView(b.buffer)
509
+ v.setUint32(0, SPZ_MAGIC, true)
510
+ v.setUint32(4, 3, true)
511
+ v.setUint32(8, count, true)
512
+ v.setUint8(12, shDegree)
513
+ v.setUint8(13, fractionalBits)
514
+ v.setUint8(14, s.antialiased ? FLAG_ANTIALIASED : 0)
515
+ v.setUint8(15, 0)
516
+ let o = SPZ_HEADER
517
+ const fixed = 2 ** fractionalBits
518
+ for (let i = 0; i < count * 3; i++) {
519
+ const q = Math.round(s.positions[i] * fixed) || 0
520
+ b[o] = q & 0xff
521
+ b[o + 1] = (q >> 8) & 0xff
522
+ b[o + 2] = (q >> 16) & 0xff
523
+ o += 3
524
+ }
525
+ for (let i = 0; i < count; i++) b[o++] = clampByte(s.alphas[i] * 255)
526
+ for (let i = 0; i < count * 3; i++) b[o++] = clampByte((s.colors[i] * COLOR_SCALE + 0.5) * 255)
527
+ for (let i = 0; i < count * 3; i++) b[o++] = clampByte((s.scales[i] + 10) * 16)
528
+ for (let i = 0; i < count; i++) {
529
+ const i4 = i * 4
530
+ let largest = 0
531
+ for (let k = 1; k < 4; k++) if (Math.abs(s.rotations[i4 + k]) > Math.abs(s.rotations[i4 + largest])) largest = k
532
+ const negate = s.rotations[i4 + largest] < 0
533
+ let packed = largest
534
+ for (let k = 0; k < 4; k++) {
535
+ if (k === largest) continue
536
+ const value = negate ? -s.rotations[i4 + k] : s.rotations[i4 + k]
537
+ const mag = Math.min(511, Math.round((Math.abs(value) / Math.SQRT1_2) * 511))
538
+ packed = packed * 1024 + (value < 0 ? 512 : 0) + mag
539
+ }
540
+ v.setUint32(o, packed >>> 0, true)
541
+ o += 4
542
+ }
543
+ for (let i = 0; i < count; i++) {
544
+ for (let k = 0; k < dim; k++) {
545
+ const bucket = k < 3 ? 8 : 16
546
+ const src = (i * dim + k) * 3
547
+ b[o++] = shByte(s.sh[src], bucket)
548
+ b[o++] = shByte(s.sh[src + 1], bucket)
549
+ b[o++] = shByte(s.sh[src + 2], bucket)
550
+ }
551
+ }
552
+ return zlib.gzipSync(b, { level: 6 })
553
+ }
554
+
555
+ // ---------------------------------------------------------------- stats
556
+
557
+ /** The value at fraction p of the sorted values (0..1). */
558
+ function quantile(sorted, p) {
559
+ if (!sorted.length) return 0
560
+ const i = Math.min(sorted.length - 1, Math.max(0, Math.round(p * (sorted.length - 1))))
561
+ return sorted[i]
562
+ }
563
+
564
+ /**
565
+ * What a splat is, in numbers: its count and colour detail, its bounds
566
+ * (every splat, and the 1st to 99th percentile, which leaves out the
567
+ * floaters a capture always has), and a guess at its floor: the 2nd
568
+ * percentile of the heights of the solid splats (opacity over a half), which
569
+ * is where a captured or generated room's ground usually is. In whatever
570
+ * frame the splats are in.
571
+ */
572
+ export function splatStats(s, { sample = 200_000 } = {}) {
573
+ const step = Math.max(1, Math.floor(s.count / sample))
574
+ const axes = [[], [], []]
575
+ const solidY = []
576
+ const min = [Infinity, Infinity, Infinity]
577
+ const max = [-Infinity, -Infinity, -Infinity]
578
+ for (let i = 0; i < s.count; i++) {
579
+ for (let c = 0; c < 3; c++) {
580
+ const p = s.positions[i * 3 + c]
581
+ if (p < min[c]) min[c] = p
582
+ if (p > max[c]) max[c] = p
583
+ }
584
+ if (i % step) continue
585
+ for (let c = 0; c < 3; c++) axes[c].push(s.positions[i * 3 + c])
586
+ if (s.alphas[i] > 0.5) solidY.push(s.positions[i * 3 + 1])
587
+ }
588
+ for (const a of axes) a.sort((x, y) => x - y)
589
+ solidY.sort((x, y) => x - y)
590
+ const r = (x) => Math.round(x * 1000) / 1000
591
+ return {
592
+ count: s.count,
593
+ shDegree: s.shDegree,
594
+ bounds: { min: min.map(r), max: max.map(r) },
595
+ core: { min: axes.map((a) => r(quantile(a, 0.01))), max: axes.map((a) => r(quantile(a, 0.99))) },
596
+ floorY: r(quantile(solidY.length ? solidY : axes[1], 0.02)),
597
+ }
598
+ }
599
+
600
+ /** How many splats a file says it holds, from its header alone (an .spz's,
601
+ * a .ply's vertex count, a .splat's length), so a file far past what a
602
+ * planet draws is refused before it is decoded. Null when it cannot tell. */
603
+ export function splatCountOf(bytes, name = '') {
604
+ const buf = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)
605
+ const ext = (/\.[a-z0-9]+$/i.exec(String(name))?.[0] ?? '').toLowerCase()
606
+ if (ext === '.splat') return buf.byteLength % 32 === 0 ? buf.byteLength / 32 : null
607
+ if (ext === '.ply' || (buf[0] === 0x70 && buf[1] === 0x6c && buf[2] === 0x79)) {
608
+ const text = Buffer.from(buf.buffer, buf.byteOffset, Math.min(buf.byteLength, 64 * 1024)).toString('latin1')
609
+ const m = /element vertex (\d+)/.exec(text.slice(0, text.indexOf('end_header') >>> 0))
610
+ return m ? Number(m[1]) : null
611
+ }
612
+ return spzHeader(buf)?.count ?? null
613
+ }
614
+
615
+ /** The .spz's own count and degree from its header, without decoding it:
616
+ * null when it is not an SPZ three reads. */
617
+ export function spzHeader(bytes) {
618
+ const buf = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)
619
+ try {
620
+ const v = new DataView(buf.buffer, buf.byteOffset, buf.byteLength)
621
+ if (buf.byteLength >= 16 && v.getUint32(0, true) === SPZ_MAGIC) return { version: v.getUint32(4, true), count: v.getUint32(8, true), shDegree: v.getUint8(12) }
622
+ // Only the start of a gzip one is unpacked: what its first 4 KB hold.
623
+ const head = zlib.gunzipSync(buf.subarray(0, 4096), { finishFlush: zlib.constants.Z_SYNC_FLUSH }).subarray(0, 16)
624
+ if (head.byteLength < 16) return null
625
+ const h = new DataView(head.buffer, head.byteOffset, head.byteLength)
626
+ if (h.getUint32(0, true) !== SPZ_MAGIC) return null
627
+ return { version: h.getUint32(4, true), count: h.getUint32(8, true), shDegree: h.getUint8(12) }
628
+ } catch {
629
+ return null
630
+ }
631
+ }