@driftengine/assets 3.61.0

package/dist/orient.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Turn an imported asset into the engine's frame. One responsibility: orientation.
+ *
+ * **This lives on the intermediate, not in a reader, and that placement is the point.** Every
+ * format arrives here eventually — glTF, OBJ, STL, FBX, and whatever is added next — and each
+ * one has its own idea of which way is up: glTF specifies Y-up and means it, STL specifies
+ * nothing at all, FBX records a convention per file and its exporters disagree about how to
+ * honour it. If each reader carried its own correction, the engine would slowly acquire one
+ * format's habits as its defaults, and the next reader would be written to match the last
+ * one's quirks rather than its own specification. So a reader's job is to report what its
+ * file says, faithfully and with no opinion, and the single opinionated step happens once,
+ * here, where it is written down and testable.
+ *
+ * **Why an override exists at all.** A file can be internally consistent and still disagree
+ * with itself: an asset whose `GlobalSettings` declare Y-up while every node in it was
+ * exported a half turn away is not malformed, and no amount of reading it more carefully
+ * reveals which of the two statements the author meant. That is not a defect a reader can
+ * repair, because the information is genuinely absent from the file — so it is supplied from
+ * outside, by somebody who has looked at the model, and the baker prints what it was told.
+ *
+ * Every turn here is a **rotation**, never a mirror. A reflection would flip the handedness
+ * of the geometry, which turns every triangle inside out and shades the model dark where it
+ * should be lit, and it is not obvious in a bounding box — the numbers look right and the
+ * render does not. Each entry in `TURNS` has determinant +1, so the winding a reader produced
+ * is still the winding the rasteriser wants, and the index buffers are passed through
+ * untouched.
+ */
+import type { DrftNode, MeshData } from '@driftengine/drft';
+/** Which way is up in the asset, as a signed axis of the engine's own frame. */
+export type UpAxis = '+x' | '-x' | '+y' | '-y' | '+z' | '-z';
+export declare const UP_AXES: readonly UpAxis[];
+/** Read an axis a person typed. `z` and `+z` mean the same thing; anything else is refused. */
+export declare function parseUpAxis(text: string): UpAxis;
+/** What the turn does, in words, for the line the baker prints. */
+export declare function describeUpAxis(up: UpAxis): string;
+/**
+ * Stand an asset up, given which of its axes points at the sky.
+ *
+ * Normals take the same matrix as positions rather than an inverse transpose, and that is
+ * exact rather than an approximation: for a rotation the two are the same matrix. There is
+ * no scale here by construction, which is the other half of why.
+ */
+export declare function orientMeshes(meshes: readonly MeshData[], assetUp: UpAxis): MeshData[];
+/**
+ * Which way round a format's coordinate system is.
+ *
+ * **Every format read here is right-handed**, including the one that was declared left-handed for
+ * two releases on the strength of the graphics API its authoring tool targets, and whose frame is
+ * measured in the reader that reports it. The pair below is what a genuinely left-handed format
+ * gets.
+ */
+export type Handedness = 'right' | 'left';
+/**
+ * Mirror an asset into the engine's right-handed frame, in place.
+ *
+ * **This is the one thing the `TURNS` table above deliberately cannot do**, and the paragraph at
+ * the top of this file explaining why is still correct: an up-axis correction must be a rotation,
+ * or it flips geometry that was already the right way round. A *handedness* conversion is the
+ * opposite case — the geometry is genuinely mirrored, and refusing to mirror it is what would
+ * leave it wrong. Keeping the two apart is what lets each stay honest about what it does.
+ *
+ * **Three changes, and all three or none.** Negating X alone turns every triangle inside out;
+ * reversing the winding without flipping the bitangent sign lights every normal-mapped surface
+ * backwards. Doing them together, here, is why this is a function and not three lines inside a
+ * reader — the next left-handed format gets the same conversion and the same tests.
+ *
+ * UVs are untouched. A mirror moves the surface, not its parameterisation.
+ */
+export declare function convertHandedness(meshes: readonly MeshData[]): void;
+/**
+ * Mirror an asset's hierarchy by the same reflection `convertHandedness` mirrors its geometry by.
+ *
+ * **The pair to `convertHandedness`, exactly as `orientNodes` is the pair to `orientMeshes`**, and
+ * it did not exist: the one caller that mirrored a graph negated each node's translation X inline
+ * and left the rotations alone. A hierarchy with rotations then places its parts where the
+ * geometry is not — measured on a real car at **1.385 m apart and on the other side of the
+ * model** — while both halves stay individually well formed, which is the worst shape this can
+ * take and the reason the two functions now sit together.
+ *
+ * **The rotation is conjugated, not negated.** Reflecting a rotation `R` by a mirror `M` gives
+ * `M R M`, which is a rotation about the mirrored axis in the opposite sense; as a quaternion that
+ * is `(x, −y, −z, w)` for a reflection about the YZ plane. A scale is untouched, because `M S M`
+ * is `S` for any diagonal.
+ *
+ * **Every node, not only the roots**, which is the one place this differs from `orientNodes`. A
+ * rotation applied to a root already carries its descendants, so applying it to a child would
+ * apply it twice. A reflection is a conjugation and conjugation distributes over the product —
+ * `M (A B) M = (M A M)(M B M)` — so leaving a child alone drops the mirror out of the composition
+ * rather than avoiding a double application.
+ */
+export declare function mirrorNodes(nodes: readonly DrftNode[]): DrftNode[];
+/**
+ * Turn an asset's hierarchy by the same rotation `orientMeshes` turns its geometry by.
+ *
+ * **Without this, `--up` silently desynchronises the two.** The meshes rotate and the graph does
+ * not, so every node then claims a part is somewhere it no longer is — and nothing downstream can
+ * detect it, because both halves are individually well formed. That is the worst shape a bug can
+ * take in a bake, so the two turns happen together or the hierarchy is wrong.
+ *
+ * **Only roots are turned**, and that is not an optimisation: a child's transform is relative to
+ * its parent, so rotating the parent already carries every descendant with it. Turning a child too
+ * would apply the rotation twice.
+ */
+export declare function orientNodes(nodes: readonly DrftNode[], assetUp: UpAxis): DrftNode[];

package/dist/orient.js

@@ -0,0 +1,241 @@
+/**
+ * Turn an imported asset into the engine's frame. One responsibility: orientation.
+ *
+ * **This lives on the intermediate, not in a reader, and that placement is the point.** Every
+ * format arrives here eventually — glTF, OBJ, STL, FBX, and whatever is added next — and each
+ * one has its own idea of which way is up: glTF specifies Y-up and means it, STL specifies
+ * nothing at all, FBX records a convention per file and its exporters disagree about how to
+ * honour it. If each reader carried its own correction, the engine would slowly acquire one
+ * format's habits as its defaults, and the next reader would be written to match the last
+ * one's quirks rather than its own specification. So a reader's job is to report what its
+ * file says, faithfully and with no opinion, and the single opinionated step happens once,
+ * here, where it is written down and testable.
+ *
+ * **Why an override exists at all.** A file can be internally consistent and still disagree
+ * with itself: an asset whose `GlobalSettings` declare Y-up while every node in it was
+ * exported a half turn away is not malformed, and no amount of reading it more carefully
+ * reveals which of the two statements the author meant. That is not a defect a reader can
+ * repair, because the information is genuinely absent from the file — so it is supplied from
+ * outside, by somebody who has looked at the model, and the baker prints what it was told.
+ *
+ * Every turn here is a **rotation**, never a mirror. A reflection would flip the handedness
+ * of the geometry, which turns every triangle inside out and shades the model dark where it
+ * should be lit, and it is not obvious in a bounding box — the numbers look right and the
+ * render does not. Each entry in `TURNS` has determinant +1, so the winding a reader produced
+ * is still the winding the rasteriser wants, and the index buffers are passed through
+ * untouched.
+ */
+import { DrftError } from '@driftengine/drft';
+export const UP_AXES = ['+x', '-x', '+y', '-y', '+z', '-z'];
+/**
+ * The rotation that carries each axis onto the engine's `+y`, row-major 3x3.
+ *
+ * `-y` is the one genuinely ambiguous case: a half turn about X and a half turn about Z both
+ * stand the asset up, and they differ by a half turn of yaw, which no amount of measurement
+ * on the model can decide. X is the choice, because for an asset whose parts were exported
+ * with a quarter turn already baked into them it reduces those to exactly the conventional
+ * Z-up conversion rather than to that conversion plus an unexplained yaw.
+ */
+const TURNS = {
+    '+y': { m: [1, 0, 0, 0, 1, 0, 0, 0, 1], says: 'already the engine frame, so nothing is turned' },
+    '-y': { m: [1, 0, 0, 0, -1, 0, 0, 0, -1], says: 'a half turn about X' },
+    '+z': {
+        m: [1, 0, 0, 0, 0, 1, 0, -1, 0],
+        says: 'a quarter turn about X, the conventional Z-up conversion',
+    },
+    '-z': { m: [1, 0, 0, 0, 0, -1, 0, 1, 0], says: 'a quarter turn about X, the other way' },
+    '+x': { m: [0, -1, 0, 1, 0, 0, 0, 0, 1], says: 'a quarter turn about Z' },
+    '-x': { m: [0, 1, 0, -1, 0, 0, 0, 0, 1], says: 'a quarter turn about Z, the other way' },
+};
+/** Read an axis a person typed. `z` and `+z` mean the same thing; anything else is refused. */
+export function parseUpAxis(text) {
+    const cleaned = text.trim().toLowerCase();
+    const signed = cleaned.startsWith('+') || cleaned.startsWith('-') ? cleaned : `+${cleaned}`;
+    const found = UP_AXES.find((axis) => axis === signed);
+    if (found === undefined) {
+        throw new DrftError(`"${text}" is not an axis. Use one of: ${UP_AXES.join(', ')}.`);
+    }
+    return found;
+}
+/** What the turn does, in words, for the line the baker prints. */
+export function describeUpAxis(up) {
+    return TURNS[up].says;
+}
+function turnTriples(source, m) {
+    const out = new Float32Array(source.length);
+    const m0 = m[0];
+    const m1 = m[1];
+    const m2 = m[2];
+    const m3 = m[3];
+    const m4 = m[4];
+    const m5 = m[5];
+    const m6 = m[6];
+    const m7 = m[7];
+    const m8 = m[8];
+    for (let i = 0; i + 2 < source.length; i += 3) {
+        const x = source[i];
+        const y = source[i + 1];
+        const z = source[i + 2];
+        out[i] = m0 * x + m1 * y + m2 * z;
+        out[i + 1] = m3 * x + m4 * y + m5 * z;
+        out[i + 2] = m6 * x + m7 * y + m8 * z;
+    }
+    return out;
+}
+/**
+ * Stand an asset up, given which of its axes points at the sky.
+ *
+ * Normals take the same matrix as positions rather than an inverse transpose, and that is
+ * exact rather than an approximation: for a rotation the two are the same matrix. There is
+ * no scale here by construction, which is the other half of why.
+ */
+export function orientMeshes(meshes, assetUp) {
+    const { m } = TURNS[assetUp];
+    return meshes.map((mesh) => ({
+        ...mesh,
+        positions: turnTriples(mesh.positions, m),
+        normals: turnTriples(mesh.normals, m),
+    }));
+}
+/**
+ * Mirror an asset into the engine's right-handed frame, in place.
+ *
+ * **This is the one thing the `TURNS` table above deliberately cannot do**, and the paragraph at
+ * the top of this file explaining why is still correct: an up-axis correction must be a rotation,
+ * or it flips geometry that was already the right way round. A *handedness* conversion is the
+ * opposite case — the geometry is genuinely mirrored, and refusing to mirror it is what would
+ * leave it wrong. Keeping the two apart is what lets each stay honest about what it does.
+ *
+ * **Three changes, and all three or none.** Negating X alone turns every triangle inside out;
+ * reversing the winding without flipping the bitangent sign lights every normal-mapped surface
+ * backwards. Doing them together, here, is why this is a function and not three lines inside a
+ * reader — the next left-handed format gets the same conversion and the same tests.
+ *
+ * UVs are untouched. A mirror moves the surface, not its parameterisation.
+ */
+export function convertHandedness(meshes) {
+    for (const mesh of meshes) {
+        for (let at = 0; at < mesh.positions.length; at += 3) {
+            mesh.positions[at] = -mesh.positions[at];
+        }
+        for (let at = 0; at < mesh.normals.length; at += 3) {
+            mesh.normals[at] = -mesh.normals[at];
+        }
+        const tangents = mesh.tangents;
+        if (tangents !== undefined) {
+            for (let at = 0; at < tangents.length; at += 4) {
+                tangents[at] = -tangents[at];
+                tangents[at + 3] = -tangents[at + 3];
+            }
+        }
+        for (let at = 0; at + 2 < mesh.indices.length; at += 3) {
+            const middle = mesh.indices[at + 1];
+            mesh.indices[at + 1] = mesh.indices[at + 2];
+            mesh.indices[at + 2] = middle;
+        }
+    }
+}
+/**
+ * Mirror an asset's hierarchy by the same reflection `convertHandedness` mirrors its geometry by.
+ *
+ * **The pair to `convertHandedness`, exactly as `orientNodes` is the pair to `orientMeshes`**, and
+ * it did not exist: the one caller that mirrored a graph negated each node's translation X inline
+ * and left the rotations alone. A hierarchy with rotations then places its parts where the
+ * geometry is not — measured on a real car at **1.385 m apart and on the other side of the
+ * model** — while both halves stay individually well formed, which is the worst shape this can
+ * take and the reason the two functions now sit together.
+ *
+ * **The rotation is conjugated, not negated.** Reflecting a rotation `R` by a mirror `M` gives
+ * `M R M`, which is a rotation about the mirrored axis in the opposite sense; as a quaternion that
+ * is `(x, −y, −z, w)` for a reflection about the YZ plane. A scale is untouched, because `M S M`
+ * is `S` for any diagonal.
+ *
+ * **Every node, not only the roots**, which is the one place this differs from `orientNodes`. A
+ * rotation applied to a root already carries its descendants, so applying it to a child would
+ * apply it twice. A reflection is a conjugation and conjugation distributes over the product —
+ * `M (A B) M = (M A M)(M B M)` — so leaving a child alone drops the mirror out of the composition
+ * rather than avoiding a double application.
+ */
+export function mirrorNodes(nodes) {
+    return nodes.map((node) => ({
+        ...node,
+        translation: [-node.translation[0], node.translation[1], node.translation[2]],
+        rotation: [node.rotation[0], -node.rotation[1], -node.rotation[2], node.rotation[3]],
+    }));
+}
+/**
+ * Turn an asset's hierarchy by the same rotation `orientMeshes` turns its geometry by.
+ *
+ * **Without this, `--up` silently desynchronises the two.** The meshes rotate and the graph does
+ * not, so every node then claims a part is somewhere it no longer is — and nothing downstream can
+ * detect it, because both halves are individually well formed. That is the worst shape a bug can
+ * take in a bake, so the two turns happen together or the hierarchy is wrong.
+ *
+ * **Only roots are turned**, and that is not an optimisation: a child's transform is relative to
+ * its parent, so rotating the parent already carries every descendant with it. Turning a child too
+ * would apply the rotation twice.
+ */
+export function orientNodes(nodes, assetUp) {
+    const { m } = TURNS[assetUp];
+    if (assetUp === '+y')
+        return [...nodes];
+    const turn = (v) => [
+        m[0] * v[0] + m[1] * v[1] + m[2] * v[2],
+        m[3] * v[0] + m[4] * v[1] + m[5] * v[2],
+        m[6] * v[0] + m[7] * v[1] + m[8] * v[2],
+    ];
+    /* The turn as a quaternion, so a root's own rotation composes with it. */
+    const trace = m[0] + m[4] + m[8];
+    let q;
+    if (trace > 0) {
+        const s = Math.sqrt(trace + 1) * 2;
+        q = [
+            (m[7] - m[5]) / s,
+            (m[2] - m[6]) / s,
+            (m[3] - m[1]) / s,
+            s / 4,
+        ];
+    }
+    else if (m[0] > m[4] && m[0] > m[8]) {
+        const s = Math.sqrt(1 + m[0] - m[4] - m[8]) * 2;
+        q = [
+            s / 4,
+            (m[1] + m[3]) / s,
+            (m[2] + m[6]) / s,
+            (m[7] - m[5]) / s,
+        ];
+    }
+    else if (m[4] > m[8]) {
+        const s = Math.sqrt(1 + m[4] - m[0] - m[8]) * 2;
+        q = [
+            (m[1] + m[3]) / s,
+            s / 4,
+            (m[5] + m[7]) / s,
+            (m[2] - m[6]) / s,
+        ];
+    }
+    else {
+        const s = Math.sqrt(1 + m[8] - m[0] - m[4]) * 2;
+        q = [
+            (m[2] + m[6]) / s,
+            (m[5] + m[7]) / s,
+            s / 4,
+            (m[3] - m[1]) / s,
+        ];
+    }
+    return nodes.map((node) => {
+        if (node.parent >= 0)
+            return node;
+        const [bx, by, bz, bw] = node.rotation;
+        return {
+            ...node,
+            translation: turn(node.translation),
+            rotation: [
+                q[3] * bx + q[0] * bw + q[1] * bz - q[2] * by,
+                q[3] * by - q[0] * bz + q[1] * bw + q[2] * bx,
+                q[3] * bz + q[0] * by - q[1] * bx + q[2] * bw,
+                q[3] * bw - q[0] * bx - q[1] * by - q[2] * bz,
+            ],
+        };
+    });
+}

package/dist/radianceHdr.d.ts

@@ -0,0 +1,36 @@
+/** The Radiance `.hdr` container (RGBE), decoded to linear floats. */
+/**
+ * An equirectangular image, linear, three floats a texel, row 0 at the top.
+ *
+ * Three rather than four because an environment has no alpha and never will: the fourth channel
+ * would be a byte a texel of ones, and at 2048x1024 that is eight megabytes of nothing.
+ */
+export interface RadianceImage {
+    readonly width: number;
+    readonly height: number;
+    /** `width * height * 3` linear values, row-major from the top. */
+    readonly data: Float32Array;
+}
+/**
+ * Read a Radiance RGBE file into linear radiance.
+ *
+ * **Pure, and it takes bytes rather than a URL.** It knows nothing about a device, a fetch or a
+ * texture, which is what lets it be tested exactly and what keeps the fetching decision — cache
+ * headers, retries, where the file lives — with the consumer who has to make it.
+ *
+ * **Both scanline encodings, because only one of them is optional in practice.** A file narrower
+ * than 8 or wider than 0x7fff stores flat RGBE quadruples; everything else is new-style
+ * run-length, and that is every environment map anybody actually has. A decoder that handles only
+ * the flat path passes a hand-built test and fails on every real file.
+ *
+ * **Every refusal names what it found.** `AGENTS.md` requires failing loudly at load with an
+ * actionable message: a decoder that quietly answers black for a header it does not recognise
+ * hands a scene an environment of nothing, which is indistinguishable from a probe that has not
+ * baked yet and is diagnosed as the renderer's fault.
+ *
+ * **What it costs** is `width * height * 12` bytes for the result, which at 2048x1024 is 25 MB
+ * held while the faces are built. **What would make it wrong** is a consumer streaming an
+ * environment larger than memory; this reads whole files, and a tiled format is what that consumer
+ * wants — which is one of the reasons KTX2 is named and deliberately not taken.
+ */
+export declare function readRadianceHdr(bytes: Uint8Array): RadianceImage;

package/dist/radianceHdr.js

@@ -0,0 +1,172 @@
+/** The Radiance `.hdr` container (RGBE), decoded to linear floats. */
+/**
+ * Where a decoded byte sits inside its bucket.
+ *
+ * Radiance's own `colr_color` is `ldexp(mantissa + 0.5, exponent - (128 + 8))`, and the half is
+ * the part every reimplementation drops. Dropping it makes an image about 0.2% dark, which is
+ * invisible on its own, survives every eyeball comparison, and is exactly the kind of thing that
+ * is never found. It is written as a named constant so that nobody removes it as a typo.
+ */
+const BUCKET_CENTRE = 0.5;
+/** `2^-(128 + 8)`, the scale a stored exponent of zero would otherwise land on. */
+const EXPONENT_BIAS = 128 + 8;
+/**
+ * Read a Radiance RGBE file into linear radiance.
+ *
+ * **Pure, and it takes bytes rather than a URL.** It knows nothing about a device, a fetch or a
+ * texture, which is what lets it be tested exactly and what keeps the fetching decision — cache
+ * headers, retries, where the file lives — with the consumer who has to make it.
+ *
+ * **Both scanline encodings, because only one of them is optional in practice.** A file narrower
+ * than 8 or wider than 0x7fff stores flat RGBE quadruples; everything else is new-style
+ * run-length, and that is every environment map anybody actually has. A decoder that handles only
+ * the flat path passes a hand-built test and fails on every real file.
+ *
+ * **Every refusal names what it found.** `AGENTS.md` requires failing loudly at load with an
+ * actionable message: a decoder that quietly answers black for a header it does not recognise
+ * hands a scene an environment of nothing, which is indistinguishable from a probe that has not
+ * baked yet and is diagnosed as the renderer's fault.
+ *
+ * **What it costs** is `width * height * 12` bytes for the result, which at 2048x1024 is 25 MB
+ * held while the faces are built. **What would make it wrong** is a consumer streaming an
+ * environment larger than memory; this reads whole files, and a tiled format is what that consumer
+ * wants — which is one of the reasons KTX2 is named and deliberately not taken.
+ */
+export function readRadianceHdr(bytes) {
+    const signature = readLine(bytes, 0);
+    if (!signature.text.startsWith('#?RADIANCE') && !signature.text.startsWith('#?RGBE')) {
+        throw new Error(`readRadianceHdr: not a Radiance file — expected a "#?RADIANCE" signature, found ` +
+            `"${signature.text.slice(0, 20)}"`);
+    }
+    let at = signature.next;
+    let format = null;
+    /* The header runs to a blank line, and the resolution line is the one after it. */
+    for (;;) {
+        const line = readLine(bytes, at);
+        at = line.next;
+        if (line.text === '')
+            break;
+        if (line.text.startsWith('FORMAT='))
+            format = line.text.slice('FORMAT='.length).trim();
+        if (at >= bytes.length)
+            throw new Error('readRadianceHdr: the header never ended');
+    }
+    if (format !== null && format !== '32-bit_rle_rgbe') {
+        throw new Error(`readRadianceHdr: only 32-bit_rle_rgbe is decoded here, and this file declares ` +
+            `"${format}". An XYZE file carries CIE primaries rather than RGB and converting it is a ` +
+            'colour decision rather than a decoding one.');
+    }
+    const resolution = readLine(bytes, at);
+    at = resolution.next;
+    /*
+     * `-Y height +X width` only. Radiance permits eight orientations, six of which nothing has
+     * produced in decades, and treating one as another silently returns an image that is flipped —
+     * which in an environment map puts the sky underfoot and is the most confusing available failure.
+     */
+    const match = /^-Y\s+(\d+)\s+\+X\s+(\d+)$/.exec(resolution.text.trim());
+    if (match === null) {
+        throw new Error(`readRadianceHdr: only "-Y height +X width" is handled, and this file says ` +
+            `"${resolution.text.trim()}". Any other orientation would decode to a flipped image.`);
+    }
+    const height = Number(match[1]);
+    const width = Number(match[2]);
+    if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+        throw new Error(`readRadianceHdr: a ${width} by ${height} image is not decodable`);
+    }
+    const data = new Float32Array(width * height * 3);
+    /* One scanline of RGBE, reused, because a 2048-wide image would otherwise allocate per row. */
+    const scanline = new Uint8Array(width * 4);
+    for (let y = 0; y < height; y++) {
+        at = readScanline(bytes, at, scanline, width);
+        for (let x = 0; x < width; x++) {
+            const exponent = scanline[x * 4 + 3] ?? 0;
+            const out = (y * width + x) * 3;
+            /*
+             * A stored exponent of zero is exactly black and Radiance reserves it for that. Running it
+             * through the same arithmetic gives `0.5 * 2^-136`: denormal, nonzero, and enough to make
+             * every black texel of a night sky something a prefilter will average into a grey haze.
+             */
+            if (exponent === 0) {
+                data[out] = 0;
+                data[out + 1] = 0;
+                data[out + 2] = 0;
+                continue;
+            }
+            const scale = 2 ** (exponent - EXPONENT_BIAS);
+            data[out] = ((scanline[x * 4] ?? 0) + BUCKET_CENTRE) * scale;
+            data[out + 1] = ((scanline[x * 4 + 1] ?? 0) + BUCKET_CENTRE) * scale;
+            data[out + 2] = ((scanline[x * 4 + 2] ?? 0) + BUCKET_CENTRE) * scale;
+        }
+    }
+    return { width, height, data };
+}
+/** One newline-terminated line as text, and where the next one starts. */
+function readLine(bytes, from) {
+    let end = from;
+    while (end < bytes.length && bytes[end] !== 0x0a)
+        end++;
+    let text = '';
+    for (let i = from; i < end; i++)
+        text += String.fromCharCode(bytes[i] ?? 0);
+    return { text: text.replace(/\r$/, ''), next: end + 1 };
+}
+/**
+ * One scanline of RGBE into `out`, in either encoding, returning where the next one starts.
+ *
+ * The new-style marker is `2, 2, hi, lo` with `hi<<8 | lo` equal to the width. That third and
+ * fourth byte being the width is what distinguishes it from an old-style scanline whose first
+ * pixel happens to be `(2, 2, ...)`, which is a real colour and does occur.
+ */
+function readScanline(bytes, from, out, width) {
+    const declared = ((bytes[from + 2] ?? 0) << 8) | (bytes[from + 3] ?? 0);
+    const isRle = width >= 8 &&
+        width < 0x8000 &&
+        bytes[from] === 2 &&
+        bytes[from + 1] === 2 &&
+        declared === width;
+    if (!isRle) {
+        /* Flat quadruples, which is what a narrow image and an old encoder both produce. */
+        for (let x = 0; x < width; x++) {
+            out[x * 4] = bytes[from + x * 4] ?? 0;
+            out[x * 4 + 1] = bytes[from + x * 4 + 1] ?? 0;
+            out[x * 4 + 2] = bytes[from + x * 4 + 2] ?? 0;
+            out[x * 4 + 3] = bytes[from + x * 4 + 3] ?? 0;
+        }
+        return from + width * 4;
+    }
+    let at = from + 4;
+    /*
+     * The four channels are stored one after another rather than interleaved, which is the whole
+     * reason this encoding compresses: a sky's red channel is a smooth ramp and its exponent channel
+     * is nearly constant, and neither is compressible while they are interleaved with the others.
+     */
+    for (let channel = 0; channel < 4; channel++) {
+        let x = 0;
+        while (x < width) {
+            const count = bytes[at] ?? 0;
+            at++;
+            if (count > 128) {
+                /* A run: repeat the next byte this many times, minus the flag bit. */
+                const value = bytes[at] ?? 0;
+                at++;
+                const run = count - 128;
+                if (x + run > width)
+                    throw new Error('readRadianceHdr: a run overran its scanline');
+                for (let i = 0; i < run; i++)
+                    out[(x + i) * 4 + channel] = value;
+                x += run;
+            }
+            else {
+                if (count === 0)
+                    throw new Error('readRadianceHdr: a zero-length literal run');
+                if (x + count > width)
+                    throw new Error('readRadianceHdr: a literal run overran its scanline');
+                for (let i = 0; i < count; i++)
+                    out[(x + i) * 4 + channel] = bytes[at + i] ?? 0;
+                at += count;
+                x += count;
+            }
+        }
+    }
+    return at;
+}