plane.h

Go to the documentation of this file.

/* Copyright (C) 2017-2024  Chris Piker <chris-piker@uiowa.edu>
 *                    2004  Jeremy Faden <jeremy-faden@uiowa.edu>
 *
 * This file is part of das2C, the Core Das2 C Library.
 * 
 * das2C is free software; you can redistribute it and/or modify it under
 * the terms of the GNU Lesser General Public License version 2.1 as published
 * by the Free Software Foundation.
 *
 * das2C is distributed in the hope that it will be useful, but WITHOUT ANY
 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
 * more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * version 2.1 along with das2C; if not, see <http://www.gnu.org/licenses/>. 
 */
 
#ifndef _das_plane_h_
#define _das_plane_h_
 
#include <math.h>
#include <stdbool.h>
 
#include <das2/buffer.h>
#include <das2/descriptor.h>
#include <das2/units.h>
#include <das2/encoding.h>
#include <das2/datum.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ************************************************************************* */
typedef enum plane_type {Invalid=-1, X=2001, Y=2003, Z=2004, YScan=2012
} plane_type_t;
 
 
typedef enum ytag_spec {ytags_none=0, ytags_list=1, ytags_series=2} ytag_spec_t;
      
plane_type_t str2PlaneType(const char * type);
 
DAS_API const char* PlaneType_toStr( plane_type_t type );
 
/* ************************************************************************* */
typedef struct plane_descriptor{
   DasDesc base;
 
   plane_type_t planeType;
   char* sName;
    
   /* The encoder/decoder used to read and write values for this plane. */
   DasEncoding* pEncoding;
    
   /* The units of measurement for values in this plane */
   das_units units;
    
   /* The number of values in each packet of this plane.
    * For planes other than <yscan>'s this is always 1
    */
   size_t uItems;
   
   /* Das 2.3 note
    * One of the fundamental assumptions in this code, way back from when
    * Jeremy started it was that all data could be converted to doubles.  
    * for high-time resolution data this just won't work.  There is no way
    * to encode time to nano-second accuracy over any appreciable time range
    * in a 64 bit floating point value. 
    * 
    * Furthermore, some data types are just fine as they are, there is no
    * reason to convert them.  We should think about removing this restriction.
    * for das 2.3.
    * 
    * --cwp 2018-10-25
    */
   double* pData;
   double value;  /* Convenience for planes that only store one data point */
   bool bAlloccedBuf; /* true if had to allocate a data buffer (<yscan> only)*/
   
   double rFill;  /* The fill value for this plane, will be wrapped in a 
                     macro to make isFill look like a function */
   bool _bFillSet;  /* Flag to make sure fill value has been set */
   
   ytag_spec_t ytag_spec;
   
   double* pYTags;       /* Explicit Y value array <yscan>'s */
   
   double yTagInter;    /* Or spec as a series <yscans>'s */
   double yTagMin;
   double yTagMax;
   
   das_units yTagUnits;
   DasEncoding* pYEncoding;
   
   /* set to true setValues or decode is called, set to false when encode is 
    * called */
   bool bPlaneDataValid;
    
   /* User data pointer.
    * The stream->packet->plane hierarchy provides a good organizational
    * structure for application data, especially for applications whose
    * purpose is to filter streams.  This pointer can be used to hold
    * a reference to information that is not serialized.  It is initialized
    * to NULL when a Plane Descriptor is created otherwise the library
    * doesn't deal with it in any other way. */
   void* pUser;  
   
} PlaneDesc;
 
DAS_API PlaneDesc* new_PlaneDesc_empty(void);
 
DAS_API PlaneDesc* new_PlaneDesc( 
   plane_type_t pt, const char* sGroup, DasEncoding* pType, das_units units
);
 
DAS_API PlaneDesc* new_PlaneDesc_yscan(
   const char* sGroup, DasEncoding* pZType, das_units zUnits, size_t uItems,
   DasEncoding* pYType, const double* pYTags, das_units yUnits
);
 
DAS_API PlaneDesc* new_PlaneDesc_yscan_series(
   const char* sGroup, DasEncoding* pZType, das_units zUnits, size_t uItems,
   double yTagInter, double yTagMin, double yTagMax, das_units yUnits
);
 
/* Creates a new plane descriptor from attribute strings
 * 
 * Unlike the other top-level descriptor objects in a Das2 Stream planes
 * are not independent XML documents.  This constructor is called from
 * the new_PktDesc_xml constructor to build plane descriptor object from
 * keyword / value stlye string lists.  The top level XML parsing is handled
 * by the PktDesc class.
 *
 * @param pParent the Properties parent for the new plane descriptor, this
 *        is always a PktDesc object pointer.
 *
 * @param pt The ::PlaneType, must be one of: 
 *    - X
 *    - Y 
 *    - YScan
 *    - Z
 *
 * @param attrs A null terminated array of strings.  It is assumed that
 *        the strings represent keyword value pairs.  i.e the first string
 *        is a setting name, such as 'units' the second string is the the
 *        value for 'units'.  Strings are processed in pairs until a NULL
 *        pointer is encountered.
 * 
 * @todo When encountering ASCII times, change the units to us2000 to better
 *       preserve precision for fine times for down stream processors.
 *  
 * @returns A pointer to new PlaneDesc allocated on the heap or NULL on an 
 *          error
 * @memberof PlaneDesc
 */
DAS_API PlaneDesc* new_PlaneDesc_pairs(
   DasDesc* pParent, plane_type_t pt, const char** attrs
);
 
DAS_API PlaneDesc* PlaneDesc_copy(const PlaneDesc* pThis);
 
 
DAS_API void del_PlaneDesc(PlaneDesc* pThis);
 
DAS_API bool PlaneDesc_equivalent(const PlaneDesc* pThis, const PlaneDesc* pOther);
 
DAS_API plane_type_t PlaneDesc_getType(const PlaneDesc* pThis);
 
DAS_API size_t PlaneDesc_getNItems(const PlaneDesc* pThis);
 
DAS_API void PlaneDesc_setNItems(PlaneDesc* pThis, size_t nItems);
 
 
DAS_API double PlaneDesc_getValue(const PlaneDesc* pThis, size_t uIdx);
 
 
DAS_API const das_datum* PlaneDesc_getDatum(
   const PlaneDesc* pThis, size_t uIdx, das_datum* pD
);
 
 
DAS_API DasErrCode PlaneDesc_setValue(PlaneDesc* pThis, size_t uIdx, double value);
 
DAS_API DasErrCode PlaneDesc_setTimeValue(
   PlaneDesc* pThis, const char* sTime, size_t idx
);
 
DAS_API DasEncoding* PlaneDesc_getValEncoder(PlaneDesc* pThis);
 
DAS_API void PlaneDesc_setValEncoder(PlaneDesc* pThis, DasEncoding* pEnc);
 
DAS_API const double* PlaneDesc_getValues(const PlaneDesc* pThis);
 
 
DAS_API void PlaneDesc_setValues(PlaneDesc* pThis, const double* pData);
 
 
DAS_API double PlaneDesc_getFill(const PlaneDesc* pThis );
 
#define PlaneDesc_isFill(P, V) \
 ((P->rFill == 0.0 && V == 0.0) || (fabs((P->rFill - V)/P->rFill)<0.00001))
 
/* bool PlaneDesc_isFill(const PlaneDesc* pThis, double value ); */
 
DAS_API void PlaneDesc_setFill( PlaneDesc* pThis, double value );
                            
DAS_API const char* PlaneDesc_getName(const PlaneDesc* pThis );
 
 
DAS_API void PlaneDesc_setName(PlaneDesc* pThis, const char* sName);
 
 
DAS_API das_units PlaneDesc_getUnits(const PlaneDesc* pThis );
 
DAS_API void PlaneDesc_setUnits(PlaneDesc* pThis, das_units units);
 
DAS_API das_units PlaneDesc_getYTagUnits( PlaneDesc* pThis );
 
DAS_API void PlaneDesc_setYTagUnits(PlaneDesc* pThis, das_units units);
 
 
DAS_API ytag_spec_t PlaneDesc_getYTagSpec(const PlaneDesc* pThis);
 
DAS_API const double* PlaneDesc_getYTags(const PlaneDesc* pThis);
 
 
DAS_API const double* PlaneDesc_getOrMakeYTags(PlaneDesc* pThis);
 
 
DAS_API void PlaneDesc_setYTags(PlaneDesc* pThis, const double* pYTags);
 
DAS_API void PlaneDesc_getYTagSeries(
   const PlaneDesc* pThis, double* pInterval, double* pMin, double* pMax
);
 
DAS_API void PlaneDesc_setYTagSeries(
   PlaneDesc* pThis, double rInterval, double rMin, double rMax
);
 
 
DAS_API DasErrCode PlaneDesc_encode(
   PlaneDesc* pThis, DasBuf* pBuf, const char* sIndent
);
 
DAS_API DasErrCode PlaneDesc_encodeData(PlaneDesc* pThis, DasBuf* pBuf, bool bLast);
 
DAS_API DasErrCode PlaneDesc_decodeData(const PlaneDesc* pThis, DasBuf* pBuf);
 
#ifdef __cplusplus
}
#endif
 
#endif /* _das_plane_h_ */