fourdgs library

A decoder for the .4dgs container: a single, self-contained, seekable file holding a 4D gaussian splat scene — gaussians whose position, opacity and existence vary continuously over time, optionally with an embedded audio sources and a default camera trajectory.

The format is renderer-agnostic and so is this decoder. It reconstructs splat state at a given time and stops there; how that state is drawn is out of scope, and nothing here knows or cares.

Two read paths are provided because they catch different mistakes:

  • readFourdgsBytes walks a whole file front to back. It needs no index and survives a truncated file.
  • openFourdgsIndexed reads the Footer, then the index, then only the byte ranges an instant needs. It is the path a seeking client takes.

The only thing either needs from the outside world is a FourdgsReadable — something that can report its size and read a byte range. Transports live at the edges, so the decoder can be tested without a network and shipped without a platform.

Writing goes the other way through the same primitives: writeFourdgsToSink and writeKeyframeDeltaToSink emit bounded records; writeFourdgsBytes and writeKeyframeDeltaBytes are their in-memory conveniences. They encode gaussian state in their own right rather than wrapping another SDK, which is what makes their agreement with those SDKs worth something.

Reading a file from disk needs one more import: package:fourdgs/io.dart carries the dart:io transport, kept out of this library so the decoder itself stays platform-free and usable in a browser.

The normative specification is at github.com/avala-ai/4dgs.

Classes

FourdgsAttachment
Opcode 0x0D. Arbitrary payloads — thumbnails, provenance, licences. Attachments are NOT the mechanism for audio; audio has its own record because it is a first-class part of the scene.
FourdgsAttributeStream
One decoded attribute stream: values[i * channels + c].
FourdgsAudio
Opcode 0x09. Present only when the scene has audio; its absence is the signal, not a placeholder.
FourdgsAudioData
Opcode 0x12. One source's encoded codec payload.
FourdgsAudioSource
One independently timed, optionally spatial audio source.
FourdgsAudioSourceDescriptor
A small source descriptor, independent of its encoded payload.
FourdgsAudioSourceKeyframe
One source pose on the scene clock.
FourdgsAudioSourceKeyframeRecord
FourdgsAudioSourceRecord
Opcode 0x11. A small source descriptor paired with FourdgsAudioData.
FourdgsAudioSourceState
The source-local timing and pose reconstructed at one scene instant.
FourdgsAudioTrack
A legacy, non-spatial track.
FourdgsBandRange
A spherical-harmonic band's own byte range within the file.
FourdgsBytes
A whole resource already in memory.
FourdgsCamera
Opcode 0x0A. A default viewpoint and an optional suggested path. Purely advisory: a reader MAY ignore it entirely.
FourdgsCameraTrajectory
A default viewpoint and an optional suggested path. Advisory in the format and advisory here: nothing in decoding depends on it.
FourdgsChunkBody
A chunk's header and the raw bytes of its concatenated attribute streams.
FourdgsChunkHeader
Opcode 0x05 — a chunk's own fields. Its attribute streams follow in the records blob, which parseChunk returns alongside.
FourdgsChunkIndexEntry
Opcode 0x08. One entry per chunk; together they are the seek index.
FourdgsCoordinateFrame
The frame a file's own coordinates are expressed in. Opcode 0x20.
FourdgsCursor
A bounds-checked read head over a byte buffer.
FourdgsCut
Where a framing walk stopped, when it did not reach the end.
FourdgsDecodedChunk
One chunk's gaussians, on the global scene clock.
FourdgsDeltaChunkBody
A Delta Chunk's header and the raw bytes of its three groups.
FourdgsDeltaChunkHeader
Opcode 0x10 — a Delta Chunk's own fields. Its three length-framed groups (updates, births, deaths) follow in the records blob, which parseDeltaChunk returns alongside.
FourdgsFinding
One thing wrong with a file, and — when the decoder named it — which refusal.
FourdgsFooter
FourdgsFrame
One record's framing: what it is, where it starts, how long its content is.
FourdgsGaussianSet
Every gaussian in a scene, structure-of-arrays.
FourdgsGeodeticAnchor
Where a frame's origin sits on the WGS-84 ellipsoid, and which way it faces. Opcode 0x23.
FourdgsHeader
Opcode 0x01. Everything a reader needs before deciding what to fetch.
FourdgsIndexedAudioSource
The independently readable ranges belonging to one audio source.
FourdgsIndexedScene
A scene opened over byte ranges: everything needed to decide what to fetch, and nothing that had to be fetched to decide it.
FourdgsInspection
Every record a file frames, and what the summary checksum covers.
FourdgsKeyframeDeltaOptions
Cadence, mode, and everything else a keyframe-delta file needs.
FourdgsMetadata
Opcode 0x0B.
FourdgsNamedRefusal
A refusal with a name, and where it is if the tool could place it.
FourdgsObjectEntry
FourdgsObjectLayer
Every object-layer record a file carried, and the rule that spans the tracks.
FourdgsObjectTable
The scene's one Object Table. Opcode 0x24.
FourdgsObjectTrack
One object's rigid pose over the scene clock. Opcode 0x25, one per object.
FourdgsObjectTrackView
Adapter so FourdgsObjectTrack satisfies FourdgsPoseSampled, and the clamp-and-slerp of section 5.15.4 is reused rather than restated.
FourdgsPose
A rigid transform: rotate by a unit quaternion, then translate.
FourdgsPoseSampled
A record fourdgsPoseAt can sample: time-stamped rigid poses with an interpolation mode.
FourdgsProvenance
Every provenance record a file carried, and the rules that span them.
FourdgsQuantization
Opcode 0x03. The dequantization grids and the error bounds they guarantee.
FourdgsReadable
The one abstraction the decoder depends on.
FourdgsRecord
One framed record: its opcode, its content, and where it started.
FourdgsRecordSpan
Where a record sits, without reading what is in it.
FourdgsRefusalSite
The byte a refusal fired at, and what sits there.
FourdgsRigTrajectory
FourdgsRigTrajectoryView
Adapter so FourdgsRigTrajectory satisfies FourdgsPoseSampled.
FourdgsSample
One population, at one instant, with identity.
FourdgsScene
A whole file, decoded.
FourdgsSensorCalibration
One sensor's intrinsics and extrinsics. Opcode 0x21, one record per sensor.
FourdgsState
Reconstructed state at one instant: which gaussians are visible, where their centres are, and what their opacity is.
FourdgsStatistics
Opcode 0x0C. Advisory: a reader that needs certainty computes from the chunks instead.
FourdgsSteps
Grid pitches, read verbatim from the Quantization record so a decoder never re-derives a float and drifts from the encoder.
FourdgsStreamHeader
An attribute stream's header, read without touching its payload.
FourdgsSummaryCoverage
The only checksum the format defines: summary_crc over the bytes from summary_start to where the Footer begins.
FourdgsSummaryOffset
Opcode 0x0F. Lets a reader range-read one class of index record without reading the others.
FourdgsValidation
Everything a validator has to say about one file.
FourdgsWalk
The result of walking a file's framing, and the cut if there was one.
FourdgsWindow
One validity window: the span outside which a gaussian does not exist.
FourdgsWindowTable
Opcode 0x04. Gaussians reference windows by index, so the per-gaussian cost of a validity window is an index rather than two floats.
FourdgsWriteOptions
How a scene is written. The defaults are the reference encoders' own.
KeyframeDeltaChunk
One decoded chunk and the composed population valid over [t0, t1).
KeyframeDeltaPopulation
A composed population as gaussian state, dequantized once from its bins.
KeyframeDeltaSequence
A whole keyframe-delta file, decoded by either read path.
KeyframeDeltaState
A composed population: identities, and one bin column per attribute.

Enums

FourdgsSeverity
How much a finding matters. Ordered, so the worst one picks the exit code.

Constants

attrColor → const int
attrFlags → const int
attrGaussianId → const int
Identity, required in every chunk of a keyframe-delta file and absent from a gaussian-birth one. Distinct from attrSourceIndex, which is a producer-side handle a reader may skip; this is what a delta names its gaussians by.
attrMotion → const int
attrMuT → const int
attrObjectId → const int
Object membership, spec section 6.6. A u32 per gaussian, 0 = background / unassigned. Optional: a chunk without it carries gaussians that belong to no object.
attrOpacity → const int
attrPosition → const int
attrReservedFirst → const int
The first and last id of the reserved extension pool, registry §"Attribute ids". Ids 15–63 are reserved and a version-1 writer MUST NOT emit them; ids 64–127 are private and application-defined. A reader skips both the same way, by payload_length, which is what forward compatibility requires — but only one of the two is a file a conformance validator should accept.
attrReservedLast → const int
attrRotation → const int
attrRotationIndex → const int
attrScale → const int
attrSigmaT → const int
attrSourceGroup → const int
attrSourceIndex → const int
attrWindowIndex → const int
audioDataHeadBytes → const int
How much of an Audio Data record's content _audioDataHead needs: the u32 source id and the u64 length in front of the payload.
audioSourceFlagLoop → const int
audioSourceFlagSpatial → const int
audioSourceKeyframeBytes → const int
f64 time, three f64 position values and four f64 quaternion values.
backgroundObject → const int
Background / unassigned. A gaussian carrying this id belongs to no object.
bandRangeBytes → const int
Encoded size of one SH band descriptor: u8 band, u64 offset, u64 length.
cameraModelCoefficients → const Map<int, List<int>>
Coefficient counts each camera model defines, keyed by its registry id. A model absent from here is one this build does not know — not the same as wrong: null means "ask the caller", not "refuse".
chunkFixedHeadBytes → const int
How many bytes of a Chunk's content parseChunkInterval needs.
codecDeflate → const int
codecZstd → const int
deltaModeChained → const int
deltaModeKeyframe → const int
delta_mode values (spec §5.18). Per chunk, not per file.
flagNeverFades → const int
Bit 0 of the per-gaussian flags attribute: this gaussian never fades, so its sigma_t is infinite and its marginal is 1 across its whole window.
footerFixedBytes → const int
Opcode 0x02. The tail pointer that makes the file seekable.
fourdgsCrcBlockBytes → const int
How much of a checksummed region is read at a time.
fourdgsDefaultCutoff → const double
The Header's default marginal visibility threshold.
fourdgsHeadProbeBytes → const int
One read of this size from the front covers the header records of every scene measured so far. A larger header costs one extra round trip, never a wrong parse.
fourdgsPackageVersion → const String
This package's version, and the single source of truth for it.
fourdgsRefusalCodes → const Set<String>
Every refusal this reader can name (spec: the refusal table).
fourdgsShLadders → const Map<String, List<int>>
Named per-band ladders, band 1 first, as website/docs/reference/compression.md measures them.
fourdgsShMaxBits → const int
fourdgsShMinBits → const int
The narrowest and widest a spherical-harmonic band may declare (spec §6.5).
fourdgsVersion → const int
Major version this reader implements.
headerFlagChunksCompressed → const int
headerFlagHasAudio → const int
indexDeltaBlockBytes → const int
Bytes the keyframe-delta block appends to a Chunk Index entry: u8 kind, u8 delta_mode, u64 reference_offset, u64 keyframe_offset, u16 depth, u64 live_count.
keyframeDeltaAbsoluteInUpdate → const Set<int>
Attributes an update restates outright rather than differencing. The smallest-three rotation coding omits the largest-magnitude component, so the three stored bins mean different components either side of a change; a rotating object crosses that boundary constantly, so rotation is restated.
keyframeDeltaBinMax → const int
keyframeDeltaBinMin → const int
Composed bins are signed 32-bit. Not a limit anyone meets — at a millimetre grid it spans about 2,000 km — but stated so two decoders in two languages agree on where the boundary is rather than one finding it on a 64-bit accumulator and the other on a 32-bit one. Overflow is refused, never wrapped: a wrapped position bin is a gaussian at a plausible-looking wrong place, which is the failure the bounds contract exists to make impossible.
keyframeDeltaGopInvariant → const Set<int>
Attributes a delta's update group MUST NOT carry. The per-gaussian grids for velocity and birth time are derived from these three, so a bin difference across a change in any of them is a difference between bins on two different grids — a number with no interpretation (spec §11.5).
lengthUnitMetres → const Map<int, double>
Metres per unit for each registry length unit, or null for one this build does not know. An unrecognized registry value is not a malformed one.
maxBandsPerChunk → const int
The most SH band descriptors one chunk index entry may declare.
maxChunkDecodedBytes → const int
The most decoded bytes one chunk may cost, across every array this decoder builds for it.
maxChunkIndexEntries → const int
The most chunk-index entries one scene may declare.
maxFramedRecords → const int
The most top-level records a framing walk retains.
maxFrontMatterBytes → const int
The most this reader will transfer in one go for a header record or for the whole summary block.
maxFrontMatterReads → const int
Round-trip cap for reading the front matter.
maxRigTrajectorySamples → const int
The former public name for maxTrajectorySamples.
maxStreamBytes → const int
A crafted length must not be able to make a reader allocate before it has been checked against the resource. Streams above this are refused outright.
maxTrajectorySamples → const int
The most samples one count-prefixed trajectory may declare — a Rig Trajectory, an Object Track, or the Camera record's suggested path.
maxWindowsPerScene → const int
The most validity windows one scene may declare.
modeConst → const int
modeDelta → const int
modeRaw → const int
opAttachment → const int
opAttachmentIndex → const int
opAttributeStream → const int
opAudio → const int
opAudioData → const int
opAudioSource → const int
opCamera → const int
opChunk → const int
opChunkIndex → const int
opCoordinateFrame → const int
opDeltaChunk → const int
opFooter → const int
opGeodeticAnchor → const int
opHeader → const int
opMetadata → const int
opObjectTable → const int
opObjectTrack → const int
opPrivateStart → const int
First opcode of the application range, which the specification never defines and a conforming reader always skips.
opProvenanceEnd → const int
opProvenanceStart → const int
First opcode of the provenance family, and one past its last. 0x26–0x2F are reserved for source timing (spec section 5.15.6).
opQuantization → const int
opRigTrajectory → const int
opSensorCalibration → const int
opShBandStream → const int
opStatistics → const int
opSummaryOffset → const int
opWindowTable → const int
poseToRig → const int
Wire constant: sensor extrinsic maps into a named rig.
poseToScene → const int
Wire constant: sensor extrinsic maps into the scene frame.
recordHeaderBytes → const int
u8 opcode + u64 content_length.
refusalMagicMismatch → const String
The file does not begin with the 4dgs magic.
refusalUnknownQuantizationScheme → const String
The Quantization record names a scheme this build does not implement.
refusalUnknownStreamCodec → const String
A stream declares a codec this build does not implement.
refusalUnknownTemporalModel → const String
The Header names a temporal model this build does not implement — including the empty name, which is a declaration of nothing rather than a default.
refusalUnsupportedMajorVersion → const String
The magic is ours; the major version is not one this reader implements.
refusalWindowIndexOutOfRange → const String
A gaussian's window index names a row the Window Table does not have.
requiredAttributes → const List<int>
Ids every chunk must carry. 11 and 12 are optional producer-side identities and readers that do not need them skip the streams.
rigTrajectorySampleBytes → const int
Encoded size of one rig trajectory sample: time + rotation + translation.
shBandChannels → const Map<int, int>
Coefficients per gaussian in each spherical-harmonic band, three channels included: band 1 carries three coefficients per channel, band 2 five, band 3 seven.
shBandRange → const Map<int, ({int first, int last})>
Where each band's coefficients sit within one colour component's row, as [first, last). Band b carries 2b + 1 of them, so a whole degree d occupies [0, shBandRange[d]!.last).
streamHeaderBytes → const int
u8 ×5 + u32 element_count + u64 payload_length.
trajectoryLinear → const int
Wire constant: linear (slerp + lerp) trajectory interpolation.
trajectoryStep → const int
Wire constant: hold-until-next sample trajectory interpolation.
windowBytes → const int
Encoded size of one window table entry: two f64 bounds.

Properties

fourdgsMagic → Uint8List
0x89 4 D G S 1 CR LF.
final
kSupport → double
marginal >= cutoff <=> |t - mu| <= K * sigma, for the default cutoff.
final

Functions

applyKeyframeDeltaBody(KeyframeDeltaState reference, FourdgsDeltaChunkBody body, {required int chunkOffset}) → KeyframeDeltaState
Compose one already-parsed Delta Chunk onto its selected reference state.
assembleGaussians(List<FourdgsDecodedChunk> chunks, int shDegree, {({int coefficients, Uint8List values})? sh}) → FourdgsGaussianSet
Concatenates decoded chunks into one gaussian set.
chainFor(List<FourdgsChunkIndexEntry> index, double t) → List<FourdgsChunkIndexEntry>
The keyframe and deltas a reader must read to reconstruct instant t.
chainFrom(List<FourdgsChunkIndexEntry> index, FourdgsChunkIndexEntry current, {Map<int, FourdgsChunkIndexEntry>? byOffset}) → List<FourdgsChunkIndexEntry>
The keyframe and deltas that reconstruct current itself.
checkCutoff(double cutoff, {String what = "the Header's cutoff"}) → void
Refuses a marginal threshold outside (0, 1], naming it.
checkIndexEntry(FourdgsChunkIndexEntry entry, {required bool isKeyframeDelta, required String where}) → void
Everything an index entry can be refused for that needs the Header to see it.
checkKeyframeDeltaMuT(KeyframeDeltaState state, double t0, FourdgsQuantization quantization) → void
Require every keyframe gaussian's encoded birth-time bin to name its t0.
checkMagic(Uint8List head) → void
Refuses a file this reader must not try to interpret.
checkSceneTime(double t) → void
checkTiling(List<FourdgsChunkIndexEntry> index, {double? durationSec}) → void
State chunks tile the timeline: no overlap, no gap (spec §11.1). This is what makes the seek predicate a lookup rather than a search.
chunkDecodedBytesPerGaussian(int shDegree) → int
Decoded bytes one gaussian costs, for a chunk carrying SH up to shDegree.
composeKeyframeDeltaChain(Uint8List data, List<FourdgsChunkIndexEntry> index, FourdgsChunkIndexEntry entry, {Map<int, FourdgsChunkIndexEntry>? byOffset}) → KeyframeDeltaState
The composed state of one index entry: its chain, walked and telescoped.
decodeAttributeStream(FourdgsCursor cursor) → FourdgsAttributeStream
Reads one attribute stream from cursor.
decodeAttributeStreamBody(FourdgsCursor cursor, FourdgsStreamHeader header, {int streamOffset = 0, int? chunkOffset}) → FourdgsAttributeStream
Decodes the payload of a stream whose header has already been read.
decodeChunkStreams(Uint8List streams, int count, FourdgsSteps steps, List<double> posOrigin, List<FourdgsWindow> windows, {required double cutoff, String compression = '', Map<int, Uint8List> shBandRecords = const <int, Uint8List>{}, Map<int, int> shBandContentOffsets = const <int, int>{}, int chunkOffset = 0, int streamsOffset = 0}) → FourdgsDecodedChunk
Decodes a chunk's attribute streams.
decodeKeyframeDeltaIndexed(Uint8List data) → ({List<FourdgsChunkIndexEntry> index, KeyframeDeltaSequence sequence})
Read the Footer, then the index, then compose each chunk by byte range.
decodeKeyframeDeltaStreamed(Uint8List data) → KeyframeDeltaSequence
Front to back: decode each chunk and compose it onto the state it references.
decodeShBandRecord(Uint8List content, {required int expectedBand, required int expectedCount, int fileOffset = 0}) → Uint8List?
Decodes one SH Band Stream record's content: a u8 band followed by an ordinary attribute stream.
dequantizeRotation(int largest, int b0, int b1, int b2, double step, List<double> dst, int at) → void
Smallest-three quaternion reconstruction, writing xyzw into dst at at.
describeFourdgsRefusal(Object error, {FourdgsWalk? walk, FourdgsRefusalSite? site}) → FourdgsNamedRefusal?
Everything the tool can say about one refusal: the identifier and the byte.
finiteLerp(double a, double b, double u) → double
Interpolate two finite values without overflowing their difference across zero.
formatFourdgsInspection(FourdgsInspection inspection) → String
The record table, in the column widths the Rust and TypeScript tools print.
formatFourdgsInspectionJson(FourdgsInspection inspection) → String
The same walk, for a caller that is a program rather than a person.
fourdgsCommas(int n) → String
A count with thousands separators, matching the Python tool's {:,}.
fourdgsCrc32(Uint8List data, [int crc = 0]) → int
CRC-32 (IEEE) over data, as the Footer's summary_crc declares it.
fourdgsCrc32Range(FourdgsReadable source, int start, int length) → Future<int>
The checksum of [start, start + length) of source, a block at a time.
fourdgsPoseAt(FourdgsPoseSampled track, double t) → FourdgsPose?
The pose at scene time t, or null when the record has no samples.
fourdgsQuantizeSh(int value, int bits) → int
Round one coefficient byte onto the grid bits names, at bin centres.
fourdgsRigPoseAt(FourdgsRigTrajectory trajectory, double t) → FourdgsPose?
Convenience: sample a FourdgsRigTrajectory without wrapping it.
fourdgsShBound(int bits) → int
The maximum deviation, in code units, a bit depth guarantees.
fourdgsShStep(int bits) → int
The grid pitch, in code units, that a bit depth implies.
fourdgsSlerp(List<double> aIn, List<double> bIn, double u) → List<double>
Shortest-arc spherical interpolation between two unit quaternions.
fourdgsStateAtWithObjects(FourdgsGaussianSet gaussians, FourdgsObjectLayer? objects, double t, {double cutoff = fourdgsDefaultCutoff}) → FourdgsState
Reconstructed gaussian state at t with the object layer composed onto it.
indexEntryPopulation(FourdgsChunkIndexEntry entry, {required bool isKeyframeDelta}) → int
The number of gaussians an index entry says are there, which is not always the number it stores in gaussianCount.
inspectFourdgs(FourdgsReadable source) → Future<FourdgsInspection>
Frames every record, then checks the summary region the Footer declares.
interpolationFraction(double t, double a, double b) → double
The normalized position of t between finite, strictly increasing a and b. Scaling is necessary when the mathematical span is finite but cannot be represented as an f64, for example -1e308..1e308.
isLegalTopLevelOpcode(int opcode) → bool
True when a specified opcode is itself a top-level record.
isPrivateOpcode(int opcode) → bool
isProvenanceOpcode(int opcode) → bool
True for the provenance family, defined and reserved alike.
isSpecifiedOpcode(int opcode) → bool
True for the opcodes this version of the specification defines.
iterRecords(Uint8List buf, [int pos = 0]) → Iterable<FourdgsRecord>
Every record in buf from pos, interpreting nothing.
keyframeDeltaChainIndex(List<FourdgsChunkIndexEntry> index) → Map<int, FourdgsChunkIndexEntry>
Index entries by the byte their chunk starts at, which is what a delta references (spec §11.8).
keyframeDeltaPopulation(KeyframeDeltaSequence sequence, KeyframeDeltaChunk chunk) → KeyframeDeltaPopulation
The population chunk composes to, as gaussian state on the file's grids.
keyframeDeltaStateFromChunk(Uint8List content, {required int chunkOffset}) → KeyframeDeltaState
Decode one keyframe Chunk into composed keyframe-delta state.
keyframeDeltaStatesJson(KeyframeDeltaSequence sequence) → Map<String, Object?>
The statement two implementations are diffed on for a keyframe-delta file.
lifeClass(int sigmaBin, double sigmaLogStep, bool neverFades, double windowLength, {double? k}) → int
Velocity precision class, from the sigma bin a decoder has already read.
mathMax(double a, double b) → double
mathMin(int a, int b) → int
mergeChunkBands(List<int> counts, List<Map<int, Uint8List>> chunkBands) → ({int coefficients, Uint8List values})?
One scene's coefficients, out of the per-chunk bands each read path gathered.
motionStep(int lifeClassValue, double stepRef) → double
The velocity pitch a lifeClass implies.
muStep(int sigmaBin, double sigmaLogStep, bool neverFades, double stepRef) → double
Birth-time pitch: stepRef, refined by powers of two until it is at most 5 % of the gaussian's own sigma.
normalizeQuaternion(List<double> q) → List<double>
opcodeName(int opcode) → String
The names in _opcodeNames, plus the two ranges a reader steps over.
openFourdgsIndexed(FourdgsReadable source, {int probeBytes = fourdgsHeadProbeBytes, int? framedFooterOffset, int? framedFooterLength}) → Future<FourdgsIndexedScene>
Opens a scene: a bounded read from the front, then the index. Never the file.
parseChunk(Uint8List content) → FourdgsChunkBody
parseChunkInterval(Uint8List head, {int fileOffset = 0}) → ({int count, int level, double t0, double t1})
A Chunk's interval and count, from the first chunkFixedHeadBytes bytes.
parseDeltaChunk(Uint8List content) → FourdgsDeltaChunkBody
quaternionMultiply(List<double> a, List<double> b) → List<double>
Hamilton product of two xyzw quaternions.
quaternionNorm(List<double> q) → double
The measured pose of the capture platform over the scene clock. Opcode 0x22.
rctInverse(int c0, int c1, int c2, List<int> out) → void
Inverts the reversible colour transform, which stores (g, r - g, b - g).
readFourdgsAttachments(FourdgsReadable source, FourdgsIndexedScene scene) → Future<List<FourdgsAttachment>>
Every Attachment record, by range. Each one costs exactly its own bytes, so a caller that wants a thumbnail does not pay for a licence file beside it.
readFourdgsAudio(FourdgsReadable source, FourdgsIndexedScene scene) → Future<FourdgsAudioTrack?>
The embedded track's bytes, fetched independently of any gaussian data.
readFourdgsAudioRange(FourdgsReadable source, FourdgsIndexedScene scene, int sourceId, int offset, int length) → Future<Uint8List>
Validates the small descriptor, then reads one source-relative payload range.
readFourdgsAudioSourceDescriptors(FourdgsReadable source, FourdgsIndexedScene scene) → Future<List<FourdgsAudioSourceDescriptor>>
Fetches small source descriptors without transferring encoded payloads.
readFourdgsAudioSources(FourdgsReadable source, FourdgsIndexedScene scene) → Future<List<FourdgsAudioSource>>
Fetches every source descriptor and encoded payload.
readFourdgsAudioSourceState(FourdgsReadable source, FourdgsIndexedScene scene, int sourceId, double t) → Future<FourdgsAudioSourceState>
Reconstructs one source at scene time t without transferring its payload.
readFourdgsBytes(Uint8List data, {bool recoverTruncated = true, int maxShBand = 3}) → FourdgsScene
Decodes a whole file already in memory.
readFourdgsCamera(FourdgsReadable source, FourdgsIndexedScene scene) → Future<FourdgsCameraTrajectory?>
The suggested camera trajectory, fetched only when a caller wants it.
readFourdgsChunk(FourdgsReadable source, FourdgsIndexedScene scene, FourdgsChunkIndexEntry entry, {int maxShBand = 0}) → Future<FourdgsDecodedChunk>
Fetches and decodes one chunk, plus only the SH bands asked for.
readFourdgsMetadata(FourdgsReadable source, FourdgsIndexedScene scene) → Future<List<FourdgsMetadata>>
Every Metadata record, by range.
readFourdgsObjects(FourdgsReadable source, FourdgsIndexedScene scene) → Future<FourdgsObjectLayer>
Every object-layer record, from the same framed ranges as provenance.
readFourdgsProvenance(FourdgsReadable source, FourdgsIndexedScene scene) → Future<FourdgsProvenance>
Every provenance record, by range, fetched only when a caller wants them.
readKeyframeDeltaChain(FourdgsReadable source, List<FourdgsChunkIndexEntry> index, FourdgsChunkIndexEntry entry, {Map<int, FourdgsChunkIndexEntry>? byOffset}) → Future<KeyframeDeltaState>
The same chain, fetched by byte range instead of from a resident file.
readRecord(FourdgsCursor cursor) → FourdgsRecord
readStreamHeader(FourdgsCursor cursor) → FourdgsStreamHeader
Reads a stream's header and leaves cursor on its payload.
refuseUnusableInterval(double t0, double t1, int at, String what) → void
The interval rule, applied wherever a record states one.
refuseZeroWidthPopulation(FourdgsChunkIndexEntry entry, int population, String where) → void
Refuses gaussians nothing can ever reach, over an interval of no width.
scanRecordSpans(Uint8List buf, [int pos = 0]) → Iterable<FourdgsRecordSpan>
Walks record headers in buf from pos, without requiring their content to be present.
skipStreamPayload(FourdgsCursor cursor, FourdgsStreamHeader header) → void
Steps over a stream whose header has been read, without decoding it.
supportK(double cutoff, {String what = "the Header's cutoff"}) → double
Half-width of a gaussian's visible support, in sigmas, for a file's own cutoff (spec §6.3).
validateFourdgs(FourdgsReadable source) → Future<FourdgsValidation>
Every check, in the Python validator's order.
walkFourdgsFrames(FourdgsReadable source, FourdgsWalk walk) → Stream<FourdgsFrame>
Replays every frame from walk without retaining another frame table.
walkFourdgsFraming(FourdgsReadable source) → Future<FourdgsWalk>
Every top-level record, from framing alone.
windowIndexOutOfRange(int index, int tableLength, {String gaussian = ''}) → FourdgsMalformedFile
The refusal a window_index outside the Window Table gets, wherever it is reached from.
writeFourdgsBytes(FourdgsGaussianSet gaussians, double durationSec, {FourdgsWriteOptions options = const FourdgsWriteOptions()}) → Uint8List
Encode gaussians as one in-memory .4dgs file.
writeFourdgsToSink(Sink<List<int>> sink, FourdgsGaussianSet gaussians, double durationSec, {FourdgsWriteOptions options = const FourdgsWriteOptions()}) → void
Encode gaussians to sink, one complete framed record at a time.
writeKeyframeDeltaBytes(List<FourdgsSample> samples, double durationSec, {FourdgsKeyframeDeltaOptions options = const FourdgsKeyframeDeltaOptions()}) → Uint8List
Encode samples as a complete keyframe-delta file.
writeKeyframeDeltaToSink(Sink<List<int>> sink, List<FourdgsSample> samples, double durationSec, {FourdgsKeyframeDeltaOptions options = const FourdgsKeyframeDeltaOptions(verify: false)}) → void
Encode samples to sink, one complete framed record at a time.

Exceptions / Errors

FourdgsException
Everything this decoder throws, so a caller can catch the whole family.
FourdgsInvalidInput
The caller handed the encoder something no conforming file can be written from.
FourdgsMalformedFile
The framing held but the content did not make sense — a required record missing, an attribute absent from a chunk, a field out of range.
FourdgsTruncatedFile
The file ended, or a length pointed past the end, before a structure was complete.
FourdgsUnsupportedCodec
A stream names a codec this build cannot decode.
FourdgsUnsupportedFeature
A legal file feature that this particular high-level API cannot preserve.
FourdgsUnsupportedVersion
The magic is absent, or names a major version this reader does not implement.