getIFD: 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,
  ...
)

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

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/UNDIFINED 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.

Examples

Run this code

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.'))
}