Package 'rcaiman'

Description

Global or local thresholding of images.

Usage

apply_thr(r, thr)

Arguments

Details

It is a wrapper function around the operator > from the terra package. If a single threshold value is provided as the thr argument, it is applied to every pixel of the object r. If instead a SpatRaster is provided, a particular threshold is applied to each particular pixel.

Value

An object of class SpatRaster with values 0 and 1.

See Also

Other Binarization Functions: obia(), ootb_mblt(), ootb_obia(), regional_thresholding(), thr_isodata(), thr_mblt()

Examples

r <- read_caim()
bin <- apply_thr(r$Blue, thr_isodata(r$Blue[]))
plot(bin)
## Not run: 
# This function is useful in combination with the ‘autothresholdr’
# package. For example:
require(autothresholdr)
thr <- auto_thresh(r$Blue[], "IsoData")[1]
bin <- apply_thr(r$Blue, thr)
plot(bin)

## End(Not run)

Description

Build a single-layer image with azimuth angles as pixel values, assuming upwards-looking hemispherical photography with the optical axis vertically aligned.

Usage

azimuth_image(z, orientation = 0)

Arguments

Value

An object of class SpatRaster with azimuth angles in degrees. If the orientation argument is zero, North (0º) is pointing up as in maps, but East (90º) and West (270º) are flipped regarding to maps. To understand why, take two flash-card size pieces of paper; put one on a table in front of you and draw on it a compass rose; take the other and hold it with your arms extended over your head and, following the directions of the compass rose in front of you, draw another one in the paper side that is facing down—it will be an awkward position, like if you were taking an upward-looking photo with a mobile device while looking at the screen—; finally, put it down and compare both compass roses.

See Also

Other Lens Functions: calc_diameter(), calc_relative_radius(), calc_zenith_colrow(), calibrate_lens(), crosscalibrate_lens(), expand_noncircular(), extract_radiometry(), fisheye_to_equidistant(), fisheye_to_pano(), lens(), test_lens_coef(), zenith_image()

Examples

z <- zenith_image(600, lens("Nikon_FCE9"))
a <- azimuth_image(z)
plot(a)
## Not run: 
a <- azimuth_image(z, 45)
plot(a)

## End(Not run)

Description

Calculate canopy openness

Usage

calc_co(bin, z, a, m = NULL, angle_width = 10)

Arguments

Details

Canopy openness calculated as in the equation from Gonsamo et al. (2011):

$CO = \sum_{i = 1}^{N} GF(\phi_i, \theta_i) \cdot [(cos(\theta_1) - cos(\theta_2))/n]$,

where $GF(\phi_i, \theta_i)$ is the gap fraction of the cell $i$, $\theta_1$ and $\theta_2$ are the minimum and maximum zenith angle of the cell $i$, $n$ is the number of cells on the ring delimited by $\theta_1$ and $\theta_2$, and $N$ is the total number of cells.

When a mask is provided through the m argument, the equation is modified as follow:

$\frac{ CO = \sum_{i = 1}^{N} GF(\phi_i, \theta_i) \cdot [(cos(\theta_1) - cos(\theta_2))/n] }{ \sum_{i = 1}^{N} (cos(\theta_1) - cos(\theta_2))/n}$.

This allows the masking of any individual cell.

Value

Numeric vector of length one.

References

Gonsamo A, Walter JN, Pellikka P (2011). “CIMES: A package of programs for determining canopy geometry and solar radiation regimes through hemispherical photographs.” Computers and Electronics in Agriculture, 79(2), 207–215. doi:10.1016/j.compag.2011.10.001.

Examples

caim <- read_caim()
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)
m <- mask_hs(z, 0, 70)
bin <- apply_thr(caim$Blue, thr_isodata(caim$Blue[m]))
plot(bin)
calc_co(bin, z, a, m, 10)

Description

Calculate the diameter in pixels of a 180º fisheye image.

Usage

calc_diameter(lens_coef, radius, angle)

Arguments

Details

This function helps handle devices with a field of view different than 180º. Given a lens projection function and data points consisting of radii (pixels) and their correspondent zenith angle ($\theta$), it returns the horizon radius (i.e., the radius for $\theta$ equal to 90º).

When working with non-circular hemispherical photography, this function will help to find the diameter that a circular image would have if the equipment would record the whole hemisphere.

The required data (radius-angle data pairs) can be obtained following the instructions given in the user manual of Hemisfer software. The following is a slightly simpler alternative:

• Find a vertical wall and a leveled floor, both well-constructed.

• Draw a triangle of $5 \times 4 \times 3$ meters on the floor, with the 4-meter side over the wall.

• Locate the camera over the vertex that is 3 meters away from the wall. Place it at a given height above the floor, 1.3 meters for instance.

• Make a mark on the wall at the chosen height over the wall-vertex nearest to the camera-vertex. Make four more marks with one meter of spacing and following a horizontal line. This will create marks for 0º, 18º, 34º, 45º, and 54º $\theta$.

• Before taking the photograph, do not forget to align the zenith coordinates with the 0º $\theta$ mark and check if the optical axis is leveled.

The line selection tool of ImageJ can be used to measure the distance in pixels between points on the image. Draw a line, and use the dropdown menu Analyze>Measure to obtain its length.

For obtaining the projection of a new lens, refer to calibrate_lens().

Value

Numeric vector of length one. Diameter adjusted to a whole number (see zenith_image() for details about that constrain).

See Also

Other Lens Functions: azimuth_image(), calc_relative_radius(), calc_zenith_colrow(), calibrate_lens(), crosscalibrate_lens(), expand_noncircular(), extract_radiometry(), fisheye_to_equidistant(), fisheye_to_pano(), lens(), test_lens_coef(), zenith_image()

Examples

# Nikon D50 and Fisheye Nikkor 10.5mm lens
calc_diameter(lens("Nikkor_10.5mm"), 1202, 54)

Description

The out-out-of-range (OOR) index is calculated as foollow:

Usage

calc_oor_index(r, sky)

Arguments

Details

$\sum_{i = 1}^{N}(r_i/sky_i)^2$,

where $r$ is a canopy image with relative radiance data, $sky$ is an image with unobstructed sky relative radiance data, $i$ is the index that represents the position of a given pixel on the raster grid, and $N$ is the total number of pixels that satisfy: $r_i/sky_i<0$ or $r_i/sky_i>1$.

Value

Numeric vector of length one.

See Also

Other Tool Functions: calc_sngd(), colorfulness(), correct_vignetting(), defuzzify(), expand_sky_points(), extract_dn(), extract_feature(), extract_rl(), extract_sky_points(), extract_sun_coord(), find_general_sky_type(), find_sky_pixels(), masking(), optim_normalize(), percentage_of_clipped_highlights(), read_bin(), read_caim(), read_caim_raw(), read_ootb_sky_model(), sor_filter(), write_bin(), write_caim(), write_ootb_sky_model()

Examples

## Not run: 
path <- system.file("external/DSCN4500.JPG", package = "rcaiman")
caim <- read_caim(path, c(1250, 1020) - 745, 745 * 2, 745 * 2)
z <- zenith_image(ncol(caim), lens("Nikon_FCE9"))
a <- azimuth_image(z)
r <- gbc(caim$Blue)
r <- correct_vignetting(r, z, c(0.0638, -0.101)) %>% normalize()

bin <- regional_thresholding(r, rings_segmentation(z, 30), "thr_isodata")
bin <- bin & mask_hs(z, 0, 80)
sky_points <- extract_sky_points(r, bin, sky_grid_segmentation(z, a, 3))
sky_points <- extract_rl(r, z, a, sky_points, no_of_points = NULL)

model <- fit_coneshaped_model(sky_points$sky_points)
summary(model$model)
sky_cs <- model$fun(z, a)
plot(r/sky_cs)
calc_oor_index(r, sky_cs)

## End(Not run)

Description

Calculate the relative radius given a zenith angle and lens function. This is known as the projection function.

Usage

calc_relative_radius(angle, lens_coef)

Arguments

See Also

Other Lens Functions: azimuth_image(), calc_diameter(), calc_zenith_colrow(), calibrate_lens(), crosscalibrate_lens(), expand_noncircular(), extract_radiometry(), fisheye_to_equidistant(), fisheye_to_pano(), lens(), test_lens_coef(), zenith_image()

Description

Calc sky-normalized green difference (SNGD)

Usage

calc_sngd(caim, z, a, bin, angle = 60, kern_size = 3)

Arguments

Value

Numeric vector of length one.

See Also

Other Tool Functions: calc_oor_index(), colorfulness(), correct_vignetting(), defuzzify(), expand_sky_points(), extract_dn(), extract_feature(), extract_rl(), extract_sky_points(), extract_sun_coord(), find_general_sky_type(), find_sky_pixels(), masking(), optim_normalize(), percentage_of_clipped_highlights(), read_bin(), read_caim(), read_caim_raw(), read_ootb_sky_model(), sor_filter(), write_bin(), write_caim(), write_ootb_sky_model()

Examples

## Not run: 
caim <- .caim <- read_caim()
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)
m <- !is.na(z)

r <- caim$Blue

bin <- regional_thresholding(r, rings_segmentation(z, 30),
                             method = "thr_isodata")
g <- sky_grid_segmentation(z, a, 10)
sun_coord <- extract_sun_coord(r, z, a, bin, g)
sun_coord$zenith_azimuth

.a <- azimuth_image(z, orientation = sun_coord$zenith_azimuth[2]+90)
seg <- sectors_segmentation(.a, 180) * rings_segmentation(z, 30)
bin <- regional_thresholding(r, seg, method = "thr_isodata")

mx <- optim_normalize(caim, bin)
caim <- normalize(caim, mx = mx, force_range = TRUE)
ecaim <- enhance_caim(caim, m, HSV(239, 0.85, 0.5))
bin <- apply_thr(ecaim, thr_isodata(ecaim[m]))

calc_sngd(.caim, z, a, bin)

## End(Not run)

Description

Calculate zenith raster coordinates from points digitized with the open-source software package ‘ImageJ’. The zenith is the point on the image that represents the zenith when upward-looking photographs are taken with the optical axis vertically aligned.

Usage

calc_zenith_colrow(path_to_csv)

Arguments

Details

The technique described under the headline ‘Optical center characterization’ of the user manual of the software Can-Eye can be used to acquire the data for determining the zenith coordinates. This technique was used by Pekin and Macfarlane (2009), among others. Briefly, it consists in drilling a small hole in the cap of the fisheye lens (it must be away from the center of the cap), and taking about ten photographs without removing the cap. The cap must be rotated about 30º before taking each photograph.(NOTE: The method implemented here does not support multiple holes).

The point selection tool of ‘ImageJ’ software should be used to manually digitize the white dots and create a CSV file to feed this function. After digitizing the points on the image, use the dropdown menu Analyze>Measure to open the Results window. To obtain the CSV file, use File>Save As...

Another method–only valid when enough of the circle perimeter is depicted in the image– is taking a very bright picture (for example, a picture of the corner of a room with walls painted in light colors) with the lens completely free (do not use any mount). Then, digitize points over the circle perimeter. This was the method used for producing the example file (see Examples). It is worth noting that the perimeter of the circle depicted in a circular hemispherical photograph is not necessarily the horizon.

Value

Numeric vector of length two. Raster coordinates of the zenith, assuming a lens facing up with its optical axis parallel to the vertical line. It is important to note the difference between the raster coordinates and the Cartesian coordinates. In the latter, the vertical axis value decreases downward, but the opposite is true for the raster coordinates, which works like a spreadsheet.

References

Pekin B, Macfarlane C (2009). “Measurement of crown cover and leaf area index using digital cover photography and its application to remote sensing.” Remote Sensing, 1(4), 1298–1320. doi:10.3390/rs1041298.

See Also

Other Lens Functions: azimuth_image(), calc_diameter(), calc_relative_radius(), calibrate_lens(), crosscalibrate_lens(), expand_noncircular(), extract_radiometry(), fisheye_to_equidistant(), fisheye_to_pano(), lens(), test_lens_coef(), zenith_image()

Examples

## Not run: 
path <- system.file("external/points_over_perimeter.csv",
                    package = "rcaiman")
calc_zenith_colrow(path)

## End(Not run)

Description

Calibrate a fisheye lens

Usage

calibrate_lens(path_to_csv, degree = 3)

Arguments

Details

Fisheye lenses have a wide field of view and the same distortion in all directions running orthogonally to the optical axis. The latter property allows fitting a precise mathematical relationship between distances to the zenith on the image space and zenith angles on the hemispherical space (assuming upward-looking hemispherical photography with the optical axis vertically aligned).

The method outlined here, known as the simple method, is explained in details in Díaz et al. (2024). Next explanation might serve mostly as a handbook.

Step-by-step guide for producing a CSV file to feed this function

Materials

• this package and ImageJ

• camera and lens

• tripod

• standard yoga mat

• table at least as wide as the yoga mat width

• twenty two push pins of different colors

• one print of this sheet (A1 size, almost like a research poster).

• scissors

• some patience

Instructions

Cut the sheet by the dashed line. Place the yoga mat extended on top of the table. Place the sheet on top of the yoga mat. Align the dashed line with the yoga mat border closest to you. Place push pins on each cross. If you are gentle, the yoga mat will allow you to do that without damaging the table. Of course, other materials could be used to obtain the same result, such as cardboard, foam, nails, etc.

Place the camera on the tripod. Align its optical axis with the table while looking for getting an image showing the overlapping of the three pairs of push pins, as instructed in the print. In order to take care of the line of pins at 90º relative to the optical axis, it may be of help to use the naked eye to align the entrance pupil of the lens with the pins. The alignment of the push pins only guarantees the position of the lens entrance pupil, the leveling should be cheeked with an instrument, and the alignment between the optical axis and the radius of the zenith push pin should be taken into account. In practice, the latter is achieved by aligning the camera body with the orthogonal frame made by the quarter circle.

Take a photo and transfer it to the computer, open it with ImageJ, and use the point selection tool to digitize the push pins, starting from the zenith push pin and not skipping any shown push pin. End with an additional point where the image meets the surrounding black (or the last pixel in case there is not blackness because it is not a circular hemispherical image. There is no need to follow the line formed by the push pins). Then, use the dropdown menu Analyze>Measure to open the window Results. To obtain the CSV, use File>Save As...

Use test_lens_coef() to test if coefficients are OK.

Value

An object of class list with named elements. ds is the dataset used to fit the model, model is the fitted model (class lm, see stats::lm()), horizon_radius is the radius at 90º, lens_coef is a numeric vector of length equal to the degree argument containing the polynomial model coefficients for predicting relative radius (coefficients(model)/horizon_radius), zenith_colrow are the raster coordinates of the zenith push pin, max_theta is the maximum zenith angle in degrees, and max_theta_px is the distance in pixels between the zenith and the maximum zenith angle in pixels units.

Note

If we imagine the fisheye image as an analog clock, it is possible to calibrate 3 o'clock by attaching the camera to the tripod in landscape mode while leaving the quarter-circle at the lens's right side. To calibrate 9 o'clock, it will be necessary to rotate the camera to put the quarter-circle at the lens's left side. To calibrate 12 and 6 o'clock, it will be necessary to do the same but with the camera in portrait mode. If several directions are sampled with this procedure, a character vector of length greater than one in which each element is a path to a CSV files could be provided as the path_to_csv argument.

References

Díaz GM, Lang M, Kaha M (2024). “Simple calibration of fisheye lenses for hemipherical photography of the forest canopy.” Agricultural and Forest Meteorology, 352, 110020. ISSN 0168-1923, doi:10.1016/j.agrformet.2024.110020.

See Also

Other Lens Functions: azimuth_image(), calc_diameter(), calc_relative_radius(), calc_zenith_colrow(), crosscalibrate_lens(), expand_noncircular(), extract_radiometry(), fisheye_to_equidistant(), fisheye_to_pano(), lens(), test_lens_coef(), zenith_image()

Examples

path <- system.file("external/Results_calibration.csv", package = "rcaiman")
calibration <- calibrate_lens(path)
coefficients(calibration$model)
calibration$lens_coef %>% signif(3)
calibration$horizon_radius

## Not run: 
test_lens_coef(calibration$lens_coef) #MacOS and Windows tend to differ here
test_lens_coef(c(0.628, 0.0399, -0.0217))

## End(Not run)

.fp <- function(theta, lens_coef) {
  x <- lens_coef[1:5]
  x[is.na(x)] <- 0
  for (i in 1:5) assign(letters[i], x[i])
  a * theta + b * theta^2 + c * theta^3 + d * theta^4 + e * theta^5
}

plot(calibration$ds)
theta <- seq(0, pi/2, pi/180)
lines(theta, .fp(theta, coefficients(calibration$model)))

Description

Do chessboard segmentation

Usage

chessboard(r, size)

Arguments

Value

A single layer image of the class SpatRaster with integer values.

See Also

Other Segmentation Functions: mask_hs(), mask_sunlit_canopy(), polar_qtree(), qtree(), rings_segmentation(), sectors_segmentation(), sky_grid_segmentation()

Examples

caim <- read_caim()
seg <- chessboard(caim, 20)
plot(caim$Blue)
plot(extract_feature(caim$Blue, seg))

Description

CIE sky model raster

Usage

cie_sky_model_raster(z, a, sun_coord, sky_coef)

Arguments

See Also

Other Sky Reconstruction Functions: fit_cie_sky_model(), fit_coneshaped_model(), fit_trend_surface(), interpolate_and_merge(), interpolate_sky_points(), ootb_fit_cie_sky_model()

Examples

z <- zenith_image(50, lens())
a <- azimuth_image(z)
path <- system.file("external", package = "rcaiman")
skies <- read.csv(file.path(path, "15_CIE_standard_skies.csv"))
# parameters are from http://dx.doi.org/10.1016/j.energy.2016.02.054
sky_coef <- skies[4,1:5]
sun_coord <- c(45, 0)
plot(cie_sky_model_raster(z, a, sun_coord, sky_coef))

Description

Quantify the colorfulness of an image

Usage

colorfulness(caim, m = NULL)

Arguments

Details

Quantify the colorfulness of an sRGB image using a bidimensional space formed by the green/red and the blue/yellow axes of the CIE LAB space, symbolized with A and B, respectively. The colorfulness index (CI) is defined as

$CI = \dfrac{A_o}{A_p} \cdot 100$,

where $A_o$ and $A_p$ are the observed and potential area of the AB plane. $A_o$ refers to the colors from the image while $A_p$ to the colors from the whole sRGB cube.

Value

A numeric vector of length one.

Note

An early version of this function was used in Martin et al. (2020).

References

Martin DA, Wurz A, Osen K, Grass I, Hölscher D, Rabemanantsoa T, Tscharntke T, Kreft H (2020). “Shade-Tree Rehabilitation in Vanilla Agroforests is Yield Neutral and May Translate into Landscape-Scale Canopy Cover Gains.” Ecosystems, 24(5), 1253–1267. doi:10.1007/s10021-020-00586-5.

See Also

Other Tool Functions: calc_oor_index(), calc_sngd(), correct_vignetting(), defuzzify(), expand_sky_points(), extract_dn(), extract_feature(), extract_rl(), extract_sky_points(), extract_sun_coord(), find_general_sky_type(), find_sky_pixels(), masking(), optim_normalize(), percentage_of_clipped_highlights(), read_bin(), read_caim(), read_caim_raw(), read_ootb_sky_model(), sor_filter(), write_bin(), write_caim(), write_ootb_sky_model()

Examples

caim <- read_caim() %>% normalize()
colorfulness(caim)

Description

Correct vignetting effect

Usage

correct_vignetting(r, z, lens_coef_v)

Arguments

Value

The argument r but with corrected values.

See Also

Other Tool Functions: calc_oor_index(), calc_sngd(), colorfulness(), defuzzify(), expand_sky_points(), extract_dn(), extract_feature(), extract_rl(), extract_sky_points(), extract_sun_coord(), find_general_sky_type(), find_sky_pixels(), masking(), optim_normalize(), percentage_of_clipped_highlights(), read_bin(), read_caim(), read_caim_raw(), read_ootb_sky_model(), sor_filter(), write_bin(), write_caim(), write_ootb_sky_model()

Examples

path <- system.file("external/DSCN4500.JPG", package = "rcaiman")
caim <- read_caim(path, c(1250, 1020) - 745, 745 * 2, 745 * 2)
z <- zenith_image(ncol(caim), lens("Nikon_FCE9"))
r <- gbc(caim$Blue)
r
r <- correct_vignetting(r, z, c(0.0638, -0.101))
r

Description

Function that complements read_caim() and read_caim_raw()

Usage

crop_caim(r, upper_left = NULL, width = NULL, height = NULL)

Arguments

Value

SpatRaster

Examples

caim <- read_caim()
ncell(caim)
caim <- crop_caim(caim, c(231,334), 15, 10)
ncell(caim)

Description

Cross-calibrate lens

Usage

crosscalibrate_lens(
  path_to_csv_uncal,
  path_to_csv_cal,
  zenith_colrow_uncal,
  zenith_colrow_cal,
  diameter_cal,
  lens_coef,
  degree = 3
)

Arguments

Details

Read the help page of calibrate_lens() for understanding the theory being this function.

This function is intended to be used when a camera calibrated with a method of higher accuracy than the one proposed in calibrate_lens() is available or there is a main camera to which all other devices should be adjusted.

It requires two photographs taken from the exact same location with the calibrated and uncalibrated camera. This means that the lens entrance pupils should match and the optical axes should be aligned.

Points should be digitized in tandem with ImageJ and saved as CSV files.

Value

An object of class list with named elements. ds is the dataset used to fit the model, model is the fitted model (class lm, see stats::lm()), horizon_radius is the radius at 90º, lens_coef is a numeric vector of length equal to the degree argument containing the polynomial model coefficients for predicting relative radius (coefficients(model)/horizon_radius).

See Also

Other Lens Functions: azimuth_image(), calc_diameter(), calc_relative_radius(), calc_zenith_colrow(), calibrate_lens(), expand_noncircular(), extract_radiometry(), fisheye_to_equidistant(), fisheye_to_pano(), lens(), test_lens_coef(), zenith_image()

Description

This function translates degree of membership into Boolean logic using a regional approach. The output ensures that the fuzzy and Boolean versions remain consistent at the specified level of aggregation (controlled by the argument segmentation). This method makes perfect sense to translate a subpixel classification of gap fraction (or a linear ratio) into a binary product.

Usage

defuzzify(mem, segmentation)

Arguments

Value

An object of the class SpatRaster containing binary information.

Note

This method is also available in the HSP software package (Lang et al. 2013).

References

Lang M, Kodar A, Arumäe T (2013). “Restoration of above canopy reference hemispherical image from below canopy measurements for plant area index estimation in forests.” Forestry Studies, 59(1), 13–27. doi:10.2478/fsmu-2013-0008.

See Also

Other Tool Functions: calc_oor_index(), calc_sngd(), colorfulness(), correct_vignetting(), expand_sky_points(), extract_dn(), extract_feature(), extract_rl(), extract_sky_points(), extract_sun_coord(), find_general_sky_type(), find_sky_pixels(), masking(), optim_normalize(), percentage_of_clipped_highlights(), read_bin(), read_caim(), read_caim_raw(), read_ootb_sky_model(), sor_filter(), write_bin(), write_caim(), write_ootb_sky_model()

Examples

## Not run: 
path <- system.file("external/DSCN4500.JPG", package = "rcaiman")
caim <- read_caim(path, c(1250, 1020) - 745, 745 * 2, 745 * 2)
z <- zenith_image(ncol(caim), lens("Nikon_FCE9"))
a <- azimuth_image(z)
r <- gbc(caim$Blue)
r <- correct_vignetting(r, z, c(0.0638, -0.101)) %>% normalize()
bin <- find_sky_pixels(r, z, a)
bin <- ootb_mblt(r, z, a, bin)
plot(bin$bin)
ratio <- r / bin$sky_s
ratio <- normalize(ratio, 0, 1, TRUE)
plot(ratio)
g <- sky_grid_segmentation(z, a, 10)
bin2 <- defuzzify(ratio, g)
plot(bin2)
plot(abs(bin$bin - bin2))

## End(Not run)

Description

This function was first proposed in Díaz and Lencinas (2015). It uses the color perceptual attributes (hue, lightness, and chroma) to enhance the contrast between the sky and plants through fuzzy classification. It applies the next classification rules (here expressed in natural language): clear sky is blue and clouds decrease its chroma; if clouds are highly dense, then the sky is achromatic, and, in such cases, it can be light or dark; everything that does not match this description is not sky. These linguistic rules were translated to math language by means of fuzzy logic. This translation was thoughtfully explained in the aforementioned article.

Usage

enhance_caim(
  caim,
  m = NULL,
  sky_blue = NULL,
  sigma = NULL,
  w_red = 0,
  thr = NULL,
  fuzziness = NULL,
  gamma = NULL
)

Arguments

Details

This is a pixel-wise methodology that evaluates the possibility for a pixel to be member of the class Gap. High score could mean either high membership to sky_blue or, in the case of achromatic pixels, a high membership to values above thr. The algorithm internally uses membership_to_color() and local_fuzzy_thresholding(). The argument sky_blue is the target_color of the former function and its output is the argument mem of the latter function.

The argument sky_blue can be obtained from a photograph that clearly shows the sky. Then, it can be used to process all the others photograph taken with the same equipment, configuration, and protocol.

Via the gamma argument, gbc() can be internally used to back-correct the values passed to local_fuzzy_thresholding().

Value

An object of class SpatRaster (with same pixel dimensions than caim) that should show more contrast between the sky and plant pixels than any of the individual bands from caim; if not, different parameters should be tested.

Note

If you use this function in your research, please cite Díaz and Lencinas (2015) in addition to this package (⁠citation("rcaiman"⁠).

The default value of argument m is the equivalent to enter !is.na(caim$Red). See the Details section in local_fuzzy_thresholding() to understand how this argument can modify the output.

References

Díaz GM, Lencinas JD (2015). “Enhanced gap fraction extraction from hemispherical photography.” IEEE Geoscience and Remote Sensing Letters, 12(8), 1785–1789. doi:10.1109/lgrs.2015.2425931.

See Also

Other Pre-processing Functions: gbc(), local_fuzzy_thresholding(), membership_to_color(), normalize()

Examples

## Not run: 
caim <- read_caim()
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)
m <- !is.na(z)

r <- normalize(caim$Blue)

bin <- regional_thresholding(r, rings_segmentation(z, 30),
                             method = "thr_isodata")
mx <- optim_normalize(caim, bin)
mn <- min(caim[m])

sky_blue_sample <- crop_caim(caim, c(327, 239), 41, 89)
plotRGB(normalize(sky_blue_sample, mn, mx, TRUE)*255)
sky_blue <- apply(sky_blue_sample[], 2, median) %>%
  normalize(., mn, mx) %>%
  as.numeric() %>%
  matrix(., ncol = 3) %>%
  sRGB()
hex(sky_blue)
# Use hex() to obtain the HEX color code. To see a color swatch, enter the
# HEX code into a search engine (such as Mozilla Firefox).
# NOTE: see extract_dn() for an alternative method to obtain sky_blue

as(sky_blue, "HSV") #saturatio (S) is low
# To obtain same hue (H) but greater saturation
sky_blue <- HSV(239, 0.85, 0.5) %>% as(., "sRGB") %>% as(., "LAB")
hex(sky_blue)

caim <- normalize(caim, mx = mx, force_range = TRUE)
ecaim <- enhance_caim(caim, m, sky_blue = sky_blue)
plot(ecaim)
plot(caim$Blue)

## to compare
plot(apply_thr(ecaim, thr_isodata(ecaim[m])))
plot(apply_thr(caim$Blue, thr_isodata(caim$Blue[m])))

## End(Not run)

Description

Expand a non-circular hemispherical photograph.

Usage

expand_noncircular(caim, z, zenith_colrow)

Arguments

Value

An object of class SpatRaster that is the result of adding margins (NA pixels) to the argument caim. The zenith point depicted in the picture should be in the center of the image or very close to it.

See Also

Other Lens Functions: azimuth_image(), calc_diameter(), calc_relative_radius(), calc_zenith_colrow(), calibrate_lens(), crosscalibrate_lens(), extract_radiometry(), fisheye_to_equidistant(), fisheye_to_pano(), lens(), test_lens_coef(), zenith_image()

Examples

## Not run: 

 # ====================================================================
 # Non-circular Fisheye images from a Smartphone with an Auxiliary Lens
 # (Also applicable to Non-circular images from DSLR cameras)
 # ====================================================================

 path <- system.file("external/APC_0581.jpg", package = "rcaiman")
 caim <- read_caim(path)
 z <- zenith_image(2132/2,  c(0.7836, 0.1512, -0.1558))
 a <- azimuth_image(z)
 zenith_colrow <- c(1063, 771)/2
 caim <- expand_noncircular(caim, z, zenith_colrow)
 plot(caim$Blue, col = seq(0,1,1/255) %>% grey())
 m <- !is.na(caim$Red) & !is.na(z)
 plot(m, add = TRUE, alpha = 0.3, legend = FALSE)


 # ============================
 # Restricted View Canopy Photo
 # ============================

 path <- system.file("external/APC_0020.jpg", package = "rcaiman")
 caim <- read_caim(path)
 plot(caim)
 caim <- normalize(caim)
 diameter <- calc_diameter(lens(), sqrt(nrow(caim)^2 + ncol(caim)^2)/2, 90)
 z <- zenith_image(diameter, lens())
 caim <- expand_noncircular(caim, z, c(ncol(caim)/2, nrow(caim)/2))
 m <- !is.na(caim$Red)
 a <- azimuth_image(z)
 caim[!m] <- 0
 z <- normalize(z, 0, 90) * 30.15 #60.3º diagonal FOV according to metadata
 plot(caim$Blue, col = seq(0,1,1/255) %>% grey())
 m <- !is.na(caim$Red) & !is.na(z)
 plot(m, add = TRUE, alpha = 0.3, legend = FALSE)

## End(Not run)

Description

Expand sky points

Usage

expand_sky_points(
  r,
  z,
  a,
  sky_points,
  angle_width = 3,
  k = 20,
  p = 2,
  rmax = 20
)

Arguments

Value

An object of the class data.frame. It is the input argument sky_points with the additional columns: a, z, and dn and additional rows obtained by knn interpolation.

See Also

Other Tool Functions: calc_oor_index(), calc_sngd(), colorfulness(), correct_vignetting(), defuzzify(), extract_dn(), extract_feature(), extract_rl(), extract_sky_points(), extract_sun_coord(), find_general_sky_type(), find_sky_pixels(), masking(), optim_normalize(), percentage_of_clipped_highlights(), read_bin(), read_caim(), read_caim_raw(), read_ootb_sky_model(), sor_filter(), write_bin(), write_caim(), write_ootb_sky_model()

Examples

## Not run: 
caim <- read_caim()
r <- caim$Blue
bin <- apply_thr(r, thr_isodata(r[]))
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)

# See fit_cie_sky_model() for details on the CSV file
path <- system.file("external/sky_points.csv",
                    package = "rcaiman")
sky_points <- read.csv(path)
sky_points <- sky_points[c("Y", "X")]
colnames(sky_points) <- c("row", "col")
head(sky_points)
plot(bin)
points(sky_points$col, nrow(caim) - sky_points$row, col = 2, pch = 10)

sky_points2 <- expand_sky_points(r, z, a, sky_points, angle_width = 5)
plot(bin)
points(sky_points2$col, nrow(caim) - sky_points2$row, col = 2, pch = 10)

## End(Not run)

Description

Wrapper function around terra::extract().

Usage

extract_dn(r, img_points, use_window = TRUE, fun = NULL)

Arguments

Value

An object of the class data.frame. It is the argument img_points with an added column per each layer from r. The layer names are used to name the new columns. If a function is provided as the fun argument, the result will be summarized per column using the provided function, and the row and col information will be omitted. Moreover, if r is an RGB image, a color will be returned instead of a data.frame. The latter feature is useful for obtaining the sky_blue argument for enhance_caim().

Note

The point selection tool of ‘ImageJ’ software can be used to manually digitize points and create a CSV file from which to read coordinates (see Examples). After digitizing the points on the image, use the dropdown menu Analyze>Measure to open the Results window. To obtain the CSV file, use File>Save As...

See Also

Other Tool Functions: calc_oor_index(), calc_sngd(), colorfulness(), correct_vignetting(), defuzzify(), expand_sky_points(), extract_feature(), extract_rl(), extract_sky_points(), extract_sun_coord(), find_general_sky_type(), find_sky_pixels(), masking(), optim_normalize(), percentage_of_clipped_highlights(), read_bin(), read_caim(), read_caim_raw(), read_ootb_sky_model(), sor_filter(), write_bin(), write_caim(), write_ootb_sky_model()

Examples

## Not run: 
caim <- read_caim()
r <- caim$Blue
bin <- apply_thr(r, thr_isodata(r[]))
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)
g <- sky_grid_segmentation(z, a, 10)
sky_points <- extract_sky_points(r, bin, g)
sky_points <- extract_dn(caim, sky_points)
head(sky_points)

# See fit_cie_sky_model() for details on the CSV file
path <- system.file("external/sky_points.csv",
                    package = "rcaiman")
sky_points <- read.csv(path)
sky_points <- sky_points[c("Y", "X")]
colnames(sky_points) <- c("row", "col")
head(sky_points)
plot(bin)
points(sky_points$col, nrow(caim) - sky_points$row, col = 2, pch = 10)
extract_dn(caim, sky_points, fun = median)

## End(Not run)

Description

Extract features from raster images.

Usage

extract_feature(
  r,
  segmentation,
  fun = mean,
  return_raster = TRUE,
  ignore_label_0 = TRUE
)

Arguments

Details

Given a single-layer raster, a segmentation, and a function, extract_features will return a numeric vector or a SpatRaster depending on whether the parameter return_raster is TRUE or FALSE. For the first case, each pixel of each segment will adopt the respective extracted feature value. For the second case, the return will be a vector of length equal to the total number of segments. Each value will be obtained by processing all pixels that belong to a segment with the provided function.

Value

If return_raster is set to TRUE, then an object of class SpatRaster with the same pixel dimensions than r will be returned. Otherwise, the return is a numeric vector of length equal to the number of segments found in segmentation.

See Also

Other Tool Functions: calc_oor_index(), calc_sngd(), colorfulness(), correct_vignetting(), defuzzify(), expand_sky_points(), extract_dn(), extract_rl(), extract_sky_points(), extract_sun_coord(), find_general_sky_type(), find_sky_pixels(), masking(), optim_normalize(), percentage_of_clipped_highlights(), read_bin(), read_caim(), read_caim_raw(), read_ootb_sky_model(), sor_filter(), write_bin(), write_caim(), write_ootb_sky_model()

Examples

r <- read_caim()
z <- zenith_image(ncol(r),lens())
a <- azimuth_image(z)
g <- sky_grid_segmentation(z, a, 10)
print(extract_feature(r$Blue, g, return_raster = FALSE))
# plot(extract_feature(r$Blue, g, return_raster = TRUE))

Description

Extract radiometry from images taken with the aid of a portable light source and the calibration board detailed in calibrate_lens(). The end goal is to obtain the data required to model the vignetting effect.

Usage

extract_radiometry(l, size_px = NULL)

Arguments

Details

Lenses have the inconvenient property of increasingly attenuating light in the direction orthogonal to the optical axis. This phenomenon is known as the vignetting effect and varies with lens model and aperture setting. The method outlined here, known as the simple method, is explained in details in Díaz et al. (2024). Next explanation might serve mostly as a quick recap of it.

The development of the simple method was done with a Kindle Paperwhite eBooks reader of 6" with built-in light. However, an iPhone 6 plus was also tested in the early stages of development and no substantial differences were observed. A metal bookends desk book holder was used to fasten the eBook reader upright and a semi-transparent paper to favor a Lambertian light distribution. In addition, the latter was used to draw on in order to guide pixel sampling. The book holder also facilitated the alignment of the screen with the dotted lines of the printed quarter-circle.

As a general guideline, a wide variety of mobile devices could be used as light sources, but if scattered data points are obtained with it, then other light sources should be tested in order to double check that the light quality is not the reason for points scattering.

With the room only illuminated by the portable light source, nine photographs should be taken with the light source located in the equivalent to 0, 10, 20, 30, 40, 50, 60, 70, and 80 degrees of zenith angle, respectively. Camera configuration should be in manual mode and set with the aperture (f/number) for which a vignetting function is required. The shutter speed should be regulated to obtain light-source pixels with middle grey values. The nine photographs should be taken without changing the camera configuration and the light conditions.

This code exemplify how to use the function to obtain the data and base R functions to obtain the vignetting function ($f_v$).

zenith_colrow <- c(1500, 997)*2
diameter <- 947*4
z <- zenith_image(diameter, c(0.689, 0.0131, -0.0295))
a <- azimuth_image(z)

.read_raw <- function(path_to_raw_file) {
  r <- read_caim_raw(path_to_raw_file, z, a, zenith_colrow,
                     radius = 500, only_blue = TRUE)
  r
}

l <- Map(.read_raw, dir("raw/up/", full.names = TRUE))
up_data <- extract_radiometry(l)
l <- Map(.read_raw, dir("raw/down/", full.names = TRUE))
down_data <- extract_radiometry(l)
l <- Map(.read_raw, dir("raw/right/", full.names = TRUE))
right_data <- extract_radiometry(l)
l <- Map(.read_raw, dir("raw/left/", full.names = TRUE))
left_data <- extract_radiometry(l)

ds <- rbind(up_data, down_data, right_data, left_data)

plot(ds, xlim = c(0, pi/2), ylim= c(0.5,1.05),
      col = c(rep(1,9),rep(2,9),rep(3,9),rep(4,9)))
legend("bottomleft", legend = c("up", "down", "right", "left"),
       col = 1:4, pch = 1)

fit <- lm((1 - ds$radiometry) ~ poly(ds$theta, 3, raw = TRUE) - 1)
summary(fit)
coef <- -fit$coefficients #did you notice the minus sign?
.fv <- function(x) 1 + coef[1] * x + coef[2] * x^2 + coef[3] * x^3
curve(.fv, add = TRUE, col = 2)
coef

Once one of the aperture settings is calibrated, it can be used to calibrate all the rest. To do so, the equipment should be used to take photographs in all desired exposition and without moving the camera, including the aperture already calibrated and preferably under an open sky in stable diffuse light conditions. The same procedure, which minor adaptations, is applicable to cross-camera calibration. Below code could be used as a template.

zenith_colrow <- c(1500, 997)*2
diameter <- 947*4
z <- zenith_image(diameter, c(0.689, 0.0131, -0.0295))
a <- azimuth_image(z)

files <- dir("raw/", full.names = TRUE)
l <- list()
for (i in seq_along(files)) {
  if (i == 1) {
    # because the first aperture was the one already calibrated
    lens_coef_v <- c(0.0302, -0.320, 0.0908)
  } else {
    lens_coef_v <- NULL
  }
  l[[i]] <- read_caim_raw(files[i], z, a, zenith_colrow,
                          radius = 500,
                          only_blue = TRUE,
                          lens_coef_v = lens_coef_v)
}

ref <- l[[1]]
rings <- rings_segmentation(zenith_image(ncol(ref), lens()), 3)
theta <- seq(1.5, 90 - 1.5, 3) * pi/180

.fun <- function(r) {
  r <- extract_feature(r, rings, return_raster = FALSE)
  r/r[1]
}

l <- Map(.fun, l)

.fun <- function(x) {
  x / l[[1]][] # because the first is the one already calibrated
}
radiometry <- Map(.fun, l)

l <- list()
for (i in 2:length(radiometry)) {
  l[[i-1]] <- data.frame(theta = theta, radiometry = radiometry[[i]][])
}
ds <- l[[1]]
head(ds)
# The result is one dataset (ds) for each file. This is all what it is needed
# before using base R functions to fit a vignetting function

Value

An object of the class data.frame with columns theta (zenith angle in radians) and radiometry (digital number (DN) or relative digital number (RDN), depending on argument z_thr.

References

Díaz GM, Lang M, Kaha M (2024). “Simple calibration of fisheye lenses for hemipherical photography of the forest canopy.” Agricultural and Forest Meteorology, 352, 110020. ISSN 0168-1923, doi:10.1016/j.agrformet.2024.110020.

See Also

Other Lens Functions: azimuth_image(), calc_diameter(), calc_relative_radius(), calc_zenith_colrow(), calibrate_lens(), crosscalibrate_lens(), expand_noncircular(), fisheye_to_equidistant(), fisheye_to_pano(), lens(), test_lens_coef(), zenith_image()

Description

Extract the luminance relative to the zenith digital number

Usage

extract_rl(
  r,
  z,
  a,
  sky_points,
  no_of_points = 3,
  z_thr = 5,
  use_window = TRUE,
  min_spherical_dist = NULL
)

Arguments

Details

The search for near-zenith points starts in the region ranged between 0 and z_thr. If the number of near-zenith points is less than no_of_points, the region increases by steps of 2 degrees of zenith angle till the required number of points is reached.

Value

A list of three objects, zenith_dn and max_zenith_angle from the class numeric, and sky_points of the class data.frame; zenith_dn is the estimated zenith digital number, max_zenith_angle is the maximum zenith angle reached in the search for near-zenith sky points, and sky_points is the input argument sky_points with the additional columns: a, z, dn, and rl, which stand for azimuth and zenith angle in degrees, digital number, and relative luminance, respectively. If NULL is provided as no_of_points, then zenith_dn is forced to one and, therefore, dn and rl will be identical.

References

Lang M, Kodar A, Arumäe T (2013). “Restoration of above canopy reference hemispherical image from below canopy measurements for plant area index estimation in forests.” Forestry Studies, 59(1), 13–27. doi:10.2478/fsmu-2013-0008.

See Also

Other Tool Functions: calc_oor_index(), calc_sngd(), colorfulness(), correct_vignetting(), defuzzify(), expand_sky_points(), extract_dn(), extract_feature(), extract_sky_points(), extract_sun_coord(), find_general_sky_type(), find_sky_pixels(), masking(), optim_normalize(), percentage_of_clipped_highlights(), read_bin(), read_caim(), read_caim_raw(), read_ootb_sky_model(), sor_filter(), write_bin(), write_caim(), write_ootb_sky_model()

Examples

## Not run: 
caim <- read_caim()
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)

# See fit_cie_sky_model() for details on the CSV file
path <- system.file("external/sky_points.csv",
                    package = "rcaiman")
sky_points <- read.csv(path)
sky_points <- sky_points[c("Y", "X")]
colnames(sky_points) <- c("row", "col")
head(sky_points)

plot(caim$Blue)
points(sky_points$col, nrow(caim) - sky_points$row, col = 2, pch = 10)
rl <- extract_rl(caim$Blue, z, a, sky_points, 1, min_spherical_dist = 10)
points(rl$sky_points$col, nrow(caim) - rl$sky_points$row, col = 3, pch = 0)

## End(Not run)

Description

Extract sky points for model fitting

Usage

extract_sky_points(r, bin, g, dist_to_plant = 3, min_raster_dist = 3)

Arguments

Details

This function will automatically sample sky pixels from the sky regions delimited by bin. The density and distribution of the sampling points is controlled by the arguments g, dist_to_plant, and min_raster_dist.

As the first step, sky pixels from r are evaluated to find the pixel with maximum digital value (local maximum) per cell of the g argument. The dist_to_plant argument allows users to establish a buffer zone for bin, meaning a size reduction of the original sky regions.

The final step is filtering these local maximum values by evaluating the Euclidean distances between them on the raster space. Any new point with a distance from existing points minor than min_raster_dist is discarded. Cell labels determine the order in which the points are evaluated.

To skip a given filtering step, use code NULL as argument input. For instance, min_raster_dist = NULL will return points omitting the final step.

Value

An object of the class data.frame with two columns named row and col.

See Also

fit_cie_sky_model()

Other Tool Functions: calc_oor_index(), calc_sngd(), colorfulness(), correct_vignetting(), defuzzify(), expand_sky_points(), extract_dn(), extract_feature(), extract_rl(), extract_sun_coord(), find_general_sky_type(), find_sky_pixels(), masking(), optim_normalize(), percentage_of_clipped_highlights(), read_bin(), read_caim(), read_caim_raw(), read_ootb_sky_model(), sor_filter(), write_bin(), write_caim(), write_ootb_sky_model()

Examples

## Not run: 
caim <- read_caim()
r <- caim$Blue
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)
m <- !is.na(z)
bin <- regional_thresholding(r, rings_segmentation(z, 30),
                             method = "thr_isodata")
mx <- optim_normalize(caim, bin)
caim <- normalize(caim, 0, mx, TRUE)
plotRGB(caim*255)
sky_blue <- HSV(239, 0.85, 0.5)
ecaim <- enhance_caim(caim, m, sky_blue = sky_blue)
bin <- apply_thr(ecaim, thr_isodata(ecaim[m]))
g <- sky_grid_segmentation(z, a, 10)
sky_points <- extract_sky_points(r, bin, g,
                                 dist_to_plant = 3,
                                 min_raster_dist = 10)
plot(bin)
points(sky_points$col, nrow(caim) - sky_points$row, col = 2, pch = 10)

## End(Not run)

Description

Extract the sun coordinates for CIE sky model fitting.

Usage

extract_sun_coord(r, z, a, bin, g, max_angular_dist = 30)

Arguments

Details

This function uses an object-based image analyze framework. The segmentation is given by g and bin. For every cell of g, the pixels from r that are equal to one on bin are selected and its maximum value is calculated. Then, the 95th percentile of these maximum values is computed and used to filter out cells below that threshold; i.e, only the cells with at least one extremely bright sky pixel is selected.

The selected cells are grouped based on adjacency, and new bigger segments are created from these groups. The degree of membership to the class Sun is calculated for every new segment by computing the number of cells that constitute the segment and its mean digital number (values taken from r). In other words, the largest and brightest segments are the ones that score higher. The one with the highest score is selected as the sun seed.

The angular distance from the sun seed to every other segments are computed, and only the segments not farther than max_angular_dist are classified as part of the sun corona. A multi-part segment is created by merging the sun-corona segments and, finally, the center of its bounding box is considered as the sun location.

Value

Object of class list with two numeric vectors of length two named row_col and zenith_azimuth. The former is the raster coordinates of the solar disk (row and column), and the other is the angular coordinates (zenith and azimuth angles in degrees).

See Also

Other Tool Functions: calc_oor_index(), calc_sngd(), colorfulness(), correct_vignetting(), defuzzify(), expand_sky_points(), extract_dn(), extract_feature(), extract_rl(), extract_sky_points(), find_general_sky_type(), find_sky_pixels(), masking(), optim_normalize(), percentage_of_clipped_highlights(), read_bin(), read_caim(), read_caim_raw(), read_ootb_sky_model(), sor_filter(), write_bin(), write_caim(), write_ootb_sky_model()

Examples

## Not run: 
caim <- read_caim()
r <- caim$Blue
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)
m <- !is.na(z)
bin <- regional_thresholding(r, rings_segmentation(z, 30),
                             method = "thr_isodata")
mx <- optim_normalize(caim, bin)
caim <- normalize(caim, 0, mx, TRUE)
plotRGB(caim*255)
sky_blue <- HSV(239, 0.85, 0.5)
ecaim <- enhance_caim(caim, m, sky_blue = sky_blue)
bin <- apply_thr(ecaim, thr_isodata(ecaim[m]))
g <- sky_grid_segmentation(z, a, 10)
sun_coord <- extract_sun_coord(r, z, a, bin, g, max_angular_dist = 30)
points(sun_coord$row_col[2], nrow(caim) - sun_coord$row_col[1],
        col = 3, pch = 10)

## End(Not run)

Description

Find the general sky type attributable to a given set of coefficients

Usage

find_general_sky_type(model)

Arguments

Value

A character vector of length one.

See Also

Other Tool Functions: calc_oor_index(), calc_sngd(), colorfulness(), correct_vignetting(), defuzzify(), expand_sky_points(), extract_dn(), extract_feature(), extract_rl(), extract_sky_points(), extract_sun_coord(), find_sky_pixels(), masking(), optim_normalize(), percentage_of_clipped_highlights(), read_bin(), read_caim(), read_caim_raw(), read_ootb_sky_model(), sor_filter(), write_bin(), write_caim(), write_ootb_sky_model()

Examples

## Not run: 
caim <- read_caim() %>% normalize()
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)

# Manual method following Lang et al. (2010) using QGIS
path <- system.file("external/sky_points.gpkg",
                    package = "rcaiman")
sky_points <- terra::vect(path)
sky_points <- terra::extract(caim, sky_points, cells = TRUE)
sky_points <- terra::rowColFromCell(caim, sky_points$cell) %>% as.data.frame()
colnames(sky_points) <- c("row", "col")
xy <- c(210, 451) #taken with click() after x11(), then hardcoded here
sun_coord <- zenith_azimuth_from_row_col(z, a, c(nrow(z) - xy[2],xy[1]))

rl <- extract_rl(caim$Blue, z, a, sky_points)

set.seed(7)
model <- fit_cie_sky_model(rl, sun_coord,
                           general_sky_type = "Clear",
                           twilight = FALSE,
                           method = "CG")
find_general_sky_type(model)

## End(Not run)

Description

Find sky pixels automatically.

Usage

find_sky_pixels(r, z, a, sample_size_pct = 30)

Arguments

Details

This function assumes that:

• there is at least one pure sky pixel at the level of cells of $30 \times 30$ degrees, and

• sky pixels have a digital number (DN) greater than canopy pixels have.

For each $30 \times 30$ cell, this method computes a quantile value and uses it as a threshold to select the pure sky pixels from the given cell. As a result, a binarized image is produced in a regional binarization fashion (regional_thresholding()). This process starts with a quantile probability of 0.99. After producing the binarized image, this function uses a search grid with cells of $5 \times 5$ degrees to count how many of these cells have at least one sky pixel (pixels equal to one in the binarized image). If the percentage of cells with sky pixels does not reach argument sample_size_pct, it goes back to the binarization step but decreasing the probability by 0.01 points.

If probability reach 0.9 and the sample_size_pct criterion were not yet satisfied, the sample_size_pct is decreased one percent and the process starts all over again.

Value

An object of class SpatRaster with values 0 and 1. This layer masks pixels that are very likely pure sky pixels.

See Also

Other Tool Functions: calc_oor_index(), calc_sngd(), colorfulness(), correct_vignetting(), defuzzify(), expand_sky_points(), extract_dn(), extract_feature(), extract_rl(), extract_sky_points(), extract_sun_coord(), find_general_sky_type(), masking(), optim_normalize(), percentage_of_clipped_highlights(), read_bin(), read_caim(), read_caim_raw(), read_ootb_sky_model(), sor_filter(), write_bin(), write_caim(), write_ootb_sky_model()

Examples

## Not run: 
caim <- read_caim() %>% normalize(., 0, 20847)
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)
r <- caim$Blue
r[is.na(r)] <- 0
bin <- find_sky_pixels(r, z, a)
plot(bin)

## End(Not run)

Description

Fisheye to equidistant projection (also known as polar projection).

Usage

fisheye_to_equidistant(
  r,
  z,
  a,
  m = NULL,
  radius = NULL,
  k = NULL,
  p = NULL,
  rmax = 100
)

Arguments

Details

The pixel values and their image coordinates are treated as points to be reprojected and interpolated. To that end, this function use lidR::knnidw() as workhorse function, so arguments k, p, and rmax are passed to it. If the user does not input values to these arguments, both k and p are automatically defined by default as follow: when a binarized image is provided as argument r, both parameters are set to 1; otherwise, they are set to 9 and 2, respectively.

Note

Default value for the radius argument is equivalent to input the radius of the r argument.

See Also

Other Lens Functions: azimuth_image(), calc_diameter(), calc_relative_radius(), calc_zenith_colrow(), calibrate_lens(), crosscalibrate_lens(), expand_noncircular(), extract_radiometry(), fisheye_to_pano(), lens(), test_lens_coef(), zenith_image()

Examples

## Not run: 
path <- system.file("external/DSCN4500.JPG", package = "rcaiman")
caim <- read_caim(path, c(1250, 1020) - 745, 745 * 2, 745 * 2)
z <- zenith_image(ncol(caim), lens("Nikon_FCE9"))
a <- azimuth_image(z)
r <- gbc(caim$Blue)
r <- correct_vignetting(r, z, c(0.0638, -0.101)) %>% normalize()
bin <- find_sky_pixels(r, z, a)
bin <- ootb_mblt(r, z, a, bin)$bin
bin_equi <- fisheye_to_equidistant(bin, z, a)
plot(bin)
plot(bin_equi)
# Use write_bin(bin, "path/file_name") to have a file ready
# to calcute LAI with CIMES, GLA, CAN-EYE, etc.

# It can be used to reproject RGB photographs
plotRGB(caim)
caim <- fisheye_to_equidistant(caim, z, a)
plotRGB(caim)

## End(Not run)

Description

Fisheye to panoramic (cylindrical projection)

Usage

fisheye_to_pano(r, z, a, fun = mean, angle_width = 1)

Arguments

Details

An early version of this function was used in Díaz et al. (2021).

References

Díaz GM, Negri PA, Lencinas JD (2021). “Toward making canopy hemispherical photography independent of illumination conditions: A deep-learning-based approach.” Agricultural and Forest Meteorology, 296, 108234. doi:10.1016/j.agrformet.2020.108234.

See Also

Other Lens Functions: azimuth_image(), calc_diameter(), calc_relative_radius(), calc_zenith_colrow(), calibrate_lens(), crosscalibrate_lens(), expand_noncircular(), extract_radiometry(), fisheye_to_equidistant(), lens(), test_lens_coef(), zenith_image()

Examples

## Not run: 
caim <- read_caim()
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)
pano <- fisheye_to_pano(caim, z, a)
plotRGB(pano %>% normalize() %>% multiply_by(255))

## End(Not run)

Description

Use maximum likelihood to estimate the coefficients of the CIE sky model that best fit to data sampled from a canopy photograph.

Usage

fit_cie_sky_model(
  rl,
  sun_coord,
  custom_sky_coef = NULL,
  std_sky_no = NULL,
  general_sky_type = NULL,
  twilight = TRUE,
  method = "BFGS"
)

Arguments

Details

This function is based on Lang et al. (2010). In theory, the best result would be obtained with data showing a linear relation between digital numbers and the amount of light reaching the sensor. See extract_radiometry() and read_caim_raw() for further details. As a compromise solution, gbc() can be used.

The following code exemplifies how this package can be used to compare the manually-guided fitting provided by HSP (Lang et al. 2013) against the automatic fitting provided by this package. The code assumes that the user is working within an RStudio project located in the HSP project folder.

r <- read_caim("manipulate/IMG_1013.pgm") %>% normalize()
z <- zenith_image(ncol(r), lens())
a <- azimuth_image(z)
manual_input <- read_manual_input(".", "IMG_1013" )
sun_coord <- manual_input$sun_coord$row_col
sun_coord <- zenith_azimuth_from_row_col(z, sun_coord, lens())
sky_points <- manual_input$sky_points
rl <- extract_rl(r, z, a, sky_points)
model <- fit_cie_sky_model(rl, sun_coord)
cie_sky <- model$relative_luminance * model$zenith_dn
plot(r/cie_sky)

r <- read_caim("manipulate/IMG_1013.pgm")
sky_coef <- read_opt_sky_coef(".", "IMG_1013")
cie_sky_m <- cie_sky_model_raster(z, a, sun_coord$zenith_azimuth, sky_coef)
cie_sky_m <- cie_sky_manual * manual_input$zenith_dn
plot(r/cie_sky_m)

Value

An object of the class list. The result includes the following: (1) the output produced by bbmle::mle2(), (2) the 5 coefficients of the CIE model, (3) observed values, (4) predicted values, (5) the digital number at the zenith, (6) the sun coordinates (zenith and azimuth angle in degrees), (7) the optimization method (see bbmle::mle2()), and the initial values for optimizer (see bbmle::mle2()). To lear more about these initial values, see Li et al. (2016). If bbmle::mle2() does not converge, (1) will be NA and (2) will contain the coefficients of a standard sky (the one with less RMSE when more than one is tried).

Note

The point selection tool of ‘ImageJ’ software can be used to manually digitize points and create a CSV file from which to read coordinates (see Examples). After digitizing the points on the image, use the dropdown menu Analyze>Measure to open the Results window. To obtain the CSV file, use File>Save As...

The QGIS software can also be used to manually digitize points. In order to do that, drag and drop the image in an empty project, create an new vector layer, digitize points manually, save the editions, and close the project. To create the new vector layer go to the dropdown menu Layer>Create Layer>New Geopackage Layer...

Choose "point" in the Geometry type dropdown list and make sure the CRS is EPSG:7589. To be able to input the points, remember to click first on the Toogle Editing icon, and then on the Add Points Feature icon.

If you use this function in your research, please cite Lang et al. (2010) in addition to this package (⁠citation("rcaiman"⁠)).

References

Lang M, Kodar A, Arumäe T (2013). “Restoration of above canopy reference hemispherical image from below canopy measurements for plant area index estimation in forests.” Forestry Studies, 59(1), 13–27. doi:10.2478/fsmu-2013-0008.

Lang M, Kuusk A, Mõttus M, Rautiainen M, Nilson T (2010). “Canopy gap fraction estimation from digital hemispherical images using sky radiance models and a linear conversion method.” Agricultural and Forest Meteorology, 150(1), 20–29. doi:10.1016/j.agrformet.2009.08.001.

Li DH, Lou S, Lam JC, Wu RH (2016). “Determining solar irradiance on inclined planes from classified CIE (International Commission on Illumination) standard skies.” Energy, 101, 462–470. doi:10.1016/j.energy.2016.02.054.

See Also

Other Sky Reconstruction Functions: cie_sky_model_raster(), fit_coneshaped_model(), fit_trend_surface(), interpolate_and_merge(), interpolate_sky_points(), ootb_fit_cie_sky_model()

Examples

## Not run: 
caim <- read_caim() %>% normalize()
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)

# Manual method following Lang et al. (2010)
# ImageJ can be used to digitize points
path <- system.file("external/sky_points.csv",
                    package = "rcaiman")
sky_points <- read.csv(path)
sky_points <- sky_points[c("Y", "X")]
colnames(sky_points) <- c("row", "col")
head(sky_points)
plot(caim$Blue)
points(sky_points$col, nrow(caim) - sky_points$row, col = 2, pch = 10)

# Idem for QGIS
path <- system.file("external/sky_points.gpkg",
                    package = "rcaiman")
sky_points <- terra::vect(path)
sky_points <- terra::extract(caim, sky_points, cells = TRUE)
sky_points <- terra::rowColFromCell(caim, sky_points$cell) %>% as.data.frame()
colnames(sky_points) <- c("row", "col")
head(sky_points)
plot(caim$Blue)
points(sky_points$col, nrow(caim) - sky_points$row, col = 2, pch = 10)

xy <- c(210, 451) #taken with click() after x11(), then hardcoded here
sun_coord <- zenith_azimuth_from_row_col(z, a, c(nrow(z) - xy[2],xy[1]))
points(sun_coord$row_col[2], nrow(caim) - sun_coord$row_col[1],
       col = 3, pch = 1)

rl <- extract_rl(caim$Blue, z, a, sky_points)

set.seed(7)
model <- fit_cie_sky_model(rl, sun_coord,
                           general_sky_type = "Clear",
                           twilight = FALSE,
                           method = "CG")
summary(model$mle2_output)
plot(model$obs, model$pred)
abline(0,1)
lm(model$pred~model$obs) %>% summary()

sky_cie <- cie_sky_model_raster(z, a,
                                model$sun_coord$zenith_azimuth,
                                model$coef) * model$zenith_dn
plot(sky_cie)
plot(caim$Blue/sky_cie)

## End(Not run)

Description

Statistical modeling for predicting digital numbers from spherical coordinates.

Usage

fit_coneshaped_model(sky_points, use_azimuth_angle = TRUE)

Arguments

Details

This method was presented in Díaz and Lencinas (2018), under the heading Estimation of the sky DN as a previous step for our method. If you use this function in your research, please cite that paper in addition to this package (⁠citation("rcaiman"⁠).

Value

A list of two objects, one of class function and the other of class lm (see stats::lm()). If the fitting fails, it returns NULL. The function requires two arguments–zenith and azimuth in degrees–to return relative luminance.

References

Díaz GM, Lencinas JD (2018). “Model-based local thresholding for canopy hemispherical photography.” Canadian Journal of Forest Research, 48(10), 1204–1216. doi:10.1139/cjfr-2018-0006.

Wagner S (2001). “Relative radiance measurements and zenith angle dependent segmentation in hemispherical photography.” Agricultural and Forest Meteorology, 107(2), 103–115. doi:10.1016/s0168-1923(00)00232-x.

See Also

thr_mblt()

Other Sky Reconstruction Functions: cie_sky_model_raster(), fit_cie_sky_model(), fit_trend_surface(), interpolate_and_merge(), interpolate_sky_points(), ootb_fit_cie_sky_model()

Examples

## Not run: 
path <- system.file("external/DSCN4500.JPG", package = "rcaiman")
caim <- read_caim(path, c(1250, 1020) - 745, 745 * 2, 745 * 2)
z <- zenith_image(ncol(caim), lens("Nikon_FCE9"))
a <- azimuth_image(z)
r <- gbc(caim$Blue)
r <- correct_vignetting(r, z, c(0.0638, -0.101)) %>% normalize()

bin <- regional_thresholding(r, rings_segmentation(z, 30), "thr_isodata")
bin <- bin & mask_hs(z, 0, 80)
sky_points <- extract_sky_points(r, bin, sky_grid_segmentation(z, a, 3))
sky_points <- extract_rl(r, z, a, sky_points, no_of_points = NULL)

model <- fit_coneshaped_model(sky_points$sky_points)
summary(model$model)
sky_cs <- model$fun(z, a)
plot(r/sky_cs)
plot(sky_cs)
plot(r/sky_cs > 0.5)

z <- zenith_image(50, lens())
a <- azimuth_image(z)
sky_cs <- model$fun(z, a)
persp(sky_cs, theta = 90, phi = 20)

## End(Not run)

Description

Fit a trend surface using spatial::surf.ls() as workhorse function.

Usage

fit_trend_surface(r, z, a, bin, filling_source = NULL, np = 6)

Arguments

Details

This function is meant to be used after fit_coneshaped_model().

This method was presented in Díaz and Lencinas (2018), under the heading Estimation of the sky DN as a previous step for our method. If you use this function in your research, please cite that paper in addition to this package (⁠citation("rcaiman"⁠).

Value

A list with an object of class SpatRaster and of class trls (see spatial::surf.ls()).

Note

If an incomplete above-canopy image is available as filling source, non-sky pixels should be turned NA or they will be erroneously considered as sky pixels.

References

Díaz GM, Lencinas JD (2018). “Model-based local thresholding for canopy hemispherical photography.” Canadian Journal of Forest Research, 48(10), 1204–1216. doi:10.1139/cjfr-2018-0006.

See Also

thr_mblt()

Other Sky Reconstruction Functions: cie_sky_model_raster(), fit_cie_sky_model(), fit_coneshaped_model(), interpolate_and_merge(), interpolate_sky_points(), ootb_fit_cie_sky_model()

Examples

## Not run: 
path <- system.file("external/DSCN4500.JPG", package = "rcaiman")
caim <- read_caim(path, c(1250, 1020) - 745, 745 * 2, 745 * 2)
z <- zenith_image(ncol(caim), lens("Nikon_FCE9"))
a <- azimuth_image(z)
r <- gbc(caim$Blue)
r <- correct_vignetting(r, z, c(0.0638, -0.101)) %>% normalize()

bin <- regional_thresholding(r, rings_segmentation(z, 30), "thr_isodata")
bin <- bin & mask_hs(z, 0, 80)
sky_points <- extract_sky_points(r, bin, sky_grid_segmentation(z, a, 3))
sky_points <- extract_rl(r, z, a, sky_points, no_of_points = NULL)

model <- fit_coneshaped_model(sky_points$sky_points)
summary(model$model)
sky_cs <- model$fun(z, a)
plot(sky_cs)
plot(r/sky_cs)

sky_s <- fit_trend_surface(r, z, a, bin, sky_cs)$image
plot(sky_s)
plot(r/sky_s)

## End(Not run)

Description

Gamma back correction of JPEG images

Usage

gbc(DN_from_JPEG, gamma = 2.2)

Arguments

Details

Digital cameras usually use sRGB as color space. It is a standard developed to ensure accurate color and tone management. The transfer function of sRGB, known as gamma correction, is very close to a power function with the exponent 1/2.2. This is why a DN of a born-digital photograph that was encoded in sRGB has a non-linear relationship with luminance despite having the sensor a linear response to it.

Value

The same class as the DN_from_JPEG argument, with dimension unchanged but values rescaled between 0 and 1 in a non-linear fashion.

References

Díaz GM, Lencinas JD (2018). “Model-based local thresholding for canopy hemispherical photography.” Canadian Journal of Forest Research, 48(10), 1204–1216. doi:10.1139/cjfr-2018-0006.

See Also

Other Pre-processing Functions: enhance_caim(), local_fuzzy_thresholding(), membership_to_color(), normalize()

Examples

path <- system.file("external/DSCN4500.JPG", package = "rcaiman")
r <- read_caim(path, c(1250, 1020) - 745, 745 * 2, 745 * 2)
r
gbc(r)

Description

This function is part of the efforts to automate the method proposed by Lang et al. (2010). A paper for thoroughly presenting and testing this pipeline is under preparation.

Usage

interpolate_and_merge(r, z, a, sky_points, ootb_sky, rmax_tune = 1)

Arguments

Value

An object of class SpatRaster.

References

Lang M, Kuusk A, Mõttus M, Rautiainen M, Nilson T (2010). “Canopy gap fraction estimation from digital hemispherical images using sky radiance models and a linear conversion method.” Agricultural and Forest Meteorology, 150(1), 20–29. doi:10.1016/j.agrformet.2009.08.001.

See Also

Other Sky Reconstruction Functions: cie_sky_model_raster(), fit_cie_sky_model(), fit_coneshaped_model(), fit_trend_surface(), interpolate_sky_points(), ootb_fit_cie_sky_model()

Examples

## Not run: 
caim <- read_caim()
r <- caim$Blue
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)

path <- system.file("external/ootb_sky.txt", package = "rcaiman")
ootb_sky <- read_ootb_sky_model(gsub(".txt", "", path))

sky <- interpolate_and_merge(r, z, a, ootb_sky$sky_points[,c("row", "col")],
                             ootb_sky)

bin <- apply_thr(r/sky$sky, 0.75)
plot(bin)

g <- sky_grid_segmentation(z, a, 5, first_ring_different = TRUE)
sky_points <- extract_sky_points(r, bin, g, dist_to_plant = 3,
                                 min_raster_dist = 9)

points(ootb_sky$sky_points$col, nrow(caim) - ootb_sky$sky_points$row,
       col = 2, pch = 10)
points(sky_points$col, nrow(caim) - sky_points$row, col = 4, pch = 10)
sky_points <- extract_rl(r, z, a, sky_points, no_of_points = NULL)$sky_points
i <- sor_filter(sky_points, r, k = 3)

sky2 <- interpolate_and_merge(r, z, a, sky_points[i, c("row", "col")],
                              ootb_sky, rmax_tune = 0.75)
plot(sky2$sky)

sky_points <- expand_sky_points(r, z, a, sky_points[i, c("row", "col")],
                                angle_width = 1.875,
                                k= 3, rmax = 20)
sky_points <- sor_filter(sky_points) %>% sky_points[. ,]
sky2 <- interpolate_and_merge(r, z, a, sky_points, ootb_sky, rmax_tune = 0.75)
plot(sky2$sky)

## End(Not run)

Description

Interpolate values from canopy photographs.

Usage

interpolate_sky_points(sky_points, r, k = 3, p = 2, rmax = 200, col_id = "rl")

Arguments

Details

This function use lidR::knnidw() as workhorse function, so arguments k, p, and rmax are passed to it.

This function is based on Lang et al. (2010). In theory, the best result would be obtained with data showing a linear relation between digital numbers and the amount of light reaching the sensor. See extract_radiometry() and read_caim_raw() for further details. As a compromise solution, gbc() can be used.

Default parameters are the ones used by Lang et al. (2010). The argument rmax should account for between 15 to 20 degrees, but it is expressed in pixels units. So, image resolution and lens projections should be taken into account to set this argument properly.

Value

An object of class SpatRaster.

References

Lang M, Kuusk A, Mõttus M, Rautiainen M, Nilson T (2010). “Canopy gap fraction estimation from digital hemispherical images using sky radiance models and a linear conversion method.” Agricultural and Forest Meteorology, 150(1), 20–29. doi:10.1016/j.agrformet.2009.08.001.

See Also

Other Sky Reconstruction Functions: cie_sky_model_raster(), fit_cie_sky_model(), fit_coneshaped_model(), fit_trend_surface(), interpolate_and_merge(), ootb_fit_cie_sky_model()

Examples

## Not run: 
caim <- read_caim()
r <- caim$Blue %>% normalize()
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)
m <- !is.na(z)
bin <- regional_thresholding(r, rings_segmentation(z, 30),
                             method = "thr_isodata")
mx <- optim_normalize(caim, bin)
caim <- normalize(caim, 0, mx, TRUE)

sky_blue <- HSV(239, 0.85, 0.5)
ecaim <- enhance_caim(caim, m, sky_blue = sky_blue)
bin <- apply_thr(ecaim, thr_isodata(ecaim[m]))

g <- sky_grid_segmentation(z, a, 10)
sky_points <- extract_sky_points(r, bin, g, dist_to_plant = 3)
plot(bin)
points(sky_points$col, nrow(caim) - sky_points$row, col = 2, pch = 10)
sky_points <- extract_dn(r, sky_points)

sky <- interpolate_sky_points(sky_points, r, col_id = 3)
plot(sky)
plot(r/sky)

## End(Not run)

Description

Database of lens projection functions and field of views.

Usage

lens(type = "equidistant", max_fov = FALSE)

Arguments

Details

In upward-looking leveled hemispherical photography, the zenith is the center of a circle whose perimeter is the horizon. This is true only if the lens field of view is 180º. The relative radius is the radius of concentric circles expressed as a fraction of the radius that belongs to the circle that has the horizon as perimeter. The equidistant model, also called polar, is the most widely used as a standard reference. Real lenses can approximate the projection models, but they always have some kind of distortion. In the equidistant model, the relation between zenith angle and relative radius is modeled with a straight line. Following Hemisfer software, this package uses a polynomial curve to model lens distortion. A third-order polynomial is sufficient in most cases (Frazer et al. 2001). Equations should be fitted with angles in radians.

Eventually, this will be a large database, but only the following lenses are available at the moment:

• equidistant: standard equidistant projection (Schneider et al. 2009).

• Nikkor_10.5mm: AF DX Fisheye Nikkor 10.5mm f/2.8G ED (Pekin and Macfarlane 2009)

• Nikon_FCE9: Nikon FC-E9 converter (Díaz et al. 2024)

• Olloclip: Auxiliary lens for mobile devices made by Olloclip (Díaz et al. 2024)

• Nikkor_8mm: AF–S Fisheye Nikkor 8–15mm f/3.5–4.5E ED (Díaz et al. 2024)

Value

If max_fov is set to TRUE, it returns a numeric vector of length one, which is the lens maximum field of view in degrees. Otherwise, it returns a numeric vector with the coefficients of the lens function.

References

Díaz GM, Lang M, Kaha M (2024). “Simple calibration of fisheye lenses for hemipherical photography of the forest canopy.” Agricultural and Forest Meteorology, 352, 110020. ISSN 0168-1923, doi:10.1016/j.agrformet.2024.110020.

Frazer GW, Fournier RA, Trofymow JA, Hall RJ (2001). “A comparison of digital and film fisheye photography for analysis of forest canopy structure and gap light transmission.” Agricultural and Forest Meteorology, 109(4), 249–263. doi:10.1016/s0168-1923(01)00274-x.

Pekin B, Macfarlane C (2009). “Measurement of crown cover and leaf area index using digital cover photography and its application to remote sensing.” Remote Sensing, 1(4), 1298–1320. doi:10.3390/rs1041298.

Schneider D, Schwalbe E, Maas H (2009). “Validation of geometric models for fisheye lenses.” ISPRS Journal of Photogrammetry and Remote Sensing, 64(3), 259–266. doi:10.1016/j.isprsjprs.2009.01.001.

See Also

Other Lens Functions: azimuth_image(), calc_diameter(), calc_relative_radius(), calc_zenith_colrow(), calibrate_lens(), crosscalibrate_lens(), expand_noncircular(), extract_radiometry(), fisheye_to_equidistant(), fisheye_to_pano(), test_lens_coef(), zenith_image()

Examples

lens("Nikon_FCE9")
lens("Nikon_FCE9", max_fov = TRUE)

.fp <- function(theta, lens_coef) {
  x <- lens_coef[1:5]
  x[is.na(x)] <- 0
  for (i in 1:5) assign(letters[i], x[i])
  a * theta + b * theta^2 + c * theta^3 + d * theta^4 + e * theta^5
}

theta <- seq(0, pi/2, pi/180)
plot(theta, .fp(theta, lens()), type = "l", lty = 2,
      ylab = "relative radius")
lines(theta, .fp(theta, lens("Nikon_FCE9")))

Description

This function was first presented in Díaz and Lencinas (2015). It uses a threshold value as the location parameter of a logistic membership function whose scale parameter depends on a variable, here named mem. This dependence can be explained as follows: if the variable is equal to 1, then the membership function is same as a threshold function because the scale parameter is 0; lowering the variable increases the scale parameter, thus blurring the threshold because it decreases the steepness of the curve. Since the variable is defined pixel by pixel, this should be considered as a local fuzzy thresholding method.

Usage

local_fuzzy_thresholding(lightness, m, mem, thr = NULL, fuzziness = NULL)

Arguments

Details

Argument m can be used to affect the automatic estimation of thr and fuzziness.

If you use this function in your research, please cite Díaz and Lencinas (2015) in addition to this package (⁠citation("rcaiman"⁠).

Value

An object of class SpatRaster with same pixel dimensions than caim. Depending on mem, changes could be subtle.

References

Díaz GM, Lencinas JD (2015). “Enhanced gap fraction extraction from hemispherical photography.” IEEE Geoscience and Remote Sensing Letters, 12(8), 1785–1789. doi:10.1109/lgrs.2015.2425931.

See Also

Other Pre-processing Functions: enhance_caim(), gbc(), membership_to_color(), normalize()

Examples

## Not run: 
caim <- read_caim()
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)
m <- !is.na(z)

caim <- normalize(caim)

# ImageJ can be used to digitize points
path <- system.file("external/sky_points.csv",
                    package = "rcaiman")
img_points <- read.csv(path)
img_points <- img_points[c("Y", "X")]
colnames(img_points) <- c("row", "col")
head(img_points)
target_color <- extract_dn(caim, img_points, fun = median)
as(target_color, "HSV")
target_color <- HSV(240, 0.85, 0.5) #to increase saturation

mem <- membership_to_color(caim, target_color)
mem_thr <- local_fuzzy_thresholding(mean(caim), m,  mem$membership_to_grey)
plot(mem_thr)

## End(Not run)

Description

Given a zenith or azimuth image and angle restrictions, this function produces a mask.

Usage

mask_hs(r, from, to)

Arguments

Value

An object of class SpatRaster with values 0 and 1.

See Also

masking()

Other Segmentation Functions: chessboard(), mask_sunlit_canopy(), polar_qtree(), qtree(), rings_segmentation(), sectors_segmentation(), sky_grid_segmentation()

Examples

## Not run: 
z <- zenith_image(1000, lens())
a <- azimuth_image(z)
m1 <- mask_hs(z, 20, 70)
plot(m1)
m2 <- mask_hs(a, 330,360)
plot(m2)
plot(m1 & m2)
plot(m1 | m2)

# 15 degrees at each side of 0
m1 <- mask_hs(a, 0, 15)
m2 <- mask_hs(a, 345, 360)
plot(m1 | m2)

# better use this
plot(!is.na(z))
# instead of this
plot(mask_hs(z, 0, 90))

## End(Not run)

Description

It is a wrapper function around membership_to_color(). It was developed with images in sRGB color space (Díaz 2023).

Usage

mask_sunlit_canopy(caim, m = NULL)

Arguments

Value

An object of class SpatRaster with values 0 and 1.

References

Díaz GM (2023). “Optimizing forest canopy structure retrieval from smartphone-based hemispherical photography.” Methods in Ecology and Evolution, 14(3), 875–884. doi:10.1111/2041-210x.14059.

See Also

Other Segmentation Functions: chessboard(), mask_hs(), polar_qtree(), qtree(), rings_segmentation(), sectors_segmentation(), sky_grid_segmentation()

Examples

## Not run: 
path <- system.file("external/APC_0020.jpg", package = "rcaiman")
caim <- read_caim(path)
plotRGB(caim)
caim <- normalize(caim)
m <- mask_sunlit_canopy(caim)
plot(m)

## End(Not run)

Description

Image masking

Usage

masking(r, m, RGB = c(1, 0, 0))

Arguments

Value

An object of class SpatRaster that essentially is r with areas where m is equal to zero painted in a solid color. If r is a single layer image, then the layer is triplicated to allow the use of color.

See Also

mask_hs()

Other Tool Functions: calc_oor_index(), calc_sngd(), colorfulness(), correct_vignetting(), defuzzify(), expand_sky_points(), extract_dn(), extract_feature(), extract_rl(), extract_sky_points(), extract_sun_coord(), find_general_sky_type(), find_sky_pixels(), optim_normalize(), percentage_of_clipped_highlights(), read_bin(), read_caim(), read_caim_raw(), read_ootb_sky_model(), sor_filter(), write_bin(), write_caim(), write_ootb_sky_model()

Examples

## Not run: 
 r <- read_caim()
 z <- zenith_image(ncol(r), lens())
 a <- azimuth_image(z)
 m <- mask_hs(z, 20, 70) & mask_hs(a, 90, 180)

 masked_caim <-  masking(normalize(r), m)
 plotRGB(masked_caim * 255)

 masked_bin <- masking(apply_thr(r$Blue, 125), m)
 plotRGB(masked_bin * 255)
 
## End(Not run)

Description

This function was first presented in Díaz and Lencinas (2015). It computes the degree of membership to a color using two Gaussian membership functions and the axes A and B from the CIE LAB color space. The lightness dimension is not considered in the calculations.

Usage

membership_to_color(caim, target_color, sigma = NULL)

Arguments

Details

If you use this function in your research, please cite Díaz and Lencinas (2015) in addition to this package (⁠citation("rcaiman"⁠).

Value

It returns an object of the class SpatRaster. First layer is the membership to the target color. Second layer is the membership to grey. Both memberships are calculated with same sigma.

References

Díaz GM, Lencinas JD (2015). “Enhanced gap fraction extraction from hemispherical photography.” IEEE Geoscience and Remote Sensing Letters, 12(8), 1785–1789. doi:10.1109/lgrs.2015.2425931.

See Also

Other Pre-processing Functions: enhance_caim(), gbc(), local_fuzzy_thresholding(), normalize()

Examples

## Not run: 
caim <- read_caim() %>% normalize
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)
m <- !is.na(z)

sky_blue <- HSV(239, 0.85, 0.5)
mem <- membership_to_color(caim, sky_blue)
plot(mem)

## End(Not run)

Description

Normalize numeric and raster data.

Usage

normalize(r, mn = NULL, mx = NULL, force_range = FALSE)

Arguments

Details

Normalize data laying between mn and mx to the range 0 to 1. Data greater than mx get values greater than 1 in a proportional fashion. Conversely, data less than mn get values less than 0.This function can be used for linear stretching of the histogram.