@loaders.gl/scientific 0.0.0-stage → 5.0.0-alpha.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (175) hide show
  1. package/README.md +21 -2
  2. package/dist/index.cjs +4313 -0
  3. package/dist/index.cjs.map +6 -0
  4. package/dist/index.d.ts +11 -0
  5. package/dist/index.d.ts.map +1 -0
  6. package/dist/index.js +8 -0
  7. package/dist/index.js.map +1 -0
  8. package/dist/netcdf/bundled.cjs +1394 -0
  9. package/dist/netcdf/bundled.d.ts +2 -0
  10. package/dist/netcdf/bundled.d.ts.map +1 -0
  11. package/dist/netcdf/bundled.js +5 -0
  12. package/dist/netcdf/bundled.js.map +1 -0
  13. package/dist/netcdf/index.cjs +1394 -0
  14. package/dist/netcdf/index.cjs.map +6 -0
  15. package/dist/netcdf/index.d.ts +7 -0
  16. package/dist/netcdf/index.d.ts.map +1 -0
  17. package/dist/netcdf/index.js +8 -0
  18. package/dist/netcdf/index.js.map +1 -0
  19. package/dist/netcdf/iobuffer/iobuffer.d.ts +253 -0
  20. package/dist/netcdf/iobuffer/iobuffer.d.ts.map +1 -0
  21. package/dist/netcdf/iobuffer/iobuffer.js +450 -0
  22. package/dist/netcdf/iobuffer/iobuffer.js.map +1 -0
  23. package/dist/netcdf/netcdf-format.cjs +39 -0
  24. package/dist/netcdf/netcdf-format.d.ts +11 -0
  25. package/dist/netcdf/netcdf-format.d.ts.map +1 -0
  26. package/dist/netcdf/netcdf-format.js +14 -0
  27. package/dist/netcdf/netcdf-format.js.map +1 -0
  28. package/dist/netcdf/netcdf-loader-with-parser.cjs +995 -0
  29. package/dist/netcdf/netcdf-loader-with-parser.d.ts +60 -0
  30. package/dist/netcdf/netcdf-loader-with-parser.d.ts.map +1 -0
  31. package/dist/netcdf/netcdf-loader-with-parser.js +35 -0
  32. package/dist/netcdf/netcdf-loader-with-parser.js.map +1 -0
  33. package/dist/netcdf/netcdf-loader.cjs +84 -0
  34. package/dist/netcdf/netcdf-loader.d.ts +81 -0
  35. package/dist/netcdf/netcdf-loader.d.ts.map +1 -0
  36. package/dist/netcdf/netcdf-loader.js +41 -0
  37. package/dist/netcdf/netcdf-loader.js.map +1 -0
  38. package/dist/netcdf/netcdf-source-loader-types.cjs +78 -0
  39. package/dist/netcdf/netcdf-source-loader-types.d.ts +28 -0
  40. package/dist/netcdf/netcdf-source-loader-types.d.ts.map +1 -0
  41. package/dist/netcdf/netcdf-source-loader-types.js +32 -0
  42. package/dist/netcdf/netcdf-source-loader-types.js.map +1 -0
  43. package/dist/netcdf/netcdf-source-loader.cjs +1319 -0
  44. package/dist/netcdf/netcdf-source-loader.d.ts +59 -0
  45. package/dist/netcdf/netcdf-source-loader.d.ts.map +1 -0
  46. package/dist/netcdf/netcdf-source-loader.js +421 -0
  47. package/dist/netcdf/netcdf-source-loader.js.map +1 -0
  48. package/dist/netcdf/netcdfjs/netcdf-reader.d.ts +68 -0
  49. package/dist/netcdf/netcdfjs/netcdf-reader.d.ts.map +1 -0
  50. package/dist/netcdf/netcdfjs/netcdf-reader.js +172 -0
  51. package/dist/netcdf/netcdfjs/netcdf-reader.js.map +1 -0
  52. package/dist/netcdf/netcdfjs/netcdf-types.d.ts +70 -0
  53. package/dist/netcdf/netcdfjs/netcdf-types.d.ts.map +1 -0
  54. package/dist/netcdf/netcdfjs/netcdf-types.js +3 -0
  55. package/dist/netcdf/netcdfjs/netcdf-types.js.map +1 -0
  56. package/dist/netcdf/netcdfjs/read-data.d.ts +19 -0
  57. package/dist/netcdf/netcdfjs/read-data.d.ts.map +1 -0
  58. package/dist/netcdf/netcdfjs/read-data.js +51 -0
  59. package/dist/netcdf/netcdfjs/read-data.js.map +1 -0
  60. package/dist/netcdf/netcdfjs/read-header.d.ts +16 -0
  61. package/dist/netcdf/netcdfjs/read-header.d.ts.map +1 -0
  62. package/dist/netcdf/netcdfjs/read-header.js +227 -0
  63. package/dist/netcdf/netcdfjs/read-header.js.map +1 -0
  64. package/dist/netcdf/netcdfjs/read-type.d.ts +36 -0
  65. package/dist/netcdf/netcdfjs/read-type.d.ts.map +1 -0
  66. package/dist/netcdf/netcdfjs/read-type.js +135 -0
  67. package/dist/netcdf/netcdfjs/read-type.js.map +1 -0
  68. package/dist/netcdf/unbundled.cjs +1394 -0
  69. package/dist/netcdf/unbundled.d.ts +2 -0
  70. package/dist/netcdf/unbundled.d.ts.map +1 -0
  71. package/dist/netcdf/unbundled.js +5 -0
  72. package/dist/netcdf/unbundled.js.map +1 -0
  73. package/dist/netcdf.dev.js +3153 -0
  74. package/dist/netcdf.min.js +12 -0
  75. package/dist/zarr/bundled.d.ts +2 -0
  76. package/dist/zarr/bundled.d.ts.map +1 -0
  77. package/dist/zarr/bundled.js +5 -0
  78. package/dist/zarr/bundled.js.map +1 -0
  79. package/dist/zarr/geo-zarr-source-loader.d.ts +121 -0
  80. package/dist/zarr/geo-zarr-source-loader.d.ts.map +1 -0
  81. package/dist/zarr/geo-zarr-source-loader.js +692 -0
  82. package/dist/zarr/geo-zarr-source-loader.js.map +1 -0
  83. package/dist/zarr/index.cjs +14747 -0
  84. package/dist/zarr/index.cjs.map +6 -0
  85. package/dist/zarr/index.d.ts +11 -0
  86. package/dist/zarr/index.d.ts.map +1 -0
  87. package/dist/zarr/index.js +10 -0
  88. package/dist/zarr/index.js.map +1 -0
  89. package/dist/zarr/lib/consolidated-zarr.d.ts +31 -0
  90. package/dist/zarr/lib/consolidated-zarr.d.ts.map +1 -0
  91. package/dist/zarr/lib/consolidated-zarr.js +113 -0
  92. package/dist/zarr/lib/consolidated-zarr.js.map +1 -0
  93. package/dist/zarr/lib/load-zarr.d.ts +11 -0
  94. package/dist/zarr/lib/load-zarr.d.ts.map +1 -0
  95. package/dist/zarr/lib/load-zarr.js +22 -0
  96. package/dist/zarr/lib/load-zarr.js.map +1 -0
  97. package/dist/zarr/lib/spatial-multiscales.d.ts +14 -0
  98. package/dist/zarr/lib/spatial-multiscales.d.ts.map +1 -0
  99. package/dist/zarr/lib/spatial-multiscales.js +34 -0
  100. package/dist/zarr/lib/spatial-multiscales.js.map +1 -0
  101. package/dist/zarr/lib/utils.d.ts +28 -0
  102. package/dist/zarr/lib/utils.d.ts.map +1 -0
  103. package/dist/zarr/lib/utils.js +137 -0
  104. package/dist/zarr/lib/utils.js.map +1 -0
  105. package/dist/zarr/lib/zarr-data-cache.d.ts +13 -0
  106. package/dist/zarr/lib/zarr-data-cache.d.ts.map +1 -0
  107. package/dist/zarr/lib/zarr-data-cache.js +70 -0
  108. package/dist/zarr/lib/zarr-data-cache.js.map +1 -0
  109. package/dist/zarr/lib/zarr-pixel-source.d.ts +41 -0
  110. package/dist/zarr/lib/zarr-pixel-source.d.ts.map +1 -0
  111. package/dist/zarr/lib/zarr-pixel-source.js +97 -0
  112. package/dist/zarr/lib/zarr-pixel-source.js.map +1 -0
  113. package/dist/zarr/lib/zarrita-pixel-source.d.ts +40 -0
  114. package/dist/zarr/lib/zarrita-pixel-source.d.ts.map +1 -0
  115. package/dist/zarr/lib/zarrita-pixel-source.js +96 -0
  116. package/dist/zarr/lib/zarrita-pixel-source.js.map +1 -0
  117. package/dist/zarr/ome-zarr-source-loader.d.ts +195 -0
  118. package/dist/zarr/ome-zarr-source-loader.d.ts.map +1 -0
  119. package/dist/zarr/ome-zarr-source-loader.js +523 -0
  120. package/dist/zarr/ome-zarr-source-loader.js.map +1 -0
  121. package/dist/zarr/spatial-data-source.d.ts +95 -0
  122. package/dist/zarr/spatial-data-source.d.ts.map +1 -0
  123. package/dist/zarr/spatial-data-source.js +242 -0
  124. package/dist/zarr/spatial-data-source.js.map +1 -0
  125. package/dist/zarr/types.d.ts +105 -0
  126. package/dist/zarr/types.d.ts.map +1 -0
  127. package/dist/zarr/types.js +5 -0
  128. package/dist/zarr/types.js.map +1 -0
  129. package/dist/zarr/unbundled.d.ts +2 -0
  130. package/dist/zarr/unbundled.d.ts.map +1 -0
  131. package/dist/zarr/unbundled.js +5 -0
  132. package/dist/zarr/unbundled.js.map +1 -0
  133. package/dist/zarr/zarr-array-source.d.ts +102 -0
  134. package/dist/zarr/zarr-array-source.d.ts.map +1 -0
  135. package/dist/zarr/zarr-array-source.js +132 -0
  136. package/dist/zarr/zarr-array-source.js.map +1 -0
  137. package/dist/zarr/zarr-loader-types.d.ts +236 -0
  138. package/dist/zarr/zarr-loader-types.d.ts.map +1 -0
  139. package/dist/zarr/zarr-loader-types.js +128 -0
  140. package/dist/zarr/zarr-loader-types.js.map +1 -0
  141. package/dist/zarr.dev.js +16574 -0
  142. package/dist/zarr.min.js +79 -0
  143. package/package.json +62 -4
  144. package/src/index.ts +52 -0
  145. package/src/netcdf/bundled.ts +5 -0
  146. package/src/netcdf/index.ts +14 -0
  147. package/src/netcdf/iobuffer/iobuffer.ts +510 -0
  148. package/src/netcdf/netcdf-format.ts +16 -0
  149. package/src/netcdf/netcdf-loader-with-parser.ts +54 -0
  150. package/src/netcdf/netcdf-loader.ts +62 -0
  151. package/src/netcdf/netcdf-source-loader-types.ts +45 -0
  152. package/src/netcdf/netcdf-source-loader.ts +526 -0
  153. package/src/netcdf/netcdfjs/LICENSE +24 -0
  154. package/src/netcdf/netcdfjs/netcdf-reader.ts +196 -0
  155. package/src/netcdf/netcdfjs/netcdf-types.ts +75 -0
  156. package/src/netcdf/netcdfjs/read-data.ts +71 -0
  157. package/src/netcdf/netcdfjs/read-header.ts +277 -0
  158. package/src/netcdf/netcdfjs/read-type.ts +147 -0
  159. package/src/netcdf/unbundled.ts +5 -0
  160. package/src/zarr/bundled.ts +5 -0
  161. package/src/zarr/geo-zarr-source-loader.ts +998 -0
  162. package/src/zarr/index.ts +60 -0
  163. package/src/zarr/lib/consolidated-zarr.ts +190 -0
  164. package/src/zarr/lib/load-zarr.ts +31 -0
  165. package/src/zarr/lib/spatial-multiscales.ts +47 -0
  166. package/src/zarr/lib/utils.ts +162 -0
  167. package/src/zarr/lib/zarr-data-cache.ts +91 -0
  168. package/src/zarr/lib/zarr-pixel-source.ts +134 -0
  169. package/src/zarr/lib/zarrita-pixel-source.ts +141 -0
  170. package/src/zarr/ome-zarr-source-loader.ts +837 -0
  171. package/src/zarr/spatial-data-source.ts +370 -0
  172. package/src/zarr/types.ts +129 -0
  173. package/src/zarr/unbundled.ts +5 -0
  174. package/src/zarr/zarr-array-source.ts +225 -0
  175. package/src/zarr/zarr-loader-types.ts +166 -0
@@ -0,0 +1,370 @@
1
+ // loaders.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // Copyright (c) vis.gl contributors
4
+
5
+ import type {CoreAPI} from '@loaders.gl/core/loader-utils';
6
+ import {
7
+ OMEZarrImageSource,
8
+ OMEZarrSourceLoaderWithParser,
9
+ type ZarrSourceLoader,
10
+ type ZarrSourceLoaderOptions,
11
+ ZarrSource
12
+ } from './ome-zarr-source-loader';
13
+ import {ZarrArraySource, type ZarrArraySourceLoaderOptions} from './zarr-array-source';
14
+ import type {ZarrConsolidatedMetadata} from './lib/consolidated-zarr';
15
+
16
+ /** SpatialData element families stored below a container root. */
17
+ export type SpatialDataElementKind = 'image' | 'labels' | 'points' | 'shapes' | 'table';
18
+
19
+ /** Storage convention used by one SpatialData element. */
20
+ export type SpatialDataElementFormat =
21
+ | 'ome-zarr'
22
+ | 'parquet-dataset'
23
+ | 'geoparquet'
24
+ | 'anndata-zarr';
25
+
26
+ /** A normalized SpatialData element discovered without reading its payload. */
27
+ export type SpatialDataElementMetadata = Readonly<{
28
+ /** Element family. */
29
+ kind: SpatialDataElementKind;
30
+ /** Element name within its family namespace. */
31
+ name: string;
32
+ /** Zarr group path relative to the SpatialData root. */
33
+ path: string;
34
+ /** URL of the element group or its external table payload. */
35
+ url: string;
36
+ /** Storage convention used to open the element. */
37
+ format: SpatialDataElementFormat;
38
+ /** SpatialData element encoding version when declared. */
39
+ version?: string;
40
+ /** Named element axes when declared. */
41
+ axes?: readonly string[];
42
+ /** Coordinate transformations retained in their interoperable NGFF representation. */
43
+ coordinateTransformations?: readonly unknown[];
44
+ /** Original group attributes for application-specific extensions. */
45
+ attributes: Readonly<Record<string, unknown>>;
46
+ }>;
47
+
48
+ /** Normalized metadata for a SpatialData container. */
49
+ export type SpatialDataSourceMetadata = Readonly<{
50
+ /** SpatialData container format version. */
51
+ version?: string;
52
+ /** Every discovered element in stable namespace and name order. */
53
+ elements: readonly SpatialDataElementMetadata[];
54
+ /** Image elements. */
55
+ images: readonly SpatialDataElementMetadata[];
56
+ /** Label raster elements. */
57
+ labels: readonly SpatialDataElementMetadata[];
58
+ /** Point-table elements. */
59
+ points: readonly SpatialDataElementMetadata[];
60
+ /** Shape-table elements. */
61
+ shapes: readonly SpatialDataElementMetadata[];
62
+ /** AnnData table elements. */
63
+ tables: readonly SpatialDataElementMetadata[];
64
+ /** Original root attributes. */
65
+ attributes: Readonly<Record<string, unknown>>;
66
+ }>;
67
+
68
+ /** Options for {@link SpatialDataSourceLoader}. */
69
+ export type SpatialDataSourceLoaderOptions = ZarrSourceLoaderOptions;
70
+
71
+ /** Runtime source returned for a Zarr-backed SpatialData raster or table array. */
72
+ export type SpatialDataZarrElementSource = OMEZarrImageSource | ZarrArraySource;
73
+
74
+ /** Source loader for SpatialData containers stored as Zarr. */
75
+ export const SpatialDataSourceLoaderWithParser = {
76
+ dataType: null as unknown as SpatialDataSource,
77
+ dataSource: null as unknown as SpatialDataSource,
78
+ batchType: null as never,
79
+ name: 'SpatialDataSourceLoader',
80
+ id: 'spatial-data',
81
+ module: 'scientific',
82
+ version: OMEZarrSourceLoaderWithParser.version,
83
+ extensions: ['zarr'],
84
+ mimeTypes: [],
85
+ type: 'spatial-data',
86
+ fromUrl: true,
87
+ fromBlob: false,
88
+ options: {
89
+ zarr: {
90
+ metadataPath: 'auto',
91
+ path: null,
92
+ labels: undefined!,
93
+ requireConsolidatedMetadata: true
94
+ }
95
+ } as SpatialDataSourceLoaderOptions,
96
+ defaultOptions: {
97
+ zarr: {
98
+ metadataPath: 'auto',
99
+ path: null,
100
+ labels: undefined!,
101
+ requireConsolidatedMetadata: true
102
+ }
103
+ },
104
+ testURL: (url: string): boolean => /\.zarr(?:$|[/?#])/i.test(url),
105
+ createDataSource: (
106
+ data: string,
107
+ options: SpatialDataSourceLoaderOptions,
108
+ coreApi?: CoreAPI
109
+ ): SpatialDataSource => new SpatialDataSource(data, options, coreApi)
110
+ } as const satisfies ZarrSourceLoader<SpatialDataSource>;
111
+
112
+ /** Discovers and opens the typed elements of a SpatialData Zarr container. */
113
+ export class SpatialDataSource extends ZarrSource {
114
+ /** Shared normalized metadata discovery request. */
115
+ private metadataPromise: Promise<SpatialDataSourceMetadata> | null = null;
116
+
117
+ /** Creates a SpatialData container source. */
118
+ constructor(data: string, options: SpatialDataSourceLoaderOptions = {}, coreApi?: CoreAPI) {
119
+ super(data, options, coreApi);
120
+ }
121
+
122
+ /** Discovers images, labels, points, shapes, and tables without reading payload chunks. */
123
+ async getMetadata(signal?: AbortSignal): Promise<SpatialDataSourceMetadata> {
124
+ this.metadataPromise ||= this.discoverMetadata(signal);
125
+ try {
126
+ return await this.metadataPromise;
127
+ } catch (error) {
128
+ this.metadataPromise = null;
129
+ throw error;
130
+ }
131
+ }
132
+
133
+ /** Returns one named element, throwing when the kind or name is absent. */
134
+ async getElement(
135
+ kind: SpatialDataElementKind,
136
+ name: string,
137
+ signal?: AbortSignal
138
+ ): Promise<SpatialDataElementMetadata> {
139
+ const metadata = await this.getMetadata(signal);
140
+ const element = metadata.elements.find(
141
+ candidate => candidate.kind === kind && candidate.name === name
142
+ );
143
+ if (!element) {
144
+ throw new Error(`SpatialData ${kind} element ${name} is not available.`);
145
+ }
146
+ return element;
147
+ }
148
+
149
+ /** Opens an image or label element as an OME-Zarr raster source. */
150
+ async createRasterSource(
151
+ kind: 'image' | 'labels',
152
+ name: string,
153
+ signal?: AbortSignal
154
+ ): Promise<OMEZarrImageSource> {
155
+ const element = await this.getElement(kind, name, signal);
156
+ return new OMEZarrImageSource(
157
+ this.data,
158
+ {
159
+ ...this.options,
160
+ zarr: {...this.options.zarr, path: joinZarrPath(this.path, element.path)}
161
+ },
162
+ this.hasCoreApi ? this.coreApi : undefined
163
+ );
164
+ }
165
+
166
+ /** Opens an array below an AnnData table element through the generic Zarr array source. */
167
+ async createTableArraySource(
168
+ name: string,
169
+ arrayPath: string,
170
+ options: ZarrArraySourceLoaderOptions['zarrArray'] = {},
171
+ signal?: AbortSignal
172
+ ): Promise<ZarrArraySource> {
173
+ const element = await this.getElement('table', name, signal);
174
+ let pathStart = 0;
175
+ let pathEnd = arrayPath.length;
176
+ while (pathStart < pathEnd && arrayPath[pathStart] === '/') {
177
+ pathStart++;
178
+ }
179
+ while (pathEnd > pathStart && arrayPath[pathEnd - 1] === '/') {
180
+ pathEnd--;
181
+ }
182
+ const normalizedArrayPath = arrayPath.slice(pathStart, pathEnd);
183
+ if (!normalizedArrayPath) {
184
+ throw new Error('SpatialData table array path must not be empty.');
185
+ }
186
+ return new ZarrArraySource(
187
+ this.data,
188
+ {
189
+ ...this.options,
190
+ zarr: {...this.options.zarr, path: joinZarrPath(this.path, element.path)},
191
+ zarrArray: {...options, path: normalizedArrayPath}
192
+ },
193
+ this.hasCoreApi ? this.coreApi : undefined
194
+ );
195
+ }
196
+
197
+ /** Loads and normalizes the consolidated SpatialData element catalog. */
198
+ private async discoverMetadata(signal?: AbortSignal): Promise<SpatialDataSourceMetadata> {
199
+ const consolidated = await this.getConsolidatedMetadata(signal);
200
+ const spatialDataPath = normalizeZarrPath(this.path);
201
+ const attributes = spatialDataPath
202
+ ? getGroupAttributes(consolidated, spatialDataPath)
203
+ : consolidated.rootAttributes;
204
+ const elements = Object.freeze(
205
+ discoverSpatialDataElements(this.url, consolidated, spatialDataPath)
206
+ );
207
+ const rootSpatialDataAttributes = getObject(attributes.spatialdata_attrs);
208
+ const metadata: SpatialDataSourceMetadata = {
209
+ version: getString(rootSpatialDataAttributes?.version),
210
+ elements,
211
+ images: getElementsByKind(elements, 'image'),
212
+ labels: getElementsByKind(elements, 'labels'),
213
+ points: getElementsByKind(elements, 'points'),
214
+ shapes: getElementsByKind(elements, 'shapes'),
215
+ tables: getElementsByKind(elements, 'table'),
216
+ attributes: Object.freeze({...attributes})
217
+ };
218
+ return Object.freeze(metadata);
219
+ }
220
+ }
221
+
222
+ const SPATIAL_DATA_NAMESPACES = Object.freeze([
223
+ {namespace: 'images', kind: 'image', format: 'ome-zarr'},
224
+ {namespace: 'labels', kind: 'labels', format: 'ome-zarr'},
225
+ {namespace: 'points', kind: 'points', format: 'parquet-dataset'},
226
+ {namespace: 'shapes', kind: 'shapes', format: 'geoparquet'},
227
+ {namespace: 'tables', kind: 'table', format: 'anndata-zarr'}
228
+ ] as const);
229
+
230
+ /** Discovers direct element groups beneath every SpatialData namespace. */
231
+ function discoverSpatialDataElements(
232
+ rootUrl: string,
233
+ consolidated: ZarrConsolidatedMetadata,
234
+ spatialDataPath: string
235
+ ): SpatialDataElementMetadata[] {
236
+ const elements: SpatialDataElementMetadata[] = [];
237
+ for (const definition of SPATIAL_DATA_NAMESPACES) {
238
+ const namespacePath = joinZarrPath(spatialDataPath, definition.namespace);
239
+ const paths = getDirectGroupChildren(consolidated, namespacePath);
240
+ for (const fullPath of paths) {
241
+ const name = fullPath.slice(namespacePath.length + 1);
242
+ const path = `${definition.namespace}/${name}`;
243
+ const attributes = getGroupAttributes(consolidated, fullPath);
244
+ const spatialDataAttributes = getObject(attributes.spatialdata_attrs);
245
+ elements.push(
246
+ Object.freeze({
247
+ kind: definition.kind,
248
+ name,
249
+ path,
250
+ url: getElementUrl(rootUrl, fullPath, definition.format),
251
+ format: definition.format,
252
+ version: getString(spatialDataAttributes?.version) || getString(attributes.version),
253
+ axes: getAxes(attributes),
254
+ coordinateTransformations: getCoordinateTransformations(attributes),
255
+ attributes: Object.freeze({...attributes})
256
+ })
257
+ );
258
+ }
259
+ }
260
+ return elements;
261
+ }
262
+
263
+ /** Joins normalized Zarr group paths without introducing a leading slash. */
264
+ function joinZarrPath(...paths: Array<string | null>): string {
265
+ return paths.map(normalizeZarrPath).filter(Boolean).join('/');
266
+ }
267
+
268
+ /** Normalizes an optional Zarr group path for consolidated metadata lookups. */
269
+ function normalizeZarrPath(path: string | null): string {
270
+ return path?.replace(/^\/+|\/+$/g, '') || '';
271
+ }
272
+
273
+ /** Returns group paths that are direct children of a namespace. */
274
+ function getDirectGroupChildren(
275
+ consolidated: ZarrConsolidatedMetadata,
276
+ namespace: string
277
+ ): string[] {
278
+ const prefix = `${namespace}/`;
279
+ const paths = new Set<string>();
280
+ for (const [metadataPath, value] of Object.entries(consolidated.metadata)) {
281
+ const path =
282
+ consolidated.format === 'v2'
283
+ ? metadataPath.endsWith('/.zgroup')
284
+ ? metadataPath.slice(0, -8)
285
+ : ''
286
+ : value &&
287
+ typeof value === 'object' &&
288
+ (value as {node_type?: unknown}).node_type === 'group'
289
+ ? metadataPath
290
+ : '';
291
+ if (!path.startsWith(prefix) || path.slice(prefix.length).includes('/')) continue;
292
+ paths.add(path);
293
+ }
294
+ return [...paths].sort();
295
+ }
296
+
297
+ /** Returns normalized group attributes across consolidated Zarr generations. */
298
+ function getGroupAttributes(
299
+ consolidated: ZarrConsolidatedMetadata,
300
+ path: string
301
+ ): Record<string, unknown> {
302
+ if (consolidated.format === 'v2') {
303
+ return {...(getObject(consolidated.metadata[`${path}/.zattrs`]) || {})};
304
+ }
305
+ const node = getObject(consolidated.metadata[path]);
306
+ return {...(getObject(node?.attributes) || {})};
307
+ }
308
+
309
+ /** Returns the external or Zarr URL associated with an element format. */
310
+ function getElementUrl(rootUrl: string, path: string, format: SpatialDataElementFormat): string {
311
+ const baseUrl = `${rootUrl.replace(/\/+$/, '')}/${path}`;
312
+ if (format === 'parquet-dataset') return `${baseUrl}/points.parquet`;
313
+ if (format === 'geoparquet') return `${baseUrl}/shapes.parquet`;
314
+ return baseUrl;
315
+ }
316
+
317
+ /** Extracts axis names from SpatialData or nested OME metadata. */
318
+ function getAxes(attributes: Record<string, unknown>): readonly string[] | undefined {
319
+ const directAxes = normalizeAxes(attributes.axes);
320
+ if (directAxes) return Object.freeze(directAxes);
321
+ const ome = getObject(attributes.ome);
322
+ const multiscales = Array.isArray(ome?.multiscales) ? ome.multiscales : [];
323
+ const multiscale = getObject(multiscales[0]);
324
+ const axes = normalizeAxes(multiscale?.axes);
325
+ return axes ? Object.freeze(axes) : undefined;
326
+ }
327
+
328
+ /** Normalizes string and object axis declarations to names. */
329
+ function normalizeAxes(value: unknown): string[] | undefined {
330
+ if (!Array.isArray(value)) return undefined;
331
+ const axes = value
332
+ .map(axis => (typeof axis === 'string' ? axis : getString(getObject(axis)?.name)))
333
+ .filter((axis): axis is string => Boolean(axis));
334
+ return axes.length ? axes : undefined;
335
+ }
336
+
337
+ /** Extracts coordinate transformations from SpatialData or nested OME metadata. */
338
+ function getCoordinateTransformations(
339
+ attributes: Record<string, unknown>
340
+ ): readonly unknown[] | undefined {
341
+ if (Array.isArray(attributes.coordinateTransformations)) {
342
+ return Object.freeze([...attributes.coordinateTransformations]);
343
+ }
344
+ const ome = getObject(attributes.ome);
345
+ const multiscales = Array.isArray(ome?.multiscales) ? ome.multiscales : [];
346
+ const multiscale = getObject(multiscales[0]);
347
+ return Array.isArray(multiscale?.coordinateTransformations)
348
+ ? Object.freeze([...multiscale.coordinateTransformations])
349
+ : undefined;
350
+ }
351
+
352
+ /** Filters and freezes one SpatialData element family. */
353
+ function getElementsByKind(
354
+ elements: readonly SpatialDataElementMetadata[],
355
+ kind: SpatialDataElementKind
356
+ ): readonly SpatialDataElementMetadata[] {
357
+ return Object.freeze(elements.filter(element => element.kind === kind));
358
+ }
359
+
360
+ /** Narrows an unknown metadata value to an object. */
361
+ function getObject(value: unknown): Record<string, unknown> | undefined {
362
+ return value && typeof value === 'object' && !Array.isArray(value)
363
+ ? (value as Record<string, unknown>)
364
+ : undefined;
365
+ }
366
+
367
+ /** Narrows an unknown metadata value to a string. */
368
+ function getString(value: unknown): string | undefined {
369
+ return typeof value === 'string' && value ? value : undefined;
370
+ }
@@ -0,0 +1,129 @@
1
+ // loaders.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // Copyright (c) vis.gl contributors
4
+
5
+ /* eslint-disable */
6
+ import {DTYPE_LOOKUP} from './lib/zarr-pixel-source';
7
+ import type {ZarrArray} from 'zarr';
8
+
9
+ /** Storage accepted by Zarr's public array interface. */
10
+ export type ZarrStore = ZarrArray['store'];
11
+
12
+ /** Raw chunk returned by Zarr's public chunk-reading API. */
13
+ export type ZarrRawArray = Awaited<ReturnType<ZarrArray['getRawChunk']>>;
14
+ export type SupportedDtype = (typeof DTYPE_LOOKUP)[keyof typeof DTYPE_LOOKUP];
15
+ export type SupportedTypedArray = InstanceType<(typeof globalThis)[`${SupportedDtype}Array`]>;
16
+
17
+ /** Named OME axis matching one Zarr array dimension. */
18
+ interface MultiscaleAxis {
19
+ /** Axis name used for dimension selection. */
20
+ name?: string;
21
+ /** Semantic axis type such as `space`, `time`, or `channel`. */
22
+ type?: string;
23
+ }
24
+
25
+ /** One resolution level in an OME multiscale pyramid. */
26
+ interface MultiscaleDataset {
27
+ /** Array path relative to the image group. */
28
+ path: string;
29
+ /** Transformations from array coordinates into the multiscale coordinate system. */
30
+ coordinateTransformations?: unknown[];
31
+ }
32
+
33
+ interface Multiscale {
34
+ /** Ordered OME axis descriptors matching the Zarr array dimensions. */
35
+ axes?: Array<string | MultiscaleAxis>;
36
+ /** Resolution levels and their transforms into the multiscale coordinate system. */
37
+ datasets: MultiscaleDataset[];
38
+ /** Transformations applied uniformly after each resolution-level transformation. */
39
+ coordinateTransformations?: unknown[];
40
+ version?: string;
41
+ }
42
+
43
+ interface Channel {
44
+ active: boolean;
45
+ color: string;
46
+ label: string;
47
+ window: {
48
+ min?: number;
49
+ max?: number;
50
+ start: number;
51
+ end: number;
52
+ };
53
+ }
54
+
55
+ interface Omero {
56
+ channels: Channel[];
57
+ rdefs: {
58
+ /** Default time index used for display. */
59
+ defaultT?: number;
60
+ /** Default z index used for display. */
61
+ defaultZ?: number;
62
+ model: string;
63
+ };
64
+ name?: string;
65
+ }
66
+
67
+ interface MultiscaleAttrs {
68
+ multiscales: Multiscale[];
69
+ /** Non-standard legacy location retained for compatibility. */
70
+ coordinateTransformations?: unknown[];
71
+ }
72
+
73
+ interface OmeAttrs extends MultiscaleAttrs {
74
+ omero: Omero;
75
+ }
76
+
77
+ interface OMEV05Attrs {
78
+ /** OME-Zarr v0.5 metadata envelope. */
79
+ ome?: Partial<OmeAttrs>;
80
+ }
81
+
82
+ export type RootAttrs = MultiscaleAttrs | OmeAttrs | OMEV05Attrs;
83
+
84
+ export type {Channel, Multiscale, Omero};
85
+
86
+ export interface PixelData {
87
+ data: SupportedTypedArray;
88
+ width: number;
89
+ height: number;
90
+ }
91
+
92
+ export type PixelSourceSelection<S extends string[]> = {
93
+ [K in S[number]]: number;
94
+ };
95
+
96
+ export interface RasterSelection<S extends string[]> {
97
+ selection: PixelSourceSelection<S>;
98
+ signal?: AbortSignal;
99
+ }
100
+
101
+ export interface TileSelection<S extends string[]> {
102
+ x: number;
103
+ y: number;
104
+ selection: PixelSourceSelection<S>;
105
+ signal?: AbortSignal;
106
+ }
107
+
108
+ interface PhysicalSize {
109
+ size: number;
110
+ unit: string;
111
+ }
112
+
113
+ export interface PixelSourceMeta {
114
+ physicalSizes?: Record<string, PhysicalSize>;
115
+ photometricInterpretation?: number;
116
+ }
117
+
118
+ export type Labels<S extends string[]> = [...S, 'y', 'x'] | [...S, 'y', 'x', '_c'];
119
+
120
+ export interface PixelSource<S extends string[]> {
121
+ getRaster(sel: RasterSelection<S>): Promise<PixelData>;
122
+ getTile(sel: TileSelection<S>): Promise<PixelData>;
123
+ onTileError(err: Error): void;
124
+ shape: number[];
125
+ dtype: SupportedDtype;
126
+ labels: Labels<S>;
127
+ tileSize: number;
128
+ meta?: PixelSourceMeta;
129
+ }
@@ -0,0 +1,5 @@
1
+ // loaders.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // Copyright (c) vis.gl contributors
4
+
5
+ export * from './index';