Large Image Processing with blockedImage

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

% 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"]);