Creative Commons License Copyright © Michael Richmond. This work is licensed under a Creative Commons License.

Content-type: text/html Manpage of INTRO


Section: Misc. Reference Manual Pages (local)
Updated: 8 Mar 2003
Index Return to Main Contents


intro - introduction to XVista commands  


XVista is a collection of programs that run on UNIX machines under X-windows for the display and reduction of astronomical images. It has evolved from PCVISTA (Treffers and Richmond, Pub. Astr. Soc. Pac. 101, pp. 725-730) which was in turn designed to be a somewhat compatible subset of the VISTA program developed at U.C. Santa Cruz and Berkeley for the reduction of CCD data.  


The description of the XVista commands can be found in files with the extension ".man". The contents of these files can be accessed online by using the man command. Hardcopy can be generated by the following command:

troff -man | lpr -t

where the desired command should be substituted for xxx.

Keywords in square brackets [ ] are optional. Keywords which are followed by an ``='' sign imply that a numerical (or symbol ) value must be entered. Caution: no spaces can be imbedded between the keyword, the equal sign and the value.

Commands can be divided into the following categories:

image arithmetic
add                 add images 
sub                 subtract images
mul                 multiply images
div                 divide images
addvec              add a 1-D vector to a 2-D image
subvec              subtract a 1-D vector from a 2-D image
mulvec              multiply a 2-D image by a 1-D vector
divvec              divide a 2-D image by a 1-D vector

data display
tv                  display grey scale image on screen
cursor              displays data values at cursor position 
marks               displays cross hairs on a image
pfits               prints out image data on the screen 

image marking
box                 defines a rectangular image subsection 
circle              defines a circular image subsection 

image statistics
abx                 calculates miscellaneous statistics 
axes                calculates centroid of images 
hist                computes histograms 
mn                  computes mean of images 
profile             makes a circular profile around a centroid 
sky                 computes sky level 

back                fits low-order polynomial to image and subtracts it
bin                 squashes an image 
clip                replaces pixels outside a specified intensity range 
flip                changes orientation of image 
imshift             shifts image in rows and columns 
makevec             creates a 1-D vector from a 2-D image
mash                generates spectra from image files into ASCII file 
median              creates median frame from several images 
ring                convolve images with a user-supplied kernal
rotate              rotates images      
rowcol              cuts rows or columns from data into an ASCII file 
sbig2fits           convert an SBIG "uncompressed" image to FITS format
smooth              convolves images with one of several standard functions
window              cuts down images 

header manipulation
buffers             displays the FITS header variables 
comment             enters in comments into the FITS header 

convert             convert bitmaps into FITS-format files 
impatch             replaces pixel values in an image 
implant             inserts an image into another image (montage) 
xlet                sets and inspect variables 
makeim              converts ascii to FITS-format files  
propinit            initializes X window properties
pstar               generates artificial star images 
xplot               plot program for columnar data

stars               finds stars in an image 
phot                performs aperture photometry 
mask                creates a file describing defects in the image


XVista uses variables to carry data such as sky brightness or pixel locations from one program to another. Variables may be substituted for any numerical input data. In addition any arithmetic combination of variables can be used.

The xlet command allows users to set the values of symbols and to inspect their values.

The allowed arithmetic operators are +,-,*,/ as well as the elementary trigonometric and exponential functions: sin, cos, tan, sqrt, exp, log, log10. Parentheses are allowed; however, no spaces may be included in any arithmetic statement. For example, in the axes command the value of sky could be set by "sky=4.5*sin(blotz)", where blotz was a preset variable. Note: the entire group was set in quotes to hide the * operator from the UNIX shell.

Some programs set the values of the XVista variables. For example:

mn_fname           the mean of the file "fname"
sky                the "sky" value 
axr, axc           the center row and columns found by AXES 
box#               the location of the boxes
circle#            the location of the circles
profile_boxrad     size of box used to calc radial profile 
                                    of displayed image
profile_fitrad     radius out to which to fit gaussian 
                                    to selected star
aperture_innersky  inner radius of sky annulus for photometry 
                                    of displayed image
aperture_outersky  outer radius of sky annulus for photometry 
                                   of displayed image
aperture_radius    outer radius of aperture for photometry 
                                   of displayed image
aperture_magzero   zero point of flux->magnitude conversion 

The XVista variables are stored in a file referred to hereafter as the ``symbol table''; it is a small ASCII text file. The name and path of this file must be set by the environment vaiable SYM_TABLE.  


The image data are stored in disk files in FITS format, a commonly used method of storing multi-dimensional data containing header information. A description of the standard is given in Wells, Greisen, and Harten, Astron. and Astrophys. Suppl. Ser, 44, 363 (1981).

The header contains information about the number of axes (always 2), the numbers of rows and columns (NAXIS2 and NAXIS1 respectively) and the word size (always 16 bits in this suite of programs). Note that the XVista FITS-reading routines understand ONLY 16-bit integer FITS files at this time. Although FITS header variables such as the time and date of the observation and the exposure time may be present, XVista makes little use of the header data, and except for window and bin, does not modify the header. The header can be inspected by using the buffers command.

The data files usually have the three letter extension '.fts'. This extension will often be added by XVista commands and need not be typed in explicitly. You can read files with different extensions by typing them explicitly.

Although internally most of the arithmetic is done as 32 bit integers, the data are written as as 16 bit integers. The data are treated as "signed" quantities ranging from +32767 to -32768. If two data files with pixel values in the neighborhood of 20000 are added together (without the NORM switch), the data will "overflow" into negative numbers.

The FITS reader is capable of reading data with BSCALE and BZERO values, however, many of the commands will only write data with BSCALE=1.0 and BZERO=0. and so truncation may occur.  


To compile XVista we recommend you copy the compressed archive file into a separate directory (Xvista). Then run the following UNIX commands:

uncompress XvistaN.a
ar x XvistaN.a

Where N is the version number of Xvista. If all goes well you should create all the executable programs. To invoke thes programs from other directories you will have to modify your PATH. In addition you should modify your .login file to set up the symbol table. For example:

rm $SYM_TABLE       # clears values from previous sessions

The tv program communicates to other program by X-window properties. For them to work properly you must place the propinit command into the routine which is called on the startup of X Windows. On a Sun running open windows we place it in the file ~/.openwin-init.

For the manual pages to work we go thru a rather arcane procedure of setting up a separate subdirectory 'man1' below the Xvista directory and placing all the .man files with their extension replaced with .1 (yes, the number 1) into it. And placing the following line into the .login file

setenv MANPATH ~/Xvista:/usr/man

The exact details of this command will vary from user to user, try to read the UNIX man page on man.

You will also have to modify the makefile to specify the exact path for the file ''.




This document was created by man2html, using the manual pages.
Time: 14:55:01 GMT, September 25, 2003

Creative Commons License Copyright © Michael Richmond. This work is licensed under a Creative Commons License.