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