Image.YUV (image v0.62.0)

View Source

Functions to convert from/to YUV (YCbCr) encoding and BT.601/BT.709 colorspaces and sRGB images.

The following YUV (YCbCr) binary formats are supported:

  • Planar frame types only (not packed frames).

  • 4:4:4, 4:2:2 and 4:2:0 encodings.

  • BT.601 and BT.709 colorspaces.

Performance profiling indicates this implementation is not suitable for real time frame processing of YUV images.

Summary

Types

yuv_colorspace()

YUV colorspace

yuv_encoding()

YUV encoding

yuv_list()

YUV data as a three-element list of binaries

Functions

decode(binary, width, height, atom)

Deocdes a raw YUV binary into [y, u, v] planes where each plane is a binary.

encode(image, atom)

Encodes an image that is in a YUV colorspace to raw YUV data that is a list of the three planes, each a binary.

new_from_binary(binary, width, height, encoding, colorspace \\ :bt601)

Converts raw YUV data into an RGB image.

new_from_file(path, width, height, encoding, colorspace \\ :bt601)

Converts the raw YUV data in a .yuv file into an RGB image.

to_rgb(image, colorspace)

Convert an image in an YUV colorspace and convert it to RGB colorspace.

to_rgb(list, width, height, atom, colorspace)

Takes the [y, u, v] planes and converts them to an RGB image.

to_yuv(image, encoding, colorspace \\ :bt601)

Converts an image to raw YUV data as a binary.

write_to_binary(image, encoding, colorspace \\ :bt601)

Writes an image to a YUV raw binary.

write_to_file(image, path, encoding, colorspace \\ :bt601)

Writes an image to a YUV file as raw YUV data.

Types

yuv_colorspace()

@type yuv_colorspace() :: :bt601 | :bt709

YUV colorspace

yuv_encoding()

@type yuv_encoding() :: :C444 | :C422 | :C420

YUV encoding

yuv_list()

@type yuv_list() :: [binary()]

YUV data as a three-element list of binaries

Functions

decode(binary, width, height, atom)

(since 0.41.0)

Deocdes a raw YUV binary into [y, u, v] planes where each plane is a binary.

Arguments

  • binary is a binary representation of a YUV image.

  • width is the width of the image encoded in yuv.

  • height is the height of the image encoded in yuv.

  • encoding is one of :C444, :C422 or :C420 representing how yuv is encoded.

Returns

  • {:ok, [y, u, v]} or

  • {:error, reason}.

encode(image, atom)

(since 0.41.0) 
@spec encode(image :: Vix.Vips.Image.t(), encoding :: yuv_encoding()) ::
  {:ok, yuv_list()} | {:errpr, Image.error_message()}

Encodes an image that is in a YUV colorspace to raw YUV data that is a list of the three planes, each a binary.

The data is always written in a planar format.

Arguments

Returns

  • {:ok, [y, u, v]} or

  • {:error, Image.error_message()}.

new_from_binary(binary, width, height, encoding, colorspace \\ :bt601)

(since 0.41.0) 
@spec new_from_binary(
  binary :: binary(),
  width :: pos_integer(),
  height :: pos_integer(),
  encoding :: yuv_encoding(),
  colorspace :: yuv_colorspace()
) :: {:ok, Vix.Vips.Image.t()} | {:error, Image.error_message()}

Converts raw YUV data into an RGB image.

The data is assumed, and required to be in:

  • Planar format
  • 8-bit color depth

Arguments

  • binary is raw YUV data as a binary.

  • width is the width of the image encoded in the YUV data.

  • height is the height of the image encoded in the YUV data.

  • encoding is one of :C444, :C422 or :C420.

  • colorspace is one of :bt601 (the default) or :bt709.

Returns

  • {:ok, rgb_image} or

  • {:error, reason}.

new_from_file(path, width, height, encoding, colorspace \\ :bt601)

(since 0.41.0) 
@spec new_from_file(
  path :: Path.t(),
  width :: pos_integer(),
  height :: pos_integer(),
  encoding :: yuv_encoding(),
  colorspace :: yuv_colorspace()
) :: {:ok, Vix.Vips.Image.t()} | {:error, Image.error_message()}

Converts the raw YUV data in a .yuv file into an RGB image.

The data is assumed, and required to be in:

  • Planar format
  • 8-bit color depth

Arguments

  • path is any accessible file system path.

  • width is the width of the image encoded in the YUV data.

  • height is the height of the image encoded in the YUV data.

  • encoding is one of :C444, :C422 or :C420.

  • colorspace is one of :bt601 (the default) or :bt709.

Returns

  • {:ok, rgb_image} or

  • {:error, reason}.

to_rgb(image, colorspace)

(since 0.41.0) 
@spec to_rgb(image :: Vix.Vips.Image.t(), colorspace :: yuv_colorspace()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, Image.error_message()}

Convert an image in an YUV colorspace and convert it to RGB colorspace.

Arguments

to_rgb(list, width, height, atom, colorspace)

(since 0.41.0) 
@spec to_rgb(
  yuv :: yuv_list(),
  width :: pos_integer(),
  height :: pos_integer(),
  encoding :: yuv_encoding(),
  colorspace :: yuv_colorspace()
) :: {:ok, Vix.Vips.Image.t()} | {:error, Image.error_message()}

Takes the [y, u, v] planes and converts them to an RGB image.

Arguments

  • yuv is a list of three binaries representing the Y, U and V planes. Such a list is returned from Image.YUV.to_yuv/3 and from Image.YUV.encode/2.

  • width is the width of the image encoded in yuv.

  • height is the height of the image encoded in yuv.

  • encoding is one of :C444, :C422 or :C420 representing how yuv is encoded.

  • colorspace is one of :bt601 (the default) or :bt709 that represents the colorspace of image before conversion.

Returns

  • {:ok, image} or

  • {:error, reason}.

to_yuv(image, encoding, colorspace \\ :bt601)

(since 0.41.0) 
@spec to_yuv(
  image :: Vix.Vips.Image.t(),
  encoding :: yuv_encoding(),
  colorspace :: yuv_colorspace()
) ::
  {:ok, yuv_list()} | {:error, Image.error_message()}

Converts an image to raw YUV data as a binary.

Arguments

  • image is any t:Vimage.t/0.

  • encoding is one of :C444, :C422 or :C420.

  • colorspace is one of :bt601 (the default) or :bt709.

Returns

  • {:ok, [y, u, v]} or

  • {:error, reason}.

write_to_binary(image, encoding, colorspace \\ :bt601)

(since 0.41.0) 
@spec write_to_binary(
  image :: Vix.Vips.Image.t(),
  encoding :: yuv_encoding(),
  colorspace :: yuv_colorspace()
) :: {:ok, binary()} | {:error, Image.error_message()}

Writes an image to a YUV raw binary.

Arguments

  • image is any t:Vimage.t/0.

  • encoding is one of :C444, :C422 or :C420.

  • colorspace is one of :bt601 (the default) or :bt709.

Returns

  • {:ok, yuv_binary} or

  • {:error, reason}.

write_to_file(image, path, encoding, colorspace \\ :bt601)

(since 0.41.0) 
@spec write_to_file(
  image :: Vix.Vips.Image.t(),
  path :: Path.t(),
  encoding :: yuv_encoding(),
  colorspace :: yuv_colorspace()
) :: :ok | {:error, Image.error_message()}

Writes an image to a YUV file as raw YUV data.

It is recommeneded, but not required, that the path name use a .yuv suffix.

Arguments

  • path is any accessible file system path.

  • encoding is one of :C444, :C422 or :C420.

  • colorspace is one of :bt601 (the default) or :bt709.

Returns

  • :ok or

  • {:error, reason}.