IFC (version 0.2.1)

objectExtract: Object Extraction

Description

Extracts / Decompress objects stored in RIF or CIF Files.

Usage

objectExtract(ifd, param, verbose = FALSE, bypass = FALSE, ...)

Value

A list (for every extracted objects) of list (for every exported channels) depending on 'param$export' parameter:

-"matrix", a matrix when 'param$mode' is set to "raw" or "gray" OR an array when 'param$mode' is "rgb",

-"base64", a data-uri string,

-"file", an invisible file path corresponding to the location of exported file(s).

Arguments

ifd

list of sub elements of IFD data information extracted by getIFD. This argument can't be missing.

param

object of class `IFC_param`, containing extraction parameters defined by objectParam.
This argument is not mandatory but it may allow to save time for repeated image export on same file. If this argument is missing, objectExtract will use named arguments in '...' as input to objectParam to control object extraction.
However, if 'param' is provided, '...' will be ignored.

verbose

whether to display information (use for debugging purpose). Default is FALSE.

bypass

whether to bypass checks on 'ifd' and 'param'. Default is FALSE.

...

Arguments passed on to objectParam

info

object of class `IFC_info`, rich information extracted by getInfo. This argument is not mandatory but it may allow to save time for repeated image export on same file. If missing, the default, 'info' will be extracted thanks to '...'.

mode

color mode export. Either "rgb", "gray" or "raw". Default is "raw". Note that "raw" is only possible when 'export' is "matrix".

export

format mode export. Either "file", "matrix", "base64". Default is "matrix".

write_to

used when export is "file" or "base64" to compute respectively exported file name or base64 id attribute.
Exported file extension and base64 MIME type will be deduced from this pattern. Allowed export are ".bmp", ".jpg", ".jpeg", ".png", ".tif", ".tiff". Note that ".bmp" are faster but not compressed producing bigger data.
Placeholders, if found, will be substituted:
-%d: with full path directory,
-%p: with first parent directory,
-%e: with extension (without leading .),
-%s: with shortname (i.e. basename without extension),
-%o: with object_id,
-%c: with channel_id.
A good trick is to use:
-"%d/%s/%s_%o_%c.tiff", when 'export' is "file",
-"%o_%c.bmp", when 'export' is "base64".
Note that if missing and 'export' is not "file", 'write_to' will be set to "%o_%c.bmp".

base64_id

whether to add id attribute to base64 exported object. Default is FALSE.
Only applied when export is "base64".

base64_att

attributes to add to base64 exported object. Default is "".
Only applied when export is "base64". For example, use "class='draggable'".
Note that id (if 'base64_id' is TRUE) and width and height are already used.

overwrite

only apply when 'export' is "file" whether to overwrite file or not. Default is FALSE.

composite

character vector of image composite. Default is "", for no image composite.
Should be like "1.05/2.4/4.55" for a composition of 5 perc. of channel 1, 40 perc. of channel 2 and 50 perc. of channel 55.
Note that channels should have been acquired and final image composition should be 100 perc., otherwise an error is thrown.
Note that each composite will be appended after 'selection'.

selection

physical channels to extract.
Note that this parameter will be ordered.
Default is "all" to extract all acquired channels.
Use "none" to only extract composite.

random_seed

a list of elements to pass to set.seed or a single value, interpreted as an integer, or NULL to be used when 'add_noise' is set to TRUE. Default is NULL. Note that NA_integer_ or list(seed = NA_integer_) can be used to not call set.seed at all.

size

a length 2 integer vector of final dimensions of the image, height 1st and width 2nd. Default is c(0,0) for no change.

force_width

whether to use information in 'info' to fill size. Default is TRUE. When set to TRUE, width of 'size' argument will be overwritten.

removal

removal method: Either "none", "raw", "clipped", "masked", "MC".
-"none", to keep image as is, no mask extraction will be performed resulting in faster extraction,
-"raw", to keep image as is, it provides a convenient way to retrieve "raw" value for the mask,
-"clipped", to remove clipped object from image,
-"masked", to only keep masked object from image,
-"MC", to keep MC masked object from image. This parameter will be repeated with rep_len() from base for every physical channel that needs to be extracted according to 'selection' and 'composite' parameters.

add_noise

if TRUE adds normal noise to background using Rcpp. Default is TRUE.
Note that it is better to set it to FALSE when 'removal' is "masked" or "MC". Doing so will allow to place masked object in a zero filled background, otherwise background will still be filled with noise. This parameter will be repeated with rep_len() from base for every physical channel that needs to be extracted according to 'selection' and 'composite' parameters.

full_range

only apply when 'mode' is not "raw", if 'full_range' is TRUE, then object range will be considered as 0 to 4095, it is like "raw" 'mode' but resulting in [0,4095] normalization to [0,1]. Default is FALSE.
This parameter will be repeated with rep_len() from base for every physical channel that needs to be extracted according to 'selection' and 'composite' parameters.

force_range

only apply when 'mode' is not "raw", if 'force_range' is TRUE, then range will be adjusted to object range in [-4095,+inf] resulting in normalization to [0,1]. Default is FALSE.
This parameter will be repeated with rep_len() from base for every physical channel that needs to be extracted according to 'selection' and 'composite' parameters.
Note that this parameter takes the precedence over 'full_range'.

spatial_correction

only apply on RIF file, whether to apply spatial correction. Default is FALSE.

Details

When a mask is detected, 'add_noise', 'full_range' and 'force_range' are set to FALSE and range used will be forced to [0,3].

Range of image is controlled by 'Images' information from supplied 'info' or as extracted by getInfo and will be returned as 'channels' by objectParam. In case 'mode' is not "raw", 'channels$xmin', 'channels$xmax', 'channels$gamma' will be used for object extraction by objectExtract unless any of 'force_range' or 'full_range' is TRUE.

Experimental (as of v0.2.0.501): once returned by objectParam, those 'channels$xmin' and 'channels$xmax' can be manually adjusted to ]0,1[ so as to be used as 'probs' argument to quantile to allow quantile normalization during object extraction (objectExtract) afterwards.

Examples

if(requireNamespace("IFCdata", quietly = TRUE)) {
  ## use a cif file
  file_cif <- system.file("extdata", "example.cif", package = "IFCdata")
  cif_offs <- getOffsets(fileName = file_cif, fast = TRUE)
  ## extract infomation
  info <- getInfo(fileName = file_cif, from = "analysis")
  ## retrieve number of objects stored
  nobj <- as.integer(info$objcount)
  ## randomly subset the offsets of at most 5 "img" objects
  sel = sample(0:(nobj-1), min(5, nobj))
  sub_offs <- subsetOffsets(cif_offs, objects = sel, image_type = "img")
  ## read IFDs from these "img" objects
  IFDs <- getIFD(fileName = file_cif, offsets = sub_offs)
  ## extract raw data of these"img" objects to matrix
  raw = objectExtract(ifd = IFDs, info = info, mode = "raw", 
                      export = "matrix")
  ## extract base64 "rgb" colorized version of these "img" objects to base64
  b64 = objectExtract(ifd = IFDs, info = info, mode = "rgb", 
                      export = "base64", base64_id = TRUE,
                      write_to = "example_%o_%c.bmp")
  ## use DisplayGallery to show the first "img" objects and play with ... extra parameters
  ## force_range, add_noise, selection, composite, see objectParam
  DisplayGallery(info = info, offsets = cif_offs, objects = sel,
                 base64_id = TRUE, write_to = "example_%o_%c.bmp",
                 force_range = c(FALSE,TRUE,FALSE,TRUE), add_noise = FALSE,
                 selection = c(1,2,4,6), composite = "1.7/4.3")
} 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.'))
}