dimension.h

/* Copyright (C) 2018 Chris Piker <chris-piker@uiowa.edu>
 *
 * This file is part of libdas2, the Core Das2 C Library.
 *
 * Libdas2 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.
 *
 * Libdas2 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 libdas2; if not, see <http://www.gnu.org/licenses/>.
 */
 
#ifndef _das_dimension_h_
#define _das_dimension_h_
 
#include <das2/descriptor.h>
#include <das2/frame.h>
#include <das2/variable.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define DASDIM_MAXDEP 16  // Arbitrary decision, can be changed
#define DASDIM_MAXVAR 16  // Another arbitrary changable descision
#define DASDIM_MAX_VEC_AXES 4 // Can change later
#define DASDIM_AXES_SZ 3  // Instead of single character so we can handle utf-8
 
   
/* OFFSET and REFERENCE variable roles were a tough call.  In the end you only
 * need center values to do DFT's.  The DFT code should look at the coordinate
 * series and see what if it has a constant change in index.  If so, you can do
 * a DFT, otherwise you can't.
 * 
 * Currently in das 2.2 land we know that one "package" of values is a
 * continuous waveform set.  We can look at the yTags, see if they are
 * consistent and the if they are then we can transform.  It's very clear when
 * we can do this, but it's also it requires a very specific data structure. 
 * So in a general data model, how do you get the yTags?  You *can* do it with a 
 * morphology check but those tend to be a rabbit hole of exploding if
 * statements.
 * 
 * The initial thought was to have offset dimensions, but that caused a massive
 * symmetry break in the data model.  Why have a rule that always combines two
 * dimensions with a + operator?  Why not other operators?  Also, if you set 
 * say the the "STD_DEV" variable in the reference dimension and also in the
 * offset dimension, how do you combine those?  It seems offset dimensions
 * trigger more problems then they solve.
 * 
 * The solution taken here is to introduce two variable roles, REFERENCE and
 * OFFSET.  Since this choice only requires adding two string constants it can
 * be ignored if turns out it's a bad choice.  Otherwise it simplifies the
 * concept of  breaking down values into a reference point that may change for
 * each packet and a set of fixed offsets.  These sorts of coordinates come up
 * a lot in our work, for example frequency values for down-mixed data, radar
 * return altitudes and waveform captures.
 * 
 * DASVAR_CENTER should still be provided for client codes that don't understand
 * the offset and reference semantic.  And since this can be done with one 
 * call to new_DasVarBinary() without exploding the network data volume 
 * it doesn't seem like that much of a burden.
 * 
 * Another approach would have been to expand properties to include an 
 * index/value relationship section.  We could define things like constant 
 * change of value for a change in a certain index and then define if rolling
 * the next index up is the same change as the lower index roll.  This seemed
 * like a much more complicated idea and didn't work so well with offsets that
 * are constant by record (i.e. the i value) but not constant by value index
 * (j,k,l ...).
 * -cwp
 */
   
#ifndef _das_dimension_c_  
extern const char* DASVAR_CENTER;
extern const char* DASVAR_MIN;
extern const char* DASVAR_MAX;
extern const char* DASVAR_WIDTH;
extern const char* DASVAR_MEAN;   /* all these can substitute for the center    */
extern const char* DASVAR_MEDIAN; /* if the center is missing but they are      */
extern const char* DASVAR_MODE;   /* distinct so it's good to include them here */
extern const char* DASVAR_REF; 
extern const char* DASVAR_OFFSET; 
extern const char* DASVAR_MAXERR; 
extern const char* DASVAR_MINERR;
extern const char* DASVAR_UNCERT;
extern const char* DASVAR_STD_DEV;
extern const char* DASVAR_SPREAD;
extern const char* DASVAR_WEIGHT;
#endif
 
 
#define DASDIM_AXES 4
 
#define DASDIM_ROLE_SZ 32
 
enum dim_type { DASDIM_UNK = 0, DASDIM_COORD, DASDIM_DATA };
 
typedef struct das_dim {
   DasDesc base;        /* Attributes or properties for this variable */
   enum dim_type dtype;    /* Coordinate or Data flag */
   
   /* A name for this particular variable group, cannot repeat in the dataset */
   char sId[DAS_MAX_ID_BUFSZ]; 
 
   /* A general dimension category such as 'B', 'E', etc */
   char sDim[DAS_MAX_ID_BUFSZ]; 
 
   /* Plot axes afinity, if any. For variables that have no internal
    * indicies, only the first axis make any sense.  Multiple axis 
    * entries are possible because this dimension may contain a vector.
    *
    * A common example of a vector is a "space" dimension defined by a 
    * 3-vector.
    */
   ubyte axes[DASDIM_AXES][3];
 
   /* A direction frame for muli-element vectors in this dimension.
    * Not stored as a pointer so that memcpy of descriptions takes less
    * postblit fix-ups.
    */
   char frame[DASFRM_NAME_SZ];
 
   /* Holds the max index to report out of this dimension.
    * The dimension may have internal indices beyond these
    * but they are not correlated with the overall dataset 
    * indicies */
   int iFirstInternal;
   
   /* The variables which supply data for this dimension */
   DasVar* aVars[DASDIM_MAXVAR];
   char aRoles[DASDIM_MAXVAR][DASDIM_ROLE_SZ];
   size_t uVars;
   
   /* For dependent variables (i.e. data) pointers to relavent independent
    * dimensions are here.  I don't think we need this here as the dataset
    * provides this information.  Going to punt it for now but will use
    * DasVar_orthoginalTo() when printing coordinate information */
   /* struct das_dim* aCoords[DASDIM_MAXDEP];
   size_t uCoords;*/
 
   void* pUser;
} DasDim;
 
DAS_API DasDim* new_DasDim(const char* sDim, const char* sName, enum dim_type dtype, int nRank);
 
#define DasDim_id(P)  ((const char*)(P->sId))
 
 
#define DasDim_dim(P) ((const char*)(P->sDim))
 
 
DAS_API char* DasDim_toStr(const DasDim* pThis, char* sBuf, int nLen);
 
DAS_API bool DasDim_addVar(DasDim* pThis, const char* sRole, DasVar* pVar);
 
 
DAS_API const DasVar* DasDim_getVar(const DasDim* pThis, const char* sRole);
 
 
#define DasDim_numVars(P) ((P)->uVars);
 
#define DasDim_getVarByIdx(P, I) ( (I)<((P)->uVars) ? ((const DasVar*)((P)->aVars[(I)])) : NULL )
 
#define DasDim_getRoleByIdx(P, I) ( (I)<((P)->uVars) ? ((const char*)((P)->aRoles[(I)])) : NULL )
 
 
 
DAS_API const DasVar* DasDim_getPointVar(const DasDim* pThis);
 
 
DAS_API DasVar* DasDim_popVar(DasDim* pThis, const char* role);
 
DAS_API void del_DasDim(DasDim* pThis);
 
 
DAS_API int DasDim_shape(const DasDim* pThis, ptrdiff_t* pShape);
 
 
DAS_API ptrdiff_t DasDim_lengthIn(const DasDim* pThis, int nIdx, ptrdiff_t* pLoc);
 
 
#ifdef __cplusplus
}
#endif
 
#endif /* _das_dimension_h_ */