@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,54 @@
1
+ // loaders.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // Copyright (c) vis.gl contributors
4
+
5
+ import type {Loader, LoaderWithParser, LoaderOptions} from '@loaders.gl/core/loader-utils';
6
+ import type {NetCDFHeader} from './netcdfjs/netcdf-types';
7
+ import {NetCDFReader} from './netcdfjs/netcdf-reader';
8
+ import {NetCDFWorkerLoader as NetCDFWorkerLoaderMetadata} from './netcdf-loader';
9
+ import {NetCDFLoader as NetCDFLoaderMetadata} from './netcdf-loader';
10
+
11
+ const {preload: _NetCDFWorkerLoaderPreload, ...NetCDFWorkerLoaderMetadataWithoutPreload} =
12
+ NetCDFWorkerLoaderMetadata;
13
+ const {preload: _NetCDFLoaderPreload, ...NetCDFLoaderMetadataWithoutPreload} = NetCDFLoaderMetadata;
14
+
15
+ export type NetCDF = {
16
+ loaderData: NetCDFHeader;
17
+ data: {[variableName: string]: any[][]};
18
+ };
19
+
20
+ export type NetCDFLoaderOptions = LoaderOptions & {
21
+ netcdf?: {
22
+ loadData?: boolean;
23
+ loadVariables?: boolean;
24
+ };
25
+ };
26
+
27
+ /**
28
+ * Worker loader for NETCDF
29
+ */
30
+ export const NetCDFWorkerLoaderWithParser = {
31
+ ...NetCDFWorkerLoaderMetadataWithoutPreload
32
+ } as const satisfies Loader<NetCDF, never, NetCDFLoaderOptions>;
33
+
34
+ /**
35
+ * Loader for the NetCDF format
36
+ */
37
+ export const NetCDFLoaderWithParser = {
38
+ ...NetCDFLoaderMetadataWithoutPreload,
39
+ parse: async (arrayBuffer, options) => parseNetCDF(arrayBuffer, options)
40
+ } as const satisfies LoaderWithParser<NetCDF, never, NetCDFLoaderOptions>;
41
+
42
+ function parseNetCDF(arrayBuffer: ArrayBuffer, options?: NetCDFLoaderOptions): NetCDF {
43
+ const reader = new NetCDFReader(arrayBuffer);
44
+ const variables: {[variableName: string]: any[][]} = {};
45
+ if (options?.netcdf?.loadData) {
46
+ for (const variable of reader.variables) {
47
+ variables[variable.name] = reader.getDataVariable(variable);
48
+ }
49
+ }
50
+ return {
51
+ loaderData: reader.header,
52
+ data: variables
53
+ };
54
+ }
@@ -0,0 +1,62 @@
1
+ // loaders.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // Copyright (c) vis.gl contributors
4
+
5
+ import type {Loader, LoaderOptions} from '@loaders.gl/core/loader-utils';
6
+ import type {NetCDFHeader} from './netcdfjs/netcdf-types';
7
+
8
+ import {NetCDFFormat} from './netcdf-format';
9
+ // __VERSION__ is injected by babel-plugin-version-inline
10
+ // @ts-ignore TS2304: Cannot find name '__VERSION__'.
11
+ const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
12
+
13
+ export type NetCDF = {
14
+ loaderData: NetCDFHeader;
15
+ data: {[variableName: string]: any[][]};
16
+ };
17
+
18
+ export type NetCDFLoaderOptions = LoaderOptions & {
19
+ netcdf?: {
20
+ loadData?: boolean;
21
+ loadVariables?: boolean;
22
+ };
23
+ };
24
+
25
+ /** Preloads the parser-bearing NetCDF loader implementation. */
26
+ async function preload() {
27
+ const {NetCDFLoaderWithParser} = await import(
28
+ '@loaders.gl/scientific/netcdf/netcdf-loader-with-parser'
29
+ );
30
+ return NetCDFLoaderWithParser;
31
+ }
32
+
33
+ /**
34
+ * Metadata-only loader for NETCDF.
35
+ */
36
+ export const NetCDFLoader = {
37
+ ...NetCDFFormat,
38
+ dataType: null as unknown as NetCDF,
39
+ batchType: null as never,
40
+
41
+ name: 'NetCDF',
42
+ id: 'mvt',
43
+ module: 'scientific',
44
+ version: VERSION,
45
+ extensions: ['cdf', 'nc'],
46
+ mimeTypes: [
47
+ 'application/netcdf',
48
+ 'application/x-netcdf'
49
+ // 'application/octet-stream'
50
+ ],
51
+ category: 'image',
52
+ binary: true,
53
+ options: {
54
+ netcdf: {
55
+ loadVariables: false
56
+ }
57
+ },
58
+ preload
59
+ } as const satisfies Loader<NetCDF, never, NetCDFLoaderOptions>;
60
+
61
+ /** @deprecated Use NetCDFLoader. */
62
+ export const NetCDFWorkerLoader = NetCDFLoader;
@@ -0,0 +1,45 @@
1
+ // loaders.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // Copyright (c) vis.gl contributors
4
+
5
+ import type {CoreAPI, SourceLoader} from '@loaders.gl/core/loader-utils';
6
+ import {NetCDFFormat} from './netcdf-format';
7
+ import type {NetCDFSource, NetCDFSourceOptions} from './netcdf-source-loader';
8
+
9
+ // __VERSION__ is injected by babel-plugin-version-inline
10
+ // @ts-ignore TS2304: Cannot find name '__VERSION__'.
11
+ const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
12
+
13
+ /** Loads the parser-bearing NetCDF source through its explicit implementation subpath. */
14
+ async function preloadNetCDFSourceLoader(): Promise<SourceLoader<NetCDFSource>> {
15
+ const {NetCDFSourceLoaderWithParser} = await import(
16
+ '@loaders.gl/scientific/netcdf/netcdf-source-loader'
17
+ );
18
+ return NetCDFSourceLoaderWithParser;
19
+ }
20
+
21
+ /** Metadata-only NetCDF source loader kept lightweight for package-root imports. */
22
+ export const NetCDFSourceLoader = {
23
+ ...NetCDFFormat,
24
+ module: 'scientific',
25
+ dataType: null as unknown as NetCDFSource,
26
+ batchType: null as never,
27
+ name: 'NetCDFSourceLoader',
28
+ version: VERSION,
29
+ type: 'netcdf-source',
30
+ fromUrl: true,
31
+ fromBlob: true,
32
+ options: {},
33
+ defaultOptions: {},
34
+ testURL: (url: string): boolean => /\.(?:cdf|nc)(?:$|[?#])/i.test(url),
35
+ preload: preloadNetCDFSourceLoader,
36
+ createDataSource(
37
+ _data: string | Blob,
38
+ _options: NetCDFSourceOptions,
39
+ _coreApi?: CoreAPI
40
+ ): NetCDFSource {
41
+ throw new Error(
42
+ 'NetCDFSourceLoader requires async load() or an explicit @loaders.gl/scientific/netcdf/netcdf-source-loader import'
43
+ );
44
+ }
45
+ } as const satisfies SourceLoader<NetCDFSource>;
@@ -0,0 +1,526 @@
1
+ // loaders.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // Copyright (c) vis.gl contributors
4
+
5
+ import type {Field, Schema, DataType} from '@loaders.gl/core/schema';
6
+ import type {
7
+ DataSourceOptions,
8
+ RasterChannelDataType,
9
+ RasterData,
10
+ RasterQueryCapabilities,
11
+ RasterQueryOptions,
12
+ ScanQueryMetadata,
13
+ ScanQueryMetadataOptions,
14
+ SourceLoader
15
+ } from '@loaders.gl/core/loader-utils';
16
+ import {
17
+ createScanQueryMetadata,
18
+ DataSource,
19
+ validateRasterQueryOptions
20
+ } from '@loaders.gl/core/loader-utils';
21
+ import {NetCDFFormat} from './netcdf-format';
22
+ import {NetCDFReader} from './netcdfjs/netcdf-reader';
23
+ import type {NetCDFHeader, NetCDFVariable} from './netcdfjs/netcdf-types';
24
+
25
+ // __VERSION__ is injected by babel-plugin-version-inline
26
+ // @ts-ignore TS2304: Cannot find name '__VERSION__'.
27
+ const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
28
+
29
+ /** Options for a NetCDF source. */
30
+ export type NetCDFSourceOptions = DataSourceOptions;
31
+
32
+ /** Common NetCDF variable and dimension-slice request. */
33
+ export type NetCDFRasterQueryOptions = RasterQueryOptions &
34
+ Readonly<{
35
+ /** Cancels the file request and cooperative slice materialization. */
36
+ signal?: AbortSignal;
37
+ }>;
38
+
39
+ /**
40
+ * NetCDF classic source with header-only discovery and typed variable/slice execution.
41
+ */
42
+ export class NetCDFSource extends DataSource<string | Blob, NetCDFSourceOptions> {
43
+ private static readonly HEADER_RANGE_SIZE = 64 * 1024;
44
+ private static readonly MAX_HEADER_RANGE_SIZE = 4 * 1024 * 1024;
45
+ private headerPromise: Promise<{header: NetCDFHeader; byteLength: number}> | null = null;
46
+
47
+ /** Capabilities of the NetCDF variable and dimension-slice executor. */
48
+ readonly rasterQueryCapabilities: RasterQueryCapabilities = Object.freeze({
49
+ bounds: 'unsupported',
50
+ level: 'unsupported',
51
+ variables: 'pushdown',
52
+ slices: 'residual',
53
+ streaming: false,
54
+ cancellation: true
55
+ });
56
+
57
+ /** Creates a source over a NetCDF URL or Blob. */
58
+ constructor(data: string | Blob, options: NetCDFSourceOptions = {}) {
59
+ super(data, options);
60
+ }
61
+
62
+ /** Discovers variables and dimensions without decoding data arrays. */
63
+ async getQueryMetadata(options: ScanQueryMetadataOptions = {}): Promise<ScanQueryMetadata> {
64
+ throwIfAborted(options.signal);
65
+ const {header, byteLength} = await this.getHeader(options.signal);
66
+ throwIfAborted(options.signal);
67
+ const fields = header.variables.map(variable => createVariableField(variable, header));
68
+ const schema: Schema = {fields, metadata: createDimensionMetadata(header)};
69
+ return createScanQueryMetadata({
70
+ sourceType: 'netcdf',
71
+ queryType: 'raster',
72
+ execution: {status: 'supported', method: 'getRaster'},
73
+ name: typeof this.data === 'string' ? this.data.split('/').pop() : undefined,
74
+ schema,
75
+ capabilities: {
76
+ bounds: 'unsupported',
77
+ levelOfDetail: 'unsupported',
78
+ raster: this.rasterQueryCapabilities
79
+ },
80
+ statistics: {
81
+ byteLength,
82
+ rowCount: header.recordDimension.length || undefined
83
+ }
84
+ });
85
+ }
86
+
87
+ /**
88
+ * Reads selected numeric variables and applies named dimension slices.
89
+ *
90
+ * Multiple variables must retain the same shape and numeric type so they can be returned as
91
+ * ordinary raster bands. Leading dimensions are folded into height and the final dimension is
92
+ * exposed as width; the original dimension names and shape remain in result metadata.
93
+ */
94
+ async getRaster(options: NetCDFRasterQueryOptions = {}): Promise<RasterData> {
95
+ validateRasterQueryOptions(options);
96
+ validateNetCDFUnsupportedRasterOptions(options);
97
+ throwIfAborted(options.signal);
98
+ const reader = await this.loadReader(options.signal);
99
+ throwIfAborted(options.signal);
100
+ validateNetCDFSliceNames(reader.header, options.slices);
101
+ const variables = selectNetCDFVariables(reader.header, options.variables);
102
+ const results = variables.map(variable => {
103
+ throwIfAborted(options.signal);
104
+ const dimensionNames = variable.dimensions.map(
105
+ dimensionId => reader.header.dimensions[dimensionId]?.name || `dimension_${dimensionId}`
106
+ );
107
+ const dimensionSizes = variable.dimensions.map(dimensionId =>
108
+ getDimensionSize(reader.header, dimensionId)
109
+ );
110
+ const values = flattenNetCDFValues(reader.getDataVariable(variable));
111
+ const selection = selectNetCDFValues(
112
+ values,
113
+ dimensionNames,
114
+ dimensionSizes,
115
+ options.slices || {},
116
+ options.signal
117
+ );
118
+ const dtype = getNetCDFRasterDataType(variable.type);
119
+ return {
120
+ variable,
121
+ dimensionNames: selection.dimensionNames,
122
+ shape: selection.shape,
123
+ data: createNetCDFTypedArray(selection.values, dtype),
124
+ dtype
125
+ };
126
+ });
127
+ const reference = results[0];
128
+ for (const result of results.slice(1)) {
129
+ if (result.dtype !== reference.dtype || !arraysEqual(result.shape, reference.shape)) {
130
+ throw new Error(
131
+ 'NetCDF raster variables must retain the same shape and numeric type after slicing.'
132
+ );
133
+ }
134
+ }
135
+ const width = reference.shape.at(-1) ?? 1;
136
+ const height =
137
+ reference.shape.length < 2
138
+ ? 1
139
+ : reference.shape.slice(0, -1).reduce((product, size) => product * size, 1);
140
+ const noData = getNetCDFNoDataValue(reference.variable);
141
+
142
+ return {
143
+ data: results.length === 1 ? reference.data : results.map(result => result.data),
144
+ width,
145
+ height,
146
+ bandCount: results.length,
147
+ dtype: reference.dtype,
148
+ interleaved: false,
149
+ noData,
150
+ metadata: {
151
+ variables: results.map(result => result.variable.name),
152
+ dimensions: reference.dimensionNames,
153
+ shape: reference.shape,
154
+ slices: {...options.slices}
155
+ }
156
+ };
157
+ }
158
+
159
+ /** Loads a complete NetCDF reader for selected-variable execution. */
160
+ private async loadReader(signal?: AbortSignal): Promise<NetCDFReader> {
161
+ let arrayBuffer: ArrayBuffer;
162
+ if (typeof this.data === 'string') {
163
+ const response = await this.fetch(this.url, {signal});
164
+ if (!response.ok) throw new Error(`NetCDF request failed with status ${response.status}.`);
165
+ arrayBuffer = await response.arrayBuffer();
166
+ } else {
167
+ arrayBuffer = await this.data.arrayBuffer();
168
+ }
169
+ throwIfAborted(signal);
170
+ return new NetCDFReader(arrayBuffer);
171
+ }
172
+
173
+ /** Reads and caches the NetCDF header, preserving abort behavior for each caller. */
174
+ private async getHeader(
175
+ signal?: AbortSignal
176
+ ): Promise<{header: NetCDFHeader; byteLength: number}> {
177
+ throwIfAborted(signal);
178
+ if (!this.headerPromise) {
179
+ this.headerPromise = this.loadHeader().catch(error => {
180
+ this.headerPromise = null;
181
+ throw error;
182
+ });
183
+ }
184
+ const result = await this.headerPromise;
185
+ throwIfAborted(signal);
186
+ return result;
187
+ }
188
+
189
+ /** Loads enough leading bytes to parse a remote header, growing ranges when required. */
190
+ private async loadHeader(): Promise<{header: NetCDFHeader; byteLength: number}> {
191
+ if (typeof this.data !== 'string') {
192
+ const arrayBuffer = await this.data.arrayBuffer();
193
+ return {header: new NetCDFReader(arrayBuffer).header, byteLength: arrayBuffer.byteLength};
194
+ }
195
+
196
+ let rangeSize = NetCDFSource.HEADER_RANGE_SIZE;
197
+ let response: Response | null = null;
198
+ let arrayBuffer: ArrayBuffer | null = null;
199
+ let lastError: unknown;
200
+ while (rangeSize <= NetCDFSource.MAX_HEADER_RANGE_SIZE) {
201
+ response = await this.fetch(this.url, {
202
+ headers: {Range: `bytes=0-${rangeSize - 1}`}
203
+ });
204
+ if (!response.ok) throw new Error(`NetCDF request failed with status ${response.status}.`);
205
+ arrayBuffer = await response.arrayBuffer();
206
+ const byteLength = getResponseByteLength(response, arrayBuffer.byteLength);
207
+ try {
208
+ return {header: new NetCDFReader(arrayBuffer).header, byteLength};
209
+ } catch (error) {
210
+ lastError = error;
211
+ if (response.status !== 206 || arrayBuffer.byteLength < rangeSize) throw error;
212
+ rangeSize *= 2;
213
+ }
214
+ }
215
+ throw lastError || new Error('NetCDF header exceeds the maximum metadata range.');
216
+ }
217
+ }
218
+
219
+ /** Parser-bearing source loader for NetCDF metadata scans. */
220
+ export const NetCDFSourceLoaderWithParser = {
221
+ dataType: null as unknown as NetCDFSource,
222
+ batchType: null as never,
223
+ ...NetCDFFormat,
224
+ module: 'scientific',
225
+ name: 'NetCDFSourceLoader',
226
+ version: VERSION,
227
+ type: 'netcdf-source',
228
+ fromUrl: true,
229
+ fromBlob: true,
230
+ options: {},
231
+ defaultOptions: {},
232
+ testURL: (url: string): boolean => /\.(?:cdf|nc)(?:$|[?#])/i.test(url),
233
+ createDataSource: (data: string | Blob, options: NetCDFSourceOptions): NetCDFSource =>
234
+ new NetCDFSource(data, options)
235
+ } as const satisfies SourceLoader<NetCDFSource>;
236
+
237
+ /** Maps NetCDF primitive names to portable schema data types. */
238
+ function getNetCDFDataType(type: string): DataType {
239
+ switch (type.toLowerCase()) {
240
+ case 'byte':
241
+ return 'int8';
242
+ case 'ubyte':
243
+ return 'uint8';
244
+ case 'short':
245
+ return 'int16';
246
+ case 'ushort':
247
+ return 'uint16';
248
+ case 'int':
249
+ return 'int32';
250
+ case 'uint':
251
+ return 'uint32';
252
+ case 'int64':
253
+ return 'int64';
254
+ case 'uint64':
255
+ return 'uint64';
256
+ case 'float':
257
+ return 'float32';
258
+ case 'double':
259
+ return 'float64';
260
+ case 'char':
261
+ case 'string':
262
+ return 'utf8';
263
+ default:
264
+ return 'binary';
265
+ }
266
+ }
267
+
268
+ type NetCDFTypedArray =
269
+ | Int8Array
270
+ | Uint8Array
271
+ | Int16Array
272
+ | Uint16Array
273
+ | Int32Array
274
+ | Uint32Array
275
+ | Float32Array
276
+ | Float64Array;
277
+
278
+ type NetCDFValueSelection = {
279
+ values: number[];
280
+ dimensionNames: string[];
281
+ shape: number[];
282
+ };
283
+
284
+ /** Rejects raster operations that have no NetCDF classic interpretation. */
285
+ function validateNetCDFUnsupportedRasterOptions(options: NetCDFRasterQueryOptions): void {
286
+ if (options.bounds) throw new Error('NetCDF raster bounds are not supported.');
287
+ if (options.level !== undefined) throw new Error('NetCDF raster levels are not supported.');
288
+ if (options.width !== undefined || options.height !== undefined) {
289
+ throw new Error('NetCDF raster resampling is not supported.');
290
+ }
291
+ if (options.channels?.length) {
292
+ throw new Error('NetCDF uses named variables instead of numeric channels.');
293
+ }
294
+ }
295
+
296
+ /** Selects and validates query-visible numeric NetCDF variables. */
297
+ function selectNetCDFVariables(
298
+ header: NetCDFHeader,
299
+ requestedVariableNames?: readonly string[]
300
+ ): NetCDFVariable[] {
301
+ const defaultVariable = header.variables.find(
302
+ variable => variable.dimensions.length > 0 && isNetCDFRasterDataType(variable.type)
303
+ );
304
+ const variableNames = requestedVariableNames?.length
305
+ ? [...requestedVariableNames]
306
+ : defaultVariable
307
+ ? [defaultVariable.name]
308
+ : [];
309
+ if (variableNames.length === 0) {
310
+ throw new Error('NetCDF contains no numeric variables that can be read as raster data.');
311
+ }
312
+ if (new Set(variableNames).size !== variableNames.length) {
313
+ throw new Error('NetCDF raster variables must not contain duplicates.');
314
+ }
315
+ return variableNames.map(variableName => {
316
+ const variable = header.variables.find(candidate => candidate.name === variableName);
317
+ if (!variable) throw new Error(`NetCDF variable not found: ${variableName}`);
318
+ getNetCDFRasterDataType(variable.type);
319
+ return variable;
320
+ });
321
+ }
322
+
323
+ /** Validates slice names against file-level dimensions. */
324
+ function validateNetCDFSliceNames(
325
+ header: NetCDFHeader,
326
+ slices: NetCDFRasterQueryOptions['slices']
327
+ ): void {
328
+ const dimensionNames = new Set(header.dimensions.map(dimension => dimension.name));
329
+ for (const dimensionName of Object.keys(slices || {})) {
330
+ if (!dimensionNames.has(dimensionName)) {
331
+ throw new Error(`NetCDF dimension not found: ${dimensionName}`);
332
+ }
333
+ }
334
+ }
335
+
336
+ /** Applies named dimension indices and half-open ranges to row-major variable values. */
337
+ function selectNetCDFValues(
338
+ values: readonly unknown[],
339
+ dimensionNames: readonly string[],
340
+ dimensionSizes: readonly number[],
341
+ slices: NonNullable<NetCDFRasterQueryOptions['slices']>,
342
+ signal?: AbortSignal
343
+ ): NetCDFValueSelection {
344
+ const selectors = dimensionNames.map((dimensionName, dimensionIndex) => {
345
+ const size = dimensionSizes[dimensionIndex];
346
+ const slice = slices[dimensionName];
347
+ if (slice === undefined) return {start: 0, stop: size, remove: false};
348
+ if (typeof slice !== 'number') {
349
+ const [start, stop] = slice;
350
+ if (
351
+ !Number.isSafeInteger(start) ||
352
+ !Number.isSafeInteger(stop) ||
353
+ start < 0 ||
354
+ stop < start ||
355
+ stop > size
356
+ ) {
357
+ throw new Error(
358
+ `NetCDF slice ${dimensionName} must be a valid half-open range within 0..${size}.`
359
+ );
360
+ }
361
+ return {start, stop, remove: false};
362
+ }
363
+ if (!Number.isSafeInteger(slice) || slice < 0 || slice >= size) {
364
+ throw new Error(`NetCDF slice ${dimensionName} must be an index within 0..${size - 1}.`);
365
+ }
366
+ return {start: slice, stop: slice + 1, remove: true};
367
+ });
368
+ const strides = dimensionSizes.map((_, dimensionIndex) =>
369
+ dimensionSizes
370
+ .slice(dimensionIndex + 1)
371
+ .reduce((product, dimensionSize) => product * dimensionSize, 1)
372
+ );
373
+ const selectedValues: number[] = [];
374
+
375
+ const visitDimension = (dimensionIndex: number, flatOffset: number): void => {
376
+ throwIfAborted(signal);
377
+ if (dimensionIndex === selectors.length) {
378
+ const value = values[flatOffset];
379
+ if (typeof value !== 'number') {
380
+ throw new Error('NetCDF raster variables must contain numeric values.');
381
+ }
382
+ selectedValues.push(value);
383
+ return;
384
+ }
385
+ const selector = selectors[dimensionIndex];
386
+ for (let index = selector.start; index < selector.stop; index++) {
387
+ visitDimension(dimensionIndex + 1, flatOffset + index * strides[dimensionIndex]);
388
+ }
389
+ };
390
+ visitDimension(0, 0);
391
+
392
+ return {
393
+ values: selectedValues,
394
+ dimensionNames: dimensionNames.filter((_, index) => !selectors[index].remove),
395
+ shape: selectors
396
+ .map(selector => selector.stop - selector.start)
397
+ .filter((_, index) => !selectors[index].remove)
398
+ };
399
+ }
400
+
401
+ /** Flattens the nested arrays emitted by NetCDFReader into file-order scalar values. */
402
+ function flattenNetCDFValues(values: unknown): unknown[] {
403
+ if (Array.isArray(values)) return values.flatMap(flattenNetCDFValues);
404
+ if (ArrayBuffer.isView(values)) {
405
+ return Array.from(values as unknown as ArrayLike<unknown>);
406
+ }
407
+ return [values];
408
+ }
409
+
410
+ /** Returns whether a NetCDF primitive can be represented by RasterData. */
411
+ function isNetCDFRasterDataType(type: string): boolean {
412
+ try {
413
+ getNetCDFRasterDataType(type);
414
+ return true;
415
+ } catch {
416
+ return false;
417
+ }
418
+ }
419
+
420
+ /** Maps a NetCDF numeric primitive to the common raster channel type. */
421
+ function getNetCDFRasterDataType(type: string): RasterChannelDataType {
422
+ switch (type.toLowerCase()) {
423
+ case 'byte':
424
+ return 'int8';
425
+ case 'ubyte':
426
+ return 'uint8';
427
+ case 'short':
428
+ return 'int16';
429
+ case 'ushort':
430
+ return 'uint16';
431
+ case 'int':
432
+ return 'int32';
433
+ case 'uint':
434
+ return 'uint32';
435
+ case 'float':
436
+ return 'float32';
437
+ case 'double':
438
+ return 'float64';
439
+ default:
440
+ throw new Error(`NetCDF variable type is not supported as raster data: ${type}`);
441
+ }
442
+ }
443
+
444
+ /** Materializes numeric values in the selected NetCDF primitive type. */
445
+ function createNetCDFTypedArray(
446
+ values: readonly number[],
447
+ dtype: RasterChannelDataType
448
+ ): NetCDFTypedArray {
449
+ switch (dtype) {
450
+ case 'int8':
451
+ return Int8Array.from(values);
452
+ case 'uint8':
453
+ return Uint8Array.from(values);
454
+ case 'int16':
455
+ return Int16Array.from(values);
456
+ case 'uint16':
457
+ return Uint16Array.from(values);
458
+ case 'int32':
459
+ return Int32Array.from(values);
460
+ case 'uint32':
461
+ return Uint32Array.from(values);
462
+ case 'float32':
463
+ return Float32Array.from(values);
464
+ case 'float64':
465
+ return Float64Array.from(values);
466
+ }
467
+ }
468
+
469
+ /** Reads the conventional fill or missing-value attribute when it is numeric. */
470
+ function getNetCDFNoDataValue(variable: NetCDFVariable): number | null {
471
+ const attribute = variable.attributes.find(
472
+ candidate => candidate.name === '_FillValue' || candidate.name === 'missing_value'
473
+ );
474
+ const value = Number(attribute?.value);
475
+ return attribute && Number.isFinite(value) ? value : null;
476
+ }
477
+
478
+ /** Compares small raster shape arrays. */
479
+ function arraysEqual(left: readonly number[], right: readonly number[]): boolean {
480
+ return left.length === right.length && left.every((value, index) => value === right[index]);
481
+ }
482
+
483
+ /** Converts a NetCDF variable into a query-visible field. */
484
+ function createVariableField(variable: NetCDFVariable, header: NetCDFHeader): Field {
485
+ const dimensions = variable.dimensions
486
+ .map(dimensionId => header.dimensions[dimensionId])
487
+ .filter(Boolean)
488
+ .map(
489
+ (dimension, index) =>
490
+ `${dimension.name}[${getDimensionSize(header, variable.dimensions[index])}]`
491
+ )
492
+ .join(',');
493
+ const metadata: Record<string, string> = {dimensions};
494
+ for (const attribute of variable.attributes) {
495
+ metadata[attribute.name] = String(attribute.value);
496
+ }
497
+ return {name: variable.name, type: getNetCDFDataType(variable.type), nullable: true, metadata};
498
+ }
499
+
500
+ /** Adds dimensions as schema metadata so consumers can populate slice controls. */
501
+ function createDimensionMetadata(header: NetCDFHeader): Record<string, string> {
502
+ const metadata: Record<string, string> = {};
503
+ for (const [dimensionId, dimension] of header.dimensions.entries()) {
504
+ metadata[`dimension:${dimension.name}`] = String(getDimensionSize(header, dimensionId));
505
+ }
506
+ return metadata;
507
+ }
508
+
509
+ function getDimensionSize(header: NetCDFHeader, dimensionId: number): number {
510
+ const dimension = header.dimensions[dimensionId];
511
+ return dimensionId === header.recordDimension.id
512
+ ? header.recordDimension.length
513
+ : dimension?.size || 0;
514
+ }
515
+
516
+ function getResponseByteLength(response: Response, fallback: number): number {
517
+ const contentRange = response.headers.get('content-range');
518
+ const total = contentRange?.match(/\/([0-9]+)$/)?.[1];
519
+ return Number(total || response.headers.get('content-length') || fallback);
520
+ }
521
+
522
+ function throwIfAborted(signal?: AbortSignal): void {
523
+ if (signal?.aborted) {
524
+ throw new DOMException('The operation was aborted', 'AbortError');
525
+ }
526
+ }