TraceSet.h

/* $Id: TraceSet.h,v 1.7 2003/03/13 17:15:51 vlad Exp $ */

#ifndef __TraceSet_h

#define __TraceSet_h

#include <mix/General.h>
#include <ldb/vsp_trace.h>
#include <ldb/trset.h>
#include <ldb/trselect.h>


/* class TraceSet
     data are followed;
   
   methods:
     == Lifetime
     int  OpenTraceSet (TraceSet* pTrSet,
       const char* szProject, const char* szNmod);
     void CloseTraceSet (TraceSet* pTrSet);

     == Information gaining
     AValue GetGeneralAttr (TraceSet theTrSet, int gaName);
     -- returns a general attribute (named gaName) of all data in set;
     AValue GetTraceAttrDirectly (TraceSet theTrSet, IterType it,
       unsigned int index, int taName);
     -- returns a trace attribute (named taName) for the indexed
     -- trace by iter type order without iter session;
     unsigned int GetSampleIndex (TraceSet theTrSet, float time);
     -- get index of sample at the the most closest time;
     IterType WhatIterNow (TraceSet theTrSet);
     -- returns type of iterator session;

     == Iterator session opening functions
     void ForwardIter (TraceSet theTrSet,
       unsigned int startIndex, unsigned int trCnt);
     -- start iteration in direct index order;
     -- from the lowest point to the highest; (upward)
     void BackwardIter (TraceSet theTrSet,
       unsigned int startIndex, unsigned int trCnt);
     -- start iteration in direct index order;
     -- from the highest point to the lowest; (downward)

     == Iterator session functions
     void IterEnd (TraceSet theTrSet);
     -- end of iteration;
     void IterStep (TraceSet theTrSet);
     -- changes current trace in iterator's order; meaningful from IterStart()
     -- and until IterEnd();
     int IterWhile (TraceSet theTrSet);
     -- returns !0 while iterator exist and iterations are not completed;
     AValue GetTraceAttr (TraceSet theTrSet, int taName);
     -- returns trace attribute with name taName; meaningful from IterStart()
     -- and until IterEnd();
     float* GetTraceData (TraceSet theTrSet);
     -- returns pointer on current trace; pointer value is defined
     -- until IterStep(); meaningful from <way>Iter() and until IterEnd();
     void ReadTraceDataDirectly (TraceSet theTrSet, IterType it,
                                 unsigned int index, float* data)
     -- read array of samples;

     == Trace data manipulation
     float* AllocEmptyTrace (TraceSet theTrSet);
     -- allocates trace data buffer by means of malloc();
     float GetAmaxOfTrace (TraceSet theTrSet, float* data);
     -- finds the greatest amplitude of trace among absolute values;
     float TraceLevelFloatGapAdjustment(TraceSet theTrSet, float gapWidth,
       float Aavg, float Amax, float* srcData, float* dstData);
     -- performs automatic level adjustment for from srcData trace to 
     -- dstData trace by means of float gap with gapWidth {ms};

     void WriteTraceDataDirectly (TraceSet theTrSet, IterType it,
                                  unsigned int index, float* data);
     -- write trace with index to the cache.
*/

#define GTA_SafeBase    1000

#define GABodySize  (GTA_SafeBase+0)
#define GAEndTime   (GTA_SafeBase+1)
#define GASamplesCnt    (GTA_SafeBase+2)
#define GAStartTime (GTA_SafeBase+3)
#define GAStepTime  (GTA_SafeBase+4)
#define GATimeWidth (GTA_SafeBase+5)
#define GATraceSize (GTA_SafeBase+6)
#define GATracesCnt (GTA_SafeBase+7)
#ifndef TAComponent
#   define TAComponent  (GTA_SafeBase+8)
#endif
#define TA_Component    TAComponent
#ifndef TAProbeDepth
#   define TAProbeDepth (GTA_SafeBase+9)
#endif
#define TADeviceDepth   TAProbeDepth
#define TA_ProbeDepth   TAProbeDepth
#define TAIndex     (GTA_SafeBase+10)
#define TAShotId    (GTA_SafeBase+11)
#define TA_Actuality    (GTA_SafeBase+12)
#define TA_Channel  (GTA_SafeBase+13)
#define TA_Control  (GTA_SafeBase+14)   /* 1-control, 0-downhole */
#define TA_FNumber  TAShotId
#define TA_Number   (GTA_SafeBase+15)
#define TA_Xopv     (GTA_SafeBase+16)
#define TA_Xspv     (GTA_SafeBase+17)
#define TA_Yopv     (GTA_SafeBase+18)
#define TA_Yspv     (GTA_SafeBase+19)
#define TA_Zopv     (GTA_SafeBase+20)
#define TA_Zspv     (GTA_SafeBase+21)
#define TAFileIndex (GTA_SafeBase+22)
#define TA_Type     (GTA_SafeBase+23)   /* 'D', 'C', 'S', 'A' */

#define itNone      0
#define itForward   1
#define itBackward  (-1)
#define itForwardIter   itForward
#define itBackwardIter  itBackward

typedef int IterType;
typedef float   AValue;
typedef TrSet*  TraceSet;

#ifdef __cplusplus
extern "C"
{
#endif

/*
 Constructor of a TraceSet object.  
 Returns:
   0 - OK, read-only mode;
  -1 - bad parameters;
  -2 - memory allocation error;
  -3 - a file is not found;
  -4 - reading file error;
  -5 - not a seismic trace file;
  -6 - sharing violation;
*/
int  OpenTraceSet (TraceSet* pTrSet,
                   const char* szProject, const char* szNmod);

/* Destructor of a TrSet object. */
void CloseTraceSet (TraceSet* theTrSet);

/*
   Reopen trace set in read-write mode
*/
int ReopenToEdit (TraceSet theTrSet);

/*
   Reopen trace set in read-only mode
*/
int ReopenToRead (TraceSet theTrSet);

/*
   Get values from modification table. If gaName is not defined or
   theTrSet has bad value the function returns (int)0. Usually
   a programmer must cast type of returned value to needed one.
*/
AValue GetGeneralAttr (TraceSet theTrSet, int gaName);

/*
   Returns a trace attribute (named taName) for the indexed
   trace by iter type order without iter session now.
*/
AValue GetTraceAttrDirectly (TraceSet theTrSet, IterType it,
                             unsigned int index, int taName);

/* Returns pointer on well name */
const char* GetWellName (TraceSet theTrSet);

/*  Returns shot point number */
int GetShotPoint (TraceSet theTrSet);

/*
   Returns current iterator session type or itNoIter
*/
IterType WhatIterNow (TraceSet theTrSet);

/*
   Creates iterator session with natural file order trace access.
   -> startIndex defines trace index of the first accessable trace.
   If the trace of this number is not exist due to size of file,
   effect will be as well as startIndex == 0.
   -> trCnt defines count of iterations. trCnt == 0 defines iterator
   for all traces from startIndex to end of file.

   Returns:
   0 - OK;
  -1 - bad parameters;
  -2 - trace set already has unclosed iterator session;
  -3 - startIndex or startIndex+trCnt is greater then count of traces in file;
*/
#define UNTIL_END 0
int ForwardIter (TraceSet theTrSet,
                 unsigned int startIndex, unsigned int trCnt);

int BackwardIter (TraceSet theTrSet,
                 unsigned int startIndex, unsigned int trCnt);

/* Closes current iterator session if it exist. */
void IterEnd (TraceSet theTrSet);

/* Makes iteration step */
void IterStep (TraceSet theTrSet);

/* Returns hint of iteration end */
int  IterWhile (TraceSet theTrSet);

/*
   Get value from current trace header. If taName is not defined or
   theTrSet has bad value or TrSet has not iterator session
   the function returns (int)0. Usually a programmer must cast type
   of returned value to needed one.
*/
AValue GetTraceAttr (TraceSet theTrSet, int taName);

/* Get array of samples */
float* GetTraceData (TraceSet theTrSet);

/* Read array of samples */
void ReadTraceDataDirectly (TraceSet theTrSet, IterType it,
                unsigned int index, float* data);

/* Allocate array of samples */
float* AllocTraceDataDirectly (TraceSet theTrSet, IterType it,
                               unsigned int index);

/* Write trace data directly; re-open nmod in read-write mode.
   Returns:
   0 - OK, done;
  -1 - internal error;
  -2 - common write error (see TrStatus);
  -3 - can't reopen in read-write mode (see TrStatus);
 */
int WriteTraceDataDirectly (TraceSet theTrSet, IterType it,
                unsigned int index, float* data);

/* Write actuality flag directly; re-open nmod in read-write mode.
   Returns:
   0 - OK, done;
  -1 - internal error;
  -2 - common write error (see TrStatus);
  -3 - can't reopen in read-write mode (see TrStatus);
  */
int WriteTraceActualityDirectly (TraceSet theTrSet, IterType it,
                 unsigned int index, Logic act);

/* Get index of sample at the the most closest time */
unsigned int GetSampleIndex (TraceSet theTrSet, float time);

/* Finds the greatest amplitude of trace among absolute values */
float GetAmaxOfTrace (TraceSet theTrSet, float* data);

/* Apply zero threshold to the trace body */
void ApplyZeroThreshold (TraceSet theTrSet, float* data,
             float zeroAmplLevel, float Amax);

/* Allocates trace data buffer by means of malloc() */
float* AllocEmptyTrace (TraceSet theTrSet);

/* Automatic Gain Control normalization procedure:
   INPUT:
   theTrSet - trace set container
   gapWidth - gain gap width, ms
   fAGCDynAmplify - AGC amplitude value coefficient (0..1)
   Amax     - source trace |A|max
   srcData  - source trace body
   OUTPUT:
   dstData  - destination trace body
   dAmax    - |A|max in destination trace body
*/
void    AGCnormProc (TraceSet theTrSet, float gapWidth, float fAGCDynAmplify, float Amax,
             float* srcData, float* dstData, float* dAmax);

#ifdef __cplusplus
};
#endif /* __cplusplus */

#endif  /* TraceSet.h */