Mix Channels

Overview

Mix channels is a copy operation from a set of input channels to a set of output channels. The set of inputs and outputs may be given by any number of input and output images, where each image may have one or more channels.

The channel mapping from input to output is given by two arrays, one with the indices of the input channels, and the another with the corresponding channel index in the output.

The channel indices are enumerated starting from zero and increasing monotonically across all channels of all images provided in the array. For example, given an array of 3 RGB images, index 5 corresponds to the B channel of the second image.

The following table shows two examples of mix channels usage. The left one extracts each channel of an RGB image into three RGB images, in the correspondent red, green and blue channels. Remaining channels are unchanged.

Input	Parameters	Output
	In: [RGB8] Out: [RGB8, RGB8, RGB8] MappingIn: [0, 1, 2] MappingOut: [0, 4, 8]

Implementation

The algorithm is implemented as a pixel-wise copy function that reads in each input channel and writes it to the corresponding output channel. The algorithm expects the sizes of the input and output image planes to match, that is, it will not do chroma up/downsampling for instance. Furthermore, the algorithm will not do any color or pixel range conversions between input and output formats. It'll do, however, conversions between integer and floating-point values. Underflows and overflows are handled as per C language rules for such casts. For image format conversion (including proper color conversion), refer to Convert Image Format.

All input and output images must be allocated before calling the mix channels operation.

The following figure shows some examples of channel mixing possible. Each blue box represents one channel, and grouped boxes represent an image. Numbers inside the channel box represent the channel index with respect to the image, and numbers outside the boxes represent the corresponding channel index to be used in the channel mapping array. Note that the same input channel can be copied to several output channels, and output channels that aren't written to keep their original content.

C API functions

For list of limitations, constraints and backends that implements the algorithm, consult reference documentation of the following functions:

Function	Description
vpiSubmitMixChannels	Submits a Mix Channels operation to the stream.

Usage

Language: C/C++ Python

1. Import VPI module

   import vpi

2. Create the output image list from an input image, all images have same dimensions and format as input. It's assumed that input's format is vpi.Format.RGB8.

   outputs = [ vpi.Image(input.size, vpi.Format.RGB8),
               vpi.Image(input.size, vpi.Format.RGB8),
               vpi.Image(input.size, vpi.Format.RGB8) ]

3. Runs the mix channels algorithm. Each one of input channels (RGB) are mapped to its corresponding channels in the 3 output images, i.e., first image R channel receives input's R channel, second image G channel receives input's G channel, etc. The other output channels aren't touched, and keep their original content, in this case, all zeros. The result is 3 color images showing the red, green and blue channels of the input image.

   with vpi.Backend.CPU:
       vpi.mixchannels([input], outputs, [0, 1, 2], [0, 4, 8])

1. Initialization phase
   1. Include the header that defines the Mix Channels algorithm function.

      #include <vpi/algo/MixChannels.h>

   2. Define the input image, i.e. one RGB8 image.

          VPIImage input = /*...*/;

   3. Create the output images, i.e. three RGB8 images with the same size as the input image.

          int32_t w, h;
          vpiImageGetSize(input, &w, &h);
       
          VPIImage outputs[3];
          for (int i = 0; i < 3; ++i)
          {
              vpiImageCreate(w, h, VPI_IMAGE_FORMAT_RGB8, 0, &outputs[i]);
          }

   4. Create the stream where the algorithm will be submitted for execution.

          VPIStream stream;
          vpiStreamCreate(0, &stream);

2. Processing phase
   1. Initialize the input and output mapping arrays so that each one of input channels (RGB) are mapped to its corresponding channels in the 3 output images, i.e., first image R channel receives input's R channel, second image G channel receives input's G channel, etc. The other output channels aren't touched, and keep their original content, in this case, all zeros. The result is 3 color images showing the red, green and blue channels of the input image.

          int mappingIn[3]  = {0, 1, 2};
          int mappingOut[3] = {0, 4, 8};

   2. Submit the algorithm and its parameters to the stream. It'll be executed by the CPU backend. In this example, there is one input image, three output images and a mapping for 3 channels.

          vpiSubmitMixChannels(stream, VPI_BACKEND_CPU, &input, 1, outputs, 3, mappingIn, mappingOut, 3);

   3. Optionally, wait until the processing is done.

          vpiStreamSync(stream);

3. Cleanup phase
   1. Free resources held by the stream, the input image and the three output images.

          vpiStreamDestroy(stream);
          vpiImageDestroy(input);
          for (int i = 0; i < 3; ++i)
          {
              vpiImageDestroy(outputs[i]);
          }

For more information, see Mix Channels in the "C API Reference" section of VPI - Vision Programming Interface.

Performance

Performance benchmarks will be added at a later time.