objectParam {IFC}

Object Extraction Parameters Definition

Description

Defines 'IFC_object' object extraction parameters.

Usage

objectParam(
  ...,
  info,
  mode = c("rgb", "gray", "raw")[3],
  export = c("file", "matrix", "base64")[2],
  write_to,
  base64_id = FALSE,
  base64_att = "",
  overwrite = FALSE,
  composite = "",
  selection = "all",
  size = c(0, 0),
  force_width = TRUE,
  random_seed = NULL,
  removal = "none",
  add_noise = TRUE,
  full_range = FALSE,
  force_range = FALSE,
  spatial_correction = FALSE
)

Arguments

...

arguments to be passed to getInfo, only if 'info' is not provided.

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.

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.

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.

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.

Value

an object of class 'IFC_param'.