worldarray 0.1.0__tar.gz → 0.1.1__tar.gz

worldarray-0.1.1/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 0.1.1 (2026-10-22)
+
+- funlib `voxel_size`/`offset` on the parent group place an array that carries none, for
+  zarr and N5 alike; funlib's keys on an N5 array are read in the array's C order, as
+  zarr-python's N5 store writes them (both from mesh-n-bone's review of its PR #48).
+- A precomputed path that names a scale is that scale under `level=0` or `"first"` too;
+  other levels warn and are ignored, as on an array path.
+- The GCE metadata guard is applied only off Google Cloud (decided from the DMI product
+  name and the `GCE_METADATA_*` variables), so metadata-server credentials keep working on
+  a Google VM.
+- `Pyramid.placements()`, `voxel_sizes()` and `translations()` read the group document when
+  the pyramid was opened through one of its level paths too; they used to open every level
+  from there, and a missing level made them raise.
+- **Placement change.** An N5 level with `downsamplingFactors` and no offset now sits with
+  its corner at the origin at every level, as Neuroglancer draws N5: translation
+  `f / 2 * base`. 0.1.0 followed BigDataViewer for `pixelResolution` pyramids, centring the
+  base's voxel 0 on the origin (`(f - 1) / 2 * base`, half a base voxel lower), while
+  placing `resolution` pyramids with the corner at the origin, so the two disagreed. Two
+  shared fixture cases move and are renamed: `n5_group_pixelresolution_and_downsampling_factors_corner_at_origin`
+  (translation 4, 4, 4) and `n5_bigstitcher_resolution_with_downsampling_factors_corner_at_origin`
+  (0.5, 0.157, 0.157).
+
+## 0.1.0 (2026-10-21)
+
+- First version, built to `docs/spec.md`: open zarr v2, zarr v3, N5 and Neuroglancer
+  precomputed arrays and pyramids through tensorstore; one metadata precedence per format
+  with the voxel-centre rule for translations; index-space and world-box reads with
+  padding; level selection; nearest and linear resampling; retries; shared and capped
+  tensorstore contexts.
+  Built and trialled in one day against the readers it replaces in cellmap-flow,
+  cellmap-analyze, mesh-n-bone and chunkmirage, and checked on their own data by the
+  CineMap, liconn-err, registration-station and salamander repos; see `docs/spec.md`,
+  "Trial status". Hot-path reads cost 0.1 to 0.2 ms over a raw tensorstore read.

{worldarray-0.1.0 → worldarray-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: worldarray
-Version: 0.1.0
+Version: 0.1.1
 Summary: Read zarr, N5 and Neuroglancer precomputed volumes in world coordinates through tensorstore: correct voxel placement, pyramid levels, padded region reads, resampling. numpy + tensorstore only.
 Project-URL: Homepage, https://janeliascicomp.github.io/worldarray/
 Project-URL: Documentation, https://janeliascicomp.github.io/worldarray/
@@ -67,8 +67,7 @@ pip install worldarray
 
 ## Why
 
-Volumetric data at Janelia lives in zarr v2, zarr v3, N5 and Neuroglancer precomputed
-stores, on local disks, S3, GCS and HTTP. Each format records *where the array sits*,
+Volumetric data lives in zarr v2, zarr v3, N5 and Neuroglancer precomputed stores, on local disks, S3, GCS and HTTP. Each format records *where the array sits*,
 its voxel size, origin, units and axes, in its own dialect, and the dialects disagree on
 the one thing that matters most: whether a stored origin means the centre of the first
 voxel or its corner. Get that wrong and every object is half a voxel out of place, which
@@ -79,8 +78,7 @@ rule for each, picking a pyramid level for a wanted resolution, and reading a re
 given in physical units as a plain numpy block, padded where the region leaves the data,
 resampled when no level matches, fast enough for a model server or a thousand cluster
 workers, with retries for flaky object stores and thread caps for shared hosts. No one
-package did all of that, so every tool here wrote its own reader, and the readers drifted
-apart. worldarray is that reader, written once, with the rules stated and tested.
+package did all of that, so every tool wrote its own reader, and the readers drifted apart. worldarray is that reader, written once, with the rules stated and tested.
 
 Its dependencies are `tensorstore` and `numpy`. It is read-only in this version. The
 [specification](https://janeliascicomp.github.io/worldarray/spec/) is the contract it is

{worldarray-0.1.0 → worldarray-0.1.1}/README.md

@@ -8,8 +8,7 @@ pip install worldarray
 
 ## Why
 
-Volumetric data at Janelia lives in zarr v2, zarr v3, N5 and Neuroglancer precomputed
-stores, on local disks, S3, GCS and HTTP. Each format records *where the array sits*,
+Volumetric data lives in zarr v2, zarr v3, N5 and Neuroglancer precomputed stores, on local disks, S3, GCS and HTTP. Each format records *where the array sits*,
 its voxel size, origin, units and axes, in its own dialect, and the dialects disagree on
 the one thing that matters most: whether a stored origin means the centre of the first
 voxel or its corner. Get that wrong and every object is half a voxel out of place, which
@@ -20,8 +19,7 @@ rule for each, picking a pyramid level for a wanted resolution, and reading a re
 given in physical units as a plain numpy block, padded where the region leaves the data,
 resampled when no level matches, fast enough for a model server or a thousand cluster
 workers, with retries for flaky object stores and thread caps for shared hosts. No one
-package did all of that, so every tool here wrote its own reader, and the readers drifted
-apart. worldarray is that reader, written once, with the rules stated and tested.
+package did all of that, so every tool wrote its own reader, and the readers drifted apart. worldarray is that reader, written once, with the rules stated and tested.
 
 Its dependencies are `tensorstore` and `numpy`. It is read-only in this version. The
 [specification](https://janeliascicomp.github.io/worldarray/spec/) is the contract it is

{worldarray-0.1.0 → worldarray-0.1.1}/docs/spec.md

@@ -144,7 +144,8 @@ pyr.metas() ; pyr.level_meta("s1")   # ArrayMeta per level from the documents al
                     #   array's inner chunk), fill and placement, with no tensorstore opened
 pyr.placements()    # (name, spatial voxel size, spatial translation) per level from the group's own document
 pyr.voxel_sizes() ; pyr.translations()   #   where it lists the levels (OME-NGFF, COSEM N5, precomputed), so
-                    #   choosing or placing a level opens nothing; else by opening each level
+                    #   choosing or placing a level opens nothing, whether the pyramid was opened by its
+                    #   group path or by one of its level paths; else by opening each level
 
 wa.metadata(path, level=None, units=None, open=True) -> ArrayMeta   # open=False: from the documents alone
 wa.detect(path, missing_ok=False) -> Node | None   # format, kind (array|group), path, docs, scale_key; .attrs (raw user
@@ -215,10 +216,15 @@ this document and that one differ, fix one of them.
    CF coordinates. Index `i` on an axis sits at `translation + i * voxel_size`; voxel `i`
    covers `[translation + (i - 1/2) * voxel_size, translation + (i + 1/2) * voxel_size)`.
    Formats that store voxel 0's **corner** are moved half a voxel along the spatial axes
-   on reading. N5 levels with `pixelResolution` and `downsamplingFactors` and no offset
-   follow BigDataViewer: level-L voxel `i` is centred where full-resolution voxels
-   `f*i .. f*i+f-1` are, that is `(f - 1) / 2` full-resolution voxels on from voxel 0's
-   centre (the imglib2 rule liconn-err and registration-station both use). The shift
+   on reading. An N5 level with `downsamplingFactors` and no offset sits as Neuroglancer
+   draws it, a pure scale of the base grid with every level's corner at the origin: level-L
+   voxel `i` covers full-resolution voxels `f*i .. f*i+f-1`, so its centre is `f*i + f/2`
+   full-resolution voxels from the origin and its translation `f / 2 * base`. BigDataViewer
+   centres voxel 0 on the origin instead, half a base voxel lower at every level; the shift
+   between levels, `(f - 1) / 2` base voxels, is the same in both and is the imglib2 rule
+   liconn-err and registration-station use. (Decided 2026-10-22, when mesh-n-bone found
+   that `pixelResolution` and `resolution` pyramids disagreed; 0.1.0 followed BigDataViewer
+   for `pixelResolution`.) The shift
    applies only along axes named `z`, `y` or `x`, or the last three when axes are unnamed;
    never along channel or time.
 
@@ -227,7 +233,7 @@ this document and that one differ, fix one of them.
    | OME-NGFF `translation` (zarr v2/v3) | centre of voxel 0 | as is |
    | COSEM `transform.translate` (N5 or zarr) | centre (fibsem-tools wrote it as the first sample's position; Neuroglancer ignores `transform` and `offset` on N5 entirely) | as is |
    | funlib `offset` with `resolution`/`voxel_size` (N5 or zarr; `offset` missing = 0) | corner | `offset + voxel_size / 2` |
-   | N5 `pixelResolution` x `downsamplingFactors f`, no offset | BigDataViewer | `(f - 1) / 2 * pixelResolution` |
+   | N5 `pixelResolution` or `resolution` x `downsamplingFactors f`, no offset | corner at the origin at every level, as Neuroglancer draws N5 | `f / 2 * pixelResolution` |
    | precomputed `voxel_offset` x `resolution` | corner | `+ resolution / 2` |
    | CF coordinate array (xarray zarr) | sample position = centre | as is (chunkmirage layers this) |
    | nothing at all | Neuroglancer draws a plain array with its corner at the origin | voxels of 1, translation 0.5 |
@@ -284,16 +290,19 @@ this document and that one differ, fix one of them.
      `sequence`; ignore the multiscale-level transforms (they lead to other systems, which
      chunkmirage's `scene://` applies itself) and any other transform type. Else the array's
      own `resolution` / `voxel_size`, `offset`, `units`, `axis_names` (funlib) or `transform`
-     (COSEM), C order; else tensorstore's `dimension_units` attribute (zarr v3). Axes from
+     (COSEM), C order; else the same funlib keys on the parent group when the array carries
+     none (mesh-n-bone's inputs); else tensorstore's `dimension_units` attribute (zarr v3). Axes from
      OME `axes`, `dimension_names` (zarr v3), `_ARRAY_DIMENSIONS` (xarray) or `axis_names`.
    - N5: the array's `transform` (COSEM; C order unless `ordering: "F"`); else the parent's
-     `multiscales[].datasets[].transform` for this path; else `pixelResolution` (both the
+     `multiscales[].datasets[].transform` for this path; else funlib's `voxel_size` and
+     `offset` (array, else group), which zarr-python's N5 store leaves in the array's C
+     order, read by the zarr funlib rule above; else `pixelResolution` (both the
      `{dimensions, unit}` form and a bare list) or `resolution`, from the array else the
      group, times the level's `downsamplingFactors`; plus `offset`; axes from the `axes`
-     attribute. These lists are x-first. Without an `offset`, a level with `downsamplingFactors` follows
-     BigDataViewer whichever key gave the base (BigStitcher writes `resolution` and
-     `downsamplingFactors`), and a funlib `resolution` with no `downsamplingFactors` means a
-     corner at 0 (translation half a voxel); funlib never writes `downsamplingFactors`.
+     attribute. These lists are x-first. Without an `offset` the corner is at the origin at
+     every level whichever key gave the base (BigStitcher writes `resolution` and
+     `downsamplingFactors`; funlib writes `resolution` alone): translation `f / 2 * base`,
+     half a voxel of the level (Convention 1).
    - **Short lists.** A funlib, COSEM or N5 per-axis list shorter than the array (a 3-entry
      `voxel_size` on a `(c, z, y, x)` prediction, which funlib's `prepare_ds(num_channels=)`
      writes) covers the trailing axes; the leading axes get voxel size 1, translation 0,
@@ -326,8 +335,11 @@ this document and that one differ, fix one of them.
    that answers anything but a document (a server root's 301) ends the search for a
    multiscales entry quietly. Off Google Cloud, `GCE_METADATA_ROOT` is pointed at a name that
    fails at once before the first `gs://` open, because tensorstore's probe of the GCE
-   metadata server otherwise stalls every open for seconds (`store.GUARD_GCE_METADATA`
-   turns this off). A `precomputed://` prefix is accepted and
+   metadata server otherwise stalls every open for seconds; "off Google Cloud" is decided
+   with no network call, from the machine's DMI product name and the `GCE_METADATA_HOST` and
+   `GCE_METADATA_ROOT` variables, and on a Google machine the variable is left alone so the
+   credentials the real metadata server issues keep working (`store.GUARD_GCE_METADATA`
+   turns the guard off). A `precomputed://` prefix is accepted and
    dropped. The `.n5` or `.zarr` suffix is never used to decide the format. A zarr v2
    compressor carrying members tensorstore rejects (the `checksum` newer numcodecs writes
    for zstd) is opened without them. Access: a path with no scheme is a local file; `s3://`
@@ -380,13 +392,14 @@ this document and that one differ, fix one of them.
 3. **Level selection** (`select_level`, `Pyramid.select`, `open(voxel_size=)`) follows
    cellmap-flow's four modes plus one: `floor` (the level at that voxel size, else the
    **coarsest** level that is no coarser than the target on any axis, else the first),
-   `finer` (as `floor`, but an error instead of the fallback to the first level, which is
-   cellmap-analyze's rule), `exact` (that
-   level or `ValueError` listing the levels), `nearest` (closest on a log scale summed over
+   `finer` (as `floor`, but an error instead of the fallback to the first level, for
+   callers that would rather fail than read coarser data than asked), `exact` (that level or
+   `ValueError` listing the levels), `nearest` (closest on a log scale summed over
    axes, finer on a tie), `resample` (the level to resample from). Voxel sizes compare as
    floats with `rtol 1e-6`, so 10.48 is not 10. A group path without `level` or
    `voxel_size` raises with the level list; a level name that does not exist raises with
-   the list; an array path with `level` warns and ignores it. When no level has the
+   the list; an array path, or a precomputed path naming a scale, is that array or scale
+   under `level=0` or `"first"` silently and warns and ignores any other `level`. When no level has the
    requested `voxel_size`, `on_mismatch` decides: `"error"` raises with the list;
    `"resample"` reads the level `level_mode` picks and resamples (Behaviour 4); `"relabel"`
    reads that level voxel for voxel and reports `voxel_size` as the requested size with
@@ -487,7 +500,7 @@ chunkmirage derives from raw attributes carries a `layered` note beside the pack
 
 - chunkmirage's cases: N5 transposed to C order with `resolution` and `offset`; N5 COSEM
   `transform` C order; N5 group `pixelResolution` and `downsamplingFactors`
-  (BigDataViewer); N5 group `multiscales` transform matched by path; OME levels matched by
+  (the corner at the origin at every level, as Neuroglancer); N5 group `multiscales` transform matched by path; OME levels matched by
   path; OME top-level transforms applied after each dataset; an OME-unlisted array borrows
   no other level's scale; zarr legacy array attrs as a corner; a zarr3 OME 0.5 group with a
   channel axis; precomputed `voxel_offset` as a centre translation; xarray dimensions and
@@ -510,7 +523,11 @@ chunkmirage derives from raw attributes carries a `layered` note beside the pack
   fallback; detection ignores the directory suffix and finds a precomputed scale key.
 
 Reads: every statement in Behaviour 1, 2, 3 and 9; a document-less group probed through
-`s0`, integer and `"first"` levels, `detect(missing_ok=True)`, `index_box`; `read_index`
+`s0`, integer and `"first"` levels, `detect(missing_ok=True)`, `index_box`; funlib keys on
+the parent group of an attribute-less zarr and N5 array, and funlib `voxel_size`/`offset` on
+an N5 array in C order; a precomputed path naming a scale kept under `level="first"`; the
+GCE guard left alone on a Google machine; a pyramid opened through one of its level paths
+placing every level from the group document while one level's array is missing; `read_index`
 with `select`; `base_voxel_size` rescaling a BigStitcher-style pyramid; `AWS_ENDPOINT_URL`,
 `AWS_ENDPOINT_URL_S3` and the region reaching the S3 specs and the GCS redirect keying the
 kvstore cache; an array path kept under `voxel_size`; relabel keeping the corner; a
@@ -531,8 +548,8 @@ the data; a resample target set at open reports the target voxel size with the s
 Placement: the same cube stored four ways, as OME-NGFF with a `translation`, as N5 with
 funlib `resolution`/`offset`, as N5 with a COSEM `transform`, and as precomputed with a
 `voxel_offset`, reads back with the same `translation` and the same bytes for the same
-world box, within `0.1 * voxel_size`; and an N5 BigDataViewer level 1 sits where the
-equivalent OME level 1 does.
+world box, within `0.1 * voxel_size`; and an N5 level 1 with `downsamplingFactors` sits where the
+equivalent OME level 1 does, both pyramids' s0 corner at the origin.
 
 Network (skipped without it; not yet written): one public OpenOrganelle volume with a
 non-integer z spacing (4.56 or 5.24 nm), read anonymously from s3: the package reports the

{worldarray-0.1.0 → worldarray-0.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "worldarray"
-version = "0.1.0"
+version = "0.1.1"
 description = "Read zarr, N5 and Neuroglancer precomputed volumes in world coordinates through tensorstore: correct voxel placement, pyramid levels, padded region reads, resampling. numpy + tensorstore only."
 readme = "README.md"
 license = { file = "LICENSE" }

{worldarray-0.1.0 → worldarray-0.1.1}/src/worldarray/__init__.py

@@ -17,7 +17,7 @@ from .placement import ArrayMeta, corner_to_centre, default_axes
 from .retry import Retry
 from .store import Node, detect, list_chunk_keys
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 
 __all__ = [
     "ArrayMeta",

{worldarray-0.1.0 → worldarray-0.1.1}/src/worldarray/array.py

@@ -26,7 +26,7 @@ from . import resample as _resample
 from . import units as U
 from .context import shared_context
 from .geometry import Box, index_range, is_aligned
-from .levels import LevelRef, Mode, discover, same_voxel_size, select_level
+from .levels import LevelRef, Mode, discover, discover_group, same_voxel_size, select_level
 from .placement import ArrayMeta, light_levels, read_meta, read_meta_light
 from .retry import Retry, read_with_retries
 from .store import Node, detect, is_remote, open_array, precomputed_scale_index
@@ -145,11 +145,17 @@ class WorldArray:
     # --- construction helpers -------------------------------------------------
 
     def _choose_level(self, node: Node, level, voxel_size, level_mode, on_mismatch) -> LevelRef:
-        if level == "first":
-            level = 0
-        if node.format == "precomputed" and node.scale_key is not None and level is None:
+        if node.format == "precomputed" and node.scale_key is not None:
+            # a path naming a scale is that scale, as an array path is that array
+            if level not in (None, 0, "first"):
+                warnings.warn(
+                    f"{self.path} names a precomputed scale; level={level!r} is ignored",
+                    stacklevel=3,
+                )
             index = precomputed_scale_index(node.docs["info"], node.scale_key)
             return LevelRef(node.scale_key, node.path, index)
+        if level == "first":
+            level = 0
         if node.kind == "array":
             if level is not None and level != 0:  # "first" (already 0) and 0 mean "this array"
                 warnings.warn(f"{self.path} is an array; level={level!r} is ignored", stacklevel=3)
@@ -743,7 +749,7 @@ class Pyramid:
         self._select = select or {}
         self._kwargs = kwargs
         self._node = _node if _node is not None else detect(path)
-        self._refs = discover(self._node)
+        self._group, self._refs = discover_group(self._node)  # the node listing the levels
         if not self._refs:
             raise ValueError(
                 f"{path}: no levels found (no multiscales datasets, no s0, no precomputed scales)"
@@ -795,9 +801,8 @@ class Pyramid:
         COSEM N5, precomputed), else by opening each level."""
         if self._light is None:
             space, _ = _unit_targets(self.units)
-            group = self._node if self._node.kind == "group" else None
-            if group is None and self._refs and self._refs[0].path != self._node.path:
-                group = detect(self._refs[0].path.rsplit("/", 1)[0], missing_ok=True)
+            # the group the levels were discovered from, whichever path opened the pyramid
+            group = self._group
             light = light_levels(group, self.names, space) if group is not None else None
             if light is None:
                 light = [
@@ -867,7 +872,9 @@ def metadata(
     if level == "first":
         level = 0
     if node.format == "precomputed" and (level is not None or node.scale_key is not None):
-        wanted = node.scale_key if level is None else level
+        wanted = (
+            node.scale_key if node.scale_key is not None else level
+        )  # a scale path is that scale
         meta = read_meta_light(node, scale_index=precomputed_scale_index(node.docs["info"], wanted))
     elif node.kind == "group":
         refs = discover(node)

{worldarray-0.1.0 → worldarray-0.1.1}/src/worldarray/levels.py

@@ -48,8 +48,16 @@ def _probe_levels(path: str) -> list[str]:
 def discover(node: Node) -> list[LevelRef]:
     """The levels of a group node, or of the group an array node belongs to (just the array
     itself when its parent is not a multiscale group)."""
+    return discover_group(node)[1]
+
+
+def discover_group(node: Node) -> tuple[Node | None, list[LevelRef]]:
+    """``discover`` plus the node whose document lists those levels: the group itself, the
+    ancestor an array path belongs to, the precomputed ``info`` node; None for an array
+    standing alone, so a ``Pyramid`` opened through a level path still reads placements
+    from the group document instead of opening every level."""
     if node.format == "precomputed":
-        return [
+        return node, [
             LevelRef(str(s.get("key", i)), node.path, i)
             for i, s in enumerate(node.docs["info"]["scales"])
         ]
@@ -67,14 +75,14 @@ def discover(node: Node) -> list[LevelRef]:
                 and group.kind == "group"
                 and rel in _group_multiscale_paths(group)
             ):
-                return discover(group)
+                return discover_group(group)
             if parent(ancestor) is None:
                 break
             rel = f"{basename(ancestor)}/{rel}"
             ancestor = parent(ancestor)
-        return [LevelRef(basename(node.path), node.path)]
+        return None, [LevelRef(basename(node.path), node.path)]
     names = _group_multiscale_paths(node) or _probe_levels(node.path)
-    return [LevelRef(name, join(node.path, name)) for name in names]
+    return node, [LevelRef(name, join(node.path, name)) for name in names]
 
 
 def _spatial_voxel_size(level) -> np.ndarray:

{worldarray-0.1.0 → worldarray-0.1.1}/src/worldarray/placement.py

@@ -4,8 +4,8 @@ The rule everything else rests on: a **translation is the centre of voxel 0** (O
 COSEM ``transform``, CF coordinates, Neuroglancer's own zarr reader). Formats that store
 voxel 0's corner are moved half a voxel along the spatial axes on reading: precomputed's
 ``voxel_offset`` and funlib's ``offset`` (0 when only a ``resolution`` is given). N5 levels
-with ``pixelResolution`` and ``downsamplingFactors`` and no offset follow BigDataViewer: a
-downsampled voxel's centre is the centre of the block it covers (spec, Conventions 1 and 4).
+with ``downsamplingFactors`` and no offset keep their corner at the origin at every level,
+as Neuroglancer draws N5: translation ``f / 2 * base`` (spec, Conventions 1 and 4).
 
 Per-axis lists shorter than the array (a 3-entry ``voxel_size`` on a ``(c, z, y, x)``
 prediction) cover the trailing axes; the leading axes get 1.0, 0.0 or ``""``. OME lists
@@ -415,6 +415,11 @@ def _zarr(
         found = _ome(hit[0], hit[1], ndim, node.path)
     if found.voxel_size is None:
         found = _array_attrs(attrs, ndim, node.path)
+        if found.voxel_size is None and _has_funlib_keys(group_attrs):
+            # funlib's keys on the parent group, the array carrying none (mesh-n-bone's inputs)
+            axes = found.axes
+            found = _array_attrs(_funlib_subset(group_attrs), ndim, node.path)
+            found.axes = found.axes or axes
     else:
         _check_against_attrs(attrs, found, ndim, node.path, conflicts)
     if found.axes is None:
@@ -501,6 +506,21 @@ def _unpack_sequence(transforms: list[dict]) -> list[dict]:
     return out
 
 
+_FUNLIB_KEYS = ("voxel_size", "resolution", "offset", "units", "axis_names")
+
+
+def _has_funlib_keys(attrs: dict) -> bool:
+    return any(
+        isinstance(attrs.get(k), (list, tuple)) for k in ("voxel_size", "resolution", "offset")
+    )
+
+
+def _funlib_subset(attrs: dict) -> dict:
+    """Only funlib's keys of a group's attributes, so a group-level ``transform`` or ``scale``
+    (which mean other things on a group) is not taken for the array's placement."""
+    return {k: attrs[k] for k in _FUNLIB_KEYS if k in attrs}
+
+
 def _array_attrs(attrs: dict, ndim: int, path: str) -> _Resolved:
     """funlib (``resolution``/``voxel_size``, ``offset``, ``units``, ``axis_names``) or COSEM
     (``transform``) attributes on the array itself, C order. An ``offset`` with no voxel
@@ -581,12 +601,12 @@ def _check_against_attrs(
 
 def _n5(attrs: dict, group_attrs: dict, node: Node, ndim: int) -> _Resolved:
     """COSEM ``transform`` on the array; else the group's ``multiscales[].datasets[].transform``
-    for this path; else ``pixelResolution``/``resolution`` (array, else group) times the
-    level's ``downsamplingFactors``, plus ``offset``. Lists other than ``transform`` are
-    x-first and reversed to C order here. Without an ``offset``: a level with ``downsamplingFactors`` follows
-    BigDataViewer, ``(f - 1) / 2`` full-resolution voxels on, whichever key gave the base
-    (BigStitcher writes ``resolution``); a funlib ``resolution`` with no
-    ``downsamplingFactors`` means a corner at 0 (translation half a voxel)."""
+    for this path; else funlib's ``voxel_size``/``offset`` (array, else group), C order; else
+    ``pixelResolution``/``resolution`` (array, else group) times the level's
+    ``downsamplingFactors``, plus ``offset``. Lists other than ``transform`` and funlib's are
+    x-first and reversed to C order here. Without an ``offset`` the corner is at the origin
+    at every level, whichever key gave the base: translation ``f / 2 * base``, half a voxel
+    of the level, as Neuroglancer draws N5 (Convention 1)."""
     name = basename(node.path)
     transform = attrs.get("transform")
     if isinstance(transform, dict) and "scale" in transform:
@@ -596,6 +616,13 @@ def _n5(attrs: dict, group_attrs: dict, node: Node, ndim: int) -> _Resolved:
         return _cosem_transform(hit[1]["transform"], ndim, name)
 
     axes = _axes(list(attrs.get("axes", group_attrs.get("axes", [])) or [])[::-1], ndim)
+    for source in (attrs, group_attrs):
+        if isinstance(source.get("voxel_size"), (list, tuple)):
+            # funlib's own key names, which zarr-python's N5 store leaves in the array's C
+            # order (unlike resolution and pixelResolution, x-first); offset is a corner
+            found = _array_attrs(_funlib_subset(source), ndim, name)
+            found.axes = found.axes or axes
+            return found
     unit: str | None = None
     base, key = None, None
     for source in (attrs, group_attrs):
@@ -635,14 +662,12 @@ def _n5(attrs: dict, group_attrs: dict, node: Node, ndim: int) -> _Resolved:
 
     if "offset" in attrs:
         corner = _floats(list(attrs["offset"])[::-1], ndim, f"{name}: offset", pad=0.0)
-        translation = corner_to_centre(corner, voxel_size, axes)
-    elif key == "resolution" and "downsamplingFactors" not in attrs:
-        # funlib/daisy N5: a resolution with no offset is a corner at 0 (funlib never writes
-        # downsamplingFactors; BigStitcher writes "resolution" AND downsamplingFactors, and means BDV)
-        translation = corner_to_centre((0.0,) * ndim, voxel_size, axes)
     else:
-        # BigDataViewer: the downsampled voxel's centre is the centre of the block it covers
-        translation = tuple(float(v) for v in (factors - 1) / 2 * base)
+        # no stored origin: the corner at the origin at every level, as Neuroglancer draws N5
+        # (a pure scale of the base grid by downsamplingFactors). BigDataViewer centres voxel
+        # 0 on the origin instead, half a base voxel lower; the shift between levels is the same
+        corner = (0.0,) * ndim
+    translation = corner_to_centre(corner, voxel_size, axes)
     return _Resolved(axes, units, tuple(float(v) for v in voxel_size), tuple(translation), "n5")
 
 

{worldarray-0.1.0 → worldarray-0.1.1}/src/worldarray/store.py

@@ -88,6 +88,19 @@ def join(base: str, *parts: str) -> str:
 # Access
 
 
+@functools.lru_cache(maxsize=1)
+def _on_google_cloud() -> bool:
+    """A Google VM or GKE node, decided with no network call: the environment names a
+    metadata host, or the machine's DMI product name says Google."""
+    if os.environ.get("GCE_METADATA_HOST") or os.environ.get("GCE_METADATA_ROOT"):
+        return True
+    try:
+        with open("/sys/class/dmi/id/product_name") as f:
+            return f.read().strip().startswith("Google")
+    except OSError:
+        return False
+
+
 def kvstore_specs(root: str) -> list[dict]:
     """The tensorstore kvstore specs that read the directory ``root``, in the order to try
     them. ``s3://``: anonymously, then AWS's default credentials (S3 refuses even a public
@@ -109,9 +122,10 @@ def kvstore_specs(root: str) -> list[dict]:
             extra["aws_region"] = region
         return [{**spec, **extra, "aws_credentials": {"type": t}} for t in ("anonymous", "default")]
     if spec["driver"] == "gcs":
-        if GUARD_GCE_METADATA:
+        if GUARD_GCE_METADATA and not _on_google_cloud():
             # off Google Cloud, tensorstore's probe of the GCE metadata server for credentials
-            # stalls every gs:// open for seconds; point it at a name that fails at once
+            # stalls every gs:// open for seconds; point it at a name that fails at once. On a
+            # Google machine the server is real and the credentials it serves must keep working
             os.environ.setdefault("GCE_METADATA_ROOT", "metadata.google.internal.invalid")
         public = (os.environ.get("TENSORSTORE_GCS_HTTP_URL") or GCS_PUBLIC_URL).rstrip("/")
         return [

{worldarray-0.1.0 → worldarray-0.1.1}/tests/fixtures/metadata.json

@@ -104,7 +104,7 @@
       }
     },
     {
-      "name": "n5_group_pixelresolution_and_downsampling_factors_bigdataviewer",
+      "name": "n5_group_pixelresolution_and_downsampling_factors_corner_at_origin",
       "format": "n5",
       "shape": [
         4,
@@ -136,9 +136,9 @@
           8
         ],
         "translation": [
-          2,
-          2,
-          2
+          4,
+          4,
+          4
         ],
         "axes": [
           "z",
@@ -1289,7 +1289,7 @@
       }
     },
     {
-      "name": "n5_bigstitcher_resolution_with_downsampling_factors_is_bigdataviewer",
+      "name": "n5_bigstitcher_resolution_with_downsampling_factors_corner_at_origin",
       "format": "n5",
       "shape": [
         4,
@@ -1319,9 +1319,9 @@
           0.314
         ],
         "translation": [
-          0,
-          0.0785,
-          0.0785
+          0.5,
+          0.157,
+          0.157
         ],
         "axes": [
           "z",

{worldarray-0.1.0 → worldarray-0.1.1}/tests/test_access.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import os
+
 import numpy as np
 import pytest
 
@@ -192,3 +194,17 @@ def test_capped_context_can_leave_the_network_alone():
     spec = wa.capped_context_spec(concurrency=2, network=False)
     assert "s3_request_concurrency" not in spec and spec["file_io_concurrency"] == {"limit": 2}
     assert "s3_request_concurrency" in wa.capped_context_spec()
+
+
+def test_gce_guard_is_left_alone_on_a_google_machine(monkeypatch):
+    """Off Google Cloud the metadata probe is short-circuited; on a Google machine the
+    variable is left alone so the real metadata server's credentials keep working."""
+    monkeypatch.setenv("GCE_METADATA_ROOT", "remembered-for-restoration")
+    monkeypatch.delenv("GCE_METADATA_ROOT")
+    monkeypatch.delenv("GCE_METADATA_HOST", raising=False)
+    monkeypatch.setattr(store, "_on_google_cloud", lambda: True)
+    store.kvstore_specs("gs://bucket/vol")
+    assert "GCE_METADATA_ROOT" not in os.environ
+    monkeypatch.setattr(store, "_on_google_cloud", lambda: False)
+    store.kvstore_specs("gs://bucket/vol")
+    assert os.environ["GCE_METADATA_ROOT"] == "metadata.google.internal.invalid"

{worldarray-0.1.0 → worldarray-0.1.1}/tests/test_metadata.py

@@ -150,3 +150,36 @@ def test_lenient_units_take_unknown_units_as_the_target(tmp_path, caplog):
     )
     assert "nanometer" in wa.units.TABLE["length"] and "second" in wa.units.TABLE["time"]
     assert wa.open(str(group / "s0"), units=None).meta.fill_value in (None, 0)
+
+
+def test_parent_group_funlib_attrs_place_an_attribute_less_array(tmp_path):
+    """funlib's keys on the parent group, the array carrying none, zarr and N5 alike
+    (mesh-n-bone's inputs): read as on the array, offset a corner."""
+    from conftest import write_n5, write_n5_group
+
+    for fmt in ("zarr2", "n5"):
+        root = tmp_path / f"vol.{fmt}"
+        if fmt == "zarr2":
+            write_zarr2_group(root, {"voxel_size": [1, 2, 3], "offset": [4, 4, 4]})
+            write_zarr2(root / "s0", pattern((4, 4, 4)))
+        else:
+            write_n5_group(root, {"voxel_size": [1, 2, 3], "offset": [4, 4, 4]})
+            write_n5(root / "s0", pattern((4, 4, 4)))
+        meta = wa.metadata(str(root / "s0"))
+        assert meta.voxel_size == (1.0, 2.0, 3.0), fmt
+        assert meta.translation == pytest.approx((4.5, 5.0, 5.5)), fmt
+        assert meta.placed_by == "funlib", fmt
+
+
+def test_n5_array_funlib_keys_are_c_order(tmp_path):
+    """``voxel_size``/``offset`` under funlib's names on an N5 array are not reversed, unlike
+    ``resolution`` and ``pixelResolution``, because zarr-python's N5 store leaves user
+    attributes alone."""
+    from conftest import write_n5
+
+    root = tmp_path / "vol.n5"
+    write_n5(root / "s0", pattern((4, 4, 4)), attrs={"voxel_size": [1, 2, 3], "offset": [4, 4, 4]})
+    meta = wa.metadata(str(root / "s0"))
+    assert meta.voxel_size == (1.0, 2.0, 3.0)
+    assert meta.translation == pytest.approx((4.5, 5.0, 5.5))
+    assert meta.placed_by == "funlib"

{worldarray-0.1.0 → worldarray-0.1.1}/tests/test_read.py

@@ -218,13 +218,14 @@ def test_placement_agrees_across_formats(tmp_path):
         np.testing.assert_array_equal(vol.read(box), data[2:5, 2:5, 2:5], err_msg=str(path))
 
 
-def test_bigdataviewer_level_matches_ome_level(tmp_path):
+def test_n5_downsampled_level_matches_ome_level(tmp_path):
     """An N5 pyramid with pixelResolution and downsamplingFactors and no offset sits where the
-    equivalent OME pyramid (voxel 0 of s0 at the origin) puts its levels."""
+    equivalent OME pyramid with s0's corner at the origin puts its levels, as Neuroglancer
+    draws both: s0 centred at half a voxel, s1 at a whole base voxel (f / 2 * base)."""
     base, s1 = pattern((8, 8, 8)), pattern((4, 4, 4))
     ome = tmp_path / "ome.zarr"
     write_zarr2_group(
-        ome, ome_multiscales("zyx", [("s0", (4, 4, 4), (0, 0, 0)), ("s1", (8, 8, 8), (2, 2, 2))])
+        ome, ome_multiscales("zyx", [("s0", (4, 4, 4), (2, 2, 2)), ("s1", (8, 8, 8), (4, 4, 4))])
     )
     write_zarr2(ome / "s0", base)
     write_zarr2(ome / "s1", s1)
@@ -232,10 +233,12 @@ def test_bigdataviewer_level_matches_ome_level(tmp_path):
     write_n5_group(n5, {"pixelResolution": {"dimensions": [4, 4, 4], "unit": "nm"}})
     write_n5(n5 / "s0", base, attrs={"downsamplingFactors": [1, 1, 1]})
     write_n5(n5 / "s1", s1, attrs={"downsamplingFactors": [2, 2, 2]})
-    a, b = wa.open(str(ome / "s1")), wa.open(str(n5 / "s1"))
-    assert a.translation == pytest.approx(b.translation, abs=0.4)
-    box = ((6.0, 6.0, 6.0), (22.0, 22.0, 22.0))
-    np.testing.assert_array_equal(a.read(box), b.read(box))
+    for level in ("s0", "s1"):
+        a, b = wa.open(str(ome / level)), wa.open(str(n5 / level))
+        assert a.translation == pytest.approx(b.translation), level
+        assert b.corner == pytest.approx((0.0, 0.0, 0.0)), level
+        box = ((6.0, 6.0, 6.0), (22.0, 22.0, 22.0))
+        np.testing.assert_array_equal(a.read(box), b.read(box))
 
 
 def test_chunks_covering(cube):
@@ -413,7 +416,7 @@ def test_base_voxel_size_on_a_unitless_n5_pyramid_warns_about_nothing(tmp_path,
         )
     assert not [r for r in caplog.records if "no unit" in r.message]
     assert s1.voxel_size == pytest.approx((1.0, 0.314, 0.314)) and s1.translation == pytest.approx(
-        (0.0, 0.0785, 0.0785)
+        (0.5, 0.157, 0.157)  # the corner at the origin at every level
     )
 
 
@@ -699,3 +702,41 @@ def test_callables_see_the_array_without_pinned_axes_and_empty_groups_say_so(tmp
     write_zarr2_group(empty)
     with pytest.raises(ValueError, match="no levels found"):
         wa.metadata(str(empty), level="first", open=False)
+
+
+def test_precomputed_scale_path_is_that_scale_under_level_first(tmp_path):
+    """A path naming a scale is that scale, as an array path is that array; ``level=0`` and
+    ``"first"`` are silently it and any other level warns (mesh-n-bone's review)."""
+    from conftest import pattern
+
+    pre = tmp_path / "pc"
+    data = pattern((8, 8, 8))
+    write_precomputed(
+        pre,
+        [
+            {"data": data, "resolution": [4, 4, 4], "key": "4nm"},
+            {"data": data[::2, ::2, ::2], "resolution": [8, 8, 8], "key": "8nm"},
+        ],
+    )
+    for level in (None, 0, "first"):
+        vol = wa.open(str(pre / "8nm"), level=level)
+        assert (vol.level_name, vol.voxel_size) == ("8nm", (8.0, 8.0, 8.0)), level
+    light = wa.metadata(str(pre / "8nm"), level="first", open=False)
+    assert light.voxel_size == (8.0, 8.0, 8.0)
+    with pytest.warns(UserWarning, match="names a precomputed scale"):
+        assert wa.open(str(pre / "8nm"), level="4nm").level_name == "8nm"
+
+
+def test_pyramid_opened_through_a_level_path_places_from_the_group_document(pyramid):
+    """``placements`` reads the group document whichever path opened the pyramid, so a
+    level whose array is gone is still placed and nothing is opened (mesh-n-bone's review)."""
+    import shutil
+
+    group, _ = pyramid
+    expected = wa.open_pyramid(group).placements()
+    shutil.rmtree(f"{group}/s2")
+    pyr = wa.open_pyramid(f"{group}/s0")
+    assert pyr.names == ["s0", "s1", "s2"]
+    assert pyr.placements() == expected
+    assert pyr.voxel_sizes()[-1] == ("s2", (16.0, 16.0, 16.0))
+    assert pyr.translations()[-1] == ("s2", (8.0, 8.0, 8.0))

{worldarray-0.1.0 → worldarray-0.1.1}/uv.lock

@@ -1247,7 +1247,7 @@ wheels = [
 
 [[package]]
 name = "worldarray"
-version = "0.1.0"
+version = "0.1.1"
 source = { editable = "." }
 dependencies = [
     { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },

worldarray-0.1.0/CHANGELOG.md

@@ -1,13 +0,0 @@
-# Changelog
-
-## 0.1.0 (2026-10-21)
-
-- First version, built to `docs/spec.md`: open zarr v2, zarr v3, N5 and Neuroglancer
-  precomputed arrays and pyramids through tensorstore; one metadata precedence per format
-  with the voxel-centre rule for translations; index-space and world-box reads with
-  padding; level selection; nearest and linear resampling; retries; shared and capped
-  tensorstore contexts.
-  Built and trialled in one day against the readers it replaces in cellmap-flow,
-  cellmap-analyze, mesh-n-bone and chunkmirage, and checked on their own data by the
-  CineMap, liconn-err, registration-station and salamander repos; see `docs/spec.md`,
-  "Trial status". Hot-path reads cost 0.1 to 0.2 ms over a raw tensorstore read.