rcaiman (version 2.0.1)

write_sky_cie: 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)

Value

See Functions.

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.

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 <code>write_sky_cie</code>

• 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.

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.

Examples

if (FALSE) {
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)
}