Deprecate loadBioformatsZarr function. Point users to loadOmeZarr instead (#939)

* Deprecate loadBioformatsZarr fn

* Formatting

* Format

* Update avivator labels

Author: keller-mark

.changeset/clean-tires-lie.md

@@ -0,0 +1,5 @@
+---
+"@vivjs/loaders": minor
+---
+
+Rename loadBioformatsZarr to DEPRECATED_loadBioformatsZarr to reduce confusion. Update its description to point users to loadOmeZarr instead.

packages/loaders/src/index.ts

@@ -1,5 +1,5 @@
 export { loadOmeTiff, loadMultiTiff } from './tiff';
-export { loadBioformatsZarr, loadOmeZarr } from './zarr';
+export { loadOmeZarr, DEPRECATED_loadBioformatsZarr } from './zarr';
 
 export { default as TiffPixelSource } from './tiff/pixel-source';
 export { default as ZarrPixelSource } from './zarr/pixel-source';

packages/loaders/src/zarr/index.ts

@@ -9,10 +9,30 @@ interface ZarrOptions {
   fetchOptions: RequestInit;
 }
 
+/**
+ * Opens root of multiscale OME-Zarr via URL.
+ *
+ * @param source url
+ * @param options
+ * @return data source and associated OME-Zarr metadata.
+ */
+export async function loadOmeZarr(
+  source: string,
+  options: Partial<ZarrOptions & { type: 'multiscales' }> = {}
+) {
+  const store = new FetchStore(source, options.fetchOptions);
+
+  if (options?.type !== 'multiscales') {
+    throw Error('Only multiscale OME-Zarr is supported.');
+  }
+
+  return loadOme(store);
+}
+
 /**
  * Internal helper to load bioformats zarr with specified metadata and zarr directory paths.
  */
-async function _loadBioformatsZarrWithPaths(
+async function _DEPRECATED_loadBioformatsZarrWithPaths(
   source: string | (File & { path: string })[],
   metadataPath: string,
   zarrDir: string,
@@ -58,53 +78,41 @@ async function _loadBioformatsZarrWithPaths(
 }
 
 /**
- * Opens root directory generated via `bioformats2raw`. Uses OME-XML metadata,
- * and assumes that the source url is the root for a single image.
- * This function is the zarr-equivalent to using loadOmeTiff - but
- * somewhat deprecated now in favour of `loadOmeZarr` for OME-NGFF compliant images.
+ * DEPRECATED: This function is designed to load Zarr data generated by an old version of bioformats2raw
+ * (circa 2022 and pre-v0.5.0). You are probably looking for the loadOmeZarr function instead,
+ * which is designed to load modern OME-Zarr data following the OME-NGFF specifications,
+ * which is also the current (as of 2026) bioformats2raw output format.
  *
- * Supports both old and new bioformats2raw formats:
- * - Old format: METADATA.ome.xml at root, data.zarr/ directory
- * - New format: OME/METADATA.ome.xml, root zarr directory
+ * OLD DESCRIPTION: Opens root directory generated via
+ * `bioformats2raw --file_type=zarr`.
+ * Uses OME-XML metadata, and assumes first image.
+ * This function is the zarr-equivalent to using loadOmeTiff.
+ *
+ * Supports both METADATA.ome.xml and OME/METADATA.ome.xml
  *
  * @param source url
  * @param options
  * @return data source and associated OMEXML metadata.
  */
-export async function loadBioformatsZarr(
+export async function DEPRECATED_loadBioformatsZarr(
   source: string | (File & { path: string })[],
   options: Partial<ZarrOptions> = {}
 ) {
   // Try both old and new formats in parallel, return the first successful result
   // Old format: METADATA.ome.xml at root, data.zarr/ directory
   // New format: OME/METADATA.ome.xml, root zarr directory
   return Promise.any([
-    _loadBioformatsZarrWithPaths(
+    _DEPRECATED_loadBioformatsZarrWithPaths(
       source,
       'METADATA.ome.xml',
       'data.zarr',
       options
     ),
-    _loadBioformatsZarrWithPaths(source, 'OME/METADATA.ome.xml', '', options)
+    _DEPRECATED_loadBioformatsZarrWithPaths(
+      source,
+      'OME/METADATA.ome.xml',
+      '',
+      options
+    )
   ]);
 }
-
-/**
- * Opens root of multiscale OME-Zarr via URL.
- *
- * @param source url
- * @param options
- * @return data source and associated OME-Zarr metadata.
- */
-export async function loadOmeZarr(
-  source: string,
-  options: Partial<ZarrOptions & { type: 'multiscales' }> = {}
-) {
-  const store = new FetchStore(source, options.fetchOptions);
-
-  if (options?.type !== 'multiscales') {
-    throw Error('Only multiscale OME-Zarr is supported.');
-  }
-
-  return loadOme(store);
-}

sites/avivator/README.md

@@ -47,6 +47,6 @@ static site in production.
 
 ## Instructions for use
 
-To use Avivator to visualize your own imaging data, use the URL input in the web application to provide a URL to an OME-TIFF/Bioformats-Zarr.
+To use Avivator to visualize your own imaging data, use the URL input in the web application to provide a URL to an OME-TIFF/OME-Zarr.
 
-To learn more about working with OME-TIFF files or Bioformats-Zarr stores, please visit the [tutorial](../tutorial/README.md).
+<!--To learn more about working with OME-TIFF files or OME-Zarr stores, please visit the [tutorial](../tutorial/README.md).-->

sites/avivator/src/components/Controller/components/Menu.jsx

@@ -124,7 +124,7 @@ function Header(props) {
           >
             <TextField
               id="ome-input"
-              label="OME-TIFF/Bioformats-Zarr URL"
+              label="OME-TIFF/OME-Zarr URL"
               variant="filled"
               size="small"
               fullWidth

sites/avivator/src/utils.js

@@ -5,9 +5,9 @@ import { useEffect, useState } from 'react';
 import {
   AdditiveColormap3DExtensions,
   ColorPalette3DExtensions,
+  DEPRECATED_loadBioformatsZarr,
   RENDERING_MODES,
   getChannelStats,
-  loadBioformatsZarr,
   loadMultiTiff,
   loadOmeTiff,
   loadOmeZarr
@@ -228,7 +228,7 @@ export async function createLoader(
     let source;
     try {
       source = await Promise.any([
-        loadBioformatsZarr(urlOrFile),
+        DEPRECATED_loadBioformatsZarr(urlOrFile),
         (async () => {
           // Transform OME-Zarr result to match bioformats format
           const res = await loadOmeZarr(urlOrFile, { type: 'multiscales' });

sites/docs/documentation.yml

@@ -44,6 +44,5 @@ toc:
   - name: Loaders
   - loadOmeTiff
   - loadOmeZarr
-  - loadBioformatsZarr
   - loadMultiTiff
   - name: Misc

sites/docs/src/API_STRUCTURE.md

@@ -43,7 +43,7 @@ Viv wraps both Tiff- and Zarr-based data sources in a unified `PixelSource` inte
 source can be thought of as a multi-dimensional "stack" of image data with labeled
 dimensions (usually `["t", "c", "z", "y", "x"]`). A multiscale image is represented as list
 of pixel sources decreasing in shape. Viv provides several helper functions to intialize a
-loader via url: `loadOmeTiff`, `loadBioformatsZarr`, `loadOmeZarr`, and `loadMultiTiff`.
+loader via url: `loadOmeTiff`, `loadOmeZarr`, and `loadMultiTiff`.
 Each function returns a `Promise` for an object of shape `{ data: PixelSouce[], metadata: M }`,
 where `M` is a JavaScript object containing the format-specific metadata for the image.
 For OME-TIFF and Bioformats-Zarr, and MultiTiff the metadata is identical (OME-XML representation),

sites/docs/tutorial/README.md

@@ -1,3 +1,8 @@
+NOTE (AS OF JAN 2026): This tutorial was written in 2022, and is now quite outdated.
+It was written before the OME-NGFF specification was published and therefore refers to bioformats2raw v0.5.0 or before which generated a zarr data representation that was a precursor to OME-NGFF/OME-Zarr.
+
+
+
 This guide demonstrates how to generate a pyramidal OME-TIFF [with Bio-Formats](https://www.glencoesoftware.com/blog/2019/12/09/converting-whole-slide-images-to-OME-TIFF.html) that can be viewed with
 [Avivator](http://avivator.gehlenborglab.org). Viv also supports [OME-NGFF](https://github.com/ome/ngff), but tooling to generate the format remains limited as the specification matures. We will update this tutorial accordingly when a method for generating OME-NGFF is endorsed by the Open Microscopy Environment.