Navigate Viewer
navigate_viewerZoom or pan an open Rijksmuseum viewer to a specific detail of an artwork using coordinates or a relative crop.
Instructions
Zooms/pans an already-open viewer to a region — steer the user's view to a detail. Requires a viewUUID from a prior get_artwork_image call (the viewer must be open). Not for opening the viewer — use get_artwork_image. Not for visual analysis — use inspect_artwork_image.
In most cases you do NOT need this tool: inspect_artwork_image already auto-zooms the open viewer to whatever region it inspects. Call navigate_viewer only to move the user's view WITHOUT fetching image bytes for your own analysis.
By default, region coordinates are in full-image space (percentages or pixels of the original image), not relative to the current viewport. The same pct:x,y,w,h used in inspect_artwork_image will target the identical area in the viewer. Exception: when a command includes relativeTo, region is interpreted in that inspected crop's local coordinate space.
Region formats:
'pct:x,y,w,h' — percentage of full image.
'crop_pixels:x,y,w,h' — pixel coordinates of the full image. Use nativeWidth/nativeHeight returned by inspect_artwork_image to bound values. When used with relativeTo + relativeToSize, crop_pixels is instead interpreted as pixels within that inspected crop.
'x,y,w,h' — equivalent to crop_pixels: (legacy IIIF form, kept for compatibility).
'full' | 'square' — whole image shortcuts.
Out-of-bounds regions are rejected with an overlay_region_out_of_bounds warning — correct the coordinates and retry. Keep batches under 10 commands per call. The viewer session (viewUUID) remains active for 30 minutes of idle inactivity — any polling or navigation resets the clock.
Coordinate shortcut: to zoom to a region of a prior inspect_artwork_image crop, use 'relativeTo' with the crop's region string and specify 'region' as coordinates within the crop's local space; the server projects to full-image space deterministically. Use pct:x,y,w,h for crop-local percentages, or crop_pixels:x,y,w,h plus relativeToSize:{width: cropPixelWidth, height: cropPixelHeight} from inspect_artwork_image for crop-local rendered pixels.
Response field deliveryState reports whether the iframe drained the commands immediately (delivered_recently), the iframe exists but hasn't polled recently and the commands are queued (queued_waiting_for_viewer — typical when scrolled out of view), or no iframe has connected yet (no_live_viewer_seen). In the queued case, the command is preserved server-side and will apply automatically when the viewer resumes polling — do not narrate this as a delivery failure to the user.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| commands | Yes | Zoom/pan commands to execute in the viewer, in order | |
| viewUUID | Yes | Viewer UUID from a prior get_artwork_image call |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| queued | Yes | ||
| viewUUID | Yes | ||
| imageWidth | No | ||
| imageHeight | No | ||
| lastPolledAt | No | ISO timestamp of the iframe's last poll. Absent if the iframe has never polled this session. | |
| objectNumber | No | Object number of the artwork in this viewer session — gives a structuredContent reader the identity needed for a follow-up call without parsing prose. | |
| deliveryState | No | Server's view of command delivery: delivered, queued for an existing-but-offscreen viewer, or no viewer ever connected. | |
| regionRecovery | No | Out-of-bounds recovery hint. Present only on an `overlay_region_out_of_bounds` error — mirrors the recovery payload the text channel renders, so a structuredContent reader can self-correct without parsing prose. | |
| pendingCommandCount | No | Commands sitting in the queue that the iframe has not yet drained. | |
| recentlyPolledByViewer | No | True if the iframe polled within the last 5s. |