Threshold every image frame in an image stack based on their mean.

Source: R/stack_thresh.R

An ijtiff_img is a 4-dimensional array indexed by img[y, x, channel, frame]. For each channel (which consists of a stack of frames), this function finds a threshold based on the sum all of the frames, uses this to create a mask and then applies this mask to every frame in the stack (so for a given pillar in the image stack, either all the pixels therein are thresholded away or all are untouched, where pillar x,y of channel ch is img[y, x, ch, ]).

mean_stack_thresh(
  img,
  method,
  fail = NA,
  ignore_black = FALSE,
  ignore_white = FALSE,
  ignore_na = FALSE
)

Arguments

img

A 4-dimensional array in the style of an ijtiff_img (indexed by img[y, x, channel, frame]) or a 3-dimensional array which is a single channel of an ijtiff_img (indexed by img[y, x, frame]).

method

The name of the thresholding method you wish to use. The available methods are "IJDefault", "Huang", "Huang2", "Intermodes", "IsoData", "Li", "MaxEntropy", "Mean", "MinErrorI", "Minimum", "Moments", "Otsu", "Percentile", "RenyiEntropy", "Shanbhag", "Triangle" and "Yen". Partial matching is performed i.e. method = "h" is enough to get you "Huang" and method = "in" is enough to get you "Intermodes". To perform manual thresholding (where you set the threshold yourself), supply the threshold here as a number e.g. method = 3.8 (so note that this would not select the third method in the above list of methods). This manual threshold will then be used to threshold the sum stack to create a 2D mask and then this mask will be applied to all frames in the stack. If you want a different method for each channel, specify this parameter as a vector or list, one element per channel.

fail

When using auto_thresh_apply_mask(), to what value do you wish to set the pixels which fail to exceed the threshold? fail = 'saturate' sets them to saturated value (see 'Details'). fail = 'zero' sets them to zero. You can also specify directly here a natural number (must be between 0 and 2^16 - 1) to use.

ignore_black

Ignore black pixels/elements (zeros) when performing the thresholding?

ignore_white

Ignore white pixels when performing the thresholding? If set to TRUE, the function makes a good guess as to what the white (saturated) value would be (see 'Details'). If this is set to a number, all pixels with value greater than or equal to that number are ignored.

ignore_na

This should be TRUE if NAs in int_arr should be ignored or FALSE if you want the presence of NAs in int_arr to throw an error.

Value

An object of class stack_threshed_img which is the thresholded image (an array in the style of an ijtiff_img). Pillars not exceeding the threshold are set to the fail value (default NA).

Details

It's called mean_stack_thresh() and not sum_stack_thresh() because its easier for people to visualize the mean of an image series than to visualize the sum, but for the sake of this procedure, both are equivalent, except for the fact that the thresholding routine invoked inside this function prefers integers, which we get by using a sum but not by using a mean.

  • For ignore_white = TRUE, if the maximum value in the array is one of 2^8-1, 2^16-1 or 2^32-1, then those max values are ignored. That's because they're the white values in 8, 16 and 32-bit images respectively (and these are the common image bit sizes to work with). This guesswork has to be done because R does not know how many bits the image was on disk. This guess is very unlikely to be wrong, and if it is, the consequences are negligible anyway. If you're very concerned, then just specify the white value as an integer in this ignore_white argument.

  • If you have set ignore_black = TRUE and/or ignore_white = TRUE but you are still getting error/warning messages telling you to try them, then your chosen method is not working for the given array, so you should try a different method.

  • For a given array, if all values are less than 2^8, saturated value is 2^8 - 1, otherwise, saturated value is 2^16 - 1.

Examples

# \donttest{
img <- ijtiff::read_tif(system.file("extdata", "50.tif",
  package = "autothresholdr"
))
#> Reading 50.tif: an 8-bit, 100x100 pixel image of unsigned
#> integer type. Reading 1 channel and 50 frames . . .
#> Done.
ijtiff::display(img[, , 1, 1])
#> Using basic display functionality.
#>   * For better display functionality, install the EBImage package.
#>   * To install `EBImage`:
#>     - Install `BiocManager` with `install.packages("BiocManager")`.
#>     - Then run `BiocManager::install("EBImage")`.

img_thresh_mask <- mean_stack_thresh(img, "Otsu")
ijtiff::display(img_thresh_mask[, , 1, 1])
#> Using basic display functionality.
#>   * For better display functionality, install the EBImage package.
#>   * To install `EBImage`:
#>     - Install `BiocManager` with `install.packages("BiocManager")`.
#>     - Then run `BiocManager::install("EBImage")`.

ijtiff::display(img[, , 1, 1])
#> Using basic display functionality.
#>   * For better display functionality, install the EBImage package.
#>   * To install `EBImage`:
#>     - Install `BiocManager` with `install.packages("BiocManager")`.
#>     - Then run `BiocManager::install("EBImage")`.

img_thresh_mask <- mean_stack_thresh(img, "Huang")
ijtiff::display(img_thresh_mask[, , 1, 1])
#> Using basic display functionality.
#>   * For better display functionality, install the EBImage package.
#>   * To install `EBImage`:
#>     - Install `BiocManager` with `install.packages("BiocManager")`.
#>     - Then run `BiocManager::install("EBImage")`.

# }