Add samples and tutorials

Co-authored-by: CaoMengqing <[email protected]>

Author: hipudding

modules/cannops/CMakeLists.txt

@@ -14,3 +14,4 @@ ocv_include_directories(${CMAKE_SOURCE_DIR}/modules/ts/include)
 
 ocv_add_accuracy_tests(DEPENDS_ON opencv_cannops)
 ocv_add_perf_tests(DEPENDS_ON opencv_cannops)
+ocv_add_samples(opencv_cannops)

modules/cannops/include/opencv2/cann_private.hpp

@@ -31,4 +31,4 @@ double threshold(AscendMat& src, AscendMat& dst, double thresh, double maxval, i
 } // namespace cann
 } // namespace cv
 
-#endif // OPENCV_CANNOPS_CANN_PRIVATE_HPP
+#endif // OPENCV_CANNOPS_CANN_PRIVATE_HPP

modules/cannops/samples/image_processing.cpp

@@ -0,0 +1,59 @@
+// This file is part of OpenCV project.
+// It is subject to the license terms in the LICENSE file found in the top-level directory
+// of this distribution and at http://opencv.org/license.html.
+
+#include <iostream>
+#include <opencv2/imgcodecs.hpp>
+#include <opencv2/cann.hpp>
+#include <opencv2/cann_interface.hpp>
+
+int main(int argc, char *argv[])
+{
+    cv::CommandLineParser parser(argc, argv,
+                                 "{@input|puppy.png|path to input image}"
+                                 "{@output|output.png|path to output image}"
+                                 "{help||show help}"
+                                 );
+    parser.about("This is a sample for image processing with Ascend NPU. \n");
+    if (argc != 3 || parser.has("help"))
+    {
+        parser.printMessage();
+        return 0;
+    }
+
+    std::string imagePath = parser.get<std::string>(0);
+    std::string outputPath = parser.get<std::string>(1);
+
+    // read input image and generate guass noise
+    //! [input_noise]
+    cv::Mat img = cv::imread(imagePath);
+    // Generate gauss noise that will be added into the input image
+    cv::Mat gaussNoise(img.rows, img.cols,img.type());
+	cv::RNG rng;
+	rng.fill(gaussNoise, cv::RNG::NORMAL, 0, 25);
+    //! [input_noise]
+
+    //setup cann
+    //! [setup]
+    cv::cann::initAcl();
+    cv::cann::setDevice(0);
+    //! [setup]
+
+    //! [image-process]
+    cv::Mat output;
+    // add gauss noise to the image
+    cv::cann::add(img, gaussNoise, output);
+    // rotate the image with a certain mode (0, 1 and 2, correspond to rotation of 90, 180 and 270 degrees clockwise respectively)
+    cv::cann::rotate(output, output, 0);
+    // flip the image with a certain mode (0, positive and negative number, correspond to flipping around the x-axis, y-axis and both axes respectively)
+    cv::cann::flip(output, output, 0);
+    //! [image-process]
+
+    cv::imwrite(outputPath, output);
+
+    //! [tear-down-cann]
+    cv::cann::resetDevice();
+    cv::cann::finalizeAcl();
+    //! [tear-down-cann]
+    return 0;
+}

modules/cannops/samples/image_processing.py

@@ -0,0 +1,40 @@
+# This file is part of OpenCV project.
+# It is subject to the license terms in the LICENSE file found in the top-level directory
+# of this distribution and at http://opencv.org/license.html.
+
+import numpy as np
+import cv2
+import argparse
+
+parser = argparse.ArgumentParser(description='This is a sample for image processing with Ascend NPU.')
+parser.add_argument('image', help='path to input image')
+parser.add_argument('output', help='path to output image')
+args = parser.parse_args()
+
+# read input image and generate guass noise
+#! [input_noise]
+img = cv2.imread(args.image)
+# Generate gauss noise that will be added into the input image
+gaussNoise = np.random.normal(0, 25,(img.shape[0], img.shape[1], img.shape[2])).astype(img.dtype)
+#! [input_noise]
+
+# setup cann
+#! [setup]
+cv2.cann.initAcl()
+cv2.cann.setDevice(0)
+#! [setup]
+
+#! [image-process]
+# add gauss noise to the image
+output = cv2.cann.add(img, gaussNoise)
+# rotate the image with a certain mode (0, 1 and 2, correspond to rotation of 90, 180 and 270 degrees clockwise respectively)
+output = cv2.cann.rotate(output, 0)
+# flip the image with a certain mode (0, positive and negative number, correspond to flipping around the x-axis, y-axis and both axes respectively)
+output = cv2.cann.flip(output, 0)
+#! [image-process]
+
+cv2.imwrite(args.output, output)
+
+#! [tear-down-cann]
+cv2.cann.finalizeAcl()
+#! [tear-down-cann]

modules/cannops/samples/sample.cpp

@@ -156,7 +156,6 @@ void flip(InputArray _src, OutputArray _dst, int flipCode, AscendStream& stream)
 
 void rotate(InputArray _src, OutputArray _dst, int rotateMode, AscendStream& stream)
 {
-    CV_Assert(_src.dims() <= 2);
     AscendMat src = getInputMat(_src, stream), dst, tempMat;
     switch (rotateMode)
     {

modules/cannops/samples/sample.py

@@ -69,4 +69,4 @@ TEST(CVT_COLOR, YUV2BGR_DC4) { cvtColorTest(COLOR_YUV2BGR, 3, 4, 10.0f); }
 TEST(CVT_COLOR, YUV2RGB_DC4) { cvtColorTest(COLOR_YUV2RGB, 3, 4, 10.0f); }
 
 } // namespace
-} // namespace opencv_test
+} // namespace opencv_test

modules/cannops/src/core.cpp

@@ -0,0 +1,130 @@
+Ascend NPU Image Processing {#tutorial_ascend_npu_image_processing}
+==========================================================
+
+## Goal
+
+In this guide, you will gain insights into the thread safety of Ascend operators already in use, as well as discover how to effectively employ Ascend operators for image preprocessing and understand their usage limitations.
+
+## Preface
+
+We provide a suite of common matrix operation operators that support the [Ascend NPU](https://www.hiascend.com/en/) within OpenCV. For user convenience, the new 'AscendMat' structure and its associated operators maintain compatibility with the 'Mat' interface in OpenCV. These operators encompass a wide range of frequently used functions, including arithmetic operations, image processing operations, and image color space conversion. All of these operators are implemented utilizing [CANN](https://www.hiascend.com/en/software/cann)(Compute Architecture of Neural Networks). The Ascend operator facilitates accelerated operations on the NPU by making use of CANN. This acceleration effect is particularly noticeable when working with larger images, such as those with dimensions like 2048x2048, 3840x2160, 7680x4320, etc.
+
+
+## Instructions on Thread Safety
+
+Our stream function is implemented by invoking the CANN operators. In the same stream, tasks are executed sequentially, while across different streams, tasks are executed in parallel. The use of event mechanisms ensures synchronization of tasks between streams, please refer to the [**Stream Management**](https://www.hiascend.com/document/detail/en/CANNCommunityEdition/600alphaX/infacldevg/aclcppdevg/aclcppdevg_000147.html) documentation for details.
+
+
+## Example for Image Preprocessing
+
+In this section, you will discover how to use Ascend operators for image preprocessing, including functions below:
+
+- Add
+- Rotate
+- Flip
+
+
+### code
+
+@add_toggle_cpp
+@include opencv_contrib/modules/cannops/samples/image_processing.cpp
+@end_toggle
+
+@add_toggle_python
+@include opencv_contrib/modules/cannops/samples/image_processing.py
+@end_toggle
+
+### Explanation
+
+**Input Image**
+
+@add_toggle_cpp
+@snippet opencv_contrib/modules/cannops/samples/image_processing.cpp input_noise
+@end_toggle
+
+@add_toggle_python
+
+```python
+# Read the input image
+img = cv2.imread("/path/to/img")
+# Generate gauss noise that will be added into the input image
+gaussNoise = np.random.normal(mean=0,sigma=25,(img.shape[0],img.shape[1],img.shape[2])).astype(img.dtype)
+```
+
+@end_toggle
+
+**Setup CANN**
+
+@add_toggle_cpp
+
+@snippet opencv_contrib/modules/cannops/samples/image_processing.cpp setup
+
+@end_toggle
+
+@add_toggle_python
+
+@snippet opencv_contrib/modules/cannops/samples/image_processing.py setup
+
+@end_toggle
+**Image Preprocessing Example**
+
+@add_toggle_cpp
+
+@snippet opencv_contrib/modules/cannops/samples/image_processing.cpp image-process
+
+@end_toggle
+
+@add_toggle_python
+
+@snippet opencv_contrib/modules/cannops/samples/image_processing.py image-process
+
+@end_toggle
+
+**Tear down CANN**
+
+@add_toggle_cpp
+@snippet opencv_contrib/modules/cannops/samples/image_processing.cpp tear-down-cann
+
+@end_toggle
+
+@add_toggle_python
+
+@snippet opencv_contrib/modules/cannops/samples/image_processing.py tear-down-cann
+
+@end_toggle
+Results
+
+1. The original RGB input image with dimensions of (480, 640, 3):
+
+   ![puppy](./puppy.png)
+
+2. After introducing Gaussian noise, we obtain the following result:
+
+   ![puppy_noisy](./puppy_noisy.png)
+
+3. When applying the rotate operation with a rotation code of 0 (90 degrees clockwise), we obtain this result:
+
+   ![puppy_noisy_rotate](./puppy_noisy_rotate.png)
+
+4. Upon applying the flip operation with a flip code of 0 (flipping around the x-axis), we achieve the final result:
+
+   ![puppy_processed_normalized](./puppy_processed.png)
+
+
+
+## Usage Limitations
+
+While Ascend supports most commonly used operators, there are still some limitations that need to be addressed.
+
+- There is no strict limit on the size of the input image used for encoding; however, it depends on the available RAM size of your device.
+- Please note that not all data types (dtypes) are supported by every operator. The current dtype limitations are outlined in the following table. We are actively working on addressing these limitations through automatic dtype conversion in an upcoming commit.
+
+
+| Operator               | Supported Dtype                                              |
+| ---------------------- | ------------------------------------------------------------ |
+| multiply (with scale)  | float16,float32,int32                                        |
+| divide (with scale)    | float16,float,int32,int8,uint8                               |
+| bitwise add/or/xor/not | int32,int16,uint16                                           |
+| flip                   | float16,float,int64,int32,int16,uint16                       |
+| transpose              | float16,float,int64,int32,int16,int8,uint64,uint32,uint16,uint8,bool |
+| rotate                 | float16,float,int64,int32,int16,uint16                       |