coregisterImages { RStoolbox}R Documentation

Image to Image Co-Registration based on Mutual Information

R: Image to Image Co-Registration based on Mutual Information


Shifts a slave image to match the reference image (master). Match is based on maximum mutual information.


coregisterImages(slave, master, shift = 3, shiftInc = 1,
  nSamples = 1e+05, reportStats = FALSE, verbose, nBins = 100, ...)



Raster* object. Slave image to shift to master. Slave and master must have equal numbers of bands.


Raster* object. Reference image. Slave and master must have equal numbers of bands.


Numeric or matrix. If numeric, then shift is the maximal absolute radius (in pixels of slave resolution) which slave is shifted (seq(-shift, shift, by=shiftInc)). If shift is a matrix it must have two columns (x shift and y shift), then only these shift values will be tested.


Numeric. Shift increment (in pixels, but not restricted to integer). Ignored if shift is a matrix.


Integer. Number of samples to calculate mutual information.


Logical. If FALSE it will return only the shifted images. Otherwise it will return the shifted image in a list containing stats such as mutual information per shift and joint histograms.


Logical. Print status messages. Overrides global RStoolbox.verbose option.


Integer. Number of bins to calculate joint histogram.


further arguments passed to writeRaster.


Currently only a simple linear x - y shift is considered and tested. No higher order shifts (e.g. rotation, non-linear transformation) are performed. This means that your imagery should already be properly geometrically corrected.

Mutual information is a similarity metric originating from information theory. Roughly speaking, the higher the mutual information of two data-sets, the higher is their shared information content, i.e. their similarity. When two images are exactly co-registered their mutual information is maximal. By trying different image shifts, we aim to find the best overlap which maximises the mutual information.


reportStats=FALSE returns a Raster* object (x-y shifted slave image). reportStats=TRUE returns a list containing a data.frame with mutual information per shift ($MI), the shift of maximum MI ($bestShift), the joint histograms per shift in a list ($jointHist) and the shifted image ($coregImg).


reference <- rlogo
## Shift reference 2 pixels to the right and 3 up
missreg <- shift(reference,  2,  3)

## Compare shift
p <- ggR(reference, sat = 1, alpha = .5) 
p + ggR(missreg, sat = 1, hue = .5, alpha = 0.5, ggLayer=TRUE) 

plot of chunk unnamed-chunk-1

## Coregister images (and report statistics)
coreg <- coregisterImages(missreg, master = reference,
                         nSamples = 500, reportStats = TRUE)

## Plot mutual information per shift
ggplot(coreg$MI) + geom_raster(aes(x,y,fill=mi))

plot of chunk unnamed-chunk-1

## Plot joint histograms per shift (x/y shift in facet labels)
## No test: 

df <- melt(coreg$jointHist)   
df$L1 <- factor(df$L1, levels = names(coreg$jointHist))
df[df$value == 0, "value"] <- NA ## don't display p = 0
ggplot(df) + geom_raster(aes(x = Var2, y = Var1,fill=value)) + facet_wrap(~L1) + 
       scale_fill_gradientn(name = "p", colours =  heat.colors(10), na.value = NA)
#> Warning: Removed 438677 rows containing missing values (geom_raster).

plot of chunk unnamed-chunk-1

## End(No test)
## Compare correction
ggR(reference, sat = 1, alpha = .5) +
  ggR(coreg$coregImg, sat = 1, hue = .5, alpha = 0.5, ggLayer=TRUE) 

plot of chunk unnamed-chunk-1

[Package RStoolbox version 0.2.6 Index]