WAX Helper Applications

Author:: Serge Monkewitz

	Contents
	bexp (Band File Explorer) bspgen (BSP File Generator) ASCII Scan Corner File Format bsptest (BSP File Tester) scantest (Scan File Tester) srcgen (Source Code Generator)

General Information

Each of the applications described below, when run with the command line option -help, will provide detailed information on usage and available command line options.

These executables are created during the wax installation procedure, and are all located in the bin subdirectory of the WAX installation directory.

This application, given a band file, allows a user to figure out the indexes of the bands covering a given declination range, or conversely, the declination range covered by the bands with a given range of indexes.

Usage

bexp -help

Returns detailed usage information.

bexp <band file> <dec min> <dec max>

Returns the range of bands that completely cover the given range of declinations.

bexp <band file> <band range>

Returns the declination range covered by the given range of bands.

Command Line Arguments

<band file>

The name of the file containing the sky subdivision to use (i.e. the mapping between declinations and band indexes).

<dec min>

The minimum declination (in degrees) to cover with a band. The value must be a floating point number in the range [-90.0, 90.0].

<dec max>

The maximum declination (in degrees) to cover with a band. The value must be a floating point number in the range [-90.0, 90.0].

<band range>

The band index[es] to return a range of declinations for.

Examples : 30
           30-33

Usage Examples

Example 1:

bexp /my_wax_install/wax_example/bands.txt -49.5 -35.33

Example 2:

bexp /my_wax_install/wax_example/bands.txt 477

Example 3:

bexp /my_wax_install/wax_example/bands.txt 450-482

bspgen (BSP File Generator)

This application, given an ASCII table containing scan corners for a set of scans, will generate BSP files that allow extremely fast scan coverage computations for positions and small regions on the sky to be performed.

Usage

bspgen -help

Returns detailed usage information.

bspgen <corner file> <BSP directory> [-v] [-p]

Generates scan coverage BSP files for the given ASCII scan corner file.

Command Line Arguments

<corner file>

The name of the ASCII scan corner file to generate scan coverage BSP files from.

<BSP directory>

The name of the directory in which to store the generated scan coverage BSP files.

[-v]

When specified, this flag causes bspgen to print out verbose comments while running.

[-p]

When specified, this flag causes bspgen to profile the execution time of various steps in the BSP generation process.

Usage Examples

Example 1:

bspgen /my_wax_install/bsp_example/scanex.4cvecs.nds /my_wax_install/bsp_example -v -p

This command generates the scan coverage BSP files used by the WAX plug in example.

ASCII Scan Corner File Format

Each line in an ASCII scan corner file shall contain exactly 231 single byte ASCII characters and shall be terminated with an ASCII new line character (0x0A).

Let $c_1,\;c_2,\;c_3,\;c_4 \; \in \Re^3$ be unit vectors corresponding to the four scan corners, where

is the eastern corner at the scan start
is the western corner at the scan start
is the eastern corner at the scan end
is the western corner at the scan end

Each vector has three components $x,\;y,\;z$ . The $x$ axis points north, the $z$ axis points to the vernal equinox, and the $y$ axis completes the right-handed coordinate system. Furthermore, let $v \in \Re^3$ be the unit vector corresponding to the scan center. The single-byte characters within a line are interpreted as follows :

bytes 0 ... 19
ignored by the parser

bytes 20 ... 31
$x$ component of $c_2 \wedge c_1$ (a floating point number)

byte 32
ASCII space character (0x20)

bytes 33 ... 44
$y$ component of $c_2 \wedge c_1$ (a floating point number)

byte 45
ASCII space character (0x20)

bytes 46 ... 58
$z$ component of $c_2 \wedge c_1$ (a floating point number)

byte 59
ASCII space character (0x20)

bytes 60 ... 71
$x$ component of $c_4 \wedge c_2$ (a floating point number)

byte 72
ASCII space character (0x20)

bytes 73 ... 84
$y$ component of $c_4 \wedge c_2$ (a floating point number)

byte 85
ASCII space character (0x20)

bytes 86 ... 98
$z$ component of $c_4 \wedge c_2$ (a floating point number)

byte 99
ASCII space character (0x20)

bytes 100 ... 111
$x$ component of $c_3 \wedge c_4$ (a floating point number)

byte 112
ASCII space character (0x20)

bytes 113 ... 124
$y$ component of $c_3 \wedge c_4$ (a floating point number)

byte 125
ASCII space character (0x20)

bytes 126 ... 138
$z$ component of $c_3 \wedge c_4$ (a floating point number)

byte 139
ASCII space character (0x20)

bytes 140 ... 151
$x$ component of $c_1 \wedge c_3$ (a floating point number)

byte 152
ASCII space character (0x20)

bytes 153 ... 164
$y$ component of $c_1 \wedge c_3$ (a floating point number)

byte 165
ASCII space character (0x20)

bytes 166 ... 178
$z$ component of $c_1 \wedge c_3$ (a floating point number)

byte 179
ASCII space character (0x20)

bytes 180 ... 191
$x$ component of $v$ (a floating point number)

byte 192
ASCII space character (0x20)

bytes 193 ... 204
$y$ component of $v$ (a floating point number)

byte 205
ASCII space character (0x20)

bytes 206 ... 218
$z$ component of $v$ (a floating point number)

byte 219
ASCII space character (0x20)

bytes 220 ... 227
maximum angular distance (in degrees) between a scan corner and the scan center (a floating point number)

byte 228
ASCII space character (0x20)

byte 229
The southward flag for the scan. A flag value of 'F' means the scan start is south of the scan end, giving $c_1,c_2,c_4,c_3$ as an anti-clockwise ordering of the scan corners. A value of 'T' indicates the scan start is north of the scan end, yielding the $c_1,c_3,c_4,c_2$ anti-clockwise ordering. Any other value is illegal.

byte 230
ASCII new line character (0x0A)

bsptest (BSP File Tester)

This application, given a set of BSP files, will find the number of scans covering a position or small region on the sky.

Note that the results of this application (for positions only) can be verified with the scantest application.

Usage

bsptest -help

Returns detailed usage information.

bsptest <ra> <dec> <radius> <BSP directory>

Returns the range of scans that completely or partially cover the given search area.

Command Line Arguments

<ra>

The right ascension of the search area center (in degrees). The value must be a floating point number between 0 and 360 (inclusive).

<dec>

The declination of the search area center (in degrees). The value must be a floating point number between -90 and 90 (inclusive).

<radius>

The radius (in arcseconds) of the search area to test for scan overlaps. The value must be a floating point number between 0 and 28 (inclusive). A radius of 0 arcseconds causes coverage computation to be performed for a single point (as opposed to an area).

<BSP directory>

The name of the directory containing the BSP files to use for the scan coverage computation.

Usage Examples

Example 1:

bsptest 0 -90 0 /my_wax_install/bsp_example

Evaluates scan coverage at the south pole.

Example 2:

bsptest 45 45 5 /my_wax_install/bsp_example

Evaluates scan coverage within 5" of the position with a right ascension and declination of 45 degrees.

scantest (Scan File Tester)

This application, given an ASCII scan corner file containing corner vectors for a set of scans, will find the number of scans covering a position on the sky.

Usage

scantest -help

Returns detailed usage information.

scantest <ra> <dec> <corner file>

Returns the number of scans that cover the given search position.

Command Line Arguments

<ra>

The right ascension of the search position (in degrees). The value must be a floating point number between 0 and 360 (inclusive).

<dec>

The declination of the search position (in degrees). The value must be a floating point number between -90 and 90 (inclusive).

<corner file>

The name of the ASCII scan corner file to use for the scan coverage computation.

Usage Examples

Example 1:

scantest 0 -90 /my_wax_install/bsp_example/scanex.4cvecs.nds

Evaluates scan coverage at the south pole.

Example 2:

scantest 45 45 /my_wax_install/bsp_example/scanex.4cvecs.nds

Evaluates scan coverage at the position with a right ascension and declination of 45 degrees.

srcgen (Source Code Generator)

This application, given ASCII tables containing desired retrieval, output, and grouped apparition columns, will generate source code, a makefile, and database table creation scripts for a WAX executable.

Without running this application, a WAX executable cannot be built. The Compiling and Running WAX and Writing WAX Plug-Ins help pages provide more information and a concrete example of how to use this application.

A description of all created files follows (actual file names will differ if the -name command line option is specified) :

```
Makefile
```
a GNU compliant make file for building a WAX executable. If this file already exists in the output directory, it is left untouched.
```
make.sh
```
a script which invokes the make utility on the generated Makefile. If this file already exists in the output directory, it is left untouched.
```
create.sql
```
a file containing a series of SQL statements which drop and then create the various output tables. Note that the WAX executable is able to drop and create these tables as well, making this script file useful mainly for examining the output table schemas. Note that the column name, order, and datatype specification should NEVER be edited - a WAX executable assumes the tables it is outputting groups and apparitions to are equivalent to the ones given in this file. If this file already exists in the output directory, it is overwritten.
```
create.sh
```
a simple shell script which runs the statements in create.sql using the Informix dbaccess utility. If this file already exists in the output directory, it is overwritten.
```
dbio.ec
```
contains optimized ESQL/C code for retrieving apparition information and for storing groups, singleton groups, group-apparition links, and grouped apparitions. If this file already exists in the output directory, it is overwritten.
```
info.h
```
contains C data structures corresponding to the desired apparition retrieval columns, the group output columns, and the grouped apparition columns. If this file already exists in the output directory, it is overwritten.
```
summary.c
```
contains an empty implementation of the C functions declared in the summary.h C header file. This file should be edited to perform group attribute computations (the results of which are to be stored in the specified output columns) and apparition attribute computations (stored in the specified grouped apparition columns). If this file already exists in the output directory, it is left untouched.

Usage

srcgen -help

Returns detailed usage information.

srcgen <app table> <database> <input cols> <output cols> <gapp cols> <dir> [options]

Generates source code, a makefile, and database table creation scripts for a WAX executable.

Command Line Arguments

<app table>

The fully qualified name of the Informix apparition table to retrieve columns from (database@server:table).

Example: "tmass@rmt_pebble:pt_src_01"

Since the '@' and ':' characters often have special significance for UNIX shells, the argument should be enclosed in quotes.

<database>

The fully qualified name of the Informix database to use for table creation (database@server).

Example: "ipac@rmt_gravel"

Since the '@' character often has special significance for UNIX shells, the argument should be enclosed in quotes.

<input cols>

The name of an ASCII table containing the names of the database columns to retrieve. See the Retrieval column file section for details on the file format required.

<output cols>

The name of an ASCII table containing the name and SQL datatype specification for each group information column to generate. A flag can optionally be included to control which of the group information columns should be present in the single apparition group table. See the Output column file section for details on the file format required.

<gapp cols>

The name of an ASCII table containing the name and SQL datatype specification for each grouped apparition information column to generate. See the Grouped apparition column file section for details on the file format required.

<dir>

The name of the directory to generate source code and other scripts and files in.

Optional Arguments

[-v]

When specified, this flag causes srcgen to print out verbose comments when running.

[-ext]

When specified, this flag causes srcgen to generate code and scripts for extended singleton and group-apparition link catalogs. These tables will contain all retrieval columns specified by the retrieval column file in addition to the standard columns.

[-noscan]

When specified, this flag causes srcgen to generate code and scripts which does not retrieve the database column containing apparition scan keys, and does not compute or store group scan counts.

[-name <name key>]

When specified, the given string is used as a suffix in the names of all generated files.

Example: -name wsdb

will generate files with the following names :

Makefile_wsdb
make_wsdb.sh
create_wsdb.sql
create_wsdb.sh
info_wsdb.h
dbio_wsdb.ec
summary_wsdb.c

[-extra <SQL>]

When specified, the given string is appended to the end of all generated SQL CREATE TABLE statements.

[-gcntr <column name>]

When specified, the name of the output column containing group counters is set to <column name>. Otherwise, the column is named gcntr (see Group Information Table, Group-apparition Link Table, Singleton Table).

[-napp <column name>]

When specified, the name of the output column containing apparition counts is set to <column name>. Otherwise, the column is named napp (see Group Information Table).

[-gtype <column name>]

When specified, the name of the output column containing group types is set to <column name>. Otherwise, the column is named gtype (see Group Information Table).

[-sdet <column name>]

When specified, the name of the output column containing scan counts is set to <column name>. Otherwise, the column is named sdet (see Group Information Table).

[-ngrp <column name>]

When specified, the name of the output column containing group counts is set to <column name>. Otherwise, the column is named ngrp (see Group-apparition Link Table).

[-cntr <column name>]

When specified, the name of the output column containing apparition counters is set to <column name>. Otherwise, the column is named cntr (see Group-apparition Link Table).

[-ra <column name>]

When specified, the name of the retrieval column containing J2000 right ascensions for apparitions is set to <column name>. Otherwise, the column is named ra (see Input Apparition Table).

[-dec <column name>]

When specified, the name of the retrieval column containing J2000 declinations for apparitions is set to <column name>. Otherwise, the column is named dec (see Input Apparition Table).

[-skey <column name>]

When specified, the name of the retrieval column containing apparition scan keys is set to <column name>. Otherwise, the column is named scan_key (see Input Apparition Table).

Usage Examples

Examine the file /my_wax_install/wax_example/gen.sh for an example of how srcgen is used. Also see Compiling and Running WAX and Writing WAX Plug-Ins.

Generated on Thu Oct 21 13:19:39 2004 for WAX Version 2.1 by

bytes 0 ... 19	ignored by the parser
bytes 20 ... 31	component of $c_2 \wedge c_1$ (a floating point number)
byte 32	ASCII space character (`0x20`)
bytes 33 ... 44	component of $c_2 \wedge c_1$ (a floating point number)
byte 45	ASCII space character (`0x20`)
bytes 46 ... 58	component of $c_2 \wedge c_1$ (a floating point number)
byte 59	ASCII space character (`0x20`)
bytes 60 ... 71	component of $c_4 \wedge c_2$ (a floating point number)
byte 72	ASCII space character (`0x20`)
bytes 73 ... 84	component of $c_4 \wedge c_2$ (a floating point number)
byte 85	ASCII space character (`0x20`)
bytes 86 ... 98	component of $c_4 \wedge c_2$ (a floating point number)
byte 99	ASCII space character (`0x20`)
bytes 100 ... 111	component of $c_3 \wedge c_4$ (a floating point number)
byte 112	ASCII space character (`0x20`)
bytes 113 ... 124	component of $c_3 \wedge c_4$ (a floating point number)
byte 125	ASCII space character (`0x20`)
bytes 126 ... 138	component of $c_3 \wedge c_4$ (a floating point number)
byte 139	ASCII space character (`0x20`)
bytes 140 ... 151	component of $c_1 \wedge c_3$ (a floating point number)
byte 152	ASCII space character (`0x20`)
bytes 153 ... 164	component of $c_1 \wedge c_3$ (a floating point number)
byte 165	ASCII space character (`0x20`)
bytes 166 ... 178	component of $c_1 \wedge c_3$ (a floating point number)
byte 179	ASCII space character (`0x20`)
bytes 180 ... 191	component of (a floating point number)
byte 192	ASCII space character (`0x20`)
bytes 193 ... 204	component of (a floating point number)
byte 205	ASCII space character (`0x20`)
bytes 206 ... 218	component of (a floating point number)
byte 219	ASCII space character (`0x20`)
bytes 220 ... 227	maximum angular distance (in degrees) between a scan corner and the scan center (a floating point number)
byte 228	ASCII space character (`0x20`)
byte 229	The southward flag for the scan. A flag value of `'F'` means the scan start is south of the scan end, giving as an anti-clockwise ordering of the scan corners. A value of `'T'` indicates the scan start is north of the scan end, yielding the anti-clockwise ordering. Any other value is illegal.
byte 230	ASCII new line character (`0x0A`)