Filter Library

Camera

Interface Physics

ScanBaseBuffer.h

/*
 * CFiltLib/ScanBaseBuffer.h - scanbuffer base class.
 *
 * This file is part of the Camera Filter Library.
 * Computer Aided Measurement Environment for Realtime Atomic imaging (Camera)
 *
 * Copyright (C) 2004, Leiden Probe Microscopy.
 * Copyright (C) 2004, Universiteit Leiden.
 *
 * Authors: M. Seynen (original), Martin J. Moene
 *
 * $Id: ScanBaseBuffer.h 447 2006-12-13 12:58:11Z moene $
 */

#ifndef CFILTLIB_SCANBASEBUFFER_H
#define CFILTLIB_SCANBASEBUFFER_H

#if _MSC_VER > 1000
#pragma once
#endif // _MSC_VER > 1000

#ifdef _AFXEXT
   //#pragma message("CFiltLib DLL export" )
   #define CLASS_DECL  _declspec(dllexport)
#else
   //#pragma message("CFiltLib DLL import" )
   #define CLASS_DECL  _declspec(dllimport)
#endif

/**
 * the basic scan base buffer.
 * \ingroup cfl_scanbasebuffer
 */

class CLASS_DECL CScanBaseBuffer : public CObject
{
public:
   /**
    * the parent class.
    */
   typedef CObject Super;

   /**
    * this type.
    */
   typedef CScanBaseBuffer Self;

   /**
    * the buffer's value type.
    */
   typedef short ValueType;

   /**
    * the buffer's pointer-to value type.
    */
   typedef ValueType* Pointer;

   /**
    * the buffer's const pointer-to value type.
    */
   typedef const ValueType* ConstPointer;

   /**
    * the buffer's real type.
    */
   typedef double RealType;

   /**
    * the forier buffer's data type.
    */
   typedef RealType FourierElementType;

   /**
    * the buffer's size type.
    */
   typedef DWORD SizeType;

   /**
    * the buffer's flags type.
    */
   typedef DWORD FlagType;

   /**
    * the buffer's mask type.
    */
   typedef DWORD MaskType;

   /**
    * the x, y and z spacing type.
    */
   typedef RealType SpacingType;

   /**
    * the x, y and z length type.
    */
   typedef RealType LengthType;

   ///
   /// \name Construction
   /// @{

   /**
    * destructor.
    */
   virtual ~CScanBaseBuffer();

   /**
    * default constuctor.
    */
   CScanBaseBuffer();

   /// @}
   /// \name Predicates
   /// @{

   /**
    * true if buffer contains a left--right scan.
    */
   bool HasLeftToRightScan() const;

   /**
    * true if buffer contains a right--left scan.
    */
   bool HasRightToLeftScan() const;

   /**
    * true if buffer contains both a left--right and a right--left scan.
    */
   bool IsBidirectionalScan() const;

   /**
    * true if all pixels of the frame are present.
    */
   bool IsCompleteFrame() const;

   /**
    * true if this buffer has not yet been used.
    */
   bool IsNewBuffer() const;

   /**
    * true if data not yet loaded.
    */
   bool IsEmptyBuffer() const;

   /**
    * true if data present in buffer.
    */
   bool IsLoadedBuffer() const;

   /**
    * true if data in buffer has been modified.
    */
   bool IsModifiedBuffer() const;

   /**
    * true if buffer is used for in-memory filtering.
    */
   bool IsInMemoryBuffer() const;

   /// @}
   /// \name Accessors
   /// @{

   /**
    * X-size in pixels.
    */
   SizeType Columns() const;

   /**
    * Y-size in pixels.
    */
   SizeType Rows() const;

   /**
    * the buffer data (non-const).
    */
   Pointer Data();

   /**
    * the buffer data (const).
    */
   ConstPointer Data() const;

   /**
    * the fourier left-right data (non-const).
    */
   FourierElementType** FourierDataL2R();

   /**
    * the fourier left-right data (const).
    */
   FourierElementType const* const* FourierDataL2R() const;

   /**
    * the fourier right-left data (non-const).
    */
   FourierElementType** FourierDataR2L();

   /**
    * the fourier right-left data (const).
    */
   FourierElementType const* const* FourierDataR2L() const;

   /**
    * Y-size by X-size number of pixels.
    */
   SizeType GetFrameSize() const;

   /*
    * number of pixels from the start of the L2R or R2L frame.
    */
   SizeType GetPartialFrameOffset() const;

   /**
    * number of pixels of the partial frame.
    */
   SizeType GetPartialFrameSize() const;

   /**
    * the frame width in [m].
    */
   LengthType GetFrameWidth() const;

   /**
    * the frame height in [m].
    */
   LengthType GetFrameHeight() const;

   /**
    * the pixel spacing in the x-direction in [m].
    */
   SpacingType GetSpacingX() const;

   /**
    * the pixel spacing in the y-direction in [m].
    */
   SpacingType GetSpacingY() const;

   /**
    * the bit spacing in the z-direction in [m].
    */
   SpacingType GetSpacingZ() const;

   /**
    * the length for the given number of pixels in the x-direction in [m].
    */
   LengthType GetLengthX( SizeType dx ) const;

   /**
    * the length for the given number of pixels in the y-direction in [m].
    */
   LengthType GetLengthY( SizeType dy ) const;

   /**
    * the absolute height in [m] for given ADC value: scale * (adc + offset).
    */
   LengthType GetAbsoluteHeight( ValueType adcValue ) const;

   /**
    * the rows required for FFT.
    */
   SizeType GetRowsForFFT() const;

   /**
    * the columns required for FFT.
    */
   SizeType GetColumnsForFFT() const;

   /**
    * the size required for FFT.
    */
   static SizeType GetSizeForFFT( SizeType size );

   /// @}
   /// \name Mutators
   /// @{

   /**
    * make sure a buffer of appropriate size is available;
    * \deprecated Replace with CreateOutputBuffer( const Self * ).
    */
   BOOL CheckAndSetBufferSize();

   /**
    * clear contents of data buffer.
    */
   void ClearDataBuffer();

   /**
    * clear contents of data buffer.
    */
   void ClearFourierBuffer();

   /**
    * create this buffer for input with the given size.
    */
   BOOL CreateInputBuffer( const CSize& size );

   /**
    * create this buffer for output based on the given input buffer; if specified, allocate extra elements.
    */
   BOOL CreateOutputBufferFor( const Self& input, SizeType extra = 0 );

   /**
    * resize this data buffer to the given size, on reallocation add extra size.
    */
   BOOL ResizeDataBuffer( const CSize& size, SizeType extra = 0 );

   /**
    * create the fourier buffer(s) based on the current databuffer size.
    */
   BOOL CreateFourierBuffer();

   /**
    * delete the fourier buffer(s).
    */
   BOOL DeleteFourierBuffer();

   /**
    * allocate fourier buffer(s) based on the current databuffer size and 
    * copy contents from other buffer.
    */
   BOOL CopyFourierBufferFrom( const Self& other );

   /// @}

protected:
   /// @}
   /// \name Buffer Creation
   /// @{

   /**
    * shallow copy; set data and fourier buffer pointers to 0.
    */
   void Copy( const Self& rhs );

   /**
    * allocate data buffer, but not fourier buffers.
    */
   void AllocateDataBuffer( SizeType extra = 0 );

   /**
    * allocate fourier buffer.
    */
   void AllocateFourierBuffer();

   /**
    * release all buffers.
    */
   void ReleaseAllBuffers();

   /**
    * release data buffer.
    */
   void ReleaseDataBuffer();

   /**
    * release fourier buffer.
    */
   void ReleaseFourierBuffer();

   /**
    * true if buffer has the right size and settings to use as output buffer
    * for the given input buffer.
    */
   BOOL IsUsableOutputBufferFor( const Self& input );

   /// @}

private:
   /// @}
   /// \name Prohibited
   /// @{

   /**
    * shallow copy-assignment constructor; do not copy data and fourier buffers.
    */
   CScanBaseBuffer( const Self& rhs );

   /**
    * shallo copy-assignment; do not copy data and fourier buffers.
    */
   Self& operator= ( const Self& rhs );

   /// @}

public:
   /**
    * data L2R/R2L flags; see InterfaceDll.h, "Scandata Buffer Flags:".
    */
   FlagType m_dwFlags;

   /**
    * X size buffer, see Columns().
    */
   SizeType m_dwSizeX;

   /**
    * Y size buffer, see Rows().
    */
   SizeType m_dwSizeY;

   /**
    * number of pixels in buffer, see also IsCompleteFrame().
    */
   SizeType m_dwPixels;

   /**
    * pointer to the data, see Data().
    */
   Pointer m_pwData;

   /**
    * FFT data for L2R.
    */
   FourierElementType** m_pdFourierL2R;

   /**
    * FFT data for R2L.
    */
   FourierElementType** m_pdFourierR2L;

   /**
    * name of the buffer.
    */
   CString m_csBufferName;

   /**
    * name of the data set.
    */
   CString m_csDataName;

   /**
    * name of the data unit.
    */
   CString m_csDataUnit;

   /**
    * scale factor between 1 unit and 1 LSB; see AbsoluteHeight().
    */
   RealType m_dDataScaleFactor;

   /**
    * offset for ADC=0; see AbsoluteHeight().
    */
   int m_nDataOffset;

   /**
    * mask register for optional parameters; see InterfaceDll.h,
    * "Scandata Buffer Parameter Mask".
    */
   MaskType m_dwParameterMask;

   /**
    * X slope of backgroundplane.
    */
   RealType m_dSlopeX;

   /**
    * Y slope of backgroundplane.
    */
   RealType m_dSlopeY;

   /**
    * average (RealType).
    */
   RealType m_dAvg;

   /**
    * min Z.
    */
   int m_nMinZ;

   /**
    * max Z.
    */
   int m_nMaxZ;

   /**
    * sum of all data squared; extra, not in cyclic/raw.
    */
   RealType m_dSecMom;

   /**
    * partial data in buffer, valid from Offset for Count pixels.
    */
   SizeType m_dwPixelOffset;

   /**
    * for dual l2r/r2l scans these values are valid for both areas.
    */
   SizeType m_dwPixelCount;

   /**
    * X Step size of area in picometer.
    */
   RealType m_dXStepSize;

   /**
    * Y Step size of area in picometer.
    */
   RealType m_dYStepSize;

   /**
    * original X Size in pixels.
    */
   SizeType m_dwOrgScanXSize;

   /**
    * original Y Size in pixels.
    */
   SizeType m_dwOrgScanYSize;

   /**
    * Rotation of scan around center in rad.
    */
   RealType m_dScanAngle;

   /**
    * the current state of this buffer.
    *
    * The state of the buffer may be obtained via IsNewBuffer(), IsEmptyBuffer(),
    * IsLoadedBuffer(), IsModifiedBuffer() and IsInMemoryBuffer().
    *
    * See also \ref m_eStatus.
    */
   enum tStatus
   {
      SB_NOTLOADED=0,   ///< data has not yet been loaded into this buffer from disk
      SB_LOADED,        ///< this is a buffer loaded with data from disk
      SB_NEW,           ///< this is a fresh buffer, there is no link to disk yet
      SB_TEMP,          ///< this is a temporary buffer used for in-memory filtering
      SB_MODIFIED,      ///< buffer with data obtained from disk has been modified and must still be updated on disk
   };

   /**
    * buffer status type.
    */
   typedef tStatus StatusType;

protected:
   DECLARE_DYNCREATE( CScanBaseBuffer );// buffers can be serialized

   /*
    * internal data members:
    */

   /**
    * \brief status of the buffer contents (loaded, modified etc.).
    *
    * This status is used by the application to handle the data buffers. 
    * There are two types of buffer usages
    * - in-memory filters (on-line and viewing filters)
    * - normal filters
    *
    * For in-memory filters, the application sets the status for the <b>output
    * buffer</b> to \c SB_TEMP. The application deletes this temporary buffer
    * when it moves to another frame.
    *
    * For normal (interactive) filters, the application sets the status for the
    * <b>output buffer</b> to \c SB_NEW. After closing the filter's dialog with 
    * OK, the application writes the buffer's contents to disk.
    *
    * See also \ref tStatus.
    */
   StatusType    m_eStatus;             

   SizeType      m_dwMemoryAllocated;   ///< number of data points allocated in buffer
   LARGE_INTEGER m_liRAWIndex;          ///< file position in RAW data file
   LARGE_INTEGER m_liEditIndex;         ///< file position in edited data file
};

/*------------------------------------------------------------------------
** inline methods:
*/

/*
 * true if buffer contains a left--right scan.
 */
inline bool CScanBaseBuffer::HasLeftToRightScan() const
{
   return 0 != ( m_dwFlags & SPM_SDBF_LEFT2RIGHT );
}

/*
 * true if buffer contains a right--left scan.
 */
inline bool CScanBaseBuffer::HasRightToLeftScan() const
{
   return 0 != ( m_dwFlags & SPM_SDBF_RIGHT2LEFT );
}

/*
 * true if buffer contains both a left--right and a right--left scan.
 */
inline bool CScanBaseBuffer::IsBidirectionalScan() const
{
   return HasLeftToRightScan() && HasRightToLeftScan();
}

/*
 * X-size in pixels.
 */
inline CScanBaseBuffer::SizeType CScanBaseBuffer::Columns() const
{
   return m_dwSizeX;
}

/*
 * Y-size in pixels.
 */
inline CScanBaseBuffer::SizeType CScanBaseBuffer::Rows() const
{
   return m_dwSizeY;
}

/*
 * the buffer's data (no-const).
 */
inline CScanBaseBuffer::Pointer CScanBaseBuffer::Data()
{
   return m_pwData;
}

/*
 * the buffer's data (const).
 */
inline CScanBaseBuffer::ConstPointer CScanBaseBuffer::Data() const
{
   return m_pwData;
}

/*
 * the fourier left-right data (non-const).
 */
inline CScanBaseBuffer::FourierElementType** CScanBaseBuffer::FourierDataL2R()
{
   return m_pdFourierL2R;
}

/*
 * the fourier left-right data (const).
 */
inline CScanBaseBuffer::FourierElementType const* const * CScanBaseBuffer::FourierDataL2R() const
{
   return m_pdFourierL2R;
}

/*
 * the fourier right-left data (non-const).
 */
inline CScanBaseBuffer::FourierElementType** CScanBaseBuffer::FourierDataR2L()
{
   return m_pdFourierR2L;
}

/*
 * the fourier right-left data (const).
 */
inline CScanBaseBuffer::FourierElementType const* const* CScanBaseBuffer::FourierDataR2L() const
{
   return m_pdFourierR2L;
}

/*
 * Y-size by X-size number of pixels.
 */
inline CScanBaseBuffer::SizeType CScanBaseBuffer::GetFrameSize() const
{
   return m_dwSizeY * m_dwSizeX;
}

/*
 * number of pixels from the start of the L2R or R2L frame.
 */
inline CScanBaseBuffer::SizeType CScanBaseBuffer::GetPartialFrameOffset() const
{
   return m_dwPixelOffset;
}

/*
 * number of pixels of the partial frame.
 */
inline CScanBaseBuffer::SizeType CScanBaseBuffer::GetPartialFrameSize() const
{
   return m_dwPixelCount;
}

/*
 * true if all pixels of the frame are present.
 */
inline bool CScanBaseBuffer::IsCompleteFrame() const
{
#if 0
   CString s;
   s.Format( "IN: PixelCount:%d Pixels:%d FrameSize:%d",
   m_dwPixelCount, m_dwPixels, GetFrameSize() );

   Q_LOG( _T(s) );
#endif

   return m_dwPixels == ( 1 + IsBidirectionalScan() ) * GetFrameSize();

//    return m_dwPixelCount == GetFrameSize()
//        && m_dwPixels     == ( 1 + IsBidirectionalScan() ) * GetFrameSize();
}

/*
 * true if this buffer has not yet been used.
 */
inline bool CScanBaseBuffer::IsNewBuffer() const
{
   return SB_NEW == m_eStatus;
}

/*
 * true if data not yet loaded.
 */
inline bool CScanBaseBuffer::IsEmptyBuffer() const
{
   return SB_NOTLOADED == m_eStatus;
}

/*
 * true if data present in buffer.
 */
inline bool CScanBaseBuffer::IsLoadedBuffer() const
{
   return SB_LOADED == m_eStatus;
}

/*
 * true if data in buffer has been modified.
 */
inline bool CScanBaseBuffer::IsModifiedBuffer() const
{
   return SB_MODIFIED == m_eStatus;
}

/*
 * true if buffer is used for in-memory filtering.
 */
inline bool CScanBaseBuffer::IsInMemoryBuffer() const
{
   return SB_TEMP == m_eStatus;
}

/**
 * the pixel spacing in the x-direction in [m].
 */
inline CScanBaseBuffer::SpacingType CScanBaseBuffer::GetSpacingX() const
{
   return m_dXStepSize * 1e-12;
}

/**
 * the pixel spacing in the y-direction in [m].
 */
inline CScanBaseBuffer::SpacingType CScanBaseBuffer::GetSpacingY() const
{
   return m_dYStepSize * 1e-12;
}

/**
 * the bit spacing in the z-direction in [m].
 */
inline CScanBaseBuffer::SpacingType CScanBaseBuffer::GetSpacingZ() const
{
   /*
    * assume nano, unless unit is valid:
    */
   RealType unit = 1e-9;

   if ( m_csDataUnit.IsEmpty() )
      return m_dDataScaleFactor * unit;

   switch ( m_csDataUnit.GetAt(0) )
   {
      case 'p': unit = 1e-12; break;
      case 'n': unit = 1e-9; break;
      case 'u': unit = 1e-6; break;
      case 'm': unit = 1e-3; break;
      case 'k': unit = 1e+3; break;
      case 'M': unit = 1e+6; break;
      case 'G': unit = 1e+9; break;
   }

   return m_dDataScaleFactor * unit;
}

/**
 * the length for the given number of pixels in the x-direction in [m].
 */
inline CScanBaseBuffer::LengthType CScanBaseBuffer::GetLengthX( SizeType dx ) const
{
   return dx * GetSpacingX();
}

/**
 * the length for the given number of pixels in the y-direction in [m].
 */
inline CScanBaseBuffer::LengthType CScanBaseBuffer::GetLengthY( SizeType dy ) const
{
   return dy * GetSpacingY();
}

/*
 * the absolute height in [m] for given ADC value: scale * (adc + offset).
 */
inline CScanBaseBuffer::LengthType CScanBaseBuffer::GetAbsoluteHeight( ValueType adcValue ) const
{
   return ( adcValue + m_nDataOffset ) * GetSpacingZ();
}

/**
 * the rows required for FFT.
 */
inline CScanBaseBuffer::SizeType CScanBaseBuffer::GetRowsForFFT() const
{
   return GetSizeForFFT( Rows() );
}

/**
 * the columns required for FFT.
 */
inline CScanBaseBuffer::SizeType CScanBaseBuffer::GetColumnsForFFT() const
{
   return GetSizeForFFT( Columns() );
}

/**
 * the size required for FFT.
 */
inline CScanBaseBuffer::SizeType CScanBaseBuffer::GetSizeForFFT( SizeType size )
{
   return static_cast< SizeType >( pow( 2.0, ceil( log( static_cast<double>( size ) ) / log( 2.0 ) ) ) );
}

#endif // ifndef CFILTLIB_SCANBASEBUFFER_H

/*
 * end of file
 */

---