---
title: "OME-NGFF Images"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{OME-NGFF Images}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  out.width = "100%"
)
library(pizzarr)

sample_dir <- tools::R_user_dir("pizzarr")
clean <- !dir.exists(sample_dir)

has_blosc <- requireNamespace("blosc", quietly = TRUE)

idr_url <- "https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.4/idr0062A/6001240.zarr"
online <- tryCatch({
  con <- url(paste0(idr_url, "/.zattrs"))
  on.exit(try(close(con), silent = TRUE))
  length(readLines(con, warn = FALSE)) > 0
}, error = function(e) FALSE, warning = function(w) FALSE)
```

[OME-NGFF](https://ngff.openmicroscopy.org/) is a convention for storing
bioimaging data in Zarr. A microscopy image is often far too large to open at
full resolution, so an OME-NGFF store holds the same image several times over at
decreasing resolutions — an image pyramid — and records the arrangement in group
attributes. Reading one means consulting those attributes to pick a resolution,
then reading the array it points to.

The convention is independent of where the store lives. This vignette reads a
local store and a remote one with the same code; only the store object differs.
See `vignette("remote-stores")` for connection details.

## The multiscales attribute

The root group carries a `multiscales` attribute describing the pyramid. Each
entry in its `datasets` list names a path within the store, ordered from highest
resolution to lowest:

```{r, eval = has_blosc}
root <- pizzarr_sample("dog.ome.zarr")

g <- zarr_open_group(DirectoryStore$new(root))

attrs <- g$get_attrs()$to_list()
names(attrs)
```

```{r, eval = has_blosc}
vapply(attrs$multiscales[[1]]$datasets, function(d) d$path, character(1))
```

Those paths are the arrays. Taking the first gives full resolution:

```{r, eval = has_blosc}
first_resolution <- attrs$multiscales[[1]]$datasets[[1]]$path

zarr_arr <- g$get_item(first_resolution)
zarr_arr$get_shape()
```

Three channels of 500 by 750 pixels — RGB. Reading it all and plotting takes
the array into the channel-last order `rasterImage()` expects:

```{r, eval = has_blosc, fig.alt = "Photograph of a dog, decoded from a local OME-NGFF Zarr store."}
arr <- zarr_arr$get_item("...")$data

dm <- dim(arr)
plot.new()
plot.window(c(0, dm[3]), c(0, dm[2]), asp = 1)
rasterImage(aperm(arr, c(2, 3, 1)) / 255, 0, 0, dm[3], dm[2])
```

## The same code against a remote store

A published OME-NGFF image behaves identically — swap `DirectoryStore` for
`HttpStore` and nothing else changes. This one comes from the EMBL-EBI
[Image Data Resource](https://idr.openmicroscopy.org/), which serves its Zarr
over an S3-compatible endpoint:

```{r, eval = has_blosc && online}
g <- zarr_open_group(HttpStore$new(idr_url))

attrs <- g$get_attrs()$to_list()
first_resolution <- attrs$multiscales[[1]]$datasets[[1]]$path

zarr_arr <- g$get_item(first_resolution)
zarr_arr$get_shape()
```

This image has four dimensions — two channels, 236 Z-planes, then 275 by 271
pixels. Reading all of it would pull far more than the illustration needs, so
take a single Z-plane. Only the chunks overlapping the selection are fetched:

```{r, eval = has_blosc && online}
z_index <- 118

nested_arr <- zarr_arr$get_item(list(
  slice(1, 2), slice(z_index, z_index), slice(NA, NA), slice(NA, NA)
))

nested_arr$shape
```

The two channels are not red and green as such — they are separate stains.
Mapping them onto two colour channels gives a quick look:

```{r, eval = has_blosc && online, fig.alt = "Two-channel fluorescence microscopy Z-plane rendered as a red and green composite."}
arr <- nested_arr$data

rg_arr <- aperm(arr, c(2, 4, 3, 1))[1, , , ]
rgb_arr <- array(0, dim = c(271, 275, 3))
rgb_arr[, , 1] <- rg_arr[, , 1]
rgb_arr[, , 2] <- rg_arr[, , 2]

plot.new()
plot.window(c(0, 271), c(0, 275), asp = 1)
rasterImage(rgb_arr / max(rgb_arr), 0, 0, 271, 275)
```

```{r, include = FALSE}
if (clean) unlink(sample_dir, recursive = TRUE)
```