# CT tools: drag resolution, X-ray window/level, CT volume, labels, OME-Zarr streaming

All code in this document is original to Unroll and licensed Apache 2.0. The feature set was inspired by
[ScrollSlabViewer](https://github.com/Paul-G2/ScrollSlabViewer) by Paul-G2 (MIT); the ideas (raymarched MIP, an
oriented slab clip, a label overlay, a lower resolution while the camera moves, percentile contrast) are common
volume rendering techniques and no code was copied from it or other viewers.

## 1. Lower resolution while dragging

`lib/dragres.js`. On OrbitControls `start` the renderer and the effect composer drop to a fraction of their
pixel ratio; after `end`, once the camera has stopped changing for 150 ms (damping included), the full
ratio returns. The render targets of the bloom pass shrink with it, which is where most of the saving is.

| Where | What |
| --- | --- |
| Settings | **Lower resolution while dragging**: `off`, `light` (0.75x), `strong` (0.5x). Default `light`, `strong` on touch screens. The pixel ratio never goes below 0.5. |
| URL | `?dragRes=off\|light\|strong` (this visit only, like every setting) |
| API | `unrollView.dragRes.state()`, `unrollView.dragRes.set('strong')`, test hooks `begin()` and `end()`; `unrollView.settings.set('dragRes', 'off')` |
| Event | ui.js dispatches `unroll:settings` on every settings change |

## 2. X-ray window/level with percentile auto contrast

`lib/ctwl.js`, plus one uniform in `app.js` (`uCTWin`, applied in the surface fragment shader right after the
empty-surface test, so holes stay holes). Values are on the 0..1 scale of the CT atlas:
`low = level - window / 2`, `high = level + window / 2`, and each pixel shows `clamp((ct - low) / (high - low))`.

Auto contrast builds a 256-bin histogram of the CT atlas (drawn once into a 512 px wide canvas, empty pixels
with value 0..3 ignored) and sets low and high to the chosen percentiles (default 1 and 99).

| Where | What |
| --- | --- |
| Panel | **X-ray contrast** group: **Window (contrast range)** and **Level (center brightness)** sliders, **Auto contrast**, **Full range** |
| Settings | **X-ray auto contrast on load**, **Auto contrast low percentile** (0 to 20), **Auto contrast high percentile** (80 to 100) |
| URL | `?ctwin=0.5&ctlevel=0.4`, `?ctauto=1` (Settings percentiles) or `?ctauto=2,98` |
| API | `unrollView.ct.setWindow(window, level)`, `ct.setLowHigh(low, high)`, `ct.auto(pLow, pHigh)`, `ct.reset()`, `ct.state()`, `ct.histogram()`, `ct.percentiles(pLow, pHigh)` |
| Actions | `ct.auto`, `ct.reset` (in `unrollView.actions.list()`) |

## 3. CT volume: MIP inside an oriented slab

`lib/ctvolume.js` (view, panel, API) and `lib/ctsource.js` (where the data comes from). Two read-only hooks in
`app.js`: `unrollView.scanGeom()` (the int16 mesh grids, which hold scan voxels minus the roll axis center) and
`unrollView.scanPick(x, y)` (winding and UV under a screen point, from the existing float pick).

How a pick becomes a cube:

1. Winding UV to grid cell through the winding's `colIdx`/`rowIdx`, bilinear between the 4 grid vertices, plus
   `axis.centre` gives the scan voxel (x, y, z) at level 0. The surface normal comes from the row and column
   tangents at that cell. The scan's zarr axes are (z, y, x), so `[z][y][x]` at level 0 is the picked voxel.
2. A cube of `size` voxels (64 to 256; 256 on desktops, 128 on phones) at detail level `L` (voxels of
   9.362 x 2^L µm) is centered on it, clamped to the level's shape, read chunk by chunk and uploaded as a
   `THREE.Data3DTexture` (R8, linear filtering). 256³ is 16.8 MB on the GPU, 128³ is 2.1 MB.
3. The view is a unit cube drawn with back faces in its own canvas and WebGL context (so the main scroll
   renderer, its passes and its picking are untouched). The fragment shader marches each ray at 1.25 samples
   per voxel (up to 1024 steps, jittered against banding), clipped to the box and to the slab
   `|dot(p, n) - offset| <= thickness / 2`, and keeps the brightest sample. Window/level is applied to that
   maximum. It renders on demand (camera change or a control), not every frame.
4. The slab normal starts as the surface normal, so the MIP looks across the sheet; **Tilt across** and
   **Tilt along** turn it about two perpendicular axes, **Slab offset** moves it, **Face the slab** points the
   camera down the normal.

| Where | What |
| --- | --- |
| Panel | **CT volume** group: **Pick a point** (crosshair; click the papyrus; Esc cancels), **Show volume**. The floating **CT VOLUME · MIP** panel has Slab clip, Slab thickness, Slab offset, Tilt across, Tilt along, Window, Level, Cube size, Detail level, Auto contrast, Face the slab, Pick another point |
| Settings | **CT volume cube size (voxels)** (auto, 64, 128, 192, 256), **CT volume detail level** (auto, 0 to 4; auto is 1 on desktops, 2 on phones) |
| URL | `?ctvol=w035,0.5,0.5` (winding, u, v) or `?ctvol=4126,3926,5478` (scan voxels x, y, z), with `&ctlod=1`, `&ctsize=128`, `&ctslab=16` (voxels), `&cttilt=10,0` (degrees) |
| API | `unrollView.ct.volume.open({ winding, u, v } \| { voxel: [x, y, z] } \| { x, y } screen point, level?, size? })`, `close()`, `state()`, `setSlab({ on, thickness, offset, tiltX, tiltY, face })`, `setWindow(w, l)`, `auto()`, `setLevel(l)`, `setSize(n)`, `pick(on)`, `scanPoint(winding, u, v)`, `image()` (PNG data URL), `bench(n)` |
| Actions | `ctvol.pick`, `ctvol.show`, `ctvol.close` |
| Event | `unroll:ctvolume` on window (`open`, `loaded`) |

Only scrolls whose meshes were traced on a known public volume can open it (PHerc0139 today, see
`VOLUMES` in `lib/ctsource.js`); a manifest may name its own with `ctZarr` and `ctVoxelUM`.

## 4. Labeled segments

`lib/ctlabels.js`. When the cube has loaded, every winding grid (the traced segment meshes) is walked cell by
cell; cells within reach of the cube are split so samples sit under 0.7 voxels apart at the cube's detail
level, and each sample writes the segment's number (1 to 255) into an R8 label volume of the cube's size, with
its 6 neighbors, so a sheet is about 3 voxels thick. The label volume is a second `Data3DTexture` (nearest
filtering) in the same raymarch: the first label met along a ray tints the MIP pixel in the segment's color,
scaled by the MIP brightness; a highlighted segment is drawn stronger and the rest are dimmed.

| Where | What |
| --- | --- |
| Panel | **Labeled segments** checkbox in the CT VOLUME panel, then one chip per segment in the cube (color swatch and winding id); click to highlight, click again to clear |
| URL | `?ctlabels=1` (with `?ctvol=...`) |
| API | `unrollView.ct.volume.labels.show(on)`, `.highlight(id)`, `.state()` (segments, colors, voxel counts, build ms), `.colors()`; `window.unroll.ct.labels(on)`, `ct.highlight(id)` |

## 5. OME-Zarr streaming from the open data bucket

`lib/ctsource.js` reads the scan straight from `https://vesuvius-challenge-open-data.s3.amazonaws.com`
(the public bucket `s3://vesuvius-challenge-open-data`). Only that bucket is accepted, for the built-in
scrolls, for a manifest's `ctZarr` and for `?ctzarr=`. Level metadata comes from `<zarr>/<level>/.zarray`
(zarr v2, OME-Zarr multiscale levels 0 to 5) and the cube is assembled from the chunks it overlaps,
fetched 6 at a time (the PHerc0139 volume stores raw uint8 chunks, so no decompression is needed; a compressed level is refused with a clear error).

CORS: checked on 2026-10-16, a GET of `.zarray` with an `Origin` header answers `200` with
`Access-Control-Allow-Origin: *` and `Access-Control-Allow-Methods: HEAD, GET`, so no proxy is needed. If the
bucket ever stops sending CORS headers, the fallback is a small read-only proxy (for example a Hugging Face
Space or a Cloudflare Worker) that forwards GETs for that bucket only and adds the header.

| Where | What |
| --- | --- |
| URL | `?ctzarr=https://vesuvius-challenge-open-data.s3.amazonaws.com/<path>.zarr&ctum=9.362` |
| API | `window.unroll.ct.source()` (bucket, zarr URL, voxel size), `unrollView.ct.volume.state().source` |

## Agents: `window.unroll.ct`

`dragRes(mode)`, `setWindow(w, l)`, `autoContrast(pLow, pHigh)`, `fullRange()`, `contrast()`, `open(where)`,
`close()`, `state()`, `setSlab(o)`, `volumeWindow(w, l)`, `volumeAuto()`, `setDetail(level)`, `setSize(n)`,
`pick(on)`, `image()`, `labels(on)`, `highlight(id)`, `source()`. Specs in `lib/ctapi.js` (`CT_SPECS`), listed in
`api.json` with `extension: true`.