form_geoloc.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_geoloc_h_
#define _das_form_geoloc_h_
 
#include <das3/form.h>
#include <das3/form_vector.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* --- component systems, the ellipsoidal half ----------------------------- *
 *
 * A surface is an ellipsoid reference, and detic/graphic are lat/lon/alt ON
 * that ellipsoid, so the systems that need a surface are exactly the systems
 * that need a center.  They are therefore geoloc's, and a free vector cannot
 * hold them -- form_vector.c refuses them by range.
 *
 * The codes CONTINUE form_vector.h's numbering rather than starting a second
 * space, so one ubyte reads the same next to either formalism and a consumer
 * like das3_spice can switch over all six in one statement.
 *
 * The das_geosys_* lookups below are the SUPERSET: they answer for all six by
 * handling these two and delegating the rest downward.  Call these when you
 * may be holding either kind of form; call das_vsys_* only when you know it
 * is a free vector.
 */
 
#define DAS_VSYS_DETIC     0x00000005  /* eastward lon, lat, alt  (Earth)    */
#define DAS_VSYS_GRAPHIC   0x00000006  /* WESTWARD lon, lat, alt             */
 
#define DAS_VSYS_MAX       0x00000006
 
DAS_API const char* das_geosys_str(ubyte uSys);
 
DAS_API ubyte das_geosys_id(const char* sSys);
 
DAS_API const char* das_geosys_desc(ubyte uSys);
 
DAS_API const char* das_geosys_symbol(ubyte uSys, int iDir);
 
DAS_API int8_t das_geosys_index(ubyte uSys, const char* sSymbol);
 
#define das_geosys_isEllipsoidal(S) \
   (((S) == DAS_VSYS_DETIC)||((S) == DAS_VSYS_GRAPHIC))
 
/* Exported so that its address can be compared.  Client code uses the
   DAS_FORM_GEOLOC macro below and has no reason to name this directly. */
DAS_API extern const DasForm_VTbl das_form_geoloc_vtbl;
 
#define DAS_FORM_GEOLOC (&das_form_geoloc_vtbl)
 
DAS_API DasForm* new_DasFormGeoLoc(
   const char* sBody, const char* sFrame, const char* sSurface,
   ubyte uSysType, const ubyte* pDirs
);
 
DAS_API const char* DasFormGeoLoc_body(const DasForm* pThis);
 
DAS_API const char* DasFormGeoLoc_frame(const DasForm* pThis);
 
DAS_API const char* DasFormGeoLoc_surface(const DasForm* pThis);
 
DAS_API ubyte DasFormGeoLoc_sysType(const DasForm* pThis);
 
DAS_API const ubyte* DasFormGeoLoc_dirs(const DasForm* pThis);
 
/* For a component's display symbol -- "λ", "φ", "h" -- use DasVar_compSym(),
   which works for every kind of composite value and not just this one. */
 
/* To read a position datum's components use das_datum_toDoubles().  It returns
   them in storage order.
 
   A missing component of a position is zero, and there is no
   das_geosys_default() to call because the answer is zero for every slot of all
   six systems.  This is where the two geometric formalisms differ:
   das_vsys_default() gives a free vector's missing radius a value of 1, so that
   a vector sent as angles alone reads as a direction.  Positions get no such
   treatment, since a radius of 1 would place a spacecraft one kilometre from
   the body's center. */
 
#ifdef __cplusplus
}
#endif
 
#endif /* _das_form_geoloc_h_ */