render_convert_colorspace: Render Convert Colorspace

In rayimage: Image Processing for Simulated Cameras

Render Convert Colorspace

Description

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

Usage

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

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

rayimage documentation built on June 12, 2026, 5:06 p.m.