VECTOR_BINS(3)

NAME

     VW_bins_init  VW_bins(binlist);   VW_bin_box   VW_bin_pixels
     VW_bin_pixel VW_bins_at_pixel VW_bin_at_pixel

SYNOPSIS

     #include <soi_VW_bins.h>

     typedef struct
     {
       List_Header list_header;
       Vector_Bin_List_Entry ** vector_bin_list_entry;
       short  * bindata;
     } VWBINS;

     VWBINS *VW_bins_init(char * vwbin_pathname);

     int VW_bins(VW_bins * binlist);

     float *VW_bin_box(VWBINS *binlist, int bin_number, int *dim_x,
          int *dim_y, int *ccd_x, int *ccd_y);

     int VW_bin_pixels(VWBINS * binlist, int bin_number);

     int VW_bin_pixel(VWBINS *binlist, int bin_number, int pixel_number,
          float *weight)

     int VW_bins_at_pixel(VWBINS *binlist, long int ccd_address);

     int VW_bin_at_pixel(VWBINS *binlist, int ccd_address,
          int relative_bin_number);

DESCRIPTION

     MDI  Vector  Weighted  Bins  description   functions.    The
     description of the MDI vector weighted bins, in terms of CCD
     pixels and weights is available in several forms.

     First,  an  initialization  function  must  be  called  that
     accesses  the  tabulated bin description and prepares it for
     future use.  The table is stored in a FITS file produced  as
     part  of the Level-0 processing steps for the 5-k structure-
     program data processing.  The table will be  used  for  many
     months  and  will  not  be stored in the same dataset as the
     actual data.  The filename of the table will be  constructed
     from the DSDS Dataset name for the binlist Dataset.  It will
     be of the form,
         {Basename.}binlist.fits where Basename may be  empty  if
     only one binlist is stored in the

     A sample call of the initialization function could be:


     typedef struct key {
       struct key     * next;
       char         * name;
       int          type;
       void         * val; } KEY;

     extern char *getkey_str (KEY *list, char *key);

     {ARG_DATA_IN, "in",  "", "", ""},

     VWBINS * binlist; binlist = * VW_bins_init(
            getkey_str(params, "vwbin_pathname"));


     if (!binlist) complainalot;

     Next, the number of bins can be ascertained by:  int  nbins;
     nbins = VW_bins(binlist);

     Then, the individual bins can be examined in  one  of  three
     ways.   One way is to request the location and dimensions of
     a bounding box that contains all the pixels that  contribute
     to  the bin.  The VW_bin_box function returns a pointer to a
     malloced array that should be  considered  a  2-D  array  of
     weights.   The  bounding box location on the 1024 x 1024 CCD
     image is returned along with the dimensions of the  box  via
     calling  parameters.   The pointer should be "freed" when no
     longer needed.

     A second way to access the bin  description  information  is
     first  to  request  the  number  of pixels in a bin with the
     VW_bin_pixels function and, then, for each pixel,  call  the
     VW_bin_pixel  function  to  get the location of the pixel on
     the CCD and the weight (via a calling parameter).  For  this
     pair  of  functions,  the CCD address is the lexicographical
     address of the pixel in the 1024  x  1024  CCD  array.   The
     standard   MDI   CCD   orientation  is  used  with  pixel  0
     corresponding to the SE  corner  of  the  image  with  pixel
     addresses  increasing  in rows then along the columns to the
     north.  This will be simply the address within the  standard
     CCD image array.

     Finally,  if  the  orthogonal  approach   is   needed,   the
     VW_bins_at_pixel, VW_bin_at_pixel combination can be used to
     find all  the  bins  that  use  data  from  a  given  pixel.
     VW_bins_at_pixel returns the number of bins that use a given
     CCD pixel.  VW_bin_at_pixel returns the bin  number  of  the
     nth  bin  using a given CCD pixel.  If there is no match, it
     returns -1.

FILES

     Level-0 Vector-Weighted Bin-Definition Datasets.  The datasets are named
     by the MDI Data-Product Code (DPC) that defines the bin list.
     The likely names are: prog:mdicalib,level:binlist,series:{dpc}[version#]

STATUS

     Preliminary testing has been done with a file that  deviates
     from  the  documented  specification of "vector-weighted bin
     list."  The writer does not know where to obtain  an  actual
     list  of  the  correct  type.  Putative samples do not agree
     with the documentation in mdi340023.

FILES

     ~/STAGING/include/soi_VW_bins.h

SEE ALSO

DIAGNOSTICS

BUGS

     I am not sure that i  know VW_bin_pixel is supposed  to  do;
     so,  I  made  something up for the time being.  There is one
     chance in four that the CCD index is correct.