OME-TIFF / ImageJ / plain TIFF stacks
OME-TIFF channel stacks
Code
import NiiVue, { CHANNEL_COLORMAPS, CHANNEL_GRAY_COLORMAP, DRAG_MODE, describeTiff, OVERLAY_COLOR_BLEND, omeTiffVolumesFrom, parseTiff, SHOW_RENDER, SLICE_TYPE, tiffChannelCount, tiffChannelName, tiffIsTiled,} from '@niivue/niivue'import { backendFromUrl, isAntiAlias } from './displayControls.js'import { omeXml, phantomChannels, writeTiff } from './ome.tiff.write.js'
// OME-TIFF is the third of the microscopy containers this package reads (see// notes/ome-tiff-format.md). A .tif holds a flat stack of image planes and// nothing else; the metadata block in the first directory is what says how// those planes fold into z, channel and time. This page reads a whole file// into memory and shows each channel as a volume: slices, a 3D render and a// clip plane. (Large 2D slides stream tile by tile in demo-ext-tile instead.)// The decoders and metadata flavours (OME-XML, ImageJ, plain stacks; none,// PackBits, Deflate) are covered by src/volume/tiff*.test.ts.
const gl1 = document.getElementById('gl1')const webgpuCheck = document.getElementById('webgpuCheck')const imageSelect = document.getElementById('image')const fileInput = document.getElementById('file')const secondaryDrag = document.getElementById('secondaryDrag')const clipCheck = document.getElementById('clipCheck')const nearestCheck = document.getElementById('nearestCheck')const blendSelect = document.getElementById('blend')const channelList = document.getElementById('channelList')const statusLine = document.getElementById('status')
/** * Real OME-TIFFs written by other software, so the reader is exercised against * files this repository did not produce, plus a phantom written here. Every * host below sends CORS headers, which a browser needs for a cross-origin * fetch; most microscopy archives do not, so an arbitrary URL may still be * blocked (Open file always works). */const PHANTOM = 'phantom'const SAMPLES = [ { label: 'hiPSC cell, 3 channels, 238 x 284 x 70 (14 MB)', url: 'https://allencell.s3.amazonaws.com/aics/variance_project_dataset/crop_raw/012b784e_raw.ome.tif', credit: 'Allen Institute for Cell Science, variance project dataset (research and non-commercial use, with citation)', note: 'BigTIFF, 16-bit, 210 planes folding into three channels of a 70-slice stack. ' + 'It names no channel colours and states no voxel size, so the colours are ' + 'the fallback palette and the voxels are 1 um.', }, { label: 'Spheroid, Hoechst channel, 1024 x 1024 (2.2 MB)', url: 'https://ftp.ebi.ac.uk/biostudies/fire/S-BIAD/254/S-BIAD2254/Files/spher-colo52/PB000142_spher-colo52_HT29_L1/Well-B04-z0-HOECHST.ome.tiff', credit: 'Cell Painting in 3D spheroids, BioImage Archive S-BIAD2254 (CC BY 4.0)', note: 'Bio-Formats output: big-endian, 16-bit, micrometre units and a channel colour.', }, { label: 'Synthetic phantom, 3 channels (generated here)', url: PHANTOM, credit: 'Synthetic phantom written by this page (OME-XML, Deflate)', note: 'Deliberately anisotropic voxels: a wrong z-spacing shows as a squashed or stretched sagittal view.', },]
const nv1 = new NiiVue({ backend: backendFromUrl(), isAntiAlias, backgroundColor: [0, 0, 0, 1], sliceType: SLICE_TYPE.MULTIPLANAR, // The clip control acts on the 3D render, so keep its tile in the // multiplanar layout instead of the slices-only AUTO default. showRender: SHOW_RENDER.ALWAYS, isColorbarVisible: false, // Right drag pans and the wheel zooms the 2D slices; yoked, a zoom on any // tile zooms them all. secondaryDragMode: DRAG_MODE.pan, isYoked3DTo2DZoom: true, // Every channel counts alike, on black, as fluorescence viewers show them. volumeIsChannelStack: true, // Each channel is an overlay, so the clip plane must cut them too, or they // show through the clipped base and it appears to do nothing. clipPlaneOverlay: true, // A dropped file is read here (channels and all), not as one volume. isDragDropEnabled: false,})window.nv1 = nv1webgpuCheck.checked = nv1.backend === 'webgpu'webgpuCheck.onchange = async function () { await nv1.reinitializeView({ backend: this.checked ? 'webgpu' : 'webgl2' })}secondaryDrag.onchange = () => { nv1.secondaryDragMode = Number(secondaryDrag.value)}clipCheck.onchange = () => { nv1.setClipPlane(clipCheck.checked ? [0.1, 270, 0] : [2, 0, 0])}nearestCheck.onchange = () => { nv1.volumeIsNearestInterpolation = nearestCheck.checked}document.getElementById('colorBtn').oninput = function () { const [r, g, b] = [1, 3, 5].map( (i) => parseInt(this.value.slice(i, i + 2), 16) / 255, ) nv1.backgroundColor = [r, g, b, 1]}// max keeps each pixel's brightest channel; additive sums them.function applyBlend() { nv1.volumeOverlayColorBlend = blendSelect.value === 'max' ? OVERLAY_COLOR_BLEND.MAX : OVERLAY_COLOR_BLEND.ADDITIVE}applyBlend()blendSelect.onchange = applyBlend
// The status bar shows messages until a click on the image, then the voxel// under the crosshair; the next message takes it back.let isShowingLocation = falsegl1.addEventListener('pointerdown', () => { isShowingLocation = true})nv1.addEventListener('locationChange', (e) => { if (isShowingLocation) statusLine.textContent = e.detail.string})await nv1.attachToCanvas(gl1)webgpuCheck.checked = nv1.backend === 'webgpu'
// textContent (not innerHTML): messages include data-derived channel names.function say(message) { isShowingLocation = false statusLine.textContent = message}function fail(message, err) { say(`${message}: ${err?.message ?? err}`) console.error(message, err)}
document.getElementById('aboutBtn').onclick = () => { window.alert( 'OME-TIFF stores a microscopy stack as a flat run of TIFF planes; its ' + 'metadata says how they fold into z, channel and time, and gives the ' + 'voxel size and channel names and colours. NiiVue reads OME-XML and ' + 'ImageJ hyperstack metadata (a plain stack is one channel), 8/16/32-bit ' + 'and float data, classic TIFF and BigTIFF, strips or tiles, and ' + 'uncompressed, PackBits, LZW or Deflate planes. Each channel becomes a ' + 'volume: slices, a 3D render and a clip plane.\n\n' + 'Pick a sample, open your own .tif (or drop one on the image), or give ' + 'a URL. The status bar credits each sample; hover a menu entry for its ' + 'format notes.', )}
// --- The phantom -----------------------------------------------------------------
const SIZE = { sizeX: 192, sizeY: 160, sizeZ: 64 }const SPACING = [0.25, 0.25, 0.9]
/** A 3-channel OME-TIFF; OME's XYCZT order varies channel fastest. */async function phantomBuffer() { const channels = phantomChannels(SIZE) const planes = [] for (let z = 0; z < SIZE.sizeZ; z++) { for (const channel of channels) planes.push(channel.planes[z]) } const bytes = await writeTiff({ width: SIZE.sizeX, height: SIZE.sizeY, planes, description: omeXml({ name: 'NiiVue synthetic phantom', ...SIZE, sizeC: channels.length, spacing: SPACING, channels, }), compression: 'deflate', }) return bytes.buffer}
// --- Image menu: samples, then a custom URL or a local file ------------------------
const customOption = new Option()const customUrlOption = new Option('Custom URL...', 'custom-url')for (const sample of SAMPLES) { const option = new Option(sample.label, sample.url) option.title = sample.note imageSelect.append(option)}imageSelect.append(customUrlOption, new Option('Open file...', 'open-file'))let shownValue = SAMPLES[0].url
// A custom pick is listed as itself, so the menu always names what is shown.function showCustom(value, label) { customOption.value = value customOption.text = `${label} (custom)` customUrlOption.before(customOption) imageSelect.value = value}
// A failed open puts the menu back on what is still shown, custom entry// included: by text too, as two local files share the value 'local'.let shownCustom = { value: '', text: '' }function restoreMenu() { Object.assign(customOption, shownCustom) if (!shownCustom.value) customOption.remove() imageSelect.value = shownValue}
imageSelect.onchange = () => { const value = imageSelect.value if (value === 'open-file') { imageSelect.value = shownValue fileInput.click() return } if (value === 'custom-url') { imageSelect.value = shownValue const url = window.prompt('OME-TIFF URL (the host must send CORS)')?.trim() if (!url) return showCustom(url, url.split('/').pop() || url) openUrl(url) return } if (value === PHANTOM) openPhantom() else if (value === 'local') openFile(localFile) else openUrl(value)}
// The last local file opened, so its menu entry can reopen it.let localFile = nullasync function openFile(file) { showCustom('local', file.name) await open(file.name, () => file.arrayBuffer(), '', file)}fileInput.onchange = () => { const file = fileInput.files?.[0] fileInput.value = '' if (file) openFile(file)}const main = document.getElementById('canvas-container')main.addEventListener('dragover', (e) => e.preventDefault())main.addEventListener('drop', (e) => { e.preventDefault() const file = e.dataTransfer?.files?.[0] if (file) openFile(file)})
function openUrl(url) { const name = url.split('/').pop() || url const credit = SAMPLES.find((s) => s.url === url)?.credit ?? '' return open( name, async () => { const response = await fetch(url) if (!response.ok) { throw new Error(`${response.status} ${response.statusText}`) } return response.arrayBuffer() }, credit, )}
function openPhantom() { return open('Synthetic phantom', phantomBuffer, SAMPLES.at(-1).credit)}
// --- Channel panel ---------------------------------------------------------------
/** The parsed TIFF on offer, its credit, and how it was described. */let source = nulllet sourceCredit = ''let sourceSummary = ''// Opens and loads can overlap (a slow URL, quick ticks); only the latest of// each wins. Separate counts, so a tick on the old file's channels while a new// one opens does not cancel the open.let opening = 0let generation = 0// The channels on screen, in volume order: what the window inputs address.let shownChannels = []// Scene swaps run one at a time, each skipped once a newer request exists:// loadVolumes prepares before it swaps, so a check after it is too late.let swaps = Promise.resolve()function swapScene(mine, step) { const done = swaps.then(() => (mine === generation ? step() : false)) swaps = done.catch(() => {}) return done}
async function open(label, readBuffer, credit, file = null) { const mine = ++opening const picked = imageSelect.value say(`Reading ${label}...`) try { const next = describeTiff(parseTiff(await readBuffer())) if (mine !== opening) return // Decode every channel (all start ticked) and switch only with the scene, // so a corrupt plane or failed upload leaves the old file, menu and // channel list in place. const channels = Array.from({ length: tiffChannelCount(next) }, (_, c) => c) say('Decoding planes...') const volumes = channels.length ? await omeTiffVolumesFrom(next, { channels }) : [] if (mine !== opening) return const shown = await loadSelected({ source: next, channels, volumes, commit() { if (file) localFile = file shownValue = picked shownCustom = { value: customOption.value, text: customOption.text } source = next sourceCredit = credit sourceSummary = describeSource(source) showChannels() }, }) if (!shown && mine === opening) restoreMenu() } catch (err) { if (mine !== opening) return restoreMenu() fail(`Could not read ${label} (a cross-origin host must send CORS)`, err) }}
function describeSource(src) { const flavour = src.ome ? `OME-XML ${src.ome.pixelType}` : src.imagej ? 'ImageJ hyperstack' : 'plain TIFF' return ( `${flavour}, ${src.tiff.ifds.length} planes` + `${src.tiff.isBigTiff ? ', BigTIFF' : ''}` + `${tiffIsTiled(src.tiff) ? ', tiled' : ''}` )}
function selectedChannels() { return [...channelList.querySelectorAll('input[type=checkbox]:checked')].map( (box) => Number(box.value), )}
function showChannels() { channelList.replaceChildren() for (let c = 0; c < tiffChannelCount(source); c++) { const label = document.createElement('label') const box = Object.assign(document.createElement('input'), { type: 'checkbox', value: String(c), checked: true, }) box.onchange = () => loadSelected() const swatch = document.createElement('span') swatch.className = 'swatch' swatch.dataset.channel = String(c) // The window maximum, in the file's units, once loaded. const max = Object.assign(document.createElement('input'), { type: 'number', disabled: true, title: 'Window maximum: lower is brighter', }) max.dataset.channel = String(c) max.oninput = () => { const at = shownChannels.indexOf(c) const calMax = Number(max.value) if (at >= 0 && Number.isFinite(calMax) && calMax > nv1.volumes[at].calMin) nv1.setVolume(at, { calMax }) } label.append(box, swatch, tiffChannelName(source, c), max) channelList.append(label) }}
// Colours come from the file's OME Color, else the fallback palette.const CHANNEL_RGB = new Map( [...CHANNEL_COLORMAPS, CHANNEL_GRAY_COLORMAP].map((c) => [c.name, c.rgb]),)
/** * Window each channel over its robust range, not the global one: a * fluorescence channel is mostly background with a few bright structures, so * the full range leaves the signal a few counts above black. */function showLoaded(channels) { for (const row of channelList.querySelectorAll('label')) { const swatch = row.querySelector('.swatch') const max = row.querySelector('input[type=number]') const at = channels.indexOf(Number(max.dataset.channel)) const volume = nv1.volumes[at] max.disabled = !volume const rgb = CHANNEL_RGB.get(volume?.colormap) swatch.style.background = volume && rgb ? `rgb(${rgb.join(',')})` : '' if (!volume) continue const calMin = volume.robustMin ?? volume.globalMin const calMax = volume.robustMax ?? volume.globalMax nv1.setVolume(at, { calMin, calMax, opacity: 1 }) max.value = String(Math.round(calMax * 100) / 100) }}
/** * Load the ticked channels, or with `opened` a newly read file's decoded * channels, offering that file (`opened.commit`) once they show. True when shown. */async function loadSelected(opened = null) { const mine = ++generation const channels = opened?.channels ?? selectedChannels() const loading = opened?.source ?? source say(channels.length ? 'Decoding planes...' : 'No channel selected') try { const volumes = opened?.volumes ?? (channels.length ? await omeTiffVolumesFrom(loading, { channels }) : []) const swapped = await swapScene(mine, async () => { await nv1.loadVolumes(volumes) opened?.commit() // A file opened meanwhile has its own rows: these channels are not theirs. shownChannels = loading === source ? channels : [] showLoaded(shownChannels) return true }) if (!swapped || mine !== generation || volumes.length === 0) return swapped const vol = nv1.volumes[0] const voxels = vol.dimsRAS.slice(1, 4) // A single-plane file (one z, as most published 2D fields are) has nothing // to show in the other two planes, so give the whole canvas to the axial. nv1.sliceType = voxels[2] > 1 ? SLICE_TYPE.MULTIPLANAR : SLICE_TYPE.AXIAL const spacing = vol.pixDimsRAS .slice(1, 4) .map((v) => v.toFixed(3)) .join(' x ') say( `Showing ${volumes.map((v) => v.name).join(', ')} - ` + `${voxels.join(' x ')} voxels, ${spacing} um (${sourceSummary})` + `${sourceCredit ? `. ${sourceCredit}` : ''}`, ) return true } catch (err) { if (mine === generation) fail('Could not load the channels', err) return false }}
await openUrl(SAMPLES[0].url)