GHdf5.hpp

Go to the documentation of this file.

/***************************************************************************
 *                  GHdf5.hpp - HDF5 file handling class                   *
 * ----------------------------------------------------------------------- *
 *  copyright (C) 2026 by Juergen Knoedlseder                              *
 * ----------------------------------------------------------------------- *
 *                                                                         *
 *  This program is free software: you can redistribute it and/or modify   *
 *  it under the terms of the GNU General Public License as published by   *
 *  the Free Software Foundation, either version 3 of the License, or      *
 *  (at your option) any later version.                                    *
 *                                                                         *
 *  This program is distributed in the hope that it will be useful,        *
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of         *
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          *
 *  GNU General Public License for more details.                           *
 *                                                                         *
 *  You should have received a copy of the GNU General Public License      *
 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.  *
 *                                                                         *
 ***************************************************************************/
/**
 * @file GHdf5.hpp
 * @brief HDF5 file handling class definition
 * @author Juergen Knoedlseder
 */
 
#ifndef GHDF5_HPP
#define GHDF5_HPP
 
/* __ Includes ___________________________________________________________ */
#include <cstdio>            // std::fopen, std::fgets, std::fclose, etc...
#include <stdint.h>          // uint64_t
#include "GBase.hpp"
#include "GXml.hpp"
#include "GFilename.hpp"
 
/* __ Forward declaration ________________________________________________ */
class GXmlElement;
 
/* __ Constants __________________________________________________________ */
 
/* __ Prototypes ________________________________________________________ */
namespace gammalib { namespace hdf5 {
    std::string        fread_data(FILE* fptr, const int& nbytes);
    std::string        fread_data(FILE*              fptr,
                                  const GXmlElement* dataspace,
                                  const GXmlElement* datatype,
                                  const GXmlElement* datalayout,
                                  const GXmlElement* datafilter = NULL);
    std::string        fread_data_chunk(FILE*              fptr,
                                        const GXmlElement* chunk,
                                        const GXmlElement* dataspace,
                                        const GXmlElement* datatype,
                                        const GXmlElement* datalayout,
                                        const GXmlElement* datafilter = NULL);
    int                fread_int(FILE* fptr, const int& nbytes);
    uint32_t           fread_uint32(FILE* fptr, const int& nbytes);
    uint64_t           fread_uint64(FILE* fptr, const int& nbytes);
    std::string        fread_string(FILE* fptr, const int& nbytes);
    std::string        fread_data_as_string(FILE* fptr, const GXmlElement* datatype);
    void               fread_zero(FILE* fptr, const int& nbytes);
    int                data_to_int(const char*        data,
                                   const GXmlElement* datatype);
    double             data_to_double(const char*        data,
                                      const GXmlElement* datatype);
    std::string        data_to_string(const char*        data,
                                      const GXmlElement* datatype);
    std::string        data_filter(const std::string& data,
                                   const GXmlElement* datafilter);
    std::string        data_filter_bitshuffle(const std::string& data,
                                              const GXmlElement* filter);
    const GXmlElement* xml_msg_type(const GXmlElement* header,
                                    const std::string& type,
                                    const int&         number = 0);
    bool               xml_has_msg_type(const GXmlElement* header,
                                        const std::string& type,
                                        const int&         number = 0);
    int                xml_msg_attributes(const GXmlElement* header,
                                          const std::string& name = "");
    const GXmlElement* xml_msg_attribute(const GXmlElement* header,
                                         const std::string& name,
                                         const int&         number = 0);
    bool               xml_has_msg_attribute(const GXmlElement* header,
                                             const std::string& name,
                                             const int&         number = 0);
    std::string        xml_msg_attribute(const GXmlElement* header,
                                         const std::string& name,
                                         const std::string& key);
    const GXmlElement* xml_msg_dataspace(const GXmlElement* header);
    const GXmlElement* xml_msg_datatype(const GXmlElement* header);
    const GXmlElement* xml_msg_datalayout(const GXmlElement* header);
    const GXmlElement* xml_msg_datafilter(const GXmlElement* header);
    std::string        classname(const int& cls);
} }
 
 
/***********************************************************************//**
 * @class GHdf5
 *
 * @brief COSI instrument response function class
 *
 * The COSI instrument response function class defines the function
 * that translates from physical quantities to measured quantities.
 *
 * @todo Complete the class description.
 ***************************************************************************/
class GHdf5 : public GBase {
 
public:
    // Constructors and destructors
    GHdf5(void);
    GHdf5(const GFilename& filename);
    GHdf5(const GHdf5& file);
    virtual ~GHdf5(void);
 
    // Operators
    GHdf5& operator=(const GHdf5 & file);
 
    // Methods
    void               clear(void);
    GHdf5*             clone(void) const;
    std::string        classname(void) const;
    bool               is_empty(void) const;
    void               load(const GFilename& filename);
    void               read(FILE* fptr);
    const GXml&        xml(void) const;
    const GXmlElement* xml_hdf5_entry(const std::string& name) const;
    std::string        print(const GChatter& chatter = NORMAL) const;
 
private:
    // Private methods
    void init_members(void);
    void copy_members(const GHdf5& file);
    void free_members(void);
 
    // Private methods used to read HDF5 files
    void        read_superblock(FILE* fptr);
    void        read_symbol_table_node(FILE*              fptr,
                                       const uint64_t&    address,
                                       const uint64_t&    offset,
                                       const std::string& heap,
                                       GXmlElement*       table,
                                       const int&         indent);
    void        read_symbol_table_entry(FILE*              fptr,
                                        const uint64_t&    address,
                                        const uint64_t&    offset,
                                        const std::string& heap,
                                        GXmlElement*       entry,
                                        const int&         indent);
    void        read_group(FILE*           fptr,
                           const uint64_t& address_btree,
                           const uint64_t& address_heap,
                           GXmlElement*    group,
                           const int&      indent);
    void        read_btree_chunked(FILE*           fptr,
                                   const uint64_t& address,
                                   const int&      dimensions,
                                   GXmlElement*    btree);
    void        read_object_header(FILE*           fptr,
                                   const uint64_t& address,
                                   GXmlElement*    header,
                                   const int&      indent);
    void        read_object_header_v1(FILE*        fptr,
                                      GXmlElement* header,
                                      const int&   indent);
    void        read_object_header_v2(FILE*        fptr,
                                      GXmlElement* header,
                                      const int&   indent);
    void        read_object_header_message(FILE*        fptr,
                                           const int&   type,
                                           GXmlElement* message,
                                           const int&   indent);
    void        read_message_dataspace(FILE*        fptr,
                                       GXmlElement* message,
                                       std::string& msg);
    void        read_message_datatype(FILE*        fptr,
                                      GXmlElement* message,
                                      std::string& msg);
    void        read_message_layout(FILE*        fptr,
                                    GXmlElement* message,
                                    std::string& msg);
    void        read_message_filter(FILE*        fptr,
                                    GXmlElement* message,
                                    std::string& msg);
    void        read_message_attribute(FILE*        fptr,
                                       GXmlElement* message,
                                       std::string& msg);
    std::string global_heap_string(FILE*                fptr,
                                   const uint64_t& address,
                                   const int&      id,
                                   const uint32_t& length);
 
    // Private support methods
    void        debug_msg(const std::string& msg, const int& indent);
    std::string hexaddress(const uint64_t& address);
    std::string extract(const std::string& string, const int& pos);
    int         pad2eight(const int& nbytes);
 
    // Private data members
    GFilename m_filename;    // File name from which data were loaded
    int       m_offset;      // Size of Offsets
    int       m_length;      // Size of Lengths
    GXml      m_xml;         // Metadata parsed from HDF5 file
};
 
 
/***********************************************************************//**
 * @brief Return class name
 *
 * @return String containing the class name ("GHdf5").
 ***************************************************************************/
inline
std::string GHdf5::classname(void) const
{
    return ("GHdf5");
}
 
 
/***********************************************************************//**
 * @brief Signals if HDF5 instance is empty
 *
 * @return True if HDF5 instance is empty.
 ***************************************************************************/
inline
bool GHdf5::is_empty(void) const
{
    return (m_xml.is_empty());
}
 
 
/***********************************************************************//**
 * @brief Return HDF5 metadata as XML object
 *
 * @return HDF5 metadata XML object.
 *
 * Returns the XML object that holds the HDF5 file metadata that is gathered
 * when loading a COSI response file. This method is mainly used for
 * diagnostic purposes.
 ***************************************************************************/
inline
const GXml& GHdf5::xml(void) const
{
    return (m_xml);
}
 
 
/***********************************************************************//**
 * @brief Return "Dataspace" message XML element
 *
 * @param[in] header Pointer to XML header element.
 * @return Pointer to "Dataspace" message XML element.
 *
 * Returns a XML pointer to the first header message of type "Dataspace".
 * If no "Dataspace" header message exists a NULL pointer is returned.
 ***************************************************************************/
inline
const GXmlElement* gammalib::hdf5::xml_msg_dataspace(const GXmlElement* header)
{
    const GXmlElement* element = NULL;
    if (xml_has_msg_type(header, "Dataspace", 0)) {
        element = xml_msg_type(header, "Dataspace", 0);
    }
    return (element);
}
 
 
/***********************************************************************//**
 * @brief Return "Datatype" message XML element
 *
 * @param[in] header Pointer to XML header element.
 * @return Pointer to "Datatype" message XML element.
 *
 * Returns a XML pointer to the first header message of type "Datatype".
 * If no "Datatype" header message exists a NULL pointer is returned.
 ***************************************************************************/
inline
const GXmlElement* gammalib::hdf5::xml_msg_datatype(const GXmlElement* header)
{
    const GXmlElement* element = NULL;
    if (xml_has_msg_type(header, "Datatype", 0)) {
        element = xml_msg_type(header, "Datatype", 0);
    }
    return (element);
}
 
 
/***********************************************************************//**
 * @brief Return "DataStorageLayout" message XML element
 *
 * @param[in] header Pointer to XML header element.
 * @return Pointer to "DataStorageLayout" message XML element.
 *
 * Returns a XML pointer to the first header message of type
 * "DataStorageLayout". If no "DataStorageLayout" header message exists a
 * NULL pointer is returned.
 ***************************************************************************/
inline
const GXmlElement* gammalib::hdf5::xml_msg_datalayout(const GXmlElement* header)
{
    const GXmlElement* element = NULL;
    if (xml_has_msg_type(header, "DataStorageLayout", 0)) {
        element = xml_msg_type(header, "DataStorageLayout", 0);
    }
    return (element);
}
 
 
/***********************************************************************//**
 * @brief Return "DataStorageFilterPipeline" message XML element
 *
 * @param[in] header Pointer to XML header element.
 * @return Pointer to "DataStorageFilterPipeline" message XML element.
 *
 * Returns a XML pointer to the first header message of type
 * "DataStorageFilterPipeline". If no "DataStorageFilterPipeline" header
 * message exists a NULL pointer is returned.
 ***************************************************************************/
inline
const GXmlElement* gammalib::hdf5::xml_msg_datafilter(const GXmlElement* header)
{
    const GXmlElement* element = NULL;
    if (xml_has_msg_type(header, "DataStorageFilterPipeline", 0)) {
        element = xml_msg_type(header, "DataStorageFilterPipeline", 0);
    }
    return (element);
}
 
#endif /* GHDF5_HPP */