sky_light_image: Image-Based Location and Time Sky Light

In rayrender: Build and Raytrace 3D Scenes

Image-Based Location and Time Sky Light

Description

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.

Usage

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

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.

Value

A ray_infinite_light containing a cached-image sky description.

See Also

sky_light(), infinite_light(), sun_light(), moon_light()

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
)

rayrender documentation built on Sept. 16, 2026, 9:08 a.m.