% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/generate_sky.R
\name{generate_sky}
\alias{generate_sky}
\title{Generate a Hosek-Wilkie sky dome array}
\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
)
}
\arguments{
\item{filename}{Default \code{NA}. Path to an image file to write. If not given, the array is returned instead.}

\item{albedo}{Default \code{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.}

\item{turbidity}{Default \code{3}. 1.7-10 atmospheric turbidity. Only valid for Hosek model.}

\item{elevation}{Default \code{10}. Solar elevation above the horizon (degrees).}

\item{azimuth}{Default \code{90}, sun directly east. Solar azimuth (degrees). The left edge of the image faces north and the middle faces south.}

\item{altitude}{Default \code{0}. Altitude of the viewer in meters. Valid range: 0 to 15000. Only valid for the Prague model.}

\item{resolution}{Default \code{2048}. Height of the image. Width is twice this number.}

\item{number_cores}{Default \code{1}. Number of threads to use in computation.}

\item{hosek}{Default \code{TRUE}. Set to \code{FALSE} to enable the Prague 2021-22 spectral sky model.}

\item{wide_spectrum}{Default \code{FALSE}. Use the 55-channel Prague coefficients (sea level only).}

\item{visibility}{Default \code{50}. Meteorological range in kilometres for Prague model.}

\item{verbose}{Default \code{FALSE}. Whether to print progress bars/diagnostic info.}

\item{render_mode}{Default \code{"all"}. One of \code{"all"}, \code{"atmosphere"}, or \code{"sun"}.
Use \code{"all"} for atmosphere + solar disk, \code{"atmosphere"} for atmospheric radiance only, or \code{"sun"} for the solar disk only.}

\item{below_horizon}{Default \code{TRUE}. Whether to sample atmospheric scattering below the horizon, which is non-zero when altitude > 0.}
}
\value{
Either the image array, or the array is invisibly returned if a file
is written. The array has dimensions \verb{(resolution, 2 * resolution, 4)}.
}
\description{
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 \code{filename} is supplied.
}
\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)

\dontshow{if (interactive() || identical(Sys.getenv("IN_PKGDOWN"), "true")) withAutoprint(\{ # examplesIf}
# 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()
\dontshow{\}) # examplesIf}
}
