RootscanR (version 0.0.1)

stitchImgs: Stitch images

Description

stitchImgs - This function stitches all specified images (currently only PNGs supported) together in a line. It also searches for the best overlap between two consecutive images (see parameters and findOverlap()). If overlap_px is already known, this function calls blendImgs().

blendImgs - This function stitches all specified images together in a line according to specified overlap widths.

Usage

stitchImgs(
  img_paths = NULL,
  imgs = NULL,
  out_file = NULL,
  overlap_px = NULL,
  max_shift_px = NULL,
  perc_better_per_px = 0.01,
  corr_formula = "1-rel_eucl_diff_colors",
  stitch_direction = "left_to_right",
  blending_mode = "under",
  show_messages = TRUE
)
blendImgs(
  img_paths = NULL,
  imgs = NULL,
  out_file = NULL,
  overlap_px,
  stitch_direction = "left_to_right",
  blending_mode = "under"
)

Value

stitchImgs The stitched image in the form of a PNG, i.e., an array with 3 dimensions (3 layers each containing a 2-dim. numeric matrix with values between 0 and 1).

blendImgs The stitched image in the form of a PNG, i.e., an array with 3 dimensions (3 layers each containing a 2-dim. numeric matrix with values between 0 and 1).

Arguments

img_paths

(Optional, default = NULL) Character vector specifying all of the individual image paths of interest. This is only used if imgs is set to NULL. For ImageCorr() it must have length 2.

imgs

List of images (e.g., provided by the RootDetector). Each image can be a PNG, i.e., an array with 3 dimensions (3 layers each containing a 2-dim. numeric matrix with values between 0 and 1), or a 2-dim. matrix. For ImageCorr() it must have length 2.

out_file

Full path for how the stitched image should be saved, e.g. 'C:/path/stitched.png'. If no path is provided, the image is not saved (only returned).

overlap_px

Numeric vector (default NULL) specifying the (likely) widths of the overlaps between two consecutive images. The vector must have one element less than there are images and must not contain any negative values.

max_shift_px

Numeric vector (default NULL) specifying the maximal deviation in pixels from the overlap_px, i.e., all possible overlaps in that range from the likely overlap are compared and the best is chosen if it is better than the overlap_px (see also perc_better_per_px). If overlap_px is already exact, then set max_shift_px to zero(s). If at NULL, it is set to 10 percent of the image.

perc_better_per_px

Numeric value (percentage, default 0.01, i.e., 1 percent) specifying how much better the correlation of an overlap must be than the overlap_px per pixel difference, to be selected instead. If set to 0, the overall best correlation determines the overlap. Example: If set to 0.01 = 1 percent, an overlap being 4 pixels away from the specified overlap_px must have a correlation 4*1 percent better than overlap_px to be chosen as the better overlap.

corr_formula

Character value specifying the formula to be used (by default 1) for calculating how good an overlap of two images is, i.e., how similar the two overlapping images are. Available are the following formulas:

• "frac_matches_rgb_intensities": Fraction of matching intensities over all three color channels. Only suitable for images with few unique colors. Ranges from 0 (no matches) to 1 (full match).
  

• "frac_matches_colors": Fraction of matching colors in the images. Only suitable for images with few unique colors. Ranges from 0 (no matches) to 1 (full match).
  

• "weighted_matches_b_w": Counts the matches of black and white pixels and weighs them anti-proportional to the black and white pixel frequencies. Both black and white make up half of the correlation score. Only suitable for images with mostly pure black and white pixels. Ranges from 0 (no matches) to 1 (full match).
  

• "weighted_matches_colors": Counts the matches per unique color and weighs them anti-proportional to the frequencies of the colors. Each unique color makes up the same fraction of the correlation score. Only suitable for images with few unique colors. Ranges from 0 (no matches) to 1 (full match).
  

• "1-rel_sqrd_diff_rgb_intensities": One minus the relative squared difference of intensities across all color channels. Ranges from 0 (no matches) to 1 (full match).
  

• "1-rel_abs_diff_rgb_intensities": One minus the relative absolute difference of intensities across all color channels. Ranges from 0 (no matches) to 1 (full match).
  

• "1-rel_eucl_diff_colors" (default): One minus the relative Euclidean differences of colors. Ranges from 0 (no matches) to 1 (full match).

stitch_direction

Character specifying in which order the images should be stitched. Available are: 'left_to_right' (default), 'right_to_left', 'top_to_bottom', and 'bottom_to_top'.

blending_mode

Character value specifying how overlapping pixels are combined. Available are:

• "under" (default): The first image(s) dominate(s), and only non-overlapping parts of further images contribute.
  

• "over": The next image completely replaces the previous image in the overlap.
  

• "average": The RGB values of overlapping regions are averaged.
  

• "max": The maximal RGB values from both images are chosen.
  

• "min": The minimal RGB values from both images are chosen.

show_messages

Specify if messages should be depicted (default TRUE).

Examples

# Small example of stitching two 3x4 matrices left to right together.
test <- stitchImgs(imgs = list(matrix(c(1,0,0,0,
                                        0,1,0,0,
                                        0,0,1,1), ncol = 4, nrow = 3,
                                      byrow = TRUE),
                               matrix(c(0,0,0,0,
                                        1,0,0,1,
                                        0,1,1,0), ncol = 4, nrow = 3,
                                      byrow = TRUE)),
           overlap_px = 1, max_shift_px = 2)
# The stitched image also contains the overlaps used for stitching.
attributes(test)
# Example of stitching the two matrices with a fixed (in this case not
# optimal) overlap.
blendImgs(imgs = list(matrix(c(1,0,0,0,
                               0,1,0,0,
                               0,0,1,1), ncol = 4, nrow = 3, byrow = TRUE),
                      matrix(c(0,0,0,0,
                               1,0,0,1,
                               0,1,1,0), ncol = 4, nrow = 3, byrow = TRUE)),
          overlap_px = 1, blending_mode = "over")[,,1]