GraphicsMagick

- Home
- Project
- Download
- Install
- Source
- News
- Utilities
- Programming
- Reference

# channel

## Image channel functions

Contents

- ChannelImage
- ExportImageChannel
- GetImageChannelDepth
- ImportImageChannel
- ImportImageChannelsMasked
- SetImageChannelDepth

# ChannelImage

## Synopsis

    unsigned int ChannelImage( Image *image, const ChannelType channel );

## Description

Transform an image so that the resulting image is a grayscale image based on a specified image channel. The resulting image is returned in the RGB colorspace. This function does not force or assume an input image colorspace so it may be used to extract channels from images in colorspaces other than RGB or CMYK. For example, if the image is currently transformed to the HWB colorspace, the 'B' channel may be extracted by specifying RedChannel as the ChannelType argument.

The format of the ChannelImage method is:

    unsigned int ChannelImage( Image *image, const ChannelType channel );

A description of each parameter follows:

image:
  The image.
channel:
  Identify which channel to extract: Red, Cyan, Green, Magenta, Blue, Yellow, or Opacity.

# ExportImageChannel

## Synopsis

    Image *ExportImageChannel( const Image *image, const ChannelType channel,
                               ExceptionInfo *exception );

## Description

ExportImageChannel() exports a specified image channel as a new image.

The format of the ExportImageChannel method is:

    Image *ExportImageChannel( const Image *image, const ChannelType channel,
                               ExceptionInfo *exception );

image:
  The source image.
channel:
  The image channel to export
exception:
  Return any errors or warnings in this structure.

# GetImageChannelDepth

## Synopsis

    unsigned long GetImageChannelDepth( const Image *image, const ChannelType channel,
                                        ExceptionInfo *exception );

## Description

GetImageChannelDepth() returns the minimum bit depth required to store the specified image channel without actual loss of color resolution. Pixel components are stored in a Quantum, which is 8, 16, or 32 bits depending on the QuantumDepth value set when the software is compiled. GetImageChannelDepth() returns the smallest modulus storage size which supports the scale of the pixel within the range (i.e. no information is lost). As an example, the value one is returned for a bilevel channel since only one bit of resolution is required to represent a bilevel channel.

The format of the GetImageChannelDepth method is:

    unsigned long GetImageChannelDepth( const Image *image, const ChannelType channel,
                                        ExceptionInfo *exception );

image:
  The image.
channel:
  Channel to test.
exception:
  Return any errors or warnings in this structure.

# ImportImageChannel

## Synopsis

    MagickPassFail ImportImageChannel( const Image *source_image, Image *update_image,
                                       const ChannelType channel );

## Description

ImportImageChannel() imports an image into the specified image channel.

The format of the ImportImageChannel method is:

    MagickPassFail ImportImageChannel( const Image *source_image, Image *update_image,
                                       const ChannelType channel );

source_image:
  The image to use as the replacement image channel.
update_image:
  The image to import the channel into.
channel:
  The image channel to import

# ImportImageChannelsMasked

## Synopsis

    MagickPassFail ImportImageChannelsMasked( const Image *source_image,
                                              Image *update_image,
                                              const ChannelType channels );

## Description

ImportImageChannelsMasked() imports all the channels from a source image to an update image, except for the channels specified.

The format of the ImportImageChannelsMasked method is:

    MagickPassFail ImportImageChannelsMasked( const Image *source_image,
                                              Image *update_image,
                                              const ChannelType channels );

source_image:
  The image from which to extract the replacement channels.
update_image:
  The image to import the channels into.
channel:
  The image channel to import

# SetImageChannelDepth

## Synopsis

    MagickPassFail SetImageChannelDepth( Image *image, const ChannelType channel,
                                         const unsigned int depth );

## Description

SetImageChannelDepth() translates the pixel quantums in the specified channel so that if they are later divided to fit within the specified bit depth, that no additional information is lost (i.e. no remainder resulting from the division). Note that any subsequent image processing is likely to increase the effective depth of the image channels. A non-zero value is returned if the operation is successful. Check the exception member of image to determine the cause for any failure.

The format of the SetImageChannelDepth method is:

    MagickPassFail SetImageChannelDepth( Image *image, const ChannelType channel,
                                         const unsigned int depth );

image:
  The image to update.
channel:
  Channel to modify.
depth:
  Desired channel depth (range 1 to QuantumDepth)