# Live sheet

`live.html` streams one traced sheet (a tifxyz segment) and one scan volume (OME-Zarr: CT, or a 3D ink prediction)
straight from the Vesuvius Challenge open data bucket and shows the volume on the sheet in 3D. Nothing is packed
ahead of time and nothing is uploaded: your browser fetches only the rows of the segment inside the crop (HTTP Range)
and only the zarr chunks the samples touch, then samples and draws.

## The sampling rule

Each node of the segment grid gets one value: the volume's voxels along the node's normal over plus or minus
**Depth** level-0 voxels, reduced by **max** or **mean**, reading the nearest voxel of the chosen pyramid **level**
(numpy rounding). This is the rule of `kit sheetview` in [ChaseHendrick/Scrolls](https://github.com/ChaseHendrick/Scrolls),
which writes the same mesh for Neuroglancer, and the two agree: on the PHerc0139 w045 preset (119,301 points) the
largest difference was 6e-6, and on a blosc-compressed 3D ink volume (350,761 points) it was 0. **Refine grid**
adds bilinear midpoints (a new node is valid when its cell's four corners are). Holes (-1) stay holes.

## Inputs

| Field | URL parameter | Meaning |
| --- | --- | --- |
| Segment | `seg` | a tifxyz folder URL (`x.tif`, `y.tif`, `z.tif`, `meta.json`), uncompressed float32 in strips; the voxel size comes from the `-NNum.tifxyz` folder name |
| Volume | `vol` | an OME-Zarr v2 root in the segment's voxels, raw or blosc, uint8 to float32 |
| Crop | `crop=r0,r1,c0,c1` | rows and columns of the segment grid |
| Volume level | `level` | pyramid level; 1 halves the reads |
| Depth | `depth` | voxels each side of the sheet |
| Refine grid | `up` | 1 to 4 |
| Along the normal | `reduce` | `max` or `mean` |
| Colors | `palette` | `gray` or `ink` |
| | `autoload=1` | load at once |

Example: `/live.html?crop=500,650,700,900&level=1&depth=4&up=2&reduce=mean&autoload=1`.

The presets are PHerc0139 w045 only, a public scan off the prize lists. Any public segment and volume in the bucket
work, since the bucket answers CORS for GET and HEAD.

## Outputs

- **Download VTK**: the mesh with its values as ASCII VTK, the format Neuroglancer's `vtk://` source and ParaView read.
- **Volume in neuroglancer**: the hosted Neuroglancer on the same volume.

An ink prediction shown here is model output, not a reading.

## For agents

```js
await liveSheet.load({ seg, vol, crop: [r0, r1, c0, c1], level: 1, depth: 4, up: 2, reduce: 'mean' });
liveSheet.state();        // params, vertices, triangles, chunks, samplesPerVertex, volume
liveSheet.values();       // the value of every grid node (NaN at holes)
liveSheet.turn(30);       // orbit the camera, degrees
liveSheet.screenshot();   // PNG data URL
```

`lib/livesheet.js` has no DOM and runs in Node too: `readSegment`, `upsample`, `normals`, `openVolume`,
`sampleSheet`, `sheetMesh`, `toVTK`. Tests: `node tests/livesheet.mjs` (no network).

## Limits

Zarr v3 volumes, zarr filters, compressed or tiled TIFFs are refused with a message. A crop of about 150 by 200 nodes
refined twice is about 120,000 points and loads in about 15 s; the raw PHerc0139 CT at level 1 reads about 600 MB for
it, so prefer level 2 for wide crops.