getIFD: RIF/CIF Image Field Directories Extraction

In IFC: Tools for Imaging Flow Cytometry

RIF/CIF Image Field Directories Extraction

Description

Extracts IFDs (Image File Directory) in RIF or CIF files.
IFDs contain information about images or masks of objects stored within XIF files.
The first IFD is special in that it does not contain image of mask information but general information about the file.
Users are highly encouraged to read TIFF specifications to have a better understanding about what IFDs are.

Usage

getIFD(
  fileName,
  offsets = "first",
  trunc_bytes = 12,
  force_trunc = FALSE,
  verbose = FALSE,
  verbosity = 1,
  display_progress = FALSE,
  bypass = FALSE,
  ...
)

Arguments

fileName	path to file.
offsets	either "all", "first" or an object of class 'IFC_offset'. Default is "first".
trunc_bytes	a positive integer maximal number of individual scalar to extract BYTE/ASCII/SBYTE/UNDEFINED for TAGS (1, 2, 6 or 7). Default is 12. However, if less is found, less is returned in map. Note that, if 0 is provided, it will be automatically set to 1.
force_trunc	whether to force truncation for all TAGS types. Default is FALSE. If TRUE, 'trunc_bytes' will be used for TAGS (3, 4, 5, 8, 9, 10, 11 and 12) to extract desired number of individual scalar corresponding to each types.
verbose	whether to display information (use for debugging purpose). Default is FALSE.
verbosity	quantity of information displayed when verbose is TRUE; 1: normal, 2: rich. Default is 1.
display_progress	whether to display a progress bar. Default is FALSE.
bypass	whether to bypass checks on 'trunc_bytes', 'force_trunc', 'verbose', 'verbosity' and 'display_progress'. Default is FALSE.
...	other arguments to be passed.

Details

Function will return IFDs (image, mask or first) from the file using provided offsets argument.
IFDs contain several tags that can be viewed as descriptive meta-information of raw data stored within RIF or CIF file. For more details see TIFF specifications.
If 'offsets' == "first" only first IFD will be returned.
If 'offsets' == "all" all images and masks IFDs will be returned but not "first" one. Be aware that errors may occur if offsets are not extracted with getOffsets or subsetOffsets.

Value

A list of named lists, each containing:
-tags, a named list whose names are tags found, where each tag is a list of tag, typ, siz, val, byt, len, off, map information.
-infos, a named list containing essential information about IFDs, IMAGE_LENGTH, IMAGE_WIDTH, OBJECT_ID, COMPRESSION, TYPE, STRIP_OFFSETS, STRIP_BYTE_COUNTS, BG_MEAN, BG_STD
-curr_IFD_offset, the position of current IFD offset
-next_IFD_offset, the position of next IFD offset

Source

TIFF 6.0 specifications archived from web https://web.archive.org/web/20211209104854/https://www.adobe.io/open/standards/TIFF.html

Examples

if(requireNamespace("IFCdata", quietly = TRUE)) {
  ## use a cif file
  file_cif <- system.file("extdata", "example.cif", package = "IFCdata")
  ## read 1st IFD
  IFD_first <- getIFD(fileName = file_cif, offsets = "first")
  ## show information contained in 1st IFD
  print(sapply(IFD_first[[1]]$tags, FUN=function(x) x)) 
} else {
  message(sprintf('Please run `install.packages("IFCdata", repos = "%s", type = "source")` %s',
                  'https://gitdemont.github.io/IFCdata/',
                  'to install extra files required to run this example.'))
}

IFC documentation built on Sept. 14, 2023, 1:08 a.m.