Spine-to-Object Allocation Software
User Manual

Table of Contents

• Table of Contents
• Introduction
• Overview
• Basic Operational Procedure
• GUI Layout
• GUI Operations & Features
• Command-line Utilities
• Input File Format
• GUI Options
• Software Installation
• Reporting a Bug
• Acronyms
• Copyright
• Version

Introduction

Overview

This software is executed offline, typically by the Astronomer requesting an FMOS-Echidna observation. It accepts as input a list of target objects with associated mean RA/Dec coordinates, priority, magnitude, etc and outputs an allocation file (.s2o) which specifies all of the necessary information required by Echidna to configure itself for the observation. Echidna's control software is able to read the allocation file and configure itself without any additional knowledge of the field.

Basic Operational Procedure

0. Install the software
   If the allocation software is not installed on your system, you will need to follow the installation instructions.
1. Prepare the source list
   To ensure that no significant flux losses occur as a result of fibre mis-placement, the selected targets should have less than 0.3" relative astrometric error across the FOV. Guide stars should ideally be taken from the same positional catalogue as the astronomical sources to eliminate systematic offset errors. Guide star magnitudes should be R≤16.5 magnitude and proper motion (particularly in the case of relatively bright guide stars or old positional data) should be checked. Ideally the magnitude range of the guide stars should be minimised to avoid saturation issues with Echidna's autoguiding camera.
2. Create the input file
   The input file format is described below. Be sure to include:
   • 'F' (Guide) targets
     The allocation software will generate a warning if less than 3 guide spines can be allocated.
   • 'K' (Coordinate calibration) targets
     Several of these targets will be imaged by the sky camera during field acquisition to optimise the initial telescope pointing. Each field should have at least 5 coordinate calibration targets (of magnitude R≤15) spread across the field, including one near the field centre.
   • 'P' (Program) targets
     The science objects you wish to acquire spectra for.
3. Get updated instrument specification file
   The Subaru FMOS-Echidna website should keep an updated version of the echidna.instr file. Hopefully, it is here. This file is used by the allocation software. By using the most-current version, the software will be aware of any broken/deallocated spines and can more optimally allocate fields.
4. Invoke the allocation GUI

   spineToObject.tcl &

   To prevent the allocation software from accessing the Subaru website to check for an updated spine list, set the $NO_CHECK_SPINE_LIST_UPDATE environment variable to "true". ie.
   

   export NO_CHECK_SPINE_LIST_UPDATE=true

5. Start the allocation wizard
   Allocation Operations ⇒ Allocation Wizard (or Ctrl-w)
   You should see a dialog similar to the one below (without the text on the right-hand side).
   
   
   
   Each of the 8 buttons initiates an operation that forms part of the basic allocation procedure. You should step through each operation (top-down) to make a valid allocation.
   • Magnitude filter
     Setup magnitude filtering of science & guide objects.
     
     
     
     Objects with an apparent magnitude value outside the specified magnitude range are disabled but still stored in the .s2o files. Disabled objects are never visible/accessible from the GUI & are never allocated by the allocate program.
     Note: this option can be performed anytime. ie. it will filter the objects of any loaded file.

   • Open file
     Select a .fld or .s2o file to load.
     
     
     
     Note: When a .fld file is opened, the allocation program will immediately convert it into an allocation (.s2o) file. The Command Output window should popup and indicate whether or not this conversion was successful. Errors are highlighted in red, warnings are highlighted in blue. If an error occurs you must edit the input file and reopen it to continue. The error messages are quite verbose and should aid in discovering the source of the problem.

   • Field header
     
     
     
     Set appropriate values for all fields in the Field Information window. Positioning the mouse over each field will raise a help popup with additional information about the field. Click Apply once you have finished. Further information about each field is here.
     Note: It is important to set these parameters before performing an allocation as they directly affect the allocation algorithm and constraints.

   • Position angle Find a good Position Angle
     This option will automatically calculate the optimal position angle. A good position angle should allow at least 3 guide objects to be allocated. Allocating less than 3 guide objects can lead to sub-optimal autoguiding performance.
     Alternatively, the position angle can be explicitly set/overridden using the POS ANGLE field in the Field Information window.

   • Allocation setup
     Specify some parameters used during the allocation operation.
     
     
     
     If the use grid option is selected, allocate will generate a sky target at the "home" position of each spine. Note that any sky (ie. 'S') objects in the input file will be used first (if possible) when allocating sky targets.

     Note: allocate will allocate as many sky-subtraction targets as possible using unallocated spines (unless the minimum is set to zero). If the minimum number of sky-subtraction targets cannot be achieved using unallocated spines, allocate will deallocate low priority science targets and use those spines.

     Note: for Beam-Switching and Cross-Beam-Switching fields, the minimum number of sky-subtraction targets should be set to zero.

   • Allocate
     Automatically allocate objects
     When this operation completes the field plate will be re-rendered to display the allocation state. You can generate statistics pertaining to the allocation by clicking the 'Calculate' button in the Field Information window.

     The allocation software will automatically disable:

     • science targets that are too close together - preferentially disabling the lower priority object
     • non-guide targets that are outside the instrument FOV
     • science targets that cannot be reached by any active spine
     • guide targets that are outside the specified guiding magnitude range
     • science targets that are outside the specified science magnitude range
     • any targets that have a priority of zero
   • Create DSS File
     Create a Digital Sky Survey file of sky targets being utilised so the user can ensure there is no contamination.

   • Save
     Save the output as a .s2o file. You can reload the saved .s2o file and edit it at any time in the future.

GUI Layout

The Echidna Fibre Positioner Window

The Echidna Fibre Positioner Window contains a number of sub-windows:

• Spine Details
  This subwindow shows details about the selected spine (if any). If the mouse cursor hovers above any of the field names, a help dialog will popup that explains the field.

• Object Details
  This subwindow shows details about the selected object (if any). If the mouse cursor hovers above any of the field names, a help dialog will popup that explains the field.
  If field values are truncated a "..." will appear at the end of the visible field value. Placing the mouse cursor over the value field will cause a dialog to popup with the full field value.

• Field Plate
  This window shows a representation of the Echidna field plate. Many operations can be performed on this subwindow - most of the operations are listed here.

• Object Selection

  
  A number of checkbuttons to toggle the display of items drawn on the field plate.

  • red - all items are displayed.
  • green - all allocated items are displayed.
  • orange - all unallocated items are displayed.

  Mouse-3 will unselect the checkbutton.

  Note that the colors may be changed with the Echidna::multiButtonColor* options in the ~/.fmosPrefs file.

• Field Position

  
  A Field Position panel to adjust the field centre.
  For the up/down/left/right buttons, the field centre is offset by the number of arcseconds specified in the Offset field.
  For the rotate-left/rotate-right buttons, the position angle of the field plate is rotated by the number of degrees specified in the Rotation field.

The Field Information Window

The Field Information window contains 3 sub-windows:

• Instrument Specification

  

  Details about the fibre-positioning instrument. (In this case Echidna.) Mostly only the last 4 fields will be useful to Astronomers - it will allow them to determine if there are broken (inactive) spines.

• Field Information

  Header information about the field being observed.

  See this section about the field header.

• Allocation Statistics

  

  Statistics about the current allocation.

  The first section summarises the allocation of science objects by priority. It shows a breakdown of all the science objects in the field by priority value & lists how many of those science objects (with the same priority value) are actually allocated.

  The second section summarises the allocation by object type. It shows a breakdown of all objects in the field by object type & lists the number of those objects that are allocated. The mean fibre throughput efficiency value is the mean throughput value for all of the allocated objects of that type. The throughput value for an allocated object relates to how much a spine tilts/defocuses to reach the object. It is a percentage unit.

  The third section summarises the allocation by spine type. It shows a breakdown of the allocation by spine type - science or guide.

  Note: the bar-chart will only appear if you have the BLT Tk toolkit installed on your system.

The Command Output Window

The Command Output window captures output from the allocate program. The allocate program is responsible for performing most of the complex operations initiated in the GUI. Errors are highlighted in red, warnings are highlighted in blue.

The Auto-popup on option determine when the command output window should be popped up:

Every Command	Every time the allocate program is invoked.
Error Detect	Only when an error is detected in the output.
Warning Detect	Only when a warning or error is detected in the output. (default)
Command Fail	Only when the allocate program exits with a non-zero return value.
Never	Only pops up the window when explicitly requested by the user.

The Menus

• File
  
  • Open (Ctrl-o)
    Open a new .fld or .s2o file. You will be prompted to save any existing open file.
  • Save (Ctrl-s)
    Save the current state to the current (open) .s2o file.
  • Save As
    Specify an explicit .s2o file to save the current state to.
  • Save Unallocated
    Save unallocated science objects & all guide/atmospheric/calibration stars to a .fld file.
  • Print (Ctrl-p)
    This option will dump the current view of the field plate into a color postscript file and invoke a user-specified print command. The print command is specified by the main::printCommand parameter. Unix/Linux users will find it useful to set this parameter to "ghostview" (or a similar program) to gain a print-preview feature. Alternatively, a command akin to "lpr -Pcolourtek" is also valid and will send the postscript file straight to the specified (or default) printer.
    Note that only the current view of the field plate is printed. It can be useful to print zoomed sections of the field plate. If you desire to print the entire field plate, set the zoom level to Normal (View ⇒ Zoom ⇒ Normal or Ctrl-0) before printing.
  • Quit (Ctrl-q)
    Quit the allocation software. You will be prompted to save any existing open file.
• View
  
  • Show Information
    • Show Fibre Numbers (Ctrl-f)
      Label each (visible) spine on the field plate.
    • Show Object Names (Ctrl-n)
      Label each (visible) object on the field plate.
    • Show number/name in balloon popup (Ctrl-b)
      Use a balloon popup to display the spine id or object name whenever the mouse cursor hovers over a spine or object on the field plate.
      
      
      
      Over a spine, the balloon will display 2 colon-separated fields: The first field is either AS (allocated spine) or US (unallocated spine). The second field is the spine number within the Echidna fibre positioner instrument.
      Over an object, the balloon will display 3 colon-separated fields: The first field is either AO (allocated object) or UO (unallocated object). The second field is the object name, and the third field is the object's apparent magnitude.
  • Filter
    Note: this is a tear-off menu.
    • Priority <n>
      These 9 menu options allow the user to toggle the display of objects of priority n.
    • All
      Show all objects of all priorities.
    • None
      Don't show any objects of any priority.
    • Apply To Objects
      By default, the filtering options specified here apply to the arrows drawn on the field plate denoting an allocation between a spine and an object. Selecting this object means that the drawing of the object on the field plate is also filtered.
  • Highlight
    This option is similar to the Filter option except that instead of hiding/unhiding objects it highlights/unhighlights them.
  • Unselect All (Ctrl-u)
    Do not select any spine or object. This also causes the Spine and Object Details window to be cleared.
  • Find Object
    Pops up a dialog asking for an object name to search for. If an object matching that name is found it is highlighted on the field plate. If no such object can be found the bell will sound.
  • Zoom
    Note: this is a tear-off menu.
    • Zoom In (Ctrl-=)
      Increase the zoom level on the field plate by √2.
    • Zoom Out (Ctrl--)
      Decrease the zoom level on the field plate by √2.
    • x <n> Zoom (Ctrl-<n>)
      Set the zoom level on the field plate to n.
  • Command Output Window (Ctrl-z)
    Pops up the Command Output window if it is not already visible.
• Options
  • Save Preferences
    Save user preferences to ~/.fmosPrefs file.
  • TkCon Debug Window
    For debugging purposes only. Please ignore.
• Allocation Operations
  
  • Allocate
    Each of the allocation routines deallocates all applicable spines before performing the allocation operation. ie. the existing allocation is not preserved in any way.
    • All Fibres
      Allocate as many spines to objects as possible.
    • Guide Fibres
      Allocate as many guide spines to guide objects as possible.
    • Science Fibres
      Allocate as many science spines to science objects as possible.
    • Sky Fibres
      Allocate atmospheric standard stars, calibration stars & sky target objects according to the quantity specified in the Setup allocation dialog.
    • Single Fibre
      Allocate the selected spine to the selected object.
      Note that if the selected spine and/or object are allocated to other objects/spines before this operation is performed, the existing allocations are removed (deallocated) before the new allocation is performed.
    • Options
      Pops up a dialog prompting for command-line arguments to pass to allocate upon every invocation.
  • Check Allocation
    This option performs a rigorous check of the integrity of the current allocation, ensuring that the internal state is consistent. eg. objects are only allocated to one spine, etc.
  • Deallocate
    • All Fibres
      Deallocate all spines.
    • Guide Fibres
      Deallocate all guide spines.
    • Science Fibres
      Deallocate all science spines.
    • Sky Fibres
      Deallocate all sky spines.
    • Single Fibre
      Deallocate the currently selected spine. If no spine is selected, the spine allocated to the currently selected object is used.
  • Calculate Optimal Position Angle
    This operation will attempt to find a position angle that maximises the number of guide objects that can be allocated. Note that any existing allocation will be deallocated. If the main::bAllocateGuideOnCalcPosAngle option is set and a position angle is successfully found an allocate guide objects operation will automatically be performed as well.
  • Allocation Wizard
    Dialog popup to step through basic allocation procedure.
• Help
  • Allocation User Manual
    Open a browser displaying this user manual.
  • About
    Info about this software.

GUI Operations & Features

Selecting objects

Whenever a spine item is selected, the target object to which it is allocated is also selected. If the selected spine is not allocated, the current object selection is cleared.

To only select an object:

1. Clear the current selection using View ⇒ Unselect All (or Ctrl-u).
2. Select the object.

Allocation operations

• Fundamentals

  The allocation software imposes a number of constraints on allocations:
  • Object type & spine type must match. (eg. guide objects cannot be allocated to science spines.)
  • Object must be within the patrol area of spine.
  • Spines may not "cross".

• Manually allocating a single spine to a target object

  1. Select the spine you wish to allocate.
  2. Select the object to which you wish to allocate it too.
  3. Operations ⇒ Allocate ⇒ Single Fibre (or Ctrl-a).

  Alternatively, Ctrl-Mouse-1 on an object will immediately allocate the object to the selected spine (if there is one).

• Allocating guide objects

  Operations ⇒ Allocate ⇒ Guide Spines (or Ctrl-g).

• Allocating science objects

  Operations ⇒ Allocate ⇒ Science Spines.

• Allocating sky objects

  Operations ⇒ Allocate ⇒ Sky Fibres.

• Allocating all objects

  Operations ⇒ Allocate ⇒ All Spines (or Ctrl-a).

• Allocating a spare/unused spine to a dummy sky target

  By default, unused/spare spines are positioned at their nominal home position & potentially used for sky-subtraction? Sometimes, there may be a contaminating object at or near a spine's home position. In this case, create a new dummy sky target & allocate it to the spine by:
  1. Selecting the spine
  2. Holding down the alt key & clicking with the left mouse button where you would like the new sky target to appear.

Deallocation operations

• Manually deallocating a single fibre from an object

  1. Select the spine you wish to deallocate.
  2. Operations ⇒ Deallocate ⇒ Single Spine (or Ctrl-d).

• Deallocating guide objects

  Operations ⇒ Deallocate ⇒ Guide Spines.

• Deallocating science objects

  Operations ⇒ Deallocate ⇒ Science Spines.

• Deallocating all objects

  Operations ⇒ Deallocate ⇒ All Spines.

Changing Field Header Information

Note: placing the mouse cursor over any field in a Field Header window will popup a simple balloon help message.

• Field Name/Label

  The name (or a description) of the field to be observed.

• Field Centre

  Mean RA/Dec coordinates of field centre. Must be in format: hh mm ss.ss ±dd mm ss.s

• Observation Date

  Expected observation date. Clicking the button will popup a date-chooser dialog:

  

  Click the arrow buttons at the top to change the selected month. Clicking on a day button will select the date.

• Number of Valid Nights

  The number of nights from Observation Date that field should be valid for.

• Hour Angle Range

  The number of hours each side of the local meridian this field should be valid for.

• Equinox

  Equinox used for object positions. Can be either [J]2000[.0] or [B]1950[.0].

• Position Angle

  Position angle of field plate in degrees. Must be between -180.0 and 180.0.

• Observation Wavelength

  Central wavelength to observe in, in nanometres.

• Observation Duration

  Estimated observation duration in seconds.

• Beam-Switch Offset

  This field should contain 2 numbers separated by a comma. For cross-beam-switch allocations, this represents the offset/direction of the beam-switch. It is the number of arcseconds, in the x & y direction respectively, that the field centre is offset by. Note that the use of the x/y convention allows the offset to remain independent of the position angle. For normal beam-switch allocations, set one of the numbers to zero & the other to the maximum allowable offset (in arcseconds) that you wish the field to be beam-switched by.

• Autoguiding modes

  The 3 autoguiding modes available for Echidna are:

  • Beam-Switching

    In this mode, the telescope is offset between consecutive integrations, moving from object to sky and back again. Beam switching is the most effective method available to carry out sky subtraction and will be of particular use when targeting faint objects. eg. high redshift galaxies. Given the brightness of sky emission lines at infrared wavelengths, this mode will likely be used often. However, there are costs associated with this method. The first is that, typically, half the time is spent observing sky instead of the astronomical sources (plus extra overheads associated with offsetting the telescope). The second is that the random errors associated with sky subtraction are a factor of ~√2 higher than with a mean sky method. This is because only a single sky spectrum is subtracted, rather than an average of many. However, this single sky spectrum is observed through the same fibre with the same pixels, keeping systematic errors to a minimum.

  • Cross-Beam-Switching

    This is a variant of the Beam-Switching method. In situations where half or less of the fibres are required for a particular set of targets, it is possible to remove the beam-switching overhead of having to spend half the time on sky by configuring fibres in pairs, such that while fibre A is on object O, fibre B is on sky, then offsetting the telescope, fibre A is on sky and fibre B is on object O. This observing mode is a factor of ~2 more efficient than simple beam-swithing. The penalty is the reduced number of observable astronomical sources and the autoguiding overhead of having to reacquire guide stars after each offset.

  • Point-&-Stare

    In this mode the telescope continuously points at the astronomical sources to be observed. This mode should only be used in exceptional circumstances in the infrared. This can be used in situations where sky-subtraction is not an overriding issue. ie. bright sources where the flux in the sky is less than or comparible to that in the object spectra. eg. bright stars towards the galactic centre. Also used if the astronomers are only interested in a narrow region of the spectrum which happens to fall between night sky emission lines. In this mode, sky subtraction would be carried out using a mean sky spectrum. To obtain effective sky subtraction in this mode, fibres will have to be throughput calibrated via the strength of the night sky lines, or short offset sky exposures derived from a few dedicated sky fibres.

Zooming & Panning the Field Plate

Panning around the field plate is accomplished using the scrollbars.

Allocation Statistics

Command-line Utilities

Two shell scripts are included with the allocation software. They are:

• extract.sh
  Remove all allocated objects from a .s2o file.

  Example usage:

  ./extract.sh field.s2o > unallocated.s2o

• ofc.sh
  This script attempts to find the optimal field centre by performing a raster around the current field centre & trying to allocate as many fibres as possible. By default, the raster is a 5x5 matrix with a separation of 3 arcseconds.

  Note: This script is NOT SUPPORTED.

  Usage:

  usage: ofc.sh [-options] <file>
  available options are:
  -h     help/usage information
  -m <n> step magnitude in arcseconds. [3"]
  -s <n> raster size. [5]
  -S <n> seed value. [0]
  -v     verbose output
  			

  Any arguments specified after -- are passed to 'allocate'. ie:

  ./ofc.sh -v -m3 -s7 -- --useskygrid --bsignorespect $e/echGUI/examples/example1.s2o 

  Typical output:

    354     355     355     353     355     
    355     354     355     353*    353     
    357     357     359     360     354     
    357*    357     359     356     354     
    357*    356     356     356     357
    Optimal FIELD CENTRE +00 57 06.65 -19 11 00.84
    This is an offset of 0,3 arcseconds from the current field centre.
  			

  The numbers denote how many spines are allocated at each point in the matrix. If a * follows the number it means that it is ignored as not enough guide stars (min: 3) were allocated.

  Specifying -v will show how many guide stars are allocated at each point in the matrix:

    ./ofc.sh -v -m 480 -s 3 -- $e/echGUI/examples/example1.s2o
    208:4   250:3   199:3   
    250:3   359:9   247:3   
    207:3   259:7   208:2*  
    			

Input File Format

Mandatory header fields

Optional header fields

Target Object Fields

Object Types

Example Input File

EFLD 1.0
# Comments can begin with * or #
# Generated on Tue Oct 28 10:18:25 2003
# Mandatory header fields: LABEL, UTDATE & CENTRE
LABEL A simulated random field.
UTDATE 2003 10 28.01
CENTRE 12 34 56.78 -12 34 56.7
EQUINOX J2000.0
AGMODE Beam-Switching
OBS_DURATION 3600
POS_ANGLE 0
WAVELENGTH 1800

RandomObject01 12 34 49.23 -12 35 04.4 P 1 15.8 1 Random Object 1
RandomObject02 12 34 50.03 -12 34 55.2 P 1 17.0 0 Random Object 2
RandomObject03 12 34 41.02 -12 34 54.5 P 3 17.9 0 PM-RA=-4.24618) (PM-DEC=1.91734) Random Object 3

GuideObject01  12 34 29.43 -12 35 13.4 F 1 16.3 * Random Guide Object 1
GuideObject02  12 34 36.17 -12 35 53.1 F 1 17.1 * Random Guide Object 2

SkyTarget01    12 34 46.87 -12 34 33.1 S 1 * 1 Sky target 1
SkyTarget02    12 34 26.77 -12 34 43.6 S 1 * 1 Sky target 2
		

GUI Options

Most of the common GUI preferences can be changed via various simple operations. (ie. picking colors using a simple color dialog) However, there are a number of less common options that can only be set in the preferences file. Options that are set in the preferences file take effect when the spineToObject.tcl script is restarted.

Care should be taken when editing the preferences file as the wrong syntax or an illegal value can result in undefined behaviour.

• Loading

  The spineToObject.tcl script searches for a ~/.fmosPrefs preferences file when it starts up. You can override this filename with the $FMOS_PREFS environment variable.

• Saving

  You can save the current preferences at any time using Options ⇒ Save Preferences.

• Preferences
  
  Several preferences can only be set by editing the ~/.fmosPrefs file. They are of the form:

  set $parameter {$value}

  These preferences are briefly described here.

  Parameter	Default Value	Description
  main::allocateCommand	./bin/$(uname -s)/allocate	The location of the allocate program to utilise.
  main::allocateArgs	--check -t	Command-line arguments to pass to the allocate program upon every invocation.
  main::browserCommand	htmlview	Browser to invoke to display on-line help. Could be any of: htmlview, mozilla, netscape, firefox, dillo, rxvt -e w3m, rxvt -e links, xterm -e lynx, /Applications/Safari.app/Contents/MacOS/Safari, etc.
  main::printCommand	ghostview	Unix/Linux users will find it useful to set this parameter to "ghostview" to gain a print-preview feature. Alternatively, a command akin to "lpr -Pcolourtek" is also valid and will send the postscript file directly to the specified (or default) printer. Could be any of: ghostview, /Applications/Preview.app/Contents/MacOS/Preview, gs, evince, etc.
  main::saveFLDCommand	./bin/$(uname -s)/s2o2fld	The location of the binary to convert .s2o to .fld files.
  main::allocHelpFile	./doc/echidnaUserManual.html	Location of on-line help file.
  main::tmpFilePrefix	/tmp/ech	Prefix to use for temporary files.
  main::bAllocateGuideOnCalcPosAngle	0	If this option is set and a position angle is successfully found during a Calculate Optimal Position Angle operation an allocate guide objects operation will automatically be performed as well.
  main::initialDir	.	The initial directory to search for files to open.
  main::instrFile	./config/echidna.instr	The instrument description file to use.
  main::balloonFont	helvetica 10	Font to use for balloon help popups. (Note: there is a separate FieldPlate::balloonFont option.)
  FieldInfo::bgColor	darkgray	The background color of the entry fields in the Field Information window.
  Echidna::maxFieldWidth	12	Default width of value fields in Spine/Object Details window.
  Echidna::fieldPlateScale	1.0	The initial size of the field plate (at normal zoom level). A scale of 1.0 means that the representation is very close to actual size.
  Echidna::multiButtonColor1	#b03060	Color of multibuttons when all items selected for display.
  Echidna::multiButtonColor2	green	Color of multibuttons when allocated items selected for display.
  Echidna::multiButtonColor3	orange	Color of multibuttons when unallocated items selected for display.
  Echidna::bMultibuttonhelp	1	Show ballon help over multibuttons.
  FieldPlate::font	fixed 10	Font to use for fibre numbers, object names, etc.
  FieldPlate::unallocatedSpineColor	green	Color of unallocated active science spines.
  FieldPlate::unallocatedGuideSpineColor	purple	Color of unallocated active guide spines.
  FieldPlate::allocatedSpineColor	blue	Color of allocated science spines.
  FieldPlate::inactiveSpineColor	darkGreen	Color of inactive spines.
  FieldPlate::allocatedObjectColor	orange	Color of allocated objects.
  FieldPlate::unallocatedObjectColor	red	Color of unallocated objects.
  FieldPlate::guideStarColor	skyblue2	Color of guide stars.
  FieldPlate::calibrationStarColor	cyan3	Color of calibration stars.
  FieldPlate::atmosphericStarColor	cornflowerblue	Color of atmospheric standard stars.
  FieldPlate::skyTargetColor	deepskyblue3	Color of sky targets.
  FieldPlate::hiliteSpineColor	yellow	Color of the circle to draw around highlighted spines.
  FieldPlate::hiliteObjectColor	magenta	Color of the circle to draw around highlighted objects.
  FieldPlate::posAngleColor	yellow	Color of the position angle indicator.
  FieldPlate::balloonFont	Helvetica -12	Font to use for balloon popups in the field plate window. (Note: there is a separate main::balloonFont option for other windows.)
  FieldPlate::balloonFG	black	Text color of balloon popups.
  FieldPlate::balloonBG	#C0C080	Background color of balloon popups.
  FieldPlate::faintMag	17	Faintest star that should have it's magnitude emphasised with a larger "dot".
  FieldPlate::brightMag	12	Brightest star that should have it's magnitude emphasised with a larger "dot". Note: to disable magnitude emphasis, set faintMag & brightMag to the same value.

Software Installation

System Requirements

This software should run on any Linux or Mac OS X ≥ 10.4 (PowerPC or Intel) operating system. You will need:

• a Tcl/Tk interpreter (ie. wish) installed that is capable of supporting Tk ≥ 8.1.1
• approximately 10Mb of free RAM to run the application.
• optional: a HTML browser, if you want to view the on-line help.
• optional: the BLT Tk toolkit, if you want a bar-chart in the Allocation Statistics window. (See here.)

Installation Procedure

0. Ensure a Tcl/Tk interpreter is installed on your system. You can download one here for Linux or Mac OS X.
1. Download the latest version of the FMOS-Echidna allocation software.
2. Extract the gzip file:

   gzip -dc echAlloc-YYYYMMDD.tar.gz | tar xvf -

3. Ensure the spineToObject.tcl script is in your $PATH. You will need to edit your ~/.cshrc or ~/.profile file depending on your shell.
4. Create/update the user preferences file, by starting up the application:

   spineToObject.tcl

   and selecting Options ⇒ Save Preferences.
5. Edit the preferences file (~/.fmosPrefs) to override options. First-time users will probably only want to check the settings for the main::browserCommand and main::printCommand options.

Reporting a Bug

Acronyms

Copyright

Version

$Id: echidnaUserManual.html,v 1.28 2010/09/26 04:16:37 ss Exp $