threshold.c

Go to the documentation of this file.

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
%       TTTTT  H   H  RRRR   EEEEE  SSSSS  H   H   OOO   L      DDDD          %
%         T    H   H  R   R  E      SS     H   H  O   O  L      D   D         %
%         T    HHHHH  RRRR   EEE     SSS   HHHHH  O   O  L      D   D         %
%         T    H   H  R R    E         SS  H   H  O   O  L      D   D         %
%         T    H   H  R  R   EEEEE  SSSSS  H   H   OOO   LLLLL  DDDD          %
%                                                                             %
%                                                                             %
%                      MagickCore Image Threshold Methods                     %
%                                                                             %
%                               Software Design                               %
%                                 John Cristy                                 %
%                                 October 1996                                %
%                                                                             %
%                                                                             %
%  Copyright 1999-2008 ImageMagick Studio LLC, a non-profit organization      %
%  dedicated to making software imaging solutions freely available.           %
%                                                                             %
%  You may not use this file except in compliance with the License.  You may  %
%  obtain a copy of the License at                                            %
%                                                                             %
%    http://www.imagemagick.org/script/license.php                            %
%                                                                             %
%  Unless required by applicable law or agreed to in writing, software        %
%  distributed under the License is distributed on an "AS IS" BASIS,          %
%  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.   %
%  See the License for the specific language governing permissions and        %
%  limitations under the License.                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%
%
*/

/*
  Include declarations.
*/
#include "magick/studio.h"
#include "magick/property.h"
#include "magick/blob.h"
#include "magick/cache-view.h"
#include "magick/color.h"
#include "magick/color-private.h"
#include "magick/colorspace.h"
#include "magick/configure.h"
#include "magick/constitute.h"
#include "magick/decorate.h"
#include "magick/draw.h"
#include "magick/enhance.h"
#include "magick/exception.h"
#include "magick/exception-private.h"
#include "magick/effect.h"
#include "magick/fx.h"
#include "magick/gem.h"
#include "magick/geometry.h"
#include "magick/image-private.h"
#include "magick/list.h"
#include "magick/log.h"
#include "magick/memory_.h"
#include "magick/monitor.h"
#include "magick/monitor-private.h"
#include "magick/montage.h"
#include "magick/pixel-private.h"
#include "magick/quantize.h"
#include "magick/quantum.h"
#include "magick/random_.h"
#include "magick/resize.h"
#include "magick/resource_.h"
#include "magick/segment.h"
#include "magick/shear.h"
#include "magick/signature-private.h"
#include "magick/string_.h"
#include "magick/transform.h"
#include "magick/threshold.h"
#include "magick/option.h"
#include "magick/xml-tree.h"

/*
  Define declarations.
*/
#define ThresholdsFilename  "thresholds.xml"

/*
  Typedef declarations.
*/
struct _ThresholdMap
{
  char
    *map_id,
    *description;

  unsigned long
    width,
    height;

  long
    divisor,
    *levels;
};

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
%     A d a p t i v e T h r e s h o l d I m a g e                             %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  AdaptiveThresholdImage() selects an individual threshold for each pixel
%  based on the range of intensity values in its local neighborhood.  This
%  allows for thresholding of an image whose global intensity histogram
%  doesn't contain distinctive peaks.
%
%  The format of the AdaptiveThresholdImage method is:
%
%      Image *AdaptiveThresholdImage(const Image *image,
%        const unsigned long width,const unsigned long height,
%        const long offset,ExceptionInfo *exception)
%
%  A description of each parameter follows:
%
%    o image: the image.
%
%    o width: the width of the local neighborhood.
%
%    o height: the height of the local neighborhood.
%
%    o offset: the mean offset.
%
%    o exception: return any errors or warnings in this structure.
%
*/
MagickExport Image *AdaptiveThresholdImage(const Image *image,
  const unsigned long width,const unsigned long height,const long offset,
  ExceptionInfo *exception)
{
#define ThresholdImageTag  "Threshold/Image"

  Image
    *threshold_image;

  long
    progress,
    y;

  MagickBooleanType
    status;

  MagickPixelPacket
    zero;

  MagickRealType
    number_pixels;

  ViewInfo
    *image_view,
    *threshold_view;

  assert(image != (const Image *) NULL);
  assert(image->signature == MagickSignature);
  if (image->debug != MagickFalse)
    (void) LogMagickEvent(TraceEvent,GetMagickModule(),"%s",image->filename);
  assert(exception != (ExceptionInfo *) NULL);
  assert(exception->signature == MagickSignature);
  if ((image->columns < width) || (image->rows < height))
    ThrowImageException(OptionError,"ImageSmallerThanRadius");
  threshold_image=CloneImage(image,0,0,MagickTrue,exception);
  if (threshold_image == (Image *) NULL)
    return((Image *) NULL);
  if (SetImageStorageClass(threshold_image,DirectClass) == MagickFalse)
    {
      InheritException(exception,&threshold_image->exception);
      threshold_image=DestroyImage(threshold_image);
      return((Image *) NULL);
    }
  /*
    Local adaptive threshold.
  */
  status=MagickTrue;
  progress=0;
  GetMagickPixelPacket(image,&zero);
  number_pixels=(MagickRealType) width*height;
  image_view=AcquireCacheView(image);
  threshold_view=AcquireCacheView(threshold_image);
#if defined(MAGICKCORE_OPENMP_SUPPORT)
  #pragma omp parallel for schedule(dynamic,8) shared(progress,status)
#endif
  for (y=0; y < (long) image->rows; y++)
  {
    MagickBooleanType
      sync;

    register const IndexPacket
      *indexes;

    register const PixelPacket
      *p;

    register IndexPacket
      *threshold_indexes;

    register long
      x;

    register PixelPacket
      *q;

    if (status == MagickFalse)
      continue;
    p=GetCacheViewVirtualPixels(image_view,-((long) width/2L),y-height/2L,
      image->columns+width,height,exception);
    q=GetCacheViewAuthenticPixels(threshold_view,0,y,threshold_image->columns,1,
      exception);
    if ((p == (const PixelPacket *) NULL) || (q == (PixelPacket *) NULL))
      {
        status=MagickFalse;
        continue;
      }
    indexes=GetCacheViewVirtualIndexQueue(image_view);
    threshold_indexes=GetCacheViewAuthenticIndexQueue(threshold_view);
    for (x=0; x < (long) image->columns; x++)
    {
      long
        v;

      MagickPixelPacket
        mean,
        pixel;

      register const PixelPacket
        *r;

      register long
        u;

      pixel=zero;
      mean=zero;
      r=p;
      for (v=0; v < (long) height; v++)
      {
        for (u=0; u < (long) width; u++)
        {
          pixel.red+=r[u].red;
          pixel.green+=r[u].green;
          pixel.blue+=r[u].blue;
          pixel.opacity+=r[u].opacity;
          if (image->colorspace == CMYKColorspace)
            pixel.index=(MagickRealType) indexes[x+(r-p)+u];
        }
        r+=image->columns+width;
      }
      mean.red=(MagickRealType) (pixel.red/number_pixels+offset);
      mean.green=(MagickRealType) (pixel.green/number_pixels+offset);
      mean.blue=(MagickRealType) (pixel.blue/number_pixels+offset);
      mean.opacity=(MagickRealType) (pixel.opacity/number_pixels+offset);
      if (image->colorspace == CMYKColorspace)
        mean.index=(MagickRealType) (pixel.index/number_pixels+offset);
      q->red=(Quantum) (((MagickRealType) q->red <= mean.red) ?
        0 : QuantumRange);
      q->green=(Quantum) (((MagickRealType) q->green <= mean.green) ?
        0 : QuantumRange);
      q->blue=(Quantum) (((MagickRealType) q->blue <= mean.blue) ?
        0 : QuantumRange);
      q->opacity=(Quantum) (((MagickRealType) q->opacity <= mean.opacity) ?
        0 : QuantumRange);
      if (image->colorspace == CMYKColorspace)
        threshold_indexes[x]=(IndexPacket) (((MagickRealType)
          threshold_indexes[x] <= mean.index) ? 0 : QuantumRange);
      p++;
      q++;
    }
    sync=SyncCacheViewAuthenticPixels(threshold_view,exception);
    if (sync == MagickFalse)
      status=MagickFalse;
    if (image->progress_monitor != (MagickProgressMonitor) NULL)
      {
        MagickBooleanType
          proceed;

#if defined(MAGICKCORE_OPENMP_SUPPORT)
  #pragma omp critical
#endif
        proceed=SetImageProgress(image,ThresholdImageTag,progress++,
          image->rows);
        if (proceed == MagickFalse)
          status=MagickFalse;
      }
  }
  threshold_view=DestroyCacheView(threshold_view);
  image_view=DestroyCacheView(image_view);
  if (status == MagickFalse)
    threshold_image=DestroyImage(threshold_image);
  return(threshold_image);
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
%     B i l e v e l I m a g e                                                 %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  BilevelImage() changes the value of individual pixels based on the
%  intensity of each pixel channel.  The result is a high-contrast image.
%
%  More precisely each channel value of the image is 'thresholded' so that if
%  it is equal to or less than the given value it is set to zero, while any
%  value greater than that give is set to it maximum or QuantumRange.
%
%  This function is what is used to implement the "-threshold" operator for
%  the command line API.
%
%  If the default channel setting is given the image is thresholded using just
%  the gray 'intensity' of the image, rather than the individual channels.
%
%  The format of the BilevelImageChannel method is:
%
%      MagickBooleanType BilevelImage(Image *image,const double threshold)
%      MagickBooleanType BilevelImageChannel(Image *image,
%        const ChannelType channel,const double threshold)
%
%  A description of each parameter follows:
%
%    o image: the image.
%
%    o channel: the channel type.
%
%    o threshold: define the threshold values.
%
%  Aside: You can get the same results as operator using LevelImageChannels()
%  with the 'threshold' value for both the black_point and the white_point.
%
*/

MagickExport MagickBooleanType BilevelImage(Image *image,const double threshold)
{
  MagickBooleanType
    status;

  status=BilevelImageChannel(image,DefaultChannels,threshold);
  return(status);
}

MagickExport MagickBooleanType BilevelImageChannel(Image *image,
  const ChannelType channel,const double threshold)
{
#define ThresholdImageTag  "Threshold/Image"

  ExceptionInfo
    *exception;

  long
    progress,
    y;

  MagickBooleanType
    status;

  ViewInfo
    *image_view;

  assert(image != (Image *) NULL);
  assert(image->signature == MagickSignature);
  if (image->debug != MagickFalse)
    (void) LogMagickEvent(TraceEvent,GetMagickModule(),"%s",image->filename);
  if (SetImageStorageClass(image,DirectClass) == MagickFalse)
    return(MagickFalse);
  /*
    Bilevel threshold image.
  */
  status=MagickTrue;
  progress=0;
  exception=(&image->exception);
  image_view=AcquireCacheView(image);
#if defined(MAGICKCORE_OPENMP_SUPPORT)
  #pragma omp parallel for schedule(dynamic,8) shared(progress,status)
#endif
  for (y=0; y < (long) image->rows; y++)
  {
    register IndexPacket
      *indexes;

    register long
      x;

    register PixelPacket
      *q;

    if (status == MagickFalse)
      continue;
    q=GetCacheViewAuthenticPixels(image_view,0,y,image->columns,1,exception);
    if (q == (PixelPacket *) NULL)
      {
        status=MagickFalse;
        continue;
      }
    indexes=GetCacheViewAuthenticIndexQueue(image_view);
    if (channel == DefaultChannels)
      {
        for (x=0; x < (long) image->columns; x++)
        {
          q->red=(Quantum) ((MagickRealType) PixelIntensityToQuantum(q) <=
            threshold ? 0 : QuantumRange);
          q->green=q->red;
          q->blue=q->red;
          q++;
        }
      }
    else
      for (x=0; x < (long) image->columns; x++)
      {
        if ((channel & RedChannel) != 0)
          q->red=(Quantum) ((MagickRealType) q->red <= threshold ? 0 :
            QuantumRange);
        if ((channel & GreenChannel) != 0)
          q->green=(Quantum) ((MagickRealType) q->green <= threshold ? 0 :
            QuantumRange);
        if ((channel & BlueChannel) != 0)
          q->blue=(Quantum) ((MagickRealType) q->blue <= threshold ? 0 :
            QuantumRange);
        if ((channel & OpacityChannel) != 0)
          {
            if (image->matte == MagickFalse)
              q->opacity=(Quantum) ((MagickRealType) q->opacity <= threshold ?
                0 : QuantumRange);
            else
              q->opacity=(Quantum) ((MagickRealType) q->opacity <= threshold ?
                OpaqueOpacity : TransparentOpacity);
          }
        if (((channel & IndexChannel) != 0) &&
            (image->colorspace == CMYKColorspace))
          indexes[x]=(IndexPacket) ((MagickRealType) indexes[x] <= threshold ?
            0 : QuantumRange);
        q++;
      }
    if (SyncCacheViewAuthenticPixels(image_view,exception) == MagickFalse)
      status=MagickFalse;
    if (image->progress_monitor != (MagickProgressMonitor) NULL)
      {
        MagickBooleanType
          proceed;

#if defined(MAGICKCORE_OPENMP_SUPPORT)
  #pragma omp critical
#endif
        proceed=SetImageProgress(image,ThresholdImageTag,progress++,
          image->rows);
        if (proceed == MagickFalse)
          status=MagickFalse;
      }
  }
  image_view=DestroyCacheView(image_view);
  return(status);
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
%     B l a c k T h r e s h o l d I m a g e                                   %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  BlackThresholdImage() is like ThresholdImage() but forces all pixels below
%  the threshold into black while leaving all pixels above the threshold
%  unchanged.
%
%  The format of the BlackThresholdImage method is:
%
%      MagickBooleanType BlackThresholdImage(Image *image,const char *threshold)
%      MagickBooleanType BlackThresholdImageChannel(Image *image,
%        const ChannelType channel,const char *threshold,
%        ExceptionInfo *exception)
%
%  A description of each parameter follows:
%
%    o image: the image.
%
%    o channel: the channel or channels to be thresholded.
%
%    o threshold: Define the threshold value.
%
%    o exception: return any errors or warnings in this structure.
%
*/
MagickExport MagickBooleanType BlackThresholdImage(Image *image,
  const char *threshold)
{
  MagickBooleanType
    status;

  status=BlackThresholdImageChannel(image,DefaultChannels,threshold,
    &image->exception);
  return(status);
}

static inline MagickBooleanType IsLongGrayPixel(const LongPixelPacket *pixel)
{
#if !defined(MAGICKCORE_HDRI_SUPPORT)
  if ((pixel->red == pixel->green) && (pixel->green == pixel->blue))
    return(MagickTrue);
#else
  if ((fabs(pixel->red-pixel->green) <= MagickEpsilon) &&
      (fabs(pixel->green-pixel->blue) <= MagickEpsilon))
    return(MagickTrue);
#endif
  return(MagickFalse);
}

MagickExport MagickBooleanType BlackThresholdImageChannel(Image *image,
  const ChannelType channel,const char *threshold,ExceptionInfo *exception)
{
#define ThresholdImageTag  "Threshold/Image"

  GeometryInfo
    geometry_info;

  long
    progress,
    y;

  LongPixelPacket
    pixel;

  MagickBooleanType
    status;

  MagickStatusType
    flags;

  ViewInfo
    *image_view;

  assert(image != (Image *) NULL);
  assert(image->signature == MagickSignature);
  if (image->debug != MagickFalse)
    (void) LogMagickEvent(TraceEvent,GetMagickModule(),"%s",image->filename);
  if (threshold == (const char *) NULL)
    return(MagickTrue);
  if (SetImageStorageClass(image,DirectClass) == MagickFalse)
    return(MagickFalse);
  flags=ParseGeometry(threshold,&geometry_info);
  pixel.red=(long) (geometry_info.rho+0.5);
  pixel.green=(long) (geometry_info.sigma+0.5);
  if ((flags & SigmaValue) == 0)
    pixel.green=pixel.red;
  pixel.blue=(long) (geometry_info.xi+0.5);
  if ((flags & XiValue) == 0)
    pixel.blue=pixel.red;
  pixel.opacity=(long) (geometry_info.psi+0.5);
  if ((flags & XiValue) == 0)
    pixel.opacity=pixel.red;
  pixel.index=(long) (geometry_info.chi+0.5);
  if ((flags & ChiValue) == 0)
    pixel.index=pixel.red;
  if ((flags & PercentValue) != 0)
    {
      pixel.red*=(QuantumRange/100.0);
      pixel.green*=(QuantumRange/100.0);
      pixel.blue*=(QuantumRange/100.0);
      pixel.opacity*=(QuantumRange/100.0);
      pixel.index*=(QuantumRange/100.0);
    }
  /*
    Black threshold image.
  */
  status=MagickTrue;
  progress=0;
  image_view=AcquireCacheView(image);
#if defined(MAGICKCORE_OPENMP_SUPPORT)
  #pragma omp parallel for schedule(dynamic,8) shared(progress,status)
#endif
  for (y=0; y < (long) image->rows; y++)
  {
    register IndexPacket
      *indexes;

    register long
      x;

    register PixelPacket
      *q;

    if (status == MagickFalse)
      continue;
    q=GetCacheViewAuthenticPixels(image_view,0,y,image->columns,1,exception);
    if (q == (PixelPacket *) NULL)
      {
        status=MagickFalse;
        continue;
      }
    indexes=GetCacheViewAuthenticIndexQueue(image_view);
    if (IsLongGrayPixel(&pixel) != MagickFalse)
      for (x=0; x < (long) image->columns; x++)
      {
        if ((MagickRealType) PixelIntensityToQuantum(q) < pixel.red)
          {
            if ((channel & RedChannel) != 0)
              q->red=(Quantum) 0;
            if ((channel & GreenChannel) != 0)
              q->green=(Quantum) 0;
            if ((channel & BlueChannel) != 0)
              q->blue=(Quantum) 0;
          }
        q++;
      }
    else
      for (x=0; x < (long) image->columns; x++)
      {
        if (((channel & RedChannel) != 0) &&
            (q->red < pixel.red))
          q->red=(Quantum) 0;
        if (((channel & GreenChannel) != 0) &&
            (q->green < pixel.green))
          q->green=(Quantum) 0;
        if (((channel & BlueChannel) != 0) &&
            (q->blue < pixel.blue))
          q->blue=(Quantum) 0;
        if (((channel & OpacityChannel) != 0) &&
            (q->opacity < pixel.opacity))
          q->opacity=(Quantum) 0;
        if (((channel & IndexChannel) != 0) &&
            (image->colorspace == CMYKColorspace) &&
            (indexes[x] < pixel.index))
          indexes[x]=(Quantum) 0;
        q++;
      }
    if (SyncCacheViewAuthenticPixels(image_view,exception) == MagickFalse)
      status=MagickFalse;
    if (image->progress_monitor != (MagickProgressMonitor) NULL)
      {
        MagickBooleanType
          proceed;

#if defined(MAGICKCORE_OPENMP_SUPPORT)
  #pragma omp critical
#endif
        proceed=SetImageProgress(image,ThresholdImageTag,progress++,
          image->rows);
        if (proceed == MagickFalse)
          status=MagickFalse;
      }
  }
  image_view=DestroyCacheView(image_view);
  return(status);
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
%  D e s t r o y T h r e s h o l d M a p                                      %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  DestroyThresholdMap() de-allocate the given ThresholdMap
%
%  The format of the ListThresholdMaps method is:
%
%      ThresholdMap *DestroyThresholdMap(Threshold *map)
%
%  A description of each parameter follows.
%
%    o map:    Pointer to the Threshold map to destroy
%
*/
MagickExport ThresholdMap *DestroyThresholdMap(ThresholdMap *map)
{
  assert(map != (ThresholdMap *) NULL);
  if (map->map_id != (char *) NULL)
    map->map_id=DestroyString(map->map_id);
  if (map->description != (char *) NULL)
    map->description=DestroyString(map->description);
  if (map->levels != (long *) NULL)
    map->levels=(long *) RelinquishMagickMemory(map->levels);
  map=(ThresholdMap *) RelinquishMagickMemory(map);
  return(map);
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
+  G e t T h r e s h o l d M a p F i l e                                      %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  GetThresholdMapFile() look for a given threshold map name or alias in the
%  given XML file data, and return the allocated the map when found.
%
%  The format of the ListThresholdMaps method is:
%
%      ThresholdMap *GetThresholdMap(const char *xml,const char *filename,
%         const char *map_id,ExceptionInfo *exception)
%
%  A description of each parameter follows.
%
%    o xml:  The threshold map list in XML format.
%
%    o filename:  The threshold map XML filename.
%
%    o map_id:  ID of the map to look for in XML list.
%
%    o exception: return any errors or warnings in this structure.
%
*/
MagickExport ThresholdMap *GetThresholdMapFile(const char *xml,
  const char *filename,const char *map_id,ExceptionInfo *exception)
{
  const char *attr, *content;
  XMLTreeInfo *thresholds,*threshold,*description,*levels;
  ThresholdMap *map;

  map = (ThresholdMap *)NULL;
  (void) LogMagickEvent(ConfigureEvent,GetMagickModule(),
    "Loading threshold map file \"%s\" ...",filename);
  thresholds=NewXMLTree(xml,exception);
  if ( thresholds == (XMLTreeInfo *)NULL )
    return(map);

  for( threshold = GetXMLTreeChild(thresholds,"threshold");
       threshold != (XMLTreeInfo *)NULL;
       threshold = GetNextXMLTreeTag(threshold) ) {
    attr = GetXMLTreeAttribute(threshold, "map");
    if ( (attr != (char *)NULL) && (LocaleCompare(map_id,attr) == 0) )
      break;
    attr = GetXMLTreeAttribute(threshold, "alias");
    if ( (attr != (char *)NULL) && (LocaleCompare(map_id,attr) == 0) )
      break;
  }
  if ( threshold == (XMLTreeInfo *)NULL ) {
    return(map);
  }
  description = GetXMLTreeChild(threshold,"description");
  if ( description == (XMLTreeInfo *)NULL ) {
    (void) ThrowMagickException(exception,GetMagickModule(),OptionError,
      "XmlMissingElement", "<description>, map \"%s\"", map_id);
    thresholds = DestroyXMLTree(thresholds);
    return(map);
  }
  levels = GetXMLTreeChild(threshold,"levels");
  if ( levels == (XMLTreeInfo *)NULL ) {
    (void) ThrowMagickException(exception,GetMagickModule(),OptionError,
      "XmlMissingElement", "<levels>, map \"%s\"", map_id);
    thresholds = DestroyXMLTree(thresholds);
    return(map);
  }

  /* The map has been found -- Allocate a Threshold Map to return */
  map = (ThresholdMap *)AcquireMagickMemory(sizeof(ThresholdMap));
  if ( map == (ThresholdMap *)NULL )
    ThrowFatalException(ResourceLimitFatalError,"UnableToAcquireThresholdMap");
  map->map_id = (char *)NULL;
  map->description = (char *)NULL;
  map->levels = (long *) NULL;

  /* Assign Basic Attributes */
  attr = GetXMLTreeAttribute(threshold, "map");
  if ( attr != (char *)NULL )
    map->map_id = ConstantString(attr);

  content = GetXMLTreeContent(description);
  if ( content != (char *)NULL )
    map->description = ConstantString(content);

  attr = GetXMLTreeAttribute(levels, "width");
  if ( attr == (char *)NULL ) {
    (void) ThrowMagickException(exception,GetMagickModule(),OptionError,
      "XmlMissingAttribute", "<levels width>, map \"%s\"", map_id);
    thresholds = DestroyXMLTree(thresholds);
    map = DestroyThresholdMap(map);
    return(map);
  }
  map->width = (unsigned long) atoi(attr);
  if ( map->width == 0 ) {
    (void) ThrowMagickException(exception,GetMagickModule(),OptionError,
     "XmlInvalidAttribute", "<levels width>, map \"%s\"", map_id);
    thresholds = DestroyXMLTree(thresholds);
    map = DestroyThresholdMap(map);
    return(map);
  }

  attr = GetXMLTreeAttribute(levels, "height");
  if ( attr == (char *)NULL ) {
    (void) ThrowMagickException(exception,GetMagickModule(),OptionError,
      "XmlMissingAttribute", "<levels height>, map \"%s\"", map_id);
    thresholds = DestroyXMLTree(thresholds);
    map = DestroyThresholdMap(map);
    return(map);
  }
  map->height = (unsigned long) atoi(attr);
  if ( map->height == 0 ) {
    (void) ThrowMagickException(exception,GetMagickModule(),OptionError,
      "XmlInvalidAttribute", "<levels height>, map \"%s\"", map_id);
    thresholds = DestroyXMLTree(thresholds);
    map = DestroyThresholdMap(map);
    return(map);
  }

  attr = GetXMLTreeAttribute(levels, "divisor");
  if ( attr == (char *)NULL ) {
    (void) ThrowMagickException(exception,GetMagickModule(),OptionError,
      "XmlMissingAttribute", "<levels divisor>, map \"%s\"", map_id);
    thresholds = DestroyXMLTree(thresholds);
    map = DestroyThresholdMap(map);
    return(map);
  }
  map->divisor = atoi(attr);
  if ( map->divisor < 2 ) {
    (void) ThrowMagickException(exception,GetMagickModule(),OptionError,
      "XmlInvalidAttribute", "<levels divisor>, map \"%s\"", map_id);
    thresholds = DestroyXMLTree(thresholds);
    map = DestroyThresholdMap(map);
    return(map);
  }

  /* Allocate theshold levels array */
  content = GetXMLTreeContent(levels);
  if ( content == (char *)NULL ) {
    (void) ThrowMagickException(exception,GetMagickModule(),OptionError,
      "XmlMissingContent", "<levels>, map \"%s\"", map_id);
    thresholds = DestroyXMLTree(thresholds);
    map = DestroyThresholdMap(map);
    return(map);
  }
  map->levels=(long *) AcquireQuantumMemory((size_t) map->width,map->height*
    sizeof(*map->levels));
  if ( map->levels == (long *)NULL )
    ThrowFatalException(ResourceLimitFatalError,"UnableToAcquireThresholdMap");
  { /* parse levels into integer array */
    int i;
    char *p;
    for( i=0; i< (long) (map->width*map->height); i++) {
      map->levels[i] = (int)strtol(content, &p, 10);
      if ( p == content ) {
        (void) ThrowMagickException(exception,GetMagickModule(),OptionError,
          "XmlInvalidContent", "<level> too few values, map \"%s\"", map_id);
        thresholds = DestroyXMLTree(thresholds);
        map = DestroyThresholdMap(map);
        return(map);
      }
      if ( map->levels[i] < 0 || map->levels[i] > map->divisor ) {
        (void) ThrowMagickException(exception,GetMagickModule(),OptionError,
          "XmlInvalidContent", "<level> %ld out of range, map \"%s\"",
          map->levels[i], map_id);
        thresholds = DestroyXMLTree(thresholds);
        map = DestroyThresholdMap(map);
        return(map);
      }
      content = p;
    }
    (void) strtol(content, &p, 10);
    if ( p != content ) {
       (void) ThrowMagickException(exception,GetMagickModule(),OptionError,
         "XmlInvalidContent", "<level> too many values, map \"%s\"", map_id);
      thresholds = DestroyXMLTree(thresholds);
      map = DestroyThresholdMap(map);
      return(map);
    }
  }

  thresholds = DestroyXMLTree(thresholds);
  return(map);
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
%  G e t T h r e s h o l d M a p                                              %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  GetThresholdMap() load and search one or more threshold map files for the
%  a map matching the given name or aliase.
%
%  The format of the GetThresholdMap method is:
%
%      ThresholdMap *GetThresholdMap(const char *map_id,
%         ExceptionInfo *exception)
%
%  A description of each parameter follows.
%
%    o map_id:  ID of the map to look for.
%
%    o exception: return any errors or warnings in this structure.
%
*/
MagickExport ThresholdMap *GetThresholdMap(const char *map_id,
  ExceptionInfo *exception)
{
  const StringInfo
    *option;

  LinkedListInfo
    *options;

  ThresholdMap
    *map;

  map=(ThresholdMap *)NULL;
  options=GetConfigureOptions(ThresholdsFilename,exception);
  while (( option=(const StringInfo *) GetNextValueInLinkedList(options) )
          != (const StringInfo *) NULL && map == (ThresholdMap *)NULL )
    map=GetThresholdMapFile((const char *) GetStringInfoDatum(option),
      GetStringInfoPath(option),map_id,exception);
  options=DestroyConfigureOptions(options);
  return(map);
}

/*
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                                                                             %
%                                                                             %
+  L i s t T h r e s h o l d M a p F i l e                                    %
%                                                                             %
%                                                                             %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  ListThresholdMapFile() lists the threshold maps and their descriptions
%  in the given XML file data.
%
%  The format of the ListThresholdMaps method is:
%
%      MagickBooleanType ListThresholdMaps(FILE *file,const char*xml,
%         const char *filename,ExceptionInfo *exception)
%
%  A description of each parameter follows.
%
%    o file:  An pointer to the output FILE.
%
%    o xml:  The threshold map list in XML format.
%
%    o filename:  The threshold map XML filename.
%
%    o exception: return any errors or warnings in this structure.
%
*/
MagickBooleanType ListThresholdMapFile(FILE *file,const char *xml,
  const char *filename,ExceptionInfo *exception)
{
  XMLTreeInfo *thresholds,*threshold,*description;
  const char *map,*alias,*content;

  assert( xml != (char *)NULL );
  assert( file != (FILE *)NULL );

  (void) LogMagickEvent(ConfigureEvent,GetMagickModule(),
    "Loading threshold map file \"%s\" ...",filename);
  thresholds=NewXMLTree(xml,exception);
  if ( thresholds == (XMLTreeInfo *)NULL )
    return(MagickFalse);

  (void) fprintf(file,