fiff_tag.h

Go to the documentation of this file.

//=============================================================================================================
 
#ifndef FIFF_TAG_H
#define FIFF_TAG_H
 
//=============================================================================================================
// DEFINES
//=============================================================================================================
 
/* NOTE:
   The architecture is now deduced from the operating system, which is
   a bit stupid way, since the same operating system can me run on various
   architectures. This may need revision later on. */
 
#if defined(DARWIN)
 
#if defined(__LITTLE_ENDIAN__)
#define INTEL_X86_ARCH
#else
#define BIG_ENDIAN_ARCH
#endif
 
#else
 
#if defined(__hpux) || defined(__Lynx__) || defined(__sun)
#define BIG_ENDIAN_ARCH
#else
#if defined(__linux) || defined(WIN32) || defined(__APPLE__)
#define INTEL_X86_ARCH
#endif
 
#endif
#endif
 
#define NATIVE_ENDIAN FIFFV_LITTLE_ENDIAN
 
#ifdef INTEL_X86_ARCH
#define NATIVE_ENDIAN FIFFV_LITTLE_ENDIAN
#endif
 
#ifdef BIG_ENDIAN_ARCH
#define NATIVE_ENDIAN FIFFV_BIG_ENDIAN
#endif
 
//=============================================================================================================
// INCLUDES
//=============================================================================================================
 
#include "fiff_global.h"
#include "fiff_constants.h"
#include "fiff_file.h"
#include "fiff_types.h"
#include "fiff_id.h"
#include "fiff_coord_trans.h"
#include "fiff_ch_info.h"
#include "fiff_ch_pos.h"
#include "fiff_dir_entry.h"
#include "fiff_dig_point.h"
 
//=============================================================================================================
// EIGEN INCLUDES
//=============================================================================================================
 
#include <Eigen/Core>
#include <Eigen/SparseCore>
 
//=============================================================================================================
// QT INCLUDES
//=============================================================================================================
 
#include <QDebug>
#include <QByteArray>
#include <QList>
#include <QSharedPointer>
#include <QVector>
 
//=============================================================================================================
// STL INCLUDES
//=============================================================================================================
 
#include <iostream>
#include <memory>
 
//=============================================================================================================
// DEFINE NAMESPACE FIFFLIB
//=============================================================================================================
 
namespace FIFFLIB
{
 
class FiffStream;
class FiffDirNode;
 
//=============================================================================================================
// FORWARD DECLARATIONS
//=============================================================================================================
//
//   The magic hexadecimal values
//
inline constexpr auto IS_MATRIX = 0xFFFF0000;           
inline constexpr auto MATRIX_CODING_DENSE = 0x00004000; 
inline constexpr auto MATRIX_CODING_CCS = 0x00004010;   
inline constexpr auto MATRIX_CODING_RCS = 0x00004020;   
inline constexpr auto DATA_TYPE = 0x0000FFFF;           
 
//const fiff_int_t IS_MATRIX           = 4294901760; /**< Is Matrix encoding. ffff0000. */
//const fiff_int_t MATRIX_CODING_DENSE = 16384;       /**< MATRIX_CODING_DENSE encoding. 4000. */
//const fiff_int_t MATRIX_CODING_CCS   = 16400;       /**< MATRIX_CODING_CCS encoding. 4010. */
//const fiff_int_t MATRIX_CODING_RCS   = 16416;       /**< MATRIX_CODING_RCS encoding. 4020. */
//const fiff_int_t DATA_TYPE           = 65535;       /**< DATA_TYPE encoding. ffff. */
 
//=============================================================================================================
class FIFFSHARED_EXPORT FiffTag : public QByteArray
{
public:
    using SPtr = QSharedPointer<FiffTag>;             
    using ConstSPtr = QSharedPointer<const FiffTag>;  
    using UPtr = std::unique_ptr<FiffTag>;            
    using ConstUPtr = std::unique_ptr<const FiffTag>; 
 
    //=========================================================================================================
    FiffTag();
 
    //=========================================================================================================
    FiffTag(const FiffTag& p_FiffTag) = default;
 
    //=========================================================================================================
    FiffTag(FiffTag&& other) = default;
 
    //=========================================================================================================
    FiffTag& operator=(const FiffTag& other) = default;
 
    //=========================================================================================================
    FiffTag& operator=(FiffTag&& other) = default;
 
    //=========================================================================================================
    ~FiffTag() = default;
 
    //=========================================================================================================
    fiff_int_t getMatrixCoding() const;
 
    //=========================================================================================================
    bool isMatrix() const;
 
    //=========================================================================================================
    bool getMatrixDimensions(qint32& p_ndim, QVector<qint32>& p_Dims) const;
 
    //=========================================================================================================
    fiff_int_t getType() const;
 
    //=========================================================================================================
    QString getInfo() const;
 
    //
    // Simple types
    //
    //=========================================================================================================
    inline const quint8* toByte() const;
 
    //=========================================================================================================
    inline const quint16* toUnsignedShort() const;
 
    //=========================================================================================================
    inline const qint16* toShort() const;
 
    //=========================================================================================================
    inline const quint32* toUnsignedInt() const;
 
    //=========================================================================================================
    inline const qint32* toInt() const;
 
    //=========================================================================================================
    inline const qint32* toJulian() const;
 
    //=========================================================================================================
    inline const float* toFloat() const;
 
    //=========================================================================================================
    inline const double* toDouble() const;
 
    //=========================================================================================================
    inline QString toString() const;
 
    //=========================================================================================================
    inline const qint16* toDauPack16() const;
 
    //
    // Structures
    //
    //=========================================================================================================
    inline FiffId toFiffID() const;
 
    //=========================================================================================================
    inline FiffDigPoint toDigPoint() const;
 
    //=========================================================================================================
    inline FiffCoordTrans toCoordTrans() const;
 
    //=========================================================================================================
    inline FiffChInfo toChInfo() const;
 
    //    //=========================================================================================================
    //    /**
    //    * to fiff OLD PACK
    //    */
    //    inline fiff_coord_trans_t toCoordTrans() const;
 
    //=========================================================================================================
    inline QList<QSharedPointer<FiffDirEntry>> toDirEntry() const;
 
    //
    // MATRIX
    //
    //=========================================================================================================
    inline Eigen::MatrixXi toIntMatrix() const;
 
    //=========================================================================================================
    inline Eigen::MatrixXf toFloatMatrix() const;
 
    //=========================================================================================================
    Eigen::SparseMatrix<double> toSparseFloatMatrix() const;
 
    //
    //from fiff_combat.c
    //
 
    //=========================================================================================================
    static void convert_ch_pos(FiffChPos* pos);
 
    /*
     * Data type conversions for the little endian systems.
     */
    static void convert_matrix_from_file_data(const FiffTag::UPtr& tag);
 
    //=========================================================================================================
    static void convert_matrix_to_file_data(const FiffTag::UPtr& tag);
 
    //
    // Data type conversions for the little endian systems.
    //
    //=========================================================================================================
    static void convert_tag_data(const FiffTag::UPtr& tag, int from_endian, int to_endian);
 
    //
    // from fiff_type_spec.c
    //
    //=========================================================================================================
    static fiff_int_t fiff_type_fundamental(fiff_int_t type);
 
    //=========================================================================================================
    static fiff_int_t fiff_type_base(fiff_int_t type);
 
    //=========================================================================================================
    static fiff_int_t fiff_type_matrix_coding(fiff_int_t type);
 
    //=========================================================================================================
    inline static qint32 storageSize();
 
public:
    fiff_int_t kind; 
    fiff_int_t type; 
    fiff_int_t next; 
};
 
//=============================================================================================================
// INLINE DEFINITIONS
//=============================================================================================================
 
inline qint32 FiffTag::storageSize()
{
    // On-disk layout: kind, type, size, next (4 x fiff_int_t)
    // Note: 'size' is not a class member (QByteArray::size() is used at runtime),
    //       but it is part of the on-disk wire format.
    return sizeof(FiffTag::kind) + sizeof(FiffTag::type) + sizeof(fiff_int_t) /* size field on disk */
        + sizeof(FiffTag::next);
}
 
//=============================================================================================================
// Simple types
//=============================================================================================================
 
inline const quint8* FiffTag::toByte() const
{
    if (this->isMatrix() || this->getType() != FIFFT_BYTE)
        return nullptr;
    else
        return reinterpret_cast<const quint8*>(this->data());
}
 
//=============================================================================================================
 
inline const quint16* FiffTag::toUnsignedShort() const
{
    if (this->isMatrix() || this->getType() != FIFFT_USHORT)
        return nullptr;
    else
        return reinterpret_cast<const quint16*>(this->data());
}
 
//=============================================================================================================
 
inline const qint16* FiffTag::toShort() const
{
    if (this->isMatrix() || this->getType() != FIFFT_SHORT)
        return nullptr;
    else
        return reinterpret_cast<const qint16*>(this->data());
}
 
//=============================================================================================================
 
inline const quint32* FiffTag::toUnsignedInt() const
{
    if (this->isMatrix() || this->getType() != FIFFT_UINT)
        return nullptr;
    else
        return reinterpret_cast<const quint32*>(this->data());
}
 
//=============================================================================================================
 
inline const qint32* FiffTag::toInt() const
{
    if (this->isMatrix() || this->getType() != FIFFT_INT) {
        qWarning("Expected an integer tag : %d (found data type %d instead)\n", this->kind, this->getType());
        return nullptr;
    } else
        return reinterpret_cast<const qint32*>(this->data());
}
 
//=============================================================================================================
 
inline const qint32* FiffTag::toJulian() const
{
    if (this->isMatrix() || this->getType() != FIFFT_JULIAN) {
        qWarning("Expected a julian tag : %d (found data type %d instead)\n", this->kind, this->getType());
        return nullptr;
    } else
        return reinterpret_cast<const qint32*>(this->data());
}
 
//=============================================================================================================
 
inline const float* FiffTag::toFloat() const
{
    if (this->isMatrix() || this->getType() != FIFFT_FLOAT)
        return nullptr;
    else
        return reinterpret_cast<const float*>(this->data());
}
 
//=============================================================================================================
 
inline const double* FiffTag::toDouble() const
{
    if (this->isMatrix() || this->getType() != FIFFT_DOUBLE)
        return nullptr;
    else
        return reinterpret_cast<const double*>(this->data());
}
 
//=============================================================================================================
 
inline QString FiffTag::toString() const
{
    if (this->isMatrix() || this->getType() != FIFFT_STRING)
        return nullptr;
    else
        return *this;
}
 
//=============================================================================================================
 
inline const qint16* FiffTag::toDauPack16() const
{
    if (this->isMatrix() || this->getType() != FIFFT_DAU_PACK16)
        return nullptr;
    else
        return reinterpret_cast<const qint16*>(this->data());
}
 
//=============================================================================================================
// Structures
//=============================================================================================================
 
inline FiffId FiffTag::toFiffID() const
{
    FiffId p_fiffID;
    if (this->isMatrix() || this->getType() != FIFFT_ID_STRUCT || this->isNull() || this->size() < FiffId::storageSize())
        return p_fiffID;
    else {
        const auto* t_pInt32 = reinterpret_cast<const qint32*>(this->data());
 
        p_fiffID.version = t_pInt32[0];
        p_fiffID.machid[0] = t_pInt32[1];
        p_fiffID.machid[1] = t_pInt32[2];
        p_fiffID.time.secs = t_pInt32[3];
        p_fiffID.time.usecs = t_pInt32[4];
 
        return p_fiffID;
    }
}
 
//=============================================================================================================
 
inline FiffDigPoint FiffTag::toDigPoint() const
{
    FiffDigPoint t_fiffDigPoint;
    if (this->isMatrix() || this->getType() != FIFFT_DIG_POINT_STRUCT || this->isNull() || this->size() < FiffDigPoint::storageSize())
        return t_fiffDigPoint;
    else {
        auto* t_pInt32 = reinterpret_cast<const qint32*>(this->data());
 
        t_fiffDigPoint.kind = t_pInt32[0];
        t_fiffDigPoint.ident = t_pInt32[1];
 
        auto* t_pFloat = reinterpret_cast<const float*>(this->data());
        t_fiffDigPoint.r[0] = t_pFloat[2];
        t_fiffDigPoint.r[1] = t_pFloat[3];
        t_fiffDigPoint.r[2] = t_pFloat[4];
        t_fiffDigPoint.coord_frame = 0;
 
        return t_fiffDigPoint;
    }
}
 
//=============================================================================================================
 
inline FiffCoordTrans FiffTag::toCoordTrans() const
{
    FiffCoordTrans p_FiffCoordTrans;
    if (this->isMatrix() || this->getType() != FIFFT_COORD_TRANS_STRUCT || this->isNull() || this->size() < FiffCoordTrans::storageSize())
        return p_FiffCoordTrans;
    else {
        auto* t_pInt32 = reinterpret_cast<const qint32*>(this->data());
        p_FiffCoordTrans.from = t_pInt32[0];
        p_FiffCoordTrans.to = t_pInt32[1];
 
        p_FiffCoordTrans.trans.setIdentity(4, 4);
        auto* t_pFloat = reinterpret_cast<const float*>(this->data());
        int count = 0;
        int r, c;
        for (r = 0; r < 3; ++r) {
            p_FiffCoordTrans.trans(r, 3) = t_pFloat[11 + r];
            for (c = 0; c < 3; ++c) {
                p_FiffCoordTrans.trans(r, c) = t_pFloat[2 + count];
                ++count;
            }
        }
 
        p_FiffCoordTrans.invtrans.setIdentity(4, 4);
        count = 0;
        for (r = 0; r < 3; ++r) {
            p_FiffCoordTrans.invtrans(r, 3) = t_pFloat[23 + r];
            for (c = 0; c < 3; ++c) {
                p_FiffCoordTrans.invtrans(r, c) = t_pFloat[14 + count];
                ++count;
            }
        }
 
        return p_FiffCoordTrans;
    }
}
 
//=========================================================================================================
inline FiffChInfo FiffTag::toChInfo() const
{
    FiffChInfo p_FiffChInfo;
 
    if (this->isMatrix() || this->getType() != FIFFT_CH_INFO_STRUCT || this->isNull() || this->size() < FiffChInfo::storageSize())
        return p_FiffChInfo;
    else {
        auto* t_pInt32 = reinterpret_cast<const qint32*>(this->data());
        p_FiffChInfo.scanNo = t_pInt32[0];
        p_FiffChInfo.logNo = t_pInt32[1];
        p_FiffChInfo.kind = t_pInt32[2];
        auto* t_pFloat = reinterpret_cast<const float*>(this->data());
        p_FiffChInfo.range = t_pFloat[3];
        p_FiffChInfo.cal = t_pFloat[4];
 
        p_FiffChInfo.chpos.coil_type = t_pInt32[5];
 
        //
        //   Read the coil coordinate system definition
        //
        qint32 r;
        // r0
        for (r = 0; r < 3; ++r)
            p_FiffChInfo.chpos.r0[r] = t_pFloat[6 + r];
        // ex
        for (r = 0; r < 3; ++r)
            p_FiffChInfo.chpos.ex[r] = t_pFloat[6 + 3 + r];
        // ey
        for (r = 0; r < 3; ++r)
            p_FiffChInfo.chpos.ey[r] = t_pFloat[6 + 6 + r];
        // ez
        for (r = 0; r < 3; ++r)
            p_FiffChInfo.chpos.ez[r] = t_pFloat[6 + 9 + r];
 
        p_FiffChInfo.coord_frame = FIFFV_COORD_UNKNOWN;
 
        //
        //   Convert loc into a more useful format
        //
        if (p_FiffChInfo.kind == FIFFV_MEG_CH || p_FiffChInfo.kind == FIFFV_REF_MEG_CH) {
            p_FiffChInfo.coil_trans.setIdentity(4, 4);
            // r0
            for (r = 0; r < 3; ++r)
                p_FiffChInfo.coil_trans(r, 3) = p_FiffChInfo.chpos.r0[r];
            // ex
            for (r = 0; r < 3; ++r)
                p_FiffChInfo.coil_trans(r, 0) = p_FiffChInfo.chpos.ex[r];
            // ey
            for (r = 0; r < 3; ++r)
                p_FiffChInfo.coil_trans(r, 1) = p_FiffChInfo.chpos.ey[r];
            // ez
            for (r = 0; r < 3; ++r)
                p_FiffChInfo.coil_trans(r, 2) = p_FiffChInfo.chpos.ez[r];
 
            p_FiffChInfo.coord_frame = FIFFV_COORD_DEVICE;
        } else if (p_FiffChInfo.kind == FIFFV_EEG_CH) {
            if (p_FiffChInfo.chpos.ex.norm() > 0) {
                p_FiffChInfo.eeg_loc.block(0, 0, 3, 1) = p_FiffChInfo.chpos.r0.block(0, 0, 3, 1);
                p_FiffChInfo.eeg_loc.block(0, 1, 3, 1) = p_FiffChInfo.chpos.ex.block(0, 0, 3, 1);
            } else {
                p_FiffChInfo.eeg_loc.block(0, 0, 3, 1) = p_FiffChInfo.chpos.r0.block(0, 0, 3, 1);
            }
            p_FiffChInfo.coord_frame = FIFFV_COORD_HEAD;
        }
        //
        //   Unit and exponent
        //
        p_FiffChInfo.unit = t_pInt32[18];
        p_FiffChInfo.unit_mul = t_pInt32[19];
 
        //
        //   Handle the channel name
        //
        const char* orig = static_cast<const char*>(this->data());
        p_FiffChInfo.ch_name = QString::fromUtf8(orig + 80, static_cast<qsizetype>(qstrnlen(orig + 80, 16))).replace(" ", "");
 
        return p_FiffChInfo;
    }
}
 
//    //=========================================================================================================
//    /**
//    * to fiff OLD PACK
//    */
//    inline fiff_coord_trans_t toCoordTrans() const
//    {
 
//    }
 
//=============================================================================================================
 
inline QList<QSharedPointer<FiffDirEntry>> FiffTag::toDirEntry() const
{
    //         tag.data = struct('kind',{},'type',{},'size',{},'pos',{});
    QList<QSharedPointer<FiffDirEntry>> p_ListFiffDir;
    if (this->isMatrix() || this->getType() != FIFFT_DIR_ENTRY_STRUCT || this->data() == nullptr)
        return p_ListFiffDir;
    else {
        QSharedPointer<FiffDirEntry> t_pFiffDirEntry;
        const auto* t_pInt32 = reinterpret_cast<const qint32*>(this->data());
        for (int k = 0; k < this->size() / 16; ++k) {
            t_pFiffDirEntry = QSharedPointer<FiffDirEntry>(new FiffDirEntry);
            t_pFiffDirEntry->kind = t_pInt32[k * 4];     //fread(fid,1,'int32');
            t_pFiffDirEntry->type = t_pInt32[k * 4 + 1]; //fread(fid,1,'uint32');
            t_pFiffDirEntry->size = t_pInt32[k * 4 + 2]; //fread(fid,1,'int32');
            t_pFiffDirEntry->pos = t_pInt32[k * 4 + 3];  //fread(fid,1,'int32');
            p_ListFiffDir.append(t_pFiffDirEntry);
        }
    }
    return p_ListFiffDir;
}
 
//=============================================================================================================
// MATRIX
//=============================================================================================================
 
//=============================================================================================================
 
inline Eigen::MatrixXi FiffTag::toIntMatrix() const
{
    if (!this->isMatrix() || this->getType() != FIFFT_INT || this->data() == nullptr)
        return Eigen::MatrixXi();
 
    qint32 ndim;
    QVector<qint32> dims;
    this->getMatrixDimensions(ndim, dims);
 
    if (ndim != 2) {
        qWarning("Only two-dimensional matrices are supported at this time");
        return Eigen::MatrixXi();
    }
 
    // Use copy constructor instead --> slower performance but higher memory management reliability
    Eigen::MatrixXi p_Matrix(Eigen::Map<const Eigen::MatrixXi>(reinterpret_cast<const int*>(this->data()), dims[0], dims[1]));
 
    return p_Matrix;
}
 
//=============================================================================================================
 
inline Eigen::MatrixXf FiffTag::toFloatMatrix() const
{
    if (!this->isMatrix() || this->getType() != FIFFT_FLOAT || this->data() == nullptr)
        return Eigen::MatrixXf(); //NULL;
 
    if (fiff_type_matrix_coding(this->type) != FIFFTS_MC_DENSE) {
        qWarning("Error in FiffTag::toFloatMatrix(): Matrix is not dense!");
        return Eigen::MatrixXf();
    }
 
    qint32 ndim;
    QVector<qint32> dims;
    this->getMatrixDimensions(ndim, dims);
 
    if (ndim != 2) {
        qWarning("Only two-dimensional matrices are supported at this time");
        return Eigen::MatrixXf();
    }
 
    // Use copy constructor instead --> slower performance but higher memory management reliability
    Eigen::MatrixXf p_Matrix(Eigen::Map<const Eigen::MatrixXf>(reinterpret_cast<const float*>(this->data()), dims[0], dims[1]));
 
    return p_Matrix;
}
 
} // NAMESPACE
 
#endif // FIFF_TAG_H