0
# Computational Photography
1

2
Computational photography techniques in OpenCV combine image processing algorithms with computational methods to enhance, restore, and manipulate images in sophisticated ways. This module provides tools for inpainting damaged regions, denoising images, seamless cloning, applying artistic effects, and working with High Dynamic Range (HDR) imaging.
3

4
## Capabilities
5

6
### Inpainting
7

8
Image inpainting restores damaged or missing regions of an image using information from surrounding areas.
9

10
```python { .api }
11
cv2.inpaint(src, inpaintMask, inpaintRadius, flags, dst=None) -> dst
12
```
13

14
Restores the selected region in an image using the region neighborhood.
15

16
**Parameters:**
17
- `src` - Input 8-bit, 16-bit unsigned or 32-bit float 1-channel or 8-bit 3-channel image
18
- `inpaintMask` - Inpainting mask, 8-bit 1-channel image. Non-zero pixels indicate areas to be inpainted
19
- `inpaintRadius` - Radius of circular neighborhood of each point inpainted
20
- `flags` - Inpainting method
21
- `dst` - Output image with the same size and type as src
22

23
**Returns:**
24
- `dst` - Output inpainted image
25

26
**Inpainting Methods:**
27

28
```python { .api }
29
cv2.INPAINT_NS       # Navier-Stokes based method
30
cv2.INPAINT_TELEA    # Fast Marching Method by Telea
31
```
32

33
### Denoising
34

35
Non-local means denoising algorithms remove noise while preserving image details and edges.
36

37
```python { .api }
38
cv2.fastNlMeansDenoising(src, h=None, templateWindowSize=None,
39
                         searchWindowSize=None, dst=None) -> dst
40
```
41

42
Performs image denoising using Non-local Means Denoising algorithm.
43

44
**Parameters:**
45
- `src` - Input 8-bit 1-channel, 2-channel, 3-channel or 4-channel image
46
- `h` - Filter strength. Higher h value removes more noise but also removes image details (10 is recommended)
47
- `templateWindowSize` - Size in pixels of template patch (should be odd, default 7)
48
- `searchWindowSize` - Size in pixels of area used to compute weighted average (should be odd, default 21)
49
- `dst` - Output image with the same size and type as src
50

51
**Returns:**
52
- `dst` - Output denoised image
53

54
```python { .api }
55
cv2.fastNlMeansDenoisingColored(src, h=None, hColor=None,
56
                                templateWindowSize=None,
57
                                searchWindowSize=None, dst=None) -> dst
58
```
59

60
Modification of fastNlMeansDenoising function for colored images.
61

62
**Parameters:**
63
- `src` - Input 8-bit 3-channel image
64
- `h` - Filter strength for luminance component (10 is recommended)
65
- `hColor` - Filter strength for color components (10 is recommended)
66
- `templateWindowSize` - Size in pixels of template patch (should be odd, default 7)
67
- `searchWindowSize` - Size in pixels of area used to compute weighted average (should be odd, default 21)
68
- `dst` - Output image with the same size and type as src
69

70
**Returns:**
71
- `dst` - Output denoised colored image
72

73
```python { .api }
74
cv2.fastNlMeansDenoisingMulti(srcImgs, imgToDenoiseIndex,
75
                              temporalWindowSize, h=None,
76
                              templateWindowSize=None,
77
                              searchWindowSize=None, dst=None) -> dst
78
```
79

80
Modification of fastNlMeansDenoising function for image sequences where consecutive frames have been captured in a short period of time.
81

82
**Parameters:**
83
- `srcImgs` - Input 8-bit 1-channel, 2-channel, 3-channel or 4-channel images sequence
84
- `imgToDenoiseIndex` - Target image to denoise index in srcImgs sequence
85
- `temporalWindowSize` - Number of surrounding images to use for denoising (should be odd)
86
- `h` - Filter strength (10 is recommended)
87
- `templateWindowSize` - Size in pixels of template patch (should be odd, default 7)
88
- `searchWindowSize` - Size in pixels of area used to compute weighted average (should be odd, default 21)
89
- `dst` - Output image with the same size and type as srcImgs images
90

91
**Returns:**
92
- `dst` - Output denoised image
93

94
```python { .api }
95
cv2.fastNlMeansDenoisingColoredMulti(srcImgs, imgToDenoiseIndex,
96
                                     temporalWindowSize, h=None,
97
                                     hColor=None, templateWindowSize=None,
98
                                     searchWindowSize=None, dst=None) -> dst
99
```
100

101
Modification of fastNlMeansDenoisingMulti function for colored image sequences.
102

103
**Parameters:**
104
- `srcImgs` - Input 8-bit 3-channel images sequence
105
- `imgToDenoiseIndex` - Target image to denoise index in srcImgs sequence
106
- `temporalWindowSize` - Number of surrounding images to use for denoising (should be odd)
107
- `h` - Filter strength for luminance component (10 is recommended)
108
- `hColor` - Filter strength for color components (10 is recommended)
109
- `templateWindowSize` - Size in pixels of template patch (should be odd, default 7)
110
- `searchWindowSize` - Size in pixels of area used to compute weighted average (should be odd, default 21)
111
- `dst` - Output image with the same size and type as srcImgs images
112

113
**Returns:**
114
- `dst` - Output denoised colored image
115

116
```python { .api }
117
cv2.denoise_TVL1(observations, result, lambda_=None, niters=None) -> result
118
```
119

120
Primal-dual algorithm for Total Variation (TV) L1 denoising.
121

122
**Parameters:**
123
- `observations` - Noisy observations (grayscale or color images)
124
- `result` - Output denoised image
125
- `lambda_` - Regularization parameter (default 1.0)
126
- `niters` - Number of iterations (default 30)
127

128
**Returns:**
129
- `result` - Denoised image
130

131
### Seamless Cloning
132

133
Seamless cloning techniques blend source images into destination images without visible seams.
134

135
```python { .api }
136
cv2.seamlessClone(src, dst, mask, p, flags, blend=None) -> blend
137
```
138

139
Image editing tasks concern either global changes (color/intensity corrections, filters, deformations) or local changes concerned to a selection. Seamless cloning blends the source image into the destination image.
140

141
**Parameters:**
142
- `src` - Input 8-bit 3-channel image
143
- `dst` - Input 8-bit 3-channel image
144
- `mask` - Input 8-bit 1 or 3-channel image
145
- `p` - Point in dst image where object is placed (center of the cloned region)
146
- `flags` - Cloning method
147
- `blend` - Output image with the same size and type as dst
148

149
**Returns:**
150
- `blend` - Output blended image
151

152
**Seamless Clone Flags:**
153

154
```python { .api }
155
cv2.NORMAL_CLONE          # The power of the method is fully preserved
156
cv2.MIXED_CLONE           # Mixing the gradients from both images for best results
157
cv2.MONOCHROME_TRANSFER   # Monochrome transfer
158
```
159

160
```python { .api }
161
cv2.colorChange(src, mask, red_mul=None, green_mul=None,
162
                blue_mul=None, dst=None) -> dst
163
```
164

165
Given an original color image, two differently colored versions of this image can be mixed seamlessly.
166

167
**Parameters:**
168
- `src` - Input 8-bit 3-channel image
169
- `mask` - Input 8-bit 1 or 3-channel image
170
- `red_mul` - R-channel multiply factor (default 1.0)
171
- `green_mul` - G-channel multiply factor (default 1.0)
172
- `blue_mul` - B-channel multiply factor (default 1.0)
173
- `dst` - Output image with the same size and type as src
174

175
**Returns:**
176
- `dst` - Output color changed image
177

178
```python { .api }
179
cv2.illuminationChange(src, mask, alpha=None, beta=None, dst=None) -> dst
180
```
181

182
Applying an appropriate non-linear transformation to the gradient field inside the selection and then integrating back with a Poisson solver, modifies locally the apparent illumination of an image.
183

184
**Parameters:**
185
- `src` - Input 8-bit 3-channel image
186
- `mask` - Input 8-bit 1 or 3-channel image
187
- `alpha` - Value ranges between 0-2 (default 0.2)
188
- `beta` - Value ranges between 0-2 (default 0.4)
189
- `dst` - Output image with the same size and type as src
190

191
**Returns:**
192
- `dst` - Output illumination changed image
193

194
```python { .api }
195
cv2.textureFlattening(src, mask, low_threshold=None,
196
                      high_threshold=None, kernel_size=None,
197
                      dst=None) -> dst
198
```
199

200
By retaining only the gradients at edge locations, before integrating with the Poisson solver, one washes out the texture of the selected region, giving its contents a flat aspect.
201

202
**Parameters:**
203
- `src` - Input 8-bit 3-channel image
204
- `mask` - Input 8-bit 1 or 3-channel image
205
- `low_threshold` - Range from 0 to 100 (default 30)
206
- `high_threshold` - Value > 100 (default 45)
207
- `kernel_size` - The size of the Sobel kernel (default 3)
208
- `dst` - Output image with the same size and type as src
209

210
**Returns:**
211
- `dst` - Output texture flattened image
212

213
### Edge-Preserving Filters
214

215
Edge-preserving filters smooth images while maintaining sharp edges.
216

217
```python { .api }
218
cv2.edgePreservingFilter(src, flags=None, sigma_s=None,
219
                         sigma_r=None, dst=None) -> dst
220
```
221

222
Filtering is the fundamental operation in image and video processing. Edge-preserving smoothing filters are used in many different applications.
223

224
**Parameters:**
225
- `src` - Input 8-bit 3-channel image
226
- `flags` - Edge preserving filter type
227
- `sigma_s` - Range between 0 to 200 (default 60)
228
- `sigma_r` - Range between 0 to 1 (default 0.4)
229
- `dst` - Output image with the same size and type as src
230

231
**Returns:**
232
- `dst` - Output edge-preserving filtered image
233

234
**Edge-Preserving Filter Flags:**
235

236
```python { .api }
237
cv2.RECURS_FILTER     # Recursive filter
238
cv2.NORMCONV_FILTER   # Normalized convolution filter
239
```
240

241
```python { .api }
242
cv2.detailEnhance(src, sigma_s=None, sigma_r=None, dst=None) -> dst
243
```
244

245
This filter enhances the details of a particular image.
246

247
**Parameters:**
248
- `src` - Input 8-bit 3-channel image
249
- `sigma_s` - Range between 0 to 200 (default 10)
250
- `sigma_r` - Range between 0 to 1 (default 0.15)
251
- `dst` - Output image with the same size and type as src
252

253
**Returns:**
254
- `dst` - Output detail enhanced image
255

256
### Stylization Effects
257

258
Non-photorealistic rendering techniques that create artistic effects.
259

260
```python { .api }
261
cv2.pencilSketch(src, sigma_s=None, sigma_r=None,
262
                 shade_factor=None, dst1=None, dst2=None) -> dst1, dst2
263
```
264

265
Pencil-like non-photorealistic line drawing.
266

267
**Parameters:**
268
- `src` - Input 8-bit 3-channel image
269
- `sigma_s` - Range between 0 to 200 (default 60)
270
- `sigma_r` - Range between 0 to 1 (default 0.07)
271
- `shade_factor` - Range between 0 to 0.1 (default 0.02)
272
- `dst1` - Output 8-bit 1-channel image (grayscale sketch)
273
- `dst2` - Output 8-bit 3-channel image (colored sketch)
274

275
**Returns:**
276
- `dst1` - Grayscale pencil sketch
277
- `dst2` - Colored pencil sketch
278

279
```python { .api }
280
cv2.stylization(src, sigma_s=None, sigma_r=None, dst=None) -> dst
281
```
282

283
Stylization aims to produce digital imagery with a wide variety of effects not focused on photorealism. Edge-aware filters are ideal for stylization, as they abstract regions of low contrast while preserving high-contrast features.
284

285
**Parameters:**
286
- `src` - Input 8-bit 3-channel image
287
- `sigma_s` - Range between 0 to 200 (default 60)
288
- `sigma_r` - Range between 0 to 1 (default 0.45)
289
- `dst` - Output image with the same size and type as src
290

291
**Returns:**
292
- `dst` - Output stylized image
293

294
### HDR Imaging
295

296
High Dynamic Range (HDR) imaging techniques capture and merge multiple exposures to create images with greater dynamic range.
297

298
```python { .api }
299
cv2.createAlignMTB(max_bits=None, exclude_range=None, cut=None) -> retval
300
```
301

302
Creates AlignMTB object for HDR image alignment using median threshold bitmap.
303

304
**Parameters:**
305
- `max_bits` - Logarithm to base 2 of maximal shift in each dimension (default 6)
306
- `exclude_range` - Range for exclusion of pixels with big contrast (default 4)
307
- `cut` - If true, cut images, otherwise fill the new regions with zeros (default True)
308

309
**Returns:**
310
- `retval` - AlignMTB object
311

312
```python { .api }
313
cv2.createCalibrateDebevec(samples=None, lambda_=None,
314
                           random=None) -> retval
315
```
316

317
Creates CalibrateDebevec object for camera response calibration.
318

319
**Parameters:**
320
- `samples` - Number of pixel locations to use (default 70)
321
- `lambda_` - Smoothness term weight (default 10.0)
322
- `random` - Use random sample locations (default False)
323

324
**Returns:**
325
- `retval` - CalibrateDebevec object
326

327
```python { .api }
328
cv2.createCalibrateRobertson(max_iter=None, threshold=None) -> retval
329
```
330

331
Creates CalibrateRobertson object for camera response calibration.
332

333
**Parameters:**
334
- `max_iter` - Maximal number of Gauss-Seidel solver iterations (default 30)
335
- `threshold` - Target difference between results of two successive steps of the minimization (default 0.01)
336

337
**Returns:**
338
- `retval` - CalibrateRobertson object
339

340
```python { .api }
341
cv2.createMergeDebevec() -> retval
342
```
343

344
Creates MergeDebevec object for merging exposures into HDR image.
345

346
**Returns:**
347
- `retval` - MergeDebevec object
348

349
```python { .api }
350
cv2.createMergeMertens(contrast_weight=None, saturation_weight=None,
351
                       exposure_weight=None) -> retval
352
```
353

354
Creates MergeMertens object for exposure fusion (without HDR conversion).
355

356
**Parameters:**
357
- `contrast_weight` - Contrast measure weight (default 1.0)
358
- `saturation_weight` - Saturation measure weight (default 1.0)
359
- `exposure_weight` - Well-exposedness measure weight (default 0.0)
360

361
**Returns:**
362
- `retval` - MergeMertens object
363

364
```python { .api }
365
cv2.createMergeRobertson() -> retval
366
```
367

368
Creates MergeRobertson object for merging exposures into HDR image.
369

370
**Returns:**
371
- `retval` - MergeRobertson object
372

373
### Tone Mapping
374

375
Tone mapping operators convert HDR images to displayable low dynamic range (LDR) images.
376

377
```python { .api }
378
cv2.createTonemapDrago(gamma=None, saturation=None,
379
                       bias=None) -> retval
380
```
381

382
Creates TonemapDrago object for adaptive logarithmic mapping.
383

384
**Parameters:**
385
- `gamma` - Gamma value for gamma correction (default 1.0)
386
- `saturation` - Saturation enhancement value (default 1.0)
387
- `bias` - Value for bias function in [0, 1] range (default 0.85)
388

389
**Returns:**
390
- `retval` - TonemapDrago object
391

392
```python { .api }
393
cv2.createTonemapDurand(gamma=None, contrast=None,
394
                        saturation=None, sigma_space=None,
395
                        sigma_color=None) -> retval
396
```
397

398
Creates TonemapDurand object for bilateral filtering based tone mapping.
399

400
**Parameters:**
401
- `gamma` - Gamma value for gamma correction (default 1.0)
402
- `contrast` - Resulting contrast on logarithmic scale (default 4.0)
403
- `saturation` - Saturation enhancement value (default 1.0)
404
- `sigma_space` - Spatial sigma for bilateral filter (default 2.0)
405
- `sigma_color` - Color sigma for bilateral filter (default 2.0)
406

407
**Returns:**
408
- `retval` - TonemapDurand object
409

410
```python { .api }
411
cv2.createTonemapMantiuk(gamma=None, scale=None,
412
                         saturation=None) -> retval
413
```
414

415
Creates TonemapMantiuk object for gradient domain high dynamic range compression.
416

417
**Parameters:**
418
- `gamma` - Gamma value for gamma correction (default 1.0)
419
- `scale` - Contrast scale factor (default 0.7)
420
- `saturation` - Saturation enhancement value (default 1.0)
421

422
**Returns:**
423
- `retval` - TonemapMantiuk object
424

425
```python { .api }
426
cv2.createTonemapReinhard(gamma=None, intensity=None,
427
                          light_adapt=None, color_adapt=None) -> retval
428
```
429

430
Creates TonemapReinhard object for global tone mapping operator.
431

432
**Parameters:**
433
- `gamma` - Gamma value for gamma correction (default 1.0)
434
- `intensity` - Result intensity in [-8, 8] range (default 0.0)
435
- `light_adapt` - Light adaptation in [0, 1] range (default 1.0)
436
- `color_adapt` - Chromatic adaptation in [0, 1] range (default 0.0)
437

438
**Returns:**
439
- `retval` - TonemapReinhard object
440

441
## Additional Functions
442

443
```python { .api }
444
cv2.decolor(src, grayscale=None, color_boost=None) -> grayscale, color_boost
445
```
446

447
Transforms a color image to a grayscale image while preserving contrast and enhancing details.
448

449
**Parameters:**
450
- `src` - Input 8-bit 3-channel image
451
- `grayscale` - Output 8-bit 1-channel grayscale image
452
- `color_boost` - Output 8-bit 3-channel contrast-enhanced color image
453

454
**Returns:**
455
- `grayscale` - Grayscale output with enhanced contrast
456
- `color_boost` - Contrast-enhanced color output
457