mlWaterColumnStructures.h

Go to the documentation of this file.

// Copyright (c) Fraunhofer MEVIS, Germany. All rights reserved.
// **InsertLicense** code
//----------------------------------------------------------------------------------
 
//----------------------------------------------------------------------------------
#pragma once
 
// Local includes
#include "MLPCLR2SonicWCLoaderSystem.h"
 
// ML includes
#include <mlModuleIncludes.h>
#include <mlReleaseToolsString.h>
#include <mlByteDataReader.h>
 
#include <list>
 
ML_START_NAMESPACE
 
// The loader class these classes are used by.
class PCLR2SonicWCLoader;
 
namespace R2SonicWC {
 
// Forward needed for boost shared pointer definition.
class R2SonicWCLoader;
 
MLPCLR2SonicWCLoader_EXPORT std::string convertBytesToReadableString(const char *chars, 
                                                                     size_t numChars, 
                                                                     bool revert);
 
// The water column data contains real-time beamformer 16-bit magnitude data
// (beam amplitude) and optional 16-bit split-array phase data (intra-beam
// direction). Maximum data rate is about 70 megabytes per second (assuming
// 256 beams, 68.4 kHz sample rate, and phase data enabled). The sample rate
// (and signal bandwidth) varies with transmit pulse width and range setting.
// Maximum ping data size is about 32 megabytes (assuming 256 beams of 32768
// samples, and phase data enabled), but max size may change in the future.
// The number of beamformed data samples normally extends somewhat further
// than the user's range setting.
// When the operator enables water column mode, each sonar ping outputs
// numerous 'WCD0' packets containing: one H0 header section, one A1 beam
// angle section, and many M1 or M2 data sections. The section order may
// change in the future, so plan for that in your data acquisition.
// Each M1 or M2 section contains a subset of the ping data. Its header
// indicates its size position to help you assemble the full ping array.
// You may wish to detect missing M1 or M2 data sections (perhaps a lost
// DP packet), and then fill the gap with zeros or perhaps data from the
// previous ping (to reduce visual disturbances), and then increment an
// error counter for network health monitoring purposes.
// The water column data is basically in polar coordinates, so you may
// wish to geometrically warp it into the familiar wedge shape for display.
// Consider using OpenGL or Direct3D texture mapping.
 
//-----------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------
class MLPCLR2SonicWCLoader_EXPORT WaterColumnSectionBase {
public:
 
  WaterColumnSectionBase();
  
  virtual ~WaterColumnSectionBase();
 
  virtual std::string getSectionName() const=0;
 
  virtual void reset();
 
  MLuint64 posInFile;   
  MLuint16 sectionName; 
};
 
//-----------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------
class MLPCLR2SonicWCLoader_EXPORT WaterColumnH0 : public WaterColumnSectionBase {
public:
  WaterColumnH0();
 
  ~WaterColumnH0() override;
 
  std::string getSectionName() const override;
  
  std::string getModelNumber() const;
  
  std::string getSerialNumber() const;
 
  void reset() override;
  
  MLuint64 read(ByteDataReader &reader, MLuint64 &fileReadPos);
  
  std::string getAsString(std::string prefix) const;
    
  MLuint16 H0_SectionName;      
  MLuint16 H0_SectionSize;      
  MLuint8  H0_ModelNumber[12];  
  MLuint8  H0_SerialNumber[12]; 
  MLuint32 H0_TimeSeconds;      
  MLuint32 H0_TimeNanoseconds;  
  MLuint32 H0_PingNumber;       
  MLfloat  H0_PingPeriod;       
  MLfloat  H0_SoundSpeed;       
  MLfloat  H0_Frequency;        
  MLfloat  H0_TxPower;          
  MLfloat  H0_TxPulseWidth;     
  MLfloat  H0_TxBeamwidthVert;  
  MLfloat  H0_TxBeamwidthHoriz; 
  MLfloat  H0_TxSteeringVert;   
  MLfloat  H0_TxSteeringHoriz;  
  MLuint16 H0_TxMiscInfo;       
  MLint16  H0_VTX_Plus_Offset;  
  MLfloat  H0_RxBandwidth;      
  MLfloat  H0_RxSampleRate;     
  MLfloat  H0_RxRange;          
  MLfloat  H0_RxGain;           
  MLfloat  H0_RxSpreading;      
  MLfloat  H0_RxAbsorption;     
  MLfloat  H0_RxMountTilt;      
  MLuint32 H0_RxMiscInfo;       
  MLuint16 H0_reserved;         
  MLuint16 H0_Beams;            
};
 
//-----------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------
class MLPCLR2SonicWCLoader_EXPORT WaterColumnA1 : public WaterColumnSectionBase  {
public:
  WaterColumnA1();
  
  ~WaterColumnA1() override;
  
  std::string getSectionName() const override;
  
  void reset() override;
  
  MLuint64 read(ByteDataReader &reader, MLuint64 &fileReadPos, size_t numH0Beams);
 
  std::string getAsString(std::string       prefix,
                          const std::string &sep=" ",
                          const MLint       maxBeams=-1) const;
  
  std::vector<MLfloat> A1_BeamAngle;    
  MLuint16             A1_SectionName;  
  MLuint16             A1_SectionSize;  
  MLfloat              A1_MoreInfo[6];  
};
 
//-----------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------
class MLPCLR2SonicWCLoader_EXPORT WaterColumnM1AndM2Header {
public:
  WaterColumnM1AndM2Header();
 
  virtual ~WaterColumnM1AndM2Header();
 
  virtual std::string getSectionName() const;
 
  virtual void reset();
  
  MLuint64 read(ByteDataReader &reader, MLuint64 &fileReadPos);
 
  std::string getAsString(std::string prefix) const;
 
  MLuint16 M1OrM2_SectionName;   
  MLuint16 M1OrM2_SectionSize;   
  MLuint32 M1OrM2_PingNumber;    
  MLfloat  M1OrM2_ScalingFactor; 
  MLuint32 M1OrM2_TotalSamples;  
  MLuint32 M1OrM2_FirstSample;   
  MLuint16 M1OrM2_Samples;       
  MLuint16 M1OrM2_TotalBeams;    
  MLuint16 M1OrM2_FirstBeam;     
  MLuint16 M1OrM2_Beams;         
  MLuint32 M1OrM2_reserved0;     
  MLuint32 M1OrM2_reserved1;     
};
 
//-----------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------
class MLPCLR2SonicWCLoader_EXPORT WaterColumnM1OrM2 : public WaterColumnSectionBase {
public:
  WaterColumnM1OrM2();
  ~WaterColumnM1OrM2() override;
 
  WaterColumnM1AndM2Header         m1OrM2CommonHeader;
  
  MLuint64                         fileDataReadPos;
  
  mutable std::vector<MLuint16>    magnitudeData;   
 
  typedef struct {
    MLuint16 magnitude; 
    MLint16 phase;      
  }
  DoubleMLint16;
 
  mutable std::vector<DoubleMLint16> magnitudePhaseData;   
 
  bool                             saveMemory;
    
protected:
  mutable R2SonicWCLoader         *_reader;
 
public:
  std::string getSectionName() const override;
 
  void reset() override;
 
  void mapMxSectionData() const;
  
  void clearMxSectionData() const;
 
  void unmapMxSectionDataHint() const;
  
  MLuint64 read(R2SonicWCLoader &reader, MLuint64 &fileReadPos);
  
  std::string getAsString(const MLint       maxBeams=-1,
                          const MLint       maxSamplesPerBeam=-1,
                          std::string       prefix="",
                          const std::string &sep=" ") const;
};
 
//-----------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------
class MLPCLR2SonicWCLoader_EXPORT WaterColumnPacket : public WaterColumnSectionBase {
public:
  WaterColumnPacket();
  
  ~WaterColumnPacket() override;
 
  std::string getSectionName() const override;
 
  void reset() override;
  
  MLuint64 read(ByteDataReader &reader, MLuint64 &fileReadPos);
  
  std::string getAsString(std::string prefix="") const;
 
  MLuint32          PacketName;         
  MLuint32          PacketSize;         
  MLuint32          DataStreamID;       
};
  
//-----------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------
class MLPCLR2SonicWCLoader_EXPORT WaterColumnDataSetPing {
public:
  WaterColumnDataSetPing();
  
  virtual ~WaterColumnDataSetPing();
  
  virtual void reset();
  
  bool isValid() const;
  
  MLuint32                pingNumber;   
  const WaterColumnPacket *wcd0Section; 
  const WaterColumnH0     *h0Section;   
  const WaterColumnA1     *a1Section;   
  
  std::list<const WaterColumnM1OrM2*> mSectionPointers;
};
 
//-----------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------
class MLPCLR2SonicWCLoader_EXPORT WaterColumnDataSet {
public:
  WaterColumnDataSet();
  
  virtual ~WaterColumnDataSet();
 
  void setWorkingMemoryHint(MLuint64 numBytes);
 
  MLuint64 getWorkingMemoryHint() const;
    
  bool isValid() const;
 
  std::list<WaterColumnSectionBase*> sectionList;
  
  std::string unknownSection;                     
  
  size_t numWCD0Sections;     
  size_t numH0Sections;       
  size_t numA1Sections;       
  size_t numM1Sections;       
  size_t numM2Sections;       
  size_t numOrphanedMSections;
  size_t numUnknownSections;  
  size_t numSamplesInFile;    
  size_t numTotalPingNumbers; 
  size_t numValidPingNumbers; 
 
  
  WaterColumnPacket      *firstWaterColumnPacket; 
  WaterColumnH0          *firstH0Section;         
  WaterColumnA1          *firstA1Section;         
  WaterColumnM1OrM2      *firstM1Section;         
  WaterColumnM1OrM2      *firstM2Section;         
  WaterColumnM1OrM2      *firstMxSection;         
  WaterColumnSectionBase *mostRecentSection;      
  std::string             mostRecentSectionIntro; 
  
  std::map<MLuint32, WaterColumnDataSetPing> allPingSections;
  
  std::map<MLuint32, WaterColumnDataSetPing> validPingSections;
  
  std::vector<MLuint32> allPingNumbers;
 
protected:
  MLuint64 _workingMemoryHint;
    
public:
  
  virtual void reset();
  
  MLuint64 read(R2SonicWCLoader &reader,
                MLuint64 &fileReadPos, 
                PCLR2SonicWCLoader &updateObject);
  
  std::string getAsString(const MLint        maxSections=-1,
                          const MLint        maxBeams=-1,
                          const MLint        maxSamplesPerBeam=-1,
                                std::string  prefix="",
                          const std::string &sep=" ",
                          const bool         showFirstOfEachPacketTypeOnly=false) const;
  
};
 
}
 
ML_END_NAMESPACE