path: root/doxygen/dox/high_level/extension.dox

/** \defgroup H5LR Extensions
 *
 * <em>Working with region references, hyperslab selections,
 * and bit-fields (H5LR, H5LT)</em>
 *
 * 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 (
 * <a href="https://support.hdfgroup.org/projects/jpss/documentation">
 * project</a>, <a href="https://gamma.hdfgroup.org/ftp/pub/outgoing/NPOESS/source">
 * software </a>).
 * 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 <a href="https://gamma.hdfgroup.org/ftp/pub/outgoing/NPOESS/source">
 * software </a>
 * must be separately downloaded and installed.
 *
 * A comprehensive guide to this library,
 * <a href="https://support.hdfgroup.org/projects/jpss/documentation/HL/UG/NPOESS_HL-UG.pdf">
 * <em>User Guide to the HDF5 High-level Library for Handling Region References and Hyperslab Selections</em></a>
 * is available at
 * https://support.hdfgroup.org/projects/jpss/documentation/HL/UG/NPOESS_HL-UG.pdf.
 *
 * - \ref H5LRcopy_reference
 *        \n Copies data from the specified dataset to a new location and creates a reference to it.
 * - \ref H5LRcopy_region
 *        \n  Copies data from a referenced region to a region in a destination dataset.
 * - \ref H5LRcreate_ref_to_all
 *        \n  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.
 * - \ref H5LRcreate_region_references
 *        \n Creates an array of region references using an array of paths to
 *        datasets and an array of corresponding hyperslab descriptions.
 * - \ref H5LRget_region_info
 *        \n Retrieves information about the data a region reference points to.
 * - \ref H5LRmake_dataset
 *        \n Creates and writes a dataset containing a list of region references.
 * - \ref H5LRread_region
 *        \n  Retrieves raw data pointed to by a region reference to an application buffer.
 * - \ref H5LTcopy_region
 *        \n Copies data from a specified region in a source dataset to a specified region in a destination dataset.
 * - \ref H5LTread_bitfield_value
 *        \n Retrieves the values of quality flags for each element to the application provided buffer.
 * - \ref H5LTread_region
 *        \n Reads selected data to an application buffer.
 *
 */

/*-------------------------------------------------------------------------
 *
 * Make dataset functions
 *
 *-------------------------------------------------------------------------
 */

/**
 * --------------------------------------------------------------------------
 * \ingroup H5LR
 *
 * \brief Creates and writes a dataset containing a list of region references.
 *
 * \fgdta_loc_id
 * \param[in] path          Path to the dataset being created
 * \param[in] type_id       Datatype of the dataset
 * \param[in] buf_size      Size of the \p loc_id_ref and \p buf arrays
 * \param[in] loc_id_ref    Array of object identifiers; each identifier
 *                          describes to which HDF5 file the corresponding
 *                          region reference belongs to
 * \param[in] buf           Array of region references
 *
 * \return \herr_t
 *
 * \details Given an array of size \p buf_size of region references \p buf,
 *          the function will create a dataset with path \p path, at location
 *          specified by \p loc_id and of a datatype specified by \p 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 \p buf array belongs to the file identified
 *          by the corresponding object identifiers in the array \p loc_id_ref.
 *
 *          If \p path does not exist in \p loc_id then the function will
 *          create the path specified by \p path automatically.
 *
 * \version 1.1 Fortran wrapper introduced in this release.
 *
 * \since 1.0
 *
 */
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);

/*-------------------------------------------------------------------------
 *
 * Make and manipulate dataset region references functions
 *
 *-------------------------------------------------------------------------
 */

/**
 * --------------------------------------------------------------------------
 * \ingroup H5LR
 *
 * \brief Creates an array of region references using an array of paths to
 *        datasets and an array of corresponding hyperslab descriptions.
 *
 * \param[in] obj_id        File identifier for the HDF5 file containing
 *                          the referenced regions or an object identifier
 *                          for any object in that file
 * \param[in] num_elem      Number of elements in the \p path and \p buf arrays
 * \param[in] path          Array of pointers to strings, which contain
 *                          the paths to the target datasets for the region references
 * \param[in] block_coord   Array of hyperslab coordinate
 * \param[out] buf          Buffer for returning an array of region references
 *
 * \return \herr_t
 *
 * \note    **Motivation:**
 * \note    H5LRcreate_region_references() is useful when creating
 *          large numbers of similar region references.
 *
 * \details 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.
 *
 *          \p path parameter is an array of pointers to strings.
 *
 *          \p num_elem specifies the number of region references to be created,
 *          thus specifying the size of the \p path and \p _buf arrays.
 *
 *          Buffer \p 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 \p 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 \p 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.
 *
 * \version 1.1 Fortran wrapper introduced in this release.
 *
 * \since 1.0
 *
 */
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);

/**
 * --------------------------------------------------------------------------
 * \ingroup H5LR
 *
 * \brief Copies data from the specified dataset to a new location and creates a reference to it.
 *
 * \param[in] obj_id        Identifier of any object in a file an HDF5 reference belongs to
 * \param[in] ref           Reference to the datasets region
 * \param[in] file          Name of the destination file
 * \param[in] path          Full path to the destination dataset
 * \param[in] block_coord   Hyperslab coordinates in the destination dataset
 * \param[out] ref_new      Region reference to the new location of data
 *
 * \return \herr_t
 *
 * \details 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 \p path in the file with the name \p file, and to location
 *          specified by the hyperslab coordinates \p block_coord. It will
 *          create the region reference \p 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 \p 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 \p block_coord would be {2, 2, 5, 4}.
 *
 * \version 1.1 Fortran wrapper introduced in this release.
 *
 * \since 1.0
 *
 */
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);

/**
 * --------------------------------------------------------------------------
 * \ingroup H5LR
 *
 * \brief Copies data from a referenced region to a region in a destination dataset.
 *
 * \param[in] obj_id        Identifier of any object in a file
 *                          dataset region reference belongs to
 * \param[in] ref           Dataset region reference
 * \param[in] file          Name of the destination file
 * \param[in] path          Full path to the destination dataset
 * \param[in] block_coord   Hyperslab coordinates in the destination dataset
 *
 * \return \herr_t
 *
 * \details Given a dataset region reference \p ref in a source file
 *          specified by an identifier of any object in that file
 *          \p obj_id, the function will write data to the existing
 *          dataset \p path in file \p file to the simple hyperslab
 *          specified by \p block_coord.
 *
 *          Buffer \p 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 \p block_coord would be {2, 2, 5, 4}.
 *
 *          If \p 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 \p path and \p block_coord will be
 *          disregarded.
 *
 * \version 1.1 Fortran wrapper introduced in this release.
 *
 * \since 1.0
 *
 */
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);

/**
 * --------------------------------------------------------------------------
 * \ingroup H5LR
 *
 * \brief 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.
 *
 * \fg_loc_id
 * \param[in] group_path    Absolute or relative path to the group at which traversal starts
 * \param[in] ds_path       Absolute or relative path to the dataset with region references to be created
 * \param[in] index_type    Index_type; see valid values below in description
 * \param[in] order         Order in which index is traversed; see valid values below in description
 * \param[in] ref_type      Reference type; see valid values below in description
 *
 * \return \herr_t
 *
 * \details 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 \p ds_path in a file specified by the
 *          \p 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 \p ref_type parameter. When \p 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 \p loc_id
 *          and \p group_path parameters. In a like manner, when
 *          \p ref_type is #H5R_OBJECT, each object reference points to
 *          an object (a group or a dataset) encountered by H5Lvisit().
 *
 *          If \p ds_path does not exist in \p loc_id then the function
 *          will create the path specified by \p ds_path automatically.
 *
 *          \p index_type specifies the index to be used.
 *          Valid values include the following:
 *          - #H5_INDEX_NAME        Alphanumeric index on name
 *          - #H5_INDEX_CRT_ORDER   Index on creation order
 *
 *          \p order specifies the order in which objects are to be
 *          inspected along the index specified in \p index_type.
 *          Valid values include the following:
 *          - #H5_ITER_INC      Increasing order
 *          - #H5_ITER_DEC      Decreasing order
 *          - #H5_ITER_NATIVE   Fastest available order
 *
 *          For more detailed information on these two parameters,
 *          @see H5Lvisit().
 *
 *          \p ref_type specifies the type of the reference to be used.
 *          Valid values include the following:
 *          - #H5R_DATASET_REGION   Dataset region reference
 *          - #H5R_OBJECT           Object reference
 *
 * \version 1.1 Fortran wrapper introduced in this release.
 *
 * \since 1.0
 *
 */
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);

/*-------------------------------------------------------------------------
 *
 * Read dataset functions
 *
 *-------------------------------------------------------------------------
 */

/**
 * --------------------------------------------------------------------------
 * \ingroup H5LR
 *
 * \brief Retrieves raw data pointed to by a region reference 
 *        to an application buffer.
 *
 * \param[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
 * \param[in] ref           Region reference specifying data to be read in
 * \param[in] mem_type      Memory datatype of data read from referenced
 *                          region into the application buffer
 * \param[in,out] numelem   Number of elements to be read into buffer \p buf
 * \param[out] buf          Buffer in which data is returned to the application
 *
 * \return \herr_t
 *
 * \details H5LRread_region() reads data pointed to by the region
 *          reference \p ref into the buffer \p buf.
 *
 *          \p numelem specifies the number of elements to be read
 *          into \p buf. When the size of the reference region is unknown,
 *          H5LRread_region() can be called with \p buf set to NULL;
 *          the number of elements in the referenced region will be returned
 *          in \p numelem.
 *
 *          The buffer buf must be big enough to hold \p numelem elements
 *          of type \p mem_type. For example, if data is read from the referenced
 *          region into an integer buffer, \p mem_type should be #H5T_NATIVE_INT
 *          and the buffer must be at least \c sizeof(int) * \p numelem  bytes
 *          in size. This buffer must be allocated by the application.
 *
 * \version 1.1 Fortran wrapper introduced in this release.
 *
 * \since 1.0
 *
 */
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 );

/*-------------------------------------------------------------------------
 *
 * Query dataset functions
 *
 *-------------------------------------------------------------------------
 */

/**
 * --------------------------------------------------------------------------
 * \ingroup H5LR
 *
 * \brief Retrieves information about the data a region reference points to.
 *
 * \param[in] obj_id        Identifier of any object in an HDF5 file the region reference belongs to.
 * \param[in] ref           Region reference to query
 * \param[in,out] len       Size of the buffer to store \p path in.
 *                          NOTE: if \p *path is not NULL then \p *len must be the appropriate length
 * \param[out] path         Full path that a region reference points to
 * \param[out] rank         The number of dimensions of the dataset
 *                          dimensions of the dataset pointed by region reference.
 * \param[out] dtype        Datatype of the dataset pointed by the region reference.
 * \param[out] sel_type     Type of the selection (point or hyperslab)
 * \param[in,out] numelem   Number of coordinate blocks or selected elements.
 * \param[out] buf          Buffer containing description of the region pointed by region reference
 *
 * \return \herr_t
 *
 * \details H5LRget_region_info() queries information about the data
 *          pointed by a region reference \p 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 \p 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 \p ref is a region reference to query.
 *
 *          The parameter \p path is a pointer to application allocated
 *          buffer of size \p len+1 to return an absolute path to a dataset
 *          the region reference points to.
 *
 *          The parameter \p 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 \p len.
 *
 *          The parameter \p 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 \p numelem describes how many elements will be
 *          placed in the buffer \p buf. The number should be interpreted
 *          using the value of \p sel_type.
 *
 *          If value of \p sel_type is #H5S_SEL_HYPERSLABS, the parameter
 *          \p buf contains \p numelem blocks of the coordinates for each
 *          simple hyperslab of the referenced region. Each block has
 *          length \c 2*\p rank and 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 \c 2*\p rank*\p numelem. If region reference
 *          points to a contiguous sub-array, then the value of \p 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 \p sel_type is #H5S_SEL_POINTS, the parameter \p buf
 *          contains \p numelem blocks of the coordinates for each selected
 *          point of the referenced region. Each block has length \p rank
 *          and contains coordinates of the element. The total size of the
 *          buffer to hold the description of the region will be
 *          \p rank* \p numelem.
 *
 *
 * \version 1.1 Fortran wrapper introduced in this release.
 *
 * \since 1.0
 *
 */
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 );



/*-------------------------------------------------------------------------
 *
 * Make dataset functions
 *
 *-------------------------------------------------------------------------
 */

/**
 * --------------------------------------------------------------------------
 * \ingroup H5LR
 *
 * \brief Copies data from a specified region in a source dataset
 *        to a specified region in a destination dataset
 *
 * \param[in] file_src          Name of the source file
 * \param[in] path_src          Full path to the source dataset
 * \param[in] block_coord_src   Hyperslab coordinates in the source dataset
 * \param[in] file_dest         Name of the destination file
 * \param[in] path_dest         Full path to the destination dataset
 * \param[in] block_coord_dset  Hyperslab coordinates in the destination dataset
 *
 * \return \herr_t
 *
 * \details Given a path to a dataset \p path_src in a file with the
 *          name \p file_src, and description of a simple hyperslab of
 *          the source \p block_coord_src, the function will write data
 *          to the dataset \p path_dest in file \p file_dest to the
 *          simple hyperslab specified by \p block_coord_dset.
 *          The arrays \p block_coord_src and \p 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 \p block_coord_dset would be {2, 2, 5, 4}.
 *
 *          If \p 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 \p path_dest and
 *          \p block_coord_dset will be disregarded.
 *
 * \version 1.1 Fortran wrapper introduced in this release.
 *
 * \since 1.0
 *
 */
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);

/*-------------------------------------------------------------------------
 *
 * Read dataset functions
 *
 *-------------------------------------------------------------------------
 */

/**
 * --------------------------------------------------------------------------
 * \ingroup H5LR
 *
 * \brief Reads selected data to an application buffer.
 *
 * \param[in] file          Name of file
 * \param[in] path          Full path to a dataset
 * \param[in] block_coord   Hyperslab coordinates
 * \param[in] mem_type      Memory datatype, describing the buffer the referenced data will be read into
 * \param[out] buf          Buffer containing data from the referenced region
 *
 * \return \herr_t
 *
 * \details H5LTread_region() reads data from a region described by
 *          the hyperslab coordinates in \p block_coord, located in
 *          the dataset specified by its absolute path \p path in a
 *          file specified by its name \p file. Data is read into a
 *          buffer \p buf of the datatype that corresponds to the
 *          HDF5 datatype specified by \p mem_type.
 *
 *          Buffer \p 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 \p block_coord would be {2, 2, 5, 4}.
 *
 *          Buffer \p buf should be big enough to hold selected elements
 *          of the type that corresponds to the \p mem_type
 *
 * \version 1.1 Fortran wrapper introduced in this release.
 *
 * \since 1.0
 *
 */
H5_HLRDLL herr_t  H5LTread_region(const char *file,
                  const char *path,
                  const hsize_t *block_coord,
                  hid_t mem_type,
                  void *buf );

/**
 * --------------------------------------------------------------------------
 * \ingroup H5LR
 *
 * \brief Retrieves the values of quality flags for each element
 *        to the application provided buffer.
 *
 * \param[in] dset_id   Identifier of the dataset with bit-field values
 * \param[in] num_values    Number of the values to be extracted
 * \param[in] offset        Array of staring bits to be extracted from
 *                          the element; valid values: 0 (zero) through 7
 * \param[in] lengths       Array of the number of bits to be extracted for each value
 * \param[in] space         Dataspace identifier, describing the elements
 *                          to be read from the dataset with bit-field values
 * \param[out] buf          Buffer to read the values in
 *
 * \return \herr_t
 *
 * \details H5LTread_bitfield_value() reads selected elements from a
 *          dataset specified by its identifier \p dset_id, and unpacks
 *          the bit-field values to a buffer \p buf.
 *
 *          The parameter \p space is a space identifier that indicates
 *          which elements of the dataset should be read.
 *
 *          The parameter \p offset is an array of length \p num_values;
 *          the i<sup>th</sup> element of the array holds the value of the
 *          starting bit of the i<sup>th</sup> bit-field value.
 *          Valid values are: 0 (zero) through 7.
 *
 *          The parameter \p lengths is an array of length \p num_values;
 *          the i<sup>th</sup> element of the array holds the number of
 *          bits to be extracted for the i<sup>th</sup> 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 \p buf is allocated by the application and should be big
 *          enough to hold \c num_sel_elem * \p num_values elements of the
 *          specified type, where \c num_sel_elem is a number of the elements
 *          to be read from the dataset. Data in the buffer is organized
 *          as \p num_values values for the first element, followed by the
 *          \p num_values values for the second element, ... , followed by
 *          the \p num_values values for the
 *          \c num_selected_elem<sup>th</sup> element.
 *
 * \version 1.1 Fortran wrapper introduced in this release.
 *
 * \since 1.0
 *
 */
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);