ExternalSequence.h

Go to the documentation of this file.

#include <vector>
#include <iostream>
#include <string>
#include <sstream>
#include <fstream>
#include <map>

#ifndef CLASS_EXTERNAL_SEQUENCE
#define CLASS_EXTERNAL_SEQUENCE

//#define MASTER_SLAVE_FORMAT

#define PI     3.1415926535897932384626433832795
#define TWO_PI 6.283185307179586476925286766558


enum MessageType {
        ERROR_MSG=-2,
        WARNING_MSG,
        NORMAL_MSG,
        DEBUG_HIGH_LEVEL,
        DEBUG_MEDIUM_LEVEL,
        DEBUG_LOW_LEVEL
};

// Define the current level of messages to display
const MessageType MSG_LEVEL = NORMAL_MSG;


enum Event {
        DELAY,
        RF,
        GX,
        GY,
        GZ,
        ADC,
};
const int NUM_EVENTS=ADC+1;
const int NUM_GRADS=ADC-GX;

struct RFEvent
{
        float amplitude;     
        int magShape;        
        int phaseShape;      
        float freqOffset;    
        float phaseOffset;   
};


struct GradEvent
{
        float amplitude;      
        // Trapezoid:
        long rampUpTime;      
        long flatTime;        
        long rampDownTime;    
        // Arbitrary:
        int shape;            
};


struct ADCEvent
{
        int numSamples;     
        int dwellTime;      
        int delay;          
        float freqOffset;   
        float phaseOffset;  
};

struct EventIDs
{
        int id[NUM_EVENTS];
};


class SeqBlock
{
        friend class ExternalSequence;
public:
        SeqBlock() { gradWaveforms.resize(NUM_GRADS); }

        bool    isRF();

        bool    isTrapGradient(int channel);

        bool    isArbitraryGradient(int channel);

        bool    isADC();

        bool    isDelay();

        int     GetIndex();

        int     GetEventIndex(Event type);

        long    GetDelay();

        long    GetDuration();

        int     GetGradientLength(int channel);

        GradEvent& GetGradEvent(int channel);

        float* GetGradientPtr(int channel);

        RFEvent&        GetRFEvent();

        int    GetRFLength();

        float* GetRFAmplitudePtr();

        float* GetRFPhasePtr();

        ADCEvent& GetADCEvent();

        std::string GetTypeString();

        void   free();
protected:
        int index;          
        // Event array contains integer indices to events stored in the parent ExternalSequence object
        int events[NUM_EVENTS]; 
        long delay;         
        long duration;      
        RFEvent rf;                 
        GradEvent grad[NUM_GRADS];  
        ADCEvent adc;               
        // Below is only valid once decompressed:

        // RF
        std::vector<float> rfAmplitude;  
        std::vector<float> rfPhase;      
        // Gradient waveforms
        std::vector< std::vector<float> > gradWaveforms;    
};

// * ------------------------------------------------------------------ *
// * Inline functions                                                   *
// * ------------------------------------------------------------------ *
inline int       SeqBlock::GetIndex() { return index; }

inline bool      SeqBlock::isRF() { return (events[RF]>0); }
inline bool      SeqBlock::isTrapGradient(int channel) { return ((events[channel+GX]>0) & (grad[channel].shape==0)); }
inline bool      SeqBlock::isArbitraryGradient(int channel) { return ((events[channel+GX]>0) & (grad[channel].shape>0)); }
inline bool      SeqBlock::isADC() { return (events[ADC]>0); }
inline bool      SeqBlock::isDelay() { return (events[DELAY]>0); }

inline long      SeqBlock::GetDelay() { return delay; }
inline long      SeqBlock::GetDuration() { return duration; }

inline int       SeqBlock::GetEventIndex(Event type) { return events[type]; }

inline GradEvent& SeqBlock::GetGradEvent(int channel) { return grad[channel]; }
inline RFEvent&   SeqBlock::GetRFEvent() { return rf; }
inline ADCEvent&  SeqBlock::GetADCEvent() { return adc; }


inline std::string SeqBlock::GetTypeString() {
        std::string type;
        if (isRF()) type = type + "RF";
        if (isTrapGradient(0)) type += " TrapX";
        if (isTrapGradient(1)) type += " TrapY";
        if (isTrapGradient(2)) type += " TrapZ";
        if (isArbitraryGradient(0)) type += " ArbX";
        if (isArbitraryGradient(1)) type += " ArbY";
        if (isArbitraryGradient(2)) type += " ArbZ";
        if (isADC()) type += " ADC";
        if (isDelay()) type += " Delay";
        return type;
}

inline float*    SeqBlock::GetGradientPtr(int channel) { return (gradWaveforms[channel].size()>0) ? &gradWaveforms[channel][0] : NULL; }
inline int       SeqBlock::GetGradientLength(int channel) {     return gradWaveforms[channel].size(); }

inline float*    SeqBlock::GetRFAmplitudePtr() { return &rfAmplitude[0]; }
inline float*    SeqBlock::GetRFPhasePtr() { return &rfPhase[0]; }
inline int       SeqBlock::GetRFLength() { return rfAmplitude.size(); }

inline void      SeqBlock::free() {
        // Force the memory to be freed
        std::vector<float>().swap(rfAmplitude);
        std::vector<float>().swap(rfPhase);
        std::vector<std::vector<float> >().swap(gradWaveforms);
 }


struct CompressedShape
{
        int numUncompressedSamples;    
        std::vector<float> samples;    
};


class ExternalSequence
{
  public:

        ExternalSequence();

        ~ExternalSequence();

        bool load(std::string path);


        static void print_msg(MessageType level, std::ostream& ss);

        typedef void (*PrintFunPtr)(const std::string &str);

        static void SetPrintFunction(PrintFunPtr fun);

        std::vector<double> GetDefinition(std::string key);

        int  GetNumberOfBlocks(void);

        SeqBlock*  GetBlock(int blockIndex);

        bool decodeBlock(SeqBlock *block);

  private:

        static const int MAX_LINE_SIZE; 
        static const char COMMENT_CHAR; 
        // *** Private helper functions ***

        static std::istream& getline(std::istream& stream, char *buffer, const int MAX_SIZE);

        void buildFileIndex(std::ifstream &stream);

        void skipComments(std::ifstream &stream, char* buffer);

        bool decompressShape(CompressedShape& encoded, float *shape);


        bool checkBlockReferences(EventIDs& events);

        void checkGradient(SeqBlock& block);

        void checkRF(SeqBlock& block);

        // *** Static helper function ***

        static void defaultPrint(const std::string &str);

        // *** Static members ***

        static PrintFunPtr print_fun;              
        // *** Members ***

        std::map<std::string,int> m_fileIndex;     
        // Low level sequence blocks
        std::vector<EventIDs> m_blocks;            
        // Global user-specified definitions
        std::map<std::string, std::vector<double> >m_definitions;  
        // List of events (referenced by blocks)
        std::map<int,RFEvent>   m_rfLibrary;       
        std::map<int,GradEvent> m_gradLibrary;     
        std::map<int,ADCEvent>  m_adcLibrary;      
        std::map<int,long>      m_delayLibrary;    
        // List of basic shapes (referenced by events)
        std::map<int,CompressedShape> m_shapeLibrary;    
};

// * ------------------------------------------------------------------ *
// * Inline functions                                                   *
// * ------------------------------------------------------------------ *

inline int ExternalSequence::GetNumberOfBlocks(void){return m_blocks.size();}
inline std::vector<double>      ExternalSequence::GetDefinition(std::string key){
        if (m_definitions.count(key)>0)
                return m_definitions[key];
        else
                return std::vector<double>();
}

inline void ExternalSequence::defaultPrint(const std::string &str) { std::cout << str << std::endl; }
inline void ExternalSequence::SetPrintFunction(PrintFunPtr fun) { print_fun=fun; }



#endif  //CLASS_EXTERNAL_SEQUENCE