matlab-process-large-images

## When to Use
- Writing code that creates, processes, or visualizes `blockedImage` objects
- Implementing `images.blocked.Adapter` subclasses for custom file formats
- User needs help with large image data that doesn't fit in memory
- User wants to leverage parallel computing for image processing tasks
- Working with whole-slide images, geospatial rasters, 3D microscopy volumes, or tiled mosaics
- **Any time a user is working with a TIFF file** — load this skill and check the file first with `imfinfo`. Use `blockedImage` if the file is large (dimensions > 10,000 pixels in any axis), has multiple channels beyond RGB, or contains multiple IFDs (could be pyramid levels, time series, or Z-stack slices)

## When NOT to Use
- Image fits comfortably in memory and no parallel processing is needed — use standard `imread`/`imwrite` workflows
- General image display without `blockedImage` — use the `matlab-display-image` skill instead
- Deep learning model architecture or training loop design — this skill covers data preparation with `blockedImageDatastore`, not network design

# Large Image Processing with blockedImage

**Reference files** (read on demand when the topic comes up):
- `references/visualization.md` — imageshow, overlays, synced views, overview+detail, annotations
- `references/training-and-labeling.md` — Image Labeler, labeled blockedImages, training datastores, DL inference
- `references/3d-volumes.md` — 3D blocked images, 3D inference, 3D training data
- `references/geospatial.md` — GeoTIFF, shapefiles, coordinate systems, spatial referencing
- `references/data-discovery.md` — 7-step data discovery workflow, custom adapters, format conversion adapter selection, virtual composite adapters, adapter performance tips
- `references/specialized-workflows.md` — writing block-by-block, coordinate systems, mask-based block selection, ExtraImages for pixel-level masking, in-place resume
- `references/whole-slide-images.md` — importing WSI files via OpenSlide/Bio-Formats, choosing between libraries, display, downstream processing (segmentation, classification)

## When to use blockedImage
blockedImage is not only for data that exceeds RAM. Even when the data fits in memory, wrapping it as a blockedImage lets you harness a parallel cluster: each worker can independently read and write different blocks, enabling parallel partial reads and parallel writes into separate file blocks.

**Always ask the user what their intent with the data is.** Ask about visualization, processing, DL training, archival, and whether they want to leverage parallel compute — even if the data fits in RAM.

## When the user points you at a directory or multi-file dataset
**ALWAYS read `references/data-discovery.md` and follow its 7-step workflow** before writing any code. The workflow covers: inspecting file layout, parsing naming conventions, understanding user intent, choosing between single blockedImage vs. collection, assessing random access capabilities, checking for gaps/overlaps, and recommending an approach (built-in adapter, format conversion, or custom adapter).

## Construction
```matlab
% Read-only (auto-selects adapter; reads only metadata, fast)
bim = blockedImage("large_image.tif");

% Multiple images at once
[bim1, bim2] = blockedImage(["img1.tif", "img2.tif"]);

% Writable
bim = blockedImage(dest, imageSize, blockSize, initVal, Mode="w");

% Override adapter
bim = blockedImage(source, Adapter=myAdapter);
```

## BlockSize
- Defaults to a factor of `IOBlockSize` (adapter's native read unit), targeting ~1024 or the minimum dimension size.
- The object's `BlockSize` is the default for all downstream processing and visualization.
- Override per-operation via the `BlockSize` name-value argument (e.g., when a DL network requires a fixed input size).
- For best performance, keep `BlockSize` as a multiple of `IOBlockSize` and as large as practical.

## Reading Data
- `getBlock(bim, blocksub)` — read one block by block subscript. Returns `[data, blockinfo]`.
- `getRegion(bim, pixelStart, pixelEnd)` — read an arbitrary pixel region.
- `gather(bim)` — load entire image into memory (only if it fits in RAM). Use `Level` to select resolution.

## Processing with `apply()`
`apply(bim, @fcn)` calls `fcn` on each block one at a time. Scales to arbitrarily large data. Supports `UseParallel=true` for cluster execution.

Key name-value arguments: `BlockSize`, `BorderSize`, `Level`, `ExtraImages`, `PadPartialBlocks`, `PadMethod`, `OutputLocation`, `BatchSize`, `Resume`, `BlockLocationSet`, `DisplayWaitbar`.

### Block struct (`bs`) fields
The user function receives a block struct `bs` with:
- `bs.Data` — pixel data for this block (includes border if `BorderSize` > 0)
- `bs.Start` — 1-by-N pixel subscript of the block's top-left corner (excluding border)
- `bs.End` — 1-by-N pixel subscript of the block's bottom-right corner (excluding border)
- `bs.BorderSize` — 1-by-N border size used
- `bs.Level` — resolution level
- `bs.BlockSub` — block subscript (index into `SizeInBlocks`)
- `bs.ImageNumber` — index of the source image (when processing an array)

### Struct / non-image output
When the output per block is not image data (e.g., detection results, counts), use `images.blocked.MATBlocks` adapter to store structs:
```matlab
bResults = apply(bim, @countNuclei, ...
    BlockLocationSet=bls, BorderSize=[r r], ...
    Adapter=images.blocked.MATBlocks, OutputLocation="results_dir");
allResults = gather(bResults);  % load all structs into memory
```

### Limit work to real data
- **Crop first.** `crop(bim, cstart, cend)` is virtual — no data copy, executes instantly. Use to restrict to a spatial ROI or single channel before processing.
- **Use masks with `selectBlockLocations`.** Build a mask from a coarse level, then process only blocks overlapping the ROI. See `references/specialized-workflows.md` for the full pattern including `InclusionThreshold` and block-size tuning.

### Key patterns
- **Single pass.** Perform all pre/pos