#' Plots a matrix as an image
#'
#' @param A a matrix to be plotted
#' @param add.values boolean indicating if matrix values are to be written into
#'  matrix element boxes
#' @param main overall title for the plot
#' @param sub sub-title of the plot
#' @param interpolate a logical vector (or scalar) indicating whether to apply
#'  linear interpolation to the image when drawing.
#' @param ... further arguments passed to \code{\link{rasterImage}}
#'
#' @examples
#' AR <- 0.5^abs(outer(1:10, 1:10, `-`))
#' matrixImage(AR, AR > 0.2, main = "Autoregressiv Covariance")
#'
#' @export
matrixImage <- function(A, add.values = FALSE,
    main = NULL, sub = NULL, interpolate = FALSE, ...,
    digits = getOption("digits")
) {
    # plot raster image
    plot(c(0, ncol(A)), c(0, nrow(A)), type = "n", bty = "n", col = "red",
        xlab = "", ylab = "", xaxt = "n", yaxt = "n", main = main, sub = sub)

    # Scale values of `A` to [0, 1] with min mapped to 1 and max to 0.
    S <- (max(A) - A) / diff(range(A))

    # Raster Image ploting the matrix with element values mapped to grayscale
    # as big elements (original matrix A) are dark and small (negative) elements
    # are white.
    rasterImage(S, 0, 0, ncol(A), nrow(A), interpolate = interpolate, ...)

    # Add X-axis giving index
    x <- seq(1, ncol(A), by = 1)
    axis(1, at = x - 0.5, labels = x, lwd = 0, lwd.ticks = 1)
    # Add Y-axis
    y <- seq(1, nrow(A))
    axis(2, at = y - 0.5, labels = rev(y), lwd = 0, lwd.ticks = 1, las = 1)

    # Writes matrix values (in colored element grids)
    if (any(add.values)) {
        if (length(add.values) > 1) {
            A[!add.values] <- NA
            A[add.values] <- format(A[add.values], digits = digits)
        }
        text(rep(x - 0.5, each = nrow(A)), rep(rev(y - 0.5), ncol(A)), A,
             adj = 0.5, col = as.integer(S > 0.65))
    }
}