Package {skymodelr}

Convert altitude/azimuth to ENU

Description

Map altitude/azimuth angles (north-referenced) to a unit East-North-Up direction vector.

Usage

altaz_to_enu(alt_rad, azN_rad)

Arguments

Convert B-V color index to blackbody temperature

Description

Convert B-V color index to blackbody temperature

Usage

bv_to_temperature_K(bv)

Arguments

Value

Numeric vector of temperatures in Kelvin.

Sample Prague sky radiance at a chosen wavelength.

Description

Evaluate the Prague spectral sky model at arbitrary spherical directions and return radiance at a user-specified wavelength. Use render_mode = "all" for atmosphere + solar disk, "atmosphere" for atmospheric radiance only, or "sun" for the solar disk only.

Usage

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"
)

Arguments

Value

Numeric vector of radiance values at the requested wavelength(s).

Examples

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)

Sample a direction from the Prague model.

Description

Evaluate the Prague spectral sky model at arbitrary spherical directions without writing an image, returning radiance-only samples.

Usage

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"
)

Arguments

Value

3-column RGB matrix.

Examples

# 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)

Sample sun luminance at the disk center.

Description

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).

Usage

calculate_sun_brightness(
  elevation = 10,
  azimuth = 90,
  albedo = 0.5,
  turbidity = 3,
  altitude = 0,
  visibility = 50,
  hosek = TRUE,
  wide_spectrum = FALSE,
  lambda_nm = NULL
)

Arguments

Value

Numeric scalar of sun luminance (CIE Y, relative scale).

Examples

calculate_sun_brightness(elevation = 45, hosek = TRUE)

Clear cached sky data files

Description

Removes files cached by download_sky_data() under tools::R_user_dir("skymodelr", "data").

Usage

clear_sky_data(files = NULL, ask = interactive())

Arguments

Value

Invisibly, the paths successfully removed.

Examples

clear_sky_data()

Compute effective luminous efficacy for a chosen SPD

Description

Compute effective luminous efficacy for a chosen SPD

Usage

compute_K_eff(
  spd_type = c("D65", "BB5778"),
  wavelength_grid = NULL,
  V_lambda = NULL
)

Arguments

Value

Effective luminous efficacy in lm/W.

Compute a unit RGB vector for a chosen SPD

Description

Compute a unit RGB vector for a chosen SPD

Usage

compute_spd_rgb_unit(spd_type = c("D65", "BB5778"))

Arguments

Value

Numeric vector length 3, normalized so sum equals 1.

Download Prague Sky Model Coefficient Data

Description

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:

Usage

download_sky_data(sea_level = TRUE, wide_spectrum = FALSE)

Arguments

Details

Value

Invisibly, the full path to the data file.

Examples

# 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)

Generate the moon into a lat-long image array patch

Description

Produce a rasterised moon texture aligned for composition into the sky dome. The Earth phase is inferred from the Sun-Moon geometry, and earthshine is implemented as an emissive term scaled relative to solar irradiance.

Usage

generate_moon_image_latlong(
  datetime,
  lat,
  lon,
  elev_m = 0,
  width = 800,
  height = 800,
  earthshine = TRUE,
  earthshine_albedo = 0.19,
  solar_irradiance_w_m2 = 1300,
  moon_extinction_kV = 0.172,
  verbose = FALSE
)

Arguments

Generate the atmosphere with the moon

Description

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.

Usage

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
)

Arguments

Value

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

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

# 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()

Generate a bright-planet image array

Description

Build a planetary luminance map aligned with the sky dome for compositing within generate_sky_latlong().

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

Value

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

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

# 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()

Generate a Hosek-Wilkie sky dome array

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 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
)

Arguments

Value

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

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)


# 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 a location and time-specific sky dome (optionally with stars)

Description

Convenience wrapper around generate_sky() that:

1. Computes the Sun's apparent position for datetime, lat, and lon (via Swiss Ephemeris / swephR).

2. Renders the corresponding sky model.

3. Optionally overlays a star field using generate_stars() or moon with generate_moon_latlong().

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

Details

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.

Value

Either the raw data, or the data is invisibly returned if filename is given. The EXR is written to filename.

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)


# 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 a star-field array aligned with generate_sky()

Description

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.

Usage

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
)

Arguments

Value

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

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

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()

Convert POSIXct timestamps to Julian Date

Description

Transform a POSIXct time value into an astronomical Julian Date (days since noon UTC 1 Jan 4713 BCE).

Usage

jd_utc(time_utc)

Arguments

List cached sky data files

Description

Lists files cached by download_sky_data() under tools::R_user_dir("skymodelr", "data").

Usage

list_sky_data()

Value

A data frame with columns file, path, size, and modified.

Examples

list_sky_data()

Compute luminous efficacy for a blackbody SPD

Description

Compute luminous efficacy for a blackbody SPD

Usage

luminous_efficacy_blackbody(
  temperature_K,
  wavelengths_nm = NULL,
  V_lambda = NULL
)

Arguments

Value

Numeric vector of K_eff values in lm/W.

Convert photometric illuminance to radiometric irradiance

Description

Convert photometric illuminance to radiometric irradiance

Usage

lux_to_radiometric_irradiance(E_v_lux, K_eff)

Arguments

Value

Irradiance in W/m^2.

Moon V-band magnitude from phase angle

Description

Moon V-band magnitude from phase angle

Usage

moon_mag(phase_deg, dist_km = 384400, mean_km = 384400)

Arguments

Value

Apparent V magnitude m.

Moon disk solid angle in steradians

Description

Moon disk solid angle in steradians

Usage

moon_solid_angle_sr(diameter_deg = 0.533)

Arguments

Value

Solid angle in steradians.

Normalize a vector to unit length

Description

Scale a numeric vector so it has unit Euclidean length.

Usage

normalize(v)

Arguments

Compute radiometric star amplitude and RGB unit vector

Description

Compute radiometric star amplitude and RGB unit vector

Usage

star_radiometric_amplitude(mV, bv, wavelengths_nm = NULL, V_lambda = NULL)

Arguments

Value

List with E_v (lux), E_e (W/m^2), K_eff (lm/W), and rgb_unit.

Star catalog used for sky rendering

Description

A data frame of stellar positions and photometric/color information used by generate_stars() to render star fields.

Usage

data(stars)

Format

A data.frame with 9,110 rows and 8 variables:

bsc_number

Numeric identifier from the source catalog.

ra_rad

Right ascension in radians.

dec_rad

Declination in radians.

v_mag

Apparent visual magnitude (V band).

spec

Spectral type string.

r

Relative red channel weight derived from spectral type.

g

Relative green channel weight derived from spectral type.

b

Relative blue channel weight derived from spectral type.

Source

Derived from the Bright Star Catalogue, 5th Revised Edition (BSC5), also known as the Yale Bright Star Catalogue. The source catalogue is commonly identified as Hoffleit, D. and Warren, W. H. Jr. (1991), "The Bright Star Catalogue, 5th Revised Ed.", Yale University Observatory, and is distributed as machine-readable catalogue V/50 by the Centre de Donnees astronomiques de Strasbourg (CDS): https://cdsarc.cds.unistra.fr/viz-bin/cat/V/50.

Compute topocentric moon/sun directions

Description

Query Swiss Ephemeris for topocentric sun and moon direction vectors and magnitudes for a given observer location.

Usage

swe_dirs_topo_moon_sun(
  datetime,
  lat,
  lon,
  elev_m = 0,
  moon_extinction_kV = 0.172
)

Arguments

Compute bright-planet positions via Swiss Ephemeris

Description

Produce a data frame of planetary apparent positions and magnitudes for the observer.

Usage

swe_dirs_topo_planets_df(datetime, lat, lon, elev_m = 0)

Arguments

Compute sun/moon positions via Swiss Ephemeris

Description

Produce a data frame of apparent positions and magnitudes for the observer.

Usage

swe_dirs_topo_sunmoon_df(datetime, lat, lon, elev_m = 0)

Arguments

Convert Swiss ephemeris data to a starfield frame

Description

Build a data frame compatible with make_starfield_rcpp() from Swiss Ephemeris results.

Usage

sweph_info_to_stars_df(sweph_info)

Arguments

Convert V magnitude to illuminance in lux

Description

Convert V magnitude to illuminance in lux

Usage

vmag_to_ev_lux(mV, zero_point = 1)

Arguments

Value

Numeric vector of photometric illuminance in lux.