N3 Bias field correction

Perform N3 bias field correction on the given image

n3BiasFieldCorrection2(
  img,
  mask,
  rescaleIntensities = FALSE,
  shrinkFactor = 4,
  convergence = list(iters = 50, tol = 1e-07),
  splineParam = 200,
  numberOfFittingLevels = 4,
  weightMask = NULL,
  returnBiasField = FALSE,
  verbose = FALSE
)

Arguments

img

input antsImage

mask

input mask, if one is not passed one will be made

rescaleIntensities

At each iteration, a new intensity mapping is calculated and applied but there is nothing which constrains the new intensity range to be within certain values. The result is that the range can "drift" from the original at each iteration. This option rescales to the [min,max] range of the original image intensities within the user-specified mask. A mask is required to perform rescaling. Default is FALSE in ANTsR/ANTsPy but TRUE in ANTs.

shrinkFactor

Shrink factor for multi-resolution correction, typically integer less than 4

convergence

List of: iters, maximum number of iterations and tol, the convergence tolerance. Default tolerance is 1e-7 in ANTsR/ANTsPy but 0.0 in ANTs.

splineParam

Parameter controlling number of control points in spline. Either single value, indicating how many control points, or vector with one entry per dimension of image, indicating the spacing in each direction. Default is a mesh size of 1 per dimension.

numberOfFittingLevels

Parameter controlling number of fitting levels.

weightMask

antsImage of weight mask

returnBiasField

bool, return the field instead of the corrected image.

verbose

enables verbose output.

Value

bias corrected image or bias field

Author

Avants BB, Tustison NJ

Examples

dims <- c(50, 50)
img <- makeImage(imagesize = dims, rnorm(prod(dims)))
n3img <- n3BiasFieldCorrection2(img)
n3img <- n3BiasFieldCorrection2(img, mask = img > 0)
testthat::expect_error(n3BiasFieldCorrection2(img, weightMask = "somepath"))
testthat::expect_error(n3BiasFieldCorrection2(img, splineParam = rep(200, 3)))
# n3img<-n3BiasFieldCorrection2(img, splineParam = c(200, 20)) # long running

rm(img)
gc()
#>            used  (Mb) gc trigger  (Mb) limit (Mb) max used  (Mb)
#> Ncells  4186193 223.6    7574517 404.6         NA  5814732 310.6
#> Vcells 12339792  94.2   22785357 173.9     102400 22785327 173.9
rm(n3img)
gc()
#>            used  (Mb) gc trigger  (Mb) limit (Mb) max used  (Mb)
#> Ncells  4186018 223.6    7574517 404.6         NA  5814732 310.6
#> Vcells 12339532  94.2   22785357 173.9     102400 22785327 173.9
fname <- getANTsRData("r16")
in_img <- antsImageRead(fname)
n3 <- n3BiasFieldCorrection2(in_img)
rm(n3)
gc()
#>            used  (Mb) gc trigger  (Mb) limit (Mb) max used  (Mb)
#> Ncells  4186075 223.6    7574517 404.6         NA  5814732 310.6
#> Vcells 12339623  94.2   22785357 173.9     102400 22785327 173.9
mask <- in_img > 0
mask2 <- antsImageClone(mask, out_pixeltype = "float")
# fails
mask
#> antsImage
#>   Pixel Type          : unsigned char 
#>   Components Per Pixel: 1 
#>   Dimensions          : 256x256 
#>   Voxel Spacing       : 1x1 
#>   Origin              : 0 0 
#>   Direction           : 1 0 0 1 
#> 
sum(mask)
#> [1] 19278
if (FALSE) { # \dontrun{
n3 <- n3BiasFieldCorrection2(in_img, mask = mask, verbose = TRUE)
# fails
n3 <- n3BiasFieldCorrection2(in_img, mask = mask2)
} # }