}

3.5M Operations

2007-09-13

Contents

nicfpsExpose COMMAND [ARGS]

disExpose COMMAND [ARGS]

echelleExpose COMMAND [ARGS]

Start a sequence of exposures, or control an active sequence.

COMMAND is an exposure command or a control command. The control commands are:

pause
pause sequence. Also pause active exposure, if the exposure can be paused (1).
resume
resume sequence and any paused exposure, if one exists.
stop
immediately readout and save current exposure, if possible (1).
In any case, stop the sequence.
abort
immediately stop and DISCARD current exposure, if possible (1).
In any case, stop the sequence.
setPath PATH-OPTIONS
define or adjust the path for a given instrument and program. All these can be specified with an exposure command, but it can be more convenient or intuitive to specify them separately.
getPath
generate the exposure path keywords for the given instrument and the caller's program.
help
generate a synopsis of the expose commands.

Note 1: Most of the instruments pay no attention to new commands while reading out. So if a pause/stop/abort command is sent to the instrument after readout has started, the command will be run after the exposure is done, when it will be meaningless. I may figure out a sensible way of dealing with this; in the meanwhile the expose command returns a warning after the instrument command fails.

The exposure commands are:

bias [n=N] [CCD-OPTIONS] [PATH-OPTIONS]
dark time=S [n=N] [CCD-OPTIONS] [PATH-OPTIONS]
flat time=S [n=N] [CCD-OPTIONS] [PATH-OPTIONS]
object time=S [n=N] [CCD-OPTIONS] [PATH-OPTIONS]
Take N exposures of the given type. If given, adjust or set the file name, number, or path to the given PATH-OPTIONS. The difference between a flat and an object exposure is only that the FITS IMAGETYP value is set differently.

CCD options

Some instruments (presently only SPICam) allow specifying CCD-related options on as part of the exposure command. These options affect only the current exposure (they are not remembered) and if omitted, the current default value for that instrument is used.

bin=n
The bin factor
window=colBeg,rowBeg,colEnd,rowEnd
The window, in binned pixels. The bottom left pixel is 1,0 and both beginning and end row and column are included in the image. Note that you should always specify the bin factor if you specify the window to assure that the window values have the intended meaning.
overscan=col[,row]
The overscan, in unbinned pixels. Note: the argument may be just be pix instead of col[,row].

Path options

Each user is logged in with a given observing program (e.g. PU04), and can control several instruments. At the same time, all users from the same program are likely collaborating, so the system is set up to remember and maintain a single directory and filename pattern for each program+instrument. In other words, for each instrument that a given program uses, the system remembers and maintains a single path.

All parts of the path are 'sticky': once specified, any user from same program using the same instrument would later get the same values. Well, the sequence number would be incremented.

name=NAME
the directory and filename. This will be under an APO-specified root directory. Absolute and relative paths are treated the same. The APO root directory is currently /export/images/quarterPROGRAMNAME/UTYYMMDD on hub35m.apo.nmsu.edu, where PROGRAMNAME is the assigned schedule (and login) ID. If there is no trailing period, one is silently added.
e.g. name="target1." or name="night1/target1." Default="test."
seq=N
the exposure number to start the sequence with. Besides a number, can be 'nextByDir', which gives the next highest number across all files in the current path's directory, or 'nextByFile', which gives the next highest number across the files matching the current path. Default='nextByDir'
startNum=N
the exposure number to claim the sequence starts with. This option is purely cosmetic, and only affects the content of the instSeqState keyword.
totNum=N
the number of exposures to claim the sequence contains. This option is purely cosmetic, and only affects the content of the instSeqState keyword.
places=N
the number of digits to use for the sequence number. Default=4
suffix=TXT
how to finish the filename off. e.g. suffix='.fit'. Default='.fits' This does not work with DIS yet.

So if a PU04 user sent:
expose inst=echelle object time=10 n=2 name='flat.' seq=14 places=4
PU04 would get two files:
hub35m:/export/images/Q3PU04/UT040827/flat.0014.fit and hub35m:/export/images/Q3PU04/UT040827/flat.0015.fit
And if another PU04 user then sent:
expose inst=echelle bias name='tests/bias.'
that user would get:
hub35m:/export/images/Q3PU04/UT040827/tests/bias.0016.fit

Keywords

In order to readily disambiguate which instrument's exposures are being described, the keywords all start with the canonical instrument name. e.g. disNextPath, nicfpsFiles, echelleExpState Furthermore, the name of the sequence's program is always the first element of the keyword values.

instNextPath=cmdrID,dir,name,number,suffix
The filename parts used to build the next filename. The directory is only the part under the program root. The number is a string with the number of digits that places specifies. The four parts may not be enough to build the final filename(s).
instNewFiles=cmdrID,hostname,rootDir,programDir,userDir,filename1,...,filenameN
instNewFiles is generated when a new exposure has been started, and describes the files which are being created. There is usually just one filename; in cases when it can be more, and some file in the list is not generated, None will be used as a placeholder.
instFiles=cmdrID,hostname,rootDir,programDir,userDir,filename1,...,filenameN
If an exposure has finished, a list of the resulting filenames, and all the information required to get to them. There is usually just one filename; in cases when it can be more and some file in the list is not generated, an empty value will be used as a placeholder.
The pieces of the two keywords are:
cmdrID
The commander which started the exposure sequence.
hostname
The full hostname where the files can be found.
rootDir
The root directory on hostname under which all APO image files are currently saved.
programDir
The directory under rootDir where all of the program's files are saved.
userDir
The user-specified directory (under programDir)
filename1,[...,filenameN]
The filename or filenames from the instrument.

All of the directories are listed with trailing Unix '/'es, so the file path in unix or URL format is the concatenation of
rootDir, programDir, userDir and the appropriate filename.

For example:
disFiles="PU04.Ed","hub35m.apo.nmsu.edu","/export/images/","Q3PU04/UT040827","",None,"bias.0006r.fits"
corresponds to:
/export/images/Q3PU04/UT040827/bias.0006r.fits on hub35m.apo.nmsu.edu

instExpState=cmdrID,state,timeStamp,expectedLength,timeLeft
Report on the current exposure. The fields are:
cmdrID
The scheduling program and the login name of the user which started the exposure sequence.
state
What the exposure is doing. Can currently be idle, flushing, integrating, paused, reading, processing, done or aborted.
timeStamp
The time when the current state started.
expectedLength
A best guess as to how long the current state will take, from start to finish. For paused, how much time is left in the exposure. Some states are deemed to be short enough that expectedLength will always be set to 0.
timeLeft
A best guess as to the time remaining in the current state.
instSeqState=cmdrID,type,reqTime,currentCount,totalCount,state
Report on the current exposure sequence.
cmdrID
The scheduling program and the login name of the user which started the exposure sequence.
type
The exposure type.
reqTime
The exposure time requested.
currentCount
Which exposure in the sequence is active.
totalCount
How many exposures were requested for this sequence.
state
What the sequence is doing. Can currently be running, paused, aborted, stopped or done.
exposeTxt
Various reports of progress or trouble, intended to comfort or alarm the users.

Instrument Notes

DIS Notes

DIS has two cameras. The command and keyword changes are that:

  • The bias, dark, flat, and object commands take red and blue options. If one of them is specified, only that camera will generate an image. If both or neither is specified, then both cameras will.
  • The disFiles keyword specifies the blue filename followed by the red filename.

NIC-FPS Notes

NIC-FPS cannot bin, cannot take biases, and exposures cannot be paused.

Changes

2007-09-13
Added exposure options.
Reworked the html markup to make it standards-compliant.

2005-07-10
Removed Grim, added NICPFS.

2004-09-10
Added the 'offset' and 'total' path options.
Adjusted the 'seq' option description: 'nextByDir' is now the default.

2004-09-08
Added the 'nextByFile' and 'nextByDir' sequence number specifiers.

2004-08-27
Added instFiles.

2003-10-06
Normalized all keywords which specify user or program information to return the controlling commander ID (the program name plus the username) as their first element.

2003-09-26
Dropped userDir as part of a path specification. Any user-controlled directories in a path are specified in the name. Merged the program and usernames in the instSeqState and instExpState keys.