OpenCV  3.3.0
Open Source Computer Vision
Public Types | Public Member Functions | List of all members

Hierarchical Data Format version 5 interface. More...

#include "hdf5.hpp"

Public Types

enum  {
  H5_UNLIMITED = -1,
  H5_NONE = -1,
  H5_GETDIMS = 100,
  H5_GETMAXDIMS = 101,
  H5_GETCHUNKDIMS = 102
}
 

Public Member Functions

virtual ~HDF5 ()
 
virtual void close ()=0
 Close and release hdf5 object. More...
 
virtual void dscreate (const int rows, const int cols, const int type, String dslabel) const =0
 
virtual void dscreate (const int rows, const int cols, const int type, String dslabel, const int compresslevel) const =0
 
virtual void dscreate (const int rows, const int cols, const int type, String dslabel, const int compresslevel, const vector< int > &dims_chunks) const =0
 
virtual void dscreate (const int rows, const int cols, const int type, String dslabel, const int compresslevel, const int *dims_chunks) const =0
 Create and allocate storage for two dimensional single or multi channel dataset. More...
 
virtual void dscreate (const int n_dims, const int *sizes, const int type, String dslabel) const =0
 
virtual void dscreate (const int n_dims, const int *sizes, const int type, String dslabel, const int compresslevel) const =0
 
virtual void dscreate (const vector< int > &sizes, const int type, String dslabel, const int compresslevel=HDF5::H5_NONE, const vector< int > &dims_chunks=vector< int >()) const =0
 
virtual void dscreate (const int n_dims, const int *sizes, const int type, String dslabel, const int compresslevel, const int *dims_chunks) const =0
 Create and allocate storage for n-dimensional dataset, single or mutichannel type. More...
 
virtual vector< int > dsgetsize (String dslabel, int dims_flag=HDF5::H5_GETDIMS) const =0
 Fetch dataset sizes. More...
 
virtual int dsgettype (String dslabel) const =0
 Fetch dataset type. More...
 
virtual void dsinsert (InputArray Array, String dslabel) const =0
 
virtual void dsinsert (InputArray Array, String dslabel, const int *dims_offset) const =0
 
virtual void dsinsert (InputArray Array, String dslabel, const vector< int > &dims_offset, const vector< int > &dims_counts=vector< int >()) const =0
 
virtual void dsinsert (InputArray Array, String dslabel, const int *dims_offset, const int *dims_counts) const =0
 Insert or overwrite a Mat object into specified dataset and autoexpand dataset size if unlimited property allows. More...
 
virtual void dsread (OutputArray Array, String dslabel) const =0
 
virtual void dsread (OutputArray Array, String dslabel, const int *dims_offset) const =0
 
virtual void dsread (OutputArray Array, String dslabel, const vector< int > &dims_offset, const vector< int > &dims_counts=vector< int >()) const =0
 
virtual void dsread (OutputArray Array, String dslabel, const int *dims_offset, const int *dims_counts) const =0
 Read specific dataset from hdf5 file into Mat object. More...
 
virtual void dswrite (InputArray Array, String dslabel) const =0
 
virtual void dswrite (InputArray Array, String dslabel, const int *dims_offset) const =0
 
virtual void dswrite (InputArray Array, String dslabel, const vector< int > &dims_offset, const vector< int > &dims_counts=vector< int >()) const =0
 
virtual void dswrite (InputArray Array, String dslabel, const int *dims_offset, const int *dims_counts) const =0
 Write or overwrite a Mat object into specified dataset of hdf5 file. More...
 
virtual void grcreate (String grlabel)=0
 Create a group. More...
 
virtual bool hlexists (String label) const =0
 Check if label exists or not. More...
 
virtual void kpcreate (const int size, String kplabel, const int compresslevel=H5_NONE, const int chunks=H5_NONE) const =0
 Create and allocate special storage for cv::KeyPoint dataset. More...
 
virtual int kpgetsize (String kplabel, int dims_flag=HDF5::H5_GETDIMS) const =0
 Fetch keypoint dataset size. More...
 
virtual void kpinsert (const vector< KeyPoint > keypoints, String kplabel, const int offset=H5_NONE, const int counts=H5_NONE) const =0
 Insert or overwrite list of KeyPoint into specified dataset and autoexpand dataset size if unlimited property allows. More...
 
virtual void kpread (vector< KeyPoint > &keypoints, String kplabel, const int offset=H5_NONE, const int counts=H5_NONE) const =0
 Read specific keypoint dataset from hdf5 file into vector<KeyPoint> object. More...
 
virtual void kpwrite (const vector< KeyPoint > keypoints, String kplabel, const int offset=H5_NONE, const int counts=H5_NONE) const =0
 Write or overwrite list of KeyPoint into specified dataset of hdf5 file. More...
 

Detailed Description

Hierarchical Data Format version 5 interface.

Notice that module is compiled only when hdf5 is correctly installed.

Member Enumeration Documentation

§ anonymous enum

anonymous enum
Enumerator
H5_UNLIMITED 
H5_NONE 
H5_GETDIMS 
H5_GETMAXDIMS 
H5_GETCHUNKDIMS 

Constructor & Destructor Documentation

§ ~HDF5()

virtual cv::hdf::HDF5::~HDF5 ( )
inlinevirtual

Member Function Documentation

§ close()

virtual void cv::hdf::HDF5::close ( )
pure virtual

Close and release hdf5 object.

§ dscreate() [1/8]

virtual void cv::hdf::HDF5::dscreate ( const int  rows,
const int  cols,
const int  type,
String  dslabel 
) const
pure virtual

§ dscreate() [2/8]

virtual void cv::hdf::HDF5::dscreate ( const int  rows,
const int  cols,
const int  type,
String  dslabel,
const int  compresslevel 
) const
pure virtual

§ dscreate() [3/8]

virtual void cv::hdf::HDF5::dscreate ( const int  rows,
const int  cols,
const int  type,
String  dslabel,
const int  compresslevel,
const vector< int > &  dims_chunks 
) const
pure virtual

§ dscreate() [4/8]

virtual void cv::hdf::HDF5::dscreate ( const int  rows,
const int  cols,
const int  type,
String  dslabel,
const int  compresslevel,
const int *  dims_chunks 
) const
pure virtual

Create and allocate storage for two dimensional single or multi channel dataset.

Parameters
rowsdeclare amount of rows
colsdeclare amount of cols
typetype to be used
dslabelspecify the hdf5 dataset label, any existing dataset with the same label will be overwritten.
compresslevelspecify the compression level 0-9 to be used, H5_NONE is default and means no compression.
dims_chunkseach array member specify chunking sizes to be used for block i/o, by default NULL means none at all.
Note
If the dataset already exists an exception will be thrown.
Note
Activating compression requires internal chunking. Chunking can significantly improve access speed booth at read or write time especially for windowed access logic that shifts offset inside dataset. If no custom chunking is specified default one will be invoked by the size of whole dataset as single big chunk of data.
  • See example of level 9 compression using internal default chunking:
    // open / autocreate hdf5 file
    cv::Ptr<cv::hdf::HDF5> h5io = cv::hdf::open( "mytest.h5" );
    // create level 9 compressed space for CV_64FC2 matrix
    if ( ! h5io->hlexists( "hilbert", 9 ) )
    h5io->dscreate( 100, 50, CV_64FC2, "hilbert", 9 );
    else
    printf("DS already created, skipping\n" );
    // release
    h5io->close();
Note
A value of H5_UNLIMITED for rows or cols or booth means unlimited data on the specified dimension, thus is possible to expand anytime such dataset on row, col or booth directions. Presence of H5_UNLIMITED on any dimension require to define custom chunking. No default chunking will be defined in unlimited scenario since default size on that dimension will be zero, and will grow once dataset is written. Writing into dataset that have H5_UNLIMITED on some of its dimension requires dsinsert() that allow growth on unlimited dimension instead of dswrite() that allows to write only in predefined data space.
Note
It is not thread safe, it must be called only once at dataset creation otherwise exception will occur. Multiple datasets inside single hdf5 file is allowed.

§ dscreate() [5/8]

virtual void cv::hdf::HDF5::dscreate ( const int  n_dims,
const int *  sizes,
const int  type,
String  dslabel 
) const
pure virtual

§ dscreate() [6/8]

virtual void cv::hdf::HDF5::dscreate ( const int  n_dims,
const int *  sizes,
const int  type,
String  dslabel,
const int  compresslevel 
) const
pure virtual

§ dscreate() [7/8]

virtual void cv::hdf::HDF5::dscreate ( const vector< int > &  sizes,
const int  type,
String  dslabel,
const int  compresslevel = HDF5::H5_NONE,
const vector< int > &  dims_chunks = vector< int >() 
) const
pure virtual

§ dscreate() [8/8]

virtual void cv::hdf::HDF5::dscreate ( const int  n_dims,
const int *  sizes,
const int  type,
String  dslabel,
const int  compresslevel,
const int *  dims_chunks 
) const
pure virtual

Create and allocate storage for n-dimensional dataset, single or mutichannel type.

Parameters
n_dimsdeclare number of dimensions
sizesarray containing sizes for each dimensions
typetype to be used
dslabelspecify the hdf5 dataset label, any existing dataset with the same label will be overwritten.
compresslevelspecify the compression level 0-9 to be used, H5_NONE is default and means no compression.
dims_chunkseach array member specify chunking sizes to be used for block i/o, by default NULL means none at all.
Note
If the dataset already exists an exception will be thrown. Existence of the dataset can be checked using hlexists().
  • See example below that creates a 6 dimensional storage space:
    // open / autocreate hdf5 file
    cv::Ptr<cv::hdf::HDF5> h5io = cv::hdf::open( "mytest.h5" );
    // create space for 6 dimensional CV_64FC2 matrix
    if ( ! h5io->hlexists( "nddata" ) )
    int n_dims = 5;
    int dsdims[n_dims] = { 100, 100, 20, 10, 5, 5 };
    h5io->dscreate( n_dims, sizes, CV_64FC2, "nddata" );
    else
    printf("DS already created, skipping\n" );
    // release
    h5io->close();
Note
Activating compression requires internal chunking. Chunking can significantly improve access speed booth at read or write time especially for windowed access logic that shifts offset inside dataset. If no custom chunking is specified default one will be invoked by the size of whole dataset as single big chunk of data.
  • See example of level 0 compression (shallow) using chunking against first dimension, thus storage will consists by 100 chunks of data:
    // open / autocreate hdf5 file
    cv::Ptr<cv::hdf::HDF5> h5io = cv::hdf::open( "mytest.h5" );
    // create space for 6 dimensional CV_64FC2 matrix
    if ( ! h5io->hlexists( "nddata" ) )
    int n_dims = 5;
    int dsdims[n_dims] = { 100, 100, 20, 10, 5, 5 };
    int chunks[n_dims] = { 1, 100, 20, 10, 5, 5 };
    h5io->dscreate( n_dims, dsdims, CV_64FC2, "nddata", 0, chunks );
    else
    printf("DS already created, skipping\n" );
    // release
    h5io->close();
Note
A value of H5_UNLIMITED inside the sizes array means unlimited data on that dimension, thus is possible to expand anytime such dataset on those unlimited directions. Presence of H5_UNLIMITED on any dimension require** to define custom chunking. No default chunking will be defined in unlimited scenario since default size on that dimension will be zero, and will grow once dataset is written. Writing into dataset that have H5_UNLIMITED on some of its dimension requires dsinsert() instead of dswrite() that allow growth on unlimited dimension instead of dswrite() that allows to write only in predefined data space.

§ dsgetsize()

virtual vector<int> cv::hdf::HDF5::dsgetsize ( String  dslabel,
int  dims_flag = HDF5::H5_GETDIMS 
) const
pure virtual

Fetch dataset sizes.

Parameters
dslabelspecify the hdf5 dataset label to be measured.
dims_flagwill fetch dataset dimensions on H5_GETDIMS, and dataset maximum dimensions on H5_GETMAXDIMS.

Returns vector object containing sizes of dataset on each dimensions.

Note
Resulting vector size will match the amount of dataset dimensions. By default H5_GETDIMS will return actual dataset dimensions. Using H5_GETMAXDIM flag will get maximum allowed dimension which normally match actual dataset dimension but can hold H5_UNLIMITED value if dataset was prepared in unlimited mode on some of its dimension. It can be useful to check existing dataset dimensions before overwrite it as whole or subset. Trying to write with oversized source data into dataset target will thrown exception. The H5_GETCHUNKDIMS will return the dimension of chunk if dataset was created with chunking options otherwise returned vector size will be zero.

§ dsgettype()

virtual int cv::hdf::HDF5::dsgettype ( String  dslabel) const
pure virtual

Fetch dataset type.

Parameters
dslabelspecify the hdf5 dataset label to be checked.

Returns the stored matrix type. This is an identifier compatible with the CvMat type system, like e.g. CV_16SC5 (16-bit signed 5-channel array), and so on.

Note
Result can be parsed with CV_MAT_CN() to obtain amount of channels and CV_MAT_DEPTH() to obtain native cvdata type. It is thread safe.

§ dsinsert() [1/4]

virtual void cv::hdf::HDF5::dsinsert ( InputArray  Array,
String  dslabel 
) const
pure virtual

§ dsinsert() [2/4]

virtual void cv::hdf::HDF5::dsinsert ( InputArray  Array,
String  dslabel,
const int *  dims_offset 
) const
pure virtual

§ dsinsert() [3/4]

virtual void cv::hdf::HDF5::dsinsert ( InputArray  Array,
String  dslabel,
const vector< int > &  dims_offset,
const vector< int > &  dims_counts = vector< int >() 
) const
pure virtual

§ dsinsert() [4/4]

virtual void cv::hdf::HDF5::dsinsert ( InputArray  Array,
String  dslabel,
const int *  dims_offset,
const int *  dims_counts 
) const
pure virtual

Insert or overwrite a Mat object into specified dataset and autoexpand dataset size if unlimited property allows.

Parameters
Arrayspecify Mat data array to be written.
dslabelspecify the target hdf5 dataset label.
dims_offseteach array member specify the offset location over dataset's each dimensions from where InputArray will be (over)written into dataset.
dims_countseach array member specify the amount of data over dataset's each dimensions from InputArray that will be written into dataset.

Writes Mat object into targeted dataset and autoexpand dataset dimension if allowed.

Note
Unlike dswrite(), datasets are not created automatically. Only Mat is supported and it must to be continuous. If dsinsert() happen over outer regions of dataset dimensions and on that dimension of dataset is in unlimited mode then dataset is expanded, otherwise exception is thrown. To create datasets with unlimited property on specific or more dimensions see dscreate() and the optional H5_UNLIMITED flag at creation time. It is not thread safe over same dataset but multiple datasets can be merged inside single hdf5 file.
  • Example below creates unlimited rows x 100 cols and expand rows 5 times with dsinsert() using single 100x100 CV_64FC2 over the dataset. Final size will have 5x100 rows and 100 cols, reflecting H matrix five times over row's span. Chunks size is 100x100 just optimized against the H matrix size having compression disabled. If routine is called multiple times dataset will be just overwritten:
    // dual channel hilbert matrix
    cv::Mat H(50, 100, CV_64FC2);
    for(int i = 0; i < H.rows; i++)
    for(int j = 0; j < H.cols; j++)
    {
    H.at<cv::Vec2d>(i,j)[0] = 1./(i+j+1);
    H.at<cv::Vec2d>(i,j)[1] = -1./(i+j+1);
    count++;
    }
    // open / autocreate hdf5 file
    cv::Ptr<cv::hdf::HDF5> h5io = cv::hdf::open( "mytest.h5" );
    // optimise dataset by chunks
    int chunks[2] = { 100, 100 };
    // create Unlimited x 100 CV_64FC2 space
    h5io->dscreate( cv::hdf::HDF5::H5_UNLIMITED, 100, CV_64FC2, "hilbert", cv::hdf::HDF5::H5_NONE, chunks );
    // write into first half
    int offset[2] = { 0, 0 };
    for ( int t = 0; t < 5; t++ )
    {
    offset[0] += 100 * t;
    h5io->dsinsert( H, "hilbert", offset );
    }
    // release
    h5io->close();

§ dsread() [1/4]

virtual void cv::hdf::HDF5::dsread ( OutputArray  Array,
String  dslabel 
) const
pure virtual

§ dsread() [2/4]

virtual void cv::hdf::HDF5::dsread ( OutputArray  Array,
String  dslabel,
const int *  dims_offset 
) const
pure virtual

§ dsread() [3/4]

virtual void cv::hdf::HDF5::dsread ( OutputArray  Array,
String  dslabel,
const vector< int > &  dims_offset,
const vector< int > &  dims_counts = vector< int >() 
) const
pure virtual

§ dsread() [4/4]

virtual void cv::hdf::HDF5::dsread ( OutputArray  Array,
String  dslabel,
const int *  dims_offset,
const int *  dims_counts 
) const
pure virtual

Read specific dataset from hdf5 file into Mat object.

Parameters
ArrayMat container where data reads will be returned.
dslabelspecify the source hdf5 dataset label.
dims_offseteach array member specify the offset location over each dimensions from where dataset starts to read into OutputArray.
dims_countseach array member specify the amount over dataset's each dimensions of dataset to read into OutputArray.

Reads out Mat object reflecting the stored dataset.

Note
If hdf5 file does not exist an exception will be thrown. Use hlexists() to check dataset presence. It is thread safe.
  • Example below reads a dataset:
    // open hdf5 file
    cv::Ptr<cv::hdf::HDF5> h5io = cv::hdf::open( "mytest.h5" );
    // blank Mat container
    // read hibert dataset
    h5io->read( H, "hilbert" );
    // release
    h5io->close();
  • Example below perform read of 3x5 submatrix from second row and third element.
    // open hdf5 file
    cv::Ptr<cv::hdf::HDF5> h5io = cv::hdf::open( "mytest.h5" );
    // blank Mat container
    int offset[2] = { 1, 2 };
    int counts[2] = { 3, 5 };
    // read hibert dataset
    h5io->read( H, "hilbert", offset, counts );
    // release
    h5io->close();

§ dswrite() [1/4]

virtual void cv::hdf::HDF5::dswrite ( InputArray  Array,
String  dslabel 
) const
pure virtual

§ dswrite() [2/4]

virtual void cv::hdf::HDF5::dswrite ( InputArray  Array,
String  dslabel,
const int *  dims_offset 
) const
pure virtual

§ dswrite() [3/4]

virtual void cv::hdf::HDF5::dswrite ( InputArray  Array,
String  dslabel,
const vector< int > &  dims_offset,
const vector< int > &  dims_counts = vector< int >() 
) const
pure virtual

§ dswrite() [4/4]

virtual void cv::hdf::HDF5::dswrite ( InputArray  Array,
String  dslabel,
const int *  dims_offset,
const int *  dims_counts 
) const
pure virtual

Write or overwrite a Mat object into specified dataset of hdf5 file.

Parameters
Arrayspecify Mat data array to be written.
dslabelspecify the target hdf5 dataset label.
dims_offseteach array member specify the offset location over dataset's each dimensions from where InputArray will be (over)written into dataset.
dims_countseach array member specify the amount of data over dataset's each dimensions from InputArray that will be written into dataset.

Writes Mat object into targeted dataset.

Note
If dataset is not created and does not exist it will be created automatically. Only Mat is supported and it must to be continuous. It is thread safe but it is recommended that writes to happen over separate non overlapping regions. Multiple datasets can be written inside single hdf5 file.
  • Example below writes a 100x100 CV_64FC2 matrix into a dataset. No dataset precreation required. If routine is called multiple times dataset will be just overwritten:
    // dual channel hilbert matrix
    cv::Mat H(100, 100, CV_64FC2);
    for(int i = 0; i < H.rows; i++)
    for(int j = 0; j < H.cols; j++)
    {
    H.at<cv::Vec2d>(i,j)[0] = 1./(i+j+1);
    H.at<cv::Vec2d>(i,j)[1] = -1./(i+j+1);
    count++;
    }
    // open / autocreate hdf5 file
    cv::Ptr<cv::hdf::HDF5> h5io = cv::hdf::open( "mytest.h5" );
    // write / overwrite dataset
    h5io->dswrite( H, "hilbert" );
    // release
    h5io->close();
  • Example below writes a smaller 50x100 matrix into 100x100 compressed space optimised by two 50x100 chunks. Matrix is written twice into first half (0->50) and second half (50->100) of data space using offset.
    // dual channel hilbert matrix
    cv::Mat H(50, 100, CV_64FC2);
    for(int i = 0; i < H.rows; i++)
    for(int j = 0; j < H.cols; j++)
    {
    H.at<cv::Vec2d>(i,j)[0] = 1./(i+j+1);
    H.at<cv::Vec2d>(i,j)[1] = -1./(i+j+1);
    count++;
    }
    // open / autocreate hdf5 file
    cv::Ptr<cv::hdf::HDF5> h5io = cv::hdf::open( "mytest.h5" );
    // optimise dataset by two chunks
    int chunks[2] = { 50, 100 };
    // create 100x100 CV_64FC2 compressed space
    h5io->dscreate( 100, 100, CV_64FC2, "hilbert", 9, chunks );
    // write into first half
    int offset1[2] = { 0, 0 };
    h5io->dswrite( H, "hilbert", offset1 );
    // write into second half
    int offset2[2] = { 50, 0 };
    h5io->dswrite( H, "hilbert", offset2 );
    // release
    h5io->close();

§ grcreate()

virtual void cv::hdf::HDF5::grcreate ( String  grlabel)
pure virtual

Create a group.

Parameters
grlabelspecify the hdf5 group label.

Create a hdf5 group.

Note
Groups are useful for better organise multiple datasets. It is possible to create subgroups within any group. Existence of a particular group can be checked using hlexists(). In case of subgroups label would be e.g: 'Group1/SubGroup1' where SubGroup1 is within the root group Group1.
  • In this example Group1 will have one subgrup labeled SubGroup1:
    // open / autocreate hdf5 file
    cv::Ptr<cv::hdf::HDF5> h5io = cv::hdf::open( "mytest.h5" );
    // create Group1 if does not exists
    if ( ! h5io->hlexists( "Group1" ) )
    h5io->grcreate( "Group1" );
    else
    printf("Group1 already created, skipping\n" );
    // create SubGroup1 if does not exists
    if ( ! h5io->hlexists( "Group1/SubGroup1" ) )
    h5io->grcreate( "Group1/SubGroup1" );
    else
    printf("SubGroup1 already created, skipping\n" );
    // release
    h5io->close();
Note
When a dataset is created with dscreate() or kpcreate() it can be created right within a group by specifying full path within the label, in our example would be: 'Group1/SubGroup1/MyDataSet'. It is not thread safe.

§ hlexists()

virtual bool cv::hdf::HDF5::hlexists ( String  label) const
pure virtual

Check if label exists or not.

Parameters
labelspecify the hdf5 dataset label.

Returns true if dataset exists, and false if does not.

Note
Checks if dataset, group or other object type (hdf5 link) exists under the label name. It is thread safe.

§ kpcreate()

virtual void cv::hdf::HDF5::kpcreate ( const int  size,
String  kplabel,
const int  compresslevel = H5_NONE,
const int  chunks = H5_NONE 
) const
pure virtual

Create and allocate special storage for cv::KeyPoint dataset.

Parameters
sizedeclare fixed number of KeyPoints
kplabelspecify the hdf5 dataset label, any existing dataset with the same label will be overwritten.
compresslevelspecify the compression level 0-9 to be used, H5_NONE is default and means no compression.
chunkseach array member specify chunking sizes to be used for block i/o, H5_NONE is default and means no compression.
Note
If the dataset already exists an exception will be thrown. Existence of the dataset can be checked using hlexists().
  • See example below that creates space for 100 keypoints in the dataset:
    // open hdf5 file
    cv::Ptr<cv::hdf::HDF5> h5io = cv::hdf::open( "mytest.h5" );
    if ( ! h5io->hlexists( "keypoints" ) )
    h5io->kpcreate( 100, "keypoints" );
    else
    printf("DS already created, skipping\n" );
Note
A value of H5_UNLIMITED for size means unlimited keypoints, thus is possible to expand anytime such dataset by adding or inserting. Presence of H5_UNLIMITED require to define custom chunking. No default chunking will be defined in unlimited scenario since default size on that dimension will be zero, and will grow once dataset is written. Writing into dataset that have H5_UNLIMITED on some of its dimension requires kpinsert() that allow growth on unlimited dimension instead of kpwrite() that allows to write only in predefined data space.

§ kpgetsize()

virtual int cv::hdf::HDF5::kpgetsize ( String  kplabel,
int  dims_flag = HDF5::H5_GETDIMS 
) const
pure virtual

Fetch keypoint dataset size.

Parameters
kplabelspecify the hdf5 dataset label to be measured.
dims_flagwill fetch dataset dimensions on H5_GETDIMS, and dataset maximum dimensions on H5_GETMAXDIMS.

Returns size of keypoints dataset.

Note
Resulting size will match the amount of keypoints. By default H5_GETDIMS will return actual dataset dimension. Using H5_GETMAXDIM flag will get maximum allowed dimension which normally match actual dataset dimension but can hold H5_UNLIMITED value if dataset was prepared in unlimited mode. It can be useful to check existing dataset dimension before overwrite it as whole or subset. Trying to write with oversized source data into dataset target will thrown exception. The H5_GETCHUNKDIMS will return the dimension of chunk if dataset was created with chunking options otherwise returned vector size will be zero.

§ kpinsert()

virtual void cv::hdf::HDF5::kpinsert ( const vector< KeyPoint keypoints,
String  kplabel,
const int  offset = H5_NONE,
const int  counts = H5_NONE 
) const
pure virtual

Insert or overwrite list of KeyPoint into specified dataset and autoexpand dataset size if unlimited property allows.

Parameters
keypointsspecify keypoints data list to be written.
kplabelspecify the target hdf5 dataset label.
offsetspecify the offset location on dataset from where keypoints will be (over)written into dataset.
countsspecify the amount of keypoints that will be written into dataset.

Writes vector<KeyPoint> object into targeted dataset and autoexpand dataset dimension if allowed.

Note
Unlike kpwrite(), datasets are not created automatically. If dsinsert() happen over outer region of dataset and dataset has been created in unlimited mode then dataset is expanded, otherwise exception is thrown. To create datasets with unlimited property see kpcreate() and the optional H5_UNLIMITED flag at creation time. It is not thread safe over same dataset but multiple datasets can be merged inside single hdf5 file.
  • Example below creates unlimited space for keypoints storage, and inserts a list of 10 keypoints ten times into that space. Final dataset will have 100 keypoints. Chunks size is 10 just optimized against list of keypoints. If routine is called multiple times dataset will be just overwritten:
    // generate 10 dummy keypoints
    std::vector<cv::KeyPoint> keypoints;
    for(int i = 0; i < 10; i++)
    keypoints.push_back( cv::KeyPoint(i, -i, 1, -1, 0, 0, -1) );
    // open / autocreate hdf5 file
    cv::Ptr<cv::hdf::HDF5> h5io = cv::hdf::open( "mytest.h5" );
    // create unlimited size space with chunk size of 10
    h5io->kpcreate( cv::hdf::HDF5::H5_UNLIMITED, "keypoints", -1, 10 );
    // insert 10 times same 10 keypoints
    for(int i = 0; i < 10; i++)
    h5io->kpinsert( keypoints, "keypoints", i * 10 );
    // release
    h5io->close();

§ kpread()

virtual void cv::hdf::HDF5::kpread ( vector< KeyPoint > &  keypoints,
String  kplabel,
const int  offset = H5_NONE,
const int  counts = H5_NONE 
) const
pure virtual

Read specific keypoint dataset from hdf5 file into vector<KeyPoint> object.

Parameters
keypointsvector<KeyPoint> container where data reads will be returned.
kplabelspecify the source hdf5 dataset label.
offsetspecify the offset location over dataset from where read starts.
countsspecify the amount of keypoints from dataset to read.

Reads out vector<KeyPoint> object reflecting the stored dataset.

Note
If hdf5 file does not exist an exception will be thrown. Use hlexists() to check dataset presence. It is thread safe.
  • Example below reads a dataset containing keypoints starting with second entry:
    // open hdf5 file
    cv::Ptr<cv::hdf::HDF5> h5io = cv::hdf::open( "mytest.h5" );
    // blank KeyPoint container
    std::vector<cv::KeyPoint> keypoints;
    // read keypoints starting second one
    h5io->kpread( keypoints, "keypoints", 1 );
    // release
    h5io->close();
  • Example below perform read of 3 keypoints from second entry.
    // open hdf5 file
    cv::Ptr<cv::hdf::HDF5> h5io = cv::hdf::open( "mytest.h5" );
    // blank KeyPoint container
    std::vector<cv::KeyPoint> keypoints;
    // read three keypoints starting second one
    h5io->kpread( keypoints, "keypoints", 1, 3 );
    // release
    h5io->close();

§ kpwrite()

virtual void cv::hdf::HDF5::kpwrite ( const vector< KeyPoint keypoints,
String  kplabel,
const int  offset = H5_NONE,
const int  counts = H5_NONE 
) const
pure virtual

Write or overwrite list of KeyPoint into specified dataset of hdf5 file.

Parameters
keypointsspecify keypoints data list to be written.
kplabelspecify the target hdf5 dataset label.
offsetspecify the offset location on dataset from where keypoints will be (over)written into dataset.
countsspecify the amount of keypoints that will be written into dataset.

Writes vector<KeyPoint> object into targeted dataset.

Note
If dataset is not created and does not exist it will be created automatically. It is thread safe but it is recommended that writes to happen over separate non overlapping regions. Multiple datasets can be written inside single hdf5 file.
  • Example below writes a 100 keypoints into a dataset. No dataset precreation required. If routine is called multiple times dataset will be just overwritten:
    // generate 100 dummy keypoints
    std::vector<cv::KeyPoint> keypoints;
    for(int i = 0; i < 100; i++)
    keypoints.push_back( cv::KeyPoint(i, -i, 1, -1, 0, 0, -1) );
    // open / autocreate hdf5 file
    cv::Ptr<cv::hdf::HDF5> h5io = cv::hdf::open( "mytest.h5" );
    // write / overwrite dataset
    h5io->kpwrite( keypoints, "keypoints" );
    // release
    h5io->close();
  • Example below uses smaller set of 50 keypoints and writes into compressed space of 100 keypoints optimised by 10 chunks. Same keypoint set is written three times, first into first half (0->50) and at second half (50->75) then into remaining slots (75->99) of data space using offset and count parameters to settle the window for write access.If routine is called multiple times dataset will be just overwritten:
    // generate 50 dummy keypoints
    std::vector<cv::KeyPoint> keypoints;
    for(int i = 0; i < 50; i++)
    keypoints.push_back( cv::KeyPoint(i, -i, 1, -1, 0, 0, -1) );
    // open / autocreate hdf5 file
    cv::Ptr<cv::hdf::HDF5> h5io = cv::hdf::open( "mytest.h5" );
    // create maximum compressed space of size 100 with chunk size 10
    h5io->kpcreate( 100, "keypoints", 9, 10 );
    // write into first half
    h5io->kpwrite( keypoints, "keypoints", 0 );
    // write first 25 keypoints into second half
    h5io->kpwrite( keypoints, "keypoints", 50, 25 );
    // write first 25 keypoints into remained space of second half
    h5io->kpwrite( keypoints, "keypoints", 75, 25 );
    // release
    h5io->close();

The documentation for this class was generated from the following file: