Render Convert Colorspace

Convert between two RGB spaces via XYZ, with optional white adaptation.

render_convert_colorspace(
  image,
  from_mats = NA,
  to_mats = CS_ACESCG,
  adapt_white = TRUE,
  from_white = NA,
  to_white = NA,
  filename = NULL,
  preview = FALSE
)

Arguments

image

3-layer RGB/4-layer RGBA array, rayimg, or filename.

from_mats

Default NA. Source space object; when NA, pulled from attr(src,"colorspace").

to_mats

Default CS_ACESCG. Target space object.

adapt_white

Default TRUE. Apply Bradford CAT from from_white to to_white.

from_white

Default NA. Source white (name or XYZ, Y=1). When NA, uses attr(src,"white_current").

to_white

Default NA. Target white (name or XYZ, Y=1). When NA, uses to_mats$white_xyz.

filename

Default NULL. Output path.

preview

Default FALSE. If TRUE, display the image.

Value

A rayimg RGBA array tagged with the target space.

Examples

if (run_documentation()) {
# Read photo, convert to ACEScg with CAT (scene)
  photo = ray_read_image(sunset_image, normalize = FALSE)
  photo_aces = render_convert_colorspace(
    photo,
    to_mats = CS_ACESCG,
    adapt_white = TRUE
  )
  tmp_txt = tempfile(fileext = ".png")
  render_text_image(
    "Sunset",
    size = 60,
    filename = tmp_txt,
    color = "#c300ffff",
    background_alpha = 0
  )
  # Read logo (display-referred), convert primaries only (no CAT)
  logo = ray_read_image(tmp_txt, normalize = FALSE) # sRGB/D65
  logo_aces = render_convert_colorspace(
    logo,
    to_mats = CS_ACESCG,
    adapt_white = FALSE
  )

  # Composite in ACEScg, then display (plot_image converts to sRGB/D65 + OETF)
  # Here, we also turn overlay conversion in [render_image_overlay()] off,
 # to show what happens when you don't account for the colorspace difference.
 # By default [render_image_overlay()] will do this for you.
  comp1 = render_image_overlay(
    photo_aces,
    logo_aces,
    convert_overlay_colorspace = FALSE
  )
  comp2 = render_image_overlay(
    photo_aces,
    logo,
    convert_overlay_colorspace = FALSE
  )
  #Note the color differences, which arise from the mismatched colorspace on the right.
   plot_image_grid(list(comp1, comp2), dim = c(1, 2))
}