% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/generate_sky.R
\name{generate_sky_latlong}
\alias{generate_sky_latlong}
\title{Generate a location and time-specific sky dome (optionally with stars)}
\usage{
generate_sky_latlong(
  datetime,
  lat,
  lon,
  filename = NA,
  albedo = 0.5,
  turbidity = 3,
  altitude = 0,
  resolution = 2048,
  number_cores = 1,
  hosek = TRUE,
  wide_spectrum = FALSE,
  visibility = 50,
  stars = FALSE,
  star_width = 1,
  planets = FALSE,
  moon = FALSE,
  moon_atmosphere = FALSE,
  moon_hosek = TRUE,
  render_mode = "all",
  below_horizon = TRUE,
  verbose = FALSE,
  stars_exposure = 0,
  ...
)
}
\arguments{
\item{datetime}{POSIX-compatible date-time.}

\item{lat}{Observer latitude (degrees N).}

\item{lon}{Observer longitude (degrees E; west < 0).}

\item{filename}{Default \code{NA}. Path to the \code{.exr} file to write.}

\item{albedo}{Default \code{0.5}. Ground albedo, range 0 to 1.}

\item{turbidity}{Default \code{3}. Atmospheric turbidity, range
1.7 to 10 (\emph{Hosek only}).}

\item{altitude}{Default \code{0}. Observer altitude (m), range
0 to 15000 (\emph{Prague only}).}

\item{resolution}{Default \code{2048}. Image height in pixels (width = 2 * height).}

\item{number_cores}{Default \code{1}. CPU threads to use.}

\item{hosek}{Default \code{TRUE}. \code{FALSE} selects the Prague model.}

\item{wide_spectrum}{Default \code{FALSE}. 55-channel Prague coefficients (altitude = 0m only).}

\item{visibility}{Default \code{50}. Meteorological range (km); \emph{Prague only}.}

\item{stars}{Default \code{FALSE}. If \code{TRUE}, composite a star field
using \code{\link[=generate_stars]{generate_stars()}}. Automatically falls back to a pure star render
when the black-sky condition is met (see \emph{Details}).}

\item{star_width}{Default \code{1}. Passed to \code{\link[=generate_stars]{generate_stars()}} to control stellar point-spread size.}

\item{planets}{Default \code{FALSE}. If \code{TRUE}, composite bright planets via \code{\link[=generate_planets]{generate_planets()}}.}

\item{moon}{Default \code{FALSE}. If \code{TRUE}, overlay a moon render from \code{\link[=generate_moon_latlong]{generate_moon_latlong()}}.}

\item{moon_atmosphere}{Default \code{FALSE}. If \code{TRUE}, this generates atmospheric scattering from light from the moon.}

\item{moon_hosek}{Default \code{TRUE}. Whether to use the faster (but less accurate) Hosek model for atmospheric scattering from the moon. Note
that the light scattered from the moon is much less intense than the sun, and thus small inaccuracies are much less likely to be noticable.}

\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.}

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

\item{stars_exposure}{Default \code{0}. Increases star exposure by \code{2^exposure}. Non-physical, this just controls adjustments for artistic effect.}

\item{...}{Additional \strong{named} arguments forwarded to \code{\link[=generate_stars]{generate_stars()}}, and when enabled, \code{\link[=generate_planets]{generate_planets()}} and \code{\link[=generate_moon_latlong]{generate_moon_latlong()}}.
Unmatched names are ignored.}
}
\value{
Either the raw data, or the data is invisibly returned if filename is given. The EXR is written to \code{filename}.
}
\description{
Convenience wrapper around \code{\link[=generate_sky]{generate_sky()}} that:
\enumerate{
\item Computes the Sun's apparent position for \code{datetime}, \code{lat}, and \code{lon}
(via Swiss Ephemeris / \strong{swephR}).
\item Renders the corresponding sky model.
\item Optionally overlays a star field using \code{\link[=generate_stars]{generate_stars()}} or moon with \code{\link[=generate_moon_latlong]{generate_moon_latlong()}}.
}
}
\details{
\emph{Solar angles} - altitude (degrees above the horizon) and azimuth (degrees clockwise from
east, so 90 degrees = south) - are derived internally; you never have to supply
them directly.

\emph{Black-sky rule} - With the Prague model the sky radiance is defined only
down to -4.2 degrees, and with the Hosek model it is defined only about 0 degrees.
Below that the function skips the sky render and writes \strong{only stars} when \code{stars = TRUE}.
}
\examples{
sky = generate_sky_latlong(
  datetime = as.POSIXct("2025-03-21 12:00:00", tz = "America/New_York"),
  lat = 38.9072,
  lon = -77.0369,
  resolution = 8
)
dim(sky)

\dontshow{if (interactive() || identical(Sys.getenv("IN_PKGDOWN"), "true")) withAutoprint(\{ # examplesIf}
# Morning sunrise on spring solstice over Washington, DC with Prague model
generate_sky_latlong(
  datetime = as.POSIXct("2025-03-21 06:15:00", tz = "America/New_York"),
  lat = 38.9072,
  lon = -77.0369,
  number_cores = 2,
  hosek = FALSE
) |>
  rayimage::plot_image()

generate_sky_latlong(
  datetime = as.POSIXct("2025-03-21 12:00:00", tz = "America/New_York"),
  lat = 38.9072,
  lon = -77.0369,
  number_cores = 2
) |>
  rayimage::plot_image()

generate_sky_latlong(
  datetime = as.POSIXct("2025-03-21 18:00:00", tz = "America/New_York"),
  lat = 38.9072,
  lon = -77.0369,
  number_cores = 2
) |>
  rayimage::plot_image()

generate_sky_latlong(
  datetime = as.POSIXct("2025-03-21 18:30:00", tz = "America/New_York"),
  lat = 38.9072,
  lon = -77.0369,
  number_cores = 2,
  hosek = FALSE,
  verbose = TRUE
) |>
  rayimage::render_exposure(exposure = 2) |>
  rayimage::plot_image()
\dontshow{\}) # examplesIf}
}
