 |
HDF5
1.15.0
API Reference
|
|
|
HDF5
1.15.0
API Reference
|
|
Working with region references, hyperslab selections, and bit-fields (H5LR, H5LT)
The following reference manual entries describe high-level HDF5 C and Fortran APIs for working with region references, hyperslab selections, and bit-fields. These functions were created as part of a project supporting NPP/NPOESS Data Production and Exploitation ( project, software ). While they were written to facilitate access to NPP, NPOESS, and JPSS data in the HDF5 format, these functions may be useful to anyone working with region references, hyperslab selections, or bit-fields.
Note that these functions are not part of the standard HDF5 distribution; the software must be separately downloaded and installed.
A comprehensive guide to this library, User Guide to the HDF5 High-level Library for Handling Region References and Hyperslab Selections is available at https://support.hdfgroup.org/projects/jpss/documentation/HL/UG/NPOESS_HL-UG.pdf.
Functions | |
| H5_HLRDLL herr_t | H5LRmake_dataset (hid_t loc_id, const char *path, hid_t type_id, const size_t buf_size, const hid_t *loc_id_ref, const hdset_reg_ref_t *buf) |
| Creates and writes a dataset containing a list of region references. | |
| H5_HLRDLL herr_t | H5LRcreate_region_references (hid_t obj_id, size_t num_elem, const char **path, const hsize_t *block_coord, hdset_reg_ref_t *buf) |
| Creates an array of region references using an array of paths to datasets and an array of corresponding hyperslab descriptions. | |
| H5_HLRDLL herr_t | H5LRcopy_reference (hid_t obj_id, hdset_reg_ref_t *ref, const char *file, const char *path, const hsize_t *block_coord, hdset_reg_ref_t *ref_new) |
| Copies data from the specified dataset to a new location and creates a reference to it. | |
| H5_HLRDLL herr_t | H5LRcopy_region (hid_t obj_id, hdset_reg_ref_t *ref, const char *file, const char *path, const hsize_t *block_coord) |
| Copies data from a referenced region to a region in a destination dataset. | |
| H5_HLRDLL herr_t | H5LRcreate_ref_to_all (hid_t loc_id, const char *group_path, const char *ds_path, H5_index_t index_type, H5_iter_order_t order, H5R_type_t ref_type) |
| Creates a dataset with the region references to the data in all datasets located under a specified group in a file or creates a dataset with object references to all objects (groups or datasets) located under a specified group in a file. | |
| H5_HLRDLL herr_t | H5LRread_region (hid_t obj_id, const hdset_reg_ref_t *ref, hid_t mem_type, size_t *numelem, void *buf) |
| Retrieves raw data pointed to by a region reference to an application buffer. | |
| H5_HLRDLL herr_t | H5LRget_region_info (hid_t obj_id, const hdset_reg_ref_t *ref, size_t *len, char *path, int *rank, hid_t *dtype, H5S_sel_type *sel_type, size_t *numelem, hsize_t *buf) |
| Retrieves information about the data a region reference points to. | |
| H5_HLRDLL herr_t | H5LTcopy_region (const char *file_src, const char *path_src, const hsize_t *block_coord_src, const char *file_dest, const char *path_dest, const hsize_t *block_coord_dset) |
| Copies data from a specified region in a source dataset to a specified region in a destination dataset. | |
| H5_HLRDLL herr_t | H5LTread_region (const char *file, const char *path, const hsize_t *block_coord, hid_t mem_type, void *buf) |
| Reads selected data to an application buffer. | |
| H5_HLRDLL herr_t | H5LTread_bitfield_value (hid_t dset_id, int num_values, const unsigned *offset, const unsigned *lengths, hid_t space, int *buf) |
| Retrieves the values of quality flags for each element to the application provided buffer. | |
| H5_HLRDLL herr_t H5LRcopy_reference | ( | hid_t | obj_id, |
| hdset_reg_ref_t * | ref, | ||
| const char * | file, | ||
| const char * | path, | ||
| const hsize_t * | block_coord, | ||
| hdset_reg_ref_t * | ref_new | ||
| ) |
Copies data from the specified dataset to a new location and creates a reference to it.
| [in] | obj_id | Identifier of any object in a file an HDF5 reference belongs to |
| [in] | ref | Reference to the datasets region |
| [in] | file | Name of the destination file |
| [in] | path | Full path to the destination dataset |
| [in] | block_coord | Hyperslab coordinates in the destination dataset |
| [out] | ref_new | Region reference to the new location of data |
Given a data set pointed to by a region reference, the function H5LRcopy_reference() will copy the hyperslab data referenced by a datasets region reference into existing dataset specified by its path path in the file with the name file, and to location specified by the hyperslab coordinates block_coord. It will create the region reference ref_new to point to the new location. The number of elements in the old and newly specified regions has to be the same.
Buffer block_coord has size 2*rank and is the coordinates of the starting point following by the coordinates of the ending point of the hyperslab. For example, to extract a rectangular hyperslab region starting at element (2,2) to element (5,4) then block_coord would be {2, 2, 5, 4}.
| H5_HLRDLL herr_t H5LRcopy_region | ( | hid_t | obj_id, |
| hdset_reg_ref_t * | ref, | ||
| const char * | file, | ||
| const char * | path, | ||
| const hsize_t * | block_coord | ||
| ) |
Copies data from a referenced region to a region in a destination dataset.
| [in] | obj_id | Identifier of any object in a file dataset region reference belongs to |
| [in] | ref | Dataset region reference |
| [in] | file | Name of the destination file |
| [in] | path | Full path to the destination dataset |
| [in] | block_coord | Hyperslab coordinates in the destination dataset |
Given a dataset region reference ref in a source file specified by an identifier of any object in that file obj_id, the function will write data to the existing dataset path in file file to the simple hyperslab specified by block_coord.
Buffer block_coord has size 2*rank and is the coordinates of the starting point following by the coordinates of the ending point of the hyperslab. For example, to specify a rectangular hyperslab destination region starting at element (2,2) to element (5,4) then block_coord would be {2, 2, 5, 4}.
If path does not exist in the destination file (as may be the case when writing to a new file) then the dataset will be copied directly to the path and block_coord will be disregarded.
| H5_HLRDLL herr_t H5LRcreate_ref_to_all | ( | hid_t | loc_id, |
| const char * | group_path, | ||
| const char * | ds_path, | ||
| H5_index_t | index_type, | ||
| H5_iter_order_t | order, | ||
| H5R_type_t | ref_type | ||
| ) |
Creates a dataset with the region references to the data in all datasets located under a specified group in a file or creates a dataset with object references to all objects (groups or datasets) located under a specified group in a file.
| [in] | loc_id | Location identifier. The identifier may be that of a file or group. |
| [in] | group_path | Absolute or relative path to the group at which traversal starts |
| [in] | ds_path | Absolute or relative path to the dataset with region references to be created |
| [in] | index_type | Index_type; see valid values below in description |
| [in] | order | Order in which index is traversed; see valid values below in description |
| [in] | ref_type | Reference type; see valid values below in description |
H5LRcreate_ref_to_all() creates a dataset with the region references to the data in all datasets located under a specified group in a file or creates a dataset with object references to all objects (groups or datasets) located under a specified group in a file.
Given a dataset path ds_path in a file specified by the loc_id identifier, the function H5LRcreate_ref_to_all() will create a contiguous one-dimensional dataset with the region references or object references depending on the value of the ref_type parameter. When ref_type is H5R_DATASET_REGION, each region reference points to all data in a dataset encountered by an internally called H5Lvisit() routine, which starts at the group specified by the loc_id and group_path parameters. In a like manner, when ref_type is H5R_OBJECT, each object reference points to an object (a group or a dataset) encountered by H5Lvisit().
If ds_path does not exist in loc_id then the function will create the path specified by ds_path automatically.
index_type specifies the index to be used. Valid values include the following:
order specifies the order in which objects are to be inspected along the index specified in index_type. Valid values include the following:
For more detailed information on these two parameters,
ref_type specifies the type of the reference to be used. Valid values include the following:
| H5_HLRDLL herr_t H5LRcreate_region_references | ( | hid_t | obj_id, |
| size_t | num_elem, | ||
| const char ** | path, | ||
| const hsize_t * | block_coord, | ||
| hdset_reg_ref_t * | buf | ||
| ) |
Creates an array of region references using an array of paths to datasets and an array of corresponding hyperslab descriptions.
| [in] | obj_id | File identifier for the HDF5 file containing the referenced regions or an object identifier for any object in that file |
| [in] | num_elem | Number of elements in the path and buf arrays |
| [in] | path | Array of pointers to strings, which contain the paths to the target datasets for the region references |
| [in] | block_coord | Array of hyperslab coordinate |
| [out] | buf | Buffer for returning an array of region references |
H5LRcreate_region_references() creates a list of region references given an array of paths to datasets and another array listing the corner coordinates of the corresponding hyperslabs.
path parameter is an array of pointers to strings.
num_elem specifies the number of region references to be created, thus specifying the size of the path and _buf arrays.
Buffer block_coord has size 2*rank and is the coordinates of the starting point following by the coordinates of the ending point of the hyperslab, repeated num_elem times for each hyperslab. For example, creating two region references to two hyperslabs, one with a rectangular hyperslab region starting at element (2,2) to element (5,4) and the second rectangular region starting at element (7,7) to element (9,10), results in block_coord being {2,2,5,4, 7,7,9,10}.
The rank of the hyperslab will be the same as the rank of the target dataset. H5LRcreate_region_references() will retrieve the rank for each dataset and will use those values to interpret the values in the buffer. Please note that rank may vary from one dataset to another.
| H5_HLRDLL herr_t H5LRget_region_info | ( | hid_t | obj_id, |
| const hdset_reg_ref_t * | ref, | ||
| size_t * | len, | ||
| char * | path, | ||
| int * | rank, | ||
| hid_t * | dtype, | ||
| H5S_sel_type * | sel_type, | ||
| size_t * | numelem, | ||
| hsize_t * | buf | ||
| ) |
Retrieves information about the data a region reference points to.
| [in] | obj_id | Identifier of any object in an HDF5 file the region reference belongs to. |
| [in] | ref | Region reference to query |
| [in,out] | len | Size of the buffer to store path in. NOTE: if *path is not NULL then *len must be the appropriate length |
| [out] | path | Full path that a region reference points to |
| [out] | rank | The number of dimensions of the dataset dimensions of the dataset pointed by region reference. |
| [out] | dtype | Datatype of the dataset pointed by the region reference. |
| [out] | sel_type | Type of the selection (point or hyperslab) |
| [in,out] | numelem | Number of coordinate blocks or selected elements. |
| [out] | buf | Buffer containing description of the region pointed by region reference |
H5LRget_region_info() queries information about the data pointed by a region reference ref. It returns one of the absolute paths to a dataset, length of the path, dataset's rank and datatype, description of the referenced region and type of the referenced region. Any output argument can be NULL if that argument does not need to be returned.
The parameter obj_id is an identifier for any object in the HDF5 file containing the referenced object. For example, it can be an identifier of a dataset the region reference belongs to or an identifier of an HDF5 file the dataset with region references is stored in.
The parameter ref is a region reference to query.
The parameter path is a pointer to application allocated buffer of size len+1 to return an absolute path to a dataset the region reference points to.
The parameter len is a length of absolute path string plus the \0 string terminator. If path parameter is NULL, actual length of the path (+1 for \0 string terminator) is returned to application and can be used to allocate buffer path of an appropriate length len.
The parameter sel_type describes the type of the selected region. Possible values can be H5S_SEL_POINTS for point selection and H5S_SEL_HYPERSLABS for hyperslab selection.
The parameter numelem describes how many elements will be placed in the buffer buf. The number should be interpreted using the value of sel_type.
If value of sel_type is H5S_SEL_HYPERSLABS, the parameter buf contains numelem blocks of the coordinates for each simple hyperslab of the referenced region. Each block has length 2* is organized as follows: <"start" coordinate>, immediately followed by <"opposite" corner coordinate>. The total size of the buffer to hold the description of the region will be rank and2* region reference points to a contiguous sub-array, then the value of rank* Ifnumelem.numelem is 1 and the block contains coordinates of the upper left and lower right corners of the sub-array (or simple hyperslab).
If value of sel_type is H5S_SEL_POINTS, the parameter buf contains numelem blocks of the coordinates for each selected point of the referenced region. Each block has length rank and contains coordinates of the element. The total size of the buffer to hold the description of the region will be rank* numelem.
| H5_HLRDLL herr_t H5LRmake_dataset | ( | hid_t | loc_id, |
| const char * | path, | ||
| hid_t | type_id, | ||
| const size_t | buf_size, | ||
| const hid_t * | loc_id_ref, | ||
| const hdset_reg_ref_t * | buf | ||
| ) |
Creates and writes a dataset containing a list of region references.
| [in] | loc_id | Location identifier. The identifier may be that of a file, group, dataset, named datatype, or attribute. |
| [in] | path | Path to the dataset being created |
| [in] | type_id | Datatype of the dataset |
| [in] | buf_size | Size of the loc_id_ref and buf arrays |
| [in] | loc_id_ref | Array of object identifiers; each identifier describes to which HDF5 file the corresponding region reference belongs to |
| [in] | buf | Array of region references |
Given an array of size buf_size of region references buf, the function will create a dataset with path path, at location specified by loc_id and of a datatype specified by type_id, and will write data associated with each region reference in the order corresponding to the order of the region references in the buffer. It is assumed that all referenced hyperslabs have the same dimensionality, and only the size of the slowest changing dimension may differ. Each reference in the buf array belongs to the file identified by the corresponding object identifiers in the array loc_id_ref.
If path does not exist in loc_id then the function will create the path specified by path automatically.
| H5_HLRDLL herr_t H5LRread_region | ( | hid_t | obj_id, |
| const hdset_reg_ref_t * | ref, | ||
| hid_t | mem_type, | ||
| size_t * | numelem, | ||
| void * | buf | ||
| ) |
Retrieves raw data pointed to by a region reference to an application buffer.
| [in] | obj_id | File identifier for the HDF5 file containing the dataset with the referenced region or an object identifier for any object in that file |
| [in] | ref | Region reference specifying data to be read in |
| [in] | mem_type | Memory datatype of data read from referenced region into the application buffer |
| [in,out] | numelem | Number of elements to be read into buffer buf |
| [out] | buf | Buffer in which data is returned to the application |
H5LRread_region() reads data pointed to by the region reference ref into the buffer buf.
numelem specifies the number of elements to be read into buf. When the size of the reference region is unknown, H5LRread_region() can be called with buf set to NULL; the number of elements in the referenced region will be returned in numelem.
The buffer buf must be big enough to hold numelem elements of type mem_type. For example, if data is read from the referenced region into an integer buffer, mem_type should be H5T_NATIVE_INT and the buffer must be at least sizeof(int) * numelem bytes in size. This buffer must be allocated by the application.
| H5_HLRDLL herr_t H5LTcopy_region | ( | const char * | file_src, |
| const char * | path_src, | ||
| const hsize_t * | block_coord_src, | ||
| const char * | file_dest, | ||
| const char * | path_dest, | ||
| const hsize_t * | block_coord_dset | ||
| ) |
Copies data from a specified region in a source dataset to a specified region in a destination dataset.
| [in] | file_src | Name of the source file |
| [in] | path_src | Full path to the source dataset |
| [in] | block_coord_src | Hyperslab coordinates in the source dataset |
| [in] | file_dest | Name of the destination file |
| [in] | path_dest | Full path to the destination dataset |
| [in] | block_coord_dset | Hyperslab coordinates in the destination dataset |
Given a path to a dataset path_src in a file with the name file_src, and description of a simple hyperslab of the source block_coord_src, the function will write data to the dataset path_dest in file file_dest to the simple hyperslab specified by block_coord_dset. The arrays block_coord_src and block_coord_dset have a length of 2*rank and are the coordinates of the starting point following by the coordinates of the ending point of the hyperslab. For example, to specify a rectangular hyperslab destination region starting at element (2,2) to element (5,4) then block_coord_dset would be {2, 2, 5, 4}.
If path_dest does not exist in the destination file (as may be the case when writing to a new file) then the dataset will be copied directly to the path_dest and block_coord_dset will be disregarded.
| H5_HLRDLL herr_t H5LTread_bitfield_value | ( | hid_t | dset_id, |
| int | num_values, | ||
| const unsigned * | offset, | ||
| const unsigned * | lengths, | ||
| hid_t | space, | ||
| int * | buf | ||
| ) |
Retrieves the values of quality flags for each element to the application provided buffer.
| [in] | dset_id | Identifier of the dataset with bit-field values |
| [in] | num_values | Number of the values to be extracted |
| [in] | offset | Array of staring bits to be extracted from the element; valid values: 0 (zero) through 7 |
| [in] | lengths | Array of the number of bits to be extracted for each value |
| [in] | space | Dataspace identifier, describing the elements to be read from the dataset with bit-field values |
| [out] | buf | Buffer to read the values in |
H5LTread_bitfield_value() reads selected elements from a dataset specified by its identifier dset_id, and unpacks the bit-field values to a buffer buf.
The parameter space is a space identifier that indicates which elements of the dataset should be read.
The parameter offset is an array of length num_values; the ith element of the array holds the value of the starting bit of the ith bit-field value. Valid values are: 0 (zero) through 7.
The parameter lengths is an array of length num_values; the ith element of the array holds the number of bits to be extracted for the ith bit-field value. Extracted bits will be interpreted as a base-2 integer value. Each value will be converted to the base-10 integer value and stored in the application buffer.
Buffer buf is allocated by the application and should be big enough to hold num_sel_elem * num_values elements of the specified type, where num_sel_elem is a number of the elements to be read from the dataset. Data in the buffer is organized as num_values values for the first element, followed by the num_values values for the second element, ... , followed by the num_values values for the num_selected_elemth element.
| H5_HLRDLL herr_t H5LTread_region | ( | const char * | file, |
| const char * | path, | ||
| const hsize_t * | block_coord, | ||
| hid_t | mem_type, | ||
| void * | buf | ||
| ) |
Reads selected data to an application buffer.
| [in] | file | Name of file |
| [in] | path | Full path to a dataset |
| [in] | block_coord | Hyperslab coordinates |
| [in] | mem_type | Memory datatype, describing the buffer the referenced data will be read into |
| [out] | buf | Buffer containing data from the referenced region |
H5LTread_region() reads data from a region described by the hyperslab coordinates in block_coord, located in the dataset specified by its absolute path path in a file specified by its name file. Data is read into a buffer buf of the datatype that corresponds to the HDF5 datatype specified by mem_type.
Buffer block_coord has size 2*rank and is the coordinates of the starting point following by the coordinates of the ending point of the hyperslab. For example, to extract a rectangular hyperslab region starting at element (2,2) to element (5,4) then block_coord would be {2, 2, 5, 4}.
Buffer buf should be big enough to hold selected elements of the type that corresponds to the mem_type
1.9.8