% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/render_convert_colorspace.R
\name{render_convert_colorspace}
\alias{render_convert_colorspace}
\title{Render Convert Colorspace}
\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{
\item{image}{3-layer RGB/4-layer RGBA array, \code{rayimg}, or filename.}

\item{from_mats}{Default \code{NA}. Source space object; when \code{NA}, pulled from \code{attr(src,"colorspace")}.}

\item{to_mats}{Default \code{CS_ACESCG}. Target space object.}

\item{adapt_white}{Default \code{TRUE}. Apply Bradford CAT from \code{from_white} to \code{to_white}.}

\item{from_white}{Default \code{NA}. Source white (name or XYZ, Y=1). When \code{NA}, uses \code{attr(src,"white_current")}.}

\item{to_white}{Default \code{NA}. Target white (name or XYZ, Y=1). When \code{NA}, uses \code{to_mats$white_xyz}.}

\item{filename}{Default \code{NULL}. Output path.}

\item{preview}{Default \code{FALSE}. If \code{TRUE}, display the image.}
}
\value{
A \code{rayimg} RGBA array tagged with the \strong{target} space.
}
\description{
Convert between two RGB spaces via XYZ, with optional white adaptation. Operates on \strong{linear} RGB.
}
\examples{
\dontshow{if (interactive() || identical(Sys.getenv("IN_PKGDOWN"), "true")) withAutoprint(\{ # examplesIf}
# 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))
\dontshow{\}) # examplesIf}
}
