rcaiman (version 2.0.1)

read_caim: Read a canopy image from a file

Description

Reads a born-digital image (typically RGB-JPEG or RGB-TIFF) using terra::rast() and returns a terra::SpatRaster object. Optionally, it can extract a rectangular region of interest (ROI) specified by the user.

Usage

read_caim(path = NULL, upper_left = NULL, width = NULL, height = NULL)

Value

Numeric terra::SpatRaster, typically with layers named "Red", "Green", and "Blue". If the file format or metadata prevents automatic layer naming, names will be inferred and a warning may be issued.

Arguments

path

character vector of length one. Path to an image file, including extension. If NULL, an example image is returned.

upper_left

numeric vector of length two. Pixel coordinates of the upper-left corner of the ROI, in the format c(column, row).

width, height

numeric vector of length one. Size (in pixels) of the rectangular ROI to read.

Selecting a Region of Interest

To load a specific subregion from the image, use the arguments upper_left, width, and height. These are expressed in raster coordinates, similar to a spreadsheet layout: columns first, then rows. In other words, specify coordinates as c(column, row), not c(row, column), which is typical in data.frame objects.

While any image editor can be used to obtain these values, this function was tested with ImageJ, particularly the Fiji distribution. A recommended workflow:

1. Open the image in Fiji.

2. Draw a rectangular selection.

3. Go to Edit > Selection > Specify... to read upper_left, width, and height.

Details

This function is intended for importing color hemispherical photographs, such as those obtained with digital cameras equipped with fisheye lenses. For raw image files (e.g., NEF, CR2), see read_caim_raw().

Internally, this is a wrapper around terra::rast(), so support for image formats depends on the capabilities of the terra package.

If no arguments are provided, a sample image will be returned.

See Also

write_caim()

Examples

path <- system.file("external/DSCN4500.JPG", package = "rcaiman")
zenith_colrow <- c(1276, 980)
diameter <- 756*2
caim <- read_caim(path, zenith_colrow - diameter/2, diameter, diameter)
plot(caim$Blue)