PlaneDesc Struct Reference

#include <das2/plane.h>

Inheritance diagram for PlaneDesc:

Detailed Description

Describes a data plane within a packet type.

Each packet of Das2 stream data contains values for one or more planes. To illustrate this take a look at the packet header in the X Tagged Stream Example from the Das2 ICD.

 [00]000088<stream>
 <properties DatumRange:xRange="2013-001T01:00:00 to 2013-01:10:00"/>
 </stream>
 [01]000424<packet>

   <x type="time23" units="us2000"></x>

   <y type="ascii11" name="radius" units=""><properties String:yLabel="R!DE!N" /></y>

   <y type="ascii11" name="mag_lat" units=""><properties String:yLabel="MLat" /></y>

   <y type="ascii11" name="mag_lt" units=""><properties String:yLabel="MLT" /></y>

   <y type="ascii11" name="l_shell" units=""><properties String:yLabel="L" /></y>

 </packet>
 :01:2013-001T01:00:00.000  5.782e+00 -1.276e+01  3.220e+00  6.079e+00
 :01:2013-001T01:01:00.000  5.782e+00 -1.274e+01  3.232e+00  6.077e+00
 :01:2013-001T01:02:00.000  5.781e+00 -1.272e+01  3.244e+00  6.076e+00

Each <x> and <y> element inside the <packet> element above is a serialized PlaneDesc. The point of a PlaneDesc structure is to:

Hold the definition of a single plane within a single packet type.
Assist PacketDescriptors with serializing and de-serializing data packets.

Just as an isolated plane without a parent <packet> tag does not make sense in a Das2 Stream, PlaneDesc structures don't have much use on their own. They are typically owned by a PacketDescriptor and accessed via the PacketDescriptor.planes array.

Public Member Functions
PlaneDesc *	new_PlaneDesc_empty (void)
	Creates a Plane Descriptor with mostly empty settings.
PlaneDesc *	new_PlaneDesc (plane_type_t pt, const char sName, DasEncoding pType, UnitType units)
	Creates a new X,Y or Z plane descriptor.
PlaneDesc *	new_PlaneDesc_yscan (const char sName, DasEncoding pZType, UnitType zUnits, size_t uItems, DasEncoding pYType, const double pYTags, UnitType yUnits)
	Creates a new <yscan> plane descriptor.
PlaneDesc *	PlaneDesc_copy (const PlaneDesc *pThis)
	Copy constructor for planes Deep copy one a plane except for the parent id.
void	del_PlaneDesc (PlaneDesc *pThis)
	Free a plane object allocated on the heap.
plane_type_t	PlaneDesc_getType (const PlaneDesc *pThis)
	Get a plane's type.
size_t	PlaneDesc_getNItems (const PlaneDesc *pThis)
	Get the number of items in a plane YScan planes have a variable number of items, for all other types this function returns 1.
double	PlaneDesc_getValue (const PlaneDesc *pThis, size_t uIdx)
	Get the first value from a plane.
ErrorCode	PlaneDesc_setValue (PlaneDesc *pThis, size_t uIdx, double value)
	Set a current value in a plane.
ErrorCode	PlaneDesc_setTimeValue (PlaneDesc pThis, const char sTime, size_t idx)
	Set a single time value in a plane.
DasEncoding *	PlaneDesc_getValEncoder (PlaneDesc *pThis)
	Get the data value encoder/decoder object for a plane The encoder returned via this pointer can be mutated and any changes will be reflected in the next data write for the plane.
void	PlaneDesc_setValEncoder (PlaneDesc pThis, DasEncoding pEnc)
	Set the data value encoder/decoder object for a plane The previous encoder's memory is returned the heap via free().
const double *	PlaneDesc_getValues (const PlaneDesc *pThis)
	Get a pointer to the current set of values in a plane.
void	PlaneDesc_setValues (PlaneDesc pThis, const double pData)
	Set all the current values for a plane.
double	PlaneDesc_getFill (const PlaneDesc *pThis)
	Returns the fill value identified for the plane.
bool	PlaneDesc_isFill (const PlaneDesc *pThis, double value)
	Returns non-zero if the value is the fill value identified for the data plane.
void	PlaneDesc_setFill (PlaneDesc *pThis, double value)
	Identify the double fill value for the plane.
const char *	PlaneDesc_getName (const PlaneDesc *pThis)
	Get the name of a plane.
void	PlaneDesc_setName (PlaneDesc pThis, const char sName)
	Set the name of a plane.
UnitType	PlaneDesc_getUnits (const PlaneDesc *pThis)
	Get the units of measure for a plane's packet data.
void	PlaneDesc_setUnits (PlaneDesc *pThis, UnitType units)
	Set the unit type for the plane data.
UnitType	PlaneDesc_getYTagUnits (PlaneDesc *pThis)
	Get Y axis units for a 2-D plane.
const double *	PlaneDesc_getYTags (const PlaneDesc *pThis)
	Get Y axis coordinates for a 2-D plane of data.
ErrorCode	PlaneDesc_encode (PlaneDesc pThis, DasBuf pBuf, const char *sIndent, bool bDependant)
	Serialize a Plane Descriptor as XML data.
ErrorCode	PlaneDesc_encodeData (PlaneDesc pThis, DasBuf pBuf, bool bLast)
	Serialize a plane's current data.
ErrorCode	PlaneDesc_decodeData (const PlaneDesc pThis, DasBuf pBuf)
	Read in a plane's current data.
Descriptor Functions
These work for any type of Descriptor, including PlaneDesc , PktDesc and StreamDesc. To make your compiler happy you will need to cast Plane, Packet and Stream Descriptor pointers to just the generic type of Descriptor pointer when using these functions. For example: PktDesc* pPktDesc; hasProperty((Descriptor*)pPktDesc, "SomePropName");
bool	Desc_hasProp (const Descriptor pThis, const char propertyName)
	Determine if a property is present in a Descriptor or it's ancestors.
const char *	Desc_getPropStr (const Descriptor pThis, const char propertyName)
	read the property of type String named propertyName.
ErrorCode	Desc_setPropStr (Descriptor pThis, const char sName, const char *sVal)
	SetProperty methods add properties to any Descriptor (stream,packet,plane).
double	Desc_getPropDouble (const Descriptor pThis, const char propertyName)
	Read the property of type double named propertyName.
ErrorCode	Desc_setPropDouble (Descriptor pThis, const char propertyName, double value)
	Set property of type double.
double	Desc_getPropDatum (Descriptor pThis, const char sPropName, UnitType units)
	Get the a numeric property in the specified units.
ErrorCode	Desc_setPropDatum (Descriptor pThis, const char sName, double rVal, UnitType units)
	Set property of type Datum (double, UnitType pair).
double *	Desc_getPropDoubleArray (Descriptor pThis, const char propertyName, int *nitems)
	Get the values of an array property.
ErrorCode	Desc_setPropDoubleArray (Descriptor pThis, const char propertyName, int nitems, double *value)
	Set the property of type double array.
int	Desc_getPropInt (const Descriptor pThis, const char propertyName)
	Get a property integer value.
ErrorCode	Desc_setPropInt (Descriptor pThis, const char sName, int nVal)
	Set the property of type int.
ErrorCode	Desc_setPropDatumRange (Descriptor pThis, const char sName, double beg, double end, UnitType units)
	Set property of type DatumRange (double, double, UnitType triple).
ErrorCode	Desc_setPropFloatArray (Descriptor pThis, const char propertyName, int nitems, float *value)
	Set the property of type float array.
void	Desc_copyProperties (Descriptor pThis, const Descriptor source)
	Deepcopy properties into a descriptor.

Member Function Documentation

PlaneDesc * new_PlaneDesc	(	plane_type_t	pt,
		const char *	sName,
		DasEncoding *	pType,
		UnitType	units
	)

Creates a new X,Y or Z plane descriptor.

Parameters:

	pParent	the Properties parent for the new plane descriptor, this is always a PktDesc object pointer.
	pt	The PlaneType, must be one of: X - Independent Values Y - Dependent or Independent Values Z - Dependent Values YScan - Dependent Values
	sName	the name for the new plane
	pType	an encoding object for the new plane. The PlaneDesc will take ownership of this object and free it when del_PlaneDesc is called.
	units	The units of measurement for data in this plane.

Returns:: A pointer to new PlaneDesc allocated on the heap.

PlaneDesc * new_PlaneDesc_yscan	(	const char *	sName,
		DasEncoding *	pZType,
		UnitType	zUnits,
		size_t	uItems,
		DasEncoding *	pYType,
		const double *	pYTags,
		UnitType	yUnits
	)

Creates a new <yscan> plane descriptor.

A <yscan> plane is an array of Z-values taken along Y for each X tag. Spectrogram amplitudes are commonly transmitted in this plane type. In that case <x> contains times, <yscan> values are amplitudes, and the frequencies are held in the yTags attribute for the plane.

Parameters:

	sName	the name for the new plane, may be the empty string ""
	pType	an encoding object for the new plane. The PlaneDesc will take ownership of this object and free it when del_PlaneDesc is called.
	zUnits	The units of measurement for Z-axis data in this plane.
	uItems	The number of data values in each packet of this plane's data. i.e. the number of yTags.
	pYType	The encoding for the Y values. If NULL, a simple encoding will be defined with the format string "%.6e"
	pYTags	The YTags for the new plane, if NULL the value index will be used as the YTags. I.e. the Y axis values will be 0, 1, 2, ... uItems - 1
	yUnits	The units for yTag values.

Returns:: A pointer to new PlaneDesc allocated on the heap.

PlaneDesc * PlaneDesc_copy ( const PlaneDesc * pThis )

Copy constructor for planes Deep copy one a plane except for the parent id.

Parameters:

pThis

The plane descriptor to copy

Returns:: A new plane descriptor allocated on the heap. All properties of the plane descriptor are duplicated as well.

void del_PlaneDesc ( PlaneDesc * pThis )

Free a plane object allocated on the heap.

This frees the memory allocated for the main structure as well as any internal buffers allocated for storing data values and Y-tags.

Parameters:

pThis

The plane descriptor to free

plane_type_t PlaneDesc_getType ( const PlaneDesc * pThis )

Get a plane's type.

Parameters:

pThis

The plane descriptor to query

Returns:: The plane type, which is one of X, Y, YScan or Z

size_t PlaneDesc_getNItems ( const PlaneDesc * pThis )

Get the number of items in a plane YScan planes have a variable number of items, for all other types this function returns 1.

Parameters:

pThis

the PlaneDiscriptor

Returns:: the number of items in plane

double PlaneDesc_getValue	(	const PlaneDesc *	pThis,
		size_t	uIdx
	)

Get the first value from a plane.

Get the current value for an item in a plane, Note that X, Y and Z planes only have one item.

See also:: DasEnc_write() for converting doubles to time strings.

Parameters:

	The	Plane descriptor object
	uIdx	the index of the value to retrieve, this is always 0 for X, Y, and Z planes.

Returns:: the current value or FILL_VALUE in no data have been read or set.

ErrorCode PlaneDesc_setValue	(	PlaneDesc *	pThis,
		size_t	uIdx,
		double	value
	)

Set a current value in a plane.

Set a current value for an item in a plane. Note X, Y and Z planes only have one item.

Parameters:

	pThis	The plane in question
	value	The new value

Returns:: 0 if successful or a positive error number otherwise.

ErrorCode PlaneDesc_setTimeValue	(	PlaneDesc *	pThis,
		const char *	sTime,
		size_t	idx
	)

Set a single time value in a plane.

Manually sets a current value for a plane instead of decoding it from an input stream. The given time string is converted to a broken down time using the parsetime function from daslib and then the brokend down time is converted to a double in the units specified for this plane.

Parameters:

	pThis	The plane to get the value
	sTime	a parse-able time string
	idx	The index at which to write the value, for X, Y and Z planes 0 is the only valid index.

Returns:: 0 if successful or a positive error number otherwise. Attempting to set a time value for planes who's units are not time is an error.

DasEncoding * PlaneDesc_getValEncoder ( PlaneDesc * pThis )

Get the data value encoder/decoder object for a plane The encoder returned via this pointer can be mutated and any changes will be reflected in the next data write for the plane.

Parameters:

pThis

The data plane in question

Returns:: The current encoder for this plane. You may change fields within the returned encoder but do not free() the return value.

void PlaneDesc_setValEncoder	(	PlaneDesc *	pThis,
		DasEncoding *	pEnc
	)

Set the data value encoder/decoder object for a plane The previous encoder's memory is returned the heap via free().

Parameters:

	pThis	The data plane in question
	pEnc	A pointer to the new encoder structure, the plane takes ownership of it's memory. This value must not be null

const double * PlaneDesc_getValues ( const PlaneDesc * pThis )

Get a pointer to the current set of values in a plane.

Planes are basically wrappers around a double array with some encoding and decoding information. This function provides a pointer to the value array for the plane.

Parameters:

[in] pThis The plane in question

Returns:: A pointer to the current plane's data, or NULL if neither PlaneDesc_setValue() or PlaneDesc_decode() have been called.

void PlaneDesc_setValues	(	PlaneDesc *	pThis,
		const double *	pData
	)

Set all the current values for a plane.

See also:: PlaneDesc_getNItems()

Parameters:

	pThis	The plane to receive the values
	pData	A pointer to an array of doubles that is the same length as the number of items in this plane. Values are copied in, no references are kept to the input pointer after the function completes

double PlaneDesc_getFill ( const PlaneDesc * pThis )

Returns the fill value identified for the plane.

Note: If the value has not been explicitly specified, then the canonical value is used.

const char * PlaneDesc_getName ( const PlaneDesc * pThis )

Get the name of a plane.

Returns:: the name of the plane, or "" if it is not specified.

void PlaneDesc_setName	(	PlaneDesc *	pThis,
		const char *	sName
	)

Set the name of a plane.

Parameters:

	pThis	The plane descriptor to rename
	sName	the new name for the plane, will be copied into internal memory

UnitType PlaneDesc_getUnits ( const PlaneDesc * pThis )

Get the units of measure for a plane's packet data.

Returns:: the units of the data values in a plane

void PlaneDesc_setUnits	(	PlaneDesc *	pThis,
		UnitType	units
	)

Set the unit type for the plane data.

All Das2 Stream values are stored as doubles within the library the units property indicates what these doubles mean

Parameters:

	pThis	The Plane to alter
	units	The new units setting. Note this value may be NULL in which case the Plane will be set to UNIT_DIMENSIONLESS.

UnitType PlaneDesc_getYTagUnits ( PlaneDesc * pThis )

Get Y axis units for a 2-D plane.

Returns:: the Units of the YTags of a <yscan> plane.

const double * PlaneDesc_getYTags ( const PlaneDesc * pThis )

Get Y axis coordinates for a 2-D plane of data.

Returns:: an array of doubles containing the yTags for the YSCAN plane

ErrorCode PlaneDesc_encode	(	PlaneDesc *	pThis,
		DasBuf *	pBuf,
		const char *	sIndent,
		bool	bDependant
	)

Serialize a Plane Descriptor as XML data.

This function is almost the opposite of new_PlaneDesc_pairs()

Parameters:

	pThis	The plane descriptor to store as string data
	pBuf	A buffer object to receive the bytes
	sIndent	A string to place before each line of output
	bDependant	If true this is dependant data and should serialized with a name attribute.

Returns:: 0 if successful, or a positive integer if not.

ErrorCode PlaneDesc_encodeData	(	PlaneDesc *	pThis,
		DasBuf *	pBuf,
		bool	bLast
	)

Serialize a plane's current data.

In addition to holding the format information for a single data plane in a Packet, PlaneDesc objects also hold one set of samples for the plane. For the plane types <x>, <y>, and <z> a single plane's data is just one value. For the <yscan> type a single plane's data is 1-N values. Use this function to encode a planes current data values for output.

Parameters:

	pThis	The plane descriptor that has been loaded with data
	pBuf	A buffer to receive the encoded bytes
	bLast	All ASCII type values are written with a single space after the value except for the last value of the last plane which has a newline character appended. Set this to true if this is the last plane in the packet which is being encoded.

Returns:: 0 if successful, or a positive integer if not.

ErrorCode PlaneDesc_decodeData	(	const PlaneDesc *	pThis,
		DasBuf *	pBuf
	)

Read in a plane's current data.

Parameters:

	pThis	The plane to receive the data values
	pBuf	The buffer containing values to decode.

Returns:: 0 if successful, or a positive integer if not.

bool Desc_hasProp	(	const Descriptor *	pThis,
		const char *	propertyName
	)			`[inherited]`

Determine if a property is present in a Descriptor or it's ancestors.

Parameters:

	pThis	the descriptor object to query
	propertyName	the name of the property to retrieve.

Returns:: true if the descriptor or one of it's ancestors has a property with the given name, false otherwise.

ErrorCode Desc_setPropStr	(	Descriptor *	pThis,
		const char *	sName,
		const char *	sVal
	)			`[inherited]`

SetProperty methods add properties to any Descriptor (stream,packet,plane).

The typed methods (e.g. setPropertyDatum) property tag the property with a type so that it will be parsed into the given type.

double Desc_getPropDouble	(	const Descriptor *	pThis,
		const char *	propertyName
	)			`[inherited]`

Read the property of type double named propertyName.

The property value is parsed using sscanf.

double Desc_getPropDatum	(	Descriptor *	pThis,
		const char *	sPropName,
		UnitType	units
	)			`[inherited]`

Get the a numeric property in the specified units.

Descriptor properties my be provided as Datums. Datums are a double value along with a specified measurement unit.

Parameters:

	pThis	The Descriptor containing the property in question.
	sPropName	The name of the property to retrieve.
	units	The units of measure in which the return value will be represented. If the property value is stored in a different set of units than those indicated by this parameter than the output will be converted to the given unit type.

Returns:: The converted value or FILL_VALUE if conversion to the desired units is not possible.

ErrorCode Desc_setPropDatum	(	Descriptor *	pThis,
		const char *	sName,
		double	rVal,
		UnitType	units
	)			`[inherited]`

Set property of type Datum (double, UnitType pair).

If a property with this name already exists it is 1st deleted and then the new property is added in its place.

Parameters:

	pThis	The descriptor to receive the property
	sName	The name of the property to set
	rVal	The numeric value of the property
	units	The units of measure for the property

double * Desc_getPropDoubleArray	(	Descriptor *	pThis,
		const char *	propertyName,
		int *	nitems
	)			`[inherited]`

Get the values of an array property.

Space for the array is allocated by getDoubleArrayFromString. and nitems is set to indicate the size of the array.

Parameters:

`[in]`	pThis	the descriptor object to query
`[in]`	propertyName	the name of the proprety to retrieve
`[out]`	nitems	a pointer to a an integer containing the number of values in the returned array.

Returns:: A pointer to a double array allocated on the heap. It is the caller's responsibility to depose of the memory when it is no longer needed. If the named property doesn't exist the program exits.

See also:: hasProperty()

int Desc_getPropInt	(	const Descriptor *	pThis,
		const char *	propertyName
	)			`[inherited]`

Get a property integer value.

Parameters:

	pThis	the descriptor object to query
	propertyName	the name of the proprety to retrieve

Returns:: The value of the named property or exits the program if the named proprety doesn't exist in this descriptor.

See also:: hasProperty()

ErrorCode Desc_setPropFloatArray	(	Descriptor *	pThis,
		const char *	propertyName,
		int	nitems,
		float *	value
	)			`[inherited]`

Set the property of type float array.

Note the array is cast to a double array before encoding.

void Desc_copyProperties	(	Descriptor *	pThis,
		const Descriptor *	source
	)			`[inherited]`

Deepcopy properties into a descriptor.

Parameters:

	pThis	the descriptor to receive a copy of the properties
	source	the descriptor with the properties to be copied.

The documentation for this struct was generated from the following file:

das2/plane.h

PlaneDesc Struct Reference

Detailed Description

Public Member Functions

Descriptor Functions

Member Function Documentation