doc/filters_python.txt

   1 Python Filters module
   2 ---------------------
   3
   4 The python binding maps mostly to the C API with the 'GP_Filter' prefix
   5 stripped.
   6
   7 The filter functions could be called directly as +filters.Foo(img, ..)+ or
   8 from submodule as +img.filters.Foo(..)+. Note that in the second case the
   9 image is passed automatically as a first parameter.
  10
  11 If filter is aborted from a callback 'OSError' with errno set to
  12 'ECANCELED' is raised, see
  13 link:core_python.html#Progress_Callback[progress callback] for more
  14 information.
  15
  16 Point Filters
  17 ~~~~~~~~~~~~~
  18
  19 Invert
  20 ^^^^^^
  21
  22 [source,python]
  23 -------------------------------------------------------------------------------
  24 import gfxprim.core as core
  25 import gfxprim.filters as filters
  26
  27     # Inverts image in-place
  28     img.filters.Invert(img, callback=None)
  29
  30     # Returns newly allocated inverted image
  31     res = img.filters.InvertAlloc(callback=None)
  32
  33 -------------------------------------------------------------------------------
  34
  35 The pixel channel values are counted as +chann_max - val+.
  36
  37 include::images/invert/images.txt[]
  38
  39 Brightness
  40 ^^^^^^^^^^
  41
  42 [source,python]
  43 -------------------------------------------------------------------------------
  44 import gfxprim.core as core
  45 import gfxprim.filters as filters
  46
  47     # Increses images brightness in-place by channel_max * 0.2
  48     img.filters.Brightness(img, 0.2, callback=None)
  49
  50     # Returns image with brightness decreased by channel_max * -0.5
  51     res = img.filters.BrightnessAlloc(img, -0.5, callback=None)
  52
  53 -------------------------------------------------------------------------------
  54
  55 The pixel channel values are counted as +val + chann_max * p+.
  56
  57 include::images/brightness/images.txt[]
  58
  59 Contrast
  60 ^^^^^^^^
  61
  62 [source,python]
  63 -------------------------------------------------------------------------------
  64 import gfxprim.core as core
  65 import gfxprim.filters as filters
  66
  67     # Increses images contrast by 1.2
  68     img.filters.Contrast(img, 1.2, callback=None)
  69
  70     # Returns image with contrast decreased by 0.2
  71     res = img.filters.ContrastAlloc(img, 0.2, callback=None)
  72
  73 -------------------------------------------------------------------------------
  74
  75 The pixel channel values are counted as +val * p+.
  76
  77 include::images/contrast/images.txt[]
  78
  79 BrightnessContrast
  80 ^^^^^^^^^^^^^^^^^^
  81
  82 [source,python]
  83 -------------------------------------------------------------------------------
  84 import gfxprim.core as core
  85 import gfxprim.filters as filters
  86
  87     # Increses images contrast by 1.2 decreases brightness by -0.2
  88     img.filters.BrightnessContrast(img, -0.2, 1.2, callback=None)
  89
  90     # Returns image with contrast decreased by 0.2 brightness increased by .5
  91     res = img.filters.BrightnessContrastAlloc(img, 0.5, 0.2, callback=None)
  92
  93 -------------------------------------------------------------------------------
  94
  95 The pixel channel values are counted as +val * c + chann_max * b+.
  96
  97 include::images/brightness_contrast/images.txt[]
  98
  99 Posterize
 100 ^^^^^^^^^
 101
 102 [source,python]
 103 -------------------------------------------------------------------------------
 104 import gfxprim.core as core
 105 import gfxprim.filters as filters
 106
 107     # Posterizes image using 2 steps
 108     img.filters.Posterize(img, 2, callback=None)
 109
 110     # Returns image posterized into 4 levels
 111     res = img.filters.PosterizeAlloc(img, 4, callback=None)
 112
 113 -------------------------------------------------------------------------------
 114
 115 The pixel channel values are quantized into number of levels.
 116
 117 include::images/posterize/images.txt[]
 118
 119 Rotations and Mirroring
 120 ~~~~~~~~~~~~~~~~~~~~~~~
 121
 122 MirrorH
 123 ^^^^^^^
 124
 125 [source,python]
 126 -------------------------------------------------------------------------------
 127 import gfxprim.core as core
 128 import gfxprim.filters as filters
 129
 130     # Mirrors in-place image horizontally
 131     img.filters.MirrorH(img, callback=None)
 132
 133     # Mirrors image horizontally
 134     res = img.filters.MirrorHAlloc(callback=None)
 135
 136 -------------------------------------------------------------------------------
 137
 138 Mirrors image horizontally.
 139
 140 include::images/mirror_h/images.txt[]
 141
 142 MirrorV
 143 ^^^^^^^
 144
 145 [source,python]
 146 -------------------------------------------------------------------------------
 147 import gfxprim.core as core
 148 import gfxprim.filters as filters
 149
 150     # Mirrors in-place image vertically
 151     img.filters.MirrorV(img, callback=None)
 152
 153     # Mirrors image vertically
 154     res = img.filters.MirrorVAlloc(callback=None)
 155
 156 -------------------------------------------------------------------------------
 157
 158 Mirrors image vertically.
 159
 160 include::images/mirror_v/images.txt[]
 161
 162 Rotate90
 163 ^^^^^^^^
 164
 165 [source,python]
 166 -------------------------------------------------------------------------------
 167 import gfxprim.core as core
 168 import gfxprim.filters as filters
 169
 170     # Rotate in-place by 90 degrees
 171     img.filters.Rotate90(img, callback=None)
 172
 173     # Rotate by 90 degrees
 174     res = img.filters.Rotate90Alloc(callback=None)
 175
 176 -------------------------------------------------------------------------------
 177
 178 Rotate image by 90 degrees clockwise.
 179
 180 include::images/rotate_90/images.txt[]
 181
 182 Rotate180
 183 ^^^^^^^^^
 184
 185 [source,python]
 186 -------------------------------------------------------------------------------
 187 import gfxprim.core as core
 188 import gfxprim.filters as filters
 189
 190     # Rotate in-place by 180 degrees
 191     img.filters.Rotate180(img, callback=None)
 192
 193     # Rotate by 180 degrees
 194     res = img.filters.Rotate180Alloc(callback=None)
 195
 196 -------------------------------------------------------------------------------
 197
 198 Rotate image by 180 degrees clockwise.
 199
 200 include::images/rotate_180/images.txt[]
 201
 202 Rotate270
 203 ^^^^^^^^^
 204
 205 [source,python]
 206 -------------------------------------------------------------------------------
 207 import gfxprim.core as core
 208 import gfxprim.filters as filters
 209
 210     # Rotate in-place by 270 degrees
 211     img.filters.Rotate270(img, callback=None)
 212
 213     # Rotate by 270 degrees
 214     res = img.filters.Rotate270Alloc(callback=None)
 215
 216 -------------------------------------------------------------------------------
 217
 218 Rotate image by 270 degrees clockwise.
 219
 220 include::images/rotate_270/images.txt[]
 221
 222 Gaussian Additive Noise
 223 ~~~~~~~~~~~~~~~~~~~~~~~
 224
 225 [source,python]
 226 -------------------------------------------------------------------------------
 227 import gfxprim.core as core
 228 import gfxprim.filters as filters
 229
 230     # Adds Gaussian noise in-place with sigma=0.2 mu=0.0
 231     filters.GaussianNoiseAdd(img, img, 0.2, 0.0, callback=None)
 232
 233     # Returns newly allocated noisy image
 234     res = img.filters.GaussianNoiseAddAlloc(0.2, 0.0, callback=None)
 235
 236 -------------------------------------------------------------------------------
 237
 238 Gaussian additive noise filter adds gaussian distributed noise to an image
 239 with a defined sigma and mu. Both sigma and mu weights mapped to '[0,1]'
 240 interval.
 241
 242 include::images/gaussian_noise/images.txt[]
 243
 244
 245 Laplacian Edge Sharpening
 246 ~~~~~~~~~~~~~~~~~~~~~~~~~
 247
 248 [source,python]
 249 -------------------------------------------------------------------------------
 250 import gfxprim.core as core
 251 import gfxprim.filters as filters
 252
 253     # Does in-place Edge Sharpening
 254     filters.EdgeSharpening(img, img, 0.2, callback=None)
 255
 256     # Returns newly allocated sharpened image
 257     res = img.filters.EdgeSharpening(0.2, callback=None)
 258
 259 -------------------------------------------------------------------------------
 260
 261 Laplace based edge sharpening filter, subtracts weighted second derivative
 262 from the original image.
 263
 264 The float paramerter is multiplicative weight applied on the second
 265 derivative. Reasonable results are when the parameter is between '0.1' and
 266 '1'.
 267
 268 ////
 269 Generated in filters.txt
 270 ////
 271 image:laplacian_edge_sharpening.png["Laplacian Edge Sharpening"]
 272
 273 include::images/edge_sharpening/images.txt[]
 274
 275 Convolution
 276 ~~~~~~~~~~~
 277
 278 [source,python]
 279 -------------------------------------------------------------------------------
 280 import gfxprim.core as core
 281 import gfxprim.filters as filters
 282
 283     # Does in-place bilinear convolution with 3x3 box blur kernel
 284     filters.Convolution(img, img, [[1, 1, 1],
 285                                    [1, 1, 1],
 286                                    [1, 1, 1]], 9, callback=None)
 287
 288     # Does bilinear convolution with 3x3 box blur kernel.
 289     #
 290     # The image data from source starting at 20,20 of a size 250x250 are
 291     # stored at 100,100 in res.
 292     filters.ConvolutionEx(img, 20, 20, 250, 250, res, 100, 100,
 293                           [[1, 1, 1],
 294                            [1, 1, 1],
 295                            [1, 1, 1]], 9, callback=None)
 296
 297     # Returns newly allocated image convolution with Laplacian 3x3 kernel
 298     res = img.filters.ConvolutionAlloc([[ 0.00, -0.25,  0.00],
 299                                         [-0.25,  1.00, -0.25],
 300                                         [ 0.00, -0.25,  0.00]],
 301                                         1, callback=None)
 302
 303     # Returns newly allocated subimage convolution with Sobel 3x3 kernel
 304     res = img.filters.ConvolutionExAlloc(50, 50, 100, 100,
 305                                          [[ 1, 0, -1],
 306                                           [ 2, 0, -2],
 307                                           [ 1, 0, -1]], 1, callback=None)
 308 -------------------------------------------------------------------------------
 309
 310 Bilinear convolution. The kernel is specified as two dimensional array of
 311 numbers, the second number is divisor of the kernel weighed sum of pixels.
 312
 313 ////
 314 Generated in filters.txt
 315 ////
 316
 317 The pixel value is computed as:
 318 image:discrete_linear_convolution_alg1.png["Bilinear Convolution"]
 319
 320 Which is the same as:
 321 image:discrete_linear_convolution_alg2.png["Bilinear Convolution"]
 322
 323 NOTE: The number of kernel rows and columns is expected to be odd number.
 324
 325 TIP: See link:example_py_convolution.html[convolution example].
 326
 327
 328 include::images/convolution/images.txt[]
 329
 330 Blurs
 331 ~~~~~
 332
 333 [source,python]
 334 -------------------------------------------------------------------------------
 335 import gfxprim.core as core
 336 import gfxprim.filters as filters
 337
 338     # Does in-place Gaussian blur, the image is modified in-place
 339     filters.GaussianBlur(img, img, x_sigma, y_sigma, callback=None)
 340
 341     # Returns newly alocated blurred image
 342     res = img.filters.GaussianBlur(x_sigma, y_sigma, callback=None)
 343
 344 -------------------------------------------------------------------------------
 345
 346 Gaussian blur (low pass) filters implemented as bilinear separable
 347 convolution.
 348
 349 TIP: See link:example_py_blur.html[blur example].
 350
 351 include::images/blur/images.txt[]
 352
 353 Ditherings
 354 ~~~~~~~~~~
 355
 356 [source,python]
 357 -------------------------------------------------------------------------------
 358 import gfxprim.core as core
 359 import gfxprim.filters as filters
 360
 361     # Returns img dithered to 1-bit Grayscale as a new image
 362     res = img.filters.FloydSteinbergAlloc(core.C.PIXEL_G1, callback=None)
 363
 364     # Returns img dithered to 1-bit Grayscale as a new image
 365     res = img.filters.HilbertPeanoAlloc(core.C.PIXEL_G1, callback=None)
 366
 367 -------------------------------------------------------------------------------
 368
 369 Returns new 1-bit Grayscale image which is result from Floyd-Steinberg,
 370 Hilbert-Peano dithering.
 371
 372 The first parameter is pixel type, the second is progress callback.
 373
 374 For more information and example images see link:filters_dithering.html[C
 375 dithering documentation].
 376
 377 TIP: See link:example_py_dithering.html[dithering example].
 378
 379 include::images/convert/images.txt[]
 380 include::images/floyd_steinberg/images.txt[]
 381 include::images/hilbert_peano/images.txt[]
 382
 383 Median
 384 ~~~~~~
 385
 386 [source,python]
 387 -------------------------------------------------------------------------------
 388 import gfxprim.core as core
 389 import gfxprim.filters as filters
 390
 391     # Returns result of median filter over a rectangle of a side 2 * 3 + 1 pixels
 392     res = img.filters.MedianAlloc(3, 3, callback=None)
 393
 394     # Applies median filter in-place
 395     img.filters.Median(3, 3, callback=None)
 396 -------------------------------------------------------------------------------
 397
 398 Constant time median filter (the computational complexity is independent of
 399 radius size).
 400
 401 The parameters are radius values for x and y. The algorithm uses x
 402 respectively y pixel neighbors from each side so the result is median of
 403 rectangle of +2 * x + 1+ x +2 * y + 1+ pixels.
 404
 405 include::images/median/images.txt[]
 406
 407 Resize
 408 ~~~~~~
 409
 410 [source,python]
 411 -------------------------------------------------------------------------------
 412 import gfxprim.core as core
 413 import gfxprim.filters as filters
 414
 415     # Nearest neighbour resize, fastest but lowest quality
 416     res = img.ResizeNNAlloc(100, 100, callback=None)
 417
 418     # Fast and good quality with low pass on downscaling
 419     res = img.ResizeLinearLFIntAlloc(100, 100, callback=None)
 420
 421     # Cubic interpolation, needs low pass (blur) applied before downscaling
 422     res = img.ResizeCubicIntAlloc(100, 100, callback=None)
 423
 424     # All of the above, TYPE is numeric enum
 425     res = img.ResizeAlloc(100, 100, TYPE, callback=None)
 426
 427 -------------------------------------------------------------------------------
 428
 429 Functions to resize (resample) image.
 430
 431 TIP: See link:example_py_resize.html[resize example].