form_vector.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_vector_h_
#define _das_form_vector_h_
 
#include <das3/form.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* --- component systems, the free-vector half ----------------------------- *
 *
 * The system vocabulary belongs to the formalisms that use it, not to a
 * central table, so that a new formalism can bring its own systems without
 * editing shared code.  This file owns the four that need no origin; the two
 * ellipsoidal ones are measured ON a body and live in form_geoloc.h.
 *
 * The ID SPACE IS CONTINUOUS ACROSS THE TWO FILES (geoloc picks up at 5) and
 * that is deliberate.  Separate per-formalism spaces would be tidier, but a
 * ubyte would then only be readable next to the form that issued it, and the
 * consumers -- das3_spice above all -- switch over all six in one statement.
 * One space costs geoloc a downward include it already has.
 */
 
#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_VEC_MAX   0x00000004  /* the last one a free vector may use */
 
DAS_API const char* das_vsys_str(ubyte uSys);
 
DAS_API ubyte das_vsys_id(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 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_geoloc.c needs them
 * for the systems it shares with this file and adds its own ellipsoidal arms.
 * Values are in CANONICAL direction order (not storage order) and angles are
 * in DEGREES.
 *
 * Under SPICE=yes these delegate to cspice so that every das tool agrees to
 * the last bit.  Otherwise they do the trigonometry directly, which is exact
 * for these four systems -- no kernel data is involved.
 */
 
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);
 
/* The trigonometric implementations, ALWAYS COMPILED even under SPICE=yes.
 *
 * Exported so a SPICE build can assert the two paths agree.  The risk in
 * having two implementations is not rounding, it is CONVENTION -- recsph_c
 * returns colatitude from +Z while reclat_c returns latitude, and the two
 * also disagree about which slot the longitude sits in.  A mismatch there is
 * a 90 degree error that surfaces in someone's plot months later, so the
 * fallback must stay testable rather than being compiled out. */
DAS_API bool das_vsys_toCartTrig(ubyte uSys, const double* pIn, double* pOut);
DAS_API bool das_vsys_fromCartTrig(ubyte uSys, const double* pIn, double* pOut);
 
#ifdef __cplusplus
}
#endif
 
#endif /* _das_form_vector_h_ */