feat: generate viewer links dynamically for Zarr datasets by allison-truhlar · Pull Request #307 · JaneliaSciComp/fileglancer

allison-truhlar · 2026-02-02T21:27:51Z

Clickup id: 86advt10e

This PR implements dynamic viewer configuration for Zarr datasets via a build-time viewers.config.yaml file and integration of the @bioimagetools/capability-manifest library for automatic dataset-viewer compatibility detection.

Changes

Created viewers.config.yaml with documentation for customizing viewer configuration. This file specifies available viewers for a Fileglancer deployment. The default configuration is our current viewers: Neuroglancer, Avivator, Vol-E, and OME-Zarr Validator. Configuration is bundled at build time.
Added ViewersContext for managing viewer configuration. This context:
- Loads and validates viewer configuration from YAML at initialization
- Fetches capability manifests using @bioimagetools/capability-manifest library, or load from the /public folder bundled into the application during the build (this is currently the case since the manifests are not present on our main branch, only in this PR branch)
- Provides getCompatibleViewers() function to determine dataset-viewer compatibility using the capability-manifest library for compatibility detection
Refactored useZarrMetadata to dynamically generate openWithToolUrls using ViewersContext. URLs are generated only for compatible viewers based on the getCompatibleViewers function.
Updated DataToolLinks to render viewer buttons dynamically by mapping over valid viewers from ViewersContext. The "Copy URL" tool is always available when a data link is available.
Added logo management system with convention-based naming ({name}.png), custom logo override support, and fallback logo for missing assets.
Added unit tests for config parsing and component tests for DataToolLinks.
Updated documentation with a ViewersConfiguration.md guide and updated CLAUDE.md with viewer configuration instructions.

- Custom viewers (validator, vol-e) now check for multiscales - Ensures viewers only display for OME-Zarr datasets, not plain Zarr arrays - Update DataToolLinks alt text to use displayName for E2E test compatibility

Add useCallback to memoize the getCompatibleViewers function in ViewersContext to prevent unnecessary recalculations and improve performance when filtering compatible viewers based on metadata.

Add more detailed error logging and ensure graceful degradation when: - Capability manifests fail to load - Viewer configuration parsing fails - No valid viewers are configured The application will continue with an empty viewer list and clear console messages to help users troubleshoot configuration issues.

neomorphic

Looks good to me. I was able to enable and disable a viewer using the viewers.config.yaml. I added a few comments about some the code I wasn't sure on.

frontend/src/config/viewerLogos.ts

frontend/src/queries/n5Queries.ts

frontend/src/hooks/useN5Metadata.ts

frontend/src/config/viewersConfig.ts

frontend/src/contexts/ViewersContext.tsx

- previously, if a logo path wasn't found, a 404 URL was still created, so it was never falling through to the fallback_logo.

- includes checking that a fallback_logo is used when no logo is found for a viewer

…e → Vol-E)

…atch

…to mimic intended setup

…iewers confi

docs/Development.md

.devcontainer/devcontainer.json

krokicki · 2026-03-02T15:33:51Z

docs/Development.md

+
+**Quick Setup:**
+
+1. Edit the configuration file at `frontend/src/config/viewers.config.yaml` to enable/disable viewers or customize URLs


It's best not to edit committed source code to change configuration. If users change version controlled code then they will have problems staying up to date with upstream changes. One alternative pattern for this would be to allow users to copy this file into the main directory with their own changes, and then during the build use it to override the default config.

I changed to the suggested pattern in commit 774a1ac, added documentation for this in commit e9f9649 and a test for it in commit d4572bf. Does this look okay?

frontend/src/contexts/ViewersContext.tsx

krokicki · 2026-03-02T15:55:19Z

frontend/src/hooks/useZarrMetadata.ts

-          openWithToolUrls.avivator = null;
+      // Convert our metadata to OmeZarrMetadata format for capability checking
+      const omeZarrMetadata = {
+        version: effectiveZarrVersion === 3 ? '0.5' : '0.4',


This is extremely fragile code from my original vibe-coded prototype. We need a better way to get the NGFF version.

Starting in NGFF 0.5, there is an attribute that specifies the version (https://ngff.openmicroscopy.org/specifications/0.5/index.html#ome-zarr-metadata).

I'm not sure if there's a reliable way to tell for versions prior to 0.5. @mkitti do you know? We could take a look at the OME-NGFF Validator, which somehow prints the version.

There are some hints here:
https://www.openmicroscopy.org/2021/12/16/ome-ngff.html

I think we should not put too much effort into identifying pre-0.4 OME-NGFF. At best, it might provide some degradation path if axes or other elements are missing: if axes are missing, assume XYZCT.

If necessary, we comb through the old specs:
https://ngff.openmicroscopy.org/specifications/0.1/index.html

What I am more concerned about in the above code is future compatibility. OME-NGFF 0.6 is coming soon. If we do see Zarr v3, we should look for and parse the attributes.ome.version key.

OME-NGFF Validator has a straightforward function to determine the version number that I could borrow: https://github.com/ome/ome-ngff-validator/blob/01ca6c8dae499914114acd136353ac452f93bce4/src/utils.js#L138
If no version metadata is found, since version wasn't required metadata in 0.4 and earlier, it defaults to 0.4.

Yep, that makes sense for now. In the long term it would be nice if there was a single library that we relied on for all OME-Zarr parsing, ideally something that integrates with a thumbnail library like ome-zarr.js. I started an issue over there.

A related question - should I be switching all my version numbers in the app from the Zarr versions (2, 3) to using OME-Zarr version numbers when possible - i.e., only using Zarr version numbers when there isn't OME metadata available?

Zarr version is distinct from OME-Zarr version. Those are two separate version numbers. However, OME-Zarr 0.5+ is only defined on Zarr version 3 at the moment.

Here's what this looks like now: https://github.com/JaneliaSciComp/fileglancer/pull/307/changes#diff-472127167cec0c0cf8f508d637d7736126efccafdbf76cc0513fa01a494f7b16R49

See commits 10ab39e, 5b91435, da940a1

How does this look?

Add a gitignored frontend/viewers.config.yaml that, when present, is bundled instead of the committed default. Uses a Vite regex alias to correctly handle the ?raw query suffix. Includes a template file users can copy and customize without touching committed source.

- necessary for supporting unit test of how vite resolves the viewers.config.yaml file path at startup

- includes mock viewers.config.yaml file for CI

…EffectiveZarrStorageVersion utilities - also splits availableVersions in the ZarrMetadataResult type into availableZarrVersions (number[]) and availableOmeZarrVersions (string[])

… and read versions from content

… useZarrMetadata

- copy icon had changed from img to svg - i saved the vizarr/avivator logo under avivator.png, so needed to update vizarr -> avivator

allison-truhlar added 21 commits February 2, 2026 11:26

feat: add viewers configuration template

5f1a624

feat: add viewer configuration types and YAML parser

d0bf67c

feat: add ViewersContext for dynamic viewer configuration

6620486

refactor: make OpenWithToolUrls dynamic using Record type

24e030e

docs: add comment explaining type assertion in parseViewersConfig

9f5d1eb

refactor: use ViewersContext in useZarrMetadata for dynamic viewer URLs

28173ea

refactor: use ViewersContext in DataToolLinks for dynamic viewer icons

3fd00d7

chore: prettier formatting

9160eb4

chore: update logo names; add fallback logo

ecf1b62

docs: add viewers configuration guide

7698348

fix: require OME metadata for custom viewers without manifests

69ae1b6

- Custom viewers (validator, vol-e) now check for multiscales - Ensures viewers only display for OME-Zarr datasets, not plain Zarr arrays - Update DataToolLinks alt text to use displayName for E2E test compatibility

fix: update locators to match new defaults

3e15ae7

efactor: use committed config file instead of template

4292cdf

docs: add viewers configuration to CLAUDE.md

d545e28

refactor: remove unused keys from N5OpenWithToolUrls type

d5c24e9

perf: memoize getCompatibleViewers function

e6e1cd4

Add useCallback to memoize the getCompatibleViewers function in ViewersContext to prevent unnecessary recalculations and improve performance when filtering compatible viewers based on metadata.

chore: fix eslint warnings

58d163d

fix: add validation for ome-zarr verison numbers

5ae87ae

tests: unit tests for the viewer config parsing func

4b6db2e

tests: component tests for DataToolLinks

fef30cd

allison-truhlar requested review from krokicki and neomorphic February 2, 2026 21:28

allison-truhlar mentioned this pull request Feb 2, 2026

wip: add capability manifest pkg #305

Closed

Merge branch 'main' into viewers-config

82b9cfb

neomorphic approved these changes Feb 2, 2026

View reviewed changes

allison-truhlar added 4 commits February 3, 2026 10:10

fix: add ViewersProvider to unit test setup for zarr tests

d2a4e84

fix: change how logos urls are found

b0e97a3

- previously, if a logo path wasn't found, a 404 URL was still created, so it was never falling through to the fallback_logo.

tests: add unit tests for the getViewerLogo func

8b2af82

- includes checking that a fallback_logo is used when no logo is found for a viewer

chore: prettier formatting

1ebfb3e

allison-truhlar added 8 commits February 12, 2026 11:39

fix: use relative paths for viewer manifest URLs to fix CI failures

9c629d2

fix: capitalize viewer names in manifests (validator → Validator, vol…

f4e7f51

…e → Vol-E)

fix: use viewer label for logo alt text and update test locators to m…

3080e8a

…atch

chore: prettier formatting

06c0ab1

Merge branch 'main' into viewers-config

7e46003

refactor: change manifest_urls in viewers config to the GH repo urls …

1a3dff9

…to mimic intended setup

fix: decouple DataToolLinks tests from exact manifest_url values in v…

77502ae

…iewers confi

fix: correct templating for avivator/vizarr instance_template_url

f024930

krokicki reviewed Mar 2, 2026

View reviewed changes

allison-truhlar added 21 commits March 4, 2026 13:29

chore: add spaces back in md file that were removed by prettier plugin

67ed39a

fix: remove personal path

69b09d0

fix: rename validator manifest viewer.name to OME-Zarr Validator

6805035

docs: update viewers configuration docs to reflect override pattern

e9f9649

refactor: log viewer initialization errors once at the top level only

59d64ac

chore: add fileglancer domain to devcontainer firewall allowlist

a1324c5

chore: prettier formatting

a9deb49

refactor: extract resolveViewersConfigPath utility from vite.config.ts

27c0d81

- necessary for supporting unit test of how vite resolves the viewers.config.yaml file path at startup

test: add unit tests for viewers.config.yaml override path resolution

d4572bf

- includes mock viewers.config.yaml file for CI

chore: add s3.janelia.org to devcontainer firewall allowlist

b31e918

Merge branch 'main' into viewers-config

144446e

chore: update and trim down the frontend/CLAUDE.md file

d5f05dc

refactor: add getOmeNgffVersion, areZarrMetadataFilesPresent, and get…

10ab39e

…EffectiveZarrStorageVersion utilities - also splits availableVersions in the ZarrMetadataResult type into availableZarrVersions (number[]) and availableOmeZarrVersions (string[])

refactor: restructure fetchZarrMetadata to check all metadata sources…

5b91435

… and read versions from content

refactor: use real NGFF version and getEffectiveZarrStorageVersion in…

da940a1

… useZarrMetadata

refactor: update components for new zarr/OME-NGFF version API

1314821

test: update zarr version detection and metadata table tests

08a6691

tests: fix DataToolLinks tests

45cfc05

- copy icon had changed from img to svg - i saved the vizarr/avivator logo under avivator.png, so needed to update vizarr -> avivator

chore: move N5MetadataTable test to _tests_ directory

13642a7

chore: prettier formatting

032708a


		Quick Setup:

		1. Edit the configuration file at `frontend/src/config/viewers.config.yaml` to enable/disable viewers or customize URLs

Conversation

allison-truhlar commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Uh oh!

neomorphic left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

allison-truhlar commented Feb 2, 2026 •

edited

Loading