#include "brttutil.h" BUGrid * bugrid_create (char *grid_type, long nxgrid, float *xgrid_coords, char *xgrid_type, char *xgrid_units, long nygrid, float *ygrid_coords, char *ygrid_type, char *ygrid_units, char *data_type, char *data_units, char *tag, char *handle) BUGrid * bugrid_get_grid (char *handle) long bugrid_register_grid (BUGrid *grid, char *handle) long bugrid_free (char *handle) void bugrid_free_bugrid (BUGrid *grid) long bugrid_free_tag (char *tag) BUGrid * bugrid_copy (char *in_handle, char *tag, char *handle) long bugrid_put(char *handle, double time, long nsamps, double dt, float *data) long bugrid_put_bugrid(BUGrid *grid, double time, long nsamps, double dt, float *data) long bugrid_eval (char *handle, long isamp, long nxys, float *x, float *y, char *interp_mode, char *extrap_mode, float **out, long *out_size) long bugrid_eval_bugrid (BUGrid *grid, long isamp, long nxys, float *x, float *y, char *interp_mode, char *extrap_mode, float **out, long *out_size) long bugrid_order_bugrid (BUGrid *grid) long bugrid_stuff (char *handle, char **packet, int *nbytes, int *packetsz) long bugrid_stuff_bugrid (BUGrid *grid, char **packet, int *nbytes, int *packetsz) long bugrid_unstuff (char *packet, int nbytes, BUGrid **grid) long bugrid_write_fd_bugrid (BUGrid *grid, int fd) long bugrid_read_fd (int fd, BUGrid **grid) long bugrid_coords_d2slow (long nds, float *xcoords, float *ycoords, char *method, char *model, char *phase_code, float sdepth, float gap_value) long bugrid_eval_d2slow (char *handle, long isamp, long nds, float *distances, float *azimuths, char *method, char *model, char *phase_code, float sdepth, char *interp_mode, char *extrap_mode, float **out, long *out_size) long bugrid_eval_d2slow_bugrid (BUGrid *grid, long isamp, long nds, float *distances, float *azimuths, char *method, char *model, char *phase_code, float sdepth, char *interp_mode, char *extrap_mode, float **out, long *out_size) long bugrid_maxmin(char *handle, long isamp, float *xmin, float *xmax, float *ymin, float *ymax, float *zmin, float *zmax) long bugrid_maxmin_bugrid(BUGrid *grid, long isamp, float *xmin, float *xmax, float *ymin, float *ymax, float *zmin, float *zmax)
These subroutines create and manipulate generic BRTT utility time-dependent data grid objects (aka bugrid objects). A bugrid object can be used to represent a rectilinear 2-dimensional grid of time-sampled data values; each object is characterized by a floating time-sampled single-valued function of two floating independent variables sampled across a rectilinear grid.
bugrid_create will create a bugrid object and return a pointer to the object, or NULL if there is an error. grid_type specifies a user defined string that describes the grid, or this can be ignored with NULL. The number of X-axis independent variable grid values is specified by nxgrid. The nxgrid floating X-axis independent variables are in the xgrid_coords array (note that the values of this array are copied into an allocated array within the bugrid object). A user defined X-axis type can be specified in xgrid_type and X-axis units can be specified in xgrid_units. The number of Y-axis independent variable grid values is specified by nygrid. The nygrid floating Y-axis independent variables are in the ygrid_coords array (note that the values of this array are copied into an allocated array within the bugrid object). A user defined Y-axis type can be specified in ygrid_type and Y-axis units can be specified in ygrid_units. A user defined data type for the time-sampled dependent data can be specified in data_type and data units can be specified in data_units. tag can be used to specify a character string tag associated with the new object. If the input value of handle is non-NULL, an object handle is returned in handle and this handle can be used for most subsequent calls to the new object.
bugrid_get_grid will return the bugrid object pointer associated with a grid handle, handle.
bugrid_register_grid will register and return in handle a previously created bugrid object pointer specified by grid.
bugrid_free will free the resources associated with the bugrid object referenced by handle.
bugrid_free_bugrid will free the resources associated with the bugrid object referenced by the object pointer grid.
bugrid_free_tag will free the resources associated with all of the bugrid objects whose tag is tag.
bugrid_put will put dependent variable data in data, with time of first sample time, nsamps number of samples, dt time sampling increment, into the bugrid object referenced by handle. Any prior data in the bugrid object is freed, a new data buffer is allocated and the data sample values are copied into the new buffer. The input data sample value array must be in Xgrid-Ygrid-time order.
bugrid_put_bugrid is the same as bugrid_put except that the bugrid object is specified by the grid structure pointer.
bugrid_eval will evaluate the grid surface referenced by handle at a specific time sample, isamp, for an array of nxys X-Y values, x and y, and put the nxys results into an output array, *out, returning -1 if there is an error or 0 otherwise. The grid surface is interpolated, when the input X-Y value is inside of the rectangular boundary of the grid, according to interp_mode which must be one of block, setting the output values equal to the closest grid node values, or bilinear, for a bilinear interpolation using the surrounding grid nodes. The grid surface is extrapolated, when the input X-Y value is outside of the rectangular boundary of the grid, according to extrap_mode which must be none, setting the output value to the data gap value. The *out output array is allocated and managed by bugrid_eval. If the input value of *out is NULL, then bugrid_eval will allocated the array, returning the allocated array in *output and setting *out_size to the number of floating array elements in *out, which should be the same as nxys (not to the actual size in bytes). If the input value of *out is not NULL, then it is assumed that *out was previously allocated and the input value of *out_size defines the currently allocated size of *out in numbers of floating array elements. If *out needs to be made larger, then bugrid_eval reallocates *out and sets *out_size accordingly.
bugrid_eval_bugrid is the same as bugrid_eval except that the bugrid object is specified by the grid structure pointer.
bugrid_order_bugrid causes the X and Y independent variable arrays, as well as the data array, to be ordered in increasing X and Y orders for the grid referenced by the grid structure pointer. This is called automatically by bugrid_put and bugrid_put_bugrid and is necessary for the various evaluation subroutines to work properly. Normally this does not need to be explicitly called by the user unless the grid data arrays are populated without using the bugrid subroutines.
bugrid_stuff will stuff a raw ORB packet buffer, specified by *packet, *nbytes and *packetsz (see stuffPkt(3) for a description of the packet buffer arguments), for the grid referenced by handle, returning -1 if there is an error or 0 otherwise.
bugrid_stuff_bugrid is the same as bugrid_stuff except that the bugrid object is specified by the grid structure pointer.
bugrid_unstuff will unstuff a raw ORB grid packet buffer, specified by packet and nbytes, into a new or existing bugrid object specified by the *grid structure pointer. If *grid is NULL on input, then the bugrid object is created and returned in *grid. If *grid is non-NULL on input, then the existing bugrid object is populated with the new data from the ORB packet and all of the previous contents are lost. Returns 0 or -1 if there is an error.
bugrid_write_fd_bugrid will write the grid specified by the grid structure pointer to (already opened) file descriptor fd.
bugrid_read_fd will read a grid from (already opened) file descriptor fd and unstuff it into a new or existing bugrid object specified by the *grid structure pointer, in the same manner as bugrid_unstuff.
bugrid_coords_d2slow is a utility routine that converts an array of nds distance-azimuth values, distances in xcoords in degrees and azimuths in ycoords in degrees, into equivalent Cartesian slowness values, returned back in the same xcoords and ycoords arrays as east-west slowness in sec/km and north-south slowness in sec/km, for a source at depth sdepth km and using the method and model to define the travel time engine (see tt(3)) and for the phase specified in phase_code. If there are more than one travel time branches for a particular input distance, then the slowness for the earliest branch is used. If there are no branches for a particular distance, then the output slowness values are filled in with the data gap value specified by gap_value. Returns 0 or -1 if there is an error.
bugrid_eval_d2slow will evaluate the grid surface referenced by handle at a specific time sample, isamp, for an array of nds distances and azimuths, specified in the distances array in degrees and the azimuths array in degrees, by first converting to Cartesian slowness values, using bugrid_coords_d2slow, and then by interpolating/extraploting, using bugrid_eval. The method, model, phase_code, sdepth, interp_mode, extrap_mode, out and out_size arguments are as in bugrid_coords_d2slow and bugrid_eval. This should only be used with grids whose independent variables are Cartesian east-west/north-south slowness values. Returns 0 or -1 if there is an error.
bugrid_eval_d2slow_bugrid is the same as bugrid_eval_d2slow except that the bugrid object is specified by the grid structure pointer.
bugrid_maxmin returns minimum and maximum data values in *xmin, *xmax, for the X-axis independent variable, ymin, ymax, for the Y-axis independent variable, and *zmin, *zmax, for the dependent variable, all for time sample isamp and for the grid referenced by handle. Returns 0 or -1 if there is an error.
bugrid_maxmin_bugrid is the same as bugrid_maxmin except that the bugrid object is specified by the grid structure pointer.