VPI - Vision Programming Interface

3.2 Release

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:
  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.
      Declares functions that implement support for Mix Channels.
    2. Define the input image, i.e. one RGB8 image.
      VPIImage input = /*...*/;
      struct VPIImageImpl * VPIImage
      A handle to an image.
      Definition: Types.h:256
    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]);
      }
      #define VPI_IMAGE_FORMAT_RGB8
      Single plane with interleaved RGB 8-bit channel.
      Definition: ImageFormat.h:321
      VPIStatus vpiImageCreate(int32_t width, int32_t height, VPIImageFormat fmt, uint64_t flags, VPIImage *img)
      Create an empty image instance with the specified flags.
      VPIStatus vpiImageGetSize(VPIImage img, int32_t *width, int32_t *height)
      Get the image dimensions in pixels.
    4. Create the stream where the algorithm will be submitted for execution.
      VPIStream stream;
      vpiStreamCreate(0, &stream);
      struct VPIStreamImpl * VPIStream
      A handle to a stream.
      Definition: Types.h:250
      VPIStatus vpiStreamCreate(uint64_t flags, VPIStream *stream)
      Create a stream instance.
  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);
      VPIStatus vpiSubmitMixChannels(VPIStream stream, uint64_t backend, VPIImage *inputs, int numInputs, VPIImage *outputs, int numOutputs, const int *inMapping, const int *outMapping, int numMapping)
      Submits a Mix Channels operation to the stream.
      @ VPI_BACKEND_CPU
      CPU backend.
      Definition: Types.h:92
    3. Optionally, wait until the processing is done.
      vpiStreamSync(stream);
      VPIStatus vpiStreamSync(VPIStream stream)
      Blocks the calling thread until all submitted commands in this stream queue are done (queue is empty)...
  3. Cleanup phase
    1. Free resources held by the stream, the input image and the three output images.
      for (int i = 0; i < 3; ++i)
      {
      vpiImageDestroy(outputs[i]);
      }
      void vpiImageDestroy(VPIImage img)
      Destroy an image instance.
      void vpiStreamDestroy(VPIStream stream)
      Destroy a stream instance and deallocate all HW resources.

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.

 -