copper3d 3.4.7 → 3.4.9

package/dist/bundle.esm.js

@@ -40826,6 +40826,17 @@ function copperDicomLoader(url, callback) {
             windowCenter = 226;
             windowWidth = 537;
         }
+        // Spatial geometry tags (DS VR, backslash-delimited) used to place the image plane
+        // at its true world pose, plus InstanceNumber as an ordering fallback.
+        const ipp = parseDS(dataSet.string("x00200032")); // ImagePositionPatient
+        const iop = parseDS(dataSet.string("x00200037")); // ImageOrientationPatient
+        const spacing = parseDS(dataSet.string("x00280030")); // PixelSpacing
+        let instanceNumber = parseInt(dataSet.string("x00200013"));
+        if (Number.isNaN(instanceNumber))
+            instanceNumber = undefined;
+        const corners = ipp && iop && spacing
+            ? computeImagePlaneCorners(ipp, iop, spacing, w, h)
+            : undefined;
         let pixelData = dataSet.elements.x7fe00010;
         let uint16 = convertImplicitElement(pixelData, dicomFileAsBuffer);
         let voiLUT;
@@ -40844,10 +40855,44 @@ function copperDicomLoader(url, callback) {
             uint16,
             uint8,
             order,
+            instanceNumber,
+            imagePositionPatient: ipp,
+            imageOrientationPatient: iop,
+            pixelSpacing: spacing,
+            corners,
         };
         callback && callback(copperVolume);
     });
 }
+// Parse a DICOM DS/IS multi-value string ("a\\b\\c") into a number[].
+function parseDS(s) {
+    if (!s)
+        return undefined;
+    const a = s.split("\\").map((v) => parseFloat(v));
+    return a.length && !a.some((n) => Number.isNaN(n)) ? a : undefined;
+}
+/**
+ * Compute the 4 world-space corners of a DICOM image plane from its geometry tags.
+ * IPP is the CENTER of pixel (0,0), so corners sit half a pixel out. PixelSpacing is
+ * [rowSpacing, colSpacing]; IOP's first vector is the +column-index direction.
+ */
+function computeImagePlaneCorners(ipp, iop, spacing, cols, rows) {
+    const row = new Vector3(iop[0], iop[1], iop[2]); // +column-index dir
+    const col = new Vector3(iop[3], iop[4], iop[5]); // +row-index dir
+    const sc = spacing[1]; // column spacing (along row)
+    const sr = spacing[0]; // row spacing (along col)
+    const O = new Vector3(ipp[0], ipp[1], ipp[2]); // center of pixel (0,0)
+    const p = (a, b) => O.clone()
+        .addScaledVector(row, a * sc)
+        .addScaledVector(col, b * sr)
+        .toArray();
+    return {
+        tl: p(-0.5, -0.5),
+        tr: p(cols - 0.5, -0.5),
+        bl: p(-0.5, rows - 0.5),
+        br: p(cols - 0.5, rows - 0.5),
+    };
+}
 function convertImplicitElement(elementData, dicomFileAsBuffer) {
     let w1Buffer = dicomParser.sharedCopy(dicomFileAsBuffer, elementData.dataOffset, elementData.length);
     let unit16 = new Uint16Array(w1Buffer.buffer, w1Buffer.byteOffset, w1Buffer.byteLength / Uint16Array.BYTES_PER_ELEMENT);
@@ -40884,514 +40929,23 @@ function getLut(data, windowWidth, windowCenter, invert, voiLUT) {
     };
 }
 
-// DEFLATE is a complex format; to read this code, you should probably check the RFC first:
+var vert_2d = "#define GLSLIFY 1\nout vec2 vUv;void main(){gl_Position=projectionMatrix*modelViewMatrix*vec4(position,1.0);vUv=vec2(uv.x,1.0-uv.y);}"; // eslint-disable-line
 
-// aliases for shorter compressed code (most minifers don't do this)
-var u8$1 = Uint8Array, u16$1 = Uint16Array, u32 = Uint32Array;
-// fixed length extra bits
-var fleb$1 = new u8$1([0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 0, /* unused */ 0, 0, /* impossible */ 0]);
-// fixed distance extra bits
-// see fleb note
-var fdeb$1 = new u8$1([0, 0, 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9, 10, 10, 11, 11, 12, 12, 13, 13, /* unused */ 0, 0]);
-// code length index map
-var clim$1 = new u8$1([16, 17, 18, 0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15]);
-// get base, reverse index map from extra bits
-var freb$1 = function (eb, start) {
-    var b = new u16$1(31);
-    for (var i = 0; i < 31; ++i) {
-        b[i] = start += 1 << eb[i - 1];
-    }
-    // numbers here are at max 18 bits
-    var r = new u32(b[30]);
-    for (var i = 1; i < 30; ++i) {
-        for (var j = b[i]; j < b[i + 1]; ++j) {
-            r[j] = ((j - b[i]) << 5) | i;
-        }
-    }
-    return [b, r];
-};
-var _a$1 = freb$1(fleb$1, 2), fl$1 = _a$1[0], revfl$1 = _a$1[1];
-// we can ignore the fact that the other numbers are wrong; they never happen anyway
-fl$1[28] = 258, revfl$1[258] = 28;
-var _b$1 = freb$1(fdeb$1, 0), fd$1 = _b$1[0];
-// map of value to reverse (assuming 16 bits)
-var rev$1 = new u16$1(32768);
-for (var i$1 = 0; i$1 < 32768; ++i$1) {
-    // reverse table algorithm from SO
-    var x$1 = ((i$1 & 0xAAAA) >>> 1) | ((i$1 & 0x5555) << 1);
-    x$1 = ((x$1 & 0xCCCC) >>> 2) | ((x$1 & 0x3333) << 2);
-    x$1 = ((x$1 & 0xF0F0) >>> 4) | ((x$1 & 0x0F0F) << 4);
-    rev$1[i$1] = (((x$1 & 0xFF00) >>> 8) | ((x$1 & 0x00FF) << 8)) >>> 1;
-}
-// create huffman tree from u8 "map": index -> code length for code index
-// mb (max bits) must be at most 15
-// TODO: optimize/split up?
-var hMap$1 = (function (cd, mb, r) {
-    var s = cd.length;
-    // index
-    var i = 0;
-    // u16 "map": index -> # of codes with bit length = index
-    var l = new u16$1(mb);
-    // length of cd must be 288 (total # of codes)
-    for (; i < s; ++i) {
-        if (cd[i])
-            ++l[cd[i] - 1];
-    }
-    // u16 "map": index -> minimum code for bit length = index
-    var le = new u16$1(mb);
-    for (i = 0; i < mb; ++i) {
-        le[i] = (le[i - 1] + l[i - 1]) << 1;
-    }
-    var co;
-    if (r) {
-        // u16 "map": index -> number of actual bits, symbol for code
-        co = new u16$1(1 << mb);
-        // bits to remove for reverser
-        var rvb = 15 - mb;
-        for (i = 0; i < s; ++i) {
-            // ignore 0 lengths
-            if (cd[i]) {
-                // num encoding both symbol and bits read
-                var sv = (i << 4) | cd[i];
-                // free bits
-                var r_1 = mb - cd[i];
-                // start value
-                var v = le[cd[i] - 1]++ << r_1;
-                // m is end value
-                for (var m = v | ((1 << r_1) - 1); v <= m; ++v) {
-                    // every 16 bit value starting with the code yields the same result
-                    co[rev$1[v] >>> rvb] = sv;
-                }
-            }
-        }
-    }
-    else {
-        co = new u16$1(s);
-        for (i = 0; i < s; ++i) {
-            if (cd[i]) {
-                co[i] = rev$1[le[cd[i] - 1]++] >>> (15 - cd[i]);
-            }
-        }
-    }
-    return co;
-});
-// fixed length tree
-var flt$1 = new u8$1(288);
-for (var i$1 = 0; i$1 < 144; ++i$1)
-    flt$1[i$1] = 8;
-for (var i$1 = 144; i$1 < 256; ++i$1)
-    flt$1[i$1] = 9;
-for (var i$1 = 256; i$1 < 280; ++i$1)
-    flt$1[i$1] = 7;
-for (var i$1 = 280; i$1 < 288; ++i$1)
-    flt$1[i$1] = 8;
-// fixed distance tree
-var fdt$1 = new u8$1(32);
-for (var i$1 = 0; i$1 < 32; ++i$1)
-    fdt$1[i$1] = 5;
-// fixed length map
-var flrm$1 = /*#__PURE__*/ hMap$1(flt$1, 9, 1);
-// fixed distance map
-var fdrm$1 = /*#__PURE__*/ hMap$1(fdt$1, 5, 1);
-// find max of array
-var max$1 = function (a) {
-    var m = a[0];
-    for (var i = 1; i < a.length; ++i) {
-        if (a[i] > m)
-            m = a[i];
-    }
-    return m;
-};
-// read d, starting at bit p and mask with m
-var bits$1 = function (d, p, m) {
-    var o = (p / 8) | 0;
-    return ((d[o] | (d[o + 1] << 8)) >> (p & 7)) & m;
-};
-// read d, starting at bit p continuing for at least 16 bits
-var bits16$1 = function (d, p) {
-    var o = (p / 8) | 0;
-    return ((d[o] | (d[o + 1] << 8) | (d[o + 2] << 16)) >> (p & 7));
-};
-// get end of byte
-var shft$1 = function (p) { return ((p + 7) / 8) | 0; };
-// typed array slice - allows garbage collector to free original reference,
-// while being more compatible than .slice
-var slc$1 = function (v, s, e) {
-    if (s == null || s < 0)
-        s = 0;
-    if (e == null || e > v.length)
-        e = v.length;
-    // can't use .constructor in case user-supplied
-    var n = new (v.BYTES_PER_ELEMENT == 2 ? u16$1 : v.BYTES_PER_ELEMENT == 4 ? u32 : u8$1)(e - s);
-    n.set(v.subarray(s, e));
-    return n;
-};
-// error codes
-var ec$1 = [
-    'unexpected EOF',
-    'invalid block type',
-    'invalid length/literal',
-    'invalid distance',
-    'stream finished',
-    'no stream handler',
-    ,
-    'no callback',
-    'invalid UTF-8 data',
-    'extra field too long',
-    'date not in range 1980-2099',
-    'filename too long',
-    'stream finishing',
-    'invalid zip data'
-    // determined by unknown compression method
-];
-var err$1 = function (ind, msg, nt) {
-    var e = new Error(msg || ec$1[ind]);
-    e.code = ind;
-    if (Error.captureStackTrace)
-        Error.captureStackTrace(e, err$1);
-    if (!nt)
-        throw e;
-    return e;
-};
-// expands raw DEFLATE data
-var inflt$1 = function (dat, buf, st) {
-    // source length
-    var sl = dat.length;
-    if (!sl || (st && st.f && !st.l))
-        return buf || new u8$1(0);
-    // have to estimate size
-    var noBuf = !buf || st;
-    // no state
-    var noSt = !st || st.i;
-    if (!st)
-        st = {};
-    // Assumes roughly 33% compression ratio average
-    if (!buf)
-        buf = new u8$1(sl * 3);
-    // ensure buffer can fit at least l elements
-    var cbuf = function (l) {
-        var bl = buf.length;
-        // need to increase size to fit
-        if (l > bl) {
-            // Double or set to necessary, whichever is greater
-            var nbuf = new u8$1(Math.max(bl * 2, l));
-            nbuf.set(buf);
-            buf = nbuf;
-        }
-    };
-    //  last chunk         bitpos           bytes
-    var final = st.f || 0, pos = st.p || 0, bt = st.b || 0, lm = st.l, dm = st.d, lbt = st.m, dbt = st.n;
-    // total bits
-    var tbts = sl * 8;
-    do {
-        if (!lm) {
-            // BFINAL - this is only 1 when last chunk is next
-            final = bits$1(dat, pos, 1);
-            // type: 0 = no compression, 1 = fixed huffman, 2 = dynamic huffman
-            var type = bits$1(dat, pos + 1, 3);
-            pos += 3;
-            if (!type) {
-                // go to end of byte boundary
-                var s = shft$1(pos) + 4, l = dat[s - 4] | (dat[s - 3] << 8), t = s + l;
-                if (t > sl) {
-                    if (noSt)
-                        err$1(0);
-                    break;
-                }
-                // ensure size
-                if (noBuf)
-                    cbuf(bt + l);
-                // Copy over uncompressed data
-                buf.set(dat.subarray(s, t), bt);
-                // Get new bitpos, update byte count
-                st.b = bt += l, st.p = pos = t * 8, st.f = final;
-                continue;
-            }
-            else if (type == 1)
-                lm = flrm$1, dm = fdrm$1, lbt = 9, dbt = 5;
-            else if (type == 2) {
-                //  literal                            lengths
-                var hLit = bits$1(dat, pos, 31) + 257, hcLen = bits$1(dat, pos + 10, 15) + 4;
-                var tl = hLit + bits$1(dat, pos + 5, 31) + 1;
-                pos += 14;
-                // length+distance tree
-                var ldt = new u8$1(tl);
-                // code length tree
-                var clt = new u8$1(19);
-                for (var i = 0; i < hcLen; ++i) {
-                    // use index map to get real code
-                    clt[clim$1[i]] = bits$1(dat, pos + i * 3, 7);
-                }
-                pos += hcLen * 3;
-                // code lengths bits
-                var clb = max$1(clt), clbmsk = (1 << clb) - 1;
-                // code lengths map
-                var clm = hMap$1(clt, clb, 1);
-                for (var i = 0; i < tl;) {
-                    var r = clm[bits$1(dat, pos, clbmsk)];
-                    // bits read
-                    pos += r & 15;
-                    // symbol
-                    var s = r >>> 4;
-                    // code length to copy
-                    if (s < 16) {
-                        ldt[i++] = s;
-                    }
-                    else {
-                        //  copy   count
-                        var c = 0, n = 0;
-                        if (s == 16)
-                            n = 3 + bits$1(dat, pos, 3), pos += 2, c = ldt[i - 1];
-                        else if (s == 17)
-                            n = 3 + bits$1(dat, pos, 7), pos += 3;
-                        else if (s == 18)
-                            n = 11 + bits$1(dat, pos, 127), pos += 7;
-                        while (n--)
-                            ldt[i++] = c;
-                    }
-                }
-                //    length tree                 distance tree
-                var lt = ldt.subarray(0, hLit), dt = ldt.subarray(hLit);
-                // max length bits
-                lbt = max$1(lt);
-                // max dist bits
-                dbt = max$1(dt);
-                lm = hMap$1(lt, lbt, 1);
-                dm = hMap$1(dt, dbt, 1);
-            }
-            else
-                err$1(1);
-            if (pos > tbts) {
-                if (noSt)
-                    err$1(0);
-                break;
-            }
-        }
-        // Make sure the buffer can hold this + the largest possible addition
-        // Maximum chunk size (practically, theoretically infinite) is 2^17;
-        if (noBuf)
-            cbuf(bt + 131072);
-        var lms = (1 << lbt) - 1, dms = (1 << dbt) - 1;
-        var lpos = pos;
-        for (;; lpos = pos) {
-            // bits read, code
-            var c = lm[bits16$1(dat, pos) & lms], sym = c >>> 4;
-            pos += c & 15;
-            if (pos > tbts) {
-                if (noSt)
-                    err$1(0);
-                break;
-            }
-            if (!c)
-                err$1(2);
-            if (sym < 256)
-                buf[bt++] = sym;
-            else if (sym == 256) {
-                lpos = pos, lm = null;
-                break;
-            }
-            else {
-                var add = sym - 254;
-                // no extra bits needed if less
-                if (sym > 264) {
-                    // index
-                    var i = sym - 257, b = fleb$1[i];
-                    add = bits$1(dat, pos, (1 << b) - 1) + fl$1[i];
-                    pos += b;
-                }
-                // dist
-                var d = dm[bits16$1(dat, pos) & dms], dsym = d >>> 4;
-                if (!d)
-                    err$1(3);
-                pos += d & 15;
-                var dt = fd$1[dsym];
-                if (dsym > 3) {
-                    var b = fdeb$1[dsym];
-                    dt += bits16$1(dat, pos) & ((1 << b) - 1), pos += b;
-                }
-                if (pos > tbts) {
-                    if (noSt)
-                        err$1(0);
-                    break;
-                }
-                if (noBuf)
-                    cbuf(bt + 131072);
-                var end = bt + add;
-                for (; bt < end; bt += 4) {
-                    buf[bt] = buf[bt - dt];
-                    buf[bt + 1] = buf[bt + 1 - dt];
-                    buf[bt + 2] = buf[bt + 2 - dt];
-                    buf[bt + 3] = buf[bt + 3 - dt];
-                }
-                bt = end;
-            }
-        }
-        st.l = lm, st.p = lpos, st.b = bt, st.f = final;
-        if (lm)
-            final = 1, st.m = lbt, st.d = dm, st.n = dbt;
-    } while (!final);
-    return bt == buf.length ? buf : slc$1(buf, 0, bt);
-};
-// empty
-var et$1 = /*#__PURE__*/ new u8$1(0);
-// read 2 bytes
-var b2 = function (d, b) { return d[b] | (d[b + 1] << 8); };
-// read 4 bytes
-var b4 = function (d, b) { return (d[b] | (d[b + 1] << 8) | (d[b + 2] << 16) | (d[b + 3] << 24)) >>> 0; };
-var b8 = function (d, b) { return b4(d, b) + (b4(d, b + 4) * 4294967296); };
-/**
- * Expands DEFLATE data with no wrapper
- * @param data The data to decompress
- * @param out Where to write the data. Saves memory if you know the decompressed size and provide an output buffer of that length.
- * @returns The decompressed version of the data
- */
-function inflateSync(data, out) {
-    return inflt$1(data, out);
-}
-// text decoder
-var td$1 = typeof TextDecoder != 'undefined' && /*#__PURE__*/ new TextDecoder();
-// text decoder stream
-var tds$1 = 0;
-try {
-    td$1.decode(et$1, { stream: true });
-    tds$1 = 1;
-}
-catch (e) { }
-// decode UTF8
-var dutf8 = function (d) {
-    for (var r = '', i = 0;;) {
-        var c = d[i++];
-        var eb = (c > 127) + (c > 223) + (c > 239);
-        if (i + eb > d.length)
-            return [r, slc$1(d, i - 1)];
-        if (!eb)
-            r += String.fromCharCode(c);
-        else if (eb == 3) {
-            c = ((c & 15) << 18 | (d[i++] & 63) << 12 | (d[i++] & 63) << 6 | (d[i++] & 63)) - 65536,
-                r += String.fromCharCode(55296 | (c >> 10), 56320 | (c & 1023));
-        }
-        else if (eb & 1)
-            r += String.fromCharCode((c & 31) << 6 | (d[i++] & 63));
-        else
-            r += String.fromCharCode((c & 15) << 12 | (d[i++] & 63) << 6 | (d[i++] & 63));
-    }
-};
-/**
- * Converts a Uint8Array to a string
- * @param dat The data to decode to string
- * @param latin1 Whether or not to interpret the data as Latin-1. This should
- *               not need to be true unless encoding to binary string.
- * @returns The original UTF-8/Latin-1 string
- */
-function strFromU8(dat, latin1) {
-    if (latin1) {
-        var r = '';
-        for (var i = 0; i < dat.length; i += 16384)
-            r += String.fromCharCode.apply(null, dat.subarray(i, i + 16384));
-        return r;
-    }
-    else if (td$1)
-        return td$1.decode(dat);
-    else {
-        var _a = dutf8(dat), out = _a[0], ext = _a[1];
-        if (ext.length)
-            err$1(8);
-        return out;
-    }
-}
-// skip local zip header
-var slzh = function (d, b) { return b + 30 + b2(d, b + 26) + b2(d, b + 28); };
-// read zip header
-var zh = function (d, b, z) {
-    var fnl = b2(d, b + 28), fn = strFromU8(d.subarray(b + 46, b + 46 + fnl), !(b2(d, b + 8) & 2048)), es = b + 46 + fnl, bs = b4(d, b + 20);
-    var _a = z && bs == 4294967295 ? z64e(d, es) : [bs, b4(d, b + 24), b4(d, b + 42)], sc = _a[0], su = _a[1], off = _a[2];
-    return [b2(d, b + 10), sc, su, fn, es + b2(d, b + 30) + b2(d, b + 32), off];
-};
-// read zip64 extra field
-var z64e = function (d, b) {
-    for (; b2(d, b) != 1; b += 4 + b2(d, b + 2))
-        ;
-    return [b8(d, b + 12), b8(d, b + 4), b8(d, b + 20)];
-};
-/**
- * Synchronously decompresses a ZIP archive. Prefer using `unzip` for better
- * performance with more than one file.
- * @param data The raw compressed ZIP file
- * @param opts The ZIP extraction options
- * @returns The decompressed files
- */
-function unzipSync(data, opts) {
-    var files = {};
-    var e = data.length - 22;
-    for (; b4(data, e) != 0x6054B50; --e) {
-        if (!e || data.length - e > 65558)
-            err$1(13);
-    }
-    var c = b2(data, e + 8);
-    if (!c)
-        return {};
-    var o = b4(data, e + 16);
-    var z = o == 4294967295 || c == 65535;
-    if (z) {
-        var ze = b4(data, e - 12);
-        z = b4(data, ze) == 0x6064B50;
-        if (z) {
-            c = b4(data, ze + 32);
-            o = b4(data, ze + 48);
-        }
-    }
-    var fltr = opts && opts.filter;
-    for (var i = 0; i < c; ++i) {
-        var _a = zh(data, o, z), c_2 = _a[0], sc = _a[1], su = _a[2], fn = _a[3], no = _a[4], off = _a[5], b = slzh(data, off);
-        o = no;
-        if (!fltr || fltr({
-            name: fn,
-            size: sc,
-            originalSize: su,
-            compression: c_2
-        })) {
-            if (!c_2)
-                files[fn] = slc$1(data, b, b + sc);
-            else if (c_2 == 8)
-                files[fn] = inflateSync(data.subarray(b, b + sc), new u8$1(su));
-            else
-                err$1(14, 'unknown compression type ' + c_2);
-        }
-    }
-    return files;
-}
-
-var vert_2d = "#define GLSLIFY 1\nuniform vec2 size;out vec2 vUv;void main(){gl_Position=projectionMatrix*modelViewMatrix*vec4(position,1.0);vUv.xy=position.xy/size+0.5;vUv.y=1.0-vUv.y;}"; // eslint-disable-line
-
-var frag_2d = "precision highp float;precision highp int;precision highp sampler2DArray;\n#define GLSLIFY 1\nuniform sampler2DArray diffuse;in vec2 vUv;uniform int depth;out vec4 outColor;void main(){vec4 color=texture(diffuse,vec3(vUv,depth));outColor=vec4(color.rrr*1.5,1.0);}"; // eslint-disable-line
+var frag_2d = "precision highp float;precision highp int;precision highp sampler2DArray;\n#define GLSLIFY 1\nuniform sampler2DArray diffuse;in vec2 vUv;uniform int depth;uniform float uOpacity;out vec4 outColor;void main(){vec4 color=texture(diffuse,vec3(vUv,depth));outColor=vec4(color.rrr*1.5,uOpacity);}"; // eslint-disable-line
 
 let planeWidth = 80;
 let planeHeight = 80;
-function createTexture2D_Zip(url, scene) {
-    new FileLoader()
-        .setResponseType("arraybuffer")
-        .load(url, function (data) {
-        const zip = unzipSync(new Uint8Array(data));
-        const array = new Uint8Array(zip["head256x256x109"].buffer);
-        const texture = new DataArrayTexture(array, 256, 256, 109);
-        texture.format = RedFormat;
-        texture.needsUpdate = true;
-        const material = new ShaderMaterial({
-            uniforms: {
-                diffuse: { value: texture },
-                depth: { value: 1 },
-                size: { value: new Vector2(planeWidth, planeHeight) },
-            },
-            vertexShader: vert_2d,
-            fragmentShader: frag_2d,
-            glslVersion: GLSL3,
-            side: DoubleSide,
-        });
-        const geometry = new PlaneGeometry(planeWidth, planeHeight);
-        const mesh = new Mesh(geometry, material);
-        mesh.name = "texture2d_mesh_zip";
-        scene.add(mesh);
-    });
+// Build a quad from the 4 world-space image-plane corners (preserves real pose).
+function buildAlignedQuad(c) {
+    const g = new BufferGeometry();
+    // two triangles: tl,bl,tr / tr,bl,br
+    g.setAttribute("position", new BufferAttribute(new Float32Array([...c.tl, ...c.bl, ...c.tr, ...c.tr, ...c.bl, ...c.br]), 3));
+    // vertex order is tl, bl, tr, tr, bl, br. The fragment shader flips v (vUv.y = 1-uv.y)
+    // and DataArrayTexture has no flipY, so the image-top (data row 0) must map to the
+    // top world corner: tl/tr get uv.y = 1.
+    g.setAttribute("uv", new BufferAttribute(new Float32Array([0, 1, 0, 0, 1, 1, 1, 1, 0, 0, 1, 0]), 2));
+    g.computeVertexNormals();
+    return g;
 }
 function createTexture2D_NRRD(data, width, height, depth, callback) {
     const texture = new DataArrayTexture(data, width, height, depth);
@@ -41401,7 +40955,7 @@ function createTexture2D_NRRD(data, width, height, depth, callback) {
         uniforms: {
             diffuse: { value: texture },
             depth: { value: 1 },
-            size: { value: new Vector2(planeWidth, planeHeight) },
+            uOpacity: { value: 1 },
         },
         vertexShader: vert_2d,
         fragmentShader: frag_2d,
@@ -41413,13 +40967,9 @@ function createTexture2D_NRRD(data, width, height, depth, callback) {
     mesh.name = "texture2d_mesh_zip";
     callback(mesh);
 }
-function createTexture2D_Array(copperVolume, depth, scene, gui) {
+function createTexture2D_Array(copperVolume, depth, scene, gui, aligned = false) {
     planeWidth = copperVolume.width / 2;
     planeHeight = copperVolume.height / 2;
-    ({
-        windowWidth: copperVolume.windowWidth,
-        windowCenter: copperVolume.windowCenter,
-    });
     const texture = new DataArrayTexture(copperVolume.uint8, copperVolume.width, copperVolume.height, depth);
     texture.format = RedFormat;
     texture.needsUpdate = true;
@@ -41446,18 +40996,22 @@ function createTexture2D_Array(copperVolume, depth, scene, gui) {
     const material = new ShaderMaterial({
         uniforms: {
             diffuse: { value: texture },
-            depth: { value: 1 },
-            size: { value: new Vector2(planeWidth, planeHeight) },
+            depth: { value: 0 },
+            uOpacity: { value: 1 },
         },
         vertexShader: vert_2d,
         fragmentShader: frag_2d,
         glslVersion: GLSL3,
         side: DoubleSide,
     });
-    const geometry = new PlaneGeometry(planeWidth, planeHeight);
+    // Aligned world-space quad only when explicitly requested and geometry tags exist;
+    // otherwise the legacy centred plane (keeps existing loadDicom behaviour unchanged).
+    const geometry = aligned && copperVolume.corners
+        ? buildAlignedQuad(copperVolume.corners)
+        : new PlaneGeometry(planeWidth, planeHeight);
     const mesh = new Mesh(geometry, material);
-    scene.add(mesh);
     mesh.name = "texture2d_mesh_array";
+    scene.add(mesh);
     function updateTexture(copperVolumeUp) {
         if (!!copperVolumeUp) {
             let voiLUT;
@@ -41468,7 +41022,15 @@ function createTexture2D_Array(copperVolume, depth, scene, gui) {
             texture.needsUpdate = true;
         }
     }
-    return { mesh, copperVolume, updateTexture };
+    function setFrame(i) {
+        material.uniforms.depth.value = i;
+    }
+    function setWindow(center, width) {
+        copperVolume.windowCenter = center;
+        copperVolume.windowWidth = width;
+        updateTexture(copperVolume);
+    }
+    return { mesh, copperVolume, updateTexture, setFrame, setWindow };
 }
 
 /*!
@@ -59300,6 +58862,7 @@ function onTouchEnd( event ) {
 }
 
 class copperScene extends baseScene {
+    // rayster pick
     constructor(container, renderer, opt) {
         super(container, renderer, opt);
         this.clock = new Clock();
@@ -59307,9 +58870,6 @@ class copperScene extends baseScene {
         this.mixer = null;
         this.playRate = 1.0;
         this.modelReady = false;
-        // rayster pick
-        // texture2d
-        this.texture2dMesh = null;
         if ((opt === null || opt === void 0 ? void 0 : opt.controls) === "trackball") {
             this.controls = new TrackballControls(this.camera, this.renderer.domElement);
         }
@@ -59515,38 +59075,177 @@ class copperScene extends baseScene {
             this.exportContent.animations.push(clip);
         };
     }
-    // texture2d
-    texture2d(url) {
-        createTexture2D_Zip(url, this.scene);
-        const textureInterval = setInterval(() => {
-            var _a;
-            this.scene.children.forEach((child) => {
-                if (child.isMesh) {
-                    if (child.name === "texture2d_mesh_zip") {
-                        this.texture2dMesh = child;
-                        const render_texture2d = () => {
-                            if (this.texture2dMesh) {
-                                let value = this.texture2dMesh.material.uniforms["depth"].value;
-                                value += this.depthStep;
-                                if (value > 109.0 || value < 0.0) {
-                                    if (value > 1.0)
-                                        value = 109.0 * 2.0 - value;
-                                    if (value < 0.0)
-                                        value = -value;
-                                    this.depthStep = -this.depthStep;
-                                }
-                                this.texture2dMesh.material.uniforms["depth"].value =
-                                    value;
-                            }
-                        };
-                        this.addPreRenderCallbackFunction(render_texture2d);
-                    }
-                }
+    /**
+     * Load an aligned 4D scene: a cine MRI (one slice, N cardiac phases) rendered as a
+     * world-placed plane, plus 0..N deforming surface sequences (e.g. LV endo/epi). MRI
+     * and surfaces stay in their shared patient coordinate frame (no center/scale), and
+     * advance together off ONE shared frame clock. Returns a controller (play/pause/...).
+     */
+    loadAligned4D(opts, callback) {
+        var _a;
+        const dicomDepth = opts.dicomUrls.length;
+        const loadDicomStack = () => new Promise((resolve) => {
+            const volumes = [];
+            opts.dicomUrls.forEach((url) => {
+                copperDicomLoader(url, (volume) => {
+                    volumes.push(volume);
+                    if (volumes.length !== dicomDepth)
+                        return;
+                    // order frames by cardiac phase (TriggerTime / SliceLocation)
+                    volumes.sort((a, b) => a.order - b.order);
+                    const frameSize = volumes[0].width * volumes[0].height;
+                    const uint8 = new Uint8ClampedArray(frameSize * dicomDepth);
+                    const uint16 = new Uint16Array(uint8.length);
+                    volumes.forEach((v, index) => {
+                        uint8.set(v.uint8, index * frameSize);
+                        uint16.set(v.uint16, index * frameSize);
+                    });
+                    const stacked = Object.assign(Object.assign({}, volumes[0]), { uint8,
+                        uint16 });
+                    resolve(stacked);
+                });
             });
-            if (((_a = this.texture2dMesh) === null || _a === void 0 ? void 0 : _a.name) === "texture2d_mesh_zip") {
-                clearInterval(textureInterval);
+        });
+        const loadSurfaceSequence = (urls) => new Promise((resolve) => {
+            const loader = new VTKLoader();
+            const geometries = new Array(urls.length);
+            let done = 0;
+            urls.forEach((url, index) => {
+                loader.load(url, (geometry) => {
+                    // keep world coordinates — no center()/scale()
+                    geometry.computeVertexNormals();
+                    geometries[index] = geometry;
+                    if (++done === urls.length)
+                        resolve(geometries);
+                });
+            });
+        });
+        const surfaceDefs = (_a = opts.surfaces) !== null && _a !== void 0 ? _a : [];
+        Promise.all([
+            loadDicomStack(),
+            ...surfaceDefs.map((s) => loadSurfaceSequence(s.urls)),
+        ]).then(([stacked, ...surfaceGeoms]) => {
+            var _a;
+            if (opts.window) {
+                stacked.windowCenter = opts.window.center;
+                stacked.windowWidth = opts.window.width;
             }
-        }, 500);
+            const tex = createTexture2D_Array(stacked, dicomDepth, this.scene, undefined, true);
+            tex.setFrame(0);
+            if (opts.window)
+                tex.setWindow(opts.window.center, opts.window.width);
+            const surfaceMeshes = {};
+            const seqs = [];
+            surfaceDefs.forEach((def, i) => {
+                var _a;
+                const geometries = surfaceGeoms[i];
+                const { vtkmaterial } = copperMultipleVtk(def.opts);
+                const mesh = new Mesh(geometries[0], vtkmaterial);
+                mesh.name = def.name;
+                this.scene.add(mesh);
+                surfaceMeshes[def.name] = mesh;
+                seqs.push({ mesh, geometries, offset: (_a = def.offset) !== null && _a !== void 0 ? _a : 0 });
+            });
+            const frameCount = dicomDepth;
+            // Default one cardiac cycle ≈ 1012ms (32 phases × ~31.6ms) unless overridden.
+            const cycleMs = (_a = opts.cycleMs) !== null && _a !== void 0 ? _a : 1012;
+            let frameIndex = 0;
+            let speed = 1;
+            let playing = true;
+            let disposed = false;
+            let lastStep = performance.now();
+            const dtBase = cycleMs / frameCount;
+            const applyFrame = () => {
+                tex.setFrame(frameIndex);
+                for (const s of seqs) {
+                    const i = (frameIndex + s.offset + s.geometries.length) % s.geometries.length;
+                    s.mesh.geometry = s.geometries[i];
+                }
+            };
+            const tick = () => {
+                if (disposed || !playing)
+                    return;
+                const now = performance.now();
+                if (now - lastStep >= dtBase / speed) {
+                    lastStep = now;
+                    frameIndex = (frameIndex + 1) % frameCount;
+                    applyFrame();
+                }
+            };
+            this.addPreRenderCallbackFunction(tick);
+            const clockId = tick.id;
+            const ctrl = {
+                plane: tex.mesh,
+                surfaceMeshes,
+                frameCount,
+                play: () => {
+                    playing = true;
+                    lastStep = performance.now();
+                },
+                pause: () => {
+                    playing = false;
+                },
+                toggle: () => {
+                    playing = !playing;
+                    lastStep = performance.now();
+                },
+                setSpeed: (x) => {
+                    speed = Math.max(0.01, x);
+                },
+                setFrame: (i) => {
+                    frameIndex = ((i % frameCount) + frameCount) % frameCount;
+                    applyFrame();
+                },
+                setFrameOffset: (name, n) => {
+                    const s = seqs.find((q) => q.mesh.name === name);
+                    if (s) {
+                        s.offset = n;
+                        applyFrame();
+                    }
+                },
+                setWindow: (center, width) => {
+                    tex.setWindow(center, width);
+                },
+                setPlaneOpacity: (v) => {
+                    const m = tex.mesh.material;
+                    m.transparent = v < 1;
+                    m.uniforms.uOpacity.value = v;
+                    m.needsUpdate = true;
+                },
+                setSurfaceOpacity: (name, v) => {
+                    const mesh = surfaceMeshes[name];
+                    if (!mesh)
+                        return;
+                    const m = mesh.material;
+                    m.transparent = v < 1;
+                    m.opacity = v;
+                    m.needsUpdate = true;
+                },
+                setSurfaceVisible: (name, visible) => {
+                    const mesh = surfaceMeshes[name];
+                    if (mesh)
+                        mesh.visible = visible;
+                },
+                dispose: () => {
+                    var _a, _b;
+                    disposed = true;
+                    this.removePreRenderCallbackFunction(clockId);
+                    // plane
+                    this.scene.remove(tex.mesh);
+                    tex.mesh.geometry.dispose();
+                    const pm = tex.mesh.material;
+                    (_b = (_a = pm.uniforms.diffuse.value) === null || _a === void 0 ? void 0 : _a.dispose) === null || _b === void 0 ? void 0 : _b.call(_a);
+                    pm.dispose();
+                    // surfaces
+                    for (const s of seqs) {
+                        this.scene.remove(s.mesh);
+                        s.geometries.forEach((g) => g.dispose());
+                        s.mesh.material.dispose();
+                    }
+                },
+            };
+            callback && callback(ctrl);
+        });
     }
     getPlayRate() {
         return this.playRate;
@@ -59652,8 +59351,11 @@ class copperRenderer extends baseRenderer {
         this.delta = 0;
         this.interval = 1 / this.fps;
         this.preRenderCallbackFunctions = [];
+        this.running = true;
         this.animate = (time) => {
             var _a, _b, _c;
+            if (!this.running)
+                return;
             switch ((_a = this.options) === null || _a === void 0 ? void 0 : _a.fpsMode) {
                 case "1":
                     // fpsControl one: 30fps
@@ -59680,6 +59382,10 @@ class copperRenderer extends baseRenderer {
             }
         };
     }
+    // Stop the render loop (call on teardown to release the RAF and let GC reclaim).
+    stop() {
+        this.running = false;
+    }
     getSceneByName(name) {
         return this.sceneMap[name];
     }
@@ -78410,6 +78116,12 @@ class NrrdTools {
             updateWindowLow: this.guiParameterSettings.windowLow.onChange,
             finishContrastAdjustment: this.guiParameterSettings.windowHigh.onFinished,
         };
+        // setupGUI may run AFTER images are loaded (e.g. the register/origin-switch load
+        // path), in which case the on-load syncGuiParameterSettings() ran while
+        // guiParameterSettings was still undefined and silently skipped the binding. Bind
+        // now so the window slider reflects the current volume's real min/max/window instead
+        // of the default 0/0 (which froze the slider and turned the image white on zoom).
+        this.syncGuiParameterSettings();
     }
     /**
      * Sync guiParameterSettings with current volume metadata.
@@ -79442,7 +79154,7 @@ function evaluateElement(element, weights) {
 }
 
 // import * as kiwrious from "copper3d_plugin_heart_k";
-const REVISION = "v3.4.7-beta";
+const REVISION = "v3.4.9-beta";
 console.log(`%cCopper3D Visualisation %cBeta:${REVISION}`, "padding: 3px;color:white; background:#023047", "padding: 3px;color:white; background:#f50a25");
 
 export { CHANNEL_COLORS, CHANNEL_HEX_COLORS, CameraViewPoint, Copper3dTrackballControls, GaussianSmoother, MeshNodeTool, NrrdTools, REVISION, addBoxHelper, addLabelToScene, configKiwriousHeart, convert3DPostoScreenPos, convertScreenPosto3DPos, copperMScene, copperMSceneRenderer, copperRenderer, copperRendererOnDemond, copperScene, copperSceneOnDemond, createTexture2D_NRRD, fullScreenListenner, kiwrious, loading, removeGuiFolderChilden, rgbaToCss, rgbaToHex, setHDRFilePath, throttle };