# Welldata Widget -- Loading Images and Stitching # What this widget does The Welldata Widget is your starting point. It connects to your OMERO server, downloads images from a specific well on a plate, and displays them in the Napari viewer complete with segmentation masks and experimental metadata. It also caches plate data to your local disk so that future loads are nearly instant. If your microscope acquired images across multiple overlapping positions (tiled acquisitions), the widget can stitch these positions together into a single, seamless composite image. # Opening the widget In Napari, go to **Plugins → Omero Screen Napari → Welldata Widget**. The widget opens as a panel on the right side of the viewer. ------------------------------------------------------------------------ # Step 1 -- Load a well ## What you need to fill in | Field | What to enter | Example | |----|----|----| | **Plate ID** | The numeric ID of your plate in OMERO | `3869` | | **Well Position** | One or more well positions, comma-separated | `A1` or `A1, B3, C5` | | **Images** | Which images to load from the well | `All`, `0`, `0, 1, 2`, or a range `3-5` | | **Time** | Timepoint index, or `All` for a time series | `0` | | **Cache** | Tick this to download the full plate to disk in the background | ☑ | Click **Enter** to start loading. ## What appears in the viewer Once loading completes: - **Fluorescence channels** are added as separate image layers with automatic colormaps: - DAPI / Hoechst → blue - Tubulin → green - EdU → red - Additional channels → magenta, cyan, yellow - **Segmentation masks** (nucleus outlines, cell outlines) are added as label layers if they were generated during the analysis pipeline. - A **metadata panel** appears showing the experimental annotations for the well (cell line, condition, timepoint, etc.). When you navigate between images or timepoints, this panel updates automatically. ## Loading multiple wells Separate well positions with commas: `A1, A2, A3`. All wells are loaded in sequence and stacked in the viewer. ------------------------------------------------------------------------ # Step 2 -- Browse the Plate Info Dialog Instead of typing well positions manually, you can open the **Plate Info Dialog** by clicking on the plate dropdown at the top of the widget. The dialog shows a table of every well in the plate with: - Well position, cell line, condition, timepoint - Number of images per well - Whether segmentation masks are available - Real-time cache download progress You can: - **Double-click any row** to load that well immediately. - **Select multiple rows** using the checkboxes and load them all at once. - **Sort and filter** the table to find wells quickly. ------------------------------------------------------------------------ # Step 3 -- Cache the plate for faster access Downloading images from OMERO every time is slow. The **Cache** feature downloads a plate to your local disk once, so subsequent loads are instant. There are two cache backends, and the widget picks one for you based on how the plate was processed: | Backend | Used when | What's stored | How loads work | |----|----|----|----| | **Disk cache** (legacy) | Plates processed in per-field mode | Raw per-image TCZYX pixels (uint16) | Pixels fetched per field at view time; stitching done in memory | | **OME-Zarr cache** | Plates processed with `--stitch` (see [stitched-mode segmentation](https://hocheggerlab.github.io/omero-screen/pipeline.html#stitched-mode-segmentation)) | Pre-stitched whole-well canvas in OME-Zarr v0.4 (NGFF) format | Lazy chunk loads straight into napari -- bounded memory, instant pan/zoom | The widget detects stitched-mode plates automatically (by looking for `_stitched_segmentation` images in the OMERO segmentation dataset) and uses OME-Zarr. Everything else uses the disk cache. ## How to cache 1. Tick the **Cache** checkbox before clicking Enter, **or** 2. Open the **Cached Plates panel** at the top of the widget and click the **Cache** button next to the plate you want, **or** 3. Open the **Plate Info dialog** (see Step 1) and click **Cache Plate** there. For OME-Zarr builds you'll see a determinate progress bar (`building D1 (0/12)` → `wrote D1 (1/12), building D2` …). Cancelling mid-build is safe -- wells already written stay on disk, and clicking Cache Plate again resumes from where it stopped. ## The Cached Plates panel | Control | What it does | |----|----| | **Plate dropdown** | Shows all locally cached plates with their status (disk or zarr) | | **Cache Size** | Total disk space used by the cache | | **Cache button** | Downloads the full plate in the background, using the right backend | | **Delete button** | Removes the cached data for a plate (clears both backends if both are present) and the per-plate OME-Zarr directory | | **Refresh button** | Rescans the cache folder (useful if you cached from another session) | The cache persists between Napari sessions -- you do not need to re-download when you restart. ## Where the caches live on disk The cache root is `~/omero-cache` by default (a *visible* folder, so the OME-Zarr stores can also be opened directly by Fiji/Mastodon). Override it with `OMERO_SCREEN_CACHE_PATH`. ~/omero-cache/ ├── images/ # disk cache: per-image TCZYX pixel blobs (diskcache + sqlite index) ├── plates/ # disk cache: plate metadata + well layout └── zarr/ # OME-Zarr cache: one plate_.zarr directory per cached plate └── registry.json # tracks last-accessed times for LRU eviction > **Note:** The default location moved from the old hidden `~/.cache/omero_screen` to the visible `~/omero-cache`. On the first run after upgrading you may see a one-time log line noting this; rebuild plates in the new location (the old folder can then be deleted), or set `OMERO_SCREEN_CACHE_PATH` to keep the old path. Size limits are configurable via environment variables: - `OMERO_SCREEN_IMAGE_CACHE_SIZE_LIMIT` (default **20 GiB**, for the legacy disk cache; raw bytes) - `OMERO_SCREEN_ZARR_MAX_GB` (default **100 GiB**, for the OME-Zarr cache; integer GiB, clamped to a 10 GiB minimum) When a new build would exceed its cap, the least-recently-accessed plate is evicted automatically. For the full set of cache environment variables, layout, and eviction/pinning rules, see the [Local Caching & Interactive Viewing](https://hocheggerlab.github.io/omero-screen/caching.html) guide. > **Tip:** For large plates (\>20 wells), start the cache download while you work on the first few wells. By the time you need the later wells, they will already be on disk. > **Tip:** If you suspect orphan files (e.g. after a crash), `rm -rf ~/omero-cache` is always safe -- all three caches rebuild on demand. ## Disk cache vs OME-Zarr -- which is "better"? For the **future direction**: OME-Zarr is the destination. Loads are dramatically lighter on memory (no in-memory stitching at view time), and the format is standard so the same data can be opened by other tools (`napari-ome-zarr`, Fiji, `ome-zarr-py`). For **today**: the disk cache covers per-field plates that haven't been re-run with `--stitch`, and is still the path used by the gallery / training widgets via per-image crops. Both backends coexist; the dispatcher chooses the right one. You don't normally need to think about this -- but if you're processing a new plate and want the fastest viewer experience, run with `--stitch` so the OME-Zarr path is available. ------------------------------------------------------------------------ # Step 4 -- Stitch tiled images (multi-position acquisitions) Some microscope setups acquire several overlapping fields of view per well, which need to be joined together to see the full well. The stitching panel handles this. ## When you need stitching If your well contains images named in a way that suggests a grid (e.g. position 1, 2, 3 … 25 for a 5×5 grid), or if the metadata indicates a tiled acquisition, use stitching. ## Stitching parameters | Parameter | Default | What it controls | |----|----|----| | **Stitch** | on | Whether to stitch the loaded fields into a single canvas. | | **Overlap X / Y** | 7 | Tile overlap in **pixels** along each axis. Match this to your microscope's acquisition overlap. | | **Translate X / Y** | −3 / 3 | Fine pixel offset applied between tiles to correct small residual misalignment (range −20…20). | | **Edge** | 7 | Edge-blending width in **pixels** at tile seams, to hide illumination steps. | After loading your well, fill in the stitching parameters and click **Enter** in the stitching panel. The stitched composite appears as a new layer in the viewer. > **Tip:** If the stitched image looks misaligned, nudge **Translate X / Y** by 1-2 pixels at a time, then adjust **Overlap X / Y** if seams remain. These defaults match typical Operetta/Opera acquisitions. ------------------------------------------------------------------------ # Tips and common questions **Q: The images look very dim.** A: Use napari's contrast controls (the coloured bar on each layer) to adjust brightness. The images are stored at full bit depth -- napari's auto-scaling sometimes sets a conservative range. **Q: No segmentation masks appear.** A: Masks are only shown if your plate was processed through the omero-screen analysis pipeline. If you only have raw images, the masks will not be available. **Q: I see "Plate not found" error.** A: Double-check the Plate ID in OMERO.web. The ID is the number shown in the plate URL or in the left-hand tree. **Q: Can I load images without an OMERO connection?** A: Yes, if the plate is already cached locally. Cached plates load without any server connection.