Repository navigation
Expand file tree
/
Copy pathREADME.qmd
More file actions
136 lines (106 loc) · 4.31 KB
/
Copy pathREADME.qmd
File metadata and controls
136 lines (106 loc) · 4.31 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
---
format:
gfm:
default-image-extension: ""
---
<!-- README.md is generated from README.qmd. Please edit that file -->
```{r}
#| include: false
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# ImageArray <a href="https://github.com/BIMSBbioinfo/ImageArray"><img src="man/figures/logo.png" alt="imagearray website" align="right" height="180"/></a>
**ImageArray** provides a unified, memory‑efficient way to work with pyramidal and non‑pyramidal images using the `DelayedArray` package in Bioconductor.
It stores large images in memory or on disk (as **HDF5** or **Zarr**), allows array‑like manipulations, and applies common image operations
consistently across all pyramid levels without loading arrays in memory.
- **Pyramids:** multi‑resolution stacks of, e.g., from HDF5, Zarr or OME‑TIFF (Bio-formats) images as a single object.
- **Interoperability:** plays nicely with image classes across R/Bioconductor, such as **EBImage** or **magick**.
- **Delayed operations:** NGFF transformations (scale, translation, affine), and imaging operations (negation, cropping, slicing) – performed lazily, without loading in memory, via `DelayedArray`.
- **Backends:** HDF5 and Zarr on‑disk storage using **HDF5Array** and **ZarrArray** packages.
## What are image pyramids?
<img
src="inst/extdata/dz-pyramid.png"
align="right" width="250" alt="image" hspace="10"
/>
An **image pyramid** is a multi‑scale representation built by repeatedly smoothing and down‑sampling an image (e.g. Gaussian/Laplacian pyramids).
Pyramids make zooming, visualization, and scale‑aware analysis efficient – a staple in digital pathology and large microscopy images.
## Installation
You can install ImageArray from Bioconductor with:
``` r
if (!requireNamespace("BiocManager", quietly = TRUE)) {
install.packages("BiocManager")
}
BiocManager::install("ImageArray")
```
## Getting started
**ImageArray** allows saving images to either HDF5 or
Zarr where you can define the number of layers of the
pyramids (i.e. number of downscaled images) and the path to the on-disk h5
file or zarr store.
```{r start}
#| label: start
library(ImageArray)
library(EBImage)
img_file <- system.file("images", "sample.png", package="EBImage")
img = readImage(img_file)
dir.create(td <- tempfile())
output <- file.path(td, "sample.h5")
imgarray <- writeImageArray(img,
output = output,
n.levels = 2)
imgarray
```
Each level of a pyramid can be rasterized at any time, and thus plotted.
```{r raster}
#| label: raster
imgraster <- as.raster(imgarray, level = 2)
plot(imgraster)
```
<br>
By using the `max.pixel.size`, we can request **ImageArray** to
return a pyramid level whose both width (`X`) and height (`Y`) are lower than
some pixel size, e.g. 400. Hence, **ImageArray** can be used by other
implementations to plot images in a memory-efficient way.
```{r raster_dim}
#| label: raster_dim
# visualize
bfa.raster <- as.raster(imgarray, max.pixel.size = 400)
dim(bfa.raster)
```
We can crop or slice images via lazy/delayed indexing again without loading the
image in the memory.
```{r slicing}
#| label: slicing
# crop or slice via indexing
imgarray <- imgarray[100:200, 200:300]
imgarray
```
You can also use an existing **OME-TIFF** (or any Bioformats image) to
create an ImageArray object which we use **RBioFormats** package.
```{r bioformats}
#| label: bioformats
library(RBioFormats)
ome_file <- system.file("extdata",
"xy_12bit__plant.ome.tiff",
package = "ImageArray")
imgarray <- ImageArray(ome_file,
series = 1,
resolution = 1:2)
imgarray
```
## Transformations
A number of memory-efficient (delayed or lazy) operations are available
for pyramid images, such as horizontal or vertical flipping and negation.
These operations also include coordinate transformations, including
translation, scaling, rotation and affine transformations. See [OME-NGFF](https://ngff.openmicroscopy.org/rfc/5/index.html#coordinatetransformations-metadata)
webpage to learn more about coordinate systems and transformations.
```{r rotate}
#| label: rotate
imgarray_rot <- rotate(imgarray, angle = 35)
imgarray_rot
plot(as.raster(imgarray_rot))
```