Guider Software

Installing The PC Guider Software

A good policy is to create an account for the PC Guider application. Copy the tar file that currently leaves at ftp.ctio.edu:/pub/rolo called tvguider.3.2.tar.gz to the home directory of the PC guider account. To uncompress and untar the file just write at the command line

% tar xvzf tvguider.3.2.tar.gz

You will need to add to your PATH variable the current path of the application: /home/pcguider/tvguider/bin. Copy the tvguirc file in the /home/pcguider/tvguider/bin directory to the home directory as .tvguirc. For example to install the tvguirc file in your home directory:

% cd /home/pcguider/tvguider/bin
% cp tvguirc ~/.tvguirc

You will need to install ximtool for Linux as well. Ximtool for Linux can be obtained from iraf ftp site as part of the X11 Iraf package. Version 3.2 of the PC Guider software support X11 Iraf version 1.2. You must be aware that the X Server on top of which you run ximtool must be set to 8 bits per pixel otherwise ximtool won't work. You can use xdpyinfo to check that out.
Another thing to install/create are the fifos for ximtool. To create those special files you have to be super user. For example to create the fifos "imt1i" and "imt1o":

% cd /dev
% su
% mkfifo imt1i
% mkfifo imt1o
% chmod a+w imt1i
% chmod a+w imt1o

You will also have to create the imtoolrc file to define the frame buffer configuration table and copy the file to /usr/local/lib ( or whereever you install ximtool). For example to define five frame buffers imtoolrc should look like:

Back to top

Getting things running

Login to the pcguider account and start X (if it's not running already). Then you will have to start ximtool, since it's going to be used to display the camera images. At that time you can specified some command line options that will minimize the color conflicts. Once ximtool is running you can type "tvguictio" at a shell prompt to start the PC guider. For example to start ximtool minimizing color conflicts and the tvguider:

% ximtool -basePixel 196 -cmapInitialize true -maxColors 64 &
% tvguictio

There is a script available that do the above for you, called "pcguider". For example to start the guider application type:

% pcguider

The scripts opens ximtool and then wait five seconds (too long?) to start the PC Guider application program.

Back to top

The PC Guider Control Program

The PC Guider program is actually two programs running together: The PC Guider Control Program and the PC Guider GUI. The PC Guider Control Program source code leaves at directory src/main/ of the PC Guider software directory tree. The structure of the PC Guider software directory tree is as follows:

• tvguider
  • bin
  • config
  • doc
    • applixware
  • lib
    • bitmaps
    • tvgui
  • man
    • mann
  • share
    • include
    • lib
      • blt2.3
      • tcl7.6
      • tk4.2
  • src
    • demos
      • am-dig
      • am-std
      • animate
      • cdl
      • comex+ximtool
      • cursor
      • serial
      • tv+ximtool
        • am-dig
        • am-std
    • gwish
    • main

The PC Guider Control Program is a multithreaded application that runs under a vanilla Red Hat Linux distribution. It continiously acquire images to calculate an offset error between the center of a guide box and the guide star inside of it, and then send the error vector to the TCS program to apply the correction. Please see the Hardware Setup section for specific information of the different working environments.

Once started the Guider Control Program accepts RPC connections from clients to receive commands and change its behavior. The main client of the control program is the guider GUI itself. The control program service the commands and send the answers to the command generator. Through this mechanism you can turn the guider on/off, change the size of the guiding box, switch from panoramic to roi mode, etc.

The PC Guider Control Program also opens a fifo connection to the ximtool display server program. The control program uses ximtool to display the images captured by the IC-PCI frame grabber.

Finally the control program opens an RPC (or serial if selected) connection to the TCS to send the offset errors.

Back to top

Command Interface

aoi [pan|gen|full|histogram|statistics|leaky|base|offset|size|xtrim|ytrim]

aoi pan - switch to panoramic mode. What this command actually does depends on what type of camera is in use (see configuration files later on this chapter). Under the ICCD camera setup (IC-CMP) the frame grabber will be configured to acquire the whole frame. Under the CCDTV camera setup (IC-DIG) the camera head will be set to work under panoramic mode (i.e read the whole CCD) and the frame grabber will be configured to acquire the number of pixels in a complete CCD readout.

aoi gen - switch to general roi mode. What this command actually does depends on what type of camera is in use (see configuration files later on this chapter). Under the ICCD camera setup (IC-CMP) the frame grabber will be configured to crop the incoming frame to the size and position of the subraster box (yellow box in the ximtool display). Under the CCDTV camera setup (IC-DIG) the camera head will be set to work under general roi mode (i.e. read a roi) and the frame grabber will be configured to acquire the number of pixels in the region of interest.

aoi full - switch to general roi full line submode. What this command actually does depends on what type of camera is in use (see configuration files later on this chapter). Under the ICCD camera setup (IC-CMP) the frame grabber will be configured to crop the incoming frame to the height and y position of the subraster box (yellow box in the ximtool display) keeping the width equal to the frame width. Under the CCDTV camera setup (IC-DIG) the camera head will be set to work under general roi full line submode and the frame grabber will be configured to acquire the number of pixels in the region of interest.

aoi histogram - return a string containing four values. The first value is the minimum pixel value of the frame or ROI. The second is the maximum pixel value of the frame or ROI. The third is the average pixel value in the frame or ROI. The last one is the standar deviation of the pixel values.

aoi statistics - return a string containing the min, max, mean and standard deviation within the the data section of the image, that is, the image without the trim section defined by xtrim and ytrim (supported under CCDTV camera mode).

aoi leaky factor- set the leaky memory constant. The leaky memory makes an average of the history of the image by making an average between the current frame and the previous one:

I'(k) = I(k) + C*I'(k-1)
               (C + 1)

aoi base x y - set the x and y coordinates of the subraster box.

aoi offset dx dy - offset the sibraster box coordinates by the specified amount of pixels.

aoi size sz - set the size of the subraster box.

aoi xtrim value- set the amount of columns to discard from the incoming image to value.

aoi ytrim value- set the amount of lines to discard from the incoming image to value.

camera [1|2]

camera 1 - selects the first camera scale and rotation parameters. These parameters are specified in the .conf file for each particular camera.

camera 1 - selects the second camera scale and rotation parameters. These parameters are specified in the .conf file for each particular camera.

comex [status|sync|reset|camera]

comex status

comex sync - synchronize the camera head parameters with the device driver parameters.

comex reset - initialize all the camera head parameters two their default values.

comex camera [abort|bin|dx|dy|e|g|i|mode|o|orig|resume]

comex camera abort - any integration is forced to done.

comex camera bin -

comex camera dx -

comex camera dy

comex camera e [on|off] - enable/disable internal erase to precede exposure of CCD to light.

comex camera g [2|4|6|8|10|15|20] - set the gain of the stage that precedes the A/D converter input.

comex camera i [0s-255s|0ms-1023ms] - set the time interval that the CCD integrates on light.

comex camera mode

comex camera o

comex camera orig

comex camera resume - no integration is forced to done

display [aoi|box|efactor|mark|olut|refer0|sigma]

display aoi [pos|show]

display aoi pos x y

display aoi show [0|1]

display box [pos|show]

display box pos x y

display box show [0|1]

display ref0 [pos|show]

display ref0 pos x y

display ref0 show [0|1]

display efactor factor

display mark

display olut [sigma|exp|off] - select the current output look up table. When off is selected, the ouput look up table does a linear reduction of the source image resolution to 8 bits (actually 0 - 200 due to ximtool constraints). When exp is selected, the ouput look up table does an exponential reduction of the source image to 8 bits making posible to stretch the dynamic range of the lower pixel values. When sigma is selected, display concentrates on information around the mean value in a range starting one standard deviation below the mean value and extending three standard deviation units above the mean value.

display refer0 [pos|show]

display refer0 pos x y
display refer0 show [0|1]

display sigma mean stdev

echo

erro [rate]

erro rate value

faults

guider [algorithm|box|calc|center|off|offset|on|ref]

guider algorithm [0|1|2]
guider box [pos|size]

guider box pos x y
guider box size side

guider calc
guider center
guider off
guider offset dx dy [box|ref]
guider on
guider ref [pos]

id - return the current version of the software.

infog

set [kq|ksh]

quit - exit the PC Guider Control Program.

Offset Error Algorithms

Not available yet!

Image Display

Before sending each image to ximtool, the control program draws , and applies if selected.

Ximtool doesn't support image display of color depths bigger than 8 bpp. In addition to that Ximtool reserves colors beyond level 200 for application specific colors (markers, dialog windows, etc.). That makes necessary to scale the image to fit those restrictions. Althought the server can be programmed to do the scaling just before displaying the image, the current version of the software takes care of that before sending the image to ximtool.

The image is scaled to fit the ximtool number of colors restriction, the box markers representing the guide box, subraster box and reference box are drawn and the dynamic range enhancements are applied if selected.

To stretch the dynamic range of the displayed images look up tables are created and then applied to the acquired images. Right now two enhancement algorithms are available. The first algorithm does an exponential reduction of the acquired image to 8 bits making posible to stretch the dynamic range of the lower pixel values. To accomplish this task the output lookup table is created using the following formula.

I' = A * (1 - exp (-I / (A * K))),                           0 < K < 1

The value of A depends on the current depth of the image. 12 bit images will use a value of 4096 and 8 bits images a value of 256. The value of K is a positive value between 0 and 1 that determines how much stretching will be applied to the image. The default value for K is 0.25. The display efactor command let the user change this value.

The second algorithm periodically update the output lookup table according to the mean and standard deviation values of the acquired image. The algorithm concentrates on information around the mean value in a range starting one standard deviation below the mean value and extending three standard deviation units above the mean value. All the data below the lower boundary is mapped to zero (black) and data above the upper boundary is mapped to 200 (white, under ximtool specification). The region between boundaries is devided in steps of (200/4sigma). The following table shows the calculated step values for various values of sigma:

Example 1: mean = 8, standard deviation = 1

Example 2: mean = 8, standard deviation = 3

Back to top

The PC Guider GUI

The PC Guider GUI source code leaves at directory lib/tvgui/ of the PC Guider software directory tree.

The PC guider GUI consist of one main window from which the most common operations (e.g. turning the guider on) are initiated, a history graphs window, and the display server window. Eventually some other auxiliary windows can be popped up as well.

The GUI allows to send commands and retrieve status from the PC Guider Control Program. Its menu bar gives the user menu options to set thing like the current state of the guider or changing to different operations modes. It also has several boxes that show up to date information about the value of some important variables and parameters; four graphic plots show the history of the x-y corrections as well as the number of counts and FWHM in the guiding box defined area. A status bar at the bottom of the window indicates what's the state of the guider program (on/calc/off) and the operation mode.

Back to top

Menu Bar

Options Menu

The Options menu let the user set the operation mode of the guider to one of Guider On, Guider Off or Calculate Only. Under Guider On operation mode the application will start calculating and sending corrections to the TCS. Under Calculate Only mode the error correction will be calculated but not sent to the TCS. Under Guider Off mode neither error correction calculations nor error correction transfers will be made. The currently selected mode is displayed at the status bar.

The Move Box To Object option let the user use the mouse to move the guide box to a given position over the image. When selected the mouse cursor will change and the ximtool window will automatically gain the focus for the user to put the cursor over a guide star. By typing C the guide box will be centered over the selected object.

This menu also let the user choose between active cameras. Each active camera define a different set of scale and rotations factors. This is useful if more than one camera is in use at the same time. To make the TCS aware of the right camera the user selects Camera 1 or Camera 2 to automatically change the scale and rotation factors in the TCS. The scale and rotation factors for each camera are specified in the .conf file by setting variables CAM1_HFACTOR, CAM1_DFACTOR, CAM1_RANGLE, CAM2_HFACTOR, CAM2_DFACTOR and CAM2_RANGLE.
The currently selected camera is displayed at the status bar.

Back to top

Mode Menu

The mode menu offers to the user a set of operation modes for the guider, such as the size of the acquired region, the current centroiding method or which box is the to be moved with the arrows keys. A description for each of the selections for this menu option follows.

When using Panoramic Mode the whole image will be acquired and transferred to memory. Those operations slow down the transfer rates and the speed of the calculations resulting in a slower rate of corrections to the TCS. Ideally this mode shouldn't be used for guiding but the General ROI Mode. When using General ROI Mode only a user defined region of pixels will be acquired and transferred to memory. This mode dramatically speed things up and allows a 10 Hz rate of corrections to the TCS. The Full Line Mode acquires a line the same width as the image and the same height of the General ROI Mode. The currently selected mode is displayed at the status bar. The associated line command is aoi [pan|gen|full].

The Mode Menu also let the user choose among three different offset error algorithms. The Intensity Centroid calculates the offset error as the center of mass of the area defined by the guide box. The Shectman Centroid determines the position of the star in the guide box and returns the offset error as the pixel distance between the box center and the guide star. Finally the Quadrant Centroid devides the guide box in four and calculates the offset error like the average of the four regions. The currently selected algorithm is displayed at the status bar. The associated line command is guider algorithm.

The user selectwhich box is the one to move with the arrow keys by choosing Guide Box, Subraster Box or Reference Box. It is possible to move the boxes with a key combination also. Pressing the arrows keys while holding the shift key pressed will move the subraster box. Pressing the arrows keys while holding the control key pressed will move the reference box instead. The currently selected box is displayed at the status bar.

Finally it is possible to move both the guide box and reference box at the same time by gearing them with the Gear Ref Box to Guide Box option.

View Menu

The View Menu let the user show or hide the subraster box and/or the auxiliary reference box.

Back to top

Window Menu

The Window Menu let the user pop up three auxiliary windows. The Console window let the user send command to the PC Guider Control Program. The History Graphs present the offset errors history plus the number of counts and the FWHM value inside the guide box.
The Camera Head Control window is the user interface to the CTIO CCDTV camera head. This tool let the user control parameters like camera gain and offset factors, integration time, etc. See the CCDTV camera documentation for more details about the camera.

The associated line commands are the comex camera commands family.

Help Menu

The Help Menu pop up an xterm window showing a Unix style man page with the commands available from the console.

Back to top

Status Panel

The status panel present various status variables and gives control over some of them.

The X and Y entries present the current guide box position over the image in pixel coordinates. The guide box is the white box marker in the ximtool display area. The guide box can be moved around using the arrow keys while selected as the active marker box (see Mode Menu).
The associated line command is guider offset.

The X Ref and Y Ref entries present the current reference box position over the image in pixel coordinates. The reference box is the green box marker in the ximtool display area. The reference box can be moved around using the arrow keys while selected as the active marker box (see Mode Menu) or by using the arrow keys while holding pressed the Control Key. The associated line command is display ref0 pos.

The Max Value entry present the maximum number of counts per pixel in the guide box area. The Background entry presents the average background value in the guide box area. The Total Count entry presents the total number of counts in the guide box area. The FWHM entry presents the full width high maximum value for the guide star inside the guide box. The background, total number of counts and fwhm values vary according to the selected algorithm (see Mode Menu).

The Leaky AV entry let the user set the leaky memory constant. The leaky memory integrates the acquired images by making an average between the current frame and the previous one according to the following formula. The associated line command is aoi leaky.

I'(k) = I(k) + C*I'(k-1)
               (C + 1)

The Guide Box Size and the AOI Box Size entries let the user change the size of the guide box and the subraster box. The size of the guide box can also be changed by using the + and - keys. The associated line commands are guider box size and aoi size.

Finally the Increment entry let the user change the size of the step to move the box markers over the image.

Back to top

Status Bar

The status bar presents information about currently selected modes. The information includes operation mode, selected camera, acquisition mode, offset error algorithm and active box marker.

Configuration Files

Two files exist to configure the PC Guider software: tvguirc and a guider camera specific .conf file. tvguirc defines a set of environment variables that the PC Guider Control Program and the PC Guider GUI Program share. The .conf files define guider camera specific parameters like the type of acquisition module to use with the camera, the frame format, etc.

tvguirc

This file is basically a C-Shell script that defines a set of environment variables. The following example is a typical tvguirc file. It defines the place where the tvguider program leaves, the host name of the TCS machine (ctiox0), the name of the machine in which the PC Guider Control Program runs (ctiox2), the ximtool communication channels and the .conf file to use for the current guider setup (mosaic).
------------------------------------------------------
#
#
# .tvguirc
#
# Environment variables for the PC Guider Program
#
#********* Check these out and set them as you wish ************

setenv GUIDEHOME /home/pcguider/tvguider2.2

setenv TCL_LIBRARY $GUIDEHOME/share/lib/tcl7.6
setenv TK_LIBRARY $GUIDEHOME/share/lib/tk4.2
setenv BLT_LIBRARY $GUIDEHOME/share/lib/blt2.3

# Host name of the TCS RPC server machine.
setenv TCP_NAME ctiox0

# Host name of the PC Guider RPC server machine.
setenv GUIDE_TCP_NAME ctiox2

# Ximtool fifos
setenv IMTDEV1 "fifo:/dev/imt1i:/dev/imt1o"
setenv IMTDEV2 "inet:5137"

# This tell the program where to find the binaries and configurations file.
setenv GUIDEBIN $GUIDEHOME/bin

# This is the configuration file directory
setenv CONF_DIR $GUIDEHOME/config

# This is the name of the configuration file
setenv CONF_FILE mosaic.conf

# make sure that guidebin is in the search path
set path = ( $GUIDEBIN $path )

# make sure we have the right man path
if ($?MANPATH) then
setenv MANPATH {$MANPATH}:$GUIDEHOME/man
else
setenv MANPATH {/usr/man}:$GUIDEHOME/man
endif
-------------------------------------------------

The file is expected to live in the home directory. User should modify the contents of this file to reflect its own environment.

Back to top

.conf Files

The .conf files define specfic parameters for each guider setup. There's one configuration file for each setup. Right now only two of these files are available: mosaic.conf and guider4m.conf. These files define parameters like waht type of acquisition module should be used with the camera, what's the board number of the acquisition module if more than one is installed, the type of CCD if using a CCD TV camera, the type of video format if using an analog camera, the frame format, the color depth, the camera scale, the transfer rate of the offset errors and the type of comm link to send the offset errors. Following is an example of the configuration file for the Mosaic Imager Environment.

--------------------------------------------------
##
## Mosaic Guider Camera configuration file v3.0
##

# The board number the driver chose (might be other than zero if more
# than one frame grabber is installed)
BOARD: 0

# The TV Guider software supports the IC-AMDG and IC-AMCMP
# frame grabbers.
# IC-AMCMP = 1
# IC-AMDG = 2
MODULE: 1

# This keyword gets used when the IC-AMDG is specified
# CCD02 = 2
# CCD39 = 39
# None = 0
CCD: 0

# If using IC-AMCMP NTSC 640x480 is the only supported video format.
# NTSC = 1
# PAL = 2
FORMAT: 1

# Image dimensions
# Be very carefull specifying the width and height values when
# using the IC-AMDG module. Use the following values:
# ICCD : 640x480 pixels
# CCD02: 400x290 pixels ---> 400x288
# CCD39: 100x82 pixels ---> 96x81
WIDTH: 640
HEIGHT: 480

# Version 2.0 now supports 8 and 12 bits images
DEPTH: 8

# This are the rotation and scale for the two different cameras
# that the software support
CAM1_HFACTOR: 0.326
CAM1_DFACTOR: -0.326
CAM1_RANGLE: 0.0

CAM2_HFACTOR: 0.326
CAM2_DFACTOR: -0.326
CAM2_RANGLE: 0.0

# This is the transfer rate for error corrections to the TCS
# in Hz
RATE: 0.5

# This is the type of communication link in use
# 0 RPC over the network
# 1 RS-232
COMM_LINK: 1

# This is the tty serial device in use. Gets used only when RS232
# is specified.
# /dev/ttyS0 port A
# /dev/ttyS1 port B
TTYS_PORT: /dev/ttyS0
---------------------------------------------------

New files can be created and copied to the tvguider/config/

directory. Then to actually use the file the .tvguirc file has to be modified to set the CONF_FILE variable to the new configuration file.

Back to top