arrayview 0.38.1__tar.gz → 0.40.0__tar.gz

{arrayview-0.38.1 → arrayview-0.40.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arrayview
-Version: 0.38.1
+Version: 0.40.0
 Summary: Fast multi-dimensional array viewer
 Project-URL: Home, https://github.com/oscarvanderheide/arrayview
 Project-URL: Source, https://github.com/oscarvanderheide/arrayview
@@ -43,7 +43,10 @@ Arrayview lets you scroll through multi-dimensional arrays.
 
 Open it from the shell, from Python, Julia, or Matlab, or inside a Jupyter notebook. Use it locally or over SSH. 
 
-If you work in VS Code, you can open arrays directly from the explorer; with Remote SSH, it works the same way.
+If you work in VS Code, you can open arrays directly from the explorer — click an
+array file, or right-click a folder and choose **Open Folder in ArrayView** to
+review a DICOM series or a whole directory of arrays as one stack. With Remote
+SSH or a tunnel, it works the same way.
 
 It is meant to feel simple but there's more to it than meets the eye. 
 

{arrayview-0.38.1 → arrayview-0.40.0}/README.md

@@ -6,7 +6,10 @@ Arrayview lets you scroll through multi-dimensional arrays.
 
 Open it from the shell, from Python, Julia, or Matlab, or inside a Jupyter notebook. Use it locally or over SSH. 
 
-If you work in VS Code, you can open arrays directly from the explorer; with Remote SSH, it works the same way.
+If you work in VS Code, you can open arrays directly from the explorer — click an
+array file, or right-click a folder and choose **Open Folder in ArrayView** to
+review a DICOM series or a whole directory of arrays as one stack. With Remote
+SSH or a tunnel, it works the same way.
 
 It is meant to feel simple but there's more to it than meets the eye. 
 

{arrayview-0.38.1 → arrayview-0.40.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arrayview"
-version = "0.38.1"
+version = "0.40.0"
 description = "Fast multi-dimensional array viewer"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.12"

arrayview-0.40.0/src/arrayview/_diagnostics.py

@@ -0,0 +1,211 @@
+"""Turn a launch failure into a concise, actionable terminal message.
+
+One line saying what went wrong, one line saying what to do about it. The
+severity colour is the signal that matters:
+
+    orange  something you can clear yourself right now — reload the window,
+            run it again, kill a stale server
+    red     something that needs a real change — the file, the arrays, or a
+            bug worth a traceback
+
+`SETUP` is the exception to all of that: the run before it *worked*, and the
+only thing left is a step the user has to take by hand. Nothing went wrong, so
+it is not written as though something did — no "failed to open" headline, no
+traceback hint, and none of the raw internal text.
+
+The patterns below are matched against the message text the opener and the
+backend actually produce; they are taken from observed failures rather than
+invented, so a new failure string falls through to the red catch-all with a
+`--trace` hint rather than being mislabelled as harmless.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+
+ACTION = "action"   # orange — user can clear it
+FATAL = "fatal"     # red — needs a real fix
+SETUP = "setup"     # orange — nothing failed; one manual step is outstanding
+
+_RESET = "\033[0m"
+_RED = "\033[1;31m"
+_ORANGE = "\033[1;38;5;208m"
+_DIM = "\033[2m"
+
+_RELOAD = 'Reload the VS Code window (Ctrl/Cmd+Shift+P → "Developer: Reload Window").'
+_RETRY = "Run the same command again."
+
+# (pattern, severity, what happened, what to do)
+_DIAGNOSES: list[tuple[str, str, str, str]] = [
+    # ── First run after the opener is installed — not a failure ───────────
+    # Must stay ahead of the stale-opener pattern below: the local wording
+    # ("reload this VS Code window once, then retry") matches both, and a
+    # just-installed opener is not a stale one.
+    (r"opener was installed|installed its vs ?code opener|"
+     r"updated its vs ?code opener", SETUP,
+     "The VS Code opener is installed.",
+     'Reload this VS Code window once (Ctrl/Cmd+Shift+P → "Developer: Reload '
+     'Window"), then run the same command again.'),
+
+    # ── Opener/extension state — all clearable ────────────────────────────
+    (r"stale arrayview opener|reload this vs ?code window", ACTION,
+     "This VS Code window is running an older ArrayView opener than the one "
+     "installed.",
+     _RELOAD),
+    (r"another arrayview backend now owns this port", ACTION,
+     "A newer launch took over the port, so the session this tab wanted is "
+     "gone.",
+     _RETRY),
+    (r"required extension|extension version|opener v\d", ACTION,
+     "The installed opener and the Python package disagree on version.",
+     _RELOAD + "  If it persists: uv tool install --reinstall arrayview"),
+
+    # ── Transport — the route, not the data ───────────────────────────────
+    (r"backend stopped answering", ACTION,
+     "The route to the backend stopped answering before the viewer was ready "
+     "(usually a cold tunnel, not a dead server).",
+     _RETRY + "  If it repeats, reload the VS Code window."),
+    (r"could not connect to the arrayview backend|ws-open", ACTION,
+     "The viewer loaded but its WebSocket never connected.",
+     _RELOAD + "  If it persists, the port is blocked or the tunnel is down."),
+    (r"viewer route stopped answering|route .*not answering", ACTION,
+     "The forwarded route stopped answering; the backend itself is likely "
+     "fine.",
+     _RETRY),
+
+    # ── Timing — slow, not broken ─────────────────────────────────────────
+    (r"did not render a frame|did not become ready|did not start the viewer",
+     ACTION,
+     "The viewer opened but showed no frame before the deadline — usually a "
+     "slow first load.",
+     _RETRY + "  If the same file always does this, it may be too large to "
+     "render in one go."),
+    (r"panel closed before|closed before its first frame", ACTION,
+     "The viewer tab was closed (or replaced by a preview tab) before it "
+     "rendered.",
+     _RETRY + "  Leave the tab open while it loads."),
+    (r"signal expired|expired before a panel|hard timeout after", ACTION,
+     "The opener was still busy with an earlier request and this one aged "
+     "out.",
+     _RETRY),
+
+    # ── Ports and stale processes ─────────────────────────────────────────
+    (r"could not find a free port|no free arrayview port|address already in use",
+     ACTION,
+     "No free port was available — earlier ArrayView servers are probably "
+     "still running.",
+     "See them with `arrayview instances`, clear them with `arrayview stop`, "
+     "then retry."),
+    (r"could not register the session|registration", ACTION,
+     "The server started but the session could not be registered.",
+     _RETRY + "  If it repeats: arrayview stop, then try again."),
+
+    # ── The data itself — a real change is needed ─────────────────────────
+    (r"pickled \(object\) data|allow_pickle", FATAL,
+     "This .npy holds pickled Python objects, not a plain array.",
+     "Load it yourself and pass the array, or re-save with "
+     "np.save(..., arr) on a numeric array."),
+    (r"could not open this file|no data left in file|failed to load|"
+     r"cannot load|unsupported file", FATAL,
+     "The file could not be read as an array.",
+     "Check the path and that the file is complete and not truncated."),
+    (r"dtype mismatch", FATAL,
+     "The arrays you passed have different dtypes.",
+     "Compare needs matching dtypes — convert one before loading."),
+    (r"shape mismatch|expected \(|spatial shape|shapes? .*differ", FATAL,
+     "The arrays you passed have incompatible shapes.",
+     "Compare needs matching spatial shapes — check both files."),
+    (r"cannot start server", FATAL,
+     "The backend server could not start at all.",
+     "Re-run with --trace for the underlying error."),
+
+    # ── Bad arguments, caught before anything starts ──────────────────────
+    (r"file not found", FATAL,
+     "That file does not exist.",
+     "Check the path — and that the share it lives on is mounted."),
+    (r"not a directory", FATAL,
+     "That path is not a directory.",
+     "Point --stack at a directory of arrays."),
+    (r"invalid vector ?field", FATAL,
+     "The vector field file could not be used with this array.",
+     "It needs the array's spatial shape plus a trailing components axis."),
+    (r"could not discover masks|could not match collection", FATAL,
+     "The pattern matched no files.",
+     "Check the pattern and run with --dry-run to see what it resolves to."),
+    (r"invalid launch request", FATAL,
+     "The launch arguments did not form a valid request.",
+     "Re-run with --diagnose to see how the launch was planned."),
+]
+
+_COMPILED = [(re.compile(p, re.I), sev, what, fix) for p, sev, what, fix in _DIAGNOSES]
+
+
+def _colour_enabled(stream) -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("ARRAYVIEW_FORCE_COLOR"):
+        return True
+    return bool(getattr(stream, "isatty", lambda: False)())
+
+
+def diagnose(message: str) -> tuple[str, str, str]:
+    """Classify a failure message → (severity, what happened, what to do)."""
+    text = (message or "").strip()
+    for pattern, severity, what, fix in _COMPILED:
+        if pattern.search(text):
+            return severity, what, fix
+    return (
+        FATAL,
+        "ArrayView failed to open the display.",
+        "Re-run with --trace (or ARRAYVIEW_TRACE=1) for the full traceback.",
+    )
+
+
+def format_failure(message: str, *, colour: bool = True) -> str:
+    """Render the diagnosis as the block printed to stderr."""
+    severity, what, fix = diagnose(message)
+    detail = (message or "").strip().removeprefix("[ArrayView] ").rstrip()
+    head = (_RED if severity == FATAL else _ORANGE) if colour else ""
+    dim = _DIM if colour else ""
+    end = _RESET if colour else ""
+    lines = [
+        f"{head}[ArrayView] {what}{end}",
+        f"{head}  → {fix}{end}",
+    ]
+    # A pending setup step is not a failure report: the instruction is the
+    # whole message. Echoing the internal wording underneath it is what made
+    # "the opener is installed, reload once" read like something broke.
+    if severity == SETUP:
+        return "\n".join(lines)
+    # Keep the raw text when it says more than the headline does.
+    if detail and detail.lower() not in what.lower():
+        lines.append(f"{dim}  ({detail}){end}")
+    return "\n".join(lines)
+
+
+def print_failure(message: str, stream=None) -> None:
+    stream = stream if stream is not None else sys.stderr
+    print(format_failure(message, colour=_colour_enabled(stream)), file=stream)
+
+
+def format_notice(message: str, *, colour: bool = True) -> str:
+    """Render a one-line ACTION notice.
+
+    Same orange as an ACTION failure, because it carries the same meaning —
+    something the user asked for is not happening — but the launch continues,
+    so there is no cause/fix block to print.
+    """
+    head = _ORANGE if colour else ""
+    end = _RESET if colour else ""
+    return f"{head}[ArrayView] {message}{end}"
+
+
+def print_notice(message: str, stream=None) -> None:
+    stream = stream if stream is not None else sys.stdout
+    print(
+        format_notice(message, colour=_colour_enabled(stream)),
+        file=stream,
+        flush=True,
+    )

{arrayview-0.38.1 → arrayview-0.40.0}/src/arrayview/_io.py

@@ -1290,12 +1290,47 @@ def load_dir_collection(
     return data, spatial_meta, overlay_items, summary
 
 
+def _dicom_series_collection(path, *, load="lazy", stack="auto"):
+    """Stack a directory holding several DICOM series, one case per series.
+
+    Right-clicking a study folder in the VS Code Explorer hands over the parent
+    of a set of per-case DICOM folders. There is no single series to show, and
+    ``--series`` is unreachable from that gesture, so the load failed with
+    "Multiple DICOM series found ... Select one with --series INDEX". Build the
+    collection instead: one stack element per series, which is what "open this
+    folder" means for that layout.
+
+    Grouping by series rather than by subfolder is what the DICOM headers
+    actually say. It gives the same answer for the usual one-series-per-folder
+    layout and a better one when a folder holds two series or a series is split
+    across folders.
+
+    Returns ``None`` when the directory holds a single series: the ordinary
+    one-series load handles that and keeps its spatial metadata, which a
+    stacked collection cannot carry.
+    """
+    from ._dicom import discover_dicom_series
+
+    series = discover_dicom_series(path)
+    if len(series) < 2:
+        return None
+    # One member per series is enough to name it: loading any slice of a DICOM
+    # series loads the whole series it belongs to.
+    return _series_from_file_matrix(
+        [[item["headers"][0].path] for item in series], load=load, stack=stack
+    )
+
+
 def _load_file_series(path, *, load="lazy", stack="auto"):
     """Build a lazy series from a directory of supported array files.
 
-    Walks *path* recursively, groups files of any supported format by
-    immediate parent folder (= patient).  Requires exactly one file per
-    patient → 4D ``(*vol, P)``.
+    Walks *path* recursively and groups files of any supported format by
+    immediate parent folder (= patient).
+
+    One file per patient folder → 4D ``(*vol, P)``.  When a folder holds
+    several arrays side by side there is no per-folder case to key on, so every
+    file becomes its own case — the same collection ``--stack`` builds for that
+    directory.
 
     If every file is NIfTI (.nii/.nii.gz), delegates to
     ``_load_nifti_series`` for canonical reorientation.  Otherwise builds
@@ -1304,6 +1339,8 @@ def _load_file_series(path, *, load="lazy", stack="auto"):
     Returns ``(series, spatial_meta)``.
     """
     # ── collect files by parent directory ──────────────────────────
+    from ._dicom import is_dicom_source
+
     patients: dict[str, list[str]] = {}
     all_nifti = True
 
@@ -1312,6 +1349,14 @@ def _load_file_series(path, *, load="lazy", stack="auto"):
             os.path.join(root, f)
             for f in files
             if _get_ext(f) in _SUPPORTED_EXTS
+            # ".dcm" is necessary but not sufficient — every other .dcm
+            # consumer (load_data, load_data_with_meta, _peek_file_shape's
+            # directory branch) validates via is_dicom_source before
+            # treating a file as real DICOM. Do the same here, otherwise a
+            # stray file that merely has a .dcm extension gets counted as a
+            # patient's series member and blows up load_data() downstream
+            # instead of being silently ignored like any other unsupported file.
+            if _get_ext(f) != ".dcm" or is_dicom_source(os.path.join(root, f))
         )
         if supported:
             patients[root] = supported
@@ -1327,24 +1372,24 @@ def _load_file_series(path, *, load="lazy", stack="auto"):
             f"Supported: {', '.join(sorted(_SUPPORTED_EXTS))}"
         )
 
+    # A folder holding several arrays side by side is a flat collection: one
+    # case per file. This used to raise and tell the user to retype the command
+    # with --stack, which made "open this folder" unreachable from any caller
+    # that can only hand over a path (VS Code Explorer, drag-and-drop, the
+    # /load route). Route it through the same builder --stack uses so both
+    # spellings produce the same session instead of one of them failing.
+    if any(len(files) != 1 for files in patients.values()):
+        flat = sorted(fpath for files in patients.values() for fpath in files)
+        return _series_from_file_matrix(
+            [[fpath] for fpath in flat], load=load, stack=stack
+        )
+
     # NIfTI-only → preserve canonical reorientation + lazy dataobj slicing
     if all_nifti:
         return _load_nifti_series(path, load=load, stack=stack)
 
     # ── build file matrix ──────────────────────────────────────────
-    patient_dirs = sorted(patients.keys())
-    file_matrix: list[list[str]] = []
-
-    for pdir in patient_dirs:
-        files = patients[pdir]
-        if len(files) == 1:
-            file_matrix.append([files[0]])
-        else:
-            raise ValueError(
-                f"Folder {pdir!r} contains {len(files)} files: "
-                f"{[os.path.basename(f) for f in files]}. "
-                "Use --stack with explicit file patterns for multi-file folders."
-            )
+    file_matrix = [[patients[pdir][0]] for pdir in sorted(patients)]
 
     return _series_from_file_matrix(file_matrix, load=load, stack=stack)
 
@@ -1476,9 +1521,20 @@ def load_data_with_meta(filepath, key=None, *, load="lazy", stack="auto", select
     """
     from ._dicom import is_dicom_source, load_dicom_series
 
-    if (os.path.isdir(filepath) or filepath.lower().endswith(".dcm")) and is_dicom_source(filepath):
+    # A ".zarr" store is itself a directory on disk. It must be excluded from
+    # the generic "directory of files to stack" path below, or the walk finds
+    # nothing matching a supported single-file extension inside it (zarr's own
+    # chunk/metadata files don't) and raises instead of opening the store.
+    is_zarr_dir = os.path.isdir(filepath) and _get_ext(filepath) == ".zarr"
+    if (
+        (os.path.isdir(filepath) and not is_zarr_dir) or filepath.lower().endswith(".dcm")
+    ) and is_dicom_source(filepath):
+        if os.path.isdir(filepath) and select is None:
+            collection = _dicom_series_collection(filepath, load=load, stack=stack)
+            if collection is not None:
+                return collection
         return load_dicom_series(filepath, select=select)
-    if os.path.isdir(filepath):
+    if os.path.isdir(filepath) and not is_zarr_dir:
         return _load_file_series(filepath, load=load, stack=stack)
     if filepath.endswith(".nii") or filepath.endswith(".nii.gz"):
         return _load_nifti_with_meta(filepath)
@@ -1491,7 +1547,7 @@ def load_data(filepath, key=None):
 
         data, _meta = load_dicom_series(filepath)
         return data
-    if os.path.isdir(filepath):
+    if os.path.isdir(filepath) and _get_ext(filepath) != ".zarr":
         from ._dicom import is_dicom_source, load_dicom_series
 
         if is_dicom_source(filepath):
@@ -1592,6 +1648,16 @@ def load_data(filepath, key=None):
                 "Select one in the viewer or pass a key."
             )
     else:
+        # DICOM files routinely carry no extension at all. Every path that
+        # reaches here by extension has already been ruled out, so a header
+        # read is cheap and is the only thing that can still recognise one —
+        # this is how a per-series representative path from
+        # `_dicom_series_collection` resolves back to its series.
+        from ._dicom import is_dicom_source, load_dicom_series
+
+        if os.path.isfile(filepath) and is_dicom_source(filepath):
+            data, _meta = load_dicom_series(filepath)
+            return data
         raise ValueError(
             "Unsupported format. Supported: .npy, .npz, .nii/.nii.gz, .zarr, "
             ".pt/.pth, .h5/.hdf5, .tif/.tiff, .mat"
@@ -1646,6 +1712,13 @@ FULL_LOAD_EXTS = frozenset([".pt", ".pth", ".tif", ".tiff", ".mat"])
 def _peek_file_shape(fpath: str, ext: str):
     """Try to return shape quickly without loading the full array. Returns None on failure."""
     try:
+        # ".zarr" stores are directories, but they're a single array, not a
+        # collection to walk and stack — read metadata via zarr, not the
+        # directory-of-files branch below.
+        if ext in (".zarr", ".zarr.zip"):
+            import zarr
+
+            return list(zarr.open(fpath, mode="r").shape)
         if os.path.isdir(fpath):
             from ._dicom import is_dicom_source, load_dicom_series