@ortho-earth/voxel 0.4.0 → 0.6.0

package/README.md

@@ -9,8 +9,9 @@ Voxel grids for [`@ortho-earth/globe`](../../packages/globe). The plugin fills t
 - They are **picked** by the unified picking: `handle.pick(x, y)`, `map.on("click", id, …)` and `queryRenderedFeatures({ layers: [id] })`. A hit carries the cell `index`, its `[i, j, k]` `cell`, the cell's `value` (scalar grids, via `handle.pick`) and your `properties`. Picking marches only the pixels under the cursor (scissor), so it stays cheap.
 - **Preparation** runs in a worker (`voxel-reader.ts`): values are quantised to 8 bits (`R8`, or `RGBA8` for `components: 4`), the colormap is baked, the box is placed or the region shell is tessellated; the main thread only forwards the buffers.
 - **Large grids** are split into **bricks**: a grid with an axis beyond 256 cells (the 3D texture size every WebGL2 device guarantees) becomes bricks of 126 cells per axis, one texture each with a 1-cell apron so trilinear sampling and iso gradients run across the seams. Bricks are drawn far to near, a brick whose cells are all below `threshold` (or empty) is skipped, and `clip`, `threshold`, picking (`index` / `cell` of the whole grid) and every style change work across them. `handle.bricks` says how many.
-- **Time**: `times` (ms, ascending) makes `values` a run of frames, one per time. The layer follows `map.clock` by default (the last frame at or before the clock's time; scrub or play the clock and the frame changes without re-uploading), or `time: <ms>` pins one frame. One `range` covers every frame so colours compare across time.
-- Stages 1–4 are done (box and region grids, blocks / volume / iso, clipping, WebGPU and WebGL2, 3D Tiles `EXT_primitive_voxels`); stage 5 has bricks and time, while level of detail and file readers (NetCDF, Zarr) follow. See [PLAN.md](./PLAN.md).
+- **Time**: `times` (ms, ascending) makes `values` a run of frames, one per time. The layer follows `map.clock` by default (the last frame at or before the clock's time; scrub or play the clock and the frame changes without re-uploading), or `time: <ms>` pins one frame. One `range` covers every frame so colours compare across time. Only the frame shown is on the GPU; the others wait in the overlay's memory and go up when the clock reaches them.
+- **GPU budget**: `voxelPlugin({ budget })` (MB, default 512, 128 on touch devices) caps the voxel textures of a map. A grid bigger than half of it also gets coarser levels (1/2, 1/4… cells per axis, averaging the non-empty cells), per brick. When the layers in view would not fit, the farthest ones (by distance over cell size) are drawn from a coarser level, and the textures of layers out of view are let go. `handle.levels` says how many coarser levels were made.
+- Stages 1–4 are done (box and region grids, blocks / volume / iso, clipping, WebGPU and WebGL2, 3D Tiles `EXT_primitive_voxels`); stage 5 has bricks, time, the GPU budget with levels of detail, and NetCDF / Zarr readers. See [PLAN.md](./PLAN.md).
 
 ```js
 import { createGlobe } from "@ortho-earth/globe";
@@ -40,6 +41,15 @@ field.backend;                                             // "webgpu" | "webgl2
 map.on("click", "field", e => console.log(e.features[0].properties.cell));
 ```
 
+## Files: NetCDF and Zarr
+
+`map.addData(url, { kind: "voxel", variable?, frames?, heights? })` reads a grid file in the reader worker and draws it as a `region` grid:
+
+- **NetCDF classic** (CDF-1, CDF-2, CDF-5): a `.nc` URL, or its bytes (`ArrayBuffer` / `Uint8Array`). NetCDF-4 (HDF5) is not read yet; `nccopy -k classic in.nc out.nc` converts it.
+- **Zarr** v2 and v3: a `.zarr` URL (the store's root). Chunks may be uncompressed or gzip / zlib (v2) and `bytes` + `gzip` (v3); blosc, zstd and sharding are not read yet. With consolidated metadata (`.zmetadata`, or `consolidated_metadata` in `zarr.json`) the variable is found by itself; otherwise pass `variable`. Only the chunks of the frames asked for are fetched.
+- The variable is `(time?, z?, y, x)`, with x the last (fastest) dimension. Coordinates follow CF: `degrees_east` / `degrees_north` (or `lon` / `lat`), a vertical coordinate in m / km (`positive: "down"` and depth go below zero) or Pa / hPa (the standard atmosphere, spacing taken as even), and `<unit> since <date>` times, which become `times` for `map.clock`. Descending latitude or height is flipped, cell centres become the region's edges, and `scale_factor`, `add_offset`, `_FillValue`, `missing_value` and `valid_*` are applied (missing cells are empty).
+- `variable` picks the variable (default: the non-coordinate numeric variable with the most dimensions), `frames: [start, end)` reads part of the time dimension, and `heights: [h0, h1]` (m) overrides the vertical extent. `handle.source` holds what was read: `format`, `variable`, `units`, `longName`, `dims`, `attrs`.
+
 ## VoxelData
 
 | field | meaning |
@@ -74,12 +84,12 @@ map.on("click", "field", e => console.log(e.features[0].properties.cell));
 
 ## Handle
 
-`id`, `kind`, `shape`, `dims`, `n` (cells), `bricks` (0 = one texture), `times` (null without frames), `frame` (the frame shown), `anchor`, `range`, `backend` (`"webgpu"` | `"webgl2"`, null until the overlay has chosen), `reader` (`"worker"` | `"main"`), `error` (the renderer refused the layer, e.g. a grid beyond the 3D texture limit), `ready`, `setData(data)`, `setProps(opts)` (style-only changes do not re-upload the grid), `setVisible(on)`, `pick(x, y, r?)` (the value of the frame shown), `remove()`.
+`id`, `kind`, `shape`, `dims`, `n` (cells), `bricks` (0 = one texture), `levels` (coarser levels for the budget, 0 = none), `source` (what a NetCDF / Zarr file was read as, null for VoxelData), `times` (null without frames), `frame` (the frame shown), `anchor`, `range`, `backend` (`"webgpu"` | `"webgl2"`, null until the overlay has chosen), `reader` (`"worker"` | `"main"`), `error` (the renderer refused the layer, e.g. a grid beyond the 3D texture limit), `ready`, `setData(data)`, `setProps(opts)` (style-only changes do not re-upload the grid), `setVisible(on)`, `pick(x, y, r?)` (the value of the frame shown), `remove()`.
 
 ## Notes
 
 - Scalar values are quantised to 8 bits for the GPU (`range` → 1..255, 0 = empty). The colormap resolves 256 steps and an iso threshold lands on one of them; `handle.pick` reports the original value from the data kept on the main thread.
-- A grid with every axis within 256 cells is one texture; a larger one is split into bricks (above). The bricks are kept in GPU memory as a whole (1 byte per cell, 4 for RGBA): a 1024 × 1024 × 128 grid needs 128 MB, so very large grids need level of detail (still to come) on phones.
+- A grid with every axis within 256 cells is one texture; a larger one is split into bricks (above). The bricks are kept in GPU memory as a whole (1 byte per cell, 4 for RGBA): a 1024 × 1024 × 128 grid needs 128 MB; the GPU budget (above) draws far bricks from coarser levels when that does not fit.
 - Region grids are marched in meters along a straight ray and each sample is converted back to longitude / latitude / height, so cell borders are the true meridians, parallels and height surfaces. Their blocks mode samples the nearest cell every quarter cell instead of a DDA (slightly soft edges). The shell is built on a sphere; under the ellipsoid display (`?ell=1`) a country-sized region can sit a few km off, which stage 3 will tighten. Very large regions (thousands of km) shade with the anchor's east / north / up.
 - All grids of one map share one overlay canvas (the render worker's WebGL contexts are limited); the overlay goes away a moment (`OVERLAY_LINGER_MS`, 250 ms) after the last handle is removed, so `remove()` followed at once by `addData()` (switching scenes) keeps the same overlay instead of tearing it down and racing a new one with the same name.
 - **3D Tiles**: a tileset whose glTF content carries `EXT_primitive_voxels` (with `KHR_implicit_shapes` boxes or `EXT_implicit_ellipsoid_region` regions), or whose `root.content` declares `3DTILES_content_voxels` (the grid fills the tile's bounding volume), becomes one layer per tile through `map.add3DTiles(url, { voxel: { render, colormap, threshold, property, … } })`; `property` picks the attribute (a class property name works too). Cylinders are not drawn yet; without this plugin the globe skips the grids and warns once.

package/dist/grid.d.ts

@@ -16,6 +16,8 @@ export interface PrepareOptions {
     threshold?: number | null;
     /** 楕円体表示の b/a（region の殻を本体と同じ形で作る・既定 1＝球） */
     rAx?: number;
+    /** LoD＝一こまの GPU の大きさ（bytes）がこれを越える格子は粗い段（各軸 1/2・1/4…）も作る（既定＝作らない） */
+    lodBytes?: number | null;
 }
 /** region（経緯度×高さの格子）の描き手向けの欄 */
 export interface GeoGrid {
@@ -110,27 +112,35 @@ export declare function frameAt(times: ArrayLike<number>, ms: number): number;
 export declare const thrOf: (threshold: number | null | undefined, range: [number, number]) => number;
 /** VoxelData → 描き手へ渡す物（worker で。配列は transfer できる物）。値は閾で切らない（閾は描き手が見る＝等値面は場の全体が要る） */
 export declare function prepare(data: unknown, o?: PrepareOptions): Prepared;
+/** 段（ブリック・粗い段）の配列＝transfer する物 */
+export declare const levelBuffers: (l: Level) => ArrayBuffer[];
 export declare const transferables: (p: Prepared | PreparedGrid) => ArrayBuffer[];
 /** 一枚のテクスチャで描く格子の上限（各軸） */
 export declare const BRICK_LIMIT = 256;
 /** ブリックの持ち分（各軸のセル数）＝テクスチャは糊代を足して最大 BRICK + 2 */
 export declare const BRICK = 126;
-export interface Brick {
-    /** テクスチャの 0 番のセルの親の格子での位置 */ off: [number, number, number];
-    /** 描く範囲（テクスチャのセル座標）[x0, y0, z0, x1, y1, z1] */ own: [number, number, number, number, number, number];
+/** 一つの段＝ブリック（s＝1）か、その粗い段（s＝2, 4…＝セル 1 個が元の s 個ぶん）。座標はその段のセル */
+export interface Level {
+    /** 縮めた倍率（1＝元の格子） */ s: number;
+    /** テクスチャの 0 番のセルの、その段の親の格子での位置 */ off: [number, number, number];
+    /** 描く範囲（テクスチャのセル座標・粗い段は端数あり）[x0, y0, z0, x1, y1, z1] */ own: [number, number, number, number, number, number];
     dims: [number, number, number];
-    n: number;
     tex: Uint8Array; /** こまごとのテクスチャ（frames[0]＝tex）・こまが無ければ null */
     frames: Uint8Array[] | null; /** 最大値（R8 の 0〜255・RGBA は α・こまを通して） */
     vmax: number;
-    anchor: [number, number, number];
+    /** box＝親の錨と A×s（セル 1 個ぶん）・region＝部分の region */ anchor: [number, number, number];
     A: Float64Array;
     radius: number;
     geo: GeoGrid | null;
 }
+export interface Brick extends Level {
+    n: number; /** 粗い段（s＝2, 4…）・作らなければ null */
+    lods: Level[] | null;
+}
 export interface PreparedGrid extends Prepared {
     vmax: number; /** 分けた時のブリック（tex は空） */
-    bricks: Brick[] | null;
+    bricks: Brick[] | null; /** 一枚の格子の粗い段（ブリックは各ブリックの lods）・作らなければ null */
+    lods: Level[] | null;
 }
 /** 詰めた値の最大（R8 はそのまま・RGBA は α） */
 export declare function maxOf(tex: Uint8Array, comps: 1 | 4): number;
@@ -145,7 +155,26 @@ export declare function parentIndex(index: number, dims: ArrayLike<number>, off:
     index: number;
     cell: [number, number, number];
 };
-/** prepare の大きな格子版＝上限を越えればブリックに分ける（越えなければ prepare と同じ＋vmax） */
+/** 粗い段の数の上限（1/16 まで） */
+export declare const LOD_MAX = 4;
+/** 段 s の格子の大きさ（各軸 ceil(d/s)） */
+export declare const levelDims: (dims: ArrayLike<number>, s: number) => [number, number, number];
+/** 作る粗い段の数＝一こまが lodBytes を越えれば、一番粗い段が lodBytes/4 以下になるまで（LOD_MAX まで）。越えなければ 0 */
+export declare function levelCount(dims: ArrayLike<number>, comps: number, lodBytes: number | null | undefined): number;
+/** 各軸 1/2 に縮める（R8＝空でない子の平均・RGBA＝α > 0 の子の平均・全部空なら空） */
+export declare function downsample(tex: Uint8Array, dims: [number, number, number], comps: 1 | 4): {
+    tex: Uint8Array;
+    dims: [number, number, number];
+};
+/** 段の並び（s＝2, 4…）＝こまごとに縮める */
+export declare function pyramid(frames: Uint8Array[], dims: [number, number, number], comps: 1 | 4, L: number): Array<{
+    s: number;
+    dims: [number, number, number];
+    frames: Uint8Array[];
+}>;
+/** 段 s の格子（frames）から、元の格子の持ち分 [lo, hi)（元のセル）を糊代 1 セルつきで切り出す。s＝1 はブリックそのもの */
+export declare function makeLevel(frames: Uint8Array[], Dl: [number, number, number], comps: 1 | 4, s: number, lo: ArrayLike<number>, hi: ArrayLike<number>, parent: Placement, pgeo: GeoGrid | null, dims: [number, number, number], rAx?: number): Level;
+/** prepare の大きな格子版＝上限を越えればブリックに分ける（越えなければ prepare と同じ＋vmax）。o.lodBytes を越える格子は粗い段（lods）も作る */
 export declare function prepareGrid(data: unknown, o?: PrepareOptions, brick?: number, limit?: number): PreparedGrid;
 export interface RayHit {
     cell: [number, number, number];

package/dist/grid.js

@@ -304,8 +304,12 @@ export function prepare(data, o = {}) {
     const cmap = buildColormap(o.colormap, o.alphaRamp ?? null);
     return { shape: d.shape, dims: [dims[0], dims[1], dims[2]], comps, n, tex: frames[0], cmap, anchor, A, radius, range, thr, placed, geo, times: d.times ? Array.from(d.times) : null, frames: T > 1 ? frames : null };
 }
-export const transferables = (p) => [p.tex.buffer, p.cmap.buffer, p.A.buffer, ...(p.geo ? [p.geo.shell.buffer] : []), ...(p.frames ?? []).map(f => f.buffer),
-    ...("bricks" in p && p.bricks ? p.bricks.flatMap(b => [b.tex.buffer, b.A.buffer, ...(b.geo ? [b.geo.shell.buffer] : []), ...(b.frames ?? []).map(f => f.buffer)]) : [])].filter((b, i, a) => a.indexOf(b) === i);
+/** 段（ブリック・粗い段）の配列＝transfer する物 */
+export const levelBuffers = (l) => [l.tex.buffer, l.A.buffer, ...(l.geo ? [l.geo.shell.buffer] : []), ...(l.frames ?? []).map(f => f.buffer)];
+const uniq = (a) => a.filter((b, i) => a.indexOf(b) === i);
+export const transferables = (p) => uniq([p.tex.buffer, p.cmap.buffer, p.A.buffer, ...(p.geo ? [p.geo.shell.buffer] : []), ...(p.frames ?? []).map(f => f.buffer),
+    ...("lods" in p && p.lods ? p.lods.flatMap(levelBuffers) : []),
+    ...("bricks" in p && p.bricks ? p.bricks.flatMap(b => [...levelBuffers(b), ...(b.lods ?? []).flatMap(levelBuffers)]) : [])]);
 // ---- 大きな格子＝ブリック（第 5 段・2026-10-24）----
 //   一軸でも BRICK_LIMIT（WebGL2 の 3D テクスチャの最低保証）を越える格子は、持ち分 BRICK セル角のブリックに分けて別々のテクスチャにする。
 //   各ブリックのテクスチャは持ち分の前後に 1 セルずつ糊代（隣のセル）を足す＝三線形・等値面の勾配が継ぎ目で途切れない。描くのは持ち分（own）だけ＝体積が継ぎ目で二重に重ならない。
@@ -344,15 +348,109 @@ export function parentIndex(index, dims, off, full) {
     const cell = [i + off[0], j + off[1], k + off[2]];
     return { index: cell[0] + full[0] * (cell[1] + full[1] * cell[2]), cell };
 }
-/** prepare の大きな格子版＝上限を越えればブリックに分ける（越えなければ prepare と同じ＋vmax） */
+// ---- LoD（第 5 段 ③・2026-10-25）----
+//   GPU の予算（plugin の budget）を越えそうな格子は、各軸 1/2・1/4…に縮めた段も作る（ブリックはブリックごと・こまもこまごと）。どの段を GPU に置くかは描き手が決める（voxel-gl.ts planLevels＝遠い層から粗く）。
+//   縮め方＝子の 2×2×2 のうち空でないセルの平均（全部空なら空）＝薄い壁や疎な点も消えない。粗い段の箱は元の格子の s 倍のセル＝端の奇数は半端な描く範囲（own の端数）で切る。
+/** 粗い段の数の上限（1/16 まで） */
+export const LOD_MAX = 4;
+/** 段 s の格子の大きさ（各軸 ceil(d/s)） */
+export const levelDims = (dims, s) => [Math.ceil(dims[0] / s), Math.ceil(dims[1] / s), Math.ceil(dims[2] / s)];
+/** 作る粗い段の数＝一こまが lodBytes を越えれば、一番粗い段が lodBytes/4 以下になるまで（LOD_MAX まで）。越えなければ 0 */
+export function levelCount(dims, comps, lodBytes) {
+    const bytes = (s) => { const d = levelDims(dims, s); return d[0] * d[1] * d[2] * comps; };
+    if (lodBytes == null || !(bytes(1) > lodBytes))
+        return 0;
+    let L = 1;
+    while (L < LOD_MAX && bytes(2 ** L) > lodBytes / 4)
+        L++;
+    return L;
+}
+/** 各軸 1/2 に縮める（R8＝空でない子の平均・RGBA＝α > 0 の子の平均・全部空なら空） */
+export function downsample(tex, dims, comps) {
+    const D = levelDims(dims, 2), out = new Uint8Array(D[0] * D[1] * D[2] * comps), acc = [0, 0, 0, 0];
+    for (let k = 0; k < D[2]; k++)
+        for (let j = 0; j < D[1]; j++)
+            for (let i = 0; i < D[0]; i++) {
+                let cnt = 0;
+                acc[0] = acc[1] = acc[2] = acc[3] = 0;
+                for (let dz = 0; dz < 2; dz++) {
+                    const z = 2 * k + dz;
+                    if (z >= dims[2])
+                        break;
+                    for (let dy = 0; dy < 2; dy++) {
+                        const y = 2 * j + dy;
+                        if (y >= dims[1])
+                            break;
+                        for (let dx = 0; dx < 2; dx++) {
+                            const x = 2 * i + dx;
+                            if (x >= dims[0])
+                                break;
+                            const c = (x + dims[0] * (y + dims[1] * z)) * comps;
+                            if (comps === 1) {
+                                if (tex[c]) {
+                                    acc[0] += tex[c];
+                                    cnt++;
+                                }
+                            }
+                            else if (tex[c + 3]) {
+                                for (let a = 0; a < 4; a++)
+                                    acc[a] += tex[c + a];
+                                cnt++;
+                            }
+                        }
+                    }
+                }
+                if (!cnt)
+                    continue;
+                const o = (i + D[0] * (j + D[1] * k)) * comps;
+                for (let a = 0; a < comps; a++)
+                    out[o + a] = Math.round(acc[a] / cnt);
+            }
+    return { tex: out, dims: D };
+}
+/** 段の並び（s＝2, 4…）＝こまごとに縮める */
+export function pyramid(frames, dims, comps, L) {
+    const out = [];
+    let cur = frames, d = dims;
+    for (let l = 1; l <= L; l++) {
+        const r = cur.map(f => downsample(f, d, comps));
+        cur = r.map(x => x.tex);
+        d = r[0].dims;
+        out.push({ s: 2 ** l, dims: d, frames: cur });
+    }
+    return out;
+}
+/** 段 s の格子（frames）から、元の格子の持ち分 [lo, hi)（元のセル）を糊代 1 セルつきで切り出す。s＝1 はブリックそのもの */
+export function makeLevel(frames, Dl, comps, s, lo, hi, parent, pgeo, dims, rAx = 1) {
+    const clo = [0, 1, 2].map(i => lo[i] / s), chi = [0, 1, 2].map(i => hi[i] / s);
+    const off = [0, 1, 2].map(i => Math.max(0, Math.floor(clo[i]) - 1)), end = [0, 1, 2].map(i => Math.min(Dl[i], Math.ceil(chi[i]) + 1));
+    const bd = [0, 1, 2].map(i => end[i] - off[i]);
+    const fr = frames.map(f => extract(f, Dl, comps, off, bd)), tex = fr[0];
+    const own = [clo[0] - off[0], clo[1] - off[1], clo[2] - off[2], chi[0] - off[0], chi[1] - off[1], chi[2] - off[2]];
+    const vmax = Math.max(...fr.map(f => maxOf(f, comps)));
+    const base = { s, off, own, dims: bd, tex, frames: fr.length > 1 ? fr : null, vmax };
+    if (pgeo) {
+        const g = pgeo, f = (i, v) => v * s / dims[i]; // その段のセル → 元の割合（粗い段の端は元の外へ半端に出る＝own で切る）
+        const r = placeRegion([g.west + g.spanLon * f(0, off[0]), g.south + g.spanLat * f(1, off[1]), g.west + g.spanLon * f(0, end[0]), g.south + g.spanLat * f(1, end[1]), g.h0 + (g.h1 - g.h0) * f(2, off[2]), g.h0 + (g.h1 - g.h0) * f(2, end[2])], bd, rAx);
+        return { ...base, anchor: r.anchor, A: r.A, radius: r.radius, geo: r.geo };
+    }
+    const A = Float64Array.from(parent.A, v => v * s); // セル 1 個＝元の s 個ぶん（列ごとに同じ倍率）
+    return { ...base, anchor: parent.anchor, A, radius: parent.radius, geo: null };
+}
+/** 値 → 詰めた一こまずつ（R8／RGBA8） */
+const packFrames = (d, range, n) => { const T = d.times?.length ?? 1, out = []; for (let t = 0; t < T; t++) {
+    const v = T > 1 ? frameValues(d.values, n, d.components, t) : d.values;
+    out.push(d.components === 4 ? toRgba8(v, d.noData) : quantize(v, range, d.noData, null));
+} return out; };
+/** prepare の大きな格子版＝上限を越えればブリックに分ける（越えなければ prepare と同じ＋vmax）。o.lodBytes を越える格子は粗い段（lods）も作る */
 export function prepareGrid(data, o = {}, brick = BRICK, limit = BRICK_LIMIT) {
-    const d = checkVoxelData(data), dims = d.dims;
+    const d = checkVoxelData(data), dims = d.dims, comps = d.components, L = levelCount(dims, comps, o.lodBytes);
     if (!needsBricks(dims, limit)) {
-        const p = prepare(d, o);
-        return { ...p, vmax: Math.max(...(p.frames ?? [p.tex]).map(f => maxOf(f, p.comps))), bricks: null };
+        const p = prepare(d, o), fr = p.frames ?? [p.tex], vmax = Math.max(...fr.map(f => maxOf(f, p.comps)));
+        const lods = L ? pyramid(fr, dims, comps, L).map(lv => makeLevel(lv.frames, lv.dims, comps, lv.s, [0, 0, 0], dims, p, p.geo, dims, o.rAx ?? 1)) : null;
+        return { ...p, vmax, bricks: null, lods };
     }
-    const T = d.times?.length ?? 1, nAll = dims[0] * dims[1] * dims[2];
-    const comps = d.components;
+    const nAll = dims[0] * dims[1] * dims[2];
     let range = [0, 1];
     if (comps === 1) {
         range = o.range ?? d.range ?? valueRange(d.values, d.noData);
@@ -373,35 +471,19 @@ export function prepareGrid(data, o = {}, brick = BRICK, limit = BRICK_LIMIT) {
         parent = r;
         pgeo = r.geo;
     }
+    const full = packFrames(d, range, nAll), pyr = L ? pyramid(full, dims, comps, L) : [];
     const sx = brickSpans(dims[0], brick), sy = brickSpans(dims[1], brick), sz = brickSpans(dims[2], brick), bricks = [];
     let vmax = 0;
     for (const [z0, z1] of sz)
         for (const [y0, y1] of sy)
             for (const [x0, x1] of sx) {
                 const lo = [x0, y0, z0], hi = [x1, y1, z1];
-                const off = [0, 1, 2].map(i => Math.max(0, lo[i] - 1)), end = [0, 1, 2].map(i => Math.min(dims[i], hi[i] + 1));
-                const bd = [0, 1, 2].map(i => end[i] - off[i]);
-                const fr = [];
-                for (let t = 0; t < T; t++) {
-                    const sub = extract(T > 1 ? frameValues(d.values, nAll, comps, t) : d.values, dims, comps, off, bd);
-                    fr.push(comps === 4 ? toRgba8(sub, d.noData) : quantize(sub, range, d.noData, null));
-                }
-                const tex = fr[0], frames = T > 1 ? fr : null;
-                const vm = Math.max(...fr.map(f => maxOf(f, comps)));
-                vmax = Math.max(vmax, vm);
-                const own = [lo[0] - off[0], lo[1] - off[1], lo[2] - off[2], hi[0] - off[0], hi[1] - off[1], hi[2] - off[2]];
-                let b;
-                if (pgeo) {
-                    const g = pgeo, f = (i, v) => v / dims[i];
-                    const r = placeRegion([g.west + g.spanLon * f(0, off[0]), g.south + g.spanLat * f(1, off[1]), g.west + g.spanLon * f(0, end[0]), g.south + g.spanLat * f(1, end[1]), g.h0 + (g.h1 - g.h0) * f(2, off[2]), g.h0 + (g.h1 - g.h0) * f(2, end[2])], bd, o.rAx ?? 1);
-                    b = { off, own, dims: bd, n: bd[0] * bd[1] * bd[2], tex, frames, vmax: vm, anchor: r.anchor, A: r.A, radius: r.radius, geo: r.geo };
-                }
-                else
-                    b = { off, own, dims: bd, n: bd[0] * bd[1] * bd[2], tex, frames, vmax: vm, anchor: parent.anchor, A: Float64Array.from(parent.A), radius: parent.radius, geo: null };
-                bricks.push(b);
+                const b = makeLevel(full, dims, comps, 1, lo, hi, parent, pgeo, dims, o.rAx ?? 1);
+                vmax = Math.max(vmax, b.vmax);
+                bricks.push({ ...b, n: b.dims[0] * b.dims[1] * b.dims[2], lods: L ? pyr.map(lv => makeLevel(lv.frames, lv.dims, comps, lv.s, lo, hi, parent, pgeo, dims, o.rAx ?? 1)) : null });
             }
     const cmap = buildColormap(o.colormap, o.alphaRamp ?? null);
-    return { shape: d.shape, dims: [dims[0], dims[1], dims[2]], comps, n: dims[0] * dims[1] * dims[2], tex: new Uint8Array(0), cmap, anchor: parent.anchor, A: parent.A, radius: parent.radius, range, thr: comps === 4 ? 0 : thrOf(o.threshold, range), placed: parent.placed, geo: null, times: d.times ? Array.from(d.times) : null, frames: null, vmax, bricks };
+    return { shape: d.shape, dims: [dims[0], dims[1], dims[2]], comps, n: nAll, tex: new Uint8Array(0), cmap, anchor: parent.anchor, A: parent.A, radius: parent.radius, range, thr: comps === 4 ? 0 : thrOf(o.threshold, range), placed: parent.placed, geo: null, times: d.times ? Array.from(d.times) : null, frames: null, vmax, bricks, lods: null };
 }
 /** 光線と箱 [0, dims] の交わり（t0, t1）。無ければ null */
 export function rayBox(ro, rd, dims) {

package/dist/index.d.ts

@@ -1,12 +1,15 @@
 import type { GlobeMap, OrthoPlugin, OverlayHandle, OverlayPick, VoxelData } from "@ortho-earth/globe";
 import type { ColormapSpec, RenderMode, Clip } from "./grid.js";
-export { prepare, checkVoxelData, checkClip, thrOf, buildColormap, colorStops, parseColor, quantize, toRgba8, valueRange, placeBox, placeRegion, unitAt, hprMat, enuBasis, ecefToLngLat, ecefEnuRows, inv3, mul3, rayBox, marchBlocks, COLORMAPS, COLORMAP_NAMES, SHELL_N, prepareGrid, maxOf, needsBricks, brickSpans, extract, parentIndex, frameValues, frameAt, BRICK, BRICK_LIMIT } from "./grid.js";
-export type { PrepareOptions, Prepared, PreparedGrid, Brick, ColormapSpec, ColorStop, RenderMode, Clip, Hpr, Placement, GeoGrid, RayHit, EnuBasis, Mat3 } from "./grid.js";
-export type { VoxelMessage, VoxelLayerBody, VoxelStyle, VoxelPickResult, VoxelAltitude, OverlayHost, CamState, VoxelApi, PickContext } from "./voxel-gl.js";
+import type { SourceMeta } from "./sources.js";
+export { prepare, checkVoxelData, checkClip, thrOf, buildColormap, colorStops, parseColor, quantize, toRgba8, valueRange, placeBox, placeRegion, unitAt, hprMat, enuBasis, ecefToLngLat, ecefEnuRows, inv3, mul3, rayBox, marchBlocks, COLORMAPS, COLORMAP_NAMES, SHELL_N, prepareGrid, maxOf, needsBricks, brickSpans, extract, parentIndex, frameValues, frameAt, BRICK, BRICK_LIMIT, LOD_MAX, levelDims, levelCount, downsample, pyramid, makeLevel, levelBuffers } from "./grid.js";
+export type { PrepareOptions, Prepared, PreparedGrid, Brick, Level, ColormapSpec, ColorStop, RenderMode, Clip, Hpr, Placement, GeoGrid, RayHit, EnuBasis, Mat3 } from "./grid.js";
+export type { VoxelMessage, VoxelLayerBody, LevelBody, VoxelStyle, VoxelPickResult, VoxelAltitude, OverlayHost, CamState, VoxelApi, PickContext } from "./voxel-gl.js";
 export type { VoxelBackend, VoxelDrawOpts } from "./voxel-draw.js";
+export { readSource, parseNetCDF, sniffNetCDF, openZarr, zarrArray, readZarr, toVoxelData, pickVariable, axisOf, cfTimes, heightsOf, pressureToHeight, edges, unpack, isZarrUrl } from "./sources.js";
+export type { SourceOptions, SourceMeta, SourceData } from "./sources.js";
 export type { VoxelGpuModule } from "./voxel-gpu.js";
 import type { VoxelBackend } from "./voxel-draw.js";
-export declare const VERSION = "0.4.0";
+export declare const VERSION = "0.6.0";
 export type VoxelSource = VoxelData | string | URL | ArrayBuffer | Uint8Array;
 export interface VoxelOptions {
     kind?: "voxel";
@@ -39,11 +42,22 @@ export interface VoxelOptions {
     /** grids with `times` (a time dimension): "clock" (default) shows the frame of the map's clock (map.clock: the last frame at or before its time) and follows it as it plays;
      *  a number (ms) pins that time. Changes without re-uploading the grid */
     time?: number | "clock";
+    /** NetCDF / Zarr sources: the variable to draw (default the non-coordinate numeric variable with the most dimensions) */
+    variable?: string;
+    /** NetCDF / Zarr sources: read only frames [start, end) of the time dimension */
+    frames?: [number, number];
+    /** NetCDF / Zarr sources: the height range [h0, h1] in meters (default from the vertical coordinate; pressure levels use the standard atmosphere) */
+    heights?: [number, number];
 }
 export interface VoxelPluginOptions {
     /** "auto" (default): WebGPU when the map draws with WebGPU (shared device and depth texture), else WebGL2. "webgpu": WebGPU (own device under a WebGL2 map) or fail. "webgl2": always WebGL2 */
     backend?: VoxelBackend | "auto";
+    /** GPU memory for the voxel textures of this map, in MB (default 512, 128 on touch devices). Only the frame shown is uploaded; a grid bigger than half of it also gets
+     *  coarser levels, drawn far away when the layers in view would not fit. Infinity turns the budget off */
+    budget?: number;
 }
+/** 既定の GPU の予算（MB）＝タッチ端末は小さく（packages/ortho-core/fallback-ladder.md の 160 MB の中） */
+export declare const defaultBudgetMB: () => number;
 /** handle.pick の 1 件＝統一 picking の答え（layer＝手綱の id・index＝セルの番号・cell＝[i, j, k]・value＝セルの値） */
 export interface VoxelHit extends OverlayPick {
     id: number;
@@ -86,6 +100,10 @@ export interface VoxelHandle {
     times: number[] | null;
     /** the frame shown (0 without a time dimension) */
     frame: number;
+    /** number of coarser levels made for the GPU budget (0 = the grid fits) */
+    levels: number;
+    /** what a NetCDF / Zarr source was read as (format, variable, units, long name, dimensions, attributes); null for VoxelData */
+    source: SourceMeta | null;
     ready: Promise<VoxelHandle>;
     setData(data: VoxelSource): Promise<VoxelHandle>;
     setProps(p: Partial<VoxelOptions>): Promise<VoxelHandle>;
@@ -108,7 +126,7 @@ export declare const OVERLAY_LINGER_MS = 250;
 /** 格子を上げ直さずに変えられる opts（setProps はこれだけなら "style" を送る） */
 export declare const STYLE_KEYS: readonly (keyof VoxelOptions)[];
 /** map.addData(data, { kind: "voxel", … }) の実体 */
-export declare function createVoxel(map: VoxelMap, data: VoxelSource, opts?: VoxelOptions, { backend }?: VoxelPluginOptions): VoxelHandle;
+export declare function createVoxel(map: VoxelMap, data: VoxelSource, opts?: VoxelOptions, { backend, budget }?: VoxelPluginOptions): VoxelHandle;
 /** map.use(voxelPlugin()) → map.addData(data, { kind: "voxel", render?, colormap?, range?, threshold?, alphaRamp?, step?, opacity?, altitude?, depthTest?, above?, properties? }) */
-export declare function voxelPlugin({ backend }?: VoxelPluginOptions): VoxelPlugin;
+export declare function voxelPlugin({ backend, budget }?: VoxelPluginOptions): VoxelPlugin;
 export default voxelPlugin;

package/dist/index.js

@@ -1,8 +1,18 @@
-import { prepareGrid, transferables, checkVoxelData, checkClip, buildColormap, thrOf, frameAt } from "./grid.js";
-export { prepare, checkVoxelData, checkClip, thrOf, buildColormap, colorStops, parseColor, quantize, toRgba8, valueRange, placeBox, placeRegion, unitAt, hprMat, enuBasis, ecefToLngLat, ecefEnuRows, inv3, mul3, rayBox, marchBlocks, COLORMAPS, COLORMAP_NAMES, SHELL_N, prepareGrid, maxOf, needsBricks, brickSpans, extract, parentIndex, frameValues, frameAt, BRICK, BRICK_LIMIT } from "./grid.js";
+import { transferables, levelBuffers, checkVoxelData, checkClip, buildColormap, thrOf, frameAt } from "./grid.js";
+import { readAndPrepare } from "./voxel-reader.js";
+export { prepare, checkVoxelData, checkClip, thrOf, buildColormap, colorStops, parseColor, quantize, toRgba8, valueRange, placeBox, placeRegion, unitAt, hprMat, enuBasis, ecefToLngLat, ecefEnuRows, inv3, mul3, rayBox, marchBlocks, COLORMAPS, COLORMAP_NAMES, SHELL_N, prepareGrid, maxOf, needsBricks, brickSpans, extract, parentIndex, frameValues, frameAt, BRICK, BRICK_LIMIT, LOD_MAX, levelDims, levelCount, downsample, pyramid, makeLevel, levelBuffers } from "./grid.js";
+export { readSource, parseNetCDF, sniffNetCDF, openZarr, zarrArray, readZarr, toVoxelData, pickVariable, axisOf, cfTimes, heightsOf, pressureToHeight, edges, unpack, isZarrUrl } from "./sources.js";
 // 描き手（worker）の URL＝入口（voxel-draw.js が兄弟を import）。字面は .js のまま＝npm の dist では実体・repo の中では Vite が .ts に読み替える
 const VOXEL_URL = new URL("./voxel-draw.js", import.meta.url).href;
-export const VERSION = "0.4.0";
+export const VERSION = "0.6.0";
+/** 既定の GPU の予算（MB）＝タッチ端末は小さく（packages/ortho-core/fallback-ladder.md の 160 MB の中） */
+export const defaultBudgetMB = () => { try {
+    return typeof matchMedia === "function" && matchMedia("(pointer: coarse)").matches ? 128 : 512;
+}
+catch {
+    return 512;
+} };
+const MB = 1 << 20;
 /** 楕円体表示の b/a（region の殻を本体と同じ形で作る） */
 const R_AX_ELL = 1 - 1 / 298.257223563;
 const rAxOf = (map) => { try {
@@ -14,7 +24,7 @@ catch {
 const shared = new WeakMap();
 /** 手綱が全部外れてからオーバーレイを片付けるまでの猶予（ms）＝場面の切り替え（remove → すぐ addData）で同じ名のオーバーレイを壊して作り直さない（render worker の片付けと新しい登録が競う） */
 export const OVERLAY_LINGER_MS = 250;
-function acquire(map, above, id, backend) {
+function acquire(map, above, id, backend, budget) {
     let m = shared.get(map);
     if (!m)
         shared.set(map, (m = { ids: new Set() }));
@@ -40,6 +50,7 @@ function acquire(map, above, id, backend) {
                 slot.errors.get(e.q)?.(e.error || "error");
             }
         };
+        ov.post({ type: "budget", bytes: Number.isFinite(budget) ? budget * MB : 0 }); // 0＝予算なし
         m[k] = slot;
     }
     m[k].refs++;
@@ -99,15 +110,14 @@ const readerFree = () => { if (--liveHandles > 0 || !reader)
     return; readerIdle = setTimeout(() => { readerIdle = null; if (liveHandles || !reader)
     return; reader.w.terminate(); reader = null; }, 5000); };
 const isFileSource = (src) => typeof src === "string" || src instanceof URL || src instanceof ArrayBuffer || src instanceof Uint8Array;
-async function load(src, o, rAx) {
-    if (isFileSource(src))
-        throw new Error("voxel: file sources (.nc / .zarr / .vox / .npy) are not read yet (stage 5); pass VoxelData");
-    const d = checkVoxelData(src);
-    const popts = { colormap: o.colormap, range: o.range ?? null, alphaRamp: o.alphaRamp ?? null, threshold: o.threshold ?? null, rAx };
+async function load(src, o, rAx, budget) {
+    const file = isFileSource(src), d = file ? null : checkVoxelData(src);
+    const source = file ? { variable: o.variable, frames: o.frames ?? null, heights: o.heights ?? null } : undefined, fsrc = file ? (src instanceof URL ? src.href : src) : undefined;
+    const popts = { colormap: o.colormap, range: o.range ?? null, alphaRamp: o.alphaRamp ?? null, threshold: o.threshold ?? null, rAx, lodBytes: Number.isFinite(budget) ? budget * MB / 2 : null }; // 予算の半分を越える格子は粗い段も
     const r = spawnReader();
     if (r) {
         try {
-            const seq = ++r.seq, req = { seq, data: d, opts: popts };
+            const seq = ++r.seq, req = file ? { seq, src: fsrc, source, opts: popts } : { seq, data: d, opts: popts };
             const p = await new Promise((res, rej) => { r.pending.set(seq, { res, rej }); r.w.postMessage(req); }); // data は写し＝渡した人の配列は手放さない
             return { ...p, reader: "worker" };
         }
@@ -116,7 +126,7 @@ async function load(src, o, rAx) {
                 throw e;
         }
     }
-    return { ...prepareGrid(d, popts), reader: "main" };
+    return { ...(await readAndPrepare(file ? { src: fsrc, source, opts: popts } : { data: d, opts: popts })), reader: "main" };
 }
 const isVoxelHit = (id) => (t) => t.layer === id;
 const checkEnum = (v, allowed, name) => { if (!allowed.includes(v))
@@ -138,15 +148,21 @@ function checkOpts(opts) {
     checkClip(opts.clip);
     if (opts.time != null && opts.time !== "clock" && !(typeof opts.time === "number" && Number.isFinite(opts.time)))
         throw new TypeError("voxel: time must be \"clock\" or a time in ms");
+    if (opts.variable != null && typeof opts.variable !== "string")
+        throw new TypeError("voxel: variable must be a string");
+    if (opts.frames != null && !(Array.isArray(opts.frames) && opts.frames.length === 2 && opts.frames.every(Number.isInteger) && opts.frames[0] >= 0 && opts.frames[1] > opts.frames[0]))
+        throw new RangeError("voxel: frames must be [start, end) frame numbers");
+    if (opts.heights != null && !(Array.isArray(opts.heights) && opts.heights.length === 2 && opts.heights.every(Number.isFinite) && opts.heights[0] < opts.heights[1]))
+        throw new RangeError("voxel: heights must be [h0, h1] meters with h0 < h1");
 }
 let anonSeq = 0;
 /** map.addData(data, { kind: "voxel", … }) の実体 */
-export function createVoxel(map, data, opts = {}, { backend = "auto" } = {}) {
+export function createVoxel(map, data, opts = {}, { backend = "auto", budget = defaultBudgetMB() } = {}) {
     checkOpts(opts);
     if (!isFileSource(data))
         checkVoxelData(data); // 形の間違いは今・同期に投げる（worker へ送ってからでは遅い）
     const id = opts.id ?? `voxel${++anonSeq}`;
-    const { ov, slot, release } = acquire(map, !!opts.above, id, backend);
+    const { ov, slot, release } = acquire(map, !!opts.above, id, backend, budget);
     try {
         ov.addLayerId?.(id);
     }
@@ -172,7 +188,7 @@ export function createVoxel(map, data, opts = {}, { backend = "auto" } = {}) {
         map.clock.off("tick", onClock).off("change", onClock); };
     const run = async (src, o) => {
         const my = ++seq;
-        const p = await load(src, o, rAxOf(map));
+        const p = await load(src, o, rAxOf(map), budget);
         if (removed || my !== seq)
             return h;
         h.dims = p.dims;
@@ -183,11 +199,13 @@ export function createVoxel(map, data, opts = {}, { backend = "auto" } = {}) {
         h.error = null;
         h.shape = p.shape;
         h.bricks = p.bricks?.length ?? 0;
+        h.levels = (p.lods ?? p.bricks?.[0]?.lods)?.length ?? 0;
         times = h.times = p.times;
         h.frame = frameNow();
         follow(!!times && (o.time ?? "clock") === "clock");
         cur = src;
-        values = src.values;
+        values = p.values ?? src.values;
+        h.source = p.meta ?? null;
         comps = p.comps;
         baked = true;
         const style = { mode: MODE[o.render ?? "volume"], thr: p.thr, step: o.step ?? 0.5, opacity: o.opacity ?? 1, clip: checkClip(o.clip), depthTest: o.depthTest !== false, properties: o.properties ?? null, range: p.range, on: visible, frame: h.frame, alt: o.altitude ?? (p.placed ? "absolute" : "relative") };
@@ -201,9 +219,9 @@ export function createVoxel(map, data, opts = {}, { backend = "auto" } = {}) {
         for (const q of qs)
             slot.errors.set(q, e => { h.error = e; }); // 描き手の build の失敗（3D テクスチャの上限など）は非同期に届く＝warn と手綱の error（ready は解決する）
         if (!p.bricks)
-            ov.post({ type: "layer", q: id, shape: p.shape, dims: p.dims, comps: p.comps, tex: p.tex, frames: p.frames, cmap: p.cmap, anchor: p.anchor, A: p.A, radius: p.radius, geo: p.geo, vmax: p.vmax, ...style }, transferables(p));
+            ov.post({ type: "layer", q: id, shape: p.shape, dims: p.dims, comps: p.comps, tex: p.tex, frames: p.frames, lods: p.lods, cmap: p.cmap, anchor: p.anchor, A: p.A, radius: p.radius, geo: p.geo, vmax: p.vmax, ...style }, transferables(p));
         else
-            p.bricks.forEach((b, i) => ov.post({ type: "layer", q: qs[i], layer: id, shape: p.shape, dims: b.dims, comps: p.comps, tex: b.tex, frames: b.frames, cmap: i ? p.cmap.slice() : p.cmap, anchor: b.anchor, A: b.A, radius: b.radius, geo: b.geo, vmax: b.vmax, off: b.off, own: b.own, full: p.dims, ...style }, [b.tex.buffer, b.A.buffer, ...(b.geo ? [b.geo.shell.buffer] : []), ...(b.frames ?? []).map(f => f.buffer)].filter((x, k, a) => a.indexOf(x) === k)));
+            p.bricks.forEach((b, i) => ov.post({ type: "layer", q: qs[i], layer: id, shape: p.shape, dims: b.dims, comps: p.comps, tex: b.tex, frames: b.frames, lods: b.lods, cmap: i ? p.cmap.slice() : p.cmap, anchor: b.anchor, A: b.A, radius: b.radius, geo: b.geo, vmax: b.vmax, off: b.off, own: b.own, full: p.dims, ...style }, [...levelBuffers(b), ...(b.lods ?? []).flatMap(levelBuffers)].filter((x, k, a) => a.indexOf(x) === k)));
         return h;
     };
     // 見た目だけの変更＝格子を上げ直さない（render・opacity・step・threshold・clip・depthTest・properties・colormap・alphaRamp）
@@ -243,7 +261,7 @@ export function createVoxel(map, data, opts = {}, { backend = "auto" } = {}) {
         t.properties = { ...t.properties, value: v };
     } return t; };
     const h = {
-        id, kind: "voxel", overlay: ov, dims: null, n: 0, anchor: null, range: null, reader: null, error: null, shape: null, bricks: 0, times: null, frame: 0,
+        id, kind: "voxel", overlay: ov, dims: null, n: 0, anchor: null, range: null, reader: null, error: null, shape: null, bricks: 0, levels: 0, source: null, times: null, frame: 0,
         get backend() { return slot.backend; },
         ready: undefined,
         setData: (d) => { if (!isFileSource(d))
@@ -271,14 +289,16 @@ export function createVoxel(map, data, opts = {}, { backend = "auto" } = {}) {
     return h;
 }
 /** map.use(voxelPlugin()) → map.addData(data, { kind: "voxel", render?, colormap?, range?, threshold?, alphaRamp?, step?, opacity?, altitude?, depthTest?, above?, properties? }) */
-export function voxelPlugin({ backend = "auto" } = {}) {
+export function voxelPlugin({ backend = "auto", budget = defaultBudgetMB() } = {}) {
     checkEnum(backend, ["auto", "webgpu", "webgl2"], "backend");
+    if (!(typeof budget === "number" && budget > 0))
+        throw new RangeError("voxel: budget must be a positive number of MB (Infinity = no budget)");
     return {
         name: "voxel",
         version: VERSION,
         provides: ["data.voxel"],
         install(map) {
-            map.registry.dataKinds.add("voxel", { create: (m, data, o) => createVoxel(m, data, o, { backend }) });
+            map.registry.dataKinds.add("voxel", { create: (m, data, o) => createVoxel(m, data, o, { backend, budget }) });
             return () => { try {
                 map.registry.dataKinds.remove("voxel");
             }

package/dist/sources.d.ts

@@ -0,0 +1,91 @@
+import type { VoxelData } from "@ortho-earth/globe";
+export interface SourceOptions {
+    /** 描く変数の名前（省略＝座標でない、次元の一番多い数値の変数） */
+    variable?: string;
+    /** 時間の次元のこまの範囲 [始め, 終わり)（番号・省略＝全部） */
+    frames?: [number, number] | null;
+    /** 高さの範囲 [h0, h1]（m）を上書き（高さの座標が無い・気圧面の近似を避けたい時） */
+    heights?: [number, number] | null;
+    /** fetch の代わり（検定・認証つきの取り方） */
+    fetch?: (url: string) => Promise<Response>;
+}
+/** 読んだ変数の説明（手綱の source に載る） */
+export interface SourceMeta {
+    format: "netcdf" | "zarr";
+    variable: string;
+    units: string | null;
+    longName: string | null;
+    dims: string[];
+    attrs: Record<string, unknown>;
+}
+export type SourceData = VoxelData & {
+    shape: "region";
+    region: [number, number, number, number, number, number];
+    values: Float32Array;
+    meta: SourceMeta;
+};
+type Attrs = Record<string, unknown>;
+interface VarInfo {
+    name: string;
+    dims: string[];
+    shape: number[];
+    attrs: Attrs;
+    numeric: boolean;
+}
+interface Reader {
+    format: "netcdf" | "zarr";
+    vars: VarInfo[];
+    /** 変数の値（全体か、先頭の軸を [t0, t1) に絞った物）→ Float64 ではなく Float32（scale／offset・fill 済み） */
+    read(name: string, first?: [number, number] | null): Promise<Float32Array>;
+    /** 座標の 1 次元の値（そのまま） */
+    coord(name: string): Promise<Float64Array>;
+}
+type Axis = "x" | "y" | "z" | "t";
+/** 座標の変数が何の軸か（CF：axis・units・standard_name・名前） */
+export declare function axisOf(name: string, attrs: Attrs): Axis | null;
+/** CF の時刻（"hours since 1900-01-01 00:00:0.0" など）→ ms。読めなければ null */
+export declare function cfTimes(values: ArrayLike<number>, units: string | null): number[] | null;
+/** 気圧（Pa）→ 高さ（m・標準大気の対流圏の式） */
+export declare const pressureToHeight: (pa: number) => number;
+/** 高さの座標 → m（units と positive で） */
+export declare function heightsOf(values: ArrayLike<number>, attrs: Attrs, name?: string): number[];
+/** セルの中心の並び → 範囲（端のセルの半分だけ外へ）と昇順か。一つだけなら step で幅 */
+export declare function edges(c: ArrayLike<number>, step1?: number): {
+    lo: number;
+    hi: number;
+    asc: boolean;
+};
+/** 選んだ変数（座標でない・数値・次元 2〜4・x と y がある）を探す */
+export declare function pickVariable(r: Pick<Reader, "vars">, want?: string): VarInfo;
+/** 読み手 → VoxelData（region・times） */
+export declare function toVoxelData(r: Reader, o?: SourceOptions): Promise<SourceData>;
+/** 値の整え（scale_factor／add_offset・fill・valid range → NaN） */
+export declare function unpack(src: ArrayLike<number> & {
+    length: number;
+}, attrs: Attrs, fill?: number | null): Float32Array;
+/** NetCDF の形式（"classic"＝読める・"hdf5"＝NetCDF-4・null＝NetCDF でない） */
+export declare function sniffNetCDF(b: Uint8Array): "classic" | "hdf5" | null;
+export declare function parseNetCDF(buf: ArrayBuffer | Uint8Array): Reader;
+interface ZArray {
+    shape: number[];
+    chunks: number[];
+    dtype: string;
+    fill: number | null;
+    codec: "none" | "gzip" | "zlib";
+    sep: string;
+    v3: boolean;
+    key: (c: number[]) => string;
+    attrs: Attrs;
+    dims: string[];
+}
+/** Zarr のメタ（v2 の .zarray＋.zattrs、v3 の zarr.json）→ 読み方 */
+export declare function zarrArray(meta: Attrs, attrs?: Attrs, v3?: boolean): ZArray;
+/** Zarr の配列を読む（先頭の軸を [a, b) に絞れる・無いチャンクは fill） */
+export declare function readZarr(get: (path: string) => Promise<Uint8Array | null>, path: string, z: ZArray, first?: [number, number] | null): Promise<Float64Array>;
+/** Zarr の店（URL の根）→ 読み手。consolidated（.zmetadata／zarr.json の consolidated_metadata）があれば一覧、無ければ variable と座標を名前で取る */
+export declare function openZarr(root: string, o?: SourceOptions): Promise<Reader>;
+/** URL の種類（.zarr＝Zarr の店・それ以外の .nc 等＝一つのファイル） */
+export declare const isZarrUrl: (u: string) => boolean;
+/** VoxelSource（URL／bytes）→ VoxelData（region・times・meta） */
+export declare function readSource(src: string | URL | ArrayBuffer | Uint8Array, o?: SourceOptions): Promise<SourceData>;
+export {};