% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/planets.R
\name{generate_planets}
\alias{generate_planets}
\title{Generate a bright-planet image array}
\usage{
generate_planets(
  datetime,
  lon,
  lat,
  filename = NA,
  resolution = 2048,
  turbidity = 3,
  ozone_du = 300,
  altitude = 0,
  color = FALSE,
  planet_width = 1,
  upper_hemisphere_only = TRUE,
  atmosphere_effects = TRUE,
  number_cores = 1,
  verbose = FALSE
)
}
\arguments{
\item{datetime}{POSIXct timestamp used for ephemerides.}

\item{lon}{Observer longitude in degrees (east positive).}

\item{lat}{Observer latitude in degrees.}

\item{filename}{Default \code{NA}. Destination image path to write. When \code{NA}, the
image array is returned without writing.}

\item{resolution}{Default \code{2048}. Map half-width (image is \code{2 * resolution} by \code{resolution}).}

\item{turbidity}{Atmospheric turbidity for extinction modelling.}

\item{ozone_du}{Column ozone (Dobson Units) for colour shifts.}

\item{altitude}{Observer altitude in metres.}

\item{color}{Render RGB (\code{TRUE}) stars or monochrome (\code{FALSE}).}

\item{planet_width}{Approximate point-spread size for planets in pixels.}

\item{upper_hemisphere_only}{If \code{TRUE}, mask pixels below the horizon.}

\item{atmosphere_effects}{If \code{TRUE}, apply atmospheric extinction.}

\item{number_cores}{CPU threads used for rendering.}

\item{verbose}{Emit diagnostic output when \code{TRUE}.}
}
\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{
Build a planetary luminance map aligned with the sky dome for
compositing within \code{\link[=generate_sky_latlong]{generate_sky_latlong()}}.
}
\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{
\dontshow{if (interactive() || identical(Sys.getenv("IN_PKGDOWN"), "true")) withAutoprint(\{ # examplesIf}
# Basic star field over Washington, DC at a fixed time
generate_planets(
  datetime = as.POSIXct("2025-03-21 02:20:00", tz = "America/New_York"),
  lon = -77.0369,
  lat = 38.9072,
  resolution = 400,
  color = TRUE,
  planet_width = 1,
  atmosphere_effects = TRUE,
  upper_hemisphere_only = TRUE,
  number_cores = 2
) |>
  rayimage::plot_image()
\dontshow{\}) # examplesIf}
}
