plane.h File Reference

Header for Plane Descriptor Objects. More...

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

Include dependency graph for plane.h:

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

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
DAS_API plane_type_t	das_plane_type_fromStr (const char *sType)
	Get the plane type for a das2 element name.
DAS_API const char *	das_plane_type_toStr (plane_type_t type)
	Get the das2 element name for a plane type.
DAS_API void	PlaneDesc_setNItems (PlaneDesc *pThis, size_t nItems)
	Set the number of items in a plane.
DAS_API void	PlaneDesc_setYTagUnits (PlaneDesc *pThis, das_units units)
	Set the YTag units for a YScan plane.
DAS_API void	PlaneDesc_setYTags (PlaneDesc *pThis, const double *pYTags)
	Provide a new set of yTag values to a yScan plane.
DAS_API 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.
DAS_API void	PlaneDesc_setYTagSeries (PlaneDesc *pThis, double rInterval, double rMin, double rMax)
	Set a YScan to use series definition for yTags.

Detailed Description

Header for Plane Descriptor Objects.

Enumeration Type Documentation

plane_type_t

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

das_plane_type_fromStr()

DAS_API plane_type_t das_plane_type_fromStr

(

const char *

sType

)

Get the plane type for a das2 element name.

Parameters

sType

An element name such as "x", "y", "yscan" or "z"

Returns

the matching plane_type_t, or Invalid after a das_error() call if sType is not one

das_plane_type_toStr()

DAS_API const char * das_plane_type_toStr

(

plane_type_t

type

)

Get the das2 element name for a plane type.

Parameters

type	A plane type

Returns

a constant string such as "x" or "yscan"

PlaneDesc_setNItems()

DAS_API 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.

PlaneDesc_setYTagUnits()

DAS_API 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

PlaneDesc_setYTags()

DAS_API 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.

PlaneDesc_getYTagSeries()

DAS_API 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 output.
[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

PlaneDesc_setYTagSeries()

DAS_API 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