form_vec.h

Go to the documentation of this file.

/* Copyright (C) 2026 Chris Piker <chris-piker@uiowa.edu>
 *
 * Author: C. Piker, via Claude Opus 5
 *
 * 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_form_vec_h_
#define _das_form_vec_h_
 
#include <das3/form.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* --- component systems --------------------------------------------------- *
 *
 * The six geometric systems, one vocabulary for vectors and positions alike.
 * The first four need no origin.  Detic and graphic are lat/lon/alt ON a
 * reference ellipsoid, so the systems that need a surface are exactly the
 * systems that need an origin, and only a position may use them.
 *
 * That last rule belongs to the FORMALISM, not to the vocabulary.  The
 * das_vsys_* lookups answer for all six, and new_DasFormVector() and the
 * vector system= parser refuse anything past DAS_VSYS_VEC_MAX themselves.  The
 * names and symbols are plain data that consumers -- das3_spice, das3_cdf, the
 * CDF reader -- read across all six without caring which form issued a code,
 * and splitting the lookups at the formalism line only made each of them pick
 * a family first.  form_pos.h includes this file, so position code needs only
 * that header.
 *
 * The ID SPACE IS SHARED with form_cplx.h, which continues it at 7.  Separate
 * per-formalism spaces would be tidier, but a ubyte would then only be
 * readable next to the form that issued it.  The das_vsys_* lookups answer
 * NULL or -1 for the complex codes.
 */
 
#define DAS_VSYS_TYPE_MASK 0x0000000F
#define DAS_VSYS_UNKNOWN   0x00000000
#define DAS_VSYS_MIN       0x00000001
 
#define DAS_VSYS_CART      0x00000001  /* x, y, z                            */
#define DAS_VSYS_CYL       0x00000002  /* rho, phi, z                        */
#define DAS_VSYS_SPH       0x00000003  /* r, colatitude from +Z, phi         */
#define DAS_VSYS_CENTRIC   0x00000004  /* r, phi, latitude from the equator  */
#define DAS_VSYS_DETIC     0x00000005  /* eastward lon, lat, alt  (Earth)    */
#define DAS_VSYS_GRAPHIC   0x00000006  /* WESTWARD lon, lat, alt             */
 
#define DAS_VSYS_VEC_MAX   0x00000004  /* the last one a free vector may use */
#define DAS_VSYS_MAX       0x00000006  /* the last geometric system          */
 
DAS_API const char* das_vsys_toStr(ubyte uSys);
 
DAS_API ubyte das_vsys_fromStr(const char* sSys);
 
DAS_API const char* das_vsys_desc(ubyte uSys);
 
DAS_API const char* das_vsys_symbol(ubyte uSys, int iDir);
 
DAS_API int8_t das_vsys_index(ubyte uSys, const char* sSymbol);
 
DAS_API const char* das_vsys_name(ubyte uSys, int iDir);
 
DAS_API int8_t das_vsys_nameIndex(ubyte uSys, const char* sName);
 
#define das_vsys_isEllipsoidal(S) \
   (((S) == DAS_VSYS_DETIC)||((S) == DAS_VSYS_GRAPHIC))
 
DAS_API double das_vsys_default(ubyte uSys, int iDir);
 
/* Exported so that its address can be compared.  Client code uses the
   DAS_FORM_VEC macro below and has no reason to name this directly. */
DAS_API extern const DasForm_VTbl das_form_vector_vtbl;
 
#define DAS_FORM_VEC (&das_form_vector_vtbl)
 
DAS_API DasForm* new_DasFormVector(
   const char* sFrame, ubyte uSysType, const ubyte* pDirs
);
 
DAS_API const char* DasFormVector_frame(const DasForm* pThis);
 
DAS_API ubyte DasFormVector_sysType(const DasForm* pThis);
 
DAS_API const ubyte* DasFormVector_dirs(const DasForm* pThis);
 
/* For a component's display symbol -- "x", "λ", "θ" -- use DasVar_compSym(),
   which works for every kind of composite value and not just this one. */
 
/* To read a vector datum's components use das_datum_toDoubles().  It returns
   them in storage order and leaves any slot it does not fill untouched, so set
   those from das_vsys_default() above when a stream sends fewer components
   than its system defines. */
 
 
/* --- coordinate system conversion --------------------------------------- *
 *
 * Free functions rather than form methods, because form_pos.c needs them
 * for the systems it shares with this file.  No kernel data is involved;
 * the trigonometry is exact for the four systems a free vector may use.
 * Agreement with cspice's conventions is checked by test/TestSpice.c rather
 * than by linking cspice in, so libdas3's numbers never depend on a build
 * setting.
 */
 
DAS_API bool das_vsys_toCart(ubyte uSys, const double* pIn, double* pOut);
 
DAS_API bool das_vsys_fromCart(ubyte uSys, const double* pIn, double* pOut);
 
#ifdef __cplusplus
}
#endif
 
#endif /* _das_form_vec_h_ */