.help votpos Mar12 votools
.ih
NAME
votpos -- Extract the position columns from a VOTable
.ih
USAGE
votpos input
.ih
PARAMETERS
.ls input
The list of input VOTables.
.le
.ls output = STDOUT
The output filename.
.le
.ls ra_col = INDEF
RA column number (one-indexed).  If specified as other than INDEF, the named
column will be used instead of the column determined by the primary position
UCD (i.e. 'POS_EQ_RA_MAIN' or 'pos.eq.ra;meta.main').
.le
.ls dec_col = INDEF
Dec column number (one-indexed).  If specified as other than INDEF, the named
column will be used instead of the column determined by the primary position
UCD (i.e. 'POS_EQ_DEC_MAIN' or 'pos.eq.dec;meta.main').
.le
.ls rows = "-"
A range specification of rows to extract.
.le
.ls header = no
Print a output header?
.le
.ls number = no
Print the row number of each position?  If enabled, the output will consist
of the (index,ra,dec) values from the table, otherwise just the (ra,dec) will
be printed.
.le
.ls plot = no
Plot the result table on the standard graphics stream?  If enabled, a plot 
of the (ra,dec) positions will be drawn to the graphics terminal.
.le
.ls overplot = no
Over an existing display/plot?  If enabled, and existing plot will be 
appended using the same axis labels and scale.
.le
.ls color = 1
Plot marker color (in the range 1 to 9).  
.le
.ls title = ""
Title string to put on a plot.
.le
.ls verbose = yes
Print verbose output?
.le
.ls status = 0
Status of the service.  A non-zero value indicates no results were found.
.le

.ih
DESCRIPTION

The \fIVOTPOS\fR task is used to extract the primary position columns from
a VOTable.  These columns are defined by the UCD 'POS_EQ_RA_MAIN' and 
'POS_EQ_DEC_MAIN' for Cone Search services, or by 'pos.eq.ra;meta.main'
and 'pos.eq.dec;meta.main' for other VO services.  If the \fIra_col\fR
and \fIdec_col\fR parameters are set, the (one-indexed) column number in
the table will be used regardless of the UCD value.  Rows of the table
may be selected by specifying a range string to the \fIrows\fR parameter.

If the \fIheader\fR parameter is enabled, a table header will prepend the
list of extracted positions.  If the \fInumber\fR parameter is enabled, 
the row number will be printed as the first column of the output.

A plot of the positions may be displayed by setting the \fIplot\fR parameter.
Subsequent tables may be appended to the plot by specifying the
\fIoverplot\fR parameter.  When not overplotting, the \fIcolor\fR parameter
number 1 will always be used, otherwise each overplot will automatically
increment the marker color to make the points a unique color.  In all cases,
the marker shape will be a box meaning that when overplotted points are at 
the same position they will be drawn in the last color used and may be 
confused with earlier points at the same position.  A title string may be
put on the plot by specifying the \fItitle\fR parameter.


.ih
EXAMPLES
1. Query for catalog positions of NGC188 and extract the (numbered) position
columns to the file 'ngc188.pos'.

.nf
  votools> getcat gsc2.3 ngc188 size=0.1 output="ngc188.xml"
  votools> votpos ngc188.xml number+ out="ngc188.pos"
.fi

2. Use the VOTable is the first example but plot the positions on the
graphics terminal.  Overplot a second catalog query of the 2MASS Point
SOurce Catalog without saving the extracted positions.

.nf
  votools> votpos ngc188.xml plot+ out="ngc188.pos"
  votools> getcat 2mass-psc ngc188 size=0.1 output="2mass.xml"
  votools> votpos 2mass.xml plot+ overplot+ out=""
.fi

3. Query the GSC 2.3 catalog to overlay an image displayed of the NGC188 field.

.nf
  votools> dss ngc188 size=0.1
  votools> getcat gsc2.3 ngc188 size=0.1 output="ngc188.xml"
  votools> votpos ngc188.xml number+ out="ngc188.pos"
  votools> taboverlay ngc188 ngc188.pos
.fi

.ih
REVISIONS
.
.ih
SEE ALSO
getcat, getimg
.endhelp