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

 

NAME

buvector_create, buvector_free, buvector_free_tag, buvector_free_vector, buvector_get_vector, buvector_read, buvector_create_tsamp, buvector_create_response_fap, buvector_create_from_pf, buvector_resize, buvector_copy, buvector_append, buvector_puty, buvector_get_point, buvector_get_points, buvector_eval, buvector_maxmin, buvector_transform_edp - BRTT vector utility

SYNOPSIS


#include "brttutil.h"

BUVector *
buvector_create (int nx, int ny, char *tag, char *handle)

int
buvector_free (char *handle)

int
buvector_free_tag (char *tag)

void
buvector_free_vector (BUVector *vector)

BUVector *
buvector_get_vector (char *handle)

BUVector *
buvector_read(char *fname, char *tag, int line_off, int xpos,
                   int ny, int *ypos, int lpos, char *handle)

BUVector *
buvector_create_tsamp (int nsamp, double time, double samprate,
                   double *data, char *tag, char *handle)

BUVector *
buvector_create_response_fap (char *filename, char *tag,
                   char *handle, int *err)

BUVector *
buvector_create_from_pf (Pf *pf, char *name, char *tag,
                   char *handle, int *err)

int
buvector_resize (char *handle)

BUVector *
buvector_copy (char *in_handle, char *tag, char *handle)

int
buvector_append(char *handle, int index, double x,
                   double *y, char *label)

int
buvector_put(char *handle, int index, double x, double *y, char *label)

int
buvector_puty(char *handle, int index, double *y, char *label)

int
buvector_get_point(char *handle, int index, double *x, double *y,
                   char *label)

int
buvector_get_points (char *handle, int *npts, int *ny,
                 double **xpts, void *vypts, char ***labels)

int
buvector_eval(char *handle, double x, double *y)

int
buvector_maxmin(char *handle, int iy,
         double *xmin, double *xmax, double *ymin, double *ymax)

int
buvector_transform_edp (char *handle, double lonr, double latr)

These subroutines create and manipulate generic BRTT utility data vector objects (aka buvector objects). A buvector object is a set of floating dependent (Y) values, along with an optional character string label, as a function of a single independent (X) variable. Each point in the vector consists of one or more dependent (Y) values and an optional character string label for a single independent (X) value.

buvector_create will create an empty buvector object and return a pointer to the object, or NULL if there is an error. nx and ny can be specified as positive integers to preset the memory allocation. If nx is set to 0, then the number of X points is set dynamically as data is appended. If ny is set to 0, then it is assumed there is only one dependent Y value. Note that setting ny in this call sets a fixed number of Y dependent values for subsequent calls using this object. tag can be used to specify a character string tag associated with the new object. An object handle is returned in handle and this handle is used for most subsequent calls to the new object.

buvector_free will free the resources associated with the buvector object referenced by handle.

buvector_free_tag will free the resources associated with all of the buvector objects whose tag is tag.

buvector_free_vector will free the resources associated with the buvector object pointer vector.

buvector_get_vector will return the buvector object pointer referenced by handle.

buvector_read will create a buvector object by reading data values from an ASCII file with name fname and return a pointer to the object, or NULL if there is an error. tag can be used to specify a character string tag associated with the new object. An object handle is returned in handle and this handle is used for most subsequent calls to the new object. The input file must be in ASCII format with each line representing a single element (X value) in the vector. Lines starting with the # character or blank lines are ignored. The numerical values in each line must be white space delimited. The X independent data value is specified by the xpos'th numerical value (word) in each line (starting with 0). Each of the ny Y dependent values are specified by the ypos array values in each line (starting with 0). A character string label for each X independent data value can be specified with the lpos value in the same manner as the Y dependent values (-1 means no label). A line offset in the file can be specified by line_off which will cause line_off lines to be skipped at the beginning of the file before processing starts.

buvector_create_tsamp will create a buvector object from a time sampled data waveform with nsamp points, sample rate samprate samples per second, epoch time of first sample time, sample values in array data, and return a pointer to the object, or NULL if there is an error. tag can be used to specify a character string tag associated with the new object. An object handle is returned in handle and this handle is used for most subsequent calls to the new object. A time sampled vector object is one in which the X dependent variable is absolute epochal time, there is a single Y dependent variable which contains the sample values and there are no data lables.

buvector_create_response_fap will create a buvector object from an ASCII file with file name filename which is in either fap or fap2 external instrument response file format (see response(5)) and return a pointer to the object, or NULL if there is an error. tag can be used to specify a character string tag associated with the new object. An object handle is returned in handle and this handle is used for most subsequent calls to the new object. The frequency of the response is treated as the X independent data value and the amplitude, phase and optional error bounds are treated as the Y dependent values. Error returns, indicated by a NULL return value, are further specified in err, where a value of -1 means fatal memory allocation errors and +1 means errors parsing the input response file.

buvector_create_from_pf will create a buvector object from an Antelope parameter file object, pf, and return a pointer to the object, or NULL if there is an error. The parameter file object must contain a table with name name. Each line of the table is parse as an ASCII string. The first whitespace delimited field in each string is read as the X-value and following fields are read as Y-values. tag can be used to specify a character string tag associated with the new object. An object handle is returned in handle and this handle is used for most subsequent calls to the new object.

buvector_copy will create a buvector object by copying an already existing object referenced by in_handle and return a pointer to the object, or NULL if there is an error. tag can be used to specify a character string tag associated with the new object. An object handle is returned in handle and this handle is used for most subsequent calls to the new object.

buvector_resize will double the number of points (X values) in the memory allocation for the object referenced by handle.

buvector_append causes a new vector element to be appended after an existing element in a buvector object referenced by handle. The new vector element, as specified by x X-value, y Y-value array and optional label, is appended after the index'th vector element (starting with 0). If index is -1, then the new element is append at the end of the vector.

buvector_put causes a point in a buvector object referenced by handle to be replaced with the X-value, as specified by x, and the list of Y-values, as specified by the y array, for the index'th X point in the vector (starting with 0). The optional character string label value can also be replaced. This will error exit if the vector is a constant time sampled vector since the X(time) values for such a vector cannot ne specified individually.

buvector_puty causes the Y dependent values to be replaced in a buvector object referenced by handle. with the list of Y-values, as specified by the y array, for the index'th X point in the vector (starting with 0). The optional character string label value can also be replaced.

buvector_get_point returns a single X-value in x, the associated Y-values in the array y and the label in label for the index'th X point in the buvector object referenced by handle.

buvector_get_points returns all of the points in the buvector object referenced by handle. The number of points (X-values) is returned in npts. The number of Y-values is returned in ny if ny is set to -1 upon entry. Otherwise, ny upon entry specifies that only the ny'th Y-value should be returned (starting at 0). The X-values are returned in the array referenced by xpts which is always dynamically allocated and should be freed by the user when it is no longer needed (the entry xpts value is ignored and this memory allocation method is followed by all of the other returned arrays). The Y-values are returned in vypts according to the entry value of ny. If ny is -1 upon entry, indicating that all Y-values should be returned, then ny upon exit is set to the number of Y-values in the vector object, vypts is a reference to a dynamically allocated array of ny pointers for each of the Y-values in the vector object and each of these pointers is a reference to dynamically allocated and filled double arrays for each of the npts values in the vector object. If ny is set to a Y index value upon entry, then vypts is a reference to a dynamically allocated and filled double array for each of the npts values in the vector object for the single ny'th Y-value. If label is not NULL, then it is returned as a reference to a dynamically allocated array of strdup'ed labels for each of the npts values in the vector object.

buvector_eval causes the Y dependent values, corresponding to the single x X-value, to be returned in the y array for the buvector object referenced by handle. Linear interpolation is used to evaluate the Y values for an X value that is not exactly equal to one of the vector points.

buvector_maxmin returns minimum and maximum X and Y values in xmin, xmax, ymin, ymax for the buvector object referenced by handle. If iy is set to -1, then all of the Y-values are used to compute the maxima and minima, otherwise only the iy,th Y values are used to compute the maxima and minima.

buvector_transform_edp will transform a vector's X-Y coordinates, assumed to be X=longitude and a single Y-value with Y=latitude, to equal distance projection coordinates relative to longitude lonr and latitude latr for the buvector object referenced by handle. The transformation is done to the vector coordinates in place.

LIBRARY

-lbrttutil

AUTHOR

Danny Harvey
Printer icon