- Access pixel values and modify them
- Access image properties
-- Setting Region of Interest (ROI)
-- Splitting and Merging images
+- Set a Region of Interest (ROI)
+- Split and merge images
-Almost all the operations in this section is mainly related to Numpy rather than OpenCV. A good
+Almost all the operations in this section are mainly related to Numpy rather than OpenCV. A good
knowledge of Numpy is required to write better optimized code with OpenCV.
-*( Examples will be shown in Python terminal since most of them are just single line codes )*
+*( Examples will be shown in a Python terminal, since most of them are just single lines of code )*
Accessing and Modifying pixel values
------------------------------------
[255 255 255]
@endcode
-**warning**
+**Warning**
-Numpy is a optimized library for fast array calculations. So simply accessing each and every pixel
-values and modifying it will be very slow and it is discouraged.
+Numpy is an optimized library for fast array calculations. So simply accessing each and every pixel
+value and modifying it will be very slow and it is discouraged.
@note The above method is normally used for selecting a region of an array, say the first 5 rows
and last 3 columns. For individual pixel access, the Numpy array methods, array.item() and
-array.itemset() are considered better, however they always return a scalar. If you want to access
-all B,G,R values, you need to call array.item() separately for all.
+array.itemset() are considered better. They always return a scalar, however, so if you want to access
+all the B,G,R values, you will need to call array.item() separately for each value.
Better pixel accessing and editing method :
@code{.py}
Accessing Image Properties
--------------------------
-Image properties include number of rows, columns and channels, type of image data, number of pixels
-etc.
+Image properties include number of rows, columns, and channels; type of image data; number of pixels; etc.
-The shape of an image is accessed by img.shape. It returns a tuple of number of rows, columns, and channels
-(if image is color):
+The shape of an image is accessed by img.shape. It returns a tuple of the number of rows, columns, and channels
+(if the image is color):
@code{.py}
>>> print( img.shape )
(342, 548, 3)
@endcode
@note img.dtype is very important while debugging because a large number of errors in OpenCV-Python
-code is caused by invalid datatype.
+code are caused by invalid datatype.
Image ROI
---------
-Sometimes, you will have to play with certain region of images. For eye detection in images, first
-face detection is done all over the image. When a face is obtained, we select the face region alone
+Sometimes, you will have to play with certain regions of images. For eye detection in images, first
+face detection is done over the entire image. When a face is obtained, we select the face region alone
and search for eyes inside it instead of searching the whole image. It improves accuracy (because eyes
are always on faces :D ) and performance (because we search in a small area).
Splitting and Merging Image Channels
------------------------------------
-Sometimes you will need to work separately on B,G,R channels of image. In this case, you need
-to split the BGR images to single channels. In other cases, you may need to join these individual
-channels to a BGR image. You can do it simply by:
+Sometimes you will need to work separately on the B,G,R channels of an image. In this case, you need
+to split the BGR image into single channels. In other cases, you may need to join these individual
+channels to create a BGR image. You can do this simply by:
@code{.py}
>>> b,g,r = cv.split(img)
>>> img = cv.merge((b,g,r))
@code
>>> b = img[:,:,0]
@endcode
-Suppose you want to set all the red pixels to zero, you do not need to split the channels first.
+Suppose you want to set all the red pixels to zero - you do not need to split the channels first.
Numpy indexing is faster:
@code{.py}
>>> img[:,:,2] = 0
**Warning**
-cv.split() is a costly operation (in terms of time). So do it only if you need it. Otherwise go
+cv.split() is a costly operation (in terms of time). So use it only if necessary. Otherwise go
for Numpy indexing.
Making Borders for Images (Padding)
-----------------------------------
-If you want to create a border around the image, something like a photo frame, you can use
+If you want to create a border around an image, something like a photo frame, you can use
**cv.copyMakeBorder()**. But it has more applications for convolution operation, zero
padding etc. This function takes following arguments:
Goal
----
-- Learn several arithmetic operations on images like addition, subtraction, bitwise operations
- etc.
-- You will learn these functions : **cv.add()**, **cv.addWeighted()** etc.
+- Learn several arithmetic operations on images, like addition, subtraction, bitwise operations, and etc.
+- Learn these functions: **cv.add()**, **cv.addWeighted()**, etc.
Image Addition
--------------
-You can add two images by OpenCV function, cv.add() or simply by numpy operation,
-res = img1 + img2. Both images should be of same depth and type, or second image can just be a
+You can add two images with the OpenCV function, cv.add(), or simply by the numpy operation
+res = img1 + img2. Both images should be of same depth and type, or the second image can just be a
scalar value.
@note There is a difference between OpenCV addition and Numpy addition. OpenCV addition is a
saturated operation while Numpy addition is a modulo operation.
-For example, consider below sample:
+For example, consider the below sample:
@code{.py}
>>> x = np.uint8([250])
>>> y = np.uint8([10])
>>> print( x+y ) # 250+10 = 260 % 256 = 4
[4]
@endcode
-It will be more visible when you add two images. OpenCV function will provide a better result. So
-always better stick to OpenCV functions.
+This will be more visible when you add two images. Stick with OpenCV functions, because they will provide a better result.
Image Blending
--------------
-This is also image addition, but different weights are given to images so that it gives a feeling of
+This is also image addition, but different weights are given to images in order to give a feeling of
blending or transparency. Images are added as per the equation below:
\f[g(x) = (1 - \alpha)f_{0}(x) + \alpha f_{1}(x)\f]
By varying \f$\alpha\f$ from \f$0 \rightarrow 1\f$, you can perform a cool transition between one image to
another.
-Here I took two images to blend them together. First image is given a weight of 0.7 and second image
-is given 0.3. cv.addWeighted() applies following equation on the image.
+Here I took two images to blend together. The first image is given a weight of 0.7 and the second image
+is given 0.3. cv.addWeighted() applies the following equation to the image:
\f[dst = \alpha \cdot img1 + \beta \cdot img2 + \gamma\f]
Bitwise Operations
------------------
-This includes bitwise AND, OR, NOT and XOR operations. They will be highly useful while extracting
+This includes the bitwise AND, OR, NOT, and XOR operations. They will be highly useful while extracting
any part of the image (as we will see in coming chapters), defining and working with non-rectangular
-ROI etc. Below we will see an example on how to change a particular region of an image.
+ROI's, and etc. Below we will see an example of how to change a particular region of an image.
-I want to put OpenCV logo above an image. If I add two images, it will change color. If I blend it,
-I get an transparent effect. But I want it to be opaque. If it was a rectangular region, I could use
-ROI as we did in last chapter. But OpenCV logo is a not a rectangular shape. So you can do it with
-bitwise operations as below:
+I want to put the OpenCV logo above an image. If I add two images, it will change the color. If I blend them,
+I get a transparent effect. But I want it to be opaque. If it was a rectangular region, I could use
+ROI as we did in the last chapter. But the OpenCV logo is a not a rectangular shape. So you can do it with
+bitwise operations as shown below:
@code{.py}
# Load two images
img1 = cv.imread('messi5.jpg')
# I want to put logo on top-left corner, So I create a ROI
rows,cols,channels = img2.shape
-roi = img1[0:rows, 0:cols ]
+roi = img1[0:rows, 0:cols]
# Now create a mask of logo and create its inverse mask also
img2gray = cv.cvtColor(img2,cv.COLOR_BGR2GRAY)
Goal
----
-In image processing, since you are dealing with large number of operations per second, it is
-mandatory that your code is not only providing the correct solution, but also in the fastest manner.
-So in this chapter, you will learn
+In image processing, since you are dealing with a large number of operations per second, it is mandatory that your code is not only providing the correct solution, but that it is also providing it in the fastest manner.
+So in this chapter, you will learn:
- To measure the performance of your code.
- Some tips to improve the performance of your code.
-- You will see these functions : **cv.getTickCount**, **cv.getTickFrequency** etc.
+- You will see these functions: **cv.getTickCount**, **cv.getTickFrequency**, etc.
Apart from OpenCV, Python also provides a module **time** which is helpful in measuring the time of
-execution. Another module **profile** helps to get detailed report on the code, like how much time
-each function in the code took, how many times the function was called etc. But, if you are using
+execution. Another module **profile** helps to get a detailed report on the code, like how much time
+each function in the code took, how many times the function was called, etc. But, if you are using
IPython, all these features are integrated in an user-friendly manner. We will see some important
-ones, and for more details, check links in **Additional Resources** section.
+ones, and for more details, check links in the **Additional Resources** section.
Measuring Performance with OpenCV
---------------------------------
-**cv.getTickCount** function returns the number of clock-cycles after a reference event (like the
-moment machine was switched ON) to the moment this function is called. So if you call it before and
-after the function execution, you get number of clock-cycles used to execute a function.
+The **cv.getTickCount** function returns the number of clock-cycles after a reference event (like the
+moment the machine was switched ON) to the moment this function is called. So if you call it before and
+after the function execution, you get the number of clock-cycles used to execute a function.
-**cv.getTickFrequency** function returns the frequency of clock-cycles, or the number of
+The **cv.getTickFrequency** function returns the frequency of clock-cycles, or the number of
clock-cycles per second. So to find the time of execution in seconds, you can do following:
@code{.py}
e1 = cv.getTickCount()
e2 = cv.getTickCount()
time = (e2 - e1)/ cv.getTickFrequency()
@endcode
-We will demonstrate with following example. Following example apply median filtering with a kernel
-of odd size ranging from 5 to 49. (Don't worry about what will the result look like, that is not our
+We will demonstrate with following example. The following example applies median filtering with kernels
+of odd sizes ranging from 5 to 49. (Don't worry about what the result will look like - that is not our
goal):
@code{.py}
img1 = cv.imread('messi5.jpg')
# Result I got is 0.521107655 seconds
@endcode
-@note You can do the same with time module. Instead of cv.getTickCount, use time.time() function.
-Then take the difference of two times.
+@note You can do the same thing with the time module. Instead of cv.getTickCount, use the time.time() function.
+Then take the difference of the two times.
Default Optimization in OpenCV
------------------------------
-Many of the OpenCV functions are optimized using SSE2, AVX etc. It contains unoptimized code also.
+Many of the OpenCV functions are optimized using SSE2, AVX, etc. It contains the unoptimized code also.
So if our system support these features, we should exploit them (almost all modern day processors
support them). It is enabled by default while compiling. So OpenCV runs the optimized code if it is
-enabled, else it runs the unoptimized code. You can use **cv.useOptimized()** to check if it is
+enabled, otherwise it runs the unoptimized code. You can use **cv.useOptimized()** to check if it is
enabled/disabled and **cv.setUseOptimized()** to enable/disable it. Let's see a simple example.
@code{.py}
# check if optimization is enabled
In [9]: %timeit res = cv.medianBlur(img,49)
10 loops, best of 3: 64.1 ms per loop
@endcode
-See, optimized median filtering is \~2x faster than unoptimized version. If you check its source,
-you can see median filtering is SIMD optimized. So you can use this to enable optimization at the
+As you can see, optimized median filtering is \~2x faster than the unoptimized version. If you check its source,
+you can see that median filtering is SIMD optimized. So you can use this to enable optimization at the
top of your code (remember it is enabled by default).
Measuring Performance in IPython
Sometimes you may need to compare the performance of two similar operations. IPython gives you a
magic command %timeit to perform this. It runs the code several times to get more accurate results.
-Once again, they are suitable to measure single line codes.
+Once again, it is suitable to measuring single lines of code.
-For example, do you know which of the following addition operation is better, x = 5; y = x\*\*2,
-x = 5; y = x\*x, x = np.uint8([5]); y = x\*x or y = np.square(x) ? We will find it with %timeit in
+For example, do you know which of the following addition operations is better, x = 5; y = x\*\*2,
+x = 5; y = x\*x, x = np.uint8([5]); y = x\*x, or y = np.square(x)? We will find out with %timeit in the
IPython shell.
@code{.py}
In [10]: x = 5
1000000 loops, best of 3: 1.16 us per loop
@endcode
You can see that, x = 5 ; y = x\*x is fastest and it is around 20x faster compared to Numpy. If you
-consider the array creation also, it may reach upto 100x faster. Cool, right? *(Numpy devs are
+consider the array creation also, it may reach up to 100x faster. Cool, right? *(Numpy devs are
working on this issue)*
@note Python scalar operations are faster than Numpy scalar operations. So for operations including
-one or two elements, Python scalar is better than Numpy arrays. Numpy takes advantage when size of
-array is a little bit bigger.
+one or two elements, Python scalar is better than Numpy arrays. Numpy has the advantage when the size of
+the array is a little bit bigger.
We will try one more example. This time, we will compare the performance of **cv.countNonZero()**
-and **np.count_nonzero()** for same image.
+and **np.count_nonzero()** for the same image.
@code{.py}
In [35]: %timeit z = cv.countNonZero(img)
In [36]: %timeit z = np.count_nonzero(img)
1000 loops, best of 3: 370 us per loop
@endcode
-See, OpenCV function is nearly 25x faster than Numpy function.
+See, the OpenCV function is nearly 25x faster than the Numpy function.
@note Normally, OpenCV functions are faster than Numpy functions. So for same operation, OpenCV
functions are preferred. But, there can be exceptions, especially when Numpy works with views
More IPython magic commands
---------------------------
-There are several other magic commands to measure the performance, profiling, line profiling, memory
-measurement etc. They all are well documented. So only links to those docs are provided here.
+There are several other magic commands to measure performance, profiling, line profiling, memory
+measurement, and etc. They all are well documented. So only links to those docs are provided here.
Interested readers are recommended to try them out.
Performance Optimization Techniques
There are several techniques and coding methods to exploit maximum performance of Python and Numpy.
Only relevant ones are noted here and links are given to important sources. The main thing to be
-noted here is that, first try to implement the algorithm in a simple manner. Once it is working,
-profile it, find the bottlenecks and optimize them.
+noted here is, first try to implement the algorithm in a simple manner. Once it is working,
+profile it, find the bottlenecks, and optimize them.
--# Avoid using loops in Python as far as possible, especially double/triple loops etc. They are
+-# Avoid using loops in Python as much as possible, especially double/triple loops etc. They are
inherently slow.
-2. Vectorize the algorithm/code to the maximum possible extent because Numpy and OpenCV are
+2. Vectorize the algorithm/code to the maximum extent possible, because Numpy and OpenCV are
optimized for vector operations.
3. Exploit the cache coherence.
-4. Never make copies of array unless it is needed. Try to use views instead. Array copying is a
+4. Never make copies of an array unless it is necessary. Try to use views instead. Array copying is a
costly operation.
-Even after doing all these operations, if your code is still slow, or use of large loops are
-inevitable, use additional libraries like Cython to make it faster.
+If your code is still slow after doing all of these operations, or if the use of large loops is inevitable, use additional libraries like Cython to make it faster.
Additional Resources
--------------------
projects / platform / upstream / opencv.git / commitdiff