A pixel is comprised of one or more color values, or channels (e.g. red pixel channel).

Prior versions of ImageMagick (4-6), support 4 to 5 pixel channels (RGBA or CMYKA). The first 4 channels are accessed with the PixelPacket data structure. The structure includes 4 members of type Quantum (typically 16-bits) of red, green, blue, and opacity. The black channel or colormap indexes are supported by a separate method and structure, IndexPacket. As an example, here is a code snippet from ImageMagick version 6 that negates the color components (but not the alpha component) of the image pixels:

for (y=0; y < (ssize_t) image->rows; y++)
{
  IndexPacket
    *indexes;

  PixelPacket
    *q;

  q=GetCacheViewAuthenticPixels(image_view,0,y,image->columns,1,exception);
  if (q == (PixelPacket *) NULL)
    {
      status=MagickFalse;
      continue;
    }
  indexes=GetCacheViewAuthenticIndexQueue(image_view);
  for (x=0; x < (ssize_t) image->columns; x++)
  {
    if ((channel & RedChannel) != 0)
      q->red=(Quantum) QuantumRange-q->red;
    if ((channel & GreenChannel) != 0)
      q->green=(Quantum) QuantumRange-q->green;
    if ((channel & BlueChannel) != 0)
      q->blue=(Quantum) QuantumRange-q->blue;
    if (((channel & IndexChannel) != 0) &&
        (image->colorspace == CMYKColorspace))
      indexes[x]=(IndexPacket) QuantumRange-indexes[x];
    q++;
  }
  if (SyncCacheViewAuthenticPixels(image_view,exception) == MagickFalse)
    status=MagickFalse;
}

ImageMagick version 7 supports any number of channels from 1 to 64 (and beyond) and simplifies access with a single method that returns an array of pixel channels of type Quantum. Source code that compiles against prior versions of ImageMagick requires refactoring to work with ImageMagick version 7. We illustrate with an example. Let's naively refactor the version 6 code snippet from above so it works with the ImageMagick version 7 API:

for (y=0; y < (ssize_t) image->rows; y++)
{
  Quantum
    *q;

  q=GetCacheViewAuthenticPixels(image_view,0,y,image->columns,1,exception);
  if (q == (Quantum *) NULL)
    {
      status=MagickFalse;
      continue;
    }
  for (x=0; x < (ssize_t) image->columns; x++)
  {
    if ((GetPixelRedTraits(image) & UpdatePixelTrait) != 0)
      SetPixelRed(image,QuantumRange-GetPixelRed(image,q),q);
    if ((GetPixelGreenTraits(image) & UpdatePixelTrait) != 0)
      SetPixelGreen(image,QuantumRange-GetPixelGreen(image,q),q);
    if ((GetPixelBlueTraits(image) & UpdatePixelTrait) != 0)
      SetPixelBlue(image,QuantumRange-GetPixelBlue(image,q),q);
    if ((GetPixelBlackTraits(image) & UpdatePixelTrait) != 0)
      SetPixelBlack(image,QuantumRange-GetPixelBlack(image,q),q);
    if ((GetPixelAlphaTraits(image) & UpdatePixelTrait) != 0)
      SetPixelAlpha(image,QuantumRange-GetPixelAlpha(image,q),q);
    q+=GetPixelChannels(image);
  }
  if (SyncCacheViewAuthenticPixels(image_view,exception) == MagickFalse)
    status=MagickFalse;
}

Let's do that again but take full advantage of the new variable pixel channel support:

for (y=0; y < (ssize_t) image->rows; y++)

{
  Quantum
    *q;

  q=GetCacheViewAuthenticPixels(image_view,0,y,image->columns,1,exception);
  if (q == (Quantum *) NULL)
    {
      status=MagickFalse;
      continue;
    }
  for (x = 0; x < (ssize_t) image->columns; x++)
  {
    ssize_t
      i;

    if (GetPixelWriteMask(image,q) <= (QuantumRange/2))
      {
        q+=GetPixelChannels(image);
        continue;
      }
    for (i=0; i < (ssize_t) GetPixelChannels(image); i++)
    {
      PixelChannel channel = GetPixelChannelChannel(image,i);
      PixelTrait traits = GetPixelChannelTraits(image,channel);
      if ((traits & UpdatePixelTrait) == 0)
        continue;
      q[i]=QuantumRange-q[i];
    }
    q+=GetPixelChannels(image);
  }
  if (SyncCacheViewAuthenticPixels(image_view,exception) == MagickFalse)
    status=MagickFalse;
}

Note, how we use GetPixelChannels() to advance to the next set of pixel channels.

The colormap indexes and black pixel channel (for the CMYK colorspace) are no longer stored in the index channel, previously accessed with GetAuthenticIndexQueue() and GetCacheViewAuthenticIndexQueue(). Instead they are now a first class pixel channel and accessed as a member of the pixel array (e.g. pixel[4]) or with the convenience pixel accessor methods GetPixelIndex(), SetPixelIndex(), GetPixelBlack(), and SetPixelBlack().

As a consequence of using an array structure for variable pixel channels, auto-vectorization compilers have additional opportunities to speed up pixel loops.

The `sync` channel in IMv6 was really a flag instead of a channel. In IMv7, we instead use a flag: -define compose:sync=false.

Pixel Accessors

You can access pixel channel as array elements (e.g. pixel[1]) or use convenience accessors to get or set pixel channels:

You can find these accessors defined in the header file, MagickCore/pixel-accessor.h

Pixel Traits

Each pixel channel includes one or more of these traits:

We provide these methods to set and get pixel traits:

For convenience you can set the active trait for a set of pixel channels with a channel mask and this method:

Previously MagickCore methods had channel analogs, for example, NegateImage() and NegateImageChannels(). The channel analog methods are no longer necessary because the pixel channel traits specify whether to act on a particular pixel channel or whether to blend with the alpha mask. For example, instead of

we use:

Pixel User Channels

In version 7, we introduce pixel user channels. Traditionally we utilize 4 channels, red, green, blue, and alpha. For CMYK we also have a black channel. User channels are designed to contain whatever additional channel information that makes sense for your application. Some examples include extra channels in TIFF or PSD images or perhaps you require a channel with infrared information for the pixel. You can associate traits with the user channels so that when they are acted upon by an image processing algorithm (e.g. blur) the pixels are copied, acted upon by the algorithm, or even blended with the alpha channel if that makes sense.

Pixel Metacontent

In version 7, we introduce pixel metacontent. Metacontent is content about content. So rather than being the content itself, it's something that describes or is associated with the content. Here the content is a pixel. The pixel metacontent is for your exclusive use (internally the data is just copied, it is not modified) and is accessed with these MagickCore API methods:

Command Changes

Behavioral Changes

New Options