plane.h File Reference

Header for Plane Descriptor Objects. More...

Detailed Description

Header for Plane Descriptor Objects.

#include <math.h>
#include <stdbool.h>
#include <das2/buffer.h>
#include <das2/descriptor.h>
#include <das2/units.h>
#include <das2/encoding.h>

Go to the source code of this file.

Data Structures
struct	PlaneDesc
	Describes a data plane within a packet type. More...

Enumerations
enum	plane_type_t
	An enumeration of packet data plane types. More...

Functions
plane_type_t	str2PlaneType (const char *type)
	Returns the enumeration for the data type string.
const char *	PlaneType_toStr (plane_type_t type)
	Returns the string for the enumeration.
void	PlaneDesc_setNItems (PlaneDesc *pThis, size_t nItems)
	Set the number of items in a plane. More...
void	PlaneDesc_setYTagUnits (PlaneDesc *pThis, das_units units)
	Set the YTag units for a YScan plane. More...
ytag_spec_t	PlaneDesc_getYTagSpec (const PlaneDesc *pThis)
	Get the storage method for yTag values. More...
void	PlaneDesc_setYTags (PlaneDesc *pThis, const double *pYTags)
	Provide a new set of yTag values to a yScan plane. More...
void	PlaneDesc_getYTagSeries (const PlaneDesc *pThis, double *pInterval, double *pMin, double *pMax)
	Get the Y axis coordinate series for a 2-D plane of data. More...
void	PlaneDesc_setYTagSeries (PlaneDesc *pThis, double rInterval, double rMin, double rMax)
	Set a YScan to use series definition for yTags. More...

Enumeration Type Documentation

enum plane_type_t

An enumeration of packet data plane types.

A Das2 packet contains one dependent value set from each of it's Planes. The plane types are:

X - Data defined within an <x> plane, typically these are time values. There is one value for each X plane in a Das2 data packet

Y - Data defined within a <y> plane, this would be line-plot data. There is one value for each Y plane in a Das2 data packet. This value is correlated with the <x> plane value in the packet.

Z - Data defined within a <z> plane. There is one value for each Z plane in a Das2 data packet. The Z value is correlated with both the <x> plane value and the <y> plane value.

YScan - Our most common data type, values are defined by a <yscan> plain tag. There are 1-N values in each YScan plane for each das2 data packet. All YScan values from a single data packet are correlated with the X value provide in the <x> plane.

Function Documentation

void PlaneDesc_setNItems	(	PlaneDesc *	pThis,
		size_t	nItems
	)

Set the number of items in a plane.

Warning

Calling this function with a different size then the current number of items in a plane will cause a re-allocation of the internal data values memory buffer. Any pointers returned previously by PlaneDesc_getValues() or PlaneDesc_getYTags() will be invalidated.

Always call PlaneDesc_setYTags() or PlaneDesc_setYTagSeries() after changing the number of items in a plane! Failure do to so has undefined results.

Parameters

pThis	The plane, which must be of type YScan
nItems	the new number of items in the plane.

void PlaneDesc_setYTagUnits	(	PlaneDesc *	pThis,
		das_units	units
	)

Set the YTag units for a YScan plane.

Parameters

pThis	The plane, which must be of type YScan.
units	The new units

ytag_spec_t PlaneDesc_getYTagSpec

(

const PlaneDesc *

pThis

)

Get the storage method for yTag values.

The 2nd dimension of a yScan plane may have data values associated with each index point. These values can be specified individually or by simply providing an interval between point and the value of the 0th index. Use this function to determine which method is used.

void PlaneDesc_setYTags	(	PlaneDesc *	pThis,
		const double *	pYTags
	)

Provide a new set of yTag values to a yScan plane.

Parameters

pThis	A pointer to a YScan plane
pYTags	a pointer to an array of doubles that must be at least as long as the number of items returned by PlaneDesc_getNItems() for this plane.

void PlaneDesc_getYTagSeries	(	const PlaneDesc *	pThis,
		double *	pInterval,
		double *	pMin,
		double *	pMax
	)

Get the Y axis coordinate series for a 2-D plane of data.

Parameters

[in]	pThis	A pointer to a YScan plane
[out]	pInterval	a pointer to a double which will be set to the interval between samples in a series, or DAS_FILL_VALUE if y-tags are specified individually.
[out]	pMin	a pointer to a double which will be set to the minimum value of the series, or DAS_FILL_VALUE if y-tags are are specified as a list. If NULL, minimum yTag value is not outpu.
[out]	pMax	a pointer to a double which will be set to the maximum value of the series, or DAS_FILL_VALUE if y-tags are are specified as a list. This is not an exclusive upper bound, but rather the actual value for the last yTag. If NULL, maximum yTag value is not output

void PlaneDesc_setYTagSeries	(	PlaneDesc *	pThis,
		double	rInterval,
		double	rMin,
		double	rMax
	)

Set a YScan to use series definition for yTags.

Note that this can change the return value from PlaneDesc_getYTagSpec() and trigger deallocation of internal yTag lists

Parameters

pThis	a pointer to a YScan
rInterval	the interval between yTag values
rMin	The initial yTag value or DAS_FILL_VALUE if rMax is supplied
rMax	The final yTag value or DAS_FILL_VALUE if rMin is supplied