contrastProjection: Maximum contrast projection of a 3D image stack
In MaxContrastProjection: Perform a maximum contrast projection of 3D images along the z-dimension into 2D

Description Usage Arguments Details Value Functions Author(s) Examples

View source: R/projection.R

Projects a z-stack of 2D images according to the highest local contrast. Optionally, median smoothing can be applied to the resulting projection index map prior to the projection itself.

getContrastStack(imageStack, w_x, w_y, brushShape = "disc", validate = TRUE)

getIndexMap(contrastStack, smoothing = 0, validate = TRUE)

contrastProjection(imageStack, w_x, w_y = NULL, smoothing = 0,
    brushShape = "disc", interpolation = 0, fix.gaussian.blur = FALSE,
    blur.size = 0, return.all = FALSE)

projection_fromMap(imageStack, indexMap, interpolation = 0, validate = TRUE)

`imageStack`	A numeric 3D array-like which should ne projected. The dimensions should be (spatial_1, spatial_2, numer_of_images)
`w_x`	The size of the window in x-direction
`w_y`	The size of the window in y-direction
`brushShape`	A string indicating the shape of the window. Currently supported values are `"box", "disc"` and "disc" is the default
`validate`	A boolean value indicating if the variables need to be validated or if this function is being called internally, i.e. the variables have already been validated once. This is only used to marginally speed up internal calls to functions and has no bearing on the actual functionality of the method.
`contrastStack`	A numeric 3D array-like which contains the local contrasts for each image in `imageStack` at each pixel
`smoothing`	The size of the median filter window. If this is 0, median smoothing is not applied.
`interpolation`	The size of the blurring kernel to use when interpolating values at the boundaries of regions in the index map. Set to 0 for no interpolation.
`fix.gaussian.blur`	A logical value indicating whether the false gaussian blur caused by unfocused images should be fixed or not (see vignette for more details on this).
`blur.size`	An integer indicating the radius of the gaussian blur. Ignored unless `fix.gaussian.blur = TRUE`. The total diameter of the brush is defined as 2*blur.size+1, meaning that a 'blur.size' value of 0 will result in a 1x1 pixel brush.
`return.all`	A logical value indicating whether only the projection should be returned (FALSE) or if all intermediate results should be returned as well, including the index map and the contrast stack (TRUE)
`indexMap`	A custom index map according to which the image stack is projected. The values must be integers between 1 and the number of layers in `imageStack`

The local contrast for every image in the stack is determined using calcContrast. getContrastStack returns this stack of contrast maps. Then, the z-layer with the highest local contrast is determined for each pixel in the (x,y)-plane, resulting in an index map with the same spatial dimensions as the input images. This index map can then be smoothed with a median filter if desired. getIndexMap returns this index map. Lastly, the image stack is projected into the (x,y)-plane using this index map to determine which z-layer to use at every pixel. contrastProjection returns this fully projected image.

The brushShape indicates the shape of the window over which to calculate the variance. Depending on the symmetry of the objects being imaged, the window shape may have a significant impact on the quality of the projection.

If an object lies in several focal plains then the projection may include some artifical boundaries at the edges of the regions in each focal plain. Linear interpolation between the two layers at their boundaries serves to eliminate this problem. The interpolation size gives the size of the kernel to use for blurring the boundaries between individual regions of the index map. The projection values at these boundaries are then interpolated based on the non-integer values on the index maps. For example, if a pixel on the index map has the value 7.25, then the projected value at this pixel is 75

If a very bright object lies on a dark background, then the gaussian blurring of the unfocused image stacks can create a brighter ring structure around this object. Fixing this involves Voronoi propagation into the regions directly surrounding bright objects. This correction only makes sense if there is a clear differentiation between fore- and background in the image. A perfect segmentation is unnecessary as the rings will only appear around exceptionally bright objects, which are easy to segment.

contrastProjection: A 2D matrix corresponding to the maximum contrast projection of imageStack
getIndexMap: A 2D matrix indicating the z-layer with the maximum contrast at every pixel in the (x,y)-plane of imageStack
getContrastStack: a 3D array corresponding to the contrast map for every image of imageStack
projection_fromMap: A 2D matrix corresponding to the maximum contrast projection of imageStack

getContrastStack: Get the full stack of contrast maps for each image in the image stack
getIndexMap: Get the index map (with or without smoothing) which indicates the layer corresponding to the highest contrast for each pixel in the (x,y)-plane
projection_fromMap: Get the index map (with or without smoothing) which indicates the layer corresponding to the highest contrast for each pixel in the (x,y)-plane

Jan Sauer

1
2
3

print(contrastProjection)
print(getIndexMap)
print(getContrastStack)

function (imageStack, w_x, w_y = NULL, smoothing = 0, brushShape = "disc", 
    interpolation = 0, fix.gaussian.blur = FALSE, blur.size = 0, 
    return.all = FALSE) 
{
    if (missing(imageStack)) 
        stop("'imageStack' is missing")
    if (missing(w_x)) 
        stop("'w_x' is missing")
    if (is.null(w_y)) 
        w_y = w_x
    if (class(imageStack) == "Image") 
        imageStack = imageData(imageStack)
    valid = validateVariables(imageStack = imageStack, w_x = w_x, 
        w_y = w_y, smoothing = smoothing, brushShape = brushShape, 
        fix.gaussian.blur = fix.gaussian.blur, blur.size = blur.size, 
        return.all = return.all)
    contrast_stack = getContrastStack(imageStack = imageStack, 
        w_x = w_x, w_y = w_y, brushShape = brushShape, validate = FALSE)
    index_map = getIndexMap(contrastStack = contrast_stack, smoothing = smoothing, 
        validate = FALSE)
    if (fix.gaussian.blur) 
        index_map = fixGaussianBlur(imageStack = imageStack, 
            indexMap = index_map, blur.size = blur.size)
    proj = projection_fromMap(imageStack = imageStack, indexMap = index_map, 
        interpolation = interpolation)
    if (return.all == FALSE) 
        return(proj)
    if (return.all == TRUE) 
        return(list(Contrast.Stack = contrast_stack, Index.Map = index_map, 
            Projection = proj))
}
<environment: namespace:MaxContrastProjection>
function (contrastStack, smoothing = 0, validate = TRUE) 
{
    if (missing(contrastStack)) 
        stop("'contrastStack' is missing")
    if (missing(smoothing)) 
        stop("'smoothing' is missing")
    if (validate) 
        valid = validateVariables(contrastStack = contrastStack, 
            smoothing = smoothing)
    index_map = apply(contrastStack, c(1, 2), function(x) which(x == 
        max(x))[1])
    if (smoothing > 0) {
        max_id = max(index_map)
        index_map = round(medianFilter(index_map/max_id, smoothing) * 
            max_id)
    }
    return(index_map)
}
<environment: namespace:MaxContrastProjection>
function (imageStack, w_x, w_y, brushShape = "disc", validate = TRUE) 
{
    if (missing(imageStack)) 
        stop("'imageStack' is missing")
    if (missing(w_x)) 
        stop("'w_x' is missing")
    if (missing(w_y)) 
        stop("'w_y' is missing")
    if (class(imageStack) == "Image") 
        imageStack = imageData(imageStack)
    if (validate) 
        valid = validateVariables(imageStack = imageStack, w_x = w_x, 
            w_y = w_y, brushShape = brushShape)
    img_frames = getFrames(imageStack)
    contrast_stack = lapply(img_frames, calcContrast, w_x, w_y, 
        brushShape)
    contrast_stack = combine(contrast_stack)
    return(imageData(contrast_stack))
}
<environment: namespace:MaxContrastProjection>