Image-Based Location and Time Sky Light

Source: R/sky_light_image.R

Generate a cached sky EXR with skymodelr::generate_sky_latlong() and use it as an infinite light. Add it to a scene with add_infinite_light(). The image represents one observer and illuminates every scene position with the same sky. Use sky_light() for altitude-dependent lighting and finite-distance haze. Both constructors include Sun and Moon by default, controlled with sun and moon, and support optional stars and planets.

sky_light_image(
  lat,
  long,
  datetime,
  intensity = 1,
  rotation = 0,
  name = "sky",
  altitude = 0,
  visibility = 131.8,
  albedo = 0.5,
  resolution = 2048,
  hosek = TRUE,
  render_mode = "all",
  turbidity = 3,
  wide_spectrum = FALSE,
  below_horizon = TRUE,
  prague_rgb_correction = TRUE,
  prague_rgb_correction_strength = 1,
  prague_rgb_correction_gain = "auto",
  stars = FALSE,
  star_width = 1,
  stars_exposure = 0,
  planets = FALSE,
  moon = TRUE,
  moon_atmosphere = FALSE,
  moon_hosek = TRUE,
  exr_adopted_white = "D60",
  exr_metadata = TRUE,
  number_cores = 1,
  verbose = FALSE,
  sun = TRUE,
  environment_light_bake_white = FALSE,
  environment_light_bake_white_target = "D65",
  ...
)

Arguments

lat

Latitude in degrees, between -90 and 90.

long

Longitude in degrees, between -180 and 180.

datetime

A single POSIXct date and time. Specify its time zone when constructing it with as.POSIXct().

intensity

Default 1. Nonnegative multiplier for this light's radiance.

rotation

Default 0. Additional rotation in degrees around the world Y axis, using the same convention as infinite_light().

name

Default "sky". Unique light name within the scene.

altitude

Default 0. Observer altitude in meters above sea level for the entire sky image. Prague supports 0–15000 m with its full-altitude data.

visibility

Default 131.8. Prague meteorological visibility in kilometers, from 20 to 131.8. Smaller values produce stronger haze.

albedo

Default 0.5. Uniform ground reflectance for the sky model, between 0 and 1. Local surface materials are specified separately.

resolution

Default 2048. Height of the cached image in pixels; its width is twice the height.

hosek

Default TRUE. Generate a Hosek sky. Set FALSE to use Prague.

render_mode

Default "all". Select sky and Sun ("all"), sky without the solar disk ("atmosphere"), or the solar disk alone ("sun"). Moon, star, and planet switches are independent of this selection.

turbidity

Default 3. Hosek turbidity, from 1.7 to 10.

wide_spectrum

Default FALSE. Use Prague's 55-channel sea-level data.

below_horizon

Default TRUE. Include atmospheric radiance below the horizon.

prague_rgb_correction

Default TRUE. Apply skymodelr's Prague RGB tint correction.

prague_rgb_correction_strength

Default 1. Strength of the Prague RGB tint correction. Must be finite and nonnegative: 0 disables correction, and 1 applies the full calibrated correction.

prague_rgb_correction_gain

Default "auto". Calibrated Prague RGB gains, or a numeric vector of three finite, positive linear RGB multipliers.

stars

Default FALSE. Composite stars into the sky image.

star_width

Default 1. Stellar point-spread size, passed to skymodelr::generate_stars().

stars_exposure

Default 0. Artistic exposure adjustment for stars, in stops.

planets

Default FALSE. Composite bright planets into the sky image.

moon

Default TRUE. Composite a Moon image into the sky. Set FALSE when adding a separate moon_light().

moon_atmosphere

Default FALSE. Include atmospheric scattering of moonlight.

moon_hosek

Default TRUE. Use Hosek for moonlight scattering. Set FALSE to use Prague.

exr_adopted_white

Default "D60". Adopted white for EXR metadata: "D60", "D65", or numeric XYZ with Y = 1. Does not change image pixels.

exr_metadata

Default TRUE. Attach skymodelr color metadata to the EXR.

number_cores

Default 1. CPU threads used to generate the cached image.

verbose

Default FALSE. Print sky-generation progress information.

sun

Default TRUE. Include the solar disk when selected by render_mode. Set FALSE to omit it from the image.

environment_light_bake_white

Default FALSE. Bake chromatic adaptation from the generated EXR's white_current metadata into its RGB pixels before using it for lighting. Requires exr_metadata = TRUE. The adapted image is cached and reused for still images and animations.

environment_light_bake_white_target

Default "D65". Target white point when baking: "D50", "D55", "D60", "D65", "D75", "E", or a finite numeric XYZ vector with positive Y (normalized to Y = 1). Unlike exr_adopted_white, this changes the image pixels when baking is enabled.

...

Additional named arguments forwarded by skymodelr::generate_sky_latlong() to its star, planet, and Moon generators. Pass settings directly; location, datetime, and the cached filename are managed by this light. Native atmospheric controls belong to sky_light().

Value

A ray_infinite_light containing a cached-image sky description.

Details

Image generation happens before rendering and is cached for the R session. Changing only intensity, rotation, or name reuses the image. Changing the baked target white point reuses the generated sky and caches a separate adapted image. White-balance controls belong to this light; pass the light to add_infinite_light() before calling render_scene() or render_animation(). Install any required Prague data with skymodelr::download_sky_data() first; rendering does not download datasets.

With zero rotation, north is world +Z and east is world -X. Date, time, and observer altitude remain fixed throughout the image. This light supports the same integrators as infinite_light() and adds no finite atmospheric haze. Use render_scene()'s iso to adjust exposure.

For a separately sampled Sun, set render_mode = "atmosphere" and add sun_light() with matching location, time, and atmospheric settings. This avoids relying on the environment image to resolve the small solar disk.

Examples

time = as.POSIXct("2026-06-21 18:00:00", tz = "America/New_York")
scene = sphere(material = diffuse("white")) |>
  add_object(generate_ground())

scene |>
  add_infinite_light(sky_light_image(40.7, -74, time)) |>
  render_scene(
    lookfrom = c(0, 1, 10),
    lookat = c(0, 0, 0),
    width = 600,
    height = 300,
    samples = 32,
    iso = 3
  )


# A Prague image sky with an independently sampled solar disk.
# Install Prague data with skymodelr::download_sky_data() before rendering.
scene |>
  add_infinite_light(sky_light_image(
    40.7,
    -74,
    time,
    hosek = FALSE,
    render_mode = "atmosphere",
    altitude = 0,
    visibility = 50,
    albedo = 0.3
  )) |>
  add_infinite_light(sun_light(
    40.7,
    -74,
    time,
    sky_args = list(altitude = 0, visibility = 50, albedo = 0.3)
  )) |>
render_scene(
  lookfrom = c(0, 1, 10),
  lookat = c(0, 0, 0),
  aperture = 0,
  width = 600,
  height = 300,
  samples = 32,
  iso = 3
)
#> Error: The Prague sky model coefficient file 'SkyModelDatasetGround.dat' is not installed. Run download_sky_data(sea_level = TRUE, wide_spectrum = FALSE) explicitly to download it.