write_sky_cie: Write and read out-of-the-box CIE sky model and raster

In rcaiman: CAnopy IMage ANalysis

Write and read out-of-the-box CIE sky model and raster

Description

Persist and restore the out-of-the-box CIE sky model, its diagnostics, and related rasters/points. The writer produces a human-readable .txt manifest plus CSV and GeoPackage sidecar files. The reader reconstructs a list object compatible with the out-of-the-box pipeline.

Usage

write_sky_cie(sky_cie, name)

read_sky_cie(name, r, z, a, refit_allowed = FALSE)

Arguments

sky_cie	list. Object holding the fitted CIE model, diagnostics, and derived rasters, as produced by the out-of-the-box workflow.
name	character vector of length one. File base name without extension. A path can be included, e.g., "C:/Users/Doe/Documents/DSCN4500".
r	numeric terra::SpatRaster of one layer. The canopy image used in the out-of-the-box workflow (used by read_sky_cie() when refitting).
z	terra::SpatRaster generated with zenith_image().
a	terra::SpatRaster generated with azimuth_image().
refit_allowed	logical vector of length one. If TRUE, allow automatic re-fit when manual edits are detected.

Details

Encoding is UTF-8. Decimal point is .. Unknown keys are ignored with a warning. Missing required keys trigger an error. The manifest begins with ⁠format_version:⁠ which is checked for basic compatibility.

When read_sky_cie() detects manual edits (moved sun disk or changed sky points) and refit_allowed = TRUE, it re-fits the CIE model using the current r, z, and a, then revalidates.

Value

See Functions.

Functions

write_sky_cie

No return value. Writes six files to disk with the prefix name (see below).

read_sky_cie

Returns a list similar to the output of ootb_sky_cie() and suitable as input to ootb_sky_above().

Files written by write_sky_cie

• Plain text manifest: name.txt

• CSV with sky radiance samples: name_rr.csv

• CSV with sky radiance samples for the upward pass: name_rr_up.csv (optional)

• GeoPackage with sky sample points: name_sky_points.gpkg

• GeoPackage with the sun disk location: name_sun_disk.gpkg

• CSV with validation pairs: name_val.csv

Text file keys

⁠format_version:⁠

Semantic version of the manifest.

⁠sun_theta:⁠

Solar zenith (deg).

⁠sun_phi:⁠

Solar azimuth (deg).

⁠method_sun:⁠

Method used to optimize sun coordinates.

⁠zenith_dn:⁠

Reference DN at zenith.

⁠start_a:⁠…⁠start_e:⁠

Initial CIE coefficients.

⁠is_from_detected_sky_dn:⁠

Enables ⁠_rr_up.csv⁠ if TRUE.

⁠fit_a:⁠…⁠fit_e:⁠

Fitted CIE coefficients.

⁠method:⁠

Method used to fit CIE coefficients.

⁠dist_to_black:⁠

Argument passed to extract_sky_points().

⁠grid:⁠

Sky grid parameters (angle_width, first_ring_different).

⁠min_spherical_dist:⁠

Sampling buffer distance (deg).

⁠sky_points_no:⁠

Number of sky points.

⁠outliers_no:⁠

Number of sky points that were detected as outliers.

⁠rmse:⁠

Validation metrics. Root mean squared error.

⁠r_squared:⁠

Validation metric. Coefficient of determination.

⁠mae:⁠

Validation metrics. Mean absolute error.

⁠[Tested: …]⁠

Enumerates tested methods/grids/distances.

Examples

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

# Read a previously written model
path <- system.file("external/example.txt", package = "rcaiman")
sky_cie <- read_sky_cie(gsub(".txt", "", path), r = caim$Blue, z = z, a = a,
                        refit_allowed = TRUE)

## End(Not run)

rcaiman documentation built on Sept. 9, 2025, 5:42 p.m.