Working with TIFF Tags

Quick Start

library(ijtiff)

# Read tags from a TIFF file
tags <- read_tags(system.file("img", "Rlogo.tif", package = "ijtiff"))

# Write a TIFF with custom tags
img <- array(1:4, dim = c(2, 2, 1, 1))
write_tif(img, tempfile(fileext = ".tif"), 
          description = "Test image",
          resolution = c(300, 300))
#> Writing /tmp/Rtmp4HOX2H/file18e07b773a92.tif ... 0-bit 2x2
#> pixel image unsigned integer 1 ch 1 frames
#> Done.

Understanding TIFF Tags

TIFF (Tagged Image File Format) files contain not just image data, but also metadata in the form of tags. These tags provide important information about the image, such as:

Image dimensions (width, height)
Color space and channel information
Resolution and physical dimensions
Compression method
Custom metadata

The ijtiff package provides robust support for reading and writing several important TIFF tags.

Reading TIFF Tags

Basic Tag Reading

You can read tags from a TIFF file without loading the entire image using read_tags():

path_example <- system.file("img", "Rlogo-banana.tif", package = "ijtiff")
tags <- read_tags(path_example)
str(tags$frame1)  # Show just the first frame's tags
#> List of 11
#>  $ width            : int 100
#>  $ length           : int 78
#>  $ bits_per_sample  : int 8
#>  $ samples_per_pixel: int 3
#>  $ sample_format    : chr "uint"
#>  $ planar_config    : chr "contiguous"
#>  $ rows_per_strip   : int 78
#>  $ compression      : chr "deflate"
#>  $ software         : chr "ijtiff package, R 4.0.0"
#>  $ color_space      : chr "black is zero"
#>  $ photometric      : int 1

Tag Structure

The tags are returned as a list with one element per frame. Each frame’s tags include:

Image dimensions (ImageLength, ImageWidth)
Bits per sample
Samples per pixel (channels)
Resolution information (XResolution, YResolution, ResolutionUnit)
Compression method
And more

Writing TIFF Tags

Image Description

Add a description to your TIFF file using the description parameter:

# Create a simple test image
img <- array(1:4, dim = c(2, 2, 1, 1))
tmp_file <- tempfile(fileext = ".tif")

# Write with description
write_tif(img, tmp_file, description = "My test image", msg = FALSE)

# Read back the description
tags <- read_tags(tmp_file)
cat("Image description:", tags$frame1$description, "\n")
#> Image description: My test image

Color Space

Control the photometric interpretation of the image:

# Write a grayscale image with min-is-black interpretation
img_gray <- array(1:4, dim = c(2, 2, 1, 1))
tmp_file <- tempfile(fileext = ".tif")
write_tif(img_gray, tmp_file, 
          color_space = "min-is-black",  # Default for grayscale
          msg = FALSE)

# Write an RGB image
img_rgb <- array(1:24, dim = c(2, 2, 3, 1))
tmp_file2 <- tempfile(fileext = ".tif")
write_tif(img_rgb, tmp_file2, 
          color_space = "rgb",  # Required for RGB images
          msg = FALSE)

# Read back the color space information
tags_gray <- read_tags(tmp_file)
tags_rgb <- read_tags(tmp_file2)
cat("Grayscale color space:", tags_gray$frame1$color_space, "\n")
#> Grayscale color space: black is zero
cat("RGB color space:", tags_rgb$frame1$color_space, "\n")
#> RGB color space: RGB

Resolution Information

Set image resolution in different units:

# Write with resolution in inches (default)
write_tif(img, tmp_file, 
          resolution = c(300, 300),  # x and y resolution
          resolution_unit = "inch",
          overwrite = TRUE,
          msg = FALSE)

# Read back the resolution information
tags <- read_tags(tmp_file)
cat("Resolution:", tags$frame1$x_resolution, "x", tags$frame1$y_resolution, 
    "pixels per", tags$frame1$resolution_unit, "\n")
#> Resolution: 300 x 300 pixels per inch

Supported Tags

The ijtiff package supports reading and writing several TIFF tags:

ImageWidth (256): Width of the image in pixels
ImageLength (257): Height of the image in pixels
BitsPerSample (258): Number of bits per component
Compression (259): Compression scheme used
PhotometricInterpretation (262): Color space of the image data
ImageDescription (270): ASCII string describing the image
SamplesPerPixel (277): Number of components per pixel
XResolution (282): Pixels per ResolutionUnit in the ImageWidth direction
YResolution (283): Pixels per ResolutionUnit in the ImageLength direction
ResolutionUnit (296): Unit of measurement for XResolution and YResolution
SampleFormat (339): Data sample format

Reading Images with Tags

When you read an image using read_tif(), the tags are automatically attached as attributes:

# Read an image
img <- read_tif(path_example, msg = FALSE)

# View key attributes (tags)
str(attributes(img)[c("width", "length", "bits_per_sample", "samples_per_pixel")])
#> List of 4
#>  $ width            : int 100
#>  $ length           : int 78
#>  $ bits_per_sample  : int 8
#>  $ samples_per_pixel: int 3

TIFF Tags Reference

For a complete reference of all supported TIFF tags and their properties, use tif_tags_reference():

# View the complete TIFF tags reference
ref <- tif_tags_reference()
head(ref, 20)  # Show first few tags
#> # A tibble: 20 × 10
#>    code_dec code_hex name      short_description type  url   libtiff_name c_type
#>       <dbl> <chr>    <chr>     <chr>             <chr> <chr> <chr>        <chr> 
#>  1      254 00FE     NewSubfi… A general indica… base… http… TIFFTAG_SUB… LONG  
#>  2      255 00FF     SubfileT… A general indica… base… http… TIFFTAG_OSU… SHORT 
#>  3      256 0100     ImageWid… The number of co… base… http… TIFFTAG_IMA… SHORT…
#>  4      257 0101     ImageLen… The number of ro… base… http… TIFFTAG_IMA… SHORT…
#>  5      258 0102     BitsPerS… Number of bits p… base… http… TIFFTAG_BIT… SHORT 
#>  6      259 0103     Compress… Compression sche… base… http… TIFFTAG_COM… SHORT 
#>  7      262 0106     Photomet… The color space … base… http… TIFFTAG_PHO… SHORT 
#>  8      263 0107     Threshho… For black and wh… base… http… TIFFTAG_THR… SHORT 
#>  9      264 0108     CellWidth The width of the… base… http… TIFFTAG_CEL… SHORT 
#> 10      265 0109     CellLeng… The length of th… base… http… TIFFTAG_CEL… SHORT 
#> 11      266 010A     FillOrder The logical orde… base… http… TIFFTAG_FIL… SHORT 
#> 12      270 010E     ImageDes… A string that de… base… http… TIFFTAG_IMA… ASCII 
#> 13      271 010F     Make      The scanner manu… base… http… TIFFTAG_MAKE ASCII 
#> 14      272 0110     Model     The scanner mode… base… http… TIFFTAG_MOD… ASCII 
#> 15      273 0111     StripOff… For each strip, … base… http… TIFFTAG_STR… SHORT…
#> 16      274 0112     Orientat… The orientation … base… http… TIFFTAG_ORI… SHORT 
#> 17      277 0115     SamplesP… The number of co… base… http… TIFFTAG_SAM… SHORT 
#> 18      278 0116     RowsPerS… The number of ro… base… http… TIFFTAG_ROW… SHORT…
#> 19      279 0117     StripByt… For each strip, … base… http… TIFFTAG_STR… SHORT…
#> 20      280 0118     MinSampl… The minimum comp… base… http… TIFFTAG_MIN… SHORT 
#> # ℹ 2 more variables: count <chr>, default <chr>

This reference includes information about each tag’s:

Decimal and hexadecimal codes
Name and short description
Tag type (baseline or extended)
C type in libtiff
Default value
And more

Tips for Working with Tags

Always check the image description and resolution when working with scientific images
When writing images for ImageJ use, set appropriate resolution units
The sample_format tag is automatically set based on your data type
Some tags are read-only and set automatically by the package

2025-02-12