N4 bias field correction — n4BiasFieldCorrection • ANTsR

Perform N4 bias field correction on the given image

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

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, vector of maximum number of iterations for each shrinkage factor, 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 in ANTsR/ANTsPy is 200 mm per mesh element in each dimension. The ANTs default is a mesh size of 1 per dimension.
returnBiasField: bool, return the field instead of the corrected image.
verbose: enables verbose output.
weightMask: antsImage of weight mask

Value

bias corrected image or bias field

Author

BB Avants

Examples

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

rm(img)
gc()
#>           used  (Mb) gc trigger  (Mb) limit (Mb) max used  (Mb)
#> Ncells 4250734 227.1    6681702 356.9         NA  6681702 356.9
#> Vcells 7191168  54.9   16551593 126.3     102400 16551592 126.3
rm(n4img)
gc()
#>           used  (Mb) gc trigger  (Mb) limit (Mb) max used  (Mb)
#> Ncells 4250313 227.0    6681702 356.9         NA  6681702 356.9
#> Vcells 7190498  54.9   16551593 126.3     102400 16551592 126.3
fname <- getANTsRData("r16")
in_img <- antsImageRead(fname)
n4 <- n4BiasFieldCorrection(in_img)
rm(n4)
gc()
#>           used  (Mb) gc trigger  (Mb) limit (Mb) max used  (Mb)
#> Ncells 4250370 227.0    6681702 356.9         NA  6681702 356.9
#> Vcells 7190589  54.9   16551593 126.3     102400 16551592 126.3
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{
n4 <- n4BiasFieldCorrection(in_img, mask = mask, verbose = TRUE)
# fails
n4 <- n4BiasFieldCorrection(in_img, mask = mask2)
} # }