vendor: OpenCV 5.0.0 snapshot at 755e50675d97db9b7d449d8bd6b09888646f6c6e

2026-08-22 00:11:13 +08:00
commit 12022378a3
3872 changed files with 2513409 additions and 0 deletions
@@ -0,0 +1,85 @@
+Creating Groups {#tutorial_hdf_create_groups}
+===============================
+
+Goal
+----
+
+This tutorial will show you:
+ - How to create a HDF5 file?
+ - How to create a group?
+ - How to check whether a given group exists or not?
+ - How to create a subgroup?
+
+Source Code
+----
+
+The following code creates two groups: `Group1` and `SubGroup1`, where
+`SubGroup1` is a child of `Group1`.
+
+You can download the code from [here][1] or find it in the file
+`modules/hdf/samples/create_groups.cpp` of the opencv_contrib source code library.
+
+@snippet samples/create_groups.cpp tutorial
+
+Explanation
+----
+
+First, we create a HDF5 file
+
+@snippet samples/create_groups.cpp tutorial_create_file
+
+If the given file does not exist, it will be created. Otherwise, it is open for read and write.
+
+Next, we create the group `Group1`
+
+@snippet samples/create_groups.cpp tutorial_create_group
+
+Note that we have to check whether `/Group1` exists or not using
+the function cv::hdf::HDF5::hlexists() before creating it. You can not create
+a group with an existing name. Otherwise, an error will occur.
+
+Then, we create the subgroup named `Subgroup1`. In order to
+indicate that it is a sub group of `Group1`, we have to
+use the group name `/Group1/SubGroup1`:
+
+@snippet samples/create_groups.cpp tutorial_create_subgroup
+
+Note that before creating a subgroup, we have to make sure
+that its parent group exists. Otherwise, an error will occur.
+
+In the end, we have to close the file
+
+@snippet samples/create_groups.cpp tutorial_close_file
+
+Result
+----
+
+There are many tools that can be used to inspect a given HDF file, such
+as HDFView and h5dump. If you are using Ubuntu, you can install
+them with the following commands:
+
+@code
+sudo apt-get install hdf5-tools hdfview
+@endcode
+
+There are also binaries available from the The HDF Group official website <https://support.hdfgroup.org/HDF5/Tutor/tools.html>.
+
+The following figure shows the result visualized with the tool HDFView:
+
+![Figure 1: Results of creating groups and subgroups](pics/create_groups.png)
+
+The output for `h5dump` is:
+
+@code
+$ h5dump mytest.h5
+HDF5 "mytest.h5" {
+GROUP "/" {
+   GROUP "Group1" {
+      GROUP "SubGroup1" {
+      }
+   }
+}
+}
+@endcode
+
+[1]: https://github.com/opencv/opencv_contrib/tree/master/modules/hdf/samples/create_groups.cpp
@@ -0,0 +1,74 @@
+Creating, Writing and Reading Datasets {#tutorial_hdf_create_read_write_datasets}
+===============================
+
+Goal
+----
+
+This tutorial shows you:
+ - How to create a dataset?
+ - How to write a `cv::Mat` to a dataset?
+ - How to read a `cv::Mat` from a dataset?
+
+@note Currently, it supports only reading and writing cv::Mat and the matrix should be continuous
+in memory. Supports for other data types have not been implemented yet.
+
+Source Code
+----
+
+The following code demonstrates writing a single channel
+matrix and a two-channel matrix to datasets and then reading them
+back.
+
+You can download the code from [here][1] or find it in the file
+`modules/hdf/samples/create_read_write_datasets.cpp` of the opencv_contrib source code library.
+
+@snippet samples/create_read_write_datasets.cpp tutorial
+
+Explanation
+----
+
+The first step for creating a dataset is to open the file
+
+@snippet samples/create_read_write_datasets.cpp tutorial_open_file
+
+For the function `write_root_group_single_channel()`, since
+the dataset name is `/single`, which is inside the root group, we can use
+
+@snippet samples/create_read_write_datasets.cpp tutorial_write_root_single_channel
+
+to write the data directly to the dataset without the need of creating
+it beforehand. Because it is created inside cv::hdf::HDF5::dswrite()
+automatically.
+
+@warning This applies only to datasets that reside inside the root group.
+
+Of course, we can create the dataset by ourselves:
+
+@snippet samples/create_read_write_datasets.cpp tutorial_create_dataset
+
+To read data from a dataset, we use
+
+@snippet samples/create_read_write_datasets.cpp tutorial_read_dataset
+
+by specifying the name of the dataset.
+
+We can check that the data read out is exactly the data written before by using
+
+@snippet samples/create_read_write_datasets.cpp tutorial_check_result
+
+Results
+----
+
+Figure 1 shows the result visualized using the tool HDFView for the file
+`root_group_single_channel`. The results
+of matrices for datasets that are not the direct children of the root group
+are given in Figure 2 and Figure 3, respectively.
+
+![Figure 1: Result for writing a single channel matrix to a dataset inside the root group](pics/root_group_single_channel.png)
+
+![Figure 2: Result for writing a single channel matrix to a dataset not in the root group](pics/single_channel.png)
+
+![Figure 3: Result for writing a two-channel matrix to a dataset not in the root group](pics/two_channels.png)
+
+
+[1]: https://github.com/opencv/opencv_contrib/tree/master/modules/hdf/samples/create_read_write_datasets.cpp
@@ -0,0 +1,57 @@
+Reading and Writing Attributes{#tutorial_hdf_read_write_attributes}
+===============================
+
+Goal
+----
+This tutorial shows you:
+ - How to write attributes?
+ - How to read attributes?
+
+@note Although attributes can be associated with groups and datasets, only attributes
+with the root group are implemented in OpenCV. Supported attribute types are
+`int`, `double`, `cv::String` and `cv::InputArray` (only for continuous arrays).
+
+Source Code
+----
+
+The following code demonstrates reading and writing attributes
+inside the root group with data types `cv::Mat`, `cv::String`, `int`
+and `double`.
+
+You can download the code from [here][1] or find it in the file
+`modules/hdf/samples/read_write_attributes.cpp` of the opencv_contrib source code library.
+
+@snippet samples/read_write_attributes.cpp tutorial
+
+Explanation
+----
+
+The first step is to open the HDF5 file:
+
+@snippet samples/read_write_attributes.cpp tutorial_open_file
+
+Then we use cv::hdf::HDF5::atwrite() to write attributes by specifying its value and name:
+
+@snippet samples/read_write_attributes.cpp tutorial_write_mat
+
+@warning Before writing an attribute, we have to make sure that
+the attribute does not exist using cv::hdf::HDF5::atexists().
+
+To read an attribute, we use cv::hdf::HDF5::atread() by specifying the attribute name
+
+@snippet samples/read_write_attributes.cpp tutorial_read_mat
+
+In the end, we have to close the HDF file
+
+@snippet samples/read_write_attributes.cpp tutorial_close_file
+
+Results
+----
+
+Figure 1 and Figure 2 give the results visualized using the tool HDFView.
+
+![Figure 1: Attributes of the root group](pics/attributes-file.png)
+
+![Figure 2: Detailed attribute information](pics/attributes-details.png)
+
+[1]: https://github.com/opencv/opencv_contrib/tree/master/modules/hdf/samples/read_write_attributes.cpp
@@ -0,0 +1,32 @@
+The Hierarchical Data Format (hdf) I/O {#tutorial_table_of_content_hdf}
+=====================================
+
+Here you will know how to read and write a HDF5 file using OpenCV.
+Specifically, it shows you how to read/write groups, datasets and attributes.
+
+@note The HDF5 library has to be installed in your system
+to use this module.
+
+-   @subpage tutorial_hdf_create_groups
+
+    *Compatibility:* \> OpenCV 3.0
+
+    *Author:* Fangjun Kuang
+
+    You will learn how to create groups and subgroups.
+
+-   @subpage tutorial_hdf_create_read_write_datasets
+
+    *Compatibility:* \> OpenCV 3.0
+
+    *Author:* Fangjun Kuang
+
+    You will learn how to create, read and write datasets.
+
+-   @subpage tutorial_hdf_read_write_attributes
+
+    *Compatibility:* \> OpenCV 3.4
+
+    *Author:* Fangjun Kuang
+
+    You will learn how to read and write attributes.