Skip to content

gallery: Generate ROI Sample Galleries

The gallery command generates a gallery grid image of randomly-sampled ROI (region of interest) crops for each class in a Pascal VOC dataset. This is useful for quickly eyeballing what a class actually looks like in your data — spotting mislabeled examples, checking crop quality, or reviewing a dataset before training.

Breaking change

This command now takes a single DATASET_DIR (expecting JPEGImages/ and Annotations/ subfolders -- the standard Pascal VOC devkit layout) instead of separate ANNOTATION_DIR/IMAGE_DIR arguments. See generate and split, which both write/read this same directory shape.

Usage

m3-download gallery DATASET_DIR [OPTIONS]

Required Parameters

  • DATASET_DIR: Dataset directory, expecting JPEGImages/ and Annotations/ subfolders

Options

  • -o, --output-dir: (Optional) Output directory for gallery grid images (default: gallery/)
  • -n, --grid-size: (Optional) Side length of the sample grid per class, e.g. 4 produces a 4x4 grid of 16 samples (default: 4)
  • --cell-size: (Optional) Side length, in pixels, of each rendered ROI cell (default: 224)
  • --zoom-out: (Optional) Multiplier applied to each ROI's longest side to zoom out and add context (default: 1.5)
  • --draw-boxes: (Optional) Draw the ROI bounding box on each cell
  • --box-color: (Optional) Color to draw ROI bounding boxes with (default: red)
  • --box-width: (Optional) Line width, in pixels, of drawn ROI bounding boxes (default: 2)
  • --gutter: (Optional) Spacing, in pixels, between cells in the grid (default: 2)
  • --background: (Optional) Background/gutter color of the grid image (default: white)
  • --seed: (Optional) Random seed for reproducible sampling

How It Works

  1. Annotation XML files are matched to their corresponding images by filename stem
  2. Every ROI (bounding box) across all annotations is collected and grouped by concept (class)
  3. For each concept, up to grid-size * grid-size ROIs are randomly sampled
  4. Each sampled ROI is cropped into a square region (padded by --zoom-out, clamped to the image bounds), resized to --cell-size, and optionally annotated with its bounding box
  5. Cells are assembled into a single grid image per concept and saved to the output directory as <concept>.png

Sparse Classes

If a concept has fewer ROIs than the requested grid can hold, the gallery is still generated with the available samples — the remaining cells are left blank.

Examples

Generate default 4x4 galleries for every class:

m3-download gallery dataset/ --output-dir gallery/

Generate larger 8x8 galleries with bounding boxes drawn:

m3-download gallery dataset/ -n 8 --draw-boxes

Generate reproducible galleries with tighter crops (less zoom-out):

m3-download gallery dataset/ --zoom-out 1.1 --seed 42