A frame-tagged geometric vector. More...

#include <das3/form.h>

Include dependency graph for form_vec.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	das_vsys_isEllipsoidal(S) (((S) == DAS_VSYS_DETIC)\|\|((S) == DAS_VSYS_GRAPHIC))
	Is this an ellipsoidal system, i.e.

#define	DAS_FORM_VEC (&das_form_vector_vtbl)
	A geometric vector in a reference frame.

Functions
DAS_API const char *	das_vsys_toStr (ubyte uSys)
	Wire token for any of the six system codes, NULL if unrecognized.

DAS_API ubyte	das_vsys_fromStr (const char *sSys)
	Wire token to system code across all six, DAS_VSYS_UNKNOWN if unrecognized.

DAS_API const char *	das_vsys_desc (ubyte uSys)
	One line of prose about any of the six, for a "notes" property.

DAS_API const char *	das_vsys_symbol (ubyte uSys, int iDir)
	The canonical symbol for direction iDir of a system: "x", "r", "λ", "h" ...

DAS_API int8_t	das_vsys_index (ubyte uSys, const char *sSymbol)
	The inverse of das_vsys_symbol(): which direction a symbol names.

DAS_API const char *	das_vsys_name (ubyte uSys, int iDir)
	The ASCII name for direction iDir of any of the six: "x", "rho", "theta", "lambda", "h" ... Handy when unicode symbols are a hazard.

DAS_API int8_t	das_vsys_nameIndex (ubyte uSys, const char *sName)
	The inverse of das_vsys_name(), also accepting the symbols, so both "theta" and the Greek letter give 1 for a spherical system.

DAS_API double	das_vsys_default (ubyte uSys, int iDir)
	The value an ABSENT component of this system defaults to.

DAS_API bool	das_vsys_toCart (ubyte uSys, const double pIn, double pOut)
	Convert one vector from a component system to cartesian.

DAS_API bool	das_vsys_fromCart (ubyte uSys, const double pIn, double pOut)
	Convert one cartesian vector to a component system.

Detailed Description

A frame-tagged geometric vector.

NO origin.

A magnetic field, a velocity, a displacement: something with direction and magnitude that is not measured FROM anywhere. Free vectors add, subtract and scale, and one day will dot and cross.

Contrast form_pos.h, which is the same components with an ORIGIN and is therefore an affine point: positions subtract to give one of these, and two of them cannot be added at all. The discriminator is the origin, which is why they are two formalisms and not one with a flag.

surface= and body= aren't free vector concepts. A surface is a reference surface and for a position a body is the origin; a free vector has neither.

A frame that no kernel defines can still be described by a property; "frameInfo" is recommended for that purpose.

Parameters:

frame= the frame's NAME. OPTIONAL: a frameless vector is legal, it just cannot be frame-checked against anything. system= cartesian | cylindrical | spherical | centric. Default cartesian, which is what nearly all measured data is. sysorder= which canonical direction each stored component holds, e.g. "1;0;2". Default ascending.

ANGLES ARE ALWAYS DEGREES on the wire, so units carries whatever the radial component is in. The conversion helpers below take and return degrees for that reason.

Macro Definition Documentation

◆ das_vsys_isEllipsoidal

#define das_vsys_isEllipsoidal ( S ) (((S) == DAS_VSYS_DETIC)||((S) == DAS_VSYS_GRAPHIC))

Is this an ellipsoidal system, i.e.

one that requires a surface= ?

◆ DAS_FORM_VEC

#define DAS_FORM_VEC (&das_form_vector_vtbl)

A geometric vector in a reference frame.

It has a direction and a magnitude but no starting point, so two of them add.

See also: DasForm_isKind(), DasVar_formIs().

Function Documentation

◆ das_vsys_fromStr()

DAS_API ubyte das_vsys_fromStr ( const char * sSys )

Wire token to system code across all six, DAS_VSYS_UNKNOWN if unrecognized.

It knows detic and graphic, so code building a free vector must still check the result against DAS_VSYS_VEC_MAX.

◆ das_vsys_desc()

DAS_API const char * das_vsys_desc ( ubyte uSys )

One line of prose about any of the six, for a "notes" property.

NULL if unrecognized.

◆ das_vsys_symbol()

DAS_API const char * das_vsys_symbol	(	ubyte	uSys,
		int	iDir
	)

The canonical symbol for direction iDir of a system: "x", "r", "λ", "h" ...

Returns: a constant symbol, or NULL for a bad system or direction.

◆ das_vsys_index()

DAS_API int8_t das_vsys_index	(	ubyte	uSys,
		const char *	sSymbol
	)

The inverse of das_vsys_symbol(): which direction a symbol names.

Returns: the direction index, or -1 if the symbol is not in the system.

◆ das_vsys_name()

DAS_API const char * das_vsys_name	(	ubyte	uSys,
		int	iDir
	)

The ASCII name for direction iDir of any of the six: "x", "rho", "theta", "lambda", "h" ... Handy when unicode symbols are a hazard.

Returns: a constant name, or NULL for a bad system or direction.

◆ das_vsys_nameIndex()

DAS_API int8_t das_vsys_nameIndex	(	ubyte	uSys,
		const char *	sName
	)

The inverse of das_vsys_name(), also accepting the symbols, so both "theta" and the Greek letter give 1 for a spherical system.

Returns: the direction index, or -1 if the token is not in the system.

◆ das_vsys_default()

DAS_API double das_vsys_default	(	ubyte	uSys,
		int	iDir
	)

The value an ABSENT component of this system defaults to.

Zero everywhere except a radius, which defaults to 1 IN THE VARIABLE'S UNITS. Units always describe the radial component, even an implied one, so an angles-only vector in degrees reads as a unit direction rather than a null vector, and an angles-only position in R_E lies on the reference sphere. Detic and graphic have no radius, so every slot of theirs is zero and a bare latitude and longitude lie on the reference surface.

◆ das_vsys_toCart()

DAS_API bool das_vsys_toCart	(	ubyte	uSys,
		const double *	pIn,
		double *	pOut
	)

Convert one vector from a component system to cartesian.

Parameters

uSys	The system of the input values, one of DAS_VSYS_CART, DAS_VSYS_CYL, DAS_VSYS_SPH or DAS_VSYS_CENTRIC.
pIn	The three input components in CANONICAL direction order for uSys (see the DAS_VSYS_* definitions above), not storage order. Angles are in degrees.
pOut	Receives x, y, z in the same length units as the radial input component. May be the same array as pIn, to convert in place.

Returns: true on success, or false after a das_error() call if uSys has no kernel-free conversion. The ellipsoidal systems, DAS_VSYS_DETIC and DAS_VSYS_GRAPHIC, are measured against a reference surface that this function does not take, so they always land here.

◆ das_vsys_fromCart()

DAS_API bool das_vsys_fromCart	(	ubyte	uSys,
		const double *	pIn,
		double *	pOut
	)

Convert one cartesian vector to a component system.

The inverse of das_vsys_toCart().