@vitessce/spatial-accelerated 3.8.0

package/dist-tsc/VolumeDataManager.js

@@ -0,0 +1,1273 @@
+/* eslint-disable no-bitwise */
+/* eslint-disable no-underscore-dangle */
+/* eslint-disable max-len */
+/* eslint-disable no-unused-vars */
+/* eslint-disable camelcase */
+import { Data3DTexture, RedFormat, RedIntegerFormat, UnsignedByteType, UnsignedIntType, LinearFilter, NearestFilter, } from 'three';
+import { isEqual } from 'lodash-es';
+import { log, atLeastLogLevel, LogLevel } from '@vitessce/globals';
+// NOTES:
+// 2048 x 2048 x 32 = 4096 bricks, around 134 MB
+// 2048 x 2048 x 64 = 8192 bricks, around 268 MB
+// 2048 x 2048 x 128 = 16384 bricks, around 537 MB **
+// 2048 x 2048 x 256 = 32768 bricks, around 1.074 GB
+// 2048 x 2048 x 512 = 65536 bricks, around 2.148 GB
+// 2048 x 2048 x 1024 = 131072 bricks, around 4.295 GB
+// Default chunk sizes
+// const CHUNK_SIZE = 32;
+// const CHUNK_TOTAL_SIZE = 32768; // 32*32*32 = 32768
+const BRICK_SIZE = 32;
+const BRICK_CACHE_SIZE_X = 64;
+const BRICK_CACHE_SIZE_Y = 64;
+const BRICK_CACHE_SIZE_Z = 4;
+const TOTAL_NUM_BRICKS = BRICK_CACHE_SIZE_X * BRICK_CACHE_SIZE_Y * BRICK_CACHE_SIZE_Z;
+const BRICK_CACHE_SIZE_VOXELS_X = BRICK_CACHE_SIZE_X * BRICK_SIZE;
+const BRICK_CACHE_SIZE_VOXELS_Y = BRICK_CACHE_SIZE_Y * BRICK_SIZE;
+const BRICK_CACHE_SIZE_VOXELS_Z = BRICK_CACHE_SIZE_Z * BRICK_SIZE;
+const PAGE_TABLE_ADDRESS_SIZE = 'uint32';
+const BRICK_CACHE_ADDRESS_SIZE = 'uint16';
+const MAX_RESOLUTION_LEVELS = 10; // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+const MAX_CHANNELS = 7; // [0, 1, 2, 3, 4, 5, 6]
+// const manualChannelSelection = 0;
+// Add a constant for initialization status
+const INIT_STATUS = {
+    NOT_STARTED: 'not_started',
+    IN_PROGRESS: 'in_progress',
+    COMPLETE: 'complete',
+    FAILED: 'failed',
+};
+function logWithColor(message) {
+    if (atLeastLogLevel(LogLevel.DEBUG)) {
+        console.warn(`%cDM: ${message}`, 'background: blue; color: white; padding: 2px; border-radius: 3px;');
+    }
+}
+/* Begin extracted functions */
+export function _resolutionStatsToShapes(multiResolutionStats) {
+    return multiResolutionStats.map((stats) => {
+        const { dims } = stats;
+        const shape = [
+            // Other spatial-accelerated code assumes TCZYX dimension order
+            dims.t, // TODO: standardize lowercase/uppercase dim names at store-level
+            dims.c, // TODO: handle case when dimension(s) are missing
+            dims.z,
+            dims.y,
+            dims.x,
+        ];
+        return shape;
+    });
+}
+export function _resolutionStatsToBrickLayout(multiResolutionStats) {
+    return multiResolutionStats.map((stats) => {
+        const shape = [
+            stats.depth, // z
+            stats.height, // y
+            stats.width, // x
+        ];
+        // TODO: abstract chunkSize to always be 32x32x32 at store-level
+        // const chunkSize = array0.chunks || [BRICK_SIZE, BRICK_SIZE, BRICK_SIZE];
+        return [
+            Math.ceil((shape[0] || 1) / BRICK_SIZE),
+            Math.ceil((shape[1] || 1) / BRICK_SIZE),
+            Math.ceil((shape[2] || 1) / BRICK_SIZE),
+        ];
+    });
+}
+/**
+ *
+ * @param {[number, number, number][]} zarrStoreBrickLayout
+ * @param {number} channelsZarrMappingsLength
+ */
+export function _initMRMCPT(zarrStoreBrickLayout, channelsZarrMappingsLength) {
+    log.debug('_initMRMCPT', zarrStoreBrickLayout, channelsZarrMappingsLength);
+    // Page table
+    const PT = {
+        channelOffsets: [
+            [0, 0, 1],
+            [0, 1, 0],
+            [0, 1, 1],
+            [1, 0, 0],
+            [1, 0, 1],
+            [1, 1, 0],
+            [1, 1, 1],
+        ],
+        anchors: [],
+        offsets: [],
+        xExtent: 0, // includes the offset inclusive
+        yExtent: 0, // includes the offset inclusive
+        zExtent: 0, // includes the offset inclusive
+        z0Extent: 0, // l0 z extent
+        zTotal: 0, // original z extent plus the l0 z extent times the channel count
+    };
+    // Calculate PT extents first
+    PT.xExtent = 1;
+    PT.yExtent = 1;
+    PT.zExtent = 1;
+    const l0z = zarrStoreBrickLayout[0][0]; // Get z extent from highest resolution
+    PT.z0Extent = l0z;
+    // log.debug('PT', PT);
+    // log.debug('PT anchors', PT.anchors);
+    // log.debug('PT anchors with 0', PT.anchors);
+    PT.lowestDataRes = zarrStoreBrickLayout.length - 1;
+    // log.debug('lowestDataRes', PT.lowestDataRes);
+    // Sum up the extents from all resolution levels excluding the l0
+    for (let i = zarrStoreBrickLayout.length - 1; i > 0; i--) {
+        PT.anchors.push([
+            PT.xExtent,
+            PT.yExtent,
+            PT.zExtent,
+        ]);
+        PT.xExtent += zarrStoreBrickLayout[i][2];
+        PT.yExtent += zarrStoreBrickLayout[i][1];
+        PT.zExtent += zarrStoreBrickLayout[i][0];
+    }
+    PT.anchors.push([0, 0, PT.zExtent]);
+    PT.anchors.reverse();
+    // log.debug('PT anchors', PT.anchors);
+    // Calculate total Z extent including channel offsets
+    // PT.zTotal = PT.zExtent + (this.zarrStore.channelCount * l0z);
+    PT.zTotal = PT.zExtent + channelsZarrMappingsLength * l0z;
+    // log.debug('number of PT channels', channelsZarrMappingsLength);
+    // log.debug('Page Table Extents:', {
+    //   x: PT.xExtent,
+    //   y: PT.yExtent,
+    //   z: PT.zExtent,
+    //   z0: PT.z0Extent,
+    //   zTotal: PT.zTotal,
+    // });
+    // Initialize the BrickCache as a 3D texture (uint8)
+    const brickCacheData = new Uint8Array(BRICK_CACHE_SIZE_VOXELS_X
+        * BRICK_CACHE_SIZE_VOXELS_Y
+        * BRICK_CACHE_SIZE_VOXELS_Z);
+    brickCacheData.fill(0);
+    // Initialize the PageTable data using calculated extents
+    const pageTableData = new Uint32Array(PT.xExtent * PT.yExtent * PT.zTotal);
+    pageTableData.fill(0);
+    const bcTHREE = new Data3DTexture(brickCacheData, BRICK_CACHE_SIZE_VOXELS_X, BRICK_CACHE_SIZE_VOXELS_Y, BRICK_CACHE_SIZE_VOXELS_Z);
+    bcTHREE.format = RedFormat;
+    bcTHREE.type = UnsignedByteType;
+    bcTHREE.internalFormat = 'R8';
+    // bcTHREE.minFilter = NearestFilter;
+    // bcTHREE.magFilter = NearestFilter;
+    bcTHREE.minFilter = LinearFilter;
+    bcTHREE.magFilter = LinearFilter;
+    bcTHREE.generateMipmaps = false;
+    bcTHREE.needsUpdate = true;
+    const ptTHREE = new Data3DTexture(pageTableData, PT.xExtent, PT.yExtent, PT.zTotal);
+    ptTHREE.format = RedIntegerFormat;
+    ptTHREE.type = UnsignedIntType;
+    ptTHREE.internalFormat = 'R32UI';
+    ptTHREE.minFilter = NearestFilter;
+    ptTHREE.magFilter = NearestFilter;
+    ptTHREE.generateMipmaps = false;
+    ptTHREE.needsUpdate = true;
+    log.debug('_initMRMCPT', PT, ptTHREE, bcTHREE);
+    return {
+        PT,
+        ptTHREE,
+        bcTHREE,
+    };
+}
+/* ------------------------------------------------------------- *
+ * 3. Pack PT entry (flags | min | max | bcX | bcY | bcZ)        *
+ * ------------------------------------------------------------- */
+export function _packPT(min, max, bcX, bcY, bcZ) {
+    // Scale down to 7-bit range (0-127) by dividing by 2
+    const clamp7 = v => Math.max(0, Math.min(127, Math.floor(v / 2)));
+    // log.debug('Scaled min/max:', clamp7(min), clamp7(max));
+    return ((1 << 31) // bit‑31 = resident
+        | (1 << 30) // bit‑30 = init‑done
+        | (clamp7(min) << 23) // 7 bits
+        | (clamp7(max) << 16) // 7 bits
+        | ((bcX & 0x3F) << 10) // 6 bits
+        | ((bcY & 0x3F) << 4) // 6 bits
+        | (bcZ & 0x0F) // 4 bits
+    ) >>> 0; // keep unsigned
+}
+// Pack PT entry indicating "not resident but init" with min/max preserved
+// Note: this is not used anywhere?
+/*
+export function _packPTNotResident(min, max, bcX, bcY, bcZ) {
+  // Scale down to 7-bit range (0-127) by dividing by 2
+  const clamp7 = v => Math.max(0, Math.min(127, Math.floor(v / 2)));
+
+  return (
+    (0 << 31) // bit-31 = NOT resident
+    | (1 << 30) // bit-30 = init-done
+    | (clamp7(min) << 23) // 7 bits
+    | (clamp7(max) << 16) // 7 bits
+    | ((bcX & 0x3F) << 10) // 6 bits
+    | ((bcY & 0x3F) << 4) // 6 bits
+    | (bcZ & 0x0F) // 4 bits
+  ) >>> 0; // keep unsigned
+}
+*/
+export function _ptToZarr(ptx, pty, ptz, ptInfo) {
+    const { PT_zExtent, PT_z0Extent, PT_anchors } = ptInfo;
+    let channel = -1;
+    let resolution = -1;
+    let x = -1;
+    let y = -1;
+    let z = -1;
+    // log.debug('pt', ptx, pty, ptz);
+    // log.debug('pt', ptx, pty, ptz);
+    // log.debug('ptz', this.PT.z, this.PT.l0z);
+    if (ptz >= PT_zExtent) {
+        // log.debug('ptz >= this.PT.zExtent');
+        resolution = 0;
+        x = ptx;
+        y = pty;
+        z = (ptz - PT_zExtent) % PT_z0Extent;
+        channel = Math.floor((ptz - PT_zExtent) / PT_z0Extent);
+    }
+    else {
+        // log.debug('ptz < this.PT.zExtent');
+        // log.debug('this.PT.anchors', this.PT.anchors);
+        for (let i = 1; i < PT_anchors.length; i++) {
+            if (ptx < PT_anchors[i][0] && pty < PT_anchors[i][1] && ptz < PT_anchors[i][2]) {
+                // all PT coordinates are less than the anchor -> one res lower
+                // log.debug('all PT coordinates are less than the anchor -> one res lower');
+            }
+            else {
+                // log.debug('not all PT coordinates are less than the anchor ', this.PT.anchors[i]);
+                resolution = i;
+                const channelMask = [0, 0, 0];
+                // log.debug('ptx', ptx);
+                // log.debug('pty', pty);
+                // log.debug('ptz', ptz);
+                // log.debug('this.PT.anchors[i]', this.PT.anchors[i]);
+                if (ptx >= PT_anchors[i][0]) {
+                    channelMask[0] = 1;
+                }
+                if (pty >= PT_anchors[i][1]) {
+                    channelMask[1] = 1;
+                }
+                if (ptz >= PT_anchors[i][2]) {
+                    channelMask[2] = 1;
+                }
+                const binaryChannel = (channelMask[0] << 2) | (channelMask[1] << 1) | channelMask[2];
+                channel = Math.max(1, Math.min(7, binaryChannel)) - 1;
+                // log.debug('channel', channel);
+                const thisOffset = channelMask.map((v, j) => v * PT_anchors[i][j]);
+                // log.debug('thisOffset', thisOffset);
+                x = ptx - thisOffset[0];
+                y = pty - thisOffset[1];
+                z = ptz - thisOffset[2];
+                // log.debug('x', x);
+                // log.debug('y', y);
+                // log.debug('z', z);
+                break;
+            }
+        }
+    }
+    // log.debug(channel, resolution, x, y, z);
+    return {
+        channel,
+        resolution,
+        x,
+        y,
+        z,
+    };
+}
+export function _requestBufferToRequestObjects(buffer, k) {
+    const counts = new Map();
+    for (let i = 0; i < buffer.length; i += 4) {
+        const r = buffer[i];
+        const g = buffer[i + 1];
+        const b = buffer[i + 2];
+        const a = buffer[i + 3];
+        if ((r | g | b | a) === 0) {
+            // eslint-disable-next-line no-continue
+            continue;
+        }
+        const packed = ((r << 24) | (g << 16) | (b << 8) | a) >>> 0;
+        counts.set(packed, (counts.get(packed) || 0) + 1);
+    }
+    // log.debug('counts', counts);
+    // log.debug('this.k', this.k);
+    // Get the top K (potentially fewer than K) page table requests.
+    const requests = [...counts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, k)
+        .map(([packed]) => ({
+        x: (packed >> 22) & 0x3FF,
+        y: (packed >> 12) & 0x3FF,
+        z: packed & 0xFFF,
+    }));
+    return { requests, origRequestCount: counts.size };
+}
+/* End extracted functions */
+export class VolumeDataManager {
+    constructor(glParam) {
+        logWithColor('CLASS INITIALIZING');
+        // this.store = new zarrita.FetchStore(url); // TODO: use this.images instead
+        const gl = glParam.getContext?.() || glParam;
+        const renderer = glParam;
+        // this.images = images;
+        // this.imageLayerScopes = imageLayerScopes;
+        // Handle both WebGLRenderer and WebGL context
+        if (gl.domElement && gl.getContext) {
+            // This is likely a THREE.WebGLRenderer
+            this.gl = gl.getContext();
+        }
+        else if (gl.isWebGLRenderer) {
+            // Explicit THREE.WebGLRenderer check
+            this.gl = gl.getContext();
+        }
+        else {
+            // Assume it's already a WebGL context
+            this.gl = gl;
+        }
+        // const maxFragmentUniformVectors = this.gl.getParameter(this.gl.MAX_FRAGMENT_UNIFORM_VECTORS);
+        // log.debug('maxFragmentUniformVectors', maxFragmentUniformVectors);
+        // 1024
+        this.renderer = renderer;
+        // Create a mock context if we couldn't get a real one
+        if (!this.gl || typeof this.gl.getParameter !== 'function') {
+            log.debug('Unable to get WebGL context, using mock context');
+            this.gl = {
+                getParameter: (param) => {
+                    // Return reasonable defaults
+                    const defaults = {
+                        MAX_TEXTURE_SIZE: 4096,
+                        MAX_3D_TEXTURE_SIZE: 256,
+                        MAX_RENDERBUFFER_SIZE: 4096,
+                        MAX_UNIFORM_BUFFER_BINDINGS: 16,
+                    };
+                    return defaults[param] || 0;
+                },
+                MAX_TEXTURE_SIZE: 'MAX_TEXTURE_SIZE',
+                MAX_3D_TEXTURE_SIZE: 'MAX_3D_TEXTURE_SIZE',
+                MAX_RENDERBUFFER_SIZE: 'MAX_RENDERBUFFER_SIZE',
+                MAX_UNIFORM_BUFFER_BINDINGS: 'MAX_UNIFORM_BUFFER_BINDINGS',
+            };
+        }
+        log.debug('GL CONSTANTS');
+        log.debug(this.gl);
+        log.debug(this.gl.TEXTURE0);
+        log.debug(this.gl.textures);
+        log.debug('RENDERER');
+        log.debug(this.renderer);
+        this.deviceLimits = {
+            maxTextureSize: this.gl.getParameter(this.gl.MAX_TEXTURE_SIZE),
+            max3DTextureSize: this.gl.getParameter(this.gl.MAX_3D_TEXTURE_SIZE),
+            maxRenderbufferSize: this.gl.getParameter(this.gl.MAX_RENDERBUFFER_SIZE),
+            maxUniformBufferBindings: this.gl.getParameter(this.gl.MAX_UNIFORM_BUFFER_BINDINGS),
+        };
+        this.zarrStore = {
+            resolutions: null, // 6 (the number of resolutions aka. pyramid levels in the file)
+            chunkSize: [], // [32, 32, 32]
+            shapes: [], // [[795, 1024, 1024], ..., [64, 64, 64], [32, 32, 32]]
+            arrays: [], // [array0, array1, array2, array3, array4, array5]
+            dtype: '', // 'uint8'
+            physicalSizeTotal: [], // [795 x 0.0688, 1024 x 0.03417, 1024 x 0.03417]
+            physicalSizeVoxel: [], // [0.0688, 0.03417, 0.03417]
+            brickLayout: [], // [[25, 32, 32],[13, 16, 16], ..., [2,2,2],[1,1,1]]
+            // store: '', // ref to this.store
+            // group: '', // ref to this.group
+            channelCount: 1, // MAX 7 TODO: get from zarr metadata
+            scales: [], // downsample ratios, [x,y,z] per resolution level
+            lowestDataRes: 0, // lowest resolution level with data
+        };
+        this.ptTHREE = null;
+        this.bcTHREE = null;
+        this.channels = {
+            maxChannels: 7, // lower when dataset has fewer, dictates page table size
+            zarrMappings: [], // stores the zarr channel index for every one of the up to 7 channels
+            colorMappings: [], // stores the PT slot for every color
+            downsampleMin: [], // stores the downsample min for every one of the up to 7 channels
+            downsampleMax: [], // stores the downsample max for every one of the up to 7 channels
+        };
+        this.PT = {
+            channelOffsets: [
+                [0, 0, 1],
+                [0, 1, 0],
+                [0, 1, 1],
+                [1, 0, 0],
+                [1, 0, 1],
+                [1, 1, 0],
+                [1, 1, 1],
+            ],
+            anchors: [],
+            offsets: [],
+            xExtent: 0, // includes the offset inclusive
+            yExtent: 0, // includes the offset inclusive
+            zExtent: 0, // includes the offset inclusive
+            z0Extent: 0, // l0 z extent
+            zTotal: 0, // original z extent plus the l0 z extent times the channel count
+        };
+        // this.minimumMin = 255;
+        // this.maximumMin = 0;
+        // this.minimumMax = 255;
+        // this.maximumMax = 0;
+        // this.bricksAllocated = 0;
+        this.bricksEverLoaded = new Set();
+        // Properties for volume rendering
+        // this.originalScale = [1, 1, 1]; // Original dimensions
+        // this.physicalScale = [{ size: 1 }, { size: 1 }, { size: 2.1676 }]; // Physical size scaling
+        // this.physicalScale = [{ size: 1 }, { size: 1 }, { size: 1 }]; // Physical size scaling
+        // this.testArray = [];
+        // this.ptArray = [];
+        // this.ptManOffsets = [];
+        // top k page table addresses
+        // this.requestsStack = [];
+        this.isBusy = false;
+        // brick cache structure for internal calculations
+        this.BCTimeStamps = new Array(TOTAL_NUM_BRICKS).fill(0);
+        this.BCMinMax = new Array(TOTAL_NUM_BRICKS).fill([0, 0]);
+        this.BCFull = false;
+        this.BCUnusedIndex = 0;
+        // brick cache to page table mapping
+        this.bc2pt = new Array(TOTAL_NUM_BRICKS).fill(null);
+        // top k unused brick cache addresses
+        this.LRUStack = [];
+        // this.LRUReady = false;
+        this.triggerUsage = true;
+        this.triggerRequest = false;
+        this.timeStamp = 0;
+        this.k = 40;
+        this.noNewRequests = false;
+        this.needsBailout = false; // Flag to indicate if we need to bail out of processing requests
+        // Add initialization status
+        this.initStatus = INIT_STATUS.NOT_STARTED;
+        this.initError = null;
+        logWithColor('VolumeDataManager constructor complete');
+    }
+    initImages(images, imageLayerScopes) {
+        logWithColor('INIT IMAGES');
+        this.images = images;
+        this.imageLayerScopes = imageLayerScopes;
+    }
+    /**
+     * Initialize the VolumeDataManager with Zarr store details and device limits
+     * This should be called ONCE at website initialization
+     * TODO(mark): merge this with the constructor?
+     * @returns {Promise<Object>} Object with Zarr store details and device limits
+     */
+    async init(config) {
+        logWithColor('INIT()');
+        // Prevent multiple initializations
+        if (this.initStatus !== INIT_STATUS.NOT_STARTED) {
+            log.debug('VolumeDataManager init() was called more than once!');
+            if (this.initStatus === INIT_STATUS.COMPLETE) {
+                // Return existing initialized data
+                return {
+                    success: true,
+                    deviceLimits: this.deviceLimits,
+                    zarrStore: this.zarrStore,
+                    // physicalScale: this.physicalScale,
+                    physicalSizeTotal: this.zarrStore.physicalSizeTotal,
+                    physicalSizeVoxel: this.zarrStore.physicalSizeVoxel,
+                    error: null,
+                };
+            }
+            if (this.initStatus === INIT_STATUS.FAILED) {
+                return {
+                    success: false,
+                    error: this.initError || 'Unknown initialization error',
+                };
+            }
+            // Still in progress, return a pending state
+            return {
+                success: false,
+                pending: true,
+                error: 'Initialization in progress',
+            };
+        }
+        this.initStatus = INIT_STATUS.IN_PROGRESS;
+        logWithColor('INIT() IN PROGRESS');
+        try {
+            // Query Zarr store details
+            // Get all resolution levels
+            const imageWrapper = this.images?.[this.imageLayerScopes?.[0]]?.image?.instance;
+            // TODO(mark): Do not access vivLoader.metadata directly. Generalize to non-NGFF metadata.
+            this.ngffMetadata = imageWrapper.vivLoader.metadata;
+            log.debug('ngffMetadata', this.ngffMetadata);
+            if (!imageWrapper || imageWrapper.getType() !== 'ome-zarr') {
+                throw new Error('Invalid imageWrapper or not an OME-Zarr image');
+            }
+            const multiResolutionStats = imageWrapper.getMultiResolutionStats();
+            const shapes = _resolutionStatsToShapes(multiResolutionStats);
+            const resolutions = multiResolutionStats.length;
+            this.zarrStore.resolutions = resolutions;
+            // TODO: filter to only those resolutions below the 16k x 16x x 4k limit?
+            const vivData = imageWrapper.getData();
+            if (!Array.isArray(vivData) || vivData.length < 1) {
+                throw new Error('Not a multiresolution loader');
+            }
+            if (!isEqual(vivData[0].labels, ['t', 'c', 'z', 'y', 'x'])) {
+                // TODO: relax this and remove the error.
+                throw new Error('Expected OME-Zarr data with dimensions [t, c, z, y, x]');
+            }
+            log.debug('vivData', vivData);
+            // TODO: add a better getter to ImageWrapper to avoid accessing the private _data field here?
+            const arrays = vivData.map(resolutionData => resolutionData._data);
+            const scales = new Array(resolutions).fill(null);
+            // Try to load each resolution level in order
+            /*
+            const loadPromises = [];
+            for (let i = 0; i < resolutions; i++) {
+              loadPromises.push(this.tryLoadResolution(i, arrays));
+            }
+      
+            const results = await Promise.all(loadPromises);
+      
+            log.debug('results', results);
+      
+            // Verify all resolutions were loaded successfully
+            const failedResolutions = results.filter(r => !r.success);
+            if (failedResolutions.length > 0) {
+              throw new Error(`Failed to load ${failedResolutions.length} resolution levels: ${failedResolutions.map(r => r.level).join(', ')}`);
+            }
+      
+            console.info(`Successfully loaded ${resolutions} resolution levels.`);
+            */
+            // console.info('shapes', shapes);
+            // console.info('arrays', arrays);
+            // Get the first array for metadata
+            if (arrays.length > 0) {
+                const array0 = arrays[0];
+                // Update store information
+                this.zarrStore = {
+                    resolutions,
+                    chunkSize: array0.chunks,
+                    shapes,
+                    arrays,
+                    dtype: array0.dtype,
+                    physicalSizeTotal: [], // Will be populated if metadata exists
+                    physicalSizeVoxel: [], // Will be populated if metadata exists
+                    brickLayout: [], // Calculate from shapes and chunk sizes
+                    // store: this.store,
+                    // group: this.group,
+                    channelCount: shapes[0][1],
+                    scales,
+                };
+                // initializing channel mappings and slots as empty
+                this.channels.colorMappings = new Array(Math.min(this.zarrStore.channelCount, 7)).fill(-1);
+                this.channels.zarrMappings = new Array(Math.min(this.zarrStore.channelCount, 7)).fill(undefined);
+                this.channels.downsampleMin = new Array(Math.min(this.zarrStore.channelCount, 7)).fill(undefined);
+                this.channels.downsampleMax = new Array(Math.min(this.zarrStore.channelCount, 7)).fill(undefined);
+                // log.debug('zarrMappings in init', this.channels.zarrMappings);
+                // log.debug('downsampleMin in init', this.channels.downsampleMin);
+                // log.debug('downsampleMax in init', this.channels.downsampleMax);
+                // Extract physical size information if available
+                if (array0.meta && array0.meta.physicalSizes) {
+                    const { x, y, z } = array0.meta.physicalSizes;
+                    // Get size data or use default value of 1
+                    const zSize = z?.size || 1;
+                    const ySize = y?.size || 1;
+                    const xSize = x?.size || 1;
+                    this.zarrStore.physicalSizeVoxel = [zSize, ySize, xSize];
+                    // log.debug('avail physicalSizeVoxel', this.zarrStore.physicalSizeVoxel);
+                    // Calculate total physical size
+                    if (array0.shape && array0.shape.length >= 5) {
+                        this.zarrStore.physicalSizeTotal = [
+                            (array0.shape[2] || 1) * zSize,
+                            (array0.shape[3] || 1) * ySize,
+                            (array0.shape[4] || 1) * xSize,
+                        ];
+                    }
+                }
+                else {
+                    // log.debug('no physicalSizeVoxel');
+                    this.zarrStore.physicalSizeVoxel = [1, 1, 1];
+                    this.zarrStore.physicalSizeTotal = [
+                        array0.shape[2] || 1,
+                        array0.shape[3] || 1,
+                        array0.shape[4] || 1,
+                    ];
+                    // log.debug('default physicalSizeVoxel', this.zarrStore.physicalSizeVoxel);
+                    // log.debug('default physicalSizeTotal', this.zarrStore.physicalSizeTotal);
+                }
+                // log.debug('group.attrs', this.group.attrs);
+                const { multiscales } = this.ngffMetadata;
+                if (!multiscales) {
+                    throw new Error('Expected multiscales metadata in group.attrs');
+                }
+                // Check the per-resolution coordinate transformations
+                if (multiscales?.[0]?.datasets?.[0]?.coordinateTransformations) {
+                    for (let i = 0; i < resolutions; i++) {
+                        if (multiscales?.[0]?.datasets?.[i]?.coordinateTransformations?.[0]?.scale) {
+                            const { scale } = multiscales[0].datasets[i].coordinateTransformations[0];
+                            scales[i] = [scale[4], scale[3], scale[2]];
+                            // log.debug('scale', i, scales[i]);
+                        }
+                    }
+                    // TODO: if the scales are not powers of two, throw an error?
+                }
+                else {
+                    log.error('no coordinateTransformations available, assuming downsampling ratio of 2 per dimension');
+                    for (let i = 0; i < resolutions; i++) {
+                        // 2 to the power of i
+                        const scale = 2 ** i;
+                        scales[i] = [scale, scale, scale];
+                    }
+                }
+                // log.debug('scales', scales);
+                this.zarrStore.scales = scales;
+                // Use the top-level coordinateTransformations scale if available
+                const { coordinateTransformations } = this.ngffMetadata;
+                if (coordinateTransformations?.[0]?.scale) {
+                    const { scale } = coordinateTransformations[0];
+                    // Assuming scale is in format [..., zscale, yscale, xscale]
+                    const scaleLength = scale.length;
+                    if (scaleLength >= 3) {
+                        const zScale = scale[scaleLength - 3];
+                        const yScale = scale[scaleLength - 2];
+                        const xScale = scale[scaleLength - 1];
+                        // Update physicalScale
+                        // this.physicalScale = [
+                        //   { size: xScale },
+                        //   { size: yScale },
+                        //   { size: zScale },
+                        // ];
+                        // log.debug('physicalScale', this.physicalScale);
+                        // Update zarrStore's physicalSizeVoxel
+                        this.zarrStore.physicalSizeVoxel = [zScale, yScale, xScale];
+                        // Calculate total physical size if shape exists
+                        if (array0.shape && array0.shape.length >= 5) {
+                            this.zarrStore.physicalSizeTotal = [
+                                (array0.shape[2] || 1) * zScale,
+                                (array0.shape[3] || 1) * yScale,
+                                (array0.shape[4] || 1) * xScale,
+                            ];
+                        }
+                        // log.debug('Using scale from coordinateTransformations:', this.physicalScale);
+                    }
+                }
+                // Calculate brick layout for each resolution
+                this.zarrStore.brickLayout = _resolutionStatsToBrickLayout(imageWrapper.getMultiResolutionStats());
+                // log.debug('zarrStore', this.zarrStore);
+                // init channel mappings
+                // log.debug('initializing channel mappings');
+                log.debug('config', config);
+                // for each key in config, add to channel mappings
+                const { omero } = this.ngffMetadata || {};
+                if (!omero) {
+                    // TODO(mark): do not use omero metadata directly, use the ImageWrapper channel methods.
+                    throw new Error('Expected omero metadata in ngffMetadata');
+                }
+                log.debug('omero', omero);
+                Object.keys(config).forEach((key, i) => {
+                    const configChannel = config[key].spatialTargetC;
+                    this.channels.zarrMappings[i] = configChannel;
+                    this.channels.colorMappings[i] = i;
+                    this.channels.downsampleMin[i] = omero?.channels?.[configChannel]?.window?.min || 0;
+                    this.channels.downsampleMax[i] = omero?.channels?.[configChannel]?.window?.max || 65535;
+                });
+                log.debug('zarrMappings after init', this.channels.zarrMappings);
+                log.debug('colorMappings after init', this.channels.colorMappings);
+                log.debug('downsampleMin after init', this.channels.downsampleMin);
+                log.debug('downsampleMax after init', this.channels.downsampleMax);
+                // Initialize MRMCPT textures after we have all the necessary information
+                this.initMRMCPT();
+                // this.populateMRMCPT();
+                // this.testTexture();
+            }
+            this.initStatus = INIT_STATUS.COMPLETE;
+            logWithColor('INIT() COMPLETE');
+            // log.debug(this.zarrStore);
+            /*
+            if (this.ngffMetadata.coordinateTransformations
+                && this.ngffMetadata.coordinateTransformations[0]
+                && this.ngffMetadata.coordinateTransformations[0].scale) {
+              // log.debug('scale', this.ngffMetadata.coordinateTransformations[0].scale);
+            }
+            */
+            // Return data that can be displayed in the HUD
+            return {
+                success: true,
+                deviceLimits: this.deviceLimits,
+                zarrStore: this.zarrStore,
+                // physicalScale: this.physicalScale,
+                physicalSizeTotal: this.zarrStore.physicalSizeTotal,
+                physicalSizeVoxel: this.zarrStore.physicalSizeVoxel,
+                error: null,
+            };
+        }
+        catch (error) {
+            logWithColor('INIT() FAILED');
+            log.error('Error initializing VolumeDataManager:', error);
+            this.initStatus = INIT_STATUS.FAILED;
+            this.initError = error.message || 'Unknown error';
+            return {
+                success: false,
+                error: this.initError,
+            };
+        }
+    }
+    /**
+     * Initialize the BrickCache and PageTable
+     * MRMCPT: multi-resolution multi-channel page table
+     *
+     * Depends on:
+     *   - zarrStore.brickLayout
+     *   - zarrMappings.length (zarrMappings: the zarr channel index for every one of the up to 7 channels)
+     *   -
+     */
+    initMRMCPT() {
+        logWithColor('initMRMCPT');
+        // log.debug('initMRMCPT', this.zarrStore.shapes[0]);
+        // log.debug('initMRMCPT', this.zarrStore.channelCount);
+        // log.debug('initMRMCPT', this.channels.zarrMappings);
+        // log.debug('initMRMCPT', this.channels.colorMappings);
+        const { PT, ptTHREE, bcTHREE } = _initMRMCPT(this.zarrStore.brickLayout, this.channels.zarrMappings.length);
+        this.PT = PT;
+        this.ptTHREE = ptTHREE;
+        this.bcTHREE = bcTHREE;
+        // log.debug('gl', this.gl);
+        // log.debug('renderer', this.renderer);
+        logWithColor('initMRMCPT() COMPLETE');
+    }
+    /*
+    testTexture() {
+      log.debug('testTexture pt', this.ptTHREE);
+      log.debug('testTexture bc', this.bcTHREE);
+    }
+    */
+    async initTexture() {
+        const requests = [
+            { x: 0, y: 0, z: 1 },
+        ];
+        await this.handleBrickRequests(requests);
+    }
+    updateChannels(channelProps) {
+        logWithColor('updateChannels');
+        log.debug('channelProps', channelProps);
+        // log.error('TODO: init channel mappings first ');
+        log.debug('this.channels.zarrMappings', this.channels.zarrMappings);
+        log.debug('this.channels.colorMappings', this.channels.colorMappings);
+        log.debug('this.channels.downsampleMin', this.channels.downsampleMin);
+        log.debug('this.channels.downsampleMax', this.channels.downsampleMax);
+        if (this.channels.zarrMappings.length === 0) {
+            log.debug('channels not initialized yet');
+            return;
+        }
+        // Early exit check: compare requested mappings with current mappings
+        const requestedZarrChannels = Object.values(channelProps)
+            .map(channelData => channelData.spatialTargetC)
+            .filter(targetC => targetC !== undefined);
+        const currentZarrChannels = this.channels.zarrMappings
+            .filter(mapping => mapping !== undefined);
+        // Create sorted arrays for comparison
+        const requestedSorted = [...new Set(requestedZarrChannels)].sort((a, b) => a - b);
+        const currentSorted = [...new Set(currentZarrChannels)].sort((a, b) => a - b);
+        // Early exit if mappings haven't changed
+        if (requestedSorted.length === currentSorted.length
+            && requestedSorted.every((val, index) => val === currentSorted[index])) {
+            log.debug('Channel mappings unchanged, skipping update');
+            // return;
+        }
+        log.debug('Channel mappings changed:', {
+            current: currentSorted,
+            requested: requestedSorted,
+        });
+        // Instead of for...of loop, use Object.entries() with forEach
+        Object.entries(channelProps).forEach(([uiChannelKey, channelData]) => {
+            const targetZarrChannel = channelData.spatialTargetC;
+            log.debug(`UI channel "${uiChannelKey}" wants zarr channel ${targetZarrChannel}`);
+            // Check if this zarr channel is already mapped
+            const existingSlotIndex = this.channels.zarrMappings.indexOf(targetZarrChannel);
+            if (existingSlotIndex === -1) {
+                // Need to allocate a new slot for this zarr channel
+                const nextFreeSlot = this.channels.zarrMappings.findIndex(slot => slot === undefined);
+                if (nextFreeSlot !== -1) {
+                    this.channels.zarrMappings[nextFreeSlot] = targetZarrChannel;
+                    log.debug('channelData', channelData);
+                    log.debug('this.ngffMetadata?.omero?.channels', this.ngffMetadata?.omero?.channels);
+                    log.debug('targetZarrChannel', targetZarrChannel);
+                    this.channels.downsampleMin[nextFreeSlot] = this.ngffMetadata?.omero?.channels?.[targetZarrChannel]?.window?.min || 0;
+                    this.channels.downsampleMax[nextFreeSlot] = this.ngffMetadata?.omero?.channels?.[targetZarrChannel]?.window?.max || 65535;
+                    log.debug(`Mapped zarr channel ${targetZarrChannel} to slot ${nextFreeSlot}`);
+                    log.debug('channels', this.channels);
+                }
+                else {
+                    log.debug('No free slots found, looking for unused mapped channels');
+                    // Find zarr channels that are currently mapped but no longer requested
+                    const currentlyMapped = this.channels.zarrMappings.filter(mapping => mapping !== undefined);
+                    const stillRequested = requestedZarrChannels; // We calculated this earlier
+                    const unusedMappedChannels = currentlyMapped.filter(mappedChannel => !stillRequested.includes(mappedChannel));
+                    log.debug('Currently mapped:', currentlyMapped);
+                    log.debug('Still requested:', stillRequested);
+                    log.debug('Unused mapped channels:', unusedMappedChannels);
+                    if (unusedMappedChannels.length > 0) {
+                        // Find the first slot that maps to an unused zarr channel
+                        const slotToReuse = this.channels.zarrMappings.findIndex(mapping => unusedMappedChannels.includes(mapping));
+                        if (slotToReuse !== -1) {
+                            const oldZarrChannel = this.channels.zarrMappings[slotToReuse];
+                            this.channels.zarrMappings[slotToReuse] = targetZarrChannel;
+                            this.channels.downsampleMin[slotToReuse] = this.ngffMetadata?.omero?.channels?.[targetZarrChannel]?.window?.min || 0;
+                            this.channels.downsampleMax[slotToReuse] = this.ngffMetadata?.omero?.channels?.[targetZarrChannel]?.window?.max || 65535;
+                            log.debug(`Reused slot ${slotToReuse}: ${oldZarrChannel} -> ${targetZarrChannel}`);
+                            this._purgeChannel(slotToReuse);
+                        }
+                        else {
+                            log.error('Could not find slot to reuse - this should not happen');
+                        }
+                    }
+                    else {
+                        log.error('All slots are full and all mapped channels are still in use');
+                    }
+                }
+            }
+            else {
+                log.debug(`Zarr channel ${targetZarrChannel} already mapped to slot ${existingSlotIndex}`);
+            }
+        });
+        const newColorMappings = Object.values(channelProps).map((ch) => {
+            const slot = this.channels.zarrMappings.indexOf(ch.spatialTargetC);
+            return slot !== -1 ? slot : -1;
+        });
+        while (newColorMappings.length < 7) {
+            newColorMappings.push(-1);
+        }
+        log.debug('newColorMappings', newColorMappings);
+        this.channels.colorMappings = newColorMappings;
+        log.debug('updatedChannels', this.channels);
+    }
+    /**
+     * Try to load a resolution level
+     * @param {number} resolutionIndex - The resolution level to load
+     * @param {Array} arrays - Array to store the loaded arrays
+     * @returns {Promise} Promise resolving when the resolution is loaded or rejected
+     */
+    /*
+    async tryLoadResolution(resolutionIndex, arrays) {
+      logWithColor('tryLoadResolution');
+      log.debug(resolutionIndex, arrays);
+      try {
+        const array = await zarrita.open(this.group.resolve(String(resolutionIndex)));
+        // Create new arrays to avoid modifying parameters directly
+        const newArrays = [...arrays];
+        newArrays[resolutionIndex] = array;
+        // Update the original arrays
+        Object.assign(arrays, newArrays);
+        logWithColor('tryLoadResolution() COMPLETE');
+        return { success: true, level: resolutionIndex };
+      } catch (err) {
+        log.error(`Failed to load resolution ${resolutionIndex}:`, err);
+        return { success: false, level: resolutionIndex, error: err.message };
+      }
+    }
+    */
+    /**
+     * Get physical dimensions
+     * @returns {Array} Physical dimensions [X, Y, Z]
+     */
+    getPhysicalDimensionsXYZ() {
+        log.debug('getPhysicalDimensionsXYZ');
+        log.debug('this.zarrStore.physicalSizeTotal', this.zarrStore.physicalSizeTotal);
+        const out = [this.zarrStore.physicalSizeTotal[2],
+            this.zarrStore.physicalSizeTotal[1],
+            this.zarrStore.physicalSizeTotal[0]];
+        log.debug('out', out);
+        return out;
+    }
+    /**
+     * Get the maximum resolution
+     * @returns {number} Maximum resolution
+     */
+    getMaxResolutionXYZ() {
+        log.debug('getMaxResolutionXYZ');
+        log.debug('this.zarrStore.shapes', this.zarrStore.shapes);
+        const out = [this.zarrStore.shapes[0][4],
+            this.zarrStore.shapes[0][3],
+            this.zarrStore.shapes[0][2]];
+        log.debug('out', out);
+        return out;
+    }
+    getOriginalScaleXYZ() {
+        logWithColor('getOriginalScaleXYZ');
+        log.debug('this.zarrStore.physicalSizeVoxel', this.zarrStore.physicalSizeVoxel);
+        const out = [this.zarrStore.physicalSizeVoxel[2],
+            this.zarrStore.physicalSizeVoxel[1],
+            this.zarrStore.physicalSizeVoxel[0]];
+        log.debug('out', out);
+        return out;
+    }
+    getNormalizedScaleXYZ() {
+        log.debug('getNormalizedScaleXYZ');
+        const out = [
+            1.0,
+            this.zarrStore.physicalSizeVoxel[1] / this.zarrStore.physicalSizeVoxel[2],
+            this.zarrStore.physicalSizeVoxel[0] / this.zarrStore.physicalSizeVoxel[0],
+        ];
+        log.debug('out', out);
+        return out;
+    }
+    getBoxDimensionsXYZ() {
+        log.debug('getBoxDimensionsXYZ');
+        log.debug('this.zarrStore.shapes', this.zarrStore.shapes);
+        const out = [1,
+            this.zarrStore.shapes[0][3] / this.zarrStore.shapes[0][4],
+            this.zarrStore.shapes[0][2] / this.zarrStore.shapes[0][4],
+        ];
+        log.debug('out', out);
+        return out;
+    }
+    /**
+     * Load a specific Zarr chunk based on [t,c,z,y,x] coordinates
+     * @param {number} t - Time point (default 0)
+     * @param {number} c - Channel (default 0)
+     * @param {number} z - Z coordinate
+     * @param {number} y - Y coordinate
+     * @param {number} x - X coordinate
+     * @param {number} resolution - Resolution level
+     * @returns {Promise<Uint8Array>} 32x32x32 chunk data
+     */
+    async loadZarrChunk(t = 0, c = 0, z, y, x, resolution) {
+        // logWithColor('loadZarrChunk');
+        if (!this.zarrStore || !this.zarrStore.arrays[resolution]) {
+            throw new Error('Zarr store or resolution not initialized');
+        }
+        // log.debug('loadZarrChunk', t, c, z, y, x, resolution);
+        const array = this.zarrStore.arrays[resolution];
+        // TODO: Use zarrita's get(arr, slice) method (rather than arr.getChunk),
+        // which will enable reading from arrays with other chunk shapes
+        // (i.e., not strictly 32x32x32 chunks).
+        // To do so, will need to determine the slice indices corresponding
+        // to each "assumed 32x32x32 chunk key".
+        // Reference: https://zarrita.dev/slicing.html
+        const chunkEntry = await array.getChunk([t, c, z, y, x]);
+        // log.debug('chunkEntry', chunkEntry);
+        if (!chunkEntry) {
+            throw new Error(`No chunk found at coordinates [${t},${c},${z},${y},${x}]`);
+        }
+        // Ensure the chunk is the expected size
+        if (chunkEntry.data.length !== BRICK_SIZE * BRICK_SIZE * BRICK_SIZE) {
+            throw new Error(`Unexpected chunk size: ${chunkEntry.data.length}`);
+        }
+        return chunkEntry.data;
+    }
+    async processRequestData(buffer) {
+        if (this.isBusy) {
+            log.debug('processRequestData: already busy, skipping');
+            return;
+        }
+        this.isBusy = true;
+        this.triggerRequest = false;
+        const { requests, origRequestCount } = _requestBufferToRequestObjects(buffer, this.k);
+        if (requests.length === 0) {
+            this.noNewRequests = true;
+        }
+        log.debug(`processRequestData: handling ${requests.length} requests of ${origRequestCount}`);
+        await this.handleBrickRequests(requests);
+        // We want processRequestData to alternate with processUsageData.
+        this.triggerUsage = true;
+        this.isBusy = false;
+    }
+    async processUsageData(buffer) {
+        if (this.isBusy) {
+            log.debug('processUsageData: already busy, skipping');
+            this.needsBailout = true; // Set a flag to indicate we need to bail out of processing requests
+            return;
+        }
+        this.isBusy = true;
+        this.triggerUsage = false;
+        const now = ++this.timeStamp;
+        const usedBricks = new Set();
+        // Process buffer to identify used bricks
+        for (let i = 0; i < buffer.length; i += 4) {
+            const x = buffer[i];
+            const y = buffer[i + 1];
+            const z = buffer[i + 2];
+            // Skip empty entries
+            if ((x | y | z) === 0) {
+                // eslint-disable-next-line no-continue
+                continue;
+            }
+            // Calculate brick index
+            const bcIndex = z * BRICK_CACHE_SIZE_X * BRICK_CACHE_SIZE_Y + y * BRICK_CACHE_SIZE_X + x;
+            // Only add valid indices
+            if (bcIndex < this.BCTimeStamps.length) {
+                usedBricks.add(bcIndex);
+            }
+        }
+        // Update timestamps for all used bricks at once
+        Array.from(usedBricks).forEach((bcIndex) => {
+            this.BCTimeStamps[bcIndex] = now;
+        });
+        // Check if brick cache is full based on allocation index
+        // this.BCFull = this.BCUnusedIndex >= this.BCTimeStamps.length;
+        // If cache is full or we want to always maintain the LRU list
+        // if (this.BCFull || this.BCUnusedIndex >= this.BCTimeStamps.length - this.k) { // Always update LRU list
+        // do NOT overwrite BCFull; it is latched in _allocateBCSlots()
+        if (this.BCFull)
+            this._buildLRU(); // The brick cache is full, so update the list of least recently used bricks, as it will be needed for eviction during the next _allocateBCSlots
+        // log.debug('this.BCTimeStamps', this.BCTimeStamps);
+        // log.debug('this.timeStamp', this.timeStamp);
+        // We want processRequestData to alternate with processUsageData.
+        this.triggerRequest = true;
+        this.isBusy = false;
+    }
+    // Helper method to update PT entries for evicted bricks
+    _evictBrick(bcIndex) {
+        const pt = this.bc2pt[bcIndex];
+        if (!pt)
+            return; // brick was never resident
+        const [min, max] = this.BCMinMax[bcIndex] || [0, 0];
+        const ptVal = ((0 << 31) // not-resident
+            | (1 << 30) // init-done
+            | (Math.min(127, min >> 1) << 23)
+            | (Math.min(127, max >> 1) << 16)) >>> 0;
+        this._updatePTEntry(pt.x, pt.y, pt.z, ptVal); // ← PT coord!
+        this.bc2pt[bcIndex] = null; // slot now free
+    }
+    _purgeChannel(ptChannelIndex) {
+        log.debug('purging channel', ptChannelIndex);
+        log.debug('corresponding zarr channel', this.channels.zarrMappings[ptChannelIndex]);
+        if (!this.ptTHREE) {
+            log.error('pagetable texture not initialized');
+            return;
+        }
+        this.channels.downsampleMin[ptChannelIndex] = undefined;
+        this.channels.downsampleMax[ptChannelIndex] = undefined;
+        this.channels.zarrMappings[ptChannelIndex] = undefined;
+        const channelMask = this.PT.channelOffsets[ptChannelIndex];
+        log.debug('channelMask', channelMask);
+        log.error('TODO: not tested yet');
+        const { gl } = this;
+        const texPT = this.renderer.properties.get(this.ptTHREE).__webglTexture;
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_3D, texPT);
+        for (let r = 0; r < this.zarrStore.resolutions; r++) {
+            const anchor = [
+                this.PT.anchors[r][2] * channelMask[2],
+                this.PT.anchors[r][1] * channelMask[1],
+                this.PT.anchors[r][0] * channelMask[0],
+            ];
+            log.debug('anchor', anchor);
+            const extents = this.zarrStore.brickLayout[r];
+            const size = extents[0] * extents[1] * extents[2];
+            log.debug('extents', extents);
+            log.debug('size', size);
+            // texsub 3D
+            // replace with a block of zeros
+            gl.texSubImage3D(gl.TEXTURE_3D, 0, anchor[0], anchor[1], anchor[2], extents[0], extents[1], extents[2], gl.RED_INTEGER, gl.UNSIGNED_INT, new Uint32Array(size));
+        }
+        gl.bindTexture(gl.TEXTURE_3D, null);
+    }
+    // Update a PT entry
+    _updatePTEntry(ptX, ptY, ptZ, ptVal) {
+        if (!this.ptTHREE)
+            return;
+        const { gl } = this;
+        const texPT = this.renderer.properties.get(this.ptTHREE).__webglTexture;
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_3D, texPT);
+        gl.texSubImage3D(gl.TEXTURE_3D, 0, ptX, ptY, ptZ, 1, 1, 1, gl.RED_INTEGER, gl.UNSIGNED_INT, new Uint32Array([ptVal]));
+        gl.bindTexture(gl.TEXTURE_3D, null);
+    }
+    /* ------------------------------------------------------------- *
+   * 2. Allocate the next n free bricks in the brick cache         *
+   * ------------------------------------------------------------- */
+    /**
+     *
+     * @param {number} n The number of slots to allocate
+     * @returns {{ bcIndex, x, y, z }[]} Array of brick cache coordinates for the allocated slots.
+     */
+    _allocateBCSlots(n) {
+        let slots = [];
+        const total = BRICK_CACHE_SIZE_X * BRICK_CACHE_SIZE_Y * BRICK_CACHE_SIZE_Z;
+        if (!this.BCFull && this.BCUnusedIndex + n > total) {
+            // The brick cache was not already full,
+            // but allocating N more bricks will put us over the limit.
+            this.BCFull = true;
+            log.debug('BRICK CACHE FULL');
+        }
+        // Do the allocation.
+        if (!this.BCFull) {
+            for (let i = 0; i < n; ++i) {
+                const bcIndex = (this.BCUnusedIndex + i) % total; // wrap for now
+                const z = Math.floor(bcIndex / (BRICK_CACHE_SIZE_X * BRICK_CACHE_SIZE_Y));
+                const rem = bcIndex - z * BRICK_CACHE_SIZE_X * BRICK_CACHE_SIZE_Y;
+                const y = Math.floor(rem / BRICK_CACHE_SIZE_X);
+                const x = rem % BRICK_CACHE_SIZE_X;
+                slots.push({ bcIndex, x, y, z });
+            }
+            this.BCUnusedIndex += n;
+        }
+        else { // ---- BC already full ----
+            // Before proceeding to choose old slots from the LRU stack,
+            // we need to ensure that the LRU stack is at least as long as N
+            // (since N is the number of new brick slots to allocate).
+            if (this.LRUStack.length < n)
+                this._buildLRU(); // top-up list
+            // Use the LRU stack to evict the least-recently-used bricks
+            // and return their coordinates for the new bricks to use.
+            slots = this.LRUStack.splice(0, n).map((bcIndex) => {
+                this._evictBrick(bcIndex);
+                const z = Math.floor(bcIndex / (BRICK_CACHE_SIZE_X * BRICK_CACHE_SIZE_Y));
+                const rem = bcIndex - z * BRICK_CACHE_SIZE_X * BRICK_CACHE_SIZE_Y;
+                const y = Math.floor(rem / BRICK_CACHE_SIZE_X);
+                const x = rem % BRICK_CACHE_SIZE_X;
+                return { bcIndex, x, y, z };
+            });
+        }
+        return slots;
+    }
+    /* ------------------------------------------------------------- *
+   * 4. Upload one brick + PT entry                                *
+   * ------------------------------------------------------------- */
+    async _uploadBrick(ptCoord, bcSlot) {
+        // log.debug('uploading brick', ptCoord, bcSlot);
+        if (ptCoord.x >= this.PT.xExtent
+            || ptCoord.y >= this.PT.yExtent
+            || ptCoord.z >= this.PT.zTotal
+            || ptCoord.x < 0
+            || ptCoord.y < 0
+            || ptCoord.z < 0) {
+            log.error('this.PT', this.PT);
+            log.error('ptCoord out of bounds', ptCoord);
+            return;
+        }
+        // log.debug('ptCoord', ptCoord);
+        // log.debug('this.PT', this.PT);
+        /* 4.1 fetch chunk from Zarr */
+        const { channel, resolution, x, y, z } = _ptToZarr(ptCoord.x, ptCoord.y, ptCoord.z, { PT_zExtent: this.PT.zExtent, PT_z0Extent: this.PT.z0Extent, PT_anchors: this.PT.anchors });
+        const zarrChannel = this.channels.zarrMappings[channel];
+        if (zarrChannel === undefined || zarrChannel === -1) {
+            log.error('zarrChannel is undefined or -1', zarrChannel);
+            return;
+        }
+        log.debug('starting to load zarr chunk', { resolution, z, y, x, zarrChannel });
+        let chunk = await this.loadZarrChunk(0, zarrChannel, z, y, x, resolution);
+        // log.debug('chunk', chunk);
+        // TODO(mark): is there a better way than iterating over all of the chunk values?
+        if (chunk instanceof Uint16Array) {
+            log.debug('chunk is Uint16Array, converting to Uint8Array');
+            if (this.channels.downsampleMin[channel] === undefined) {
+                // get the channel ID from this.channels.zarrMappings
+                const channelId = this.channels.zarrMappings[channel];
+                log.debug('channelId was not found in this.channels.downsampleMin[channel]', channelId);
+                // get the downsample min and max for the channel from omero
+                this.channels.downsampleMin[channel] = this.ngffMetadata?.omero?.channels?.[channelId]?.window?.min || 0;
+                this.channels.downsampleMax[channel] = this.ngffMetadata?.omero?.channels?.[channelId]?.window?.max || 65535;
+                log.debug('this.channels.downsampleMin[channel]', this.channels.downsampleMin[channel]);
+                log.debug('this.channels.downsampleMax[channel]', this.channels.downsampleMax[channel]);
+            }
+            // TODO(mark): to reduce memory usage, create the Uint8Array as a view of the Uint16Array
+            // and use bitwise operations. Then scale the values.
+            const uint8Chunk = new Uint8Array(chunk.length);
+            for (let i = 0; i < chunk.length; i++) {
+                // Scale from 0-65535 to 0-255
+                uint8Chunk[i] = Math.floor((chunk[i] - this.channels.downsampleMin[channel]) / (this.channels.downsampleMax[channel] - this.channels.downsampleMin[channel]) * 255);
+            }
+            chunk = uint8Chunk;
+        }
+        if (!(chunk instanceof Uint8Array)) {
+            throw new Error(`Unsupported chunk type: ${chunk.constructor.name}. Expected Uint8Array.`);
+        }
+        let min = 255;
+        let max = 0;
+        for (let i = 0; i < chunk.length; ++i) {
+            const v = chunk[i];
+            if (v < min)
+                min = v;
+            if (v > max)
+                max = v;
+        }
+        /* 4.3 brick‑cache upload */
+        const { gl } = this;
+        const texBC = this.renderer.properties.get(this.bcTHREE).__webglTexture;
+        gl.activeTexture(gl.TEXTURE2);
+        gl.bindTexture(gl.TEXTURE_3D, texBC);
+        gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
+        gl.texSubImage3D(gl.TEXTURE_3D, 0, bcSlot.x * BRICK_SIZE, bcSlot.y * BRICK_SIZE, bcSlot.z * BRICK_SIZE, BRICK_SIZE, BRICK_SIZE, BRICK_SIZE, gl.RED, gl.UNSIGNED_BYTE, chunk);
+        gl.pixelStorei(gl.UNPACK_ALIGNMENT, 4);
+        gl.bindTexture(gl.TEXTURE_3D, null);
+        // log.debug('uploaded brick');
+        const error = gl.getError();
+        if (error !== gl.NO_ERROR) {
+            log.error('WebGL error during brick upload:', error, chunk);
+        }
+        /* 4.4 PT entry upload */
+        if (channel >= this.channels.zarrMappings.length) {
+            log.debug('channel is out of bounds', channel);
+            min = 255;
+            max = 255;
+        }
+        const ptVal = _packPT(min, max, bcSlot.x, bcSlot.y, bcSlot.z);
+        const texPT = this.renderer.properties.get(this.ptTHREE).__webglTexture;
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_3D, texPT);
+        gl.texSubImage3D(gl.TEXTURE_3D, 0, ptCoord.x, ptCoord.y, ptCoord.z, 1, 1, 1, gl.RED_INTEGER, gl.UNSIGNED_INT, new Uint32Array([ptVal]));
+        gl.bindTexture(gl.TEXTURE_3D, null);
+        // log.debug('uploaded PT entry');
+        // log.debug('ptVal', ptVal);
+        // log.debug('min', min);
+        // log.debug('max', max);
+        // log.debug('bcSlot', bcSlot);
+        // log.debug('channel', channel);
+        // log.debug('resolution', resolution);
+        // log.debug('x', x);
+        // log.debug('y', y);
+        // log.debug('z', z);
+        // log.debug('ptCoord', ptCoord);
+        const error2 = gl.getError();
+        if (error2 !== gl.NO_ERROR) {
+            log.error('WebGL error during pagetable upload:', error2, chunk);
+        }
+        /* 4.5 bookkeeping */
+        // const now = ++this.timeStamp;
+        this.BCTimeStamps[bcSlot.bcIndex] = this.timeStamp;
+        this.BCMinMax[bcSlot.bcIndex] = [min, max];
+        this.bc2pt[bcSlot.bcIndex] = ptCoord;
+        // log.debug('bookkeeping');
+    }
+    /* ------------------------------------------------------------- *
+   * 5. Public: handle a batch of PT requests (array of {x,y,z})   *
+   * ------------------------------------------------------------- */
+    async handleBrickRequests(ptRequests) {
+        // log.debug('handleBrickRequests');
+        if (ptRequests.length === 0)
+            return;
+        // log.debug('ptRequests', ptRequests);
+        // log.debug('this.BCFull', this.BCFull);
+        // log.debug('this.BCUnusedIndex', this.BCUnusedIndex);
+        // log.debug('this.BCTimeStamps', this.BCTimeStamps);
+        // log.debug('this.LRUStack', this.LRUStack);
+        /* <= k requests, allocate same number of bricks */
+        const slots = this._allocateBCSlots(ptRequests.length);
+        // log.debug('slots', slots);
+        /* upload each (sequentially or Promise.all if you prefer IO overlap) */
+        log.debug('handleBrickRequests: starting for loop');
+        for (let i = 0; i < ptRequests.length; ++i) {
+            log.debug('uploading brick', ptRequests[i], slots[i]);
+            // eslint-disable-next-line no-await-in-loop
+            await this._uploadBrick(ptRequests[i], slots[i]);
+            // this.bricksAllocated++;
+            const rlength = this.bricksEverLoaded.size;
+            this.bricksEverLoaded.add(`${ptRequests[i].x},${ptRequests[i].y},${ptRequests[i].z}`);
+            if (rlength === this.bricksEverLoaded.size) {
+                log.debug('DUPLICATE BRICK LOADED', ptRequests[i]);
+            }
+            if (this.needsBailout) {
+                log.debug('Bailing out of handleBrickRequests early due to needsBailout flag');
+                this.needsBailout = false; // Reset the flag
+                break; // Exit the loop early
+                // TODO(mark): do something with the allocated slots that were not used?
+            }
+        }
+        // log.debug('this.bricksAllocated', this.bricksAllocated);
+        log.debug('this.bricksEverLoaded', this.bricksEverLoaded);
+        // log.debug('uploaded bricks');
+        /* let Three.js know textures changed */
+        // this.bcTHREE.needsUpdate = true;
+        // this.ptTHREE.needsUpdate = true;
+    }
+    /* --------------------------------------------------------- *
+     * Rebuild the LRUStack with the k least-recently-used bricks *
+     * --------------------------------------------------------- */
+    _buildLRU() {
+        // Update this.LRUStack based on BCTimeStamps.
+        // BCTimeStamps is updated during both initial brick upload and processUsageData.
+        // However it is not until _buildLRU is called that the timestamps are sorted
+        // to update this.LRUStack.
+        const brickIndicesWithTimes = this.BCTimeStamps
+            .map((time, index) => ({ index, time }));
+        this.LRUStack = brickIndicesWithTimes
+            .sort((a, b) => a.time - b.time)
+            .slice(0, this.k)
+            .map(item => item.index);
+    }
+}