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 mix of channels is given by a mapping set, where each pair of elements (from, to) in this set defines the map from one input channel to one output channel. The channel indices consider each image as a container of channels. 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 mapping set may give any number of pairs as long as the input and output channel indices exist in the provided images. The following table shows two examples of mix channels usage, one to split one RGB image into three images and another to merge three images into one RGB image.

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

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 to match, that is it does not do chroma upsampling for instance. Further, the algorithm does not do any color or pixel range conversions between input and output formats. For image conversions please refer to Convert Image Format. All input and output images must be allocated before calling the mix channels operation.

The algorithm copies input channels over output channels from any number of input and output images. This is a powerful operation that is capable of doing one or more of the following operations: extract, combine or permute channels. Extract as the first example above, that is extract each channel of a single input image into three different output images. Combine as the second example above, that is combine different channels from three input images into one output image. Permute as both examples using three images for input and output, that is taking any channel from different input images and placing it on any channel of different output images.

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. Run Mix channels algorithm on the input image using the CPU backend. In this example, the mapping is: (2, 1, 0) - > (0, 1, 2); i.e. swap a RGB input image R and B channels, keeping the channel G unaltered, producing a BGR output image.

   with vpi.Backend.CPU:
       output = input.mixchannels([2, 1, 0], [0, 1, 2])

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 mapping with three pairs: (0, 0), (1, 4), (2, 8). In this example, the parameters are set to reflect the output above, that is load input channel 0 and store on output channel 0 (that is channel 0 of output image 0), load input channel 1 and store on output channel 4 (that is channel 1 of output image 1), load input channel 2 and store on output channel 8 (that is channel 2 of output image 2).

          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 with 6 values.

          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

For information on how to use the performance table below, see Algorithm Performance Tables.
Before comparing measurements, consult Comparing Algorithm Elapsed Times.
For further information on how performance was benchmarked, see Performance Benchmark.

Todo:

Add performance table