//C-  -*- C++ -*-
//C- -------------------------------------------------------------------
//C- DjVuLibre-3.5
//C- Copyright (c) 2002  Leon Bottou and Yann Le Cun.
//C- Copyright (c) 2001  AT&T
//C-
//C- This software is subject to, and may be distributed under, the
//C- GNU General Public License, either Version 2 of the license,
//C- or (at your option) any later version. The license should have
//C- accompanied the software or you may obtain a copy of the license
//C- from the Free Software Foundation at http://www.fsf.org .
//C-
//C- This program is distributed in the hope that it will be useful,
//C- but WITHOUT ANY WARRANTY; without even the implied warranty of
//C- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//C- GNU General Public License for more details.
//C- 
//C- DjVuLibre-3.5 is derived from the DjVu(r) Reference Library from
//C- Lizardtech Software.  Lizardtech Software has authorized us to
//C- replace the original DjVu(r) Reference Library notice by the following
//C- text (see doc/lizard2002.djvu and doc/lizardtech2007.djvu):
//C-
//C-  ------------------------------------------------------------------
//C- | DjVu (r) Reference Library (v. 3.5)
//C- | Copyright (c) 1999-2001 LizardTech, Inc. All Rights Reserved.
//C- | The DjVu Reference Library is protected by U.S. Pat. No.
//C- | 6,058,214 and patents pending.
//C- |
//C- | This software is subject to, and may be distributed under, the
//C- | GNU General Public License, either Version 2 of the license,
//C- | or (at your option) any later version. The license should have
//C- | accompanied the software or you may obtain a copy of the license
//C- | from the Free Software Foundation at http://www.fsf.org .
//C- |
//C- | The computer code originally released by LizardTech under this
//C- | license and unmodified by other parties is deemed "the LIZARDTECH
//C- | ORIGINAL CODE."  Subject to any third party intellectual property
//C- | claims, LizardTech grants recipient a worldwide, royalty-free, 
//C- | non-exclusive license to make, use, sell, or otherwise dispose of 
//C- | the LIZARDTECH ORIGINAL CODE or of programs derived from the 
//C- | LIZARDTECH ORIGINAL CODE in compliance with the terms of the GNU 
//C- | General Public License.   This grant only confers the right to 
//C- | infringe patent claims underlying the LIZARDTECH ORIGINAL CODE to 
//C- | the extent such infringement is reasonably necessary to enable 
//C- | recipient to make, have made, practice, sell, or otherwise dispose 
//C- | of the LIZARDTECH ORIGINAL CODE (or portions thereof) and not to 
//C- | any greater extent that may be necessary to utilize further 
//C- | modifications or combinations.
//C- |
//C- | The LIZARDTECH ORIGINAL CODE is provided "AS IS" WITHOUT WARRANTY
//C- | OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
//C- | TO ANY WARRANTY OF NON-INFRINGEMENT, OR ANY IMPLIED WARRANTY OF
//C- | MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
//C- +------------------------------------------------------------------

#ifndef _DJVUPALETTE_H_
#define _DJVUPALETTE_H_
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif
#if NEED_GNUG_PRAGMAS
# pragma interface
#endif


#include "GContainer.h"
#include "GPixmap.h"
#include <string.h>


#ifdef HAVE_NAMESPACES
namespace DJVU {
# ifdef NOT_DEFINED // Just to fool emacs c++ mode
}
#endif
#endif


/** @name DjVuPalette.h
    Files #"DjVuPalette.h"# and #"DjVuPalette.cpp"# implement a single class
    \Ref{DjVuPalette} which provides facilities for computing optimal color
    palettes, coding color palettes, and coding sequences of color indices.
    @memo 
    DjVuPalette header file
    @author: 
    L\'eon Bottou <leonb@research.att.com> */
//@{


/** Computing and coding color palettes and index arrays.
    This class provides facilities for computing optimal color palettes,
    coding color palettes, and coding sequences of color indices.
    
    {\bf Creating a color palette} -- The recipe for creating a color palette
    consists in (a) creating a DjVuPalette object, (b) constructing a color
    histogram using \Ref{histogram_add}, and (c) calling function
    \Ref{compute_palette}.

    {\bf Accessing the color palette} -- Conversion between colors and color
    palette indices is easily achieved with \Ref{color_to_index} and
    \Ref{index_to_color}.  There are also functions for computing a palette
    and quantizing a complete pixmap.

    {\bf Sequences of color indices} -- The DjVuPalette object also contains
    an array \Ref{colordata} optionally containing a sequence of color
    indices.  This array will be encoded and decoded by functions \Ref{encode}
    and \Ref{decode}.  This feature simplifies the implementation of the ``one
    color per symbol'' model in DjVu.

    {\bf Coding color palettes and color indices} -- Two functions
    \Ref{encode} and \Ref{decode} are provided for coding the color palette
    and the array of color indices when appropriate.  */
#ifdef _WIN32_WCE_EMULATION         // Work around odd behavior under WCE Emulation
#define CALLINGCONVENTION __cdecl
#else
#define CALLINGCONVENTION  /* */
#endif

class DJVUAPI DjVuPalette : public GPEnabled
{
protected:
  DjVuPalette(void);
public:
  /// Generic creator
  static GP<DjVuPalette> create(void) {return new DjVuPalette();}

  /// Non-virtual destructor
  ~DjVuPalette();
  // COPY
  DjVuPalette(const DjVuPalette &ref);
  DjVuPalette& operator=(const DjVuPalette &ref);
  // PALETTE COMPUTATION
  /** Resets the color histogram to zero. */
  void histogram_clear();
  /** Adds the color specified by #p# to the histogram.
      Argument #weight# represent the number of pixels with this color. */
  void histogram_add(const GPixel &p, int weight);
  /** Adds the color specified by the triple #bgr# to the histogram.
      Argument #weight# represent the number of pixels with this color. */
  void histogram_add(const unsigned char *bgr, int weight);
  /** Adds the color specified by the weighted triple #bgr# to the histogram.
      Argument #weight# represent the number of pixels with this color.  This
      function will compute the actual color by dividing the elements of the
      #bgr# array by #weight# and then use the unnormalized values to compute
      the average color per bucket.  This is all a way to avoid excessive loss
      of accuracy. */
  void histogram_norm_and_add(const int *bgr, int weight);
  /** Computes an optimal palette for representing an image where colors
      appear according to the histogram.  Argument #maxcolors# is the maximum
      number of colors allowed in the palette (up to 1024).  Argument
      #minboxsize# controls the minimal size of the color cube area affected
      to a color palette entry.  Returns the index of the dominant color. */
  int compute_palette(int maxcolors, int minboxsize=0);
  /** Computes the optimal palette for pixmap #pm#.  This function builds the
      histogram for pixmap #pm# and computes the optimal palette using
      \Ref{compute_palette}. */
  int compute_pixmap_palette(const GPixmap &pm, int ncolors, int minboxsize=0);
  // CONVERSION
  /** Returns the number of colors in the palette. */
  int size() const;
  /** Returns the best palette index for representing color #p#. */
  int color_to_index(const GPixel &p);
  /** Returns the best palette index for representing color #bgr#. */
  int color_to_index(const unsigned char *bgr);
  /** Overwrites #p# with the color located at position #index# in the palette. */
  void index_to_color(int index, GPixel &p) const;
  /** Overwrites #rgb[0..3]# with the color located at 
      position #index# in the palette. */
  void index_to_color(int index, unsigned char *bgr) const;
  /** Quantizes pixmap #pm#. All pixels are replaced by their closest
      approximation available in the palette. */
  void quantize(GPixmap &pm);
  /** Calls \Ref{compute_pixmap_palette} and \Ref{quantize}. */
  int compute_palette_and_quantize(GPixmap &pm, int maxcolors, int minboxsize=0);
  // COLOR CORRECTION
  /** Applies a luminance gamma correction factor of #corr# to the palette
      entries.  Values greater than #1.0# make the image brighter.  Values
      smaller than #1.0# make the image darker.  The documentation of program
      \Ref{ppmcoco} explains how to properly use this function. */
  void color_correct(double corr);
  // COLOR INDEX DATA
  /** Contains an optional sequence of color indices. 
      Function \Ref{encode} and \Ref{decode} also encode and decode this
      sequence when such a sequence is provided. */
  GTArray<short> colordata;
  /** Returns colors from the color index sequence.  Pixel #out# is
      overwritten with the color corresponding to the #nth# element of the
      color sequence \Ref{colordata}. */
  void get_color(int nth, GPixel &out) const;
  // CODING
  /** Writes the palette colors.  This function writes each palette color as a
      RGB triple into bytestream #bs#. */
  void encode_rgb_entries(ByteStream &bs) const;
  /** Reads palette colors.  This function initializes the palette colors by
      reading #palettesize# RGB triples from bytestream #bs#. */
  void decode_rgb_entries(ByteStream &bs, const int palettesize);
  /** Encodes the palette and the color index sequence. This function encodes
      the a version byte, the palette size, the palette colors and the color
      index sequence into bytestream #bs#.  Note that the color histogram is
      never saved. */
  void encode(GP<ByteStream> bs) const;
  /** Initializes the object by reading data from bytestream #bs#.  This
      function reads a version byte, the palette size, the palette and the
      color index sequence from bytestream #bs#.  Note that the color
      histogram is never saved. */
  void decode(GP<ByteStream> bs);

private:
  // Histogram
  int mask;
  GMap<int,int> *hist;
  // Quantization data
  struct PColor { unsigned char p[4]; };
  GTArray<PColor> palette;
  GMap<int,int> *pmap;
  // Helpers
  void allocate_hist();
  void allocate_pmap();
  static int CALLINGCONVENTION bcomp (const void*, const void*);
  static int CALLINGCONVENTION gcomp (const void*, const void*);
  static int CALLINGCONVENTION rcomp (const void*, const void*);
  static int CALLINGCONVENTION lcomp (const void*, const void*);
  int color_to_index_slow(const unsigned char *bgr);
private: // dummy functions
  static void encode(ByteStream *);
  static void decode(ByteStream *);
};


//@}

// ------------ INLINES


inline void 
DjVuPalette::histogram_clear()
{
  delete hist;
  hist = 0;
  mask = 0;
}

inline void 
DjVuPalette::histogram_add(const unsigned char *bgr, int weight)
{
  if (weight > 0)
    {
      if (!hist || hist->size()>=0x4000) 
        allocate_hist();
      int key = (bgr[0]<<16)|(bgr[1]<<8)|(bgr[2])|(mask);
      (*hist)[key] += weight;
    }
}  

inline void 
DjVuPalette::histogram_add(const GPixel &p, int weight)
{
  histogram_add(&p.b, weight);
}

inline void 
DjVuPalette::histogram_norm_and_add(const int *bgr, int weight)
{
  if (weight > 0)
    {
      int p0 = bgr[0]/weight; if (p0>255) p0=255;
      int p1 = bgr[1]/weight; if (p1>255) p1=255;
      int p2 = bgr[2]/weight; if (p2>255) p2=255;
      if (!hist || hist->size()>=0x4000) 
        allocate_hist();
      int key = (p0<<16)|(p1<<8)|(p2)|(mask);
      (*hist)[key] += weight;
    }
}

inline int
DjVuPalette::size() const
{
  return palette.size();
}

inline int 
DjVuPalette::color_to_index(const unsigned char *bgr)
{
  if (! pmap)
    allocate_pmap();
  int key = (bgr[0]<<16)|(bgr[1]<<8)|(bgr[2]);
  GPosition p = pmap->contains(key);
  if ( p)
    return (*pmap)[p];
  return color_to_index_slow(bgr);
}

inline int 
DjVuPalette::color_to_index(const GPixel &p)
{
  return color_to_index(&p.b);
}

inline void 
DjVuPalette::index_to_color(int index, unsigned char *bgr) const
{
  const PColor &color = palette[index];
  bgr[0] = color.p[0];
  bgr[1] = color.p[1];
  bgr[2] = color.p[2];
}

inline void 
DjVuPalette::index_to_color(int index, GPixel &p) const
{
  index_to_color(index, &p.b);
}

inline void
DjVuPalette::get_color(int nth, GPixel &p) const
{
  index_to_color(colordata[nth], p);
}



// ------------ THE END

#ifdef HAVE_NAMESPACES
}
# ifndef NOT_USING_DJVU_NAMESPACE
using namespace DJVU;
# endif
#endif
#endif