Skip to content

feat(viewer): picture-in-picture overview of the whole image - #173

Open
davehorsfall wants to merge 3 commits into
devfrom
feat/172-overview
Open

davehorsfall wants to merge 3 commits into
devfrom
feat/172-overview

Conversation

@davehorsfall

Copy link
Copy Markdown
Member

Closes #172. A picture-in-picture overview: everything loaded, drawn small in the
bottom-right, with the part on screen outlined, and clicking it moves the view there.

http://localhost:5173/?source=https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.4/idr0062A/6001240.zarr&overview=1

A second view, not a second copy of everything

Two approaches were available and I took neither.

Viv's OverviewLayer is exported and we already depend on Viv, but it builds its own
image layer from loader, selections and contrastLimits. Using it means a second copy
of every channel setting to keep in step, and it knows nothing about our label layers, grid
layers or the ROI plugin's layers — so the overview would drift from the view it is meant to
describe.

biongff-viewer#46 duplicates every
layer with an -OVERVIEW id and draws the rectangle as a positioned div. Deck already
draws every layer into every view unless told otherwise, so duplication is only needed when
the copies differ; here layerFilter just excludes what makes no sense twice — the scale
bar, which measures the view it was computed for, and the outlines, which exist for the
overview alone.

The rectangle is a polygon inside the overview's viewport. It is the inverse of fitting an
image to a viewport, and the fiddly part of that is reconciling screen pixels with image
coordinates — which, inside a viewport, deck does for you. That is the whole difference
between this and the thirty lines of clamping in #46.

Decisions, as agreed on the issue

It frames the union of every source, not the first. The scale bar and the orientation
compass read the first because they describe a frame of reference, and several images can
disagree about one. An overview describes where you are looking, and that answer is the same
whatever is drawn — elements registered against each other, the ordinary case in a
SpatialData container, would be cut off by framing only one of them.

Nothing is drawn for a plate or a well, and the button is not offered. A grid is already
an overview: it shows every position at once and is navigated by clicking into one.

Bottom-right, keeping the shape of what it shows, 150–350 px wide, 25 px from the corner
— Viv's defaults, so an overview here is the size people expect one to be.

What is tested, and what is not

overview.ts is pure and has 19 tests, because every mistake available in it draws a
rectangle: in the wrong place, the wrong size, or around the wrong thing. None throws, and
on an unfamiliar image none looks obviously wrong. The tests pin the viewport corners
(including that the strip beneath the floating panel is inside them), extents under a
rotation, the union, and the box geometry at the clamps.

Checked in a browser: the toggle appears and ?overview=1 presses it, a plate offers no
button at all, and nothing throws with the second view and the outline layer live.

I could not check that it looks right. Headless WebGL renders the canvas black here, so
the thing worth your eye is whether the outlines sit where they should and track panning.

Also fixed on the way

handleClick did not check which viewport a click came from, and it drills into grid cells.
A click in the overview now means "look here" and stops; without that guard, clicking the
overview of a plate would have navigated into a well.

Not in this PR

Drag-to-pan inside the overview, a resizable or repositionable one, and a detached window.
All are easy once the first version is real.

One known rough edge: at narrow widths the overview and the warning snackbar both want the
bottom of the window. The snackbar is dismissible and transient, and it is the same
collision already noted on #164.

🤖 Generated with Claude Code

Zoomed in, there was nothing to say where you were. The overview draws
everything loaded, small, in the bottom-right corner, with the part on screen
outlined, and clicking it moves the view there.

A second `OrthographicView` and the same layers, rather than the two approaches
that were available.

Not Viv's `OverviewLayer`, although we depend on Viv and it is exported: it
builds its own image layer from `loader`, `selections` and `contrastLimits`, so
using it would mean a second copy of every channel setting to keep in step, and
it knows nothing of our label layers, grid layers or the ROI plugin's. The
overview would drift from the view it is meant to describe.

Not duplicated layers either. Deck draws every layer into every view unless told
otherwise, so `layerFilter` only has to exclude what makes no sense twice: the
scale bar, which measures the view it was computed for, and the outlines, which
exist for the overview alone.

The outlines are a polygon in the overview's own viewport rather than a
positioned `div`. The rectangle is the inverse of fitting an image to a
viewport, and the fiddly part of that arithmetic is reconciling screen pixels
with image coordinates -- which, inside a viewport, deck does. What is left is
in `overview.ts` and tested: every mistake available there draws a rectangle,
none of them throws, and on an unfamiliar image none of them looks wrong.

It frames the union of every source, not the first. The scale bar and the
orientation compass read the first because they describe a frame of reference
and several images can disagree about one; this describes where you are looking,
and elements registered against each other -- the ordinary case in a SpatialData
container -- would be cut off by framing only one of them.

Nothing is drawn for a plate or a well, and the button is not offered. A grid is
already an overview: it shows every position at once and is navigated by
clicking into one, so a smaller copy of the same arrangement in the corner is a
way to get lost rather than a way to orient.

The box keeps the shape of what it shows, between 150 and 350 px wide, 25 px
from the corner, after Viv's defaults, so an overview here is the size people
expect. A tall image gets a narrow strip rather than a square with the image
stranded inside it.

`?overview=1` opens with it showing, so a link can point at a region and say
where it sits.

A click in the overview means "look here" and nothing else: without the guard it
would have gone on to the plugins and then to the grid, and clicking the
overview of a plate would have navigated into a well.

Closes #172

Co-Authored-By: Claude Opus 5 <[email protected]>
Copilot AI balanced review requested due to automatic review settings November 4, 2026 08:53
@netlify

netlify Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for biongff-vizarr ready!

Name Link
🔨 Latest commit 0f7c3f4
🔍 Latest deploy log https://app.netlify.com/projects/biongff-vizarr/deploys/6aeaf49571084f8461af971c
😎 Deploy Preview https://deploy-preview-173--biongff-vizarr.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@codecov

codecov Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 51.19048% with 41 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
viewer/src/components/Viewer.tsx 11.90% 28 Missing and 9 partials ⚠️
viewer/src/overview.ts 90.24% 4 Missing ⚠️

📢 Thoughts on this report? Let us know!

Opening the overview made a large image go soft. A tiled layer resolves which
resolution to fetch from the viewport it is updated against and keeps one
tileset, so sharing an instance between the detail view and the overview leaves
one of them wrong -- and it is the overview's zoom that wins, which means the
detail view draws the lowest level of the pyramid.

It showed on an 8-level Xenium slide, 22799 x 13742, and not on a 275 x 271
label image: the second is a single tile at full resolution, so there is nothing
for it to drop to and nothing to see.

So the overview gets its own copies of the layers, carrying a suffix the layer
filter routes on. They are cheap, because the tiles they ask for are the small
ones.

This is what biongff-viewer#46 does, and the commit that added the overview said
not to, on the grounds that deck draws one instance into several views and
duplicating meant keeping two copies of every channel setting in step. The first
half is true and the second does not follow: `clone` copies the props, so the
settings have one home and the tilesets have two, which is exactly the split
that was needed. Duplicating there was not redundancy.

Reported by the user, who saw it blur on one image and not another.

Refs #172

Co-Authored-By: Claude Opus 5 <[email protected]>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved overview defects cause stale viewport outlines after resizing, clipped transformed images, overflow on small canvases, and image-click callbacks that interfere with recentering.

4 open issues
What changed in this PR

Adds a picture-in-picture overview to help users locate and navigate the visible region within loaded images, addressing #172. It reuses existing layers in a second view rather than duplicating channel state.

Changes:

  • Adds overview geometry, image and viewport outlines, and click-to-center navigation.
  • Adds a toolbar toggle and initial visibility through the viewer’s overview prop and ?overview=1, excluding plates and wells.
  • Adds 19 tests covering viewport corners, transformed extents, sizing, and fitting.
File Description
viewer/​tests/​overview.test.ts Tests overview geometry and sizing.
viewer/​src/​state.ts Adds overview visibility state.
viewer/​src/​overview.ts Implements extent, sizing, and viewport geometry helpers.
viewer/​src/​components/​VizarrViewer.tsx Exposes the initial overview visibility prop.
viewer/​src/​components/​Viewer.tsx Adds the overview view, outlines, layer filtering, and click routing.
viewer/​src/​components/​Menu.tsx Adds the overview toolbar toggle.
sites/​app/​src/​App.tsx Reads the overview URL parameter and passes it to the viewer.

Review effort: Balanced

Comment on lines +269 to +271
if (info.viewport?.id === OVERVIEW_VIEW_ID) {
setViewState((previous) => (previous ? { ...previous, target: coord } : previous));
return;
Comment on lines +320 to +331
{ polygon: viewportCorners(viewState), color: VIEWPORT_OUTLINE, width: 2 },
],
filled: false,
stroked: true,
getPolygon: (d: { polygon: Array<[number, number]> }) => d.polygon,
getLineColor: (d: { color: [number, number, number] }) => d.color,
getLineWidth: (d: { width: number }) => d.width,
lineWidthUnits: "pixels",
pickable: false,
}),
];
}, [overview, viewState]);
if (!overview) {
return [ortho];
}
return [ortho, new OrthographicView({ id: OVERVIEW_VIEW_ID, controller: false, clear: true, ...overview.box })];
Comment thread viewer/src/overview.ts
Comment on lines +143 to +146
if (width > maximumWidth) {
width = maximumWidth;
height = width * aspect;
}
The overview left eight pixels between the image and the edge of the corner it
occupies. Its viewport is cleared, so that room showed as a band of background
outside the outline -- a margin around a margin, with nothing in it.

There is none now, and the outline is the edge. It is also no longer Viv's red.
Red marks the image extent there because an overview may be larger than what it
shows; here the image is fitted to the corner exactly, so the two coincide and
the line is doing one job: framing the overview against whatever is behind it.
A frame should look like the rest of the interface, so it is drawn in the same
white at 0.38 as the panel borders.

The viewport rectangle keeps Viv's amber. That one carries information.

Reported by the user, who asked what the red box was for.

Refs #172

Co-Authored-By: Claude Opus 5 <[email protected]>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants