, Kent Johnson [aut],
Simon Urbanek [ctb], Sergi Padilla-Parra [ths]
, Jeroen Ooms [rev,
ctb] , Jon Clayden
[rev] | Title: | Comprehensive TIFF I/O with Full Support for 'ImageJ' TIFF Files |
|---|---|
| Description: | General purpose TIFF file I/O for R users. Currently the only such package with read and write support for TIFF files with floating point (real-numbered) pixels, and the only package that can correctly import TIFF files that were saved from 'ImageJ' and write TIFF files than can be correctly read by 'ImageJ' <https://imagej.net/ij/>. Also supports text image I/O. |
| Authors: | Rory Nolan [aut, cre]
, Kent Johnson [aut],
Simon Urbanek [ctb], Sergi Padilla-Parra [ths]
, Jeroen Ooms [rev,
ctb] , Jon Clayden
[rev] |
| Maintainer: | Rory Nolan <[email protected]> |
| License: | GPL-3 |
| Version: | 2.3.4 |
| Built: | 2024-11-25 06:53:42 UTC |
| Source: | CRAN |
This is for interoperability with the the EBImage package.
as_EBImage(img, colormode = NULL, scale = TRUE, force = TRUE)as_EBImage(img, colormode = NULL, scale = TRUE, force = TRUE)
img |
An ijtiff_img object (or something coercible to one). |
colormode |
A numeric or a character string containing the color mode
which can be either |
scale |
Scale values in an integer image to the range |
force |
This function is designed to take ijtiff_imgs as input. To
force any old array through this function, use |
The guess for the colormode is made as follows: * If img has an attribute
color_space with value "RGB", then colormode is set to "Color". *
Else if img has 3 or 4 channels, then colormode is set to "Color". *
Else colormode is set to "Grayscale".
An EBImage::Image.
if (rlang::is_installed("EBImage")) { img <- read_tif(system.file("img", "Rlogo.tif", package = "ijtiff")) str(img) str(as_EBImage(img)) }if (rlang::is_installed("EBImage")) { img <- read_tif(system.file("img", "Rlogo.tif", package = "ijtiff")) str(img) str(as_EBImage(img)) }
TIFF files can hold many frames. Often this is sensible, e.g. each frame could be a time-point in a video or a slice of a z-stack.
count_frames(path) frames_count(path)count_frames(path) frames_count(path)
path |
A string. The path to the tiff file to read. |
For those familiar with TIFF files, this function counts the number of directories in a TIFF file. There is an adjustment made for some ImageJ-written TIFF files.
A number, the number of frames in the TIFF file. This has an
attribute n_dirs which holds the true number of directories in the TIFF
file, making no allowance for the way ImageJ may write TIFF files.
count_frames(system.file("img", "Rlogo.tif", package = "ijtiff"))count_frames(system.file("img", "Rlogo.tif", package = "ijtiff"))
Display an image that has been read in by read_tif() as it would look in
'ImageJ'. This function is really just EBImage::display() on the inside. If
you do not have EBImage installed, a more basic display is offered.
display(img, method = NULL, basic = FALSE, normalize = TRUE)display(img, method = NULL, basic = FALSE, normalize = TRUE)
img |
An ijtiff_img object. |
method |
The way of displaying images. Defaults to "browser" when R is
used interactively, and to "raster" otherwise. The default behavior can be
overridden by setting options("EBImage.display"). This has no effect when
|
basic |
Force the basic (non- |
normalize |
Normalize the image before displaying (for better contrast)? This only has an effect if the EBImage functionality is used. The basic display always normalizes. |
if (requireNamespace("EBImage")) { img <- read_tif(system.file("img", "Rlogo.tif", package = "ijtiff")) display(img) display(img[, , 1, 1]) # first (red) channel, first frame display(img[, , 2, ]) # second (green) channel, first frame display(img[, , 3, ]) # third (blue) channel, first frame display(img, basic = TRUE) # displays first (red) channel, first frame }if (requireNamespace("EBImage")) { img <- read_tif(system.file("img", "Rlogo.tif", package = "ijtiff")) display(img) display(img[, , 1, 1]) # first (red) channel, first frame display(img[, , 2, ]) # second (green) channel, first frame display(img[, , 3, ]) # third (blue) channel, first frame display(img, basic = TRUE) # displays first (red) channel, first frame }
ijtiff: TIFF I/O for ImageJ usersThis is a general purpose TIFF I/O utility for R. The tiff package already exists for this
purpose but ijtiff adds some functionality and overcomes some bugs therein.
ijtiff can write TIFF files whose pixel values are real (floating-point)
numbers; tiff cannot.
ijtiff can read and write text images; tiff
cannot.
tiff struggles to interpret channel information and gives cryptic
errors when reading TIFF files written by the ImageJ software; ijtiff
works smoothly with these images.
ijtiff_img class.A class for images which are read or to be written by the ijtiff package.
ijtiff_img(img, ...) as_ijtiff_img(img, ...)ijtiff_img(img, ...) as_ijtiff_img(img, ...)
img |
An array representing the image.
|
... |
Named arguments which are set as attributes. |
A 4 dimensional array representing an image, indexed by img[y, x, channel, frame], with selected attributes.
img <- matrix(1:4, nrow = 2) # to be a single-channel, grayscale image ijtiff_img(img, description = "single-channel, grayscale") img <- array(seq_len(2^3), dim = rep(2, 3)) # 1 channel, 2 frame ijtiff_img(img, description = "blah blah blah") img <- array(seq_len(2^3), dim = c(2, 2, 2, 1)) # 2 channel, 1 frame ijtiff_img(img, description = "blah blah") img <- array(seq_len(2^4), dim = rep(2, 4)) # 2 channel, 2 frame ijtiff_img(img, software = "R")img <- matrix(1:4, nrow = 2) # to be a single-channel, grayscale image ijtiff_img(img, description = "single-channel, grayscale") img <- array(seq_len(2^3), dim = rep(2, 3)) # 1 channel, 2 frame ijtiff_img(img, description = "blah blah blah") img <- array(seq_len(2^3), dim = c(2, 2, 2, 1)) # 2 channel, 1 frame ijtiff_img(img, description = "blah blah") img <- array(seq_len(2^4), dim = rep(2, 4)) # 2 channel, 2 frame ijtiff_img(img, software = "R")
ijtiff has the fourth dimension of an ijtiff_img as its time dimension.
However, some linescan images (images where a single line of pixels is
acquired over and over) have the time dimension as the y dimension, (to avoid
the need for an image stack). These functions allow one to convert this type
of image into a conventional ijtiff_img (with time in the fourth dimension)
and to convert back.
linescan_to_stack(linescan_img) stack_to_linescan(img)linescan_to_stack(linescan_img) stack_to_linescan(img)
linescan_img |
A 4-dimensional array in which the time axis is the first
axis. Dimension 4 must be 1 i.e. |
img |
A conventional ijtiff_img, to be turned into a linescan image.
Dimension 1 must be 1 i.e. |
The converted image, an object of class ijtiff_img.
linescan <- ijtiff_img(array(rep(1:4, each = 4), dim = c(4, 4, 1, 1))) print(linescan) stack <- linescan_to_stack(linescan) print(stack) linescan <- stack_to_linescan(stack) print(linescan)linescan <- ijtiff_img(array(rep(1:4, each = 4), dim = c(4, 4, 1, 1))) print(linescan) stack <- linescan_to_stack(linescan) print(stack) linescan <- stack_to_linescan(stack) print(linescan)
ijtiff_img.Print method for an ijtiff_img.
## S3 method for class 'ijtiff_img' print(x, ...)## S3 method for class 'ijtiff_img' print(x, ...)
x |
An object of class ijtiff_img. |
... |
Not currently used. |
The input (invisibly).
TIFF files contain metadata about images in their TIFF tags. This function is for reading this information without reading the actual image.
read_tags(path, frames = 1) tags_read(path, frames = 1)read_tags(path, frames = 1) tags_read(path, frames = 1)
path |
A string. The path to the tiff file to read. |
frames |
Which frames do you want to read tags from. Default first frame
only. To read from the 2nd and 7th frames, use |
A list of lists.
Simon Urbanek, Kent Johnson, Rory Nolan.
read_tags(system.file("img", "Rlogo.tif", package = "ijtiff")) read_tags(system.file("img", "Rlogo-banana.tif", package = "ijtiff"), frames = c(2, 4) )read_tags(system.file("img", "Rlogo.tif", package = "ijtiff")) read_tags(system.file("img", "Rlogo-banana.tif", package = "ijtiff"), frames = c(2, 4) )
Reads an image from a TIFF file/content into a numeric array or list.
read_tif(path, frames = "all", list_safety = "error", msg = TRUE) tif_read(path, frames = "all", list_safety = "error", msg = TRUE)read_tif(path, frames = "all", list_safety = "error", msg = TRUE) tif_read(path, frames = "all", list_safety = "error", msg = TRUE)
path |
A string. The path to the tiff file to read. |
frames |
Which frames do you want to read. Default all. To read the 2nd
and 7th frames, use |
list_safety |
A string. This is for type safety of this function. Since
returning a list is unlikely and probably unexpected, the default is to
error. You can instead opt to throw a warning ( |
msg |
Print an informative message about the image being read? |
TIFF files have the capability to store multiple images, each having multiple
channels. Typically, these multiple images represent the sequential frames in
a time-stack or z-stack of images and hence each of these images has the same
dimension. If this is the case, they are all read into a single 4-dimensional
array img where img is indexed as img[y, x, channel, frame] (where we
have y, x to comply with the conventional row, col indexing of a matrix -
it means that images displayed as arrays of numbers in the R console will
have the correct orientation). However, it is possible that the images in the
TIFF file have varying dimensions (most people have never seen this), in
which case they are read in as a list of images, where again each element of
the list is a 4-dimensional array img, indexed as img[y, x, channel, frame].
A (somewhat random) set of TIFF tags are attributed to the read image. These are IMAGEDEPTH, BITSPERSAMPLE, SAMPLESPERPIXEL, SAMPLEFORMAT, PLANARCONFIG, COMPRESSION, THRESHHOLDING, XRESOLUTION, YRESOLUTION, RESOLUTIONUNIT, INDEXED and ORIENTATION. More tags should be added in a subsequent version of this package. You can read about TIFF tags at https://www.awaresystems.be/imaging/tiff/tifftags.html.
TIFF images can have a wide range of internal representations, but only the most common in image processing are supported (8-bit, 16-bit and 32-bit integer and 32-bit float samples).
An object of class ijtiff_img or a list of ijtiff_imgs.
12-bit TIFFs are not supported.
There is no standard for packing order for TIFFs beyond 8-bit so we assume big-endian packing
.
Simon Urbanek wrote most of this code for the 'tiff' package. Rory Nolan lifted it from there and changed it around a bit for this 'ijtiff' package. Credit should be directed towards Lord Urbanek.
img <- read_tif(system.file("img", "Rlogo.tif", package = "ijtiff"))img <- read_tif(system.file("img", "Rlogo.tif", package = "ijtiff"))
Write images (arrays) as tab-separated .txt files on disk. Each
channel-frame pair gets its own file.
write_txt_img(img, path, rds = FALSE, msg = TRUE) read_txt_img(path, msg = TRUE) txt_img_write(img, path, rds = FALSE, msg = TRUE) txt_img_read(path, msg = TRUE)write_txt_img(img, path, rds = FALSE, msg = TRUE) read_txt_img(path, msg = TRUE) txt_img_write(img, path, rds = FALSE, msg = TRUE) txt_img_read(path, msg = TRUE)
img |
An image, represented by a 4-dimensional array, like an ijtiff_img. |
path |
The name of the input/output output file(s), without a file extension. |
rds |
In addition to writing a text file, save the image as an RDS (a single R object) file? |
msg |
Print an informative message about the image being read? |
img <- read_tif(system.file("img", "Rlogo.tif", package = "ijtiff")) tmptxt <- tempfile(pattern = "img", fileext = ".txt") write_txt_img(img, tmptxt) tmptxt_ch1_path <- paste0(strex::str_before_last_dot(tmptxt), "_ch1.txt") print(tmptxt_ch1_path) txt_img <- read_txt_img(tmptxt_ch1_path)img <- read_tif(system.file("img", "Rlogo.tif", package = "ijtiff")) tmptxt <- tempfile(pattern = "img", fileext = ".txt") write_txt_img(img, tmptxt) tmptxt_ch1_path <- paste0(strex::str_before_last_dot(tmptxt), "_ch1.txt") print(tmptxt_ch1_path) txt_img <- read_txt_img(tmptxt_ch1_path)
A dataset containing the information on all known baseline and extended TIFF tags.
tif_tags_reference()tif_tags_reference()
A data frame with 96 rows and 10 variables:
decimal numeric code of the TIFF tag
hexadecimal numeric code of the TIFF tag
the name of the TIFF tag
a short description of the TIFF tag
the type of TIFF tag: either "baseline" or "extended"
the URL of the TIFF tag at https://www.awaresystems.be
the TIFF tag name in the libtiff C library
the C type of the TIFF tag data in libtiff
the number of elements in the TIFF tag data
the default value of the data held in the TIFF tag
tif_tags_reference()tif_tags_reference()
Write images into a TIFF file.
write_tif( img, path, bits_per_sample = "auto", compression = "none", overwrite = FALSE, msg = TRUE ) tif_write( img, path, bits_per_sample = "auto", compression = "none", overwrite = FALSE, msg = TRUE )write_tif( img, path, bits_per_sample = "auto", compression = "none", overwrite = FALSE, msg = TRUE ) tif_write( img, path, bits_per_sample = "auto", compression = "none", overwrite = FALSE, msg = TRUE )
img |
An array representing the image.
|
path |
file name or a raw vector |
bits_per_sample |
number of bits per sample (numeric scalar). Supported
values are 8, 16, and 32. The default |
compression |
A string, the desired compression algorithm. Must be one
of |
overwrite |
If writing the image would overwrite a file, do you want to proceed? |
msg |
Print an informative message about the image being written? |
The input img (invisibly).
Simon Urbanek wrote most of this code for the 'tiff' package. Rory Nolan lifted it from there and changed it around a bit for this 'ijtiff' package. Credit should be directed towards Lord Urbanek.
img <- read_tif(system.file("img", "Rlogo.tif", package = "ijtiff")) temp_dir <- tempdir() write_tif(img, paste0(temp_dir, "/", "Rlogo")) img <- matrix(1:4, nrow = 2) write_tif(img, paste0(temp_dir, "/", "tiny2x2")) list.files(temp_dir, pattern = "tif$")img <- read_tif(system.file("img", "Rlogo.tif", package = "ijtiff")) temp_dir <- tempdir() write_tif(img, paste0(temp_dir, "/", "Rlogo")) img <- matrix(1:4, nrow = 2) write_tif(img, paste0(temp_dir, "/", "tiny2x2")) list.files(temp_dir, pattern = "tif$")