# Deep Zoom and Gigapixel Images

Source: https://www.potatoannotator.com/docs/vision-spatial/deep-zoom

**Annotate images too large to send to a browser as one file — aerial surveys, stitched microscopy mosaics, scanned maps — with boxes, polygons and masks that work at any magnification.** Potato serves a tile pyramid and layers the annotation canvas over it.

```yaml
annotation_schemes:
  - annotation_type: image_annotation
    name: structures
    description: "Mark every structure."
    source_field: image
    viewer: deepzoom          # the default is `fabric`
    tools: [bbox, polygon, brush, eraser]
    labels:
      - {name: building, color: "#c0392b"}
```

`media_directory` is where the tile routes read from; paths in your data file are relative to it.

Runnable example: [`examples/image/deep-zoom/`](https://github.com/davidjurgens/potato/tree/main/examples/image/deep-zoom).

## Two protocols, one pyramid

The same tile pyramid is served as both [DZI](https://en.wikipedia.org/wiki/Deep_Zoom) and [IIIF Image API 3.0](https://iiif.io/api/image/3.0/). IIIF matters for cultural-heritage and digital-humanities work, where an institution's existing viewers and citation practices already assume it. Rendering is by [OpenSeadragon](https://openseadragon.github.io/), vendored locally like every other asset.

## Masks at full resolution

Brush masks work on tiled images at the source's full resolution, because the mask buffer indexes **image pixels** rather than a GPU texture. There is no texture-size ceiling to hit.

This is worth stating carefully, because an earlier version of this claim was wrong and was corrected. Other platforms do support masking on tiled images; V7 among them. What is specific here is the buffer design, not the capability.

The buffers are sparse and chunked, which is what makes this affordable: ten classes on a 12-megapixel image went from about 458 MB to about 46 MB, and mask data stopped scaling with image area at all, holding at 16 KB regardless of resolution.

## Where Potato is not the right tool

For digital pathology specifically, [QuPath](https://qupath.github.io/) (desktop, open source, the field standard) and [Cytomine](https://cytomine.com/) (web, open source, multi-user with blind annotation) are purpose-built, and Potato does not read SVS, DICOM or NIfTI. Use Potato here when your images are large but not clinical-format, or when you need its agreement and workflow layers on top.

## Related

- [Media ingest](/docs/vision-spatial/media-ingest) — 16-bit TIFF, HEIC, RAW
- [Geometry primitives](/docs/vision-spatial/geometry-primitives)
- [Source documentation](https://github.com/davidjurgens/potato/blob/main/docs/annotation-types/multimedia/deep_zoom.md)