doc/filters.txt

   1 Context filters
   2 ---------------
   3
   4 Pixel filters for 'GP_Context'.
   5
   6 The context filter is basically a function that operates on context pixels.
   7 The result may be stored into a new bitmap or placed to bitmap passed as
   8 argument or, in some cases, the filter could be used 'in place' so the result
   9 is stored into the same context as the one passed as filter source.
  10
  11 Common filter API
  12 ~~~~~~~~~~~~~~~~~
  13
  14 For convenience, the filters API is unified:
  15
  16 * There are two functions for each filter
  17   - first one takes destination as an argument
  18   - second one allocates the destination and returns pointer to it
  19 * First argument(s) are always source(s)
  20 * Then, in case of second variant, destination
  21 * Other parameters follow
  22 * And the last argument is link:progress_callback.html[progress callback]
  23
  24 When using allocating version of the filter, pointer to the newly allocated
  25 context is returned, or in case of failure 'NULL' is returned.
  26
  27 If 'malloc()' has failed 'NULL' is returned.
  28
  29 If filter has been interrupted by a callback, all allocated memory is freed,
  30 and 'NULL' is returned.
  31
  32 When using non-allocating variant of the filter, the destination context must
  33 have correct pixel type and the size must be big enough to store the result.
  34 The return value from such filter is either zero, in case of success, or
  35 non-zero when filter was interrupted by a callback.
  36
  37 For filters that work 'in-place' (which is explicitly said for each filter)
  38 the source and the destination could be the same context. Note that this is
  39 not expected to work if you do several overlapping sub-contexts and pass these
  40 as arguments.
  41
  42 [source,c]
  43 -------------------------------------------------------------------------------
  44 /*
  45  * Filter common API.
  46  */
  47 int GP_FilterFoo(const GP_Context *src, GP_Context *dst,
  48                  foo params ...,
  49                  GP_ProgressCallback *callback);
  50
  51 GP_Context *GP_FilterFooAlloc(const GP_Context *src,
  52                               foo params ...,
  53                               GP_ProgressCallback *callback);
  54 -------------------------------------------------------------------------------
  55
  56
  57 Filters also exists in _Raw variant whose interface is similar to the first
  58 type of filter function. These filter APIs are used for internal
  59 implementation and shouldn't be called by user as the destination is expected
  60 to be crafted exactly for storing the filter result and there are 'NO' sanity
  61 checks in place.
  62
  63 'You could use these at your own risk'
  64
  65 [source,c]
  66 -------------------------------------------------------------------------------
  67 /*
  68  * Raw filter common API.
  69  */
  70 int GP_FilterFoo_Raw(const GP_Context *src, GP_Context *dst,
  71                      foo params ...,
  72                      GP_ProgressCallback *callback);
  73 -------------------------------------------------------------------------------
  74
  75 Filter Parameters
  76 ~~~~~~~~~~~~~~~~~
  77
  78 In order to pass, per-channel, filter parameters to a filter, structure called
  79 GP_FilterParams was created.
  80
  81 [source,c]
  82 -------------------------------------------------------------------------------
  83 #include <GP.h>
  84 /* or */
  85 #include <filters/GP_FilterParam.h>
  86
  87 typedef union GP_FilterParamVal {
  88         float f;
  89         uint32_t ui;
  90         int32_t i;
  91         void *ptr;
  92 } GP_FilterParamVal;
  93
  94 typedef struct GP_FilterParam {
  95         char channel_name[2];
  96         union GP_FilterParamVal val;
  97 } GP_FilterParam;
  98 -------------------------------------------------------------------------------
  99
 100 Some filters do take an empty channel_name terminated (empty channel_name is
 101 empty string i.e. "\0") array of GP_FilterParam, which is used to describe
 102 per-channel parameters.
 103
 104
 105 There are two methods how to construct GP_FilterParam structure. First one is
 106 to use macro that expands to a code which declares and initializes the array on
 107 the stack second uses memory allocated by a malloc(). In both cases the
 108 structure is has initialized channel names and terminator.
 109
 110 [source,c]
 111 -------------------------------------------------------------------------------
 112 #include <GP.h>
 113 /* or */
 114 #include <filters/GP_FilterParam.h>
 115
 116 #define GP_FILTER_PARAMS(pixel_type, name) \
 117         GP_FilterParam name[GP_PixelTypes[pixel_type].numchannels + 1]; \
 118         GP_FilterParamInitChannels(name, pixel_type);
 119 -------------------------------------------------------------------------------
 120
 121 Macro that declares and initializes GP_FilterParam structure for a given
 122 pixel_type.
 123
 124 [source,c]
 125 -------------------------------------------------------------------------------
 126 #include <GP.h>
 127 /* or */
 128 #include <filters/GP_FilterParam.h>
 129
 130 GP_FilterParam *GP_FilterParamCreate(GP_PixelType pixel_type);
 131
 132 void GP_FilterParamDestroy(GP_FilterParam *self);
 133 -------------------------------------------------------------------------------
 134
 135 Second possible way allocates memory using malloc().
 136
 137 Functions for manipulating and querying existing GP_FilterParam follows.
 138
 139 [source,c]
 140 -------------------------------------------------------------------------------
 141 #include <GP.h>
 142 /* or */
 143 #include <filters/GP_FilterParam.h>
 144
 145 void GP_FilterParamInitChannels(GP_FilterParam params[],
 146                                 GP_PixelType pixel_type);
 147 -------------------------------------------------------------------------------
 148
 149 Initializes filter param array channel names (accordingly to pixel type) and
 150 terminator. The params array must be large enough to hold number of pixel type
 151 channels plus one.
 152
 153 [source,c]
 154 -------------------------------------------------------------------------------
 155 #include <GP.h>
 156 /* or */
 157 #include <filters/GP_FilterParam.h>
 158
 159 GP_FilterParam *GP_FilterParamChannel(GP_FilterParam params[],
 160                                       const char *channel_name);
 161 -------------------------------------------------------------------------------
 162
 163 Does lookup for a given channel name and returns, if found, corresponding
 164 GP_FilterParam, otherwise 'NULL' is returned.
 165
 166 This function is primary used in filters, where filter, at the start, resolves
 167 all it's parameters.
 168
 169 [source,c]
 170 -------------------------------------------------------------------------------
 171 #include <GP.h>
 172 /* or */
 173 #include <filters/GP_FilterParam.h>
 174
 175 int GP_FilterParamCheckPixelType(GP_FilterParam params[],
 176                                  GP_PixelType pixel_type);
 177 -------------------------------------------------------------------------------
 178
 179 Matches param structure against pixel_type. Returns zero if params describes
 180 exactly same channels like pixel_type, non-zero otherwise.
 181
 182 [source,c]
 183 -------------------------------------------------------------------------------
 184 #include <GP.h>
 185 /* or */
 186 #include <filters/GP_FilterParam.h>
 187
 188 void GP_FilterParamSetIntAll(GP_FilterParam params[], int32_t val);
 189
 190 int GP_FilterParamSetInt(GP_FilterParam params[], const char *channel_name,
 191                          int32_t val);
 192
 193 void GP_FilterParamSetFloatAll(GP_FilterParam params[], float val);
 194
 195 int GP_FilterParamSetFloat(GP_FilterParam params[], const char *channel_name,
 196                            float val);
 197
 198 void GP_FilterParamSetUIntAll(GP_FilterParam params[], uint32_t val);
 199
 200 int GP_FilterParamSetUInt(GP_FilterParam params[], const char *channel_name,
 201                           uint32_t val);
 202
 203 void GP_FilterParamSetPtrAll(GP_FilterParam params[], void *ptr);
 204
 205 int GP_FilterParamSetPtr(GP_FilterParam params[], const char *channel_name,
 206                          void *ptr);
 207
 208 void GP_FilterParamFreePtrAll(GP_FilterParam params[]);
 209 -------------------------------------------------------------------------------
 210
 211 Parameter setters. Those that sets individual value returns zero on success
 212 (i.e. channel was found) and non-zero otherwise.
 213
 214 The last one calls free() on all param pointers, which is used to free
 215 allocate memory.
 216
 217 Point operation filters
 218 ~~~~~~~~~~~~~~~~~~~~~~~
 219
 220 Point operations are filters that works with pixels as with independent values
 221 (the value of destination pixel depends only on the pixel on the same
 222 coordinates in source image). All of these filters works 'in-place' and the
 223 result has always the same size as the source.
 224
 225 [source,c]
 226 -------------------------------------------------------------------------------
 227 #include <GP_Filters.h>
 228
 229 GP_Context *GP_FilterBrightness(const GP_Context *src, GP_Context *dst,
 230                                 int32_t inc, GP_ProgressCallback *callback);
 231 -------------------------------------------------------------------------------
 232
 233 Brightness filter, increments all pixel channels by a fixed value.
 234
 235 [source,c]
 236 -------------------------------------------------------------------------------
 237 #include <GP_Filters.h>
 238
 239 GP_Context *GP_FilterContrast(const GP_Context *src, GP_Context *dst,
 240                               float mul, GP_ProgressCallback *callback);
 241 -------------------------------------------------------------------------------
 242
 243 Contrast filter, multiplies all pixel channels by a fixed value.
 244
 245 [source,c]
 246 -------------------------------------------------------------------------------
 247 #include <GP_Filters.h>
 248
 249 GP_Context *GP_FilterInvert(const GP_Context *src, GP_Context *dst,
 250                             GP_ProgressCallback *callback);
 251 -------------------------------------------------------------------------------
 252
 253 Inverts the image, for each channel the result value is computed as "chan_max
 254 - val".
 255
 256 include::filter_additive_gaussian_noise.txt[]
 257
 258 Arithmetic filters
 259 ~~~~~~~~~~~~~~~~~~
 260
 261 Arithmetic filters do take two contexts as an input and combines them into one
 262 output context.
 263
 264 The pixel type of both input contexts must match.
 265
 266 If size of the input contexts differs, minimum is used.
 267
 268 [source,c]
 269 -------------------------------------------------------------------------------
 270 #include <filters/GP_Arithmetic.h>
 271 /* or */
 272 #include <GP.h>
 273
 274 int GP_FilterAddition(const GP_Context *src_a,
 275                       const GP_Context *src_b,
 276                       GP_Context *dst,
 277                       GP_ProgressCallback *callback);
 278
 279 GP_Context *GP_FilterAdditionAlloc(const GP_Context *src_a,
 280                                    const GP_Context *src_b,
 281                                    GP_ProgressCallback *callback);
 282 -------------------------------------------------------------------------------
 283
 284 Produces saturated (clamped) addition of two contexts.
 285
 286 [source,c]
 287 -------------------------------------------------------------------------------
 288 #include <filters/GP_Arithmetic.h>
 289 /* or */
 290 #include <GP.h>
 291
 292 int GP_FilterMultiply(const GP_Context *src_a,
 293                       const GP_Context *src_b,
 294                       GP_Context *dst,
 295                       GP_ProgressCallback *callback);
 296
 297 GP_Context *GP_FilterMultiplyAlloc(const GP_Context *src_a,
 298                                    const GP_Context *src_b,
 299                                    GP_ProgressCallback *callback);
 300 -------------------------------------------------------------------------------
 301
 302 Produces saturated (clamped) multiplication of two contexts.
 303
 304 [source,c]
 305 -------------------------------------------------------------------------------
 306 #include <filters/GP_Arigthmetic.h>
 307 /* or */
 308 #include <GP.h>
 309
 310 int GP_FilterDifference(const GP_Context *src_a,
 311                         const GP_Context *src_b,
 312                         GP_Context *dst,
 313                         GP_ProgressCallback *callback);
 314
 315 GP_Context *GP_FilterDifferenceAlloc(const GP_Context *src_a,
 316                                      const GP_Context *src_b,
 317                                      GP_ProgressCallback *callback);
 318
 319 -------------------------------------------------------------------------------
 320
 321 Produces symmetric difference (i.e. abs(a - b)).
 322
 323 [source,c]
 324 -------------------------------------------------------------------------------
 325 #include <filters/GP_Arigthmetic.h>
 326 /* or */
 327 #include <GP.h>
 328
 329 int GP_FilterMax(const GP_Context *src_a,
 330                  const GP_Context *src_b,
 331                  GP_Context *dst,
 332                  GP_ProgressCallback *callback);
 333
 334 GP_Context *GP_FilterMaxAlloc(const GP_Context *src_a,
 335                               const GP_Context *src_b,
 336                               GP_ProgressCallback *callback);
 337
 338 int GP_FilterMin(const GP_Context *src_a,
 339                  const GP_Context *src_b,
 340                  GP_Context *dst,
 341                  GP_ProgressCallback *callback);
 342
 343 GP_Context *GP_FilterMinAlloc(const GP_Context *src_a,
 344                               const GP_Context *src_b,
 345                               GP_ProgressCallback *callback);
 346 -------------------------------------------------------------------------------
 347
 348 Maximum and minimum filter.
 349
 350 Rotation and Symmetry filters
 351 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 352
 353 [source,c]
 354 -------------------------------------------------------------------------------
 355 #include <filters/GP_Rotate.h>
 356 /* or */
 357 #include <GP.h>
 358
 359 int GP_FilterMirrorH(const GP_Context *src, GP_Context *dst,
 360                      GP_ProgressCallback *callback);
 361
 362 GP_Context *GP_FilterMirrorHAlloc(const GP_Context *src,
 363                                    GP_ProgressCallback *callback);
 364 -------------------------------------------------------------------------------
 365
 366 Mirrors context horizontally.
 367
 368 Works 'in-place'.
 369
 370 The destination has to have the same pixel type and the size must be at least
 371 as large as source.
 372
 373 [source,c]
 374 -------------------------------------------------------------------------------
 375 #include <filters/GP_Rotate.h>
 376 /* or */
 377 #include <GP.h>
 378
 379 int GP_FilterMirrorV(const GP_Context *src, GP_Context *dst,
 380                      GP_ProgressCallback *callback);
 381
 382 GP_Context *GP_FilterMirrorVAlloc(const GP_Context *src,
 383                                    GP_ProgressCallback *callback);
 384 -------------------------------------------------------------------------------
 385
 386 Mirrors context vertically.
 387
 388 Works 'in-place'.
 389
 390 The destination has to have the same pixel type and the size must be at least
 391 as large as source.
 392
 393 [source,c]
 394 -------------------------------------------------------------------------------
 395 #include <filters/GP_Rotate.h>
 396 /* or */
 397 #include <GP.h>
 398
 399 int GP_FilterRotate90(const GP_Context *src, GP_Context *dst,
 400                       GP_ProgressCallback *callback);
 401
 402 GP_Context *GP_FilterRotate90Alloc(const GP_Context *src,
 403                                     GP_ProgressCallback *callback);
 404 -------------------------------------------------------------------------------
 405
 406 Rotate context by 90 degrees.
 407
 408 Doesn't work 'in-place' (yet).
 409
 410 The destination has to have the same pixel type and size must be large enough to
 411 fit rotated context (i.e. W and H are swapped).
 412
 413 [source,c]
 414 -------------------------------------------------------------------------------
 415 #include <filters/GP_Rotate.h>
 416 /* or */
 417 #include <GP.h>
 418
 419 int GP_FilterRotate180(const GP_Context *src, GP_Context *dst,
 420                        GP_ProgressCallback *callback);
 421
 422 GP_Context *GP_FilterRotate180Alloc(const GP_Context *src,
 423                                      GP_ProgressCallback *callback);
 424 -------------------------------------------------------------------------------
 425
 426 Rotate context by 180 degrees.
 427
 428 Doesn't work 'in-place' (yet).
 429
 430 The destination has to have the same pixel type and the size must be at least
 431 as large as source.
 432
 433 [source,c]
 434 -------------------------------------------------------------------------------
 435 #include <filters/GP_Rotate.h>
 436 /* or */
 437 #include <GP.h>
 438
 439 int GP_FilterRotate270(const GP_Context *src, GP_Context *dst,
 440                        GP_ProgressCallback *callback);
 441
 442 GP_Context *GP_FilterRotate270Alloc(const GP_Context *src,
 443                                      GP_ProgressCallback *callback);
 444 -------------------------------------------------------------------------------
 445
 446 Rotate context by 270 degrees.
 447
 448 Doesn't work 'in-place' (yet).
 449
 450 The destination has to have the same pixel type and destination size must be
 451 large enough to fit rotated context (i.e. W and H are swapped).
 452
 453 [source,c]
 454 -------------------------------------------------------------------------------
 455 #include <filters/GP_Rotate.h>
 456 /* or */
 457 #include <GP.h>
 458
 459 typedef enum GP_FilterSymmetries {
 460         GP_ROTATE_90,
 461         GP_ROTATE_CW = GP_ROTATE_90,
 462         GP_ROTATE_180,
 463         GP_ROTATE_270,
 464         GP_ROTATE_CCW = GP_ROTATE_270,
 465         GP_MIRROR_H,
 466         GP_MIRROR_V,
 467 } GP_FilterSymmetries;
 468
 469 GP_Context *GP_FilterSymmetry(const GP_Context *src,
 470                               GP_FilterSymmetries symmetry,
 471                               GP_ProgressCallback *callback);
 472
 473 int GP_FilterSymmetry(const GP_Context *src, GP_Context *dst,
 474                       GP_FilterSymmetries symmetry,
 475                       GP_ProgressCallback *callback);
 476 -------------------------------------------------------------------------------
 477
 478 Catch all function for symmetry filters.
 479
 480
 481 Linear filters
 482 ~~~~~~~~~~~~~~
 483
 484 Linear filters family consists of filters based on discrete linear
 485 convolution, that means that computed pixel value depends on linear
 486 combination of the image pixels.
 487
 488 It's defined as:
 489 [latex, discrete_linear_convolution.png, 140]
 490 -------------------------------------------------------------------------------
 491 \[
 492 O(x,y)=\sum_{i=-\infty}^{\infty}\sum_{j=-\infty}^{\infty}I(x+i,y+j) \cdot K(i,j)
 493 \]
 494 -------------------------------------------------------------------------------
 495
 496 The K denotes convolution kernel and in practice, due to computational
 497 complexity i and j are bounded in relatively small intervals. For example i
 498 and j are in (-1,1) and the kernel size is 3x3.
 499
 500 Note that pixel values outside the image are undefined. The linear convolution
 501 in GFXprim simply uses the closest border pixel values for all pixels outside
 502 the image.
 503
 504 Particular convolution kernel is called separable if it could be decomposed
 505 into two one dimensional kernels (these when combined yields back the original
 506 kernel). Such convolution then could be applied as two one dimensional
 507 convolutions which is faster operation (especially for big kernels).
 508
 509 Generic Linear Convolution
 510 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 511
 512 Following paragraph describes linear convolution implementation as well as a
 513 little of the math background skip it if you just need to use one of the
 514 ready-to-use filters.
 515
 516 [source,c]
 517 -------------------------------------------------------------------------------
 518 #include <filters/GP_Linear.h>
 519 /* or */
 520 #include <GP.h>
 521
 522 int GP_FilterLinearConvolution_Raw(const GP_Context *src,
 523                                    GP_Coord x_src, GP_Coord y_src,
 524                                    GP_Size w_src, GP_Size h_src,
 525                                    GP_Context *dst,
 526                                    GP_Coord x_dst, GP_Coord y_dst,
 527                                    float kernel[], uint32_t kw, uint32_t kh,
 528                                    float kern_div, GP_ProgressCallback *callback);
 529 -------------------------------------------------------------------------------
 530
 531 Internal generic convolution filter, this is a base for all linear convolution
 532 filters with non-separable kernel.
 533
 534 The src coordinate and sizes denotes rectangle in the source context that the
 535 filter operates on.
 536
 537 The dst coordinates defines offset into the dst context.
 538
 539 The kernel is two-dimensional array of a size kw * kh indexed as
 540 kernel[x + y*kw].
 541
 542 The kern_div is a coefficient that is used to divide the resulting values often
 543 used to normalize the result.
 544
 545 This filter works 'in-place'.
 546
 547 The pixel value is computed as:
 548 [latex, discrete_linear_convolution_alg1.png, 140]
 549 -------------------------------------------------------------------------------
 550 \[
 551 O(x,y)={1 \over kern\_div} \cdot \sum_{i=0}^{kw - 1}\sum_{j=0}^{kh - 1}
 552        I(x + i - \lfloor kw/2 \rfloor, y + j - \lfloor kh/2 \rfloor)
 553        \cdot kernel(i,j)
 554 \]
 555 -------------------------------------------------------------------------------
 556
 557 Which is the same as:
 558
 559 [latex, discrete_linear_convolution_alg2.png, 140]
 560 -------------------------------------------------------------------------------
 561 \[
 562 O(x,y)={1 \over kern\_div} \cdot
 563        \sum_{i=-\lfloor kw/2 \rfloor}^{\lfloor kw/2 \rfloor}
 564        \sum_{j=-\lfloor kh/2 \rfloor}^{\lfloor kh/2 \rfloor}
 565        I(x + i, y + j)
 566        \cdot kernel(i + \lfloor kw/2 \rfloor, j + \lfloor kh/2 \rfloor)
 567 \]
 568 -------------------------------------------------------------------------------
 569
 570 NOTE: The number of kernel rows and columns is expected to be odd number.
 571
 572 [source,c]
 573 -------------------------------------------------------------------------------
 574 #include <filters/GP_Linear.h>
 575 /* or */
 576 #include <GP.h>
 577
 578 int GP_FilterHLinearConvolution_Raw(const GP_Context *src,
 579                                     GP_Coord x_src, GP_Coord y_src,
 580                                     GP_Size w_src, GP_Size h_src,
 581                                     GP_Context *dst,
 582                                     GP_Coord x_dst, GP_Coord y_dst,
 583                                     float kernel[], uint32_t kw, float kern_div,
 584                                     GP_ProgressCallback *callback);
 585
 586 int GP_FilterVLinearConvolution_Raw(const GP_Context *src,
 587                                     GP_Coord x_src, GP_Coord y_src,
 588                                     GP_Size w_src, GP_Size h_src,
 589                                     GP_Context *dst,
 590                                     GP_Coord x_dst, GP_Coord y_dst,
 591                                     float kernel[], uint32_t kh, float kern_div,
 592                                     GP_ProgressCallback *callback);
 593
 594 int GP_FilterVHLinearConvolution_Raw(const GP_Context *src,
 595                                      GP_Coord x_src, GP_Coord y_src,
 596                                      GP_Size w_src, GP_Size h_src,
 597                                      GP_Context *dst,
 598                                      GP_Coord x_dst, GP_Coord y_dst,
 599                                      float hkernel[], uint32_t kw, float hkern_div,
 600                                      float vkernel[], uint32_t kh, float vkern_div,
 601                                      GP_ProgressCallback *callback);
 602
 603 void GP_FilterKernelPrint_Raw(float kernel[], int kw, int kh, float kern_div);
 604 -------------------------------------------------------------------------------
 605
 606 Internal special functions for one dimensional vertical and horizontal
 607 convolution these two functions are base for all separable convolution filters.
 608
 609 The src coordinate and sizes denotes rectangle in the source context that the
 610 filter operates on.
 611
 612 The dst coordinates are offset into the dst.
 613
 614 The kernel is one-dimensional array of floats of size kw or kh.
 615
 616 The kern_div is a coefficient that is used to divide the resulting values.
 617
 618 The last function does both vertical and horizontal convolution and takes care
 619 of correct progress callback.
 620
 621 These filters work 'in-place'.
 622
 623 The pixel value is computed as:
 624 [latex, discrete_linear_1D_convolution_alg1.png, 140]
 625 -------------------------------------------------------------------------------
 626 \[
 627 O(x,y)={1 \over kern\_div} \cdot \sum_{i=0}^{kw - 1}
 628        I(x + i - \lfloor kw/2 \rfloor, y)
 629        \cdot kernel(i)
 630 \]
 631
 632 \[
 633 O(x,y)={1 \over kern\_div} \cdot \sum_{j=0}^{kw - 1}
 634        I(x, y + j - \lfloor kh/2 \rfloor)
 635        \cdot kernel(j)
 636 \]
 637 -------------------------------------------------------------------------------
 638
 639 Which is the same as:
 640
 641 [latex, discrete_linear_1D_convolution_alg2.png, 140]
 642 -------------------------------------------------------------------------------
 643 \[
 644 O(x,y)={1 \over kern\_div} \cdot
 645        \sum_{i=-\lfloor kw/2 \rfloor}^{\lfloor kw/2 \rfloor}
 646        I(x + i, y)
 647        \cdot kernel(i + \lfloor kw/2 \rfloor)
 648 \]
 649
 650 \[
 651 O(x,y)={1 \over kern\_div} \cdot
 652        \sum_{j=-\lfloor kh/2 \rfloor}^{\lfloor kh/2 \rfloor}
 653        I(x, y + j)
 654        \cdot kernel(i, j + \lfloor kh/2 \rfloor)
 655 \]
 656 -------------------------------------------------------------------------------
 657
 658 NOTE: The number of kernel rows and columns is expected to be odd number.
 659
 660 NOTE: The linear convolutions are internally implemented using integer
 661       arithmetics, which works fine, but you need to take a care not to
 662       overflow 32bit signed integer. If the pixel channel size is 8bit
 663       long and 10bits are used for the fixed point part of the number
 664       the rest must fit into about 10 bits to be safe.
 665
 666 [source,c]
 667 -------------------------------------------------------------------------------
 668 #include <filters/GP_Convolution.h>
 669 /* or */
 670 #include <GP.h>
 671
 672 typedef struct GP_FilterKernel2D {
 673         unsigned int w;
 674         unsigned int h;
 675         float div;
 676         float *kernel;
 677 } GP_FilterKernel2D;
 678
 679 int GP_FilterConvolutionEx(const GP_Context *src,
 680                            GP_Coord x_src, GP_Coord y_src,
 681                            GP_Size w_src, GP_Coord h_src,
 682                            GP_Context *dst,
 683                            GP_Coord x_dst, GP_Coord y_dst,
 684                            const GP_FilterKernel2D *kernel,
 685                            GP_ProgressCallback *callback);
 686
 687 GP_Context *GP_FilterConvolutionExAlloc(const GP_Context *src,
 688                                         GP_Coord x_src, GP_Coord y_src,
 689                                         GP_Size w_src, GP_Size h_src,
 690                                         const GP_FilterKernel2D *kernel,
 691                                         GP_ProgressCallback *callback);
 692
 693 int GP_FilterConvolution(const GP_Context *src, GP_Context *dst,
 694                          const GP_FilterKernel2D *kernel,
 695                          GP_ProgressCallback *callback);
 696
 697 GP_Context *GP_FilterConvolutionAlloc(const GP_Context *src,
 698                                       const GP_FilterKernel2D *kernel,
 699                                       GP_ProgressCallback *callback);
 700
 701 void GP_FilterKernel2DPrint(const GP_FilterKernel2D *kernel);
 702 -------------------------------------------------------------------------------
 703
 704 Linear convolution filters, you should preferably use this API over the _Raw
 705 variants.
 706
 707 The Ex variants takes a rectangle on which the filter should operate as well
 708 as offset into the destination. The destination must be large enough so that
 709 starting with offset there is at least w_dst and h_dst pixels.
 710
 711 The kernel is a pointer to a structure initialized with the kernel size, divider
 712 and array of kernel values.
 713
 714 The last function prints convolution kernel in human-readable format into the
 715 stdout.
 716
 717 WARNING: If filter is executed in-place the work cannot be distributed between
 718          threads (as some of the threads will overwrite values read by other
 719          threads). In this case convolution filters runs in one thread
 720          regardless of if threads are eanbled or not.
 721
 722 [source,c]
 723 -------------------------------------------------------------------------------
 724 #include <GP.h>
 725
 726 /*
 727  * Example box smoothing filter.
 728  */
 729 static void box_smoothing(GP_Context *img)
 730 {
 731         float box_filter[] = {
 732                 1, 1, 1,
 733                 1, 1, 1,
 734                 1, 1, 1,
 735         };
 736
 737         GP_FilterKernel2D box_kernel = {
 738                 .w = 3,
 739                 .h = 3,
 740                 .div = 9,
 741                 .kernel = box_filter,
 742         };
 743
 744         GP_FilterConvolution(img, img, &box_kernel, NULL);
 745 }
 746 -------------------------------------------------------------------------------
 747
 748 Example function that implements simple 'in-place' smoothing filter.
 749
 750 Laplace Filter
 751 ^^^^^^^^^^^^^^
 752
 753 [source,c]
 754 -------------------------------------------------------------------------------
 755 #include <GP_Filters.h>
 756 /* or */
 757 #include <GP.h>
 758
 759 int GP_FilterLaplace(const GP_Context *src, GP_Context *dst,
 760                      GP_ProgressCallback *callback);
 761
 762 GP_Context *GP_FilterLaplaceAlloc(const GP_Context *src,
 763                                   GP_ProgressCallback *callback);
 764 -------------------------------------------------------------------------------
 765
 766 Discrete Laplace filter that produces a second derivative of the original
 767 image.
 768
 769 The convolution kernel is defined as:
 770
 771 [latex, laplacian_kernel.png, 130]
 772 -------------------------------------------------------------------------------
 773 \[
 774 \begin{bmatrix}
 775 0  &  1  &  0 \\
 776 0  & -2  &  0 \\
 777 0  &  1  &  0
 778 \end{bmatrix}
 779 +
 780 \begin{bmatrix}
 781 0  &  0  &  0 \\
 782 1  & -2  &  1 \\
 783 0  &  0  &  0
 784 \end{bmatrix}
 785 =
 786 \begin{bmatrix}
 787 0  &  1  &  0 \\
 788 1  & -4  &  1 \\
 789 0  &  1  &  0
 790 \end{bmatrix}
 791 \]
 792 -------------------------------------------------------------------------------
 793
 794 NOTE: This filter is not separable but could be written as a sum of two one
 795       dimensional filters as the kernel definition suggests.
 796
 797 Laplacian Edge Sharpening
 798 ^^^^^^^^^^^^^^^^^^^^^^^^^
 799
 800 [source,c]
 801 -------------------------------------------------------------------------------
 802 #include <GP_Filters.h>
 803 /* or */
 804 #include <GP.h>
 805
 806 int GP_FilterEdgeSharpening(const GP_Context *src, GP_Context *dst,
 807                             float w, GP_ProgressCallback *callback);
 808
 809 GP_Context *GP_FilterEdgeSharpeningAlloc(const GP_Context *src, float w,
 810                                          GP_ProgressCallback *callback);
 811 -------------------------------------------------------------------------------
 812
 813 Laplace based edge sharpening filter, subtracts weighted second derivative
 814 from the original image.
 815
 816 The w paramerter is multiplicative weight applied on the second derivative.
 817 Reasonable results are when the parameter is between '0.1' and '1'.
 818
 819 [latex, laplacian_edge_sharpening.png, 140]
 820 -------------------------------------------------------------------------------
 821 \[
 822 O(x,y) = I(x,y) - w * I''(x,y)
 823 \]
 824 -------------------------------------------------------------------------------
 825
 826 include::images/edge_sharpening/images.txt[]
 827
 828 Gaussian Blur
 829 ^^^^^^^^^^^^^
 830
 831 [source,c]
 832 -------------------------------------------------------------------------------
 833 #include <filters/GP_Blur.h>
 834 /* or */
 835 #include <GP.h>
 836
 837 int GP_FilterGaussianBlurEx(const GP_Context *src,
 838                             GP_Coord x_src, GP_Coord y_src,
 839                             GP_Size w_src, GP_Size h_src,
 840                             GP_Context *dst,
 841                             GP_Coord x_dst, GP_Coord y_dst,
 842                             float x_sigma, float y_sigma,
 843                             GP_ProgressCallback *callback);
 844
 845 GP_Context *GP_FilterGaussianBlurExAlloc(const GP_Context *src,
 846                                          GP_Coord x_src, GP_Coord y_src,
 847                                          GP_Size w_src, GP_Size h_src,
 848                                          float x_sigma, float y_sigma,
 849                                          GP_ProgressCallback *callback);
 850
 851 int GP_FilterGaussianBlur(const GP_Context *src, GP_Context *dst,
 852                           float x_sigma, float y_sigma,
 853                           GP_ProgressCallback *callback)
 854
 855 GP_Context *GP_FilterGaussianBlurAlloc(const GP_Context *src,
 856                                        float x_sigma, float y_sigma,
 857                                        GP_ProgressCallback *callback)
 858 -------------------------------------------------------------------------------
 859
 860 Gaussian blur (low pass) filters implemented as bilinear separable
 861 convolution.
 862
 863 The sigma denotes amount of the blur (the radius is computed accordingly
 864 automatically).
 865
 866 The sigma values can be set for vertical and horizontal direction
 867 independently which may be useful when Gaussian blur is used as a low pass
 868 filter before image is resampled non proportionally.
 869
 870 include::images/blur/images.txt[]
 871
 872 Interpolation filters
 873 ~~~~~~~~~~~~~~~~~~~~~
 874
 875 Filters to link:filters_resize.html[resize image].
 876
 877 Nearest Neighbour Interpolation
 878 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 879
 880 Fast, but produces "pixelated" images. May however work better for images with
 881 sharp edges mostly consisting of big one color regions (it doesn't blur the
 882 result on upscaling).
 883
 884 Also is commonly used to show preview before you resample the image correctly.
 885
 886 Bilinear Interpolation
 887 ^^^^^^^^^^^^^^^^^^^^^^
 888
 889 Bilinear is faster than bicubic interpolation and produces quite good results
 890 especially the low pass variant doesn't need additional filter on down-sampling.
 891
 892 Bicubic Interpolation
 893 ^^^^^^^^^^^^^^^^^^^^^
 894
 895 Works well as is on image upscaling. To get decent result on downscaling
 896 low-pass filter (Gaussian blur) must be used on original image before actual
 897 downscaling. To do this reasonably fast we could cheat a little: first resize
 898 big images a little without the low-pass filter, then apply low-pass filter and
 899 finally downscale it to desired size.
 900
 901 [[Dithering]]
 902 Dithering
 903 ~~~~~~~~~
 904
 905 link:filters_dithering.html[Dithering filters] are filters for better loosy
 906 (source pixel type has more bits to represent color or grayscale value) pixel
 907 type conversions.
 908
 909 Median
 910 ~~~~~~
 911
 912 [source,c]
 913 -------------------------------------------------------------------------------
 914 #include <filters/GP_Median.h>
 915 /* or */
 916 #include <GP.h>
 917
 918 int GP_FilterMedianEx(const GP_Context *src,
 919                       GP_Coord x_src, GP_Coord y_src,
 920                       GP_Size w_src, GP_Size h_src,
 921                       GP_Context *dst,
 922                       GP_Coord x_dst, GP_Coord y_dst,
 923                       int xmed, int ymed,
 924                       GP_ProgressCallback *callback);
 925
 926 GP_Context *GP_FilterMedianExAlloc(const GP_Context *src,
 927                                    GP_Coord x_src, GP_Coord y_src,
 928                                    GP_Size w_src, GP_Size h_src,
 929                                    int xmed, int ymed,
 930                                    GP_ProgressCallback *callback);
 931
 932 int GP_FilterMedian(const GP_Context *src,
 933                     GP_Context *dst,
 934                     int xmed, int ymed,
 935                     GP_ProgressCallback *callback);
 936
 937 GP_Context *GP_FilterMedianAlloc(const GP_Context *src,
 938                                  int xmed, int ymed,
 939                                  GP_ProgressCallback *callback);
 940 -------------------------------------------------------------------------------
 941
 942 Constant time median filter (the computational complexity is independent of
 943 radius size).
 944
 945 The xmed and ymed are radius values for x and y. The algorithm uses xmed
 946 respectively ymed pixel neighbors from each side so the result is median of
 947 rectangle of 2 * xmed + 1 x 2 * ymed + 1 pixels.
 948
 949 include::images/median/images.txt[]