| Title: | Generates and Samples Realistic Terrestrial Atmospheres |
|---|---|
| Description: | Generates physically based sky environment maps and radiance samples using the spectral Hosek-Wilkie and Prague atmosphere models. Functions write high-dynamic-range 'OpenEXR' domes in latitude-longitude projections, compute per-direction RGB or 55-channel values, and optionally composite time-accurate star fields and moon phases. Features include automatic sun and moon positioning from date, time and location, support for sea-level and high-altitude observers, wide-spectrum coefficients, and multithreaded C++ acceleration for fast, high-resolution output. For model details, see Hosek and Wilkie (2012) <doi:10.1145/2185520.2185591>, Hosek and Wilkie (2013) <doi:10.1109/MCG.2013.18>, Wilkie et al. (2021) <doi:10.1145/3450626.3459758>, and Vevoda et al. (2022) <doi:10.1111/cgf.14677>. |
| Authors: | Tyler Morgan-Wall [aut, cre, cph], Petr Vevoda [ctb], Charles University [cph], Eric Bruneton [ctb, cph], Lukas Hosek [ctb, cph], Alexander Wilkie [ctb, cph] |
| Maintainer: | Tyler Morgan-Wall <[email protected]> |
| License: | GPL-3 |
| Version: | 0.7.1 |
| Built: | 2026-11-16 06:17:38 UTC |
| Source: | https://github.com/tylermorganwall/skymodelr |
Evaluate the Prague spectral sky model at arbitrary spherical
directions and wavelengths, including grids of atmospheric conditions. Use
render_mode = "all" for atmosphere + solar disk, "atmosphere" for
atmospheric radiance only, or "sun" for the solar disk only.
calculate_sky_radiance( phi, theta, lambda_nm, altitude = 0, elevation = 10, visibility = 50, albedo = 0.5, azimuth = 90, number_cores = 1, wide_spectrum = FALSE, render_mode = "all", backend = "cpu" )calculate_sky_radiance( phi, theta, lambda_nm, altitude = 0, elevation = 10, visibility = 50, albedo = 0.5, azimuth = 90, number_cores = 1, wide_spectrum = FALSE, render_mode = "all", backend = "cpu" )
phi |
Azimuthal angle of the sample, degrees. Vectorized. Range 0 to 360. |
theta |
Vertical angle of the sample, degrees. Vectorized. Range -90 to 90. |
lambda_nm |
Wavelength in nanometers. Vectorized. Must lie within the loaded Prague dataset range. |
altitude |
Default |
elevation |
Default |
visibility |
Default |
albedo |
Default |
azimuth |
Default |
number_cores |
Default |
wide_spectrum |
Default |
render_mode |
Default |
backend |
Default |
Inputs are paired element by element, with shorter vectors recycled
by data.frame(). Use expand.grid() to form all combinations, then pass
its columns as the corresponding arguments. The function does not create a
Cartesian product automatically.
The GPU backend evaluates geometry, atmospheric radiance, and solar radiance
using the same Prague coefficients as the CPU backend. It uses single
precision, so results can differ slightly, especially near the solar limb.
Coefficients and compiled shaders are cached across calls; changing datasets
replaces the cached GPU coefficients. Large inputs are processed in bounded
batches. The initial upload and shader compilation can outweigh the benefit
for small inputs. An unavailable Metal device or a GPU failure raises an
error; use backend = "cpu" to evaluate on the CPU.
Numeric vector of spectral radiance values in W m^-2 sr^-1 nm^-1, in input row order.
# Compare the same direction and wavelength at two observer altitudes. lambda_vals = calculate_sky_radiance( phi = c(90, 90), theta = c(45, 45), lambda_nm = 550, altitude = c(0, 10000), elevation = 20, visibility = 80, albedo = 0.1 ) cbind(altitude = c(0, 10000), radiance = lambda_vals) # Form a direction-by-wavelength grid and preserve its row ordering. # On a Mac with Metal, add backend = "gpu" to evaluate the grid on the GPU. grid = expand.grid( phi = seq(0, 350, by = 10), theta = seq(0, 90, by = 10), lambda_nm = seq(380, 740, by = 20) ) grid$radiance = calculate_sky_radiance( phi = grid$phi, theta = grid$theta, lambda_nm = grid$lambda_nm, render_mode = "atmosphere" )# Compare the same direction and wavelength at two observer altitudes. lambda_vals = calculate_sky_radiance( phi = c(90, 90), theta = c(45, 45), lambda_nm = 550, altitude = c(0, 10000), elevation = 20, visibility = 80, albedo = 0.1 ) cbind(altitude = c(0, 10000), radiance = lambda_vals) # Form a direction-by-wavelength grid and preserve its row ordering. # On a Mac with Metal, add backend = "gpu" to evaluate the grid on the GPU. grid = expand.grid( phi = seq(0, 350, by = 10), theta = seq(0, 90, by = 10), lambda_nm = seq(380, 740, by = 20) ) grid$radiance = calculate_sky_radiance( phi = grid$phi, theta = grid$theta, lambda_nm = grid$lambda_nm, render_mode = "atmosphere" )
Evaluate the Prague spectral sky model at arbitrary spherical directions without writing an image, returning radiance-only samples.
calculate_sky_values( phi, theta, altitude = 0, elevation = 10, visibility = 50, albedo = 0.5, azimuth = 90, number_cores = 1, wide_spectrum = FALSE, render_mode = "all", prague_rgb_correction = TRUE, prague_rgb_correction_strength = 1, prague_rgb_correction_gain = "auto" )calculate_sky_values( phi, theta, altitude = 0, elevation = 10, visibility = 50, albedo = 0.5, azimuth = 90, number_cores = 1, wide_spectrum = FALSE, render_mode = "all", prague_rgb_correction = TRUE, prague_rgb_correction_strength = 1, prague_rgb_correction_gain = "auto" )
phi |
Horizontal angle of the sample, degrees. Vectorized. Range 0 to 360. |
theta |
Vertical angle of the sample, degrees. Vectorized. Range -90 to 90. |
altitude |
Default |
elevation |
Default |
visibility |
Default |
albedo |
Default |
azimuth |
Default |
number_cores |
Default |
wide_spectrum |
Default |
render_mode |
Default |
prague_rgb_correction |
Default |
prague_rgb_correction_strength |
Default |
prague_rgb_correction_gain |
Default |
3-column RGB matrix.
# Generate a basic atmosphere with the Prague model value_grid = expand.grid( phi = seq(0, 360, by = 30), theta = seq(0, 90, by = 10), altitude = c(0, 10000) ) vals = calculate_sky_values( phi = value_grid$phi, theta = value_grid$theta, altitude = value_grid$altitude, elevation = 45, visibility = 120, albedo = 0 ) cbind(value_grid, vals)# Generate a basic atmosphere with the Prague model value_grid = expand.grid( phi = seq(0, 360, by = 30), theta = seq(0, 90, by = 10), altitude = c(0, 10000) ) vals = calculate_sky_values( phi = value_grid$phi, theta = value_grid$theta, altitude = value_grid$altitude, elevation = 45, visibility = 120, albedo = 0 ) cbind(value_grid, vals)
Evaluate the Prague or Hosek sky model at the sun center and integrate against the CIE Y curve to return a luminance value. This is useful for relative attenuation (e.g., comparing zenith sun to a low sun).
calculate_sun_brightness( elevation = 10, azimuth = 90, albedo = 0.5, turbidity = 3, altitude = 0, visibility = 50, hosek = TRUE, wide_spectrum = FALSE, lambda_nm = NULL )calculate_sun_brightness( elevation = 10, azimuth = 90, albedo = 0.5, turbidity = 3, altitude = 0, visibility = 50, hosek = TRUE, wide_spectrum = FALSE, lambda_nm = NULL )
elevation |
Default |
azimuth |
Default |
albedo |
Default |
turbidity |
Default |
altitude |
Default |
visibility |
Default |
hosek |
Default |
wide_spectrum |
Default |
lambda_nm |
Optional vector of wavelengths for Hosek sampling. |
Numeric scalar of sun luminance (CIE Y, relative scale).
calculate_sun_brightness(elevation = 45, hosek = TRUE)calculate_sun_brightness(elevation = 45, hosek = TRUE)
Removes files cached by download_sky_data() under
tools::R_user_dir("skymodelr", "data").
clear_sky_data(files = NULL, ask = interactive())clear_sky_data(files = NULL, ask = interactive())
files |
Default |
ask |
Default |
Invisibly, the paths successfully removed.
clear_sky_data()clear_sky_data()
This model which allows for sun angles below the horizon, wide spectral ranges including infrared, polarization, as well rendering at altitude) need to download a coefficient file. There are three versions of this dataset, listed here in order of increasing size:
download_sky_data(sea_level = TRUE, wide_spectrum = FALSE)download_sky_data(sea_level = TRUE, wide_spectrum = FALSE)
sea_level |
Default |
wide_spectrum |
Default |
| Argument combination | File | Size |
sea_level = TRUE, wide_spectrum = FALSE |
SkyModelDatasetGround.dat |
107MB |
sea_level = TRUE, wide_spectrum = TRUE |
PragueSkyModelDatasetGroundInfra.dat |
574MB |
sea_level = FALSE |
SkyModelDataset.dat |
2.4GB |
Invisibly, the full path to the data file.
# Standard (11-channel, sea-level) coefficients download_sky_data() # Wide-spectrum sea-level coefficients download_sky_data(wide_spectrum = TRUE) # Full altitude-range coefficients download_sky_data(sea_level = FALSE)# Standard (11-channel, sea-level) coefficients download_sky_data() # Wide-spectrum sea-level coefficients download_sky_data(wide_spectrum = TRUE) # Full altitude-range coefficients download_sky_data(sea_level = FALSE)
Note that this is just a scaled version of generate_sky(), scaled down by the luminance
of the moon as compared to the sun. This function takes the phase of the moon into account,
along with the increase in luminosity around a full moon (known as opposition surge). Moonlight
attenuation uses the Rozenberg/Krisciunas-Schaefer airmass approximation with configurable moon_extinction_kV.
generate_moon_latlong( datetime, lat, lon, filename = NA, albedo = 0.5, turbidity = 3, altitude = 0, resolution = 2048, number_cores = 1, moon_atmosphere = FALSE, earthshine = TRUE, earthshine_albedo = 0.19, solar_irradiance_w_m2 = 1300, moon_extinction_kV = 0.172, hosek = TRUE, wide_spectrum = FALSE, visibility = 50, moon_texture_width = 801, moon_texture_height = 801, verbose = FALSE )generate_moon_latlong( datetime, lat, lon, filename = NA, albedo = 0.5, turbidity = 3, altitude = 0, resolution = 2048, number_cores = 1, moon_atmosphere = FALSE, earthshine = TRUE, earthshine_albedo = 0.19, solar_irradiance_w_m2 = 1300, moon_extinction_kV = 0.172, hosek = TRUE, wide_spectrum = FALSE, visibility = 50, moon_texture_width = 801, moon_texture_height = 801, verbose = FALSE )
datetime |
POSIX-compatible date-time. |
lat |
Observer latitude (degrees N). |
lon |
Observer longitude (degrees E; west < 0). |
filename |
Default |
albedo |
Default |
turbidity |
Default |
altitude |
Default |
resolution |
Default |
number_cores |
Default |
moon_atmosphere |
Default |
earthshine |
Default |
earthshine_albedo |
Default |
solar_irradiance_w_m2 |
Default |
moon_extinction_kV |
Default |
hosek |
Default |
wide_spectrum |
Default |
visibility |
Default |
moon_texture_width |
Default |
moon_texture_height |
Default |
verbose |
Default |
The complete lunar disk is calibrated before directions below the horizontal horizon are clipped. The upper limb remains visible after the center sets, with the finite horizon attenuation and tint retained below zero center elevation. The visible segment is not renormalized to the full Moon's brightness. Finite sky-map resolution limits how finely this edge is resolved.
Disk visibility is independent of the atmospheric model's elevation domain: the optional atmospheric component requires center elevation at least zero for Hosek or -4.2 degrees for Prague. Below that domain it is omitted, while any visible lunar limb is still drawn. Horizon depression and refraction are not modeled.
Either the image array, or the array is invisibly returned if a file
is written. The array has dimensions (resolution, 2 * resolution, 4).
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.
# Moonlit sky (Hosek), mid-evening in DC generate_moon_latlong( datetime = as.POSIXct("2025-09-05 19:30:00", tz = "America/New_York"), lat = 38.9072, lon = -77.0369, resolution = 400, turbidity = 3, verbose = TRUE ) |> rayimage::render_exposure(15) |> rayimage::plot_image()# Moonlit sky (Hosek), mid-evening in DC generate_moon_latlong( datetime = as.POSIXct("2025-09-05 19:30:00", tz = "America/New_York"), lat = 38.9072, lon = -77.0369, resolution = 400, turbidity = 3, verbose = TRUE ) |> rayimage::render_exposure(15) |> rayimage::plot_image()
Build a planetary luminance map aligned with the sky dome for
compositing within generate_sky_latlong().
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 )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 )
datetime |
POSIXct timestamp used for ephemerides. |
lon |
Observer longitude in degrees (east positive). |
lat |
Observer latitude in degrees. |
filename |
Default |
resolution |
Default |
turbidity |
Atmospheric turbidity for extinction modelling. |
ozone_du |
Column ozone (Dobson Units) for colour shifts. |
altitude |
Observer altitude in metres. |
color |
Render RGB ( |
planet_width |
Approximate point-spread size for planets in pixels. |
upper_hemisphere_only |
If |
atmosphere_effects |
If |
number_cores |
CPU threads used for rendering. |
verbose |
Emit diagnostic output when |
Either the image array, or the array is invisibly returned if a file
is written. The array has dimensions (resolution, 2 * resolution, 4).
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.
# 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()# 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()
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.
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 )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 )
filename |
Default |
albedo |
Default |
turbidity |
Default |
elevation |
Default |
azimuth |
Default |
altitude |
Default |
resolution |
Default |
number_cores |
Default |
hosek |
Default |
wide_spectrum |
Default |
visibility |
Default |
verbose |
Default |
render_mode |
Default |
below_horizon |
Default |
prague_rgb_correction |
Default |
prague_rgb_correction_strength |
Default |
prague_rgb_correction_gain |
Default |
exr_adopted_white |
Default |
exr_metadata |
Default |
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.
Either the image array, or the array is invisibly returned if a file
is written. The array has dimensions (resolution, 2 * resolution, 4).
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.
sky = generate_sky( resolution = 8, elevation = 30, azimuth = 135, render_mode = "atmosphere" ) dim(sky) # 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 )sky = generate_sky( resolution = 8, elevation = 30, azimuth = 135, render_mode = "atmosphere" ) dim(sky) # 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 )
Convenience wrapper around generate_sky() that:
Computes the Sun's apparent position for datetime, lat, and lon
(via Swiss Ephemeris / swephR).
Renders the corresponding sky model.
Optionally overlays a star field using generate_stars() or moon with generate_moon_latlong().
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, prague_rgb_correction = TRUE, prague_rgb_correction_strength = 1, prague_rgb_correction_gain = "auto", exr_adopted_white = "D60", exr_metadata = TRUE, verbose = FALSE, stars_exposure = 0, ... )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, prague_rgb_correction = TRUE, prague_rgb_correction_strength = 1, prague_rgb_correction_gain = "auto", exr_adopted_white = "D60", exr_metadata = TRUE, verbose = FALSE, stars_exposure = 0, ... )
datetime |
POSIX-compatible date-time. |
lat |
Observer latitude (degrees N). |
lon |
Observer longitude (degrees E; west < 0). |
filename |
Default |
albedo |
Default |
turbidity |
Default |
altitude |
Default |
resolution |
Default |
number_cores |
Default |
hosek |
Default |
wide_spectrum |
Default |
visibility |
Default |
stars |
Default |
star_width |
Default |
planets |
Default |
moon |
Default |
moon_atmosphere |
Default |
moon_hosek |
Default |
render_mode |
Default |
below_horizon |
Default |
prague_rgb_correction |
Default |
prague_rgb_correction_strength |
Default |
prague_rgb_correction_gain |
Default |
exr_adopted_white |
Default |
exr_metadata |
Default |
verbose |
Default |
stars_exposure |
Default |
... |
Additional named arguments forwarded to |
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.
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 only stars when stars = TRUE.
Either the raw data, or the data is invisibly returned if filename is given. The EXR is written to filename.
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) # 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()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) # 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()
generate_sky()
Render a star map for a given observer location, time, and atmospheric
conditions so it can be composited with generate_sky(). Returns a
(resolution, 2 * resolution, 4) array with an opaque alpha channel. An
image file is written only when filename is supplied.
generate_stars( lon, lat, datetime, filename = NA, resolution = 2048, turbidity = 3, ozone_du = 300, altitude = 0, color = TRUE, star_width = 1, upper_hemisphere_only = TRUE, atmosphere_effects = TRUE, number_cores = 1 )generate_stars( lon, lat, datetime, filename = NA, resolution = 2048, turbidity = 3, ozone_du = 300, altitude = 0, color = TRUE, star_width = 1, upper_hemisphere_only = TRUE, atmosphere_effects = TRUE, number_cores = 1 )
lon |
Observer longitude in degrees (east positive). |
lat |
Observer latitude in degrees. |
datetime |
|
filename |
Default |
resolution |
Default |
turbidity |
Default |
ozone_du |
Default |
altitude |
Default |
color |
Default |
star_width |
Default |
upper_hemisphere_only |
Default |
atmosphere_effects |
Default |
number_cores |
Default |
Either the image array, or the array is invisibly returned if a file
is written. The array has dimensions (resolution, 2 * resolution, 4).
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.
star_map = generate_stars( resolution = 8, lon = -77.0369, lat = 38.9072, datetime = as.POSIXct("2025-03-21 02:20:00", tz = "UTC"), atmosphere_effects = FALSE, number_cores = 1 ) dim(star_map) # Note: exposure has been increased for all examples (via white_point) for # ease of visibility in documentation # Basic star field over Washington, DC at a fixed time generate_stars( resolution = 400, lon = -77.0369, lat = 38.9072, datetime = as.POSIXct("2025-03-21 02:20:00", tz = "America/New_York"), color = TRUE, star_width = 1, atmosphere_effects = TRUE, upper_hemisphere_only = TRUE, number_cores = 2 ) |> rayimage::plot_image() # Monochrome stars, no atmospheric extinction/reddening, full sphere generate_stars( resolution = 400, lon = -122.4194, lat = 37.7749, datetime = as.POSIXct("2025-06-01 08:00:00", tz = "UTC"), color = FALSE, star_width = 1, upper_hemisphere_only = FALSE, atmosphere_effects = FALSE ) |> rayimage::plot_image() # Sharper stars (smaller PSF) with ozone/turbidity and altitude generate_stars( resolution = 400, lon = 10, lat = 45, datetime = as.POSIXct("2025-12-01 22:00:00", tz = "UTC"), star_width = 0.5, turbidity = 3.5, ozone_du = 320, altitude = 1000, color = TRUE ) |> rayimage::plot_image()star_map = generate_stars( resolution = 8, lon = -77.0369, lat = 38.9072, datetime = as.POSIXct("2025-03-21 02:20:00", tz = "UTC"), atmosphere_effects = FALSE, number_cores = 1 ) dim(star_map) # Note: exposure has been increased for all examples (via white_point) for # ease of visibility in documentation # Basic star field over Washington, DC at a fixed time generate_stars( resolution = 400, lon = -77.0369, lat = 38.9072, datetime = as.POSIXct("2025-03-21 02:20:00", tz = "America/New_York"), color = TRUE, star_width = 1, atmosphere_effects = TRUE, upper_hemisphere_only = TRUE, number_cores = 2 ) |> rayimage::plot_image() # Monochrome stars, no atmospheric extinction/reddening, full sphere generate_stars( resolution = 400, lon = -122.4194, lat = 37.7749, datetime = as.POSIXct("2025-06-01 08:00:00", tz = "UTC"), color = FALSE, star_width = 1, upper_hemisphere_only = FALSE, atmosphere_effects = FALSE ) |> rayimage::plot_image() # Sharper stars (smaller PSF) with ozone/turbidity and altitude generate_stars( resolution = 400, lon = 10, lat = 45, datetime = as.POSIXct("2025-12-01 22:00:00", tz = "UTC"), star_width = 0.5, turbidity = 3.5, ozone_du = 320, altitude = 1000, color = TRUE ) |> rayimage::plot_image()
Generate a celestial disk directly at texture resolution, independently of an environment map. The Sun supports Prague and Hosek radiance profiles. The Moon uses the existing lunar surface texture, topocentric phase orientation, earthshine, photometry, and atmospheric extinction.
generate_sun_disk( datetime, lat, lon, altitude = 0, resolution = 256, visibility = 50, albedo = 0.5, number_cores = 1, wide_spectrum = FALSE, prague_rgb_correction = TRUE, prague_rgb_correction_strength = 1, prague_rgb_correction_gain = "auto", atmospheric_attenuation = TRUE, hosek = FALSE, turbidity = 3, elevation = NULL, azimuth = NULL ) generate_moon_disk( datetime, lat, lon, altitude = 0, resolution = 1024, visibility = 50, albedo = 0.5, number_cores = 1, wide_spectrum = FALSE, prague_rgb_correction = TRUE, prague_rgb_correction_strength = 1, prague_rgb_correction_gain = "auto", earthshine = TRUE, earthshine_albedo = 0.19, solar_irradiance_w_m2 = 1300, moon_extinction_kV = 0.172, atmospheric_attenuation = TRUE )generate_sun_disk( datetime, lat, lon, altitude = 0, resolution = 256, visibility = 50, albedo = 0.5, number_cores = 1, wide_spectrum = FALSE, prague_rgb_correction = TRUE, prague_rgb_correction_strength = 1, prague_rgb_correction_gain = "auto", atmospheric_attenuation = TRUE, hosek = FALSE, turbidity = 3, elevation = NULL, azimuth = NULL ) generate_moon_disk( datetime, lat, lon, altitude = 0, resolution = 1024, visibility = 50, albedo = 0.5, number_cores = 1, wide_spectrum = FALSE, prague_rgb_correction = TRUE, prague_rgb_correction_strength = 1, prague_rgb_correction_gain = "auto", earthshine = TRUE, earthshine_albedo = 0.19, solar_irradiance_w_m2 = 1300, moon_extinction_kV = 0.172, atmospheric_attenuation = TRUE )
datetime |
A single |
lat |
Observer latitude in degrees, between -90 and 90. |
lon |
Observer longitude in degrees, between -180 and 180. |
altitude |
Default |
resolution |
Default |
visibility |
Default |
albedo |
Default |
number_cores |
Default |
wide_spectrum |
Default |
prague_rgb_correction |
Default |
prague_rgb_correction_strength |
Default |
prague_rgb_correction_gain |
Default |
atmospheric_attenuation |
Default |
hosek |
Default |
turbidity |
Default |
elevation |
Default |
azimuth |
Default |
earthshine |
Default |
earthshine_albedo |
Default |
solar_irradiance_w_m2 |
Default |
moon_extinction_kV |
Default |
Prague disks require data installed with download_sky_data(). Hosek Sun
disks (hosek = TRUE) need no external data. They include fixed-observer
atmospheric attenuation and support finite values at zenith. The atmosphere is
evaluated for one observer altitude and time when atmospheric_attenuation
is TRUE. With FALSE, solar radiance comes from the model's intrinsic
solar spectrum and lunar radiance uses unattenuated photometry without the
atmospheric tint. Solar texture values are then independent of altitude and
solar elevation; ephemeris placement and lunar phase still use the requested
location and time. Neither mode clips the texture to a geometric horizon.
Pair these images with an atmosphere-only sky and disable the corresponding
rasterized celestial bodies in that sky to avoid counting their light twice.
The disk is inscribed in the image rectangle. For column j, row i, width
w, and height h, pixel centers have coordinates
x = 2 * (j - 0.5) / w - 1 and y = 1 - 2 * (i - 0.5) / h.
Sample only within x^2 + y^2 <= 1. The corresponding ray direction is
normalize(forward + tan(radius) * (x * right + y * up)), where
radius = angular_diameter_deg * pi / 360. Image-up is the projection of
local vertical into the disk plane; image-right points toward increasing
azimuth. At the zenith or nadir, north replaces the vertical reference axis.
There is no image reprojection or implicit rotation in the return value.
The solar model has a fixed angular profile, mapped here to the apparent
ephemeris diameter without changing radiance. Lunar radiance is normalized
over disk solid angle to the existing phase-dependent irradiance, with the
solar spectral RGB distribution. With atmospheric_attenuation = TRUE,
lunar attenuation and Prague tint are evaluated at the disk center. At or
below zero center elevation, their finite horizon values are retained so the
upper limb does not disappear prematurely. This continuation preserves a full
disk texture; it is not a model of below-horizon visibility or horizon
depression at altitude. Geometric horizon clipping is the consumer's
responsibility; sample the full disk and discard directions below the
horizon when appropriate.
To save an EXR without changing radiance, tag image with
rayimage::ray_read_image(image, normalize = FALSE, source_linear = TRUE, assume_colorspace = rayimage::CS_SRGB) and write with clamp = FALSE.
A list containing:
image: a numeric array with dimensions c(height, width, 3) containing
linear sRGB radiance, with no exposure, tone mapping, or alpha channel.
Antialiased lunar coverage is already applied: do not multiply by alpha.
Out-of-gamut solar RGB values may be negative and should be preserved.
azimuth_deg: disk-center azimuth, clockwise from true north, in [0, 360).
elevation_deg: disk-center elevation above the local horizon, in degrees.
angular_diameter_deg: topocentric apparent angular diameter in degrees.
atmospheric_attenuation: whether atmospheric filtering is included.
projection: "rectilinear", using the disk mapping described below.
time = as.POSIXct("2026-01-28 21:00:00", tz = "Pacific/Auckland") moon = generate_moon_disk(time, lat = -36.87593, lon = 174.7647) moon[c("azimuth_deg", "elevation_deg", "angular_diameter_deg")] # Let a renderer evaluate Earth's atmosphere at each interaction instead. intrinsic_moon = generate_moon_disk(time, lat = -36.87593, lon = 174.7647, atmospheric_attenuation = FALSE)time = as.POSIXct("2026-01-28 21:00:00", tz = "Pacific/Auckland") moon = generate_moon_disk(time, lat = -36.87593, lon = 174.7647) moon[c("azimuth_deg", "elevation_deg", "angular_diameter_deg")] # Let a renderer evaluate Earth's atmosphere at each interaction instead. intrinsic_moon = generate_moon_disk(time, lat = -36.87593, lon = 174.7647, atmospheric_attenuation = FALSE)
Resolve the full-altitude Prague dataset and the Sun's topocentric position without loading coefficients or generating an image. This lets rendering libraries evaluate the model natively while using skymodelr's ephemeris and RGB calibration through a public interface.
get_prague_sky_metadata( datetime, lat, lon, altitude = 0, visibility = 50, albedo = 0.5, prague_rgb_correction = TRUE, prague_rgb_correction_strength = 1, prague_rgb_correction_gain = "auto" )get_prague_sky_metadata( datetime, lat, lon, altitude = 0, visibility = 50, albedo = 0.5, prague_rgb_correction = TRUE, prague_rgb_correction_strength = 1, prague_rgb_correction_gain = "auto" )
datetime |
A single |
lat |
Observer latitude in degrees, between -90 and 90. |
lon |
Observer longitude in degrees, between -180 and 180. |
altitude |
Default |
visibility |
Default |
albedo |
Default |
prague_rgb_correction |
Default |
prague_rgb_correction_strength |
Default |
prague_rgb_correction_gain |
Default |
Install the data explicitly with
download_sky_data(sea_level = FALSE). This function never downloads files
or prompts. It supports the visible-spectrum, full-altitude dataset and
returns the actual Sun position even below the Prague model's minimum
elevation of -4.2 degrees. Native consumers should use zero solar radiance
below that limit while retaining transmission for other light sources.
This function does not evaluate radiance, attenuation, or atmospheric
refraction.
A list with filename (the installed full-altitude coefficient file),
elevation_deg, azimuth_deg (clockwise from north),
angular_diameter_deg, rgb_gain (the applied R, G, B gains), and the
reference altitude, visibility, and albedo. No native pointers are
included; the result can be serialized. The coefficient path is local to
this computer and should be resolved again on another machine.
info = get_prague_sky_metadata( as.POSIXct("2026-06-21 20:00:00", tz = "America/New_York"), lat = 40.7, lon = -74 ) info[c("elevation_deg", "azimuth_deg", "rgb_gain")]info = get_prague_sky_metadata( as.POSIXct("2026-06-21 20:00:00", tz = "America/New_York"), lat = 40.7, lon = -74 ) info[c("elevation_deg", "azimuth_deg", "rgb_gain")]
Lists files cached by download_sky_data() under
tools::R_user_dir("skymodelr", "data").
list_sky_data()list_sky_data()
A data frame with columns file, path, size, and modified.
list_sky_data()list_sky_data()