doc/filters_dithering.txt

   1 Dithering
   2 ---------
   3
   4 Currently there are two dithering algorithms implemented. Both takes an RGB888
   5 24bit image as input and are able to produce any RGB or Grayscale image.
   6 This filters doesn't work 'in-place' as the result has different pixel type.
   7
   8 Floyd-Steinberg
   9 ~~~~~~~~~~~~~~~
  10
  11 Classical Floyd-Steinberg. Produces good results and is a little faster than
  12 the Hilbert-Peano dithering.
  13
  14 The error is distributed to neighbor pixels as follows:
  15
  16 [width="10%"]
  17 |===================
  18 |      |   X  | 7/16
  19 | 3/16 | 5/16 | 1/16
  20 |===================
  21
  22 And is throwed away at the image borders.
  23
  24 [source,c]
  25 -------------------------------------------------------------------------------
  26 #include <GP.h>
  27 /* or */
  28 #include <filters/GP_Dither.h>
  29
  30 int GP_FilterFloydSteinberg(const GP_Context *src, GP_Context *dst,
  31                             GP_ProgressCallback *callback);
  32 -------------------------------------------------------------------------------
  33
  34 Renders Floyd Steinberg dithering directly into passed context. The
  35 destination must be at least as large as source.
  36
  37 If operation was aborted by a callback, non-zero is returned.
  38
  39 Not all pixel types all supported. If particular combination is not supported
  40 the function returns non-zero and sets errno to 'ENOSYS'.
  41
  42 [source,c]
  43 -------------------------------------------------------------------------------
  44 #include <GP.h>
  45 /* or */
  46 #include <filters/GP_Dither.h>
  47
  48 GP_Context *GP_FilterFloydSteinbergAlloc(const GP_Context *src,
  49                                          GP_PixelType pixel_type,
  50                                          GP_ProgressCallback *callback);
  51 -------------------------------------------------------------------------------
  52
  53 Returns pointer to allocated context of given pixel_type.
  54
  55 If 'malloc(2)' has failed, or operation was aborted by a callback 'NULL' is
  56 returned.
  57
  58 Not all pixel types all supported. If particular combination is not supported
  59 the function returns 'NULL' and sets errno to 'ENOSYS'.
  60
  61 Hilbert-Peano
  62 ~~~~~~~~~~~~~
  63
  64 Hilbert-Peano space filling curve based dithering.
  65
  66 The error value is distributed around the Hilbert curve.
  67
  68 The result is a little more noisy, but doesn't create repeating patterns like
  69 Floyd-Steinberg which looks generally better to human eye. On the other hand
  70 edges tend to be less sharp.
  71
  72 [source,c]
  73 -------------------------------------------------------------------------------
  74 #include <GP.h>
  75 /* or */
  76 #include <filters/GP_Dither.h>
  77
  78 int GP_FilterHilbertPeano(const GP_Context *src, GP_Context *dst,
  79                           GP_ProgressCallback *callback);
  80 -------------------------------------------------------------------------------
  81
  82 Renders Hilbert Peano dithering directly into passed context. The
  83 destination must be at least as large as source.
  84
  85 If operation was aborted by a callback, non-zero is returned.
  86
  87 Not all pixel types all supported. If particular combination is not supported
  88 the function returns 'NULL' and sets errno to 'ENOSYS'.
  89
  90 [source,c]
  91 -------------------------------------------------------------------------------
  92 #include <GP.h>
  93 /* or */
  94 #include <filters/GP_Dither.h>
  95
  96 GP_Context *GP_FilterHilbertPeanoAlloc(const GP_Context *src,
  97                                        GP_PixelType pixel_type,
  98                                        GP_ProgressCallback *callback);
  99 -------------------------------------------------------------------------------
 100
 101 Returns pointer to allocated context of given pixel_type.
 102
 103 If 'malloc(2)' has failed, or operation was aborted by a callback 'NULL' is
 104 returned.
 105
 106 Not all pixel types all supported. If particular combination is not supported
 107 the function returns 'NULL' and sets errno to 'ENOSYS'.
 108
 109 Example Images
 110 ^^^^^^^^^^^^^^
 111 All following images were generated using 'grinder'.
 112 (Click for bigger size)
 113
 114 .Original Image; Floyd-Steinberg, Hilbert-Peano: 1-bit, 2-bit, 4-bit, 8-bit Grayscale; 1-bit, 2-bit, 3-bit (per channel) RGB
 115 image:images/dither/lenna_small.png[
 116         "Original Image",
 117         link="images/dither/lenna.png"]
 118 image:images/dither/lenna_G1_FS_small.png[
 119         "1-bit Grayscale Floyd-Steinberg",
 120         link="images/dither/lenna_G1_FS.png"]
 121 image:images/dither/lenna_G1_HP_small.png[
 122         "1-bit Grayscale Hilbert-Peano",
 123         link="images/dither/lenna_G1_HP.png"]
 124 image:images/dither/lenna_G2_FS_small.png[
 125         "2-bit Grayscale Floyd-Steinberg",
 126         link="images/dither/lenna_G2_FS.png"]
 127 image:images/dither/lenna_G2_HP_small.png[
 128         "2-bit Grayscale Hilbert-Peano",
 129         link="images/dither/lenna_G2_HP.png"]
 130 image:images/dither/lenna_G4_FS_small.png[
 131         "4-bit Grayscale Floyd-Steinberg",
 132         link="images/dither/lenna_G4_FS.png"]
 133 image:images/dither/lenna_G4_HP_small.png[
 134         "4-bit Grayscale Hilbert-Peano",
 135         link="images/dither/lenna_G4_HP.png"]
 136 image:images/dither/lenna_G8_FS_small.png[
 137         "8-bit Grayscale Floyd-Steinberg",
 138         link="images/dither/lenna_G8_FS.png"]
 139 image:images/dither/lenna_G8_HP_small.png[
 140         "7-bit Grayscale Hilbert-Peano",
 141         link="images/dither/lenna_G8_HP.png"]
 142 image:images/dither/lenna_RGB111_FS_small.png[
 143         "1-bit RGB Floyd-Steinberg",
 144         link="images/dither/lenna_RGB111_FS.png"]
 145 image:images/dither/lenna_RGB111_HP_small.png[
 146         "1-bit RGB Hilbert-Peano",
 147         link="images/dither/lenna_RGB111_HP.png"]
 148 image:images/dither/lenna_RGB222_FS_small.png[
 149         "2-bit RGB Floyd-Steinberg",
 150         link="images/dither/lenna_RGB222_FS.png"]
 151 image:images/dither/lenna_RGB222_HP_small.png[
 152         "2-bit RGB Hilbert-Peano",
 153         link="images/dither/lenna_RGB222_HP.png"]
 154 image:images/dither/lenna_RGB333_FS_small.png[
 155         "3-bit RGB Floyd-Steinberg",
 156         link="images/dither/lenna_RGB333_FS.png"]
 157 image:images/dither/lenna_RGB333_HP_small.png[
 158         "3-bit RGB Hilbert-Peano",
 159         link="images/dither/lenna_RGB333_HP.png"]