Improve the HDF module.

 - Some test cases are added
 - Two tutorials are written to show how to use it.

Author: csukuangfj

modules/fuzzy/samples/fuzzy_filtering.cpp

@@ -11,7 +11,7 @@
  * using "kernel2" with radius 100.
  *
  * Both kernels are created from linear function, using
- * linear interpolation (parametr ft:LINEAR).
+ * linear interpolation (parameter ft:LINEAR).
  */
 
 #include "opencv2/core.hpp"
@@ -26,7 +26,7 @@ int main(void)
     // Input image
     Mat I = imread("input.png");
 
-    // Kernel cretion
+    // Kernel creation
     Mat kernel1, kernel2;
 
     ft::createKernel(ft::LINEAR, 3, kernel1, 3);

modules/hdf/doc/pics/create_groups.png

@@ -47,6 +47,9 @@ This module provides storage routines for Hierarchical Data Format objects.
 Hierarchical Data Format version 5
 --------------------------------------------------------
 
+In order to use it, the hdf5 library has to be installed, which
+means cmake should find it using `find_package(HDF5)` .
+
 
   @}
 */

modules/hdf/doc/pics/root_group_single_channel.png

@@ -0,0 +1,60 @@
+// 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.
+
+/**
+ * @file create_groups.cpp
+ * @author Fangjun Kuang <csukuangfj dot at gmail dot com>
+ * @date December 2017
+ *
+ * @brief It demonstrates how to create HDF5 groups and subgroups.
+ *
+ * Basic steps:
+ *  1. Use hdf::open to create a HDF5 file
+ *  2. Use HDF5::hlexists to check if a group exists or not
+ *  3. Use HDF5::grcreate to create a group by specifying its name
+ *  4. Use hdf::close to close a HDF5 file after modifying it
+ *
+ */
+
+//! [tutorial]
+#include <iostream>
+
+#include <opencv2/core.hpp>
+#include <opencv2/hdf.hpp>
+
+using namespace cv;
+
+int main()
+{
+    //! [create_group]
+
+    //! [tutorial_create_file]
+    Ptr<hdf::HDF5> h5io = hdf::open("mytest.h5");
+    //! [tutorial_create_file]
+
+    //! [tutorial_create_group]
+    // "/" means the root group, which is always present
+    if (!h5io->hlexists("/Group1"))
+       h5io->grcreate("/Group1");
+    else
+       std::cout << "/Group1 has already been created, skip it.\n";
+    //! [tutorial_create_group]
+
+    //! [tutorial_create_subgroup]
+    // Note that Group1 has been created above, otherwise exception will occur
+    if (!h5io->hlexists("/Group1/SubGroup1"))
+       h5io->grcreate("/Group1/SubGroup1");
+    else
+       std::cout << "/Group1/SubGroup1 has already been created, skip it.\n";
+    //! [tutorial_create_subgroup]
+
+    //! [tutorial_close_file]
+    h5io->close();
+    //! [tutorial_close_file]
+
+    //! [create_group]
+
+    return 0;
+}
+//! [tutorial]

modules/hdf/doc/pics/single_channel.png

@@ -0,0 +1,135 @@
+// 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.
+
+/**
+ * @file create_read_write.cpp
+ * @author Fangjun Kuang <csukuangfj dot at gmail dot com>
+ * @date December 2017
+ *
+ * @brief It demonstrates how to create a dataset,  how
+ * to write a cv::Mat to the dataset and how to
+ * read a cv::Mat from it.
+ *
+ */
+
+//! [tutorial]
+#include <iostream>
+
+#include <opencv2/core.hpp>
+#include <opencv2/hdf.hpp>
+
+using namespace cv;
+
+void write_root_group_single_channel()
+{
+    String filename = "root_group_single_channel.h5";
+    String dataset_name = "/single"; // Note that it is a child of the root group /
+
+    // prepare data
+    Mat data;
+    data = (cv::Mat_<float>(2, 3) << 0, 1, 2, 3, 4, 5, 6);
+
+    //! [tutorial_open_file]
+    Ptr<hdf::HDF5> h5io = hdf::open(filename);
+    //! [tutorial_open_file]
+
+    //! [tutorial_write_root_single_channel]
+    // write data to the given dataset
+    // the dataset "/single" is created automatically, since it is a child of the root
+    h5io->dswrite(data, dataset_name);
+    //! [tutorial_write_root_single_channel]
+
+    //! [tutorial_read_dataset]
+    Mat expected;
+    h5io->dsread(expected, dataset_name);
+    //! [tutorial_read_dataset]
+
+    //! [tutorial_check_result]
+    double diff = norm(data - expected);
+    CV_Assert(abs(diff) < 1e-10);
+    //! [tutorial_check_result]
+
+    h5io->close();
+}
+
+void write_single_channel()
+{
+    String filename = "single_channel.h5";
+    String parent_name = "/data";
+    String dataset_name = parent_name + "/single";
+
+    // prepare data
+    Mat data;
+    data = (cv::Mat_<float>(2, 3) << 0, 1, 2, 3, 4, 5);
+
+    Ptr<hdf::HDF5> h5io = hdf::open(filename);
+
+    //! [tutorial_create_dataset]
+    // first we need to create the parent group
+    if (!h5io->hlexists(parent_name)) h5io->grcreate(parent_name);
+
+    // create the dataset if it not exists
+    if (!h5io->hlexists(dataset_name)) h5io->dscreate(data.rows, data.cols, data.type(), dataset_name);
+    //! [tutorial_create_dataset]
+
+    // the following is the same with the above function write_root_group_single_channel()
+
+    h5io->dswrite(data, dataset_name);
+
+    Mat expected;
+    h5io->dsread(expected, dataset_name);
+
+    double diff = norm(data - expected);
+    CV_Assert(abs(diff) < 1e-10);
+
+    h5io->close();
+}
+
+/*
+ * creating, reading and writing multiple-channel matrices
+ * are the same with single channel matrices
+ */
+void write_multiple_channels()
+{
+    String filename = "two_channels.h5";
+    String parent_name = "/data";
+    String dataset_name = parent_name + "/two_channels";
+
+    // prepare data
+    Mat data(2, 3, CV_32SC2);
+    for (size_t i = 0; i < data.total()*data.channels(); i++)
+        ((int*) data.data)[i] = (int)i;
+
+    Ptr<hdf::HDF5> h5io = hdf::open(filename);
+
+    // first we need to create the parent group
+    if (!h5io->hlexists(parent_name)) h5io->grcreate(parent_name);
+
+    // create the dataset if it not exists
+    if (!h5io->hlexists(dataset_name)) h5io->dscreate(data.rows, data.cols, data.type(), dataset_name);
+
+    // the following is the same with the above function write_root_group_single_channel()
+
+    h5io->dswrite(data, dataset_name);
+
+    Mat expected;
+    h5io->dsread(expected, dataset_name);
+
+    double diff = norm(data - expected);
+    CV_Assert(abs(diff) < 1e-10);
+
+    h5io->close();
+}
+
+int main()
+{
+    write_root_group_single_channel();
+
+    write_single_channel();
+
+    write_multiple_channels();
+
+    return 0;
+}
+//! [tutorial]