Extract imgcodecs module from highgui

2026-07-30 15:53:03 +04:00 · 2014-07-04 18:48:15 +04:00
parent 964b260937
commit 4286f60387
204 changed files with 968 additions and 439 deletions
@@ -25,7 +25,7 @@ Here's a sample usage of :operationsonarrays:`dft() <dft>` :
   :language: cpp
   :linenos:
   :tab-width: 4
-   :lines: 1-3, 5, 19-20, 23-78
+   :lines: 1-4, 6, 20-21, 24-79

 Explanation
 ===========
@@ -45,7 +45,7 @@ The final argument is optional. If given the image will be loaded in gray scale
 .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp
   :language: cpp
   :tab-width: 4
-   :lines: 48-60
+   :lines: 49-61

 Here we first use the C++ *stringstream* class to convert the third command line argument from text to an integer format. Then we use a simple look and the upper formula to calculate the lookup table. No OpenCV specific stuff here.

@@ -99,7 +99,7 @@ When it comes to performance you cannot beat the classic C style operator[] (poi
 .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp
   :language: cpp
   :tab-width: 4
-   :lines: 125-152
+   :lines: 126-153

 Here we basically just acquire a pointer to the start of each row and go through it until it ends. In the special case that the matrix is stored in a continues manner we only need to request the pointer a single time and go all the way to the end. We need to look out for color images: we have three channels so we need to pass through three times more items in each row.

@@ -122,7 +122,7 @@ In case of the efficient way making sure that you pass through the right amount
 .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp
   :language: cpp
   :tab-width: 4
-   :lines: 154-182
+   :lines: 155-183

 In case of color images we have three uchar items per column. This may be considered a short vector of uchar items, that has been baptized in OpenCV with the *Vec3b* name. To access the n-th sub column we use simple operator[] access. It's important to remember that OpenCV iterators go through the columns and automatically skip to the next row. Therefore in case of color images if you use a simple *uchar* iterator you'll be able to access only the blue channel values.

@@ -134,7 +134,7 @@ The final method isn't recommended for scanning. It was made to acquire or modif
 .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp
   :language: cpp
   :tab-width: 4
-   :lines: 184-216
+   :lines: 185-217

 The functions takes your input type and coordinates and calculates on the fly the address of the queried item. Then returns a reference to that. This may be a constant when you *get* the value and non-constant when you *set* the value. As a safety step in **debug mode only*** there is performed a check that your input coordinates are valid and does exist. If this isn't the case you'll get a nice output message of this on the standard error output stream. Compared to the efficient way in release mode the only difference in using this is that for every element of the image you'll get a new row pointer for what we use the C operator[] to acquire the column element.

@@ -148,14 +148,14 @@ This is a bonus method of achieving lookup table modification in an image. Becau
 .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp
   :language: cpp
   :tab-width: 4
-   :lines: 107-110
+   :lines: 108-111

 Finally call the function (I is our input image and J the output one):

 .. literalinclude:: ../../../../samples/cpp/tutorial_code/core/how_to_scan_images/how_to_scan_images.cpp
   :language: cpp
   :tab-width: 4
-   :lines: 115
+   :lines: 116

 Performance Difference
 ======================
@@ -77,7 +77,7 @@ Now that you have the basics done :download:`here's <../../../../samples/cpp/tut
   :language: cpp
   :linenos:
   :tab-width: 4
-   :lines: 1-9, 22-25, 27-44
+   :lines: 1-10, 23-26, 29-46

 Here you can observe that with the new structure we have no pointer problems, although it is possible to use the old functions and in the end just transform the result to a *Mat* object.

@@ -85,7 +85,7 @@ Here you can observe that with the new structure we have no pointer problems, al
   :language: cpp
   :linenos:
   :tab-width: 4
-   :lines: 46-51
+   :lines: 48-53

 Because, we want to mess around with the images luma component we first convert from the default RGB to the YUV color space and then split the result up into separate planes. Here the program splits: in the first example it processes each plane using one of the three major image scanning algorithms in OpenCV (C [] operator, iterator, individual element access). In a second variant we add to the image some Gaussian noise and then mix together the channels according to some formula.

@@ -95,7 +95,7 @@ The scanning version looks like:
   :language: cpp
   :linenos:
   :tab-width: 4
-   :lines: 55-75
+   :lines: 57-77

 Here you can observe that we may go through all the pixels of an image in three fashions: an iterator, a C pointer and an individual element access style. You can read a more in-depth description of these in the :ref:`howToScanImagesOpenCV` tutorial. Converting from the old function names is easy. Just remove the cv prefix and use the new *Mat* data structure. Here's an example of this by using the weighted addition function:

@@ -103,7 +103,7 @@ Here you can observe that we may go through all the pixels of an image in three
   :language: cpp
   :linenos:
   :tab-width: 4
-   :lines: 79-112
+   :lines: 81-113

 As you may observe the *planes* variable is of type *Mat*. However, converting from *Mat* to *IplImage* is easy and made automatically with a simple assignment operator.

@@ -111,7 +111,7 @@ As you may observe the *planes* variable is of type *Mat*. However, converting f
   :language: cpp
   :linenos:
   :tab-width: 4
-   :lines: 115-127
+   :lines: 117-129

 The new *imshow* highgui function accepts both the *Mat* and *IplImage* data structures. Compile and run the program and if the first image below is your input you may get either the first or second as output:

@@ -86,7 +86,7 @@ Each of the building components has their own valid domains. This leads to the d
 Creating a *Mat* object explicitly
 ==================================

-In the :ref:`Load_Save_Image` tutorial you have already learned how to write a matrix to an image file by using the :readwriteimagevideo:`imwrite() <imwrite>` function. However, for debugging purposes it's much more convenient to see the actual values. You can do this using the << operator of *Mat*. Be aware that this only works for two dimensional matrices.
+In the :ref:`Load_Save_Image` tutorial you have already learned how to write a matrix to an image file by using the :readwriteimage:`imwrite() <imwrite>` function. However, for debugging purposes it's much more convenient to see the actual values. You can do this using the << operator of *Mat*. Be aware that this only works for two dimensional matrices.

 Although *Mat* works really well as an image container, it is also a general matrix class. Therefore, it is possible to create and manipulate multidimensional matrices. You can create a Mat object in multiple ways:

@@ -200,7 +200,6 @@ Here you will learn the about the basic building blocks of the library. A must r
                   :height: 90pt
                   :width:  90pt

-  =============== ======================================================
 +
  .. tabularcolumns:: m{100pt} m{300pt}
  .. cssclass:: toctableopencv
@@ -221,8 +220,6 @@ Here you will learn the about the basic building blocks of the library. A must r
                   :width:  90pt
  .. |Author_ElenaG| unicode:: Elena U+0020 Gvozdeva

-  =============== ======================================================
-
 .. raw:: latex

   \pagebreak
@@ -39,28 +39,28 @@ You'll almost always end up using the:
 .. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
   :language: cpp
   :tab-width: 4
-   :lines:  1-3
+   :lines:  1-4

 We also include the *iostream* to facilitate console line output and input. To avoid data structure and function name conflicts with other libraries, OpenCV has its own namespace: *cv*. To avoid the need appending prior each of these the *cv::* keyword you can import the namespace in the whole file by using the lines:

 .. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
   :language: cpp
   :tab-width: 4
-   :lines:  5-6
+   :lines:  6-7

 This is true for the STL library too (used for console I/O). Now, let's analyze the *main* function. We start up assuring that we acquire a valid image name argument from the command line.

 .. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
   :language: cpp
   :tab-width: 4
-   :lines: 10-14
+   :lines: 11-15

 Then create a *Mat* object that will store the data of the loaded image.

 .. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
   :language: cpp
   :tab-width: 4
-   :lines: 16
+   :lines: 17

 Now we call the :imread:`imread <>` function which loads the image name specified by the first argument (*argv[1]*). The second argument specifies the format in what we want the image. This may be:

@@ -73,7 +73,7 @@ Now we call the :imread:`imread <>` function which loads the image name specifie
 .. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
   :language: cpp
   :tab-width: 4
-   :lines: 17
+   :lines: 18

 .. note::

@@ -88,21 +88,21 @@ After checking that the image data was loaded correctly, we want to display our

 .. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
   :language: cpp
-   :lines: 25
+   :lines: 26
   :tab-width: 4

 Finally, to update the content of the OpenCV window with a new image use the :imshow:`imshow <>` function. Specify the OpenCV window name to update and the image to use during this operation:

 .. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
   :language: cpp
-   :lines: 26
+   :lines: 27
   :tab-width: 4

 Because we want our window to be displayed until the user presses a key (otherwise the program would end far too quickly), we use the :wait_key:`waitKey <>` function whose only parameter is just how long should it wait for a user input (measured in milliseconds). Zero means to wait forever.

 .. literalinclude:: ../../../../samples/cpp/tutorial_code/introduction/display_image/display_image.cpp
   :language: cpp
-   :lines: 28
+   :lines: 29
   :tab-width: 4

 Result
@@ -361,16 +361,16 @@ Now here's our recommendation for the structure of the tutorial (although, remem

       # ---- External links for tutorials -----------------
       extlinks = {
-           'hgvideo' : ('http://docs.opencv.org/modules/highgui/doc/reading_and_writing_images_and_video.html#%s', None)
+           'rwimg' : ('http://docs.opencv.org/modules/imgcodecs/doc/reading_and_writing_images.html#%s', None)
           }

-     In short here we defined a new **hgvideo** directive that refers to an external webpage link. Its usage is:
+     In short here we defined a new **rwimg** directive that refers to an external webpage link. Its usage is:

     .. code-block:: rst

-       A sample function of the highgui modules image write and read page is the :hgvideo:`imread() function <imread>`.
+       A sample function of the highgui modules image write and read page is the :rwimg:`imread() function <imread>`.

-     Which turns to: A sample function of the highgui modules image write and read page is the :hgvideo:`imread() function <imread>`. The argument you give between the <> will be put in place of the ``%s`` in the upper definition, and as the link will anchor to the correct function. To find out the anchor of a given function just open up a web page, search for the function and click on it. In the address bar it should appear like: ``http://docs.opencv.org/modules/highgui/doc/reading_and_writing_images_and_video.html#imread`` .  Look here for the name of the directives for each page of the OpenCV reference manual. If none present for one of them feel free to add one for it.
+     Which turns to: A sample function of the highgui modules image write and read page is the :rwimg:`imread() function <imread>`. The argument you give between the <> will be put in place of the ``%s`` in the upper definition, and as the link will anchor to the correct function. To find out the anchor of a given function just open up a web page, search for the function and click on it. In the address bar it should appear like: ``http://docs.opencv.org/modules/highgui/doc/reading_and_writing_images.html#imread`` .  Look here for the name of the directives for each page of the OpenCV reference manual. If none present for one of them feel free to add one for it.

     For formulas you can add LATEX code that will translate in the web pages into images. You do this by using the *math* directive. A usage tip:

@@ -5,7 +5,7 @@ Load, Modify, and Save an Image

 .. note::

-   We assume that by now you know how to load an image using :readwriteimagevideo:`imread <imread>` and to display it in a window (using :user_interface:`imshow <imshow>`). Read the :ref:`Display_Image` tutorial otherwise.
+   We assume that by now you know how to load an image using :readwriteimage:`imread <imread>` and to display it in a window (using :user_interface:`imshow <imshow>`). Read the :ref:`Display_Image` tutorial otherwise.

 Goals
 ======
@@ -14,9 +14,9 @@ In this tutorial you will learn how to:

 .. container:: enumeratevisibleitemswithsquare

-   * Load an image using :readwriteimagevideo:`imread <imread>`
+   * Load an image using :readwriteimage:`imread <imread>`
   * Transform an image from BGR to Grayscale format by using :miscellaneous_transformations:`cvtColor <cvtcolor>`
-   * Save your transformed image in a file on disk (using :readwriteimagevideo:`imwrite <imwrite>`)
+   * Save your transformed image in a file on disk (using :readwriteimage:`imwrite <imwrite>`)

 Code
 ======
@@ -62,7 +62,7 @@ Here it is:
 Explanation
 ============

-#. We begin by loading an image using :readwriteimagevideo:`imread <imread>`, located in the path given by *imageName*. For this example, assume you are loading a RGB image.
+#. We begin by loading an image using :readwriteimage:`imread <imread>`, located in the path given by *imageName*. For this example, assume you are loading a RGB image.

 #. Now we are going to convert our image from BGR to Grayscale format. OpenCV has a really nice function to do this kind of transformations:

@@ -76,9 +76,9 @@ Explanation

      * a source image (*image*)
      * a destination image (*gray_image*), in which we will save the converted image.
-      * an additional parameter that indicates what kind of transformation will be performed. In this case we use **CV_BGR2GRAY** (because of :readwriteimagevideo:`imread <imread>` has BGR default channel order in case of color images).
+      * an additional parameter that indicates what kind of transformation will be performed. In this case we use **CV_BGR2GRAY** (because of :readwriteimage:`imread <imread>` has BGR default channel order in case of color images).

-#. So now we have our new *gray_image* and want to save it on disk (otherwise it will get lost after the program ends). To save it, we will use a function analagous to :readwriteimagevideo:`imread <imread>`: :readwriteimagevideo:`imwrite <imwrite>`
+#. So now we have our new *gray_image* and want to save it on disk (otherwise it will get lost after the program ends). To save it, we will use a function analagous to :readwriteimage:`imread <imread>`: :readwriteimage:`imwrite <imwrite>`

   .. code-block:: cpp

@@ -73,7 +73,7 @@ You may also find the source code and these video file in the :file:`samples/cpp
   :language: cpp
   :linenos:
   :tab-width: 4
-   :lines: 1-11, 22-23, 26-
+   :lines: 1-12, 23-24, 27-

 Explanation
 ===========