Generate a Hosek-Wilkie sky dome array — generate

Evaluate either the Hosek-Wilkie or Prague analytic sky models and return a high-dynamic-range image array for the given solar configuration. An image file is written only when filename is supplied.

Usage

generate_sky(
  filename = NA,
  albedo = 0.1,
  turbidity = 3,
  elevation = 10,
  azimuth = 90,
  altitude = 0,
  resolution = 2048,
  number_cores = 1,
  hosek = TRUE,
  wide_spectrum = FALSE,
  visibility = 50,
  verbose = FALSE,
  render_mode = "all",
  below_horizon = TRUE,
  prague_rgb_correction = TRUE,
  prague_rgb_correction_strength = 1,
  prague_rgb_correction_gain = "auto",
  exr_adopted_white = "D60",
  exr_metadata = TRUE
)

Arguments

filename: Default NA. Path to an image file to write. If not given, the array is returned instead.
albedo: Default 0.1. 0.0-1.0 ground albedo. Grass has an albedo of about 0.09, while a landscape covered in snow will have an albedo of 1.0.
turbidity: Default 3. 1.7-10 atmospheric turbidity. Only valid for Hosek model.
elevation: Default 10. Solar elevation above the horizon (degrees).
azimuth: Default 90, sun directly east. Solar azimuth (degrees). The left edge of the image faces north and the middle faces south.
altitude: Default 0. Altitude of the viewer in meters. Valid range: 0 to 15000. Only valid for the Prague model.
resolution: Default 2048. Height of the image. Width is twice this number.
number_cores: Default 1. Number of threads to use in computation.
hosek: Default TRUE. Set to FALSE to enable the Prague 2021-22 spectral sky model.
wide_spectrum: Default FALSE. Use the 55-channel Prague coefficients (sea level only).
visibility: Default 50. Meteorological range in kilometres for Prague model.
verbose: Default FALSE. Whether to print progress bars/diagnostic info.
render_mode: Default "all". One of "all", "atmosphere", or "sun". Use "all" for atmosphere + solar disk, "atmosphere" for atmospheric radiance only, or "sun" for the solar disk only.
below_horizon: Default TRUE. Whether to sample atmospheric scattering below the horizon, which is non-zero when altitude > 0.
prague_rgb_correction: Default TRUE. Whether to apply the Prague RGB tint correction. This correction is only applied when hosek = FALSE. Use FALSE for raw Prague RGB output.
prague_rgb_correction_strength: Default 1. Strength of the Prague RGB tint correction. Use 0 for no correction and 1 for the calibrated correction.
prague_rgb_correction_gain: Default "auto". Multiplicative linear RGB gain used by the Prague RGB tint correction. "auto" uses the calibrated default c(R = 0.94438727, G = 1.02157200, B = 0.95012063).
exr_adopted_white: Default "D60". Adopted neutral white to write to EXR metadata for generated sky maps. Currently supports "D60", "D65", or a numeric XYZ white with Y = 1. This tags the EXR adoptedNeutral metadata and does not change pixel values.
exr_metadata: Default TRUE. Whether to attach skymodelr EXR metadata before writing EXR output. Metadata includes sRGB/Rec.709 chromaticities and the selected adopted neutral white.

Value

Either the image array, or the array is invisibly returned if a file is written. The array has dimensions (resolution, 2 * resolution, 4).

Details

For Prague RGB output, prague_rgb_correction = TRUE applies a fixed linear RGB gain to reduce the small magenta / negative-green tint observed in the RGB projection of Prague sky maps. Set prague_rgb_correction = FALSE to recover raw Prague RGB output. The correction is not a white balance and is not applied to wavelength-specific spectral radiance.

EXR metadata: Generated sky maps are linear RGB. When exr_metadata = TRUE, skymodelr tags the image with sRGB/Rec.709 chromaticities and an EXR adoptedNeutral white. The default adopted neutral is D60. This metadata does not convert pixel values; it informs downstream readers how to treat the scene neutral. Use exr_adopted_white = "D65" for D65 adopted neutral, or exr_metadata = FALSE to omit skymodelr EXR metadata. The RGB encoding remains linear sRGB / Rec.709 even when the adopted neutral is D60.

Note

Writing to non-EXR formats will introduce precision loss because HDR data are quantised to the destination format, and low dynamic range outputs like PNG and JPEG files will not represent the true luminosity values encoded in the array.

Examples

sky = generate_sky(
  resolution = 8,
  elevation = 30,
  azimuth = 135,
  render_mode = "atmosphere"
)
dim(sky)
#> [1]  8 16  4

# Hosek model (default): clear morning, Sun SE, with solar disk
generate_sky(
  resolution = 400,
  elevation  = 15,
  azimuth    = 135,
  turbidity  = 3,
  render_mode = "all"
) |>
  rayimage::plot_image()


# Same view but hazier and without the solar disk
generate_sky(
  resolution = 400,
  elevation  = 15,
  azimuth    = 135,
  turbidity  = 6,
  render_mode = "atmosphere"
) |>
  rayimage::plot_image()


# Prague model (requires downloaded coefficients)
generate_sky(
  resolution = 400,
  hosek      = FALSE,
  altitude   = 0,
  visibility = 80,
  albedo     = 0.2,
  elevation  = 5,
  azimuth    = 220,
  number_cores = 2
) |>
  rayimage::plot_image()


generate_sky(
  "raw_prague.exr",
  elevation = 60,
  azimuth = 315,
  hosek = FALSE,
  prague_rgb_correction = FALSE
)