feat(geotiff): Consolidate helpers for GeoTIFF images. (#1469)

* rebase, linting/prettier

* lint

* Remove DTYPE_VALUES constant

Author: manzt

modules/geotiff/src/constants.ts

@@ -1,3 +1,2 @@
 export {loadGeoTiff} from './lib/load-geotiff';
-export {loadOMETiff} from './lib/load-ome-tiff';
 export {default as TiffPixelSource} from './lib/tiff-pixel-source';

modules/geotiff/src/index.ts

@@ -1,5 +1,4 @@
-import {fromUrl, fromBlob} from 'geotiff';
-import type {GeoTIFF} from 'geotiff';
+import {fromUrl, fromBlob, GeoTIFF} from 'geotiff';
 
 import {
   // createPoolProxy,
@@ -8,31 +7,45 @@ import {
 } from './utils/proxies';
 // import Pool from './lib/Pool';
 
-import {loadOMETiff} from './load-ome-tiff';
+import {loadOmeTiff, isOmeTiff} from './ome/load-ome-tiff';
+import type TiffPixelSource from './tiff-pixel-source';
 
-interface TiffOptions {
+/** Options for initializing a tiff pixel source. */
+interface GeoTIFFOptions {
+  /** Headers passed to each underlying request. */
   headers?: Record<string, unknown>;
+  /** Performance enhancment to index the remote tiff source using pre-computed byte-offsets. Generated via https://github.com/ilan-gold/generate-tiff-offsets */
   offsets?: number[];
+  /** Indicates whether a multi-threaded pool of image decoders should be used to decode tiles. */
   pool?: boolean;
 }
 
+interface GeoTIFFData {
+  data: TiffPixelSource<string[]>[];
+  metadata: Record<string, unknown>;
+}
+
 /**
  * Opens an OME-TIFF via URL and returns data source and associated metadata for first image.
  *
- * @param {(string | File)} source url or File object.
- * @param {{ headers: (undefined | Headers), offsets: (undefined | number[]), pool: (undefined | boolean ) }} opts
- * Options for initializing a tiff pixel source. Headers are passed to each underlying fetch request. Offests are
- // * a performance enhancment to index the remote tiff source using pre-computed byte-offsets. Pool indicates whether a
- * multi-threaded pool of image decoders should be used to decode tiles (default = true).
- * @return {Promise<{ data: TiffPixelSource[], metadata: ImageMeta }>} data source and associated OME-Zarr metadata.
+ * @param source url string, File/Blob object, or GeoTIFF object
+ * @param opts options for initializing a tiff pixel source.
+ *  - `opts.headers` are passed to each underlying fetch request.
+ *  - `opts.offsets` are a performance enhancment to index the remote tiff source using pre-computed byte-offsets.
+ *  - `opts.pool` indicates whether a multi-threaded pool of image decoders should be used to decode tiles (default = true).
+ * @return data source and associated OME-Zarr metadata.
  */
-export async function loadGeoTiff(source: string | File, opts: TiffOptions = {}) {
-  const {headers, offsets, pool = true} = opts;
-
-  let tiff: GeoTIFF;
+export async function loadGeoTiff(
+  source: string | Blob | GeoTIFF,
+  opts: GeoTIFFOptions = {}
+): Promise<GeoTIFFData> {
+  const {headers, offsets} = opts;
 
   // Create tiff source
-  if (typeof source === 'string') {
+  let tiff: GeoTIFF;
+  if (source instanceof GeoTIFF) {
+    tiff = source;
+  } else if (typeof source === 'string') {
     tiff = await fromUrl(source, headers);
   } else {
     tiff = await fromBlob(source);
@@ -61,5 +74,11 @@ export async function loadGeoTiff(source: string | File, opts: TiffOptions = {})
    */
   checkProxies(tiff);
 
-  return loadOMETiff(tiff);
+  const firstImage = await tiff.getImage(0);
+
+  if (isOmeTiff(firstImage)) {
+    return loadOmeTiff(tiff, firstImage);
+  }
+
+  throw new Error('GeoTIFF not recognized.');
 }

modules/geotiff/src/lib/load-geotiff.ts

@@ -1,19 +1,15 @@
-import type {GeoTIFF} from 'geotiff';
-import {fromString} from './ome/omexml';
+import type {GeoTIFF, GeoTIFFImage} from 'geotiff';
 
-import TiffPixelSource from './tiff-pixel-source';
-import {getOmeLegacyIndexer, getOmeSubIFDIndexer, OmeTiffIndexer} from './ome/ome-indexers';
-import {getOmePixelSourceMeta} from './ome/ome-utils';
+import TiffPixelSource from '../tiff-pixel-source';
+import {getOmeLegacyIndexer, getOmeSubIFDIndexer, OmeTiffIndexer} from './ome-indexers';
+import {getOmePixelSourceMeta} from './ome-utils';
+import {fromString} from './omexml';
+import type {OmeTiffSelection} from './ome-indexers';
 
-export interface OmeTiffSelection {
-  t: number;
-  c: number;
-  z: number;
-}
+export const isOmeTiff = (img: GeoTIFFImage) => img.fileDirectory.ImageDescription.includes('<OME');
 
-export async function loadOMETiff(tiff: GeoTIFF) {
+export async function loadOmeTiff(tiff: GeoTIFF, firstImage: GeoTIFFImage) {
   // Get first image from tiff and inspect OME-XML metadata
-  const firstImage = await tiff.getImage(0);
   const {
     ImageDescription,
     SubIFDs,
@@ -25,7 +21,7 @@ export async function loadOMETiff(tiff: GeoTIFF) {
    * Image pyramids are stored differently between versions of Bioformats.
    * Thus we need a different indexer depending on which format we have.
    */
-  let levels;
+  let levels: number;
   let pyramidIndexer: OmeTiffIndexer;
 
   if (SubIFDs) {
@@ -51,8 +47,5 @@ export async function loadOMETiff(tiff: GeoTIFF) {
     return source;
   });
 
-  return {
-    data,
-    metadata: imgMeta
-  };
+  return {data, metadata: imgMeta};
 }

modules/geotiff/src/lib/load-ome-tiff.ts modules/geotiff/src/lib/ome/load-ome-tiff.ts

@@ -1,8 +1,7 @@
 import type {GeoTIFFImage, GeoTIFF, ImageFileDirectory} from 'geotiff';
 import type {OMEXML} from '../ome/omexml';
-// TODO - circular dependency
-import type {OmeTiffSelection} from '../load-ome-tiff';
 
+export type OmeTiffSelection = {t: number; c: number; z: number};
 export type OmeTiffIndexer = (sel: OmeTiffSelection, z: number) => Promise<GeoTIFFImage>;
 
 /*

modules/geotiff/src/lib/ome/ome-indexers.ts

@@ -1,7 +1,7 @@
 import {getDims, getLabels} from './utils';
 import type {OMEXML, UnitsLength} from './omexml';
 
-const DTYPE_LOOKUP = {
+export const DTYPE_LOOKUP = {
   uint8: 'Uint8',
   uint16: 'Uint16',
   uint32: 'Uint32',

modules/geotiff/src/lib/ome/ome-utils.ts

@@ -5,7 +5,7 @@ import type {
   PixelSource,
   PixelSourceSelection,
   PixelSourceMeta,
-  SupportedDtype,
+  Dtype,
   Labels,
   RasterSelection,
   TileSelection,
@@ -17,7 +17,7 @@ class TiffPixelSource<S extends string[]> implements PixelSource<S> {
 
   constructor(
     indexer: (sel: PixelSourceSelection<S>) => Promise<GeoTIFFImage>,
-    public dtype: SupportedDtype,
+    public dtype: Dtype,
     public tileSize: number,
     public shape: number[],
     public labels: Labels<S>,

modules/geotiff/src/lib/tiff-pixel-source.ts

@@ -1,10 +1,10 @@
-import type {DTYPE_VALUES} from './constants';
+import {DTYPE_LOOKUP} from './lib/ome/ome-utils';
 
-export type SupportedDtype = keyof typeof DTYPE_VALUES;
-export type SupportedTypedArray = InstanceType<typeof globalThis[`${SupportedDtype}Array`]>;
+export type Dtype = typeof DTYPE_LOOKUP[keyof typeof DTYPE_LOOKUP];
+export type TypedArray = InstanceType<typeof globalThis[`${Dtype}Array`]>;
 
 export interface PixelData {
-  data: SupportedTypedArray;
+  data: TypedArray;
   width: number;
   height: number;
 }
@@ -47,7 +47,7 @@ export interface PixelSource<S extends string[]> {
   getTile(sel: TileSelection<S>): Promise<PixelData>;
   onTileError(err: Error): void;
   shape: number[];
-  dtype: SupportedDtype;
+  dtype: Dtype;
   labels: Labels<S>;
   tileSize: number;
   meta?: PixelSourceMeta;

modules/geotiff/src/types.ts

@@ -1,4 +1,4 @@
-declare type TypedArray = import('../constants').TypedArray;
+declare type TypedArray = import('../types').TypedArray;
 
 declare module 'geotiff' {
   function fromUrl(url: string, headers?: Record<string, unknown>): Promise<GeoTIFF>;

modules/geotiff/src/typings/geotiff.ts

@@ -2,7 +2,7 @@ import test from 'tape-promise/tape';
 import {fromFile} from 'geotiff';
 import {resolvePath, isBrowser} from '@loaders.gl/core';
 
-import {loadOMETiff} from '@loaders.gl/geotiff';
+import {loadGeoTiff} from '@loaders.gl/geotiff';
 
 const TIFF_URL = resolvePath('@loaders.gl/geotiff/test/data/multi-channel.ome.tif');
 
@@ -12,7 +12,7 @@ test('Creates correct TiffPixelSource for OME-TIFF.', async (t) => {
     return;
   }
   const tiff = await fromFile(TIFF_URL);
-  const {data} = await loadOMETiff(tiff);
+  const {data} = await loadGeoTiff(tiff);
   t.equal(data.length, 1, 'image should not be pyramidal.');
   const [base] = data;
   t.deepEqual(base.labels, ['t', 'c', 'z', 'y', 'x'], 'should have DimensionOrder "XYZCT".');
@@ -28,7 +28,7 @@ test('Get raster data.', async (t) => {
     return;
   }
   const tiff = await fromFile(TIFF_URL);
-  const {data} = await loadOMETiff(tiff);
+  const {data} = await loadGeoTiff(tiff);
   const [base] = data;
 
   for (let c = 0; c < 3; c += 1) {
@@ -54,7 +54,7 @@ test('Correct OME-XML.', async (t) => {
     return;
   }
   const tiff = await fromFile(TIFF_URL);
-  const {metadata} = await loadOMETiff(tiff);
+  const {metadata} = await loadGeoTiff(tiff);
   const {Name, Pixels} = metadata;
   t.equal(Name, 'multi-channel.ome.tif', `Name should be 'multi-channel.ome.tif'.`);
   t.equal(Pixels.SizeC, 3, 'Should have three channels.');

modules/geotiff/test/ome-tiff.spec.js

@@ -2,7 +2,7 @@ import test from 'tape-promise/tape';
 import {fromFile} from 'geotiff';
 import {resolvePath, isBrowser} from '@loaders.gl/core';
 
-import {loadOMETiff} from '@loaders.gl/geotiff';
+import {loadGeoTiff} from '@loaders.gl/geotiff';
 
 const TIFF_URL = resolvePath('@loaders.gl/geotiff/test/data/multi-channel.ome.tif');
 
@@ -12,7 +12,7 @@ test('Creates correct TiffPixelSource for OME-TIFF.', async (t) => {
     return;
   }
   const tiff = await fromFile(TIFF_URL);
-  const {data} = await loadOMETiff(tiff);
+  const {data} = await loadGeoTiff(tiff);
   t.equal(data.length, 1, 'image should not be pyramidal.');
   const [base] = data;
   t.deepEqual(base.labels, ['t', 'c', 'z', 'y', 'x'], 'should have DimensionOrder "XYZCT".');
@@ -28,7 +28,7 @@ test('Get raster data.', async (t) => {
     return;
   }
   const tiff = await fromFile(TIFF_URL);
-  const {data} = await loadOMETiff(tiff);
+  const {data} = await loadGeoTiff(tiff);
   const [base] = data;
 
   for (let c = 0; c < 3; c += 1) {
@@ -54,7 +54,7 @@ test('Correct OME-XML.', async (t) => {
     return;
   }
   const tiff = await fromFile(TIFF_URL);
-  const {metadata} = await loadOMETiff(tiff);
+  const {metadata} = await loadGeoTiff(tiff);
   const {Name, Pixels} = metadata;
   t.equal(Name, 'multi-channel.ome.tif', `Name should be 'multi-channel.ome.tif'.`);
   t.equal(Pixels.SizeC, 3, 'Should have three channels.');