SPIcam - User Information

Contact Webmaster for web page errors, corrections, ommisions, and/or additions.

This page last updated: March 7, 2007 - JMD
This page last checked: October 30, 2004 - JMD

Basic User's Guide: SPICAM- 2007

Contents

Basic information to know...

Using SPIcam (updated 3/07/2007)

• Starting SPIcam and Logging In
• Creating You SPIcam Directory
• Starting SPIcam command line software
• Setting Paths, Naming , Numbering for Image Files
  • Setting the Path - PATH command
  • Setting the Filename - FILE command
  • Setting the sequence numbering - NUM command
• Checking/setting filters in SPIcam - FILTER command
• Taking Bias exposures with SPIcam - BIAS command
• Setting exposure time in SPIcam - TIME command
• Taking Darks with SPIcam - DARK command
• Taking Flats
  • Taking Flat Fields & Automated Flat Field Script - FLAT command
  • Taking Sky Flats with SPIcam - EVEFLAT and MORNFLAT command
  • Taking Mirror cover flats with SPIcam
• Focusing SPIcam - DOFOCUS command
• Taking science images with SPIcam - OBJ command
• Quiting SPIcam - QUIT command
• Killing a Running SPIcam Process (Obs specs only)
• Commad Reference

Additional Information

Offset Directions for SPIcam

Quick Guide to using Spicam (Old & Outdated but useful detailed info on SPIcam usage and scripting)

The Semi-Official Guide to driftscanning with Spicam

Michael Strauss' guide to drift scanning with Spicam

Basic information to know...

Data can be accessed by these means means.

IMPORTANT!!! DO NOT start sub-directories or filenames with a leading zero.

SPIcam will overwrite your existing data if you write a file with an existing filename (or extension). It will NOT prompt you!!!

Using SPIcam - The Basics

SPIcam will overwrite your existing data if you write a file with an existing filename (or extension). It will NOT prompt you!!!

Starting SPIcam and Logging In

SSH into spicam@spicam-icc.apo.nmsu.edu (call APO/obs specs for password).

Creating You SPIcam Directory

IMPORTANT!!! DO NOT start sub-directories or filenames with a leading zero.

Create your images directory & subdirs (note: all images should have the root path /export/images/)

• If you have not taken any data (via TUI) for your program before, then you will need to create your program directory first.
  • To do this, at the prompt [spicam@spicam-icc ~]$ issue the command: mkdir /export/images/Qx<prog> example: mkdir /export/images/Q1UW01 for Quarter 1, University of Washington program 01 (assigned program).
  • If you have taken data already with TUI (using DIS, Echelle, or NICFPS) then this directory will have been created for you automatically already.
• Now create a subdir to place your SPIcam data in.
  • To do this, at the prompt [spicam@spicam-icc ~]$ issue the command: mkdir /export/images/Qx<prog>/spicam example: mkdir /export/images/Q1UW01/spicam
  • You can create further sub-dirs if you wish, but they must be created from the [spicam@spicam-icc ~]$ prompt to set the file write permissions correctly.
• Don't create sub-directories any other way or else the file permissions will not be set up correctly for SPIcam to write to!

Starting SPIcam command line software

Note that only one person at a time can run spicam. If it complains that the serial port is locked, this probably means someone else is running spicam. If you can't contact a person who is actually running spicam, tell the Obs spec to kill the running program.

When you start the program, there is first a large amount of initialization. Here is an example startup:

spicam 3.0 (CVS version $Name: v3_1_4 $)
failed to lock process in memory: reads may fail if machine is loaded: Cannot allocate memory
loading config file: /home/spicam/bin/spicam.cfg
filter 1 is SDSS u' (0.000000 offset)
filter 2 is SDSS g' (0.000000 offset)
filter 3 is SDSS r' (0.000000 offset)
filter 4 is SDSS i' (0.000000 offset)
filter 5 is SDSS z' (0.000000 offset)
filter 6 is open' (0.000000 offset)
starting at filter 1 (SDSS u')
initializing controller...
2007/03/07 13:07:04: spicam: COLD
2007/03/07 13:07:04: camera: COLD
SPIcam Camera Controller
Rev 8.0    May 12, 1998
OK

 Max
initializing DSP...
2007/03/07 13:07:04: spicam: CIN
2007/03/07 13:07:05: camera: 3.3
CIN
DSP ok   REV : 11
Camera ready
OK
initializing filter wheel...
2007/03/07 13:08:29: spicam: FWINIT
2007/03/07 13:08:40: camera: FWINIT OK
testing filter wheel...
2007/03/07 13:08:40: spicam: FW3!
2007/03/07 13:08:43: camera: FW3! OK
testing filter wheel...
2007/03/07 13:08:43: spicam: FW1!
2007/03/07 13:08:50: camera: FW1! OK
initializing shutter...
2007/03/07 13:08:50: spicam: SHINIT
2007/03/07 13:08:56: camera: SHINIT OK
2007/03/07 13:08:56: spicam: 0 22 FP!
2007/03/07 13:08:56: camera: 0 22 FP! OK
2007/03/07 13:08:56: spicam: 0 23 FP!
2007/03/07 13:08:56: camera: 0 23 FP! OK
2007/03/07 13:08:56: spicam: 0 4000 50 0 1024 0 2 2048 50 0 1024 0 0 0 2 2048 FF!
2007/03/07 13:08:59: camera: 0 4000 50 0 1024 0 2 2048 50 0 1024 0 0 0 2 2048 FF! OK
2007/03/07 13:08:59: spicam: FSF
2007/03/07 13:08:59: camera: FSF OK
Next file will be: /export/images/test0001.fits
Connecting to tcc004.apo.nmsu.edu...
Connected: TCC 3

Welcome to spicam - a CCD controller shell
 please send comments / bugs / suggestions to gene@astro.washington.edu

added cclear_on/cclear_off
setting the controller log to /home/spicam/logs/controller.log


* Experimental SPICAM ICC * Under Construction * Pardon Our Dust *


spicam:

Note the 'OK' listed after each test and the filters listed at the top. This is a normal startup.

Setting Paths, Naming , Numbering for Image Files

These are the necessary commands for setting things up with SPIcam.

path <filepath>         -- change data path
file <filename>         -- set the base filename
num  <num>              -- set the file extension number

PATH command

To define our image directory path (that was created earlier). At the spicam: prompt issue

Example:

spicam: path /export/images/Q1UW01/spicam

next filename: /export/images/Q1UW01/spicam/test0001.fits

FILE command

To set the filename (you will issue this same command anytime you wish to change the filename). At the spicam: prompt issue

Example:

spicam: file myfile. (Be sure to include the period at the end!!!)

next filename: /export/images/Q1UW01/spicam/myfile.0001.fits

NUM command

To set the file extension number (This will reset to 1 if you log out of SPIcam, ie. the obs specs need to take control for focusing. You will need to issue this command, after logging back in, if you want your number to continue from where you left off so note what your last file number was!!!). At the spicam: prompt issue

Example:

spicam: num 3 (sets the extension number to 3)

next filename: /export/images/Q1UW01/spicam/myfile.0003.fits

Checking/setting filters in SPIcam

These are the necessary commands for checking/setting fitlers in SPIcam.

filter help             -- help for filter command
filter ?                -- list installed filter set
filter                  -- list current filter 
filter <num>            -- set filter <num> into light path 

Example:

spicam: filter ?

1: SDSS u' (0 offset)
2: SDSS g' (0 offset)
3: SDSS r' (0 offset)
4: SDSS i' (0 offset)
5: SDSS z' (0 offset)
6: open' (0 offset)

Example:

spicam: filter 3

filter 3 (SDSS r')

Taking Bias exposures with SPIcam

These are the necessary commands for taking Bias frames in SPIcam.

bias <num>              -- take <num> bias exposures, no argument = 1

Example:

spicam: bias 3

begining exposure of 0.000000 sec
file is myfile.0003.fits
filter is 3 (SDSS r'), focus set to -150.000000
Clearing CCD (will take about 6 sec...)

Setting exposure time in SPIcam

These are the necessary commands for setting exposure time in SPIcam.

time <sec>              -- set exposure time to <sec> seconds

Example:

spicam: time 3

exp time set to 3.000000

Taking Darks with SPIcam

These are the necessary commands for naming a file in SPIcam.

dark <num>              -- take <num> dark exposures, no argument = 1

Example:

spicam: dark 3

begining exposure of 0.000000 sec
file is myfile.0003.fits
filter is 3 (SDSS r'), focus set to -150.000000
Clearing CCD (will take about 6 sec...)

Taking Flat Fields & Automated Flat Field Script (see Sky flats below)

These are the necessary commands for taking flats with SPIcam.

time <sec>              -- set exposure time to <sec> seconds

filter <num>            -- set filter <num> into light path 

file <filename> -- set the base filename

flat <num> -- take <num> flat exposures, no argument = 1

If you would like to take manual flat field frame(s) (non dithered). If you want dithered sky flats, see here.

Use TUI to slew to an empty area of sky, preferably directly opposite the sun and up high (~75degrees or so) to avoid the sky gradient.

Example:

spicam: time 3

exp time set to 3.000000

spicam: filter 3

filter 3 (SDSS r')

spicam: num 1 (sets the extension number to 1)

next filename: /export/images/Q1UW01/spicam/myfile.0001.fits

spicam: file rflat. (Be sure to include the period at the end!!!)

next filename: /export/images/Q1UW01/spicam/rflat.0001.fits

spicam: flat (take 1 sky flat exposure)

begining exposure of 0.000000 sec
file is rflat.0001.fits
filter is 3 (SDSS r'), focus set to -150.000000
Clearing CCD (will take about 6 sec...)

Taking Sky Flats with SPIcam

You can usually start flats about 20 minutes after sunset with SPIcam and the Sloan filters. Although less desirable, Mirror cover flats can be taken if Sky flats are not possible. See Taking Mirror cover flats with SPIcam .

First take a test exposure(s) (see here) to setup and to determine when you get a suitable background count for your flat (typically in the 30-40K range, SPIcam goes non-linear at around 45k and saturates at around 58k).

The script is smart enough to figure out the sky brightening, or darkening, automatically and then to adjust the exposure time accordingly. It will also automatically offset the telescope between each exposure by 10 arc seconds in X and Y to make it easier to subtract out any stars you get in your frames. All you need to do is feed it your last good exposure time, 30-40K bkgnd cts, from your test flat exposure and it will take care of the rest.

Once you have the exposure times worked out, issue the command:

spicam: eveflat <last exposure time> <number of exposures> - for evening flats

spicam: mornflat <last exposure time> <number of exposures> - for morning flats

Example:

spicam: mornflat 10 3 (last good exposure time 10 sec which gave 30-40k bkgnd cts, take 3 sucsessive exposures with dithering)

begining exposure of 0.000000 sec
file is rflat.0002.fits
filter is 3 (SDSS r'), focus set to -150.000000
Clearing CCD (will take about 6 sec...)

...

Taking Mirror cover flats with SPIcam

The installation of the new NA2 baffle during summer shutdown has considerably improved the flatness of calibration images taken off the mirror covers. Although twilight flats are still preferable and superflats taken from object images are best of all, mirror cover flats are now a desirable alternative when the other kinds are not possible. Mirror cover flats will also be slightly redder than the twilight sky or the night sky, and may therefore be more appropriate for photometry of red targets through broadband filters. Drawbacks: the lamps are quite faint in the bluest filters and will not reproduce night-sky fringing patterns in the reddest filters (i', z', I); only object superflats from the night sky can compensate for fringing.

Thanks to the new baffle, the illumination pattern of mirror cover flats now has very little dependence on rotator position, except in the outer corners of the image. Observers planning aperture photometry on small objects near the center of the field should not have to worry about rotator position for mirror cover flats. Observers doing surface photometry on larger objects or aperture photometry of multiple targets throughout the field may want to take flats at multiple rotator positions and combine them into a master flat. This does require coordination with the observing specialist, since we have to be very careful about having the mirror covers closed and motors active at the same time -- so be sure to communicate your plans clearly to the observing specialist.

Here are some suggested exposure times that should give 20K-30K counts. We do not have a current set of exposure suggestions for narrowband filters.

SDSS Filters

MSSO Filters

last updated 1/25/2007 - JMD

Focusing SPIcam

These are the necessary commands for focusing SPIcam.

time <sec>              -- set exposure time to <sec> seconds

filter <num>            -- set filter <num> into light path 

file <filename> -- set the base filename

dofocus <start focus> <inc value> <# exp> -- do a focus run

Tell the Observing Specialist that you are going to focus SPIcam, where the image is located and it's name. Also tell them the focus value that you set the telescope at. They will need this information to record in the night log.

If you are going to want to use the NA2 guider for guiding, the Observing Specialist will need to focus the guider AFTER you focus SPIcam but before you start your exposures.

(note: The Observing Specialist doesn't need to focus the guider after every focus run you do with the telescope, especially if the focus has not changed much (<35 microns).)

Example:

spicam: time 5

exp time set to 5.000000

spicam: filter 3

filter 3 (SDSS r')

spicam: num 1 (sets the extension number to 1)

next filename: /export/images/Q1UW01/spicam/myfile.0001.fits

spicam: file focus. (Be sure to include the period at the end!!!)

next filename: /export/images/Q1UW01/spicam/focus.0001.fits

spicam: dofocus -100 25 7 (start at focus value -100, increment between each exposure 25 steps, take 7 exposures total)

begining exposure of 0.000000 sec
file is rflat.0001.fits
filter is 3 (SDSS r'), focus set to -150.000000
Clearing CCD (will take about 6 sec...)

This will take a series of exposures on the same frame (with the last exposure/focus value where the star that has the gap) incrementing the focus step by the number specified between each frame.

Use IRAF to find the smallest FWHM and then set the telescope focus using TUI.

Taking science images with SPIcam

These are the necessary commands for taking science images with SPIcam.

time <sec>              -- set exposure time to <sec> seconds

filter <num>            -- set filter <num> into light path 

file <filename> -- set the base filename

obj <num> -- take <num> object exposures, no argument = 1

Asuming you have already focused SPIcam you can now use TUI to slew to your desired target. Once there start theNA2 guider guiding (see here). Now we are ready to take an image (in this example, 3 consecutive exposures, 60 sec each, with the SDSS r' filter).

Example:

spicam: time 60

exp time set to 60.000000

spicam: filter 3

filter 3 (SDSS r')

spicam: num 1 (sets the extension number to 1)

next filename: /export/images/Q1UW01/spicam/myfile.0001.fits

spicam: file myobject. (Be sure to include the period at the end!!!)

next filename: /export/images/Q1UW01/spicam/myobject.0001.fits

spicam: obj 3 (take 3 consecutive exposure)

begining exposure of 0.000000 sec
file is myobject.0001.fits
filter is 3 (SDSS r'), focus set to -150.000000
Clearing CCD (will take about 6 sec...)

Quiting SPIcam

These are the necessary commands for taking science images with SPIcam.

quit                -- exits SPIcam back to 

Example:

spicam: quit

[spicam@spicam-icc ~]$

Now type exit to exit the command line shell.

Killing a Running SPIcam Process (Obs specs only)

use the command ps ux to find the process and kill it (this is a safe procedure).

Command Reference

path <path> - Sets the file path (typically /export/images)

file(name) <filename> - Sets the filename. Be sure to end the name with a . (Period).

num(ber) <#> - Sets the extension number

filter </ /?/#>- Displays the current filter (no arguments), lists the currently installed filters (?). Sets the filter to #.

time <#> - Sets the exposure time in seconds

obj(ect) <#> - Take and object exposure, if a number is given after it will take that number of exposures.

flat <#> - Take and flat exposure, if a number is given after it will take that number of exposures.

bias <#> - Take and bias exposure, if a number is given after it will take that number of exposures.

dark <#> - Take and dark exposure, if a number is given after it will take that number of exposures.

eveflat/mornflat <last exp time> <#> - Evening/morning flat scripts. Input last exposure time that gave the desired number of counts, the script will automatically increment/decrement from this time, and the number of exposures you want to take (dithered between exposures).

exit - Exit spicam program.

Additional Information

Exposure Calculator (not maintained by APO)

Optical and UV Spectrophotometric Standard Stars

Offset Directions for SPIcam (Check these offsets!!!)

IRAF View

This is the orientation of the image as viewed in an image display via IRAF (e.g. ximtool, saoimage).

A +X, +Y instrument offset will move a star in the direction indicated by the arrows. Directions of East and North are given for 0 degrees object rotation. Note: The offset direction depends upon which interface the offset command was issued in!

TCC                          MC                    

Quick Guide to using Spicam (old & outdated but useful)

E. Magnier, A. Diercks, P. Doherty, J. Morgan, C. Stubbs

Introduction

Description

Basic Concepts

• Who, Where, What
• Getting Started
• What is Happening during Initialization
• Naming Files
• Observing Fundamentals

Defining the CCD Layout

Moving the Telescope, or parts

Header Information

Miscellaneous Commands

Shell Programing (scripting)

Advanced Commands

Alphabetical list of commands

About this document ...

Introduction

This document describes the operation of a CCD camera that we have constructed in order to develop prototype electronics for a wide field mosaic imager. The prototype system has sufficient performance to make it a useful instrument in its own right. For a detailed description of the camera system, see the SPIcam System Description.

The camera is not a facility instrument. We have tried to make the instrument as maintenance free as possible but users should be sensitive to the impact the system has on the site staff and facilities.

SPIcam is an acronym for Seaver Prototype Imaging camera, and we would like to acknowledge the generous support of the Seaver Institute and the David and Lucille Packard Foundation who made construction of this instrument possible.

Description

The CCD in SPIcam is a backside illuminated, SITe 2048x2049 pixel device with 24 pixels and a plate scale of 0.14 arc seconds per pixel giving a field of view of 4.78 arc minutes. Sensitivity and noise have been measured to be and . CTE was measured to be .999999 in both the serial and parallel directions. Measured zero points for the r' filters (for reference) () zero point is 26.25 mag for 1 electron / second.

Users control the camera through a program that runs on the acquisition computer, dryrot.apo.nmsu.edu. A simple command set supports bias frames, dark frames, and observations. The base image file name is selected by the user, and successive frames have a numerical suffix appended that is incremented after each frame. The data is stored in FITS format image files.

The camera can perform readout of a particular region of interest as well as arbitrary binning in both the serial and parallel directions.

Who, Where, What

Spicam is run from a Sun SPARCStation located in the computer room at APO. You must log into this machine to run the camera. The machine name is dryrot.apo.nmsu.edu and you must log in as spicam (Phone the Observing Specialist for the password if you don't know it).

In the home directory of the spicam account, there is a file filters.txt which describes the currently mounted filters. There are six slots in the filter wheels. When the instrument is set up, the Observing Specialist should have updated the filters.txt file, but it is a good idea to double check. From Spicam prompt you can do this by typing filter ? or The filters.txt file looks like this:

PLEASE DO NOT MODIFY THIS FILE!!! If it is not correct please notify the observing specialist.

The focus offsets are used to maintain focus when switching between filters with different relative focus positions. To use them effectively, it is best to choose one filter as the zero point and make your focus measurements in that filter. Unless you know there are significant difference in focus between your filters, it is safest just to leave these at zero.

Getting Started

Before starting up the software, it is best to ask the Observing Specialist if it is safe. To start the spicam software, just type ``spicam''. Notice that only one person at a time can run spicam. If it complains that the serial port is locked, this probably means someone else is running spicam, most likely one of the Observing Specialists. If you can't contact the person who is actually running spicam, Please notify the Observing Specialist and they can release the program from the person who has control. When you start the program, there is first a large amount of initialization. Here is an example startup:

What is Happening during Initialization

The first step is to connect to the TCC computer. This may take a few seconds. If this fails, spicam will continue to run, but it will complain frequently. The most likely reason for a failure to connect to the TCC is that the TCC is confused. If this happens, the Observing Specialists can restart the TCC program or they can reboot the machine if necessary. In the next steps, the software loads in default configuration information and the filter information.

Next, spicam initializes the camera controller, which also takes several seconds. If this fails, the camera is probably confused. Try a second time, but if it continues to fail, the Observing Specialist can reset the controller in hardware by pressing a button on the camera box.

Throughout the startup, and whenever you use spicam, there will be a variety of messages on the screen of the form:

spicam: (some text)
camera: (some text, frequently followed by 'OK').

This is the communication between the software running on the Sun (dryrot) and the hardware controller in the camera box. It is possible to turn off this camera log (see the command camlog below), but it is a reassuring sign that the system is working.

Now spicam tries to initialize and test the filter wheel. The test includes moving the filter wheel to position 1, then position 3, and again to position 1. The wheel only goes in 1 direction, so this process spins the wheel around once. Occasionally, the filter wheel has jammed if the screws which were too long were used to install the filters. In this case, the tests will fail and spicam will complain. You should ask the Observing Specialist to check on the filter wheel at this point. Once the filter wheel checks out, spicam tests the shutter as well. Finally, the software sends configuration information to the CCD hardware controller. The last line tells you the current name for the next file.

A few notes about the user interface. The interface has an interaction similar to tcsh. You can use the arrows to get to previous commands and edit the line. You can also use emacs-like commands such as ctrl-a to reach the beginning of the line and ctrl-e to reach the end. There is command and file completion: if you type part of a command (as the first thing on a line) and then type tab, it will fill in as much as possible, until the word is not unique. Typing tab twice at that point will list the possible endings. For any but the first word on a line, the same thing will happen for the files in the current directory. It is also possible to type just a fraction of a command, as long as it is unique. An ambiguous command will list the possible alternatives. For example:

Naming Files

path -- change data path file -- set the base filename number -- set the file counter number ext -- set the file extension

You can run the program from any directory. Images which are taken are stored on disk using a name of the form: PATH/FILENNNN.EXT. PATH defines the location of the resulting files, FILE is a root file name, NNNN is a sequence number which automatically increments after every read of the CCD, and EXT is an extension. These values are remembered from the last person who ran spicam, so you will not write over their files. However, it is best to choose some unique path and name when you start spicam, to avoid clutter. Use the commands path, file, number, and ext. If you type these commands without an argument, you will be told the format of the command as well as the current setting for each. For example:

current path: /export/images

Please ask the Observing Specialists where to store your files, all files MUST be stored in /export/images (on tycho).

You may store files in your own subdirectory in /export/images directory (i.e. /export/images/UW01/Jan14). You can do this in one of two ways (if you do not follow these instructions, then the file permissions may not be set up correctly). From the DRYROT prompt before starting SPIcam (you can type exit if you are at the SPIcam prompt to exit back to dryrot, create the directory and then type SPIcam to get back to the SPIcam command line. spicam: exit

Observing Fundamentals

There are several types of images you might want to take. In an OBJECT image, the CCD is cleared, the shutter is opened for a defined amount of time, the shutter is closed, and the CCD is read out. This is the typical exposure for a generic science image. In a DARK image, the CCD is cleared, there is a delay for a defined amount of time, during which the shutter is kept closed, then the CCD is read out. In a BIAS image, the CCD is cleared, and immediately read out with out opening the shutter (effectively, a 0 time DARK). In a LIGHT image, the shutter is opened for a defined amount of time and then closed, but there is no clear or read out of the CCD. To start any of these types of exposures, the command is the type of image: object, dark, bias, light, flat. A FLAT image is operationally just the same as an OBJECT image, but the IMAGETYP header keyword is set to FLAT instead of OBJECT. The CCD can be manually cleared with ``clear'' and manually read (e.g., after a set of ``light'' images) with ``read''.

There is a script which makes it easy to focus. ``Defects'' takes three arguments: ``start'', ``step'', and ``number''. It then takes a sequence of ``number'' exposures, starting at a focus value of ``start'', and increasing the focus by ``step'' between each exposure. Between each exposure, the charge on the CCD is shifted by 100 rows (200 on the last). The result is a focus plate with ``number'' images of the star, each displaced by 100 rows (200 on the last).

The exposure time is defined with the command time. It is possible to set exposure times as short as 0.068 seconds, but it is not recommended. There are two physical shutters, one for fast exposures and one for slow exposures. The fast shutter is used for exposures shorter than 1.5755 seconds, and the slow shutter is used otherwise. Currently the fast shutter does not produce a flat illumination pattern, and the real exposure time is not a well-calibrated function of the requested exposure time. It is highly recommended to avoid exposures shorter than 1.6 sec.

Defining the CCD Layout

Moving the Telescope, or parts

There are several spicam commands which allow the user to move parts of the telescope. All of these, except filter, talk through the TCC, and are potentially hazardous if other people are observing or working on the telescope. To avoid unintentionally moving the telescope, there is a priority level which can be set hi or lo. The command tcc lets the user interact with the TCC connection. tcc stat gets status information from the TCC, including UT, MJD, RA, DEC, and so forth. tcc hi and tcc lo change the priority level. tcc on and tcc off let the user start or stop the connection to the TCC. The filter command has several options. filter issued without any arguments reports the current filter (by number and name). filter N moves the filter to the Nth position (it is not possible to move the filter by name). filter ? lists the possible filter numbers and associated names. filter -r reloads the filters.txt file (in case you change it after starting spicam). filter -h lists the possible options. focus tells the current focus value, and focus NNNN sets the focus value. offset X Y moves the telescope XY degrees from the current location (X and Y in instrument coordinates). Adding the -a flag makes this an offset relative to the original boresight. rotate tells the current rotator angle, and rotate XXX moves the rotator to an angle of XXX degrees. It is currently not possible to use the spicam interface to move the telescope to a particular sky position. The user should either use remark or mcnode for this.

Header Information

There are two header keywords which can be changed by the user. The commands name and comment let the user set the header fields OBJECT and COMMENT. The command header shows the current FITS header (though when an image is taken, some values, such as UT or EXPTIME will be changed). During every CCD read, spicam calculates the mean and stdev for the entire image. This is reported during the read, but the command imstat prints the values.

Miscellaneous Commands

! -- system call
? -- list commands *
?? -- list variables *
exec -- system call
echo -- type this line *
exit -- exit program *
quit -- exit program *
help -- get help on a function *

Most of these are self-explanatory. The command ?? prints the system variables. The spicam shell is essentially an interpretive programming language, much like tcsh. You can set variables by saying

spicam: $fred = 10

You can print the value of a variable by using the command echo. Also, any expression within curly brackets {} is assumed to be an arithmetical expression and is evaluated before the line is executed. So for example, you could say:

echo {$fred*dcos(45)}

which would give the response 7.07107. There are math functions cos, sin, and tan, which operate on radian expressions, and also dcos, dsin, dtan, which operate on degree expressions. There are also the equivalent inverse functions: e.g., asin and dasin return radians and degrees, respectively.

Shell Programing

input -- read command lines from a file *
macro -- deal with the macros *
for -- loops *
if -- logical cases *
break -- escape from function *
wait -- wait until return is typed

There are several options for programming in spicam. First, a file which contains a series of commands can be executed by saying input (filename). It is also possible to define macros which will behave much like regular commands. dofocus is an example of such a command. A macro is defined by typing macro name or macro create name followed by the commands. Arguments to the macro are assigned to the variables $1 .. $N and the number of arguments is given by $0. Macros may be defined in input files, and indeed when spicam is started, it inputs the file  /.spicamrc which contains various default macros, such as dofocus. Simple loops and if statements can be performed, and are quite useful for complex macros. If statements must have the form:

if (A x B)
(commands)
else
(commands)
end

where A and B are variables, curly-brace expressions or constant values (including strings) and x is one of the operators =, >, <, and ! (not equal to). The else statement followed by additional commands is optional. For loops are also simplistic. The form is:

for var first last delta
(commands)
end

The value of $var will start at the value first and increment by delta after each loop. The loop will stop after $var is greater than stop. The value delta is optional, with 1 assumed.

Advanced Commands

cecho -- send raw command to camera controller
drift -- run a drift-scan
shade -- generate a shade image
unsign -- toggle the UNSIGN status
instrot -- (macro)
instxy -- (macro)
camlog -- define the camera logfile
output -- redirect the output

Alphabetical list of commands

! -- system call
? -- list commands *
?? -- list variables *
bias -- take BIAS image
break -- escape from function *
camlog -- define the camera logfile
cecho -- send raw command to camera controller
clear -- clear charge from CCD
comment -- set the image comment line
dark -- take DARK image
dofocus -- (macro)
drift -- run a drift-scan
echo -- type this line *
exec -- system call
exit -- exit program *
ext -- set the file extension
file -- set the base filename
filter -- set the filter wheel
flat -- take FLAT image
focus -- get / set focus value
for -- loops *
header -- show current image header
help -- get help on a function *
if -- logical cases *
imstat -- give statistics on the last image
input -- read command lines from a file *
instrot -- (macro)
instxy -- (macro)
light -- expose CCD, no clear, no read
macro -- deal with the macros *
name -- set object name (see also 'object')
number -- set the file counter number
object -- take OBJECT image
offset -- offset the telescope
output -- redirect the output
overscan -- change number of overscan pixels
path -- change data path
quit -- exit program *
read -- read out the CCD
rebin -- change CCD binning factors
rotate -- set rotation angle
shade -- generate a shade image
shift -- shift charge by N rows
status -- show current setup
tcc -- turn tcc on/off, set priority
time -- set the exposure time (see also 'object')
unsign -- toggle the UNSIGN status
wait -- wait until return is typed
window -- change CCD readout region

About this document ...

Quick Guide to using Spicam

This document was generated using the LaTeX2HTML translator Version 96.1-h (September 30, 1996) Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.

The command line arguments were:
latex2html guide.

The translation was initiated by Eugene Magnier on Mon Jun 23 15:46:50 PDT 1997

The Semi-Official Guide to driftscanning with Spicam

Drift scanning with Spicam has been simplified: Spicam now controls the telescope, making life much easier for the user. As usual when running spicam, you may point the telescope with Remark or Mcnode as you prefer. Spicam is controlled as usual from dryrot.apo.nmsu.edu. See the Spicam manual for more detailed information on running other aspects of Spicam.

In driftscan mode, the data stream is written out as square 1024x1024 frames (with the default 2x2 binning), with no overlap between them, and with an extra 100 columns of overscan (for stare-mode observations, there are also 100 rows of overscan). The last image will have the last complete 1024x1024 frame plus the remaining rows in the scan. Keep in mind that the first output frame is the ramp frame, and can look very strange, especially if the camera starts before the telescope is stable.

The basic drift command is: drift Nrows Vx Vy

During driftscanning, the telescope is moved along a Great Circle from the starting position in the direction of the vector Vx, Vy (unit vectors in the RA and DEC dirctions). When the command is issued, spicam tells the TCC to start the drift, and the TCC decides what angle it needs to move the rotator to align the CCD in the correct direction. As a result, there may be a significant pause at the beginning of a drift while the TCC moves the rotator. With the rotator at an angle of 0.0 degrees, the driftscan moves towards the north.

The Nrows option specifies the number of binned rows the CCD should read out during the drift. The maximum value for Nrows is 65536 (64 1024-row frames), or roughly 5 degrees long. The two velocities, Vx and Vy specify the drift rate in arcsec / sec. This maximum speed is currently limited between 2.58 and 6.45 arcsec/sec, and the software will warn you if you violate these limits.

The number of the frame is in the header, but (unless the user enters it explicitly on the comments or name line) not written to the header. So careful note-taking is necessary to make sure that you can reconstruct the position of any given frame. Also, the header does not record if any given exposure is stare mode or driftscan mode. It is not clear how one can refocus during a driftscan. Given the fact that the telescope focus occasionally glitches, this is a real worry.

There is no way to stop a driftscan early, without physically resetting the instrument.

If you are the first person doing driftscanning in a while, tell the mountain people ~1 day early to "rezero the rotator".

There are several flag options to drift, most of which can be ignored safetly. If you type the command drift without any arguments, you will get a short command description:

spicam: drift
USAGE: drift Nrow Vx Vy [-shade] [-b N] [-notcc] [-old] [-f fudge]
    (Vx and Vy are in arcsec per sec [2.58 - 6.45 valid range])
  [-b N] specify number of 64 row blocks per file (def: 16)
  [-notcc] runs the camera, but does not move the telescope
  [-old] uses Boresight offsets to drive the 'scope
    (the default uses the new 'ScanVelocity' command)
    (type 'help drift' for details on these modes)
spicam: 

The two important flags here are the [-old] and [-f fudge] options. The -old command tells the TCC to use the old boresight method to move the telescope. This method is less accurate, but has been more tested than the ScanVelocity method. If you find the ScanVelocity method fails at certain angles, try the -old flag instead. The [-f fudge] option lets you change the delay time between rows. This can be used to compensate for a mis-match between the motion of the telescope and the charge on the CCD. The value of fudge is a number of microseconds to add (or subtract, if negative) from the delay. For reference, the nominal delay is calculated as:

delay = (281300 / speed) - 43585 + fudge;

Michael Strauss' guide to drift scanning with Spicam

This is a quick writeup of my understanding, based on a half-night of observing, and lengthy discussions with Chris Stubbs, of how to take drift scans with SPICAM on the APO 3.5m. This is *not* an official anual, but I distribute it with the hope that it will be useful to others.

-Michael Strauss

Fire up REMARK on the Mac interface, and telnet dryrot.apo.nmsu.edu (logon as spicam, with the obselete visitor1 password)

On a separate window, telnet tycho.apo.nmsu.edu (logon as visitor1, using the current password).

We will control the slewing of the telescope and the rotation angle if the instrument from the Mac (REMARK), the operation of SPICAM from the first window, and the scanning of the telescope from the second.

From the dryrot window, invoke spicam by simply typing the line, spicam. Typing ? will give a list of all available commands. typing help command will give you more details.

Most of these commands are very straightforward, e.g., bias takes a bias, comment sets the comments line in the fits header, filter sets the filter, and so on. For many of the commands, following them by a question mark will tell you default values.

In drift scan mode, the data stream is written out as square 1024x1024 frames (with the default 2x2 binning), with no overlap between them, and with an extra 100 columns of overscan (for stare-mode observations, there are also 100 rows of overscan). Keep in mind that the first output frame is the ramp frame, and can look very strange, especially if the camera starts before the telescope is stable.

The software thinks of driftscanning as keeping the telescope boresite fixed, and moving the CCD along the focal plane. This is of course not what really happens, but it means that the position written to the header will be the same for all frames in a given scan (and it means that while you're scanning, REMARK will not update the position of the telescope). The number of the frame is in the header, but (unless the user enters it explicitly on the comments or name line) not written to the header. So careful note-taking is necessary to make sure that you can reconstruct the position of any given frame. Also, the header does not record if any given exposure is stare mode or drift-scan mode.

With object rotator angle set to zero, columns are aligned with N-S; with SAOimage, the frames have South up and E to the right. In general, if you want to scan at position angle (E from N) theta, set the object rotator angle to theta - 180. If you always drift-scan N-S, then N-S is always along the columns. If you drift-scan in any other direction, the direction of N-S will rotate on the chip. But there is no need to change the rotation angle as a function of time. These scans will of course not be along great circles.

So to driftscan, rotate to the appropriate angle, and move telescope to initial position. Launch telescope at fixed rate in instrument coordinates in y direction. Simultaneously, start reading out camera at the same rate.

It is not clear how one can refocus during a drift-scan. Given the fact that the telescope focus occasionally glitches, this is a real worry.

The driftscan command, from the spicam window, looks like:

drift 10240 0 6 -notcc

The 10240 tells it how many (binned) pixels long this exposure is. This example says that the exposure is 10 1024 frames long. The
maximum the software seems to accept is 64 1024 frames long, or roughly 5 degrees long.

The 0 is the scan rate in the x direction. This should always be zero.

The 6 is the scan rate, in arcsec/sec, in the y-direction. Sidereal rate is 15 arcsec/sec, so this is 0.4 sidereal. This number is currently limited between 2.58 and 6.45 arcsec/sec.

Before hitting return, however, you've got to get things ready with the telescope. In the tycho window, type (when you first log in). mcnode unsubscribe status These two lines suppress the verbosity of the mc unsubscribe monitor pri 1

Using remark, slew to your initial position, set your rotator angle appropriately, and type tcc offset inst/pabs 0,0,0,0.001666666667

This says to set the telescope off in the y-direction in instrument coordinates at the appropriate number of degrees/sec (not arcsec/sec!) Lots of decimal places are indeed appropriate; this must agree with the rate of the CCD to high accuracy... Note that because you are setting this in instrument coordinates, there is no further need to specify rotation angle here. Note also that these scans are *not* along great circles, which requires more integration between the camera and the tcc than exists now. But this is on the list of things to do!

The game is then to hit the tcc and drift commands as close to simultaneously as you can, and off you go! A counter will come up, which will tell you how many frames you have read out thus far. The path, ext and file commands will set what these files are called.

There is no way to stop a drift-scan early, without physically resetting the instrument.

When a drift-scan finishes, stop the telescope with the command: tcc offset inst/pabs 0,0,0,0 (or for short: tcc offset inst/pabs the 0's are the default values) This stops the scanning, and in fact returns you to your original position, tracking on the sky, which is very convenient, e.g., if you want to scan again in another filter.

When a drift-scan finishes, the counter of frame number skips one, so you will have a gap of one to confuse you slightly.

The bias is thought to be negligible (after subtracting overscan, of course); we'll have to test that.

If you are the first person doing drift scan in a while, tell the mountain people ~1 day early to "rezero the rotator".