Skip to contents

Understanding Text Images

Text images are arrays of numbers stored in a tab-delimited file (https://en.wikipedia.org/wiki/Tab-separated_values), where each location in the file represents a pixel and the value stored there is the pixel intensity.

Why Use Text Images?

Text images serve two main purposes:

  1. Compatibility: Many software packages (e.g., Microsoft Excel) don’t support saving arrays as TIFF files but can save them as tab-separated text files.

  2. Value Range: A 32-bit TIFF file can only hold values up to 23212^{32} - 1 (approximately 4×1094 \times 10^9). Text images have no such limitation, making them useful for storing very large numerical values.

Limitations

While text images can be useful in specific situations, they have some drawbacks: * Larger file sizes compared to binary formats * Slower to read and write * Less standardized than TIFF format * Not supported by most image viewing software

Working with Text Images

Reading Text Images

To read a text image, use the read_txt_img() function:

library(ijtiff)
path_txt_img <- system.file("img", "Rlogo-grey.txt", package = "ijtiff")
txt_img <- read_txt_img(path_txt_img)
#> Reading 76x100 pixel text image 'Rlogo-grey.txt' . . .
#>  Done.
print(dim(txt_img))  # Show image dimensions
#> [1]  76 100

Note that read_txt_img() expects a tab-separated file (TSV). This is the format that ImageJ uses when saving text images. Other formats like CSV are not supported.

Writing Text Images

Writing a text image is straightforward using write_txt_img():

# Create a simple test image
test_img <- array(1:16, dim = c(4, 4, 1, 1))

# Write it as a text image
out_path <- tempfile(pattern = "txtimg", fileext = ".txt")
write_txt_img(test_img, path = out_path)
#> Writing txtimg14cd69685929.txt: a 4x4 pixel text image with 1 channel and 1 frame . . .
#>  Done.

# Read it back to verify
read_back <- read_txt_img(out_path)
#> Reading 4x4 pixel text image 'txtimg14cd69685929.txt' . . .
#>  Done.
all.equal(test_img, read_back)
#> [1] "Attributes: < Length mismatch: comparison on first 1 components >"
#> [2] "Attributes: < Component \"dim\": Numeric: lengths (4, 2) differ >"
#> [3] "target is array, current is matrix"

Converting Between TIFF and Text Images

You can convert between TIFF and text image formats using a combination of read_tif(), write_tif(), read_txt_img(), and write_txt_img():

# TIFF to text
tiff_path <- system.file("img", "Rlogo-grey.tif", package = "ijtiff")
img <- read_tif(tiff_path)
#> Reading Rlogo-grey.tif: a 32-bit, 76x100 pixel image of
#> floating point type. Reading 1 channel and 1 frame . . .
#> Done.
txt_path <- tempfile(fileext = ".txt")
write_txt_img(img, txt_path)
#> Writing file14cd7b0a12f7.txt: a 76x100 pixel text image with 1 channel and 1 frame . . .
#>  Done.

# Text to TIFF
txt_img <- read_txt_img(txt_path)
#> Reading 76x100 pixel text image 'file14cd7b0a12f7.txt' . . .
#>  Done.
tiff_path2 <- tempfile(fileext = ".tif")
write_tif(txt_img, tiff_path2)
#> Writing /tmp/RtmpKdmfko/file14cd54aac61.tif ... 0-bit 76x100
#> pixel image floating point 1 ch 1 frames
#> Done.

See Also