• Antelope Release 5.9 Mac OS X 10.13.2 2019-05-01

 

NAME

chantracebuf_new, chantracebuf_free, chantracebuf_add, chantracebuf_filter - channel trace buffer subroutines

SYNOPSIS

#include "Pkt.h"
#include "brttpkt.h"
#include "wffil.h"

Chantracebuf *chantracebuf_new (double tstart, double tend,
				double latency, int apply_calib);

int chantracebuf_free (Chantracebuf *cp);

int chantracebuf_add (Chantracebuf *cp, PktChannel *pktchan);

int chantracebuf_filter (void **fil, int *type, Chantracebuf *icp,
		Chantracebuf **ocp, char *filspec, int filinit);

DESCRIPTION

These routines provide a utility for buffering individual channel waveform samples into contiguous traces using ORB packets as input. They are meant to be used in situations for which a channel waveform trace is needed given a known and finite time window.

chantracebuf_new creates a new channel trace buffer object and returns a pointer to the channel trace buffer structure. This pointer is used as a handle for subsequent operations. tstart and tend specify the epoch starting and end time window for the trace. latency is the maximum latency in seconds which is used to determine how long to wait for out of time order packets. If apply_calib is set to 0, then the calib value contained within the data packets will not be applied to the data sample values as they are read, otherwise the calib value is applied.

A channel trace buffer object is freed with chantracebuf_free.

New data packets are added to a channel trace buffer with chantracebuf_add which returns 0 if more packets are needed to fill the buffer or 1 when the buffer is ready to be used. The input to chantracebuf_add is a single packet channel structure, pktchan, as filled in by a call to unstuffpkt.

A channel trace buffer can be filtered with a call to chantracebuf_filter. A filter state hook, fil, is returned so that the filter can be reused. If the filter has not already been created, then *type should be set to WFFILFILTER_NEW upon entry. The filter can be freed with a call to free_hook(fil). The input channel trace buffer to be filtered is given by icp and the output filtered channel trace buffer by ocp. If ocp is set to 0 upon entry, then a new output channel trace buffer object will be created and returned. Otherwise, ocp, will be reused. ocp should be different from icp. The filter is specified with a normal character string specification in filspec. If filinit is non-zero, then the filter recursion past values will be initialized to remove the DC value at the beginning of each waveform segment.

The Chantracebuf structure is as follows:


typedef struct chantracebuf_ {
	double tstart;		/* requested start time */
	double tend;		/* requested end time */
	double latency;		/* maximum latency */
	double time;		/* actual start time of first sample */
	double dt;		/* sampling interval in seconds */
	int apply_calib;	/* apply calib? */
	int nsamp;		/* total number of samples */
	int ngood;		/* total number of good samples */
	float *data;		/* trace sample values */
} Chantracebuf;

The data array is initially pre-filled with "no data" values set to 2.e20. As new packet data samples are filled into the data array, these "no data" values are replaced with valid sample values. Gaps in the data will show as sample values with these large numbers. The number of gap samples can be computed as nsamp - ngood.

RETURN VALUES

chantracebuf_new returns a channel trace buffer handle (pointer to a Chantracebuf structure) or NULL if there is an error. If there is an error, then messages are left on the error register.

chantracebuf_add returns 0 if more data is needed to fill the buffer, 1 if the buffer is full and ready to use, or -1 if there is an error. If there is an error, then messages are left on the error register.

chantracebuf_filter returns 0 if everything is OK or -1 if there is an error. If there is an error, then messages are left on the error register.

LIBRARY

-lbrttpkt -lwffil -lbrttutil $(ORBLIBS)

SEE ALSO

unstuffPkt(3)

BUGS AND CAVEATS

Currently the sample rate is taken literally from the data packet headers. This works OK for smallish buffer lengths, but will break down with large buffers and slippery clocks.

AUTHOR

Danny Harvey
Printer icon