@@ -6,6 +6,8 @@
 
 version: 2
 updates:
+  # Cooldown docs:
+  # https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference
   # GitHub Actions checks
   # See here for more information:
   # https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates
@@ -14,16 +16,48 @@ updates:
     schedule:
       # Check for updates to GitHub Actions every month
       interval: "monthly"
+    cooldown:
+      default-days: 7
+    groups:
+      github-actions:
+        patterns:
+          - "*"
 
-  # Perform checks and updates for python poetry environment.
+  # Perform checks and updates for python uv environment.
+  # This depends on changes to dependabot via:
+  # https://github.com/dependabot/dependabot-core/pull/10040
   # See here for more information:
   # https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#pip-and-pip-compile
-  - package-ecosystem: "pip"
+  - package-ecosystem: "uv"
     directory: "/"
     schedule:
-      # Check for updates to poetry lockfile every month
+      # Check for updates to uv environment files every month
       interval: "monthly"
+    cooldown:
+      default-days: 7
+      semver-major-days: 14
+      semver-minor-days: 7
+      semver-patch-days: 3
     groups:
       python-packages:
         patterns:
           - "*"
+
+  # Perform checks and updates for pre-commit hook versions.
+  # Replaces the pre-commit-update pre-commit hook (removed): that hook
+  # rewrote .pre-commit-config.yaml mid-run inside every prek/pre-commit
+  # invocation (including in CI), so a newer, stricter tool version could
+  # fail lint on code nobody had touched, in the same run that just bumped
+  # it -- and CI would then auto-commit that bump back to the PR branch.
+  # Dependabot opens a normal, reviewable PR for hook version bumps instead.
+  - package-ecosystem: "pre-commit"
+    directory: "/"
+    schedule:
+      # Check for updates to pre-commit hooks every month
+      interval: "monthly"
+    cooldown:
+      default-days: 7
+    groups:
+      pre-commit-hooks:
+        patterns:
+          - "*"
@@ -4,9 +4,9 @@ name: tests
 
 "on":
   push:
-    branches: [main]
+    branches: [main, 0.3.x]
   pull_request:
-    branches: [main]
+    branches: [main, 0.3.x]
 
 jobs:
   pre_commit_checks:
@@ -23,6 +23,14 @@ jobs:
           python-version: "3.11"
       - name: Install the latest version of uv
         uses: astral-sh/setup-uv@v7
+      # VTK/pyvista's built-in headless (EGL/OSMesa) off-screen rendering
+      # path has been unreliable on ubuntu-24.04 runners here (intermittent
+      # segfaults inside plotter.render() partway through the suite, never
+      # reproduced on macOS runners or locally). A real Xvfb virtual
+      # framebuffer is pyvista's own documented, far more heavily tested
+      # recommendation for headless Linux CI rendering.
+      - name: Setup headless display
+        uses: pyvista/setup-headless-display-action@v5
       # run pre-commit
       - uses: pre-commit/action@v3.0.1
         id: pre_commit
@@ -46,6 +54,12 @@ jobs:
           python-version: ${{ matrix.python_version }}
       - name: Install the latest version of uv
         uses: astral-sh/setup-uv@v7
+      # See the same step in pre_commit_checks above for why: VTK/pyvista's
+      # built-in headless off-screen rendering has segfaulted intermittently
+      # on ubuntu-24.04 runners; a real Xvfb display is the documented fix.
+      - name: Setup headless display
+        if: ${{ runner.os == 'Linux' }}
+        uses: pyvista/setup-headless-display-action@v5
       - name: Run pytest (non-3.13)
         if: ${{ matrix.python_version != '3.13' }}
         # run all tests
 
@@ -15,7 +15,7 @@ repos:
     -   id: check-yaml
     -   id: detect-private-key
 -   repo: https://github.com/tox-dev/pyproject-fmt
-    rev: "v2.29.3"
+    rev: "v2.29.4"
     hooks:
     -   id: pyproject-fmt
 -   repo: https://github.com/codespell-project/codespell
@@ -58,11 +58,6 @@ repos:
     rev: v0.1.17
     hooks:
     -   id: almanack-check
--   repo: https://gitlab.com/vojko.pribudic.foss/pre-commit-update
-    rev: v0.6.0
-    hooks:
-    -   id: pre-commit-update
-        args: ["--keep", "mdformat", "--keep", "pre-commit-update", "--keep", "cffconvert"]
 -   repo: local
     hooks:
     -   id: code-cov-gen
 
@@ -0,0 +1,163 @@
+# ---
+# jupyter:
+#   jupytext:
+#     formats: ipynb,py:light
+#     text_representation:
+#       extension: .py
+#       format_name: light
+#       format_version: '1.5'
+#       jupytext_version: 1.19.1
+#   kernelspec:
+#     display_name: CytoDataFrame (3.13.5.final.0)
+#     language: python
+#     name: python3
+# ---
+
+# # NF1 3D pilot cropped voxel view
+#
+# View real 3D single-cell crops (with mask overlays) from two NF1 wells in one `CytoDataFrame`.
+#
+# Most of the setup below isn't about `CytoDataFrame` -- it's working around this
+# data's layout, which doesn't look like typical CellProfiler output:
+#
+# - There are no `Image_FileName_*`/`Image_PathName_*` columns, so each row's raw
+#   image path is built from the patient/well/field metadata (`load_image_set`).
+# - Every well's mask file has the exact same generic name (`nuclei_mask.tiff`),
+#   so combining two wells into one table needs `stage_mask` to tell them apart
+#   -- a single-well notebook wouldn't need this at all.
+#
+# The actual `CytoDataFrame(...)` call at the end is just a handful of arguments.
+
+# +
+import os
+import pathlib
+import re
+import tempfile
+
+import pandas as pd
+
+from cytodataframe import CytoDataFrame
+
+# Local mount point for bandicoot. Set BANDICOOT_LOCAL_BASE if it is mounted
+# somewhere else on your machine.
+BANDICOOT_LOCAL_BASE = pathlib.Path(
+    os.environ.get("BANDICOOT_LOCAL_BASE", "~/mnt/bandicoot")
+).expanduser()
+DATA_DIR = BANDICOOT_LOCAL_BASE / "NF1_organoid_data/data"
+PROFILES_DIR = (
+    DATA_DIR / "image_based_profiles_production_zedprofiler/ibp/sc_profiles_related"
+)
+if not PROFILES_DIR.is_dir():
+    raise FileNotFoundError(
+        f"Profiles not found at {PROFILES_DIR}. Set the BANDICOOT_LOCAL_BASE "
+        "environment variable to wherever bandicoot is mounted on this machine."
+    )
+
+# An "image set" here is one well + field-of-view (one 3D image). Add every
+# image set you want to view to this list -- e.g. all wells/fields in a
+# plate for per-plate QC -- not just the two shown here.
+IMAGE_SETS = [
+    "NF0055_T1__NF0055_T1__B10__F1",
+    "NF0014_T1__NF0014_T1__C4__F2",
+]
+CHANNEL = "DNA"
+CHANNEL_CODE = "405"
+COMPARTMENT = "Nuclei"
+
+# Every well's mask file has the same generic name (e.g. "nuclei_mask.tiff"),
+# but CytoDataFrame's data_mask_context_dir only matches masks by filename
+# pattern within one shared directory -- it can't tell two identically-named
+# files in different wells apart. MASK_LINK_DIR is a scratch directory (not
+# part of the repo) that `stage_mask` below fills with per-well symlinks to
+# the real mask files, renamed to embed each well's own identifier, so that
+# matching works.
+MASK_LINK_DIR = pathlib.Path(tempfile.gettempdir()) / "cytodataframe_nf1_3d_mask_links"
+MASK_LINK_DIR.mkdir(exist_ok=True)
+
+
+def load_image_set(image_set: str) -> tuple[pd.DataFrame, pathlib.Path, pathlib.Path]:
+    profiles = pd.read_parquet(PROFILES_DIR / f"{image_set}.parquet").head(1)
+    row = profiles.iloc[0]
+    patient = row["Metadata_Biology_PatientTumor"]
+    # e.g. B10-1
+    well_field = (
+        f"{row['Metadata_Experiment_WellID']}-{row['Metadata_Imaging_FieldID']}"
+    )
+
+    channel_path = (
+        DATA_DIR
+        / patient
+        / "zstack_images"
+        / well_field
+        / f"{well_field}_{CHANNEL_CODE}.tif"
+    )
+    mask_path = (
+        DATA_DIR
+        / patient
+        / "segmentation_masks"
+        / well_field
+        / f"{COMPARTMENT.lower()}_mask.tiff"
+    )
+    profiles[f"Image_FileName_{CHANNEL}"] = str(channel_path)
+    return profiles, channel_path, mask_path
+
+
+def stage_mask(channel_path: pathlib.Path, mask_path: pathlib.Path) -> pathlib.Path:
+    # See MASK_LINK_DIR above for why this exists.
+    link = MASK_LINK_DIR / f"{channel_path.stem}__{mask_path.name}"
+    if not link.exists():
+        link.symlink_to(mask_path)
+    return link
+
+
+# -
+
+# Load one object per well into a single two-row table.
+
+# +
+profile_rows = []
+for image_set in IMAGE_SETS:
+    profiles, channel_path, mask_path = load_image_set(image_set)
+    stage_mask(channel_path, mask_path)
+    profile_rows.append(profiles)
+
+profiles = pd.concat(profile_rows, ignore_index=True)
+mask_name = mask_path.name
+
+# +
+bbox_column_map = {
+    "x_min": f"{COMPARTMENT}_NoChannel_VolumeSizeShape_MinX",
+    "x_max": f"{COMPARTMENT}_NoChannel_VolumeSizeShape_MaxX",
+    "y_min": f"{COMPARTMENT}_NoChannel_VolumeSizeShape_MinY",
+    "y_max": f"{COMPARTMENT}_NoChannel_VolumeSizeShape_MaxY",
+    "z_min": f"{COMPARTMENT}_NoChannel_VolumeSizeShape_MinZ",
+    "z_max": f"{COMPARTMENT}_NoChannel_VolumeSizeShape_MaxZ",
+}
+
+center_columns = [
+    f"{COMPARTMENT}_NoChannel_VolumeSizeShape_Center{axis}" for axis in "XYZ"
+]
+
+voxel_view = CytoDataFrame(
+    data=profiles[[f"Image_FileName_{CHANNEL}"]],
+    data_bounding_box=profiles[list(bbox_column_map.values())],
+    compartment_center_xy=profiles[center_columns],
+    data_mask_context_dir=str(MASK_LINK_DIR),
+    segmentation_file_regex={rf"__{re.escape(mask_name)}$": r"_\d+\.tif$"},
+    display_options={
+        "width": 260,
+        "height": 260,
+        "table_max_height": "580px",
+        "label_overlay_mode": "filled",
+        # Voxel size (x, y, z) in um. These TIFFs carry no voxel-size
+        # metadata, and z is coarser than xy, so without this the objects are
+        # drawn too flat. xy_spacing (0.1) is the NF1 3D pipeline manifests'
+        # recorded value; z_spacing (0.5) was chosen visually against these
+        # two objects rather than read from the manifests (which record 1.0).
+        "volume_spacing": (0.1, 0.1, 0.5),
+        "volume_bbox_column_map": bbox_column_map,
+    },
+)
+# The rendered widget includes a "Mask" checkbox to toggle the overlay on/off,
+# and a red dot marking each object's center.
+voxel_view
@@ -34,9 +34,23 @@ dependencies = [
   "pyvista>=0.46.4",
   "pywavelets>1.4.1",
   "scikit-image>0.19.3",
+  # tifffile+zarr enable a lazy, windowed read of a per-object 3D bounding
+  # box (see `_try_lazy_windowed_tiff_crop`): only the object's own
+  # z-planes/window are read from a plain TIFF z-stack, instead of decoding
+  # the whole (often hundreds-of-MB) volume just to crop it down afterward.
+  # Without these, 3D volumes still load correctly via the existing eager
+  # `imageio` read -- just slower for large field-of-view TIFFs. tifffile
+  # dropped Zarr 2 support for its zarr-store integration in 2025.5.21 (an
+  # older zarr paired with a newer tifffile breaks the lazy path entirely,
+  # rather than just falling back to the eager read), and 2026.4.11 was its
+  # last release still supporting Python 3.11 (required below); a later
+  # tifffile also starts requiring zarr>=3.2.0, which itself needs
+  # Python>=3.12, so staying under that keeps 3.11 support intact.
+  "tifffile>=2025.5.21,<2026.4.11",
   "trame>=3.12",
   "trame-vtk>=2.10",
   "trame-vuetify>=3.1",
+  "zarr>=3",
 ]
 
 [dependency-groups]
@@ -53,6 +67,12 @@ dev = [
   "poethepoet>=0.37,<0.49",
   "pytest>=8.3.3,<10",
   "pytest-cov>=5,<8",
+  # Pinned to match .pre-commit-config.yaml's ruff-pre-commit rev. ruff was
+  # not previously a declared project dependency at all, so `uv run ruff`
+  # silently fell through to an unrelated, unpinned `ruff` found elsewhere
+  # on PATH (a pyenv shim, in practice) -- giving different lint results
+  # locally than prek/CI's pinned hook used, depending on which one you ran.
+  "ruff==0.16.5",
   "sqlalchemy>=1.3.6,<3",
 ]
 docs = [
@@ -114,7 +134,7 @@ lint.per-file-ignores."docs/src/examples/*.py" = [ "E402", "E501" ]
 lint.per-file-ignores."src/cytodataframe/*.py" = [ "ANN401", "PLC0415" ]
 lint.per-file-ignores."src/cytodataframe/image.py" = [ "PLR2004" ]
 # ignore typing rules for tests
-lint.per-file-ignores."tests/*" = [ "ANN201", "PLR0913", "PLR2004", "SIM105" ]
+lint.per-file-ignores."tests/*" = [ "ANN201", "PLR0913", "PLR0917", "PLR2004", "SIM105" ]
 
 # specify where version replacement is performed
 [tool.bandit]