Software
User Manual for the OSIRIS Mask Designer v2.0
Table of Contents
1. Introduction
1. Definitions and Acronysms
3. Pre-conditions
3.1 System Software
3.2 System Environment Variables
4. Mask Designer Execution
4.1 General
4.2 Set environment variables for OSIRIS Mask Designer
4.3 Starting the tool
4.4 Modes of Operation
4.4.1 List of Target Values
4.4.1.1 List of Objects in Equatorial Co-ordinates
4.4.1.2 List of Objects in Image Co-ordinates
4.4.2 Slits on an Image
4.5 Mask types
4.6 Common Features
4.6.1 Observation Configuration Window
4.6.2 Process Mask
4.6.3 Processed Mask Window
4.6.3.1 Print
4.6.3.2 Save
4.6.4 Spectra Check Enabled
4.7 Configuration
4.7.1 Mask Designer Configuration
4.8 Slit type window
4.8.1 Setting the Default slit
4.8.1.1 Curve slit
4.8.1.2 Circle Slit
4.8.1.3 Rectangle Slit
4.8.2 Changing an existing slit
4.9 Deleting slits
4.10 Saving and loading masks in progress
4.10.1 Object Definition File (ODF)
4.10.2 Mask Definition File (MDF)
4.10.3 Save All
4.10.4 Open ODF
ANNEX A Object Definition File Keywords
ANNEX B Example of input target list
ANNEX C Observation configuration parameters
ANNEX D CCD to Mask polynomial description
ANNEX E XML configuration file parameters
List of tables and figures
Figure 1 Opening an image file
Figure 2: Slits drawn on image 9
Figure 3 Mask Designer Menu 10
Figure 4 Observation Configuration Window 11
Figure 5 Processed Mask Window 13
Figure 6 Slit Type Window 17
Figure 7 Last chance to abort deleting all slits 20
Table
1: Table of configurable parameters for the OSIRIS Mask Designer application
16
Table 2: List of parameters for a Curved Slit 18
Table 3: List of parameters for a Circular Slit
18
Table 4: List o parameters for a Rectangular Slit
19
1. Introduction
This is the Software User Manual (SUM) intended for the OSIRIS Mask Designer, a utility to define the exact positions and shapes of slits in a focal plane mask in order to perform multi-object spectroscopy (MOS) with the instrument OSIRIS on the GRANTECAN telescope. The Software User Manual has been derived from the Mask Designer use-cases provided in as well as the Design Document in in the frame of the OSIRIS project. This document provides a set of guidelines for the usage of the OSIRIS Mask Designer.
This document contains the following sections:
* Hardware and software requirements for the correct installation and
usage of the Mask Designer
* A description of each operation mode and usage guidelines.
Definitions and Acronyms
| Mask Designer menu | The extra menu added to the JSkyCat application that allows access to the functionality of the Mask Designer. |
| Nod&Shuffle | OSIRIS observing mode in which MOS techniques are combined with telescope nodding and shuffling of electronic charge for CCD pixels. |
| Observation Configuration File | A file, in XML format, that contains information required for a particular observation. This information includes, for example, the observation date, the predicted temperature, etc |
| OSIRIS configuration file | The file used to configure various parameters needed by the mask designer. These parameters do not pertain to a particular observation nor to the configuration of the telescope/instrumentation. The file name is OSIRIS_MaskDesigner.cfg and its format is plain text with parameters defined in basic "keyword=value" format. |
| Target List | A plain text file containing using a list of values representing equatorial co-ordinates in right ascension (() and declination ((). The format of a target entry is defined in section 4.4.1 |
| Telescope configuration file | A
file, in XML format, that contains data specific to the GTC telescope
and the instrument OSIRIS. |
| FITS | Flexible Image Transport System |
| MDF | Mask Definition File. Describes a single mask. Includes the description (dimensions and positions) of all slits within a mask. |
| MOS | Multi-Object Spectroscopy |
| ODF | Object Definition File. This file, in FITS format, contains general parameters for the observation (such as temperature, date, etc), all input objects and their associated slits, all slit data (in world coordinates, plus angles, radii, etc), the mask to which every slit belongs and mask position data. |
| OPMS | Observing Program Management Subsystem |
Pre-Conditions
This section describes the requirements needed in order to correctly execute
the JSkyCat tool.
System
Software
The following Java software must be installed on the target platform:
* JDK - Sun's Java Development Kit (JDK) (version 1.4.0_01 or above) [http://java.sun.com/].
* JAI - Sun's Java Advanced Imaging (JAI) toolkit (version 1.1.1_01) [http://java.sun.com/products/java-media/jai]
Versions are available for Solaris, Unix, and Windows.
Nota: Indicar los links utilizados por el IAC.
3.2
System Environment Variables
Once the JDK and JAI packages are installed, the only environment variable
requirement is that the PATH contains $JDK1_4/bin where $JDK1_4 is the
path into the jdk1.4.0.
4 Mask Designer Execution
4.1 General
Whenever a user wants to design his own set of masks for a future MOS
or Nod-and-Shuffle observation with OSIRIS, all the necessary configuration
files and environment variables should be up to date. Although an OSIRIS
image is desirable in order to obtain as results, it is also possible
to use images from any other source (with absolute astrometry information
included in the FITS primary header).
If no image is provided, lists of objects in equatorial co-ordinates obtained
from catalogues can be ingested by the tool and used as input data. These
objects may be either referred to J2000 or B1950.0. OSIRIS Mask Designer
shall use the former or the latter depending on the value set for the
XML tag <imageCentre> included in the observation file:
E.g.: <imageCentre>07:01:58.0, +00:02:57.00 J2000</imageCentre>
When
positions of objects in an OSIRIS image are known, a list of pixel co-ordinates
can be also used.
When an image is used as input, the user can draw different slits (rectangles,
circles and curved slits) with different sizes and priorities. For lists
of objects, all slits drawn shall be default-sized, and the user is allowed
to change their size. However, no changes in their positions are permitted
as they have been set in the ingested file.
Once all slits are successfully displayed and configured the user can
process the mask. Several masks may be generated up to the maximum number
of masks allowed, whose value is set in the OSIRIS Mask Designer configuration
file. The software shall try to place as many slits as possible in the
main mask, and only those which produce overlapping or integrity conflicts
are sent to the second, then third and so on and so forth until the maximum
number of masks is reached. Should any conflict remain, the involved slit(s)
would be sent to a Residual mask, not meant to be physicaly reproduced
but to inform the user of those slits that will be lost.
The resulting masks can be saved either in an ODF (Object Definition File)
all together, or into several MDFs (Mask Definition Files), one per mask.
These are FITS files with all the necessary information stored in their
primary HDU.
4.2 Set environment variables for OSIRIS Mask Designer
Prior to run OSIRIS Mask Designer the user must check the environment
variable OPMS_CONFIG_DIR exists. This is an optional variable which shall
contain the path where the user can store the files containing observing
programs designed with the OPMS. This way OSIRIS Mask Designer shall search
for all the Observation Configuration files within the pointed directory.
4.3 Starting the tool
Run jskycat.sh (Solaris/Unix) or jskycat.bat (Windows) to start the JSkyCat
application. Or execute the line
java -jar lib/jsky.jar [options...]
As well as the JSkyCat standard options, the option [-observation ObservationFile] exists to load an Observation Configuration File for designing masks for a particular observation. Only the filename needs be specified as the path is set by default to that in OPMS_CONFIG_DIR. The observation file is in xml format, see ANNEX C for the values used from this file.
If the option -observation is not to be used and no Observation Configuration File is loaded when starting the tool, then the observation will need configuring. See 4.6.1 Observation Configuration Window for details on configuring the observation. Note that the value for the centre of the image must be set correctly for list of values representing the target positions.
4.4 Modes of Operation
The Mask Designer can be run in four different modes:
1. Using a list of values representing equatorial co-ordinates in right
ascension (() and declination (()
2. Defining slit positions with the mouse and an input FITS format image.
3. Defining slit positions with the mouse over an "raw image"
taken from OSIRIS, i.e an OSIRIS image not corrected from geometric distortions.
4. Using a list of values representing image co-ordinates in pixels (X,Y)
to define objects in an OSIRIS Image1.
Some of these options can be used at the same time to help the user to
understand and visualize the data. OSIRIS "raw images" can be
loaded in JskyCat together with a list of (x,y) co-ordinates in order
to see the designed slits displayed on an OSIRIS image (options 3 and
4). Other FITS images with good astrometry and corrected from geometric
distortions can be also loaded together with a list of equatorial co-ordinates
to identify objects and slits (options 1 and 2)
This section describes these modes in more detail.
It is assumed that JSkyCat is already loaded but no image is displayed.
Until the "Configure Observation" option is chosen from the
Mask Designer menu and the observation configured, JSkyCat behaves as
if the Mask Designer were not incorporated.
4.4.1 List of Target Values
Users can create their own files with lists of targets; these objects
shall be parsed into rectangular and/or circular default-sized slits either
for equatorial co-ordinate system or for OSIRIS Image co-ordinate system
(X and Y)
If a parsing error occurs when loading the Target List, the operation
is aborted and a warning given.
Once a list of targets has been successfully loaded, approximate representations
of the slits are drawn on the screen. The scale of the world coordinates
per screen pixel depends on the screen size and the size of the field.
The slits may not be moved, though their size may be adjusted by double
clicking the slit and altering the size in the Slit Type Window.
Once finished, the slits may be processed. See 4.6.2 Process Mask for
details of the steps for mask processing.
4.4.1.1 List of Objects in Equatorial Co-ordinates
Select "Load Target List..." from the Mask Designer menu. This
brings up an open file dialog. The contents of the list of targets must
be ASCII (plain text) with the following layout:
hh mm ss dd mm ss PMotionRA PMotionD SlitType Angle/FiducialFlag priority
* The first three numbers are the right ascension (() value.
* The next three are the declination (() value.
* The next two values are the proper motion right ascension and declination
in degrees, or 0.0 if the proper motion is not known.
* The next value is the character R or C for Rectangular or Circular slits.
* The next value is the angle of the slit for rectangular slits or the
fiducial flag "F" for circular slits. Only rectangular slits
may be rotated by angles and only circular slits may be set as fiducial.
* The final value is the priority of the slit. This is used to determine
which slits to include in the primary mask(s) when slits or their spectra
overlap.
The
data contained in the file is assumed to be the same epoch as the specified
centre of the image. For example, if the centre of the image is defined
in J2000, the input file is assumed to be in J2000. However, if the image
centre is defined in terms of B1950, then the input file is assumed to
contain data in B1950 format. For an example of the format of the input
file, see ANNEX B.
4.4.1.2 List of Objects in Image Co-ordinates
The contents of a list of targets in image coordinates must be ASCII (plain
text) with the following layout:
X Y SlitType Angle/FiducialFlag priority
* The first value is the X coordinate (pixel column) of the target centre
* The next value is the Y coordinate (pixel row) of the target centre
* The next value is the character R or C for Rectangular or Circular slits.
* The next value is the angle of the slit for rectangular slits or the
fiducial flag "F" for circular slits. Only rectangular slits
may be rotated by angles and only circular slits may be set as fiducial.
* The final value is the priority of the slit. This is used to determine
which slits to include in the primary mask(s) when slits or their spectra
overlap.
4.4.2 Slits on an Image
The second method of generating masks is to draw the slits either over
an image with astrometric data or over an OSIRIS image non-corrected from
geometric distortions, where no accurate astrometry is needed.
After JSky starts, load an image by selecting the menu File ? Open or
by clicking the Open button (Figure 1). From the resulting file dialog,
select the fits image to open. This image must be in FITS format and contain
corrected world co-ordinate data.
Figure 1 Opening an image file
After loading the image, select "Configure Observation" from
the Mask Designer menu. See 4.6.1 Observation Configuration Window for
details on configuring the observation. The centre of the mask is taken
as the centre of the fits image.
After the observation is configured, slits may be drawn on the screen
by clicking the mouse. The default slit type is a rectangular slit. To
change the current type, select the "Set Slit Type..." option
from the Mask Designer menu. See Section 16 for more information on the
use of the Slit Type window.
Figure 2: Slits drawn on image
The slit position may be changed by dragging the slit on screen. The accuracy
of the position (i.e. how close to the desired ( and ( the slit is) depends
largely on the screen resolution and the size of the image. For setting
the slit ( and ( values accurately, the "Slit Type" window is
recommended.
4.5 Mask Types
OSIRIS Mask Designer can generate masks for two OSIRIS observing modes:
- Multi-Object Spectroscopy (MOS): This observing mode offers the possibility
of obtaining spectra of several hundred objects simultaneously by cutting
the same number of slits all over the mask2
- Nod and Shuffle: allows astronomers to effectively subtract away the
bright spectral emission lines and fainter continuum of our atmosphere's
nighttime glow while retaining the faint spectra of stars and galaxies.
The technique also significantly reduces the amount of electronic noise
introduced by the charged-coupled-device (CCD) detectors. To do this,
precise telescope motions (nodding) and electronic shuffling of electrical
charges built up by light striking the CCD's must be executed. Only the
central third of the CCD must be exposed; thus, only this central third
of the mask must contain slitlets for the light to go throw.
An option in the Mask Designer Menu can be activated for generating Nod
and Shuffle masks and therefore deactivated for generation of MOS masks.
4.6 Common Features
This section describes features used in the Mask Designer when run in either of the two modes described above. All features are available by selecting from the Mask Designer menu shown in Figure 3.
Figure 3 Mask Designer Menu
4.6.1 Observation Configuration Window
After JSkyCat is loaded, the observation needs to be configured. This
means setting the values required for the expected conditions of the observation.
The is achieved using the Observation Configuration Window, show in Figure
4.
In order to activate the window, select "Configure Observation"
from the Mask Designer menu. The list of parameters shown depends on the
values in the OSIRIS configuration file. The values of the parameters
are taken from the Telescope configuration file and any Observation Configuration
File that is currently loaded. If no observation configuration file is
currently loaded, some of the values may be blank. If this is the case,
then the list of slits for the observation may not be processed.
Figure
4 Observation Configuration Window
By default the parameters shown are:
* Observation temperature: The predicted temperature of the observation.
This value is read from the observation configuration file.
* Observation pressure: The predicted air pressure at the time of the
observation.
* Observation date: The date and time of the observation. The time zone
is UTC.
* Hour Angle of the observation: If the observation date has not been
set by the user, it is possible to generate a mask by using an hour angle
too.
* Maximum number of masks: The maximum number of masks that should be
generated in the case of overlapping slits or slit spectra.
* Filter: The filter to be used.
* Grism: The grism to be used.
* Grism orientation: The orientation of the grism with respect to the
x-axis. Can be 0º or 90º. Anything other than these values is
taken as 0º.3
* Image centre: The centre of the image in world coordinates (format is
hh:mm:ss, sdd:mm:ss J2000).
* PSF: The PSF value, which is used to define the default slit size for
targets read in from a list of target objects
* Position angle: The position angle of the mask. This angle represents
the angle between the x-axis of the mask and the North of the image. For
example, a mask that is to be aligned with the image should have its Position
Angle set to 90º.
With the exception of the grism and filter information, the values are
shown in text fields. The grism and filter values are shown in a list
of values read from the telescope configuration file.
Click the "..." button to open a file browser to locate an XML
file containing the observation configuration data (Observation Configuration
File). SampleObservation.xml is an example of the file format.
4.6.2 Process Mask
Once the slits have been placed, either from a Target List or by drawing
the slits over an image, the option "Process Mask" may be chosen
from the Mask Designer menu. If there are no slits to process or the minimum
number of fiducial slits is not met then a warning will be given and the
processing aborted.
An error message will also be given if the positioning of the fiducial
holes is not correct. This occurs when the fiducials overlap one another
or they are positioned in such a way that they will not appear on the
mask.
Other possible causes of error are when slits have been placed within
the mask frame or lay on the gap between the two OSIRIS CCDs. The corresponding
message is thrown by the tool to inform the user and no further processing
is allowed.
Once the slits have been successfully processed, a window with the resulting
masks is displayed. The maximum masks is as defined by the user, but the
number of masks may be less if all the useful slits fit onto one mask.
Other slits are placed onto the "residual" mask. These are slits
that do not fit onto the main masks, slits that overlap fiducials or slits
that overlap other slits when the maximum number of masks is reached.
Once processing is completed, the Process Mask Window will be displayed,
see below, and the colour of the slits may change on the main display.
The colours have the following meaning:
* Red for overlapping slits.
* Blue for slits that do not fit onto the mask
* Yellow for slits that have overlapping spectra, but only when the spectra
check is enabled. See below.
4.6.3 Processed Mask Window
The Processed Mask Window is shown after the slits have been successfully processed into masks. An example is shown in Figure 5. The window has a menu with options to print the currently selected mask, to save the masks in an ODF file or to save the chosen mask in an MDFfile.
Figure
5 Processed Mask Window
The slits are shown as black (the default colour) rectangles, circles
or curves, with their approximate spectra as orange (the default colour)
boxes. The spectra shown are only approximations based on the mapping
of scale from the CCD to the mask. The overlap of spectra is that calculated
as they fall on the CCD.
4.6.3.1 Print
Selecting the menu option "Print" displays the platform dependent
print dialog window. From here the printing options may be selected.
The printout will contain the slits displayed in the currently selected
mask, together with their spectra if the option for spectra checking is
enabled. In addition, optional information may be printed in the printed
page. The default extra information is:
* Mask name
* Mask Plate Scale
* Number of slits on the mask
* Mask Position Angle
* Date of the printout
* Centre position of the image in world coordinates
The possibility exists to change these defaults or add more parameters
(the maximum limit is 10 values) by editing the configuration file. Section
4.7.1 has more details on the configuration parameters to change.
4.6.3.2 Save
Selecting the menu option "Save ODF" displays a save file dialog
window. A suitable name is chosen and when the save button is pressed,
the file is saved with the extension ".fits". The operation
is similar for the menu option "Save MDF", but an MDF is saved
instead of an ODF.
More details of saving is given in section 4.10.
4.6.4 Spectra Check Enabled
This option in the Mask Designer menu enables or disables the check for
overlapping spectra when processing the slits into masks. When the option
is checked, the check for spectra verlap takes place otherwise overlapping
spectra are not taken into account when determining which slits are placed
into which masks.
The value of the parameter SpectraOverlapCheck ("true" or "false")
in the OSIRIS configuration file determines the default behaviour.
4.7 Configuration
4.7.1 Mask Designer Configuration
4.7.1 Mask Designer Configuration
The file OSIRIS_MaskDesigner.cfg reads user interface parameters for the
main display and may be edited to change the default values shown in the
Configuration Window and in the print out of processed masks.
Values take the form of keyword = value and comments may be entered at
the start of a line with the characters //
The configuration file is read before other mask designer configuration
files, and if the reading of the file fails, the mask designer will not
work correctly.
The following table has keywords used and their meanings
| Keyword | Description |
| XML_CONFIG_FILE | The name of the telescope configuration file |
| XML_CONFIG_PATH | The path (relative or absolute) to the telescope configuration file |
| SpectraOverlapCheck | Defines whether by default the spectra overlap check is switched on. "true" indicates that it is, "false" that it is not. |
| TelescopeXMLMaximumAge | Determines the maximum age of the telescope configuration file. When this age is exceeded a warning is issued. |
| ObservationFile | The name of an observation configuration file to load. If the command line option -observation is used, the -observation value overrides this one. |
| DateFormat | The format of the dates displayed in the various windows and on the print out of the processed mask |
| MaxMasks | The maximum number of masks to use |
| psf | The psf is used to calculate the size of each target when a list of targets is read in |
| psfHeightFactor | Used when calculating the size of rectangular slits read in from a list of target positions. The height of the slit is psfHeightFactor * psf, while the slit width is psf |
| psfDiamFactor | Used when calculating the size of circular slits read in from a list of target positions. The diameter of the slit is psfDiamFactor * psf |
| MinFiducialCount | The number of fiducial slits that need to be defined before processing of the mask may be performed |
| DecimalString | Format of decimal strings displayed in the user interface. |
| OSIRIS_Log | The name of the log file to write information and warning messages to |
| MaxLogSize | The maximum size of the log file (in bytes) after this the old log is renamed OSIRIS_Log.old, if OSIRIS_Log.old already exists, it is replaced |
| DebugTrace | The debug trace outputs extra information to the log. This can be used to verify that the calculations are performed correctly at each stage of the sky to mask mapping. |
| XMLParameters | The number of XML parameters to show in the Observation Configuration window. |
| XMLParameter<N> | Where <N> starts at 1 and goes up to the number of parameters specified. The name of the parameter to display. The actual displayed name is taken from the gui.properties file for the jsky.maskdesigner.gui package. If no gui name is found, the value of this keyword is shown. This allows, for example, the keyword "imagecentre" to be displayed in the gui as "Image Centre". |
| XMLParameterEdit<N> | If this parameter is editable, this value should be set to true. Otherwise it should be false. This is optional, the default value is false. |
| XMLParameterType<N> | The type of parameter. This determines the checking at run time. This value can be one of FLOAT, INT, STRING or WORLDCOORDS. If no type is set, the default is INT. |
| PrintParameter<N> | The
parameter to show on any hardcopies of the mask made. N can be 1-10,
when a PrintParameter<N> is not found in sequence, the rest
are ignored. The actual displayed name is taken from the gui.properties
file for the jsky.maskdesigner.gui package. The value is always a
String. Special parameter names that use runtime information to produce printout values are as follows: _date_ prints the date/time of the printout (use ObservationDate to print out the planned observation date) _slits_ prints the total slits on the mask, including fiducials _slitsnf_ prints the total slits on the mask, without fiducials _mask_ prints the mask name (e.g. Mask 1, Residual, etc) |
| DefaultSlitColour | Colour of the standard slits drawn on an image. |
| SlitOffMaskColour | Colour a slit is set to when it is calculated as being off the mask area. |
| SpectraOverlapColour | Colour a slit is set to when its spectrum overlaps that of another slit. |
| PhysicalOverlapColour | Colour a slit is set to when it overlaps another slit. |
| MaskFrameColour | Colour of the mask frame, gap and nod and shuffle zones when they are displayed on the Processed Mask Window. |
| MaskSpectraColour | Colour of the slit spectra when they are displayed on the Processed Mask Window. |
| MaskSlitColour | Colour of the slits when they are displayed on the Processed Mask Window. |
| SlitUnsafeZoneColour | Colour a slit is set to when it has been placed in the mask frame, gap or nod and shuffle zone. |
| Table
1: Table of configurable parameters for the OSIRIS Mask Designer
application |
|
For a particular colour parameter, the value of the parameter is an integer of the combined RGB component for that colour. The red component is in bits 16-23, green component in bits 8-15 and blue component in bits 0-7.
4.8 Slit type window
4.8.1 Setting the Default slit
This explanation only applies when adding slits over a FITS image. Selecting
"Set Slit Type..." from the Mask Designer menu activates the
Slit Type Window.
The default slit is the slit that shall be added to the mask next time
the mouse is clicked on the image. If the default is not changed then
it is a slit with the following properties:
* A Rectangular slit
* Width is the last defined PSF value. For example width is 1.0 arc sec
if the PSF value is 1.0.
* Height is the PSF value multiplied by the PSF height ratio. For example
height is 1.0*4 = 4.0 arc sec, in the case that the ratio is set to 4.
* Angle is zero degrees
Figure 6 shows the Slit Type Window. The Fields are activated and deactivated
depending on the type of slit currently selected.
Figure 6 Slit Type Window
The
type of slit is changed using the radio buttons in the top left of the
window. The following sections describe each slit type in detail.
4.8.1.1 Curve Slit
When the button "Curve Slit" is chosen, the following fields are available:
|
Table
2: List of parameters for a Curved Slit |
|
| Field | Description |
| Width (arcsec or pixels) | The width of the slit in arcseconds |
| Priority | The slit priority |
| Start X (hh:mm:ss.sss or pixel) | The start position of the slit, the right ascension or X component |
| Start Y (sdd:mm:ss.sss or pixel) | The start position of the slit, the declination or Y component |
| Ctrl1 X (hh:mm:ss.sss or pixel) | The first control point of the slit, the right ascension or X component |
| Ctrl1 Y (sdd:mm:ss.sss or pixel) | The first control point of the slit, the declination or Y component |
| Ctrl2 X (hh:mm:ss.sss or pixel) | The second control point of the slit, the right ascension or X component |
| Ctrl2 Y (sdd:mm:ss.sss or pixel) | The second control point of the slit, the declination or Y component |
| End X (hh:mm:ss.sss or pixel) | The end position of the slit, the right ascension or X component |
| End Y (sdd:mm:ss.sss or pixel) | The end position of the slit, the declination or Y component |
The control points define the extent of the shape of the curve, though the curved slit may not always cross through the control points. It is also possible to track out "impossible" shaped curved slits, for example slits that cross over themselves, but these illegal slits are rejected at process time.
4.8.1.2 Circle Slit
When the button "Circle Slit" is chosen, the following fields are available:
|
Table
3: List of parameters for a Circular Slit |
|
| Field | Meaning |
| Radius (arcsec or pixels) | The radius of the slit in arc seconds |
| Priority | The slit priority |
| X Position (hh:mm:ss.sss or pixel) | The centre of the slit in world coordinates, this is the right ascension or X component of the coordinates. |
| Y Position (sdd:mm:ss.sss or pixel) | The centre of the slit in world coordinates, this is the declination or Y component of the coordinates. |
| Fiducial | This "checkbox", when ticked, indicates that the slit to be added is a fiducial slit. |
4.8.1.3
Rectangle Slit
When the button "Rectangle Slit" is chosen, the following fields
are available:
|
Table
4: List o parameters for a Rectangular Slit |
|
| Field | Meaning |
| Width (arcsec or pixels) | The slit width in arc seconds |
| Height (arcsec or pixels) | The slit height in arc seconds |
| Angle (degrees) | The angle between the slit and the y axis of the image |
| Priority | The slit priority |
| X Position (hh:mm:ss.sss or pixel) | The centre of the slit in world coordinates, this is the right ascension or X component of the coordinates. |
| Y Position (sdd:mm:ss.sss or pixel) | The centre of the slit in world coordinates, this is the declination or Y component of the coordinates. |
If the current image has astrometric information then the slits will be positioned using world coordinates and arc seconds for their dimensions. On the other hand, if the image is an OSIRIS image that has not been corrected for geometric distortion, then the slits are positioned using pixel coordinates and the dimensions are defined in pixels.
4.8.2
Changing an existing slit
The other operation of the Slit Type Window is to alter a slit that already
exists. In this case, the Slit type Window is activated by double clicking
the centre of a slit that has already been placed on the main image. The
double click has to occur within the bounds of the slit, i.e. within the
white lines that mark the perimeter of the slit, so it may be necessary
to zoom in if the slit is particularly small compared to the current scale.
Clicking outside of the bounds will draw another slit on the screen.
When the Slit Type Window is displayed, it contains the values for the
selected slit filled in. The values can be changed and when "OK"
is selected, the slit is updated. If "Cancel" is selected, the
changes are not made.
The fields that can be altered in this mode depend on the type of slit
selected and are the same for setting the default slit. See sections 4.8.1.1,
4.8.1.2 and 4.8.1.3 for details.
4.9
Deleting slits
There are two ways to delete slits; one by one or all slits at once. To
delete slits one at a time, select the slit on screen and choose the Mask
Designer menu option "Delete Slit". This option only deletes
the currently selected slit, so if no slit is chosen it will do nothing.
Selecting the option "Delete All Slits" will result in a dialog
box asking if you really wanted to delete all slits Figure 7. Selecting
"No" will result in no action taking place, while selecting
"Yes" will delete all slits. This action is not reversible,
so care should be taken when deleting all slits.
Figure
7 Last chance to abort deleting all slits
Any slits that have been added to the current display are also removed
when a new FITS image or list of target objects is loaded. The way to
keep track of work in progress is to save the slits in an Object Definition
File.
4.10
SAVING AND LOADING MASKS IN PROGRESS
It is convenient to be able to save a half-completed mask to reload it
later and continue with the work. The way to do this is to process the
mask by selecting "Process Mask" from the Mask Designer menu.
This will process the current contents of the display and display the
Processed Mask Window. The menu of the Processed Mask Window has the following
saving options:
* Save ODF
* Save MDF
* Save All
If data is not saved after processing the masks, then a warning is issued
as the data for the slits may be lost if a save is not performed by the
user.
4.10.1
Object Definition File (ODF)
If the option Save ODF is chosen, all of the current slits are saved.
This includes any invalid slits, which may have overlapping boundaries,
either with another slit or with the mask edges, or slits with overlapping
spectra. The ODF is saved in FITS format and has a single primary header
and no image data. The header contains a list of keywords that can be
thought of as containing 3 "regions", though all are contained
in a single list:
1. General observation and telescope data
2. Mask data (all slits)
3. Fiducial slit data
ANNEX
A contains the meanings for each of the keywords found in an ODF.
The first part of the list of keywords, after the obligatory entries,
contains values of parameters loaded from the observation and telescope
configuration files.
The mask data part of the list contains, for each mask generated including
any residual mask, the slit type and slit geometric data.
The fiducial slit data is stored at the end of the ODF. This is because
each valid mask contains the same fiducial slits/holes and so they need
to be stored just once.
It is possible, using external FITS-editing software, to add new slits
and masks to the ODF by inserting new keywords. Care should be taken to
retain the structure and keep the internal counts of slits-per-mask and
total masks up to date if this approach is taken. It is usually easier
to add additional slits using the JSkyCat/Mask Designer graphical interface
and adjust the slit parameters using the Slit Type Window (4.8).
4.10.2
Mask Definition File (MDF)
If the option Save MDF is chosen, only the slits on the currently displayed
mask are saved. If the current mask is the invalid Residual Mask then
the fiducial slit information will be lost if further saving is not made.
The structure of the MDF is identical to the ODF, except that rather than
containing a list of masks, the MDF contains just one mask of interest.
4.10.3
Save All
If the option Save All is chosen, then an ODF containing all information
is saved together with MDFs for each of the generated masks. The files
are named based on the value of <name> given by the user:
* <name>_ODF.fits
* <name>_MDF_1.fits, <name>_MDF_2.fits, ...., <name>_MDF_n.fits
for the number of masks generated.
4.10.4
Open ODF
The option Open ODF on the main Mask Designer menu allows a previously
saved ODF file to be loaded. After selecting the option, the standard
locate file dialog box appears. From here, locate the ODF to load and
the saved slits will reappear.
In order to continue working from a previous design, a FITS image must
be loaded first. This is so that the world coordinates for the underlying
mouse movements are consistent. If no FITS is loaded, or if an incorrect
FITS file is loaded, then the slits will not be editable or may not appear
in the currently visible area.
Note that when loading an ODF, the values of internal parameters are set
to the values in the saved ODF file. The correct order for updating an
observation with newer values for parameters (e.g. to change the date
of observation or the position angle) is, therefore:
* Load FITS image
* Load ODF
* Load the observation configuration file
ANNEX A OBJECT DEFINITION FILE KEYWORDS
| Keyword |
Meaning |
| SIMPLE |
Standard FITS (NOST-100-2.0) |
| BITPIX |
# of bits per pix value |
| NAXIS |
# of axes in data array |
| NAXISn |
|
| ORIGIN |
|
| EXTEND |
FITS extension may be present |
| END |
|
| MASKPLSC |
Mask Plate Scale |
| MASKWDTH |
Mask Width |
| MASKHGT |
Mask Height |
| RADIUS |
Curvature radius of the mask |
| TILT |
Curvature tilt of the mask |
| YOFF |
Mask coordinate Y offset |
| MNSLTSEP |
Minimum slit seperation |
| FABTEM |
Mask fabrication temperature |
| MAXMASKS |
Maximum number of masks generated |
| RA |
%HOURANG RA (J2000) pointing |
| DEC |
%DEGREE DEC (J2000) pointing |
| LATITUDE |
Latitude of the telescope |
| LONGITUD |
Longitude of telescope |
| OBDATE |
Date of observation, YYYY :MM :DD HH |
| OBTEM |
External temperature for the observation |
| OBPRES |
External pressure for the observation |
| OBWVP |
Water vapour pressure for the observation |
| GRISM |
Grism identification |
| GRMIN |
Grism minimum wavelength |
| GRMAX |
Grism maximum wavelength |
| GRWLEN |
Grism central wavelength |
| GRDP |
Grism dispersion per pixel |
| GRRES |
Grism resolution |
| GRORI |
Grism orientation |
| SECPIX1 |
Arcseconds per pixel in X direction |
| SECPIX2 |
Arcseconds per pixel in Y direction |
| NAXIS1 |
Number of pixels X |
| NAXIS2 |
Number of pixels Y |
| CRPIX1 |
X reference pixel |
| CRPIX2 |
Y reference pixel |
| CROTA1 |
Rotation Angle |
| FOV |
Field of view in arcmins |
| MINFID |
Minimum fiducial count |
| SLITPA |
Position angle |
| SPECCHCK |
Spectra check status |
| IS_ODF |
Is the file an Object Definition File |
| MASKFILE |
Filename of the file used to fabricate the mask |
| SLIT DEFINITIONS |
|
| MASKCNT |
Number of masks. Mask count includes residual |
| MID001 |
Mask ID (maximum of 999 masks) |
| MNAME001 |
Name of mask |
| STCNT001 |
Number of slits on mask |
| ORA0001 |
Right ascension of the target astronomical object |
| ODEC0001 |
Declination of the target astronomical object |
| STY0001 |
Slit type - RECTANGULAR CIRCULAR CURVED |
| RA1_0001 |
Slit right ascension (centre for rectangular/circular slits) |
| D1_0001 |
Slit declination (centre for rectangular/circular slits) |
| Curved slits have 4 points defined RA2_0001, D2_, etc |
|
| SW0001 |
Slit width (arcsec) Rectangular and Curved slits only |
| SH0001 |
Slit height (arcsec) Rectangular and Curved slits only |
| SR0001 |
Slit radius Circular slits only |
| SPA0001 |
Slit position angle Rectangular slits |
| UP0001 |
User given priority |
| SFD0001 |
Is fiducial ("T" or "F") for Circular slits only |
| PMRA0001 |
Proper Motion RA |
| PMD0001 |
Proper Motion DEC |
| X1_0001 |
X position on mask |
| Y1_0001 |
Y position on mask |
| Curved slits have 4 points defined X2_0001, Y2_, etc |
|
| MW0001 |
Slit width on mask Rectangular and Curved slits only |
| MH0001 |
Slit height on mask Rectangular |
| MR0001 |
Slit radius on mask Circular slits only |
| SPEC0001 |
Spectrum section for this slit |
ANNEX
B EXAMPLE OF INPUT TARGET LIST
// RA (hours minutes seconds) Dec (degrees minutes seconds)
// 0-24h -90° to +90°
// RA| DEC|
// hh mm ss| dd mm ss| PMotionRA PMotionD SlitType angleº/FiducialFlag
priority
07 01 59.980 +00 05 49.20 0.0 0.0 C F 0
07 01 50.930 +00 01 16.64 0.0 0.0 C F 0
07 01 53.120 +00 00 23.91 0.0 0.0 R 0.0 1
07 01 54.430 -00 00 17.84 0.0 0.0 R 0.0 2
07 01 56.690 +00 02 19.89 0.0 0.0 R 0.0 3
07 01 56.710 +00 00 51.81 0.0 0.0 R 0.0 4
07 01 56.850 +00 06 54.49 0.0 0.0 R 0.0 5
07 01 57.570 +00 03 22.55 0.0 0.0 R 0.0 6
07 01 57.890 +00 04 40.33 0.0 0.0 R 0.0 7
07 01 58.680 +00 06 28.02 0.0 0.0 R 0.0 8
07 01 58.940 -00 01 08.21 0.0 0.0 R 0.0 9
07 01 59.220 +00 04 21.62 0.0 0.0 R 0.0 10
07 01 59.340 +00 03 49.76 0.0 0.0 R 0.0 11
07 01 59.620 +00 05 32.41 0.0 0.0 R 0.0 12
07 02 01.010 +00 03 05.29 0.0 0.0 R 0.0 13
07 02 03.400 +00 01 56.36 0.0 0.0 R 0.0 14
07 02 03.620 +00 00 46.13 0.0 0.0 R 0.0 15
The above data is an example of a Target List, an ASCII format file containing
a list of target positions in world coordinates. A similar example follows
for the format of a Target List with target positions in x,y CCD coordinates:
// X Y SlitType angleº/FiducialFlag priority
1986 2214 R 0.0 1
1730 1946 R 0.0 2
1889 2141 C F 10
2239 1959 C F 12
1822 1877 C N 100
1687 2038 R 0.0 56
ANNEX C OBSERVATION CONFIGURATION PARAMETERS
This section contains a full list of the values read form the observation
configuration file.
| Name | Description |
| Firstname | First name of the user who has requested the observation |
| Surname | Surname of the user |
| Positionangle | Position angle of the mask |
| Grism | The name of the grism to use |
| Filter | The name of the filter to use |
| Grismorientation | 0º or 90º - the orientation of the grism wrt the x axis of the mask |
| observationDate | The anticipated date and time of observation |
| ObservationTemperature | The expected temperature for the observation |
| pressure | The expected atmospheric pressure |
| WaterVapourPressure | The expected water vapour pressure |
| imageCentre | The centre of the image. This will coincide with the centre of the mask and the central reference pixels of the CCD |
ANNEX D CCD TO MASK POLYNOMIAL DESCRIPTION
The calculation of the mask coordinates first converts the input coordinates
to off-centre seperations. Next the initial value of the mask off-centre
offset is calculated by dividing by the mask to CCD scale. Finally a Newton's
method iteration is applied to calculate the correct mask position.
ANNEX E XML CONFIGURATION FILE PARAMETERS
<LastUpdate>
The date that the Telescope and Instrument configuration file was last
updated. A period of time (90 days by default, defined by TelescopeXMLMaximumAge
in the general application configuraiton file) after this date, a warning
shall be issued when the file is loaded by JSky. This is to prevent the
values from going out of synch with the actuality of the telescope configuration.
<CCDtoMaskMapping>
Defines the start of the Polynomial factors for calculating the CCD to
Mask mapping when defining slits using x,y pixels positions. The polynomial
equations used to calculate the position of slits on the mask when working
with x,y positions are as follows:
F= F(x,y) = A0 x + A1 y + A2 + A3x2 + A4xy + A5 y2 + A6 x2 + A6 y2 + A7
x3 + A8 x2 y + A9 y2 x + A10 y3 + A11 x3 + A11 x y3 + A12 x5 + A12 x y4
+ 2A12 x2y2
G= G(x,y) = B0 y + B1 x + B2 + B3y2 + B4xy + B5 x2 + B6 y2 + B6 x2 + B7
y3 + B8 y2 x + B9 x2 y + B10 x3 + B11 y3 + B11 y x3 + B12 y5 + B12 y x4
+ 2B12 y2x2
<PolyFactor1X> . . . <PolyFactor13X>
The coefficiants A0 to A12 in the above equations correspond to the values
PolyFactor1X to PolyFactor13X.
<PolyFactor1Y> . . . <PolyFactor13Y>
The coefficiants B0 to B12 in the above equations correspond to the values
PolyFactor1Y to PolyFactor13Y.
<SkytoMaskMapping>
Defines the start of the Polynomial factors for calculating the Sky to
Mask mapping when using object positions defined by world coordinate values.
The polynomials are used to map the off-axis angles to projected physical
coordinates and the factors defined in this file have been determined
by optical ray tracing. The polynomial equations used to calculate the
position of slits on the mask when working with x,y positions are as follows:
F= F(x,y) = A0 x + A1 y + A2 + A3x2 + A4xy + A5 y2 + A6 x2 + A6 y2 + A7
x3 + A8 x2 y + A9 y2 x + A10 y3 + A11 x3 + A11 x y3 + A12 x5 + A12 x y4
+ 2A12 x2y2
G= G(x,y) = B0 y + B1 x + B2 + B3y2 + B4xy + B5 x2 + B6 y2 + B6 x2 + B7
y3 + B8 y2 x + B9 x2 y + B10 x3 + B11 y3 + B11 y x3 + B12 y5 + B12 y x4
+ 2B12 y2x2
<PolyFactor1X>
. . . <PolyFactor13X>
The coefficiants A0 to A12 in the above equations correspond to the values
PolyFactor1X to PolyFactor13X.
<PolyFactor1Y> . . . <PolyFactor13Y>
The coefficiants B0 to B12 in the above equations correspond to the values
PolyFactor1Y to PolyFactor13Y.
<MaskPlateScale>
The plate scale in the Nasmyth or Cassegrain focus. Units are arcsec/mm.
<MaskToPixelScale>
The ratio of mm on the mask to pixels on the CCD. If this value is 0 or
left undefined, then the ratio is calculated from the MaskPlateScale and
the PixelResolution1 value.
<PixelSize>
The size (width) of a CCD pixel in mm.
<PixelResolution1>
The width of a pixel in arcseconds
<PixelResolution2>
The height of a pixel in arcseconds
<PixelCentre1>
The X coordinate of the centre of the CCD. This is the point where the
optical axis of the camera falls upon the CCD.
<PixelCentre2>
The Y coordinate of the centre of the CCD. This is the point where the
optical axis of the camera falls upon the CCD.
<PixelCount1>
The width of the CCD in pixels.
<PixelCount2>
The height of the CCD in pixels.
<RotationAngle>
When a list of target slits with positions defined in World Coordinates
is loaded, this value allows the overall "image" to be rotated.
Recommended value is 0, units are degrees.
<NodAndShuffle>
The size, in arc minutes in float format, of the nod and shuffle zone.
<PixelGap1> <PixelGap2> <PixelGap3> <PixelGap4>
The four points form a polygon that represents the gap between the two
CCDs, in units of pixels. The layout of the polygon is as shown in Figure
16 below.
<FrameWidth>
The width of the frame that holds the mask in place in the telescope.
Units are mm.
<CameraFocalLength>
Focal length of the OSIRIS camera, in mm.
<CurvatureRadius>
The radius of curvature of the masks
<CurvatureTilt>
The tilt of curvature of the masks
<Latitude>
The position of the telescope, latitude in degrees.
<Longitude>
The position of the telescope, longitude in degrees.
<MaskWidth>
The width of the mask in mm.
<MaskHeight>
The width of the mask in mm.
<MaskCoordinateOffset>
The y offset of the mask centre from the optical axis. Units mm.
<MinimumSlitSeparation>
The safety distance that must be left between slits to keep the mask integrity.
Units mm.
<FabricationTemperature>
The predicted temperature that the mask will be cut at. Units ºC.
<FilterDefinitions>
Indicates the start of the narrow band filter definitions.
<Filter type="IRF1">
The start of a filter definition. Type is the name of the filter and must
be unique as duplicate definitions are overwritten.
<LambdaMin>
The minimum wavelength that this filter permits to pass through.
<LambdaZero>
The central wavelength of this filter.
<LambdaMax>
The maximum wavelength that this filter permits to pass through.
Wavelength units are in Angstroms.
<GrismDefinitions>
Indicates the start of the grism definitions.
<Grism type="IR_G1">
The start of a grism definition. Type is the name of the grism and must
be unique as duplicate definitions are overwritten.
<LambdaMin>
The minimum wavelength that this grism may be used with.
<LambdaZero>
The central wavelength of this grism.
<LambdaMax>
The maximum wavelength that this grism may be used with.
<RefractiveIndex>
Refractive index of the material that the prism is made from.
<Angle>
Angle of the prism, in degrees
<Lines>
Number of lines per µm on the grid.
<grism>
The name of the grism to use in this observation
<filter>
The name of the filter to use in this observation
<grismorientation>
The orientation of the grism, either 0 or 90º
<observationDate>
The predicted date of the observation, the format used follows the java.text.SimpleDateFormat
convention and is described by dd.MM.yyyy HH:mm:ss z (day:month:year hours:minutes:seconds
time zone). This keyword is optional, if it isn't set then the current
date is used.
<hourangle>
Instead of using an observation time, the hour angle may be set. The format
is hh:mm:ss.s.
<ObservationTemperature>
The predicted temperature at the time of the observation. Units are in
ºC.
<pressure>
The predicted atmospheric pressure at the time of the observation, units
used are mm Hg.
<WaterVapourPressure>
The predicted water vapour pressure at the time of the observation, units
used are mm Hg.
<imageCentre>
The centre of the image in world coordinates. This is in the format hh:mm:ss.s,
sdd:mm:ss.s e
This corresponds to hours:minutes:seconds, sign (+ or -, or left off for
+) degrees:minutes:seconds epoch (either J2000 or B1950). The value corresponds
to the pointing position of the telescope.
1
This option shall be available ONLY for images obtained with OSIRIS.
2 Avoiding the gap region between both OSIRIS CCDs and the border areas
where the frames clip the mask.
3 If the user sets grism orientation to 90º a dialog box shall appear
prior to make any mask processing as this is not the nominal grism orientation
for OSIRIS MOS modes. It is meant to remind the user about his "not
standard" selection, but no error is implied. The message prompts
the user to make sure about continuing with the processing, and no other
changes in the design session are produced.
Last update July 8, 2005, by Héctor Castañeda