If you're lucky (meaning that you have an i386 GNU/Linux system with compatible libc and gtk+-1.2 is installed on your system), the precompiled binary supplied with the distribution will just work. To test, cd to the toplevel distribution directory (gcx-x.x.x) and run:
src/gcxIf all goes well, you should get an empty window with a menu. Type ctrl-Q or File/Quit to exit the program. It is recommended that the program is installed in /usr/local/bin for example.
If the above doesn't work,2.1 you have to recompile the program. Make sure gtk+-1.2 is installed on the system (if you have Gnome, you also have gtk), then in the toplevel directory type:
./configure ; make clean ; makeConfigure takes some options. See the INSTALL file supplied with the distribution for more details.
If the above step completes successfully, become root and do a
make installThis will place the program in /usr/local/bin, and may also install data files in future versions.
The installation is now complete.
The data subdirectory of the distribution contains an example fits frame (uori-v-001.fits.gz), and an example recipy file for the frame (uori.rcp). These will be used throughout this section.
First, start the program:2.2
gcxYou should be presented with a empty window, with a menu at the top.
To load the example frame, type ctrl-O or use File/Open Fits; select the example fits file (uori-v-001.fits.gz) in the data directory an click Ok. The program will load and display the frame.
Alternatively, the fits file name can be supplied on the command line. Something like:
gcx data/uori-v-001.fits.gzwill star the program and load the frame at the same time.
Two status bars are displayed at the bottom of the window. The left one shows the current display parameters: the zoom level, the low cut and the high cut. The low cut corresponds to black on the monitor, while the high cut corresponds to 100% white. The values are expressed in the same units the FITS file is.
The right-side status bar shows the various status and error messages. When loading an image, global statistics for the image are displayed. This will be referred to as the ``status bar'' throughout this manual.
On most errors, a beep is sounded and an error message is printed in the status bar. Sometimes though, a command may appear to do nothing. Checking the terminal from which the program was launched will sometimes give an extra hint as to what happened.
To pan around the image, either use the scrollbars, or place the cursor over the point that you want in the center of the image and press the spacebar or the center mouse button.2.3
You can pan back to the center of the image using ctrl-L or select Image/Pan Center from the menu.
To zoom in, place the cursor over the point you want to zoom in around, and press the = key (same key that has the '+' symbol). To zoom out, press -. The Image menu also has Zoom In and Zoom Out options.
When loading a frame, the image cuts are automatically selected for a convenient display of astronomical frames. The background is set at a somewhat dark level, and the dynamic range is set to span 22 times the standard deviation of the intensity across the frame. You can always return to these cuts by pressing 0 or selecting Image/Auto Cuts.
Pressing 1 - 8 will select various predefined contrast levels. 1 is the most contrasty: the image spans 4 sigmas, while 8 spans 90 sigmas. 9 will scale the image so that the full input range is represented (the cuts are set to the min/max values of the frame). Selecting Image/Set Contrast/... from the menu will accomplish the same effect.
To vary the brightness of the background, use B (Image/Brighter) and D (Image/Darker).
Another, sometimes more convenient way of making contrast/brightness adjustments is to drag2.4 the pointer over the image. Dragging horisontally will change the brightness, while dragging vertically will adjust the contrast.
The key presses mentioned above are displayed in the menus alongside the respective options. F1 or Help/Show Bindings will show on-line help about mouse actions.
It is important to know that all the ajustments described only apply to the display. The internal representation of the frame (and of course the disc file) is never changed in any way.
Select File/Fits Header from the menu. A new window will display the optional FITS header fields from the loaded frame.2.5
GCX maintains a list of objects it can overlay on the display and run various processing steps on. They are called ``stars'' or sources. The stars can be extracted from the image, or loaded from catalogs or star files.
Ctrl-click on a star image. A round circle will appear around it (you cannot mark very faint or saturated stars). You don't need to click precisely on the peak - the program will search around, find a star and create an object (a user star) positioned at the centroid of the star image.
Click inside the circle. Information about the star will be displayed in the status bar: the start type (field star), the pixel coordinates (counting from the top-left corner), and the world coordinates if possible. Since the frame we loaded contained WCS information, but it couldn't be verified by the program, the status bar will show world coordinates, but will mark them as ``uncertain'' and disable all operations that depend on these objects' WCS. More on validating the WCS below.
Right clicking on a star will pop up a specific menu. As our WCS isn't validated yet, only the 'delete' option is active at this point.
Now press S or select Stars/Detect Sources. The program will search the whole frame, and mark stars. There is a limit as to how many stars will be marked. The limit can be changed by selecting File/Edit Options, clicking on the ``+'' next to Star Detection and Search Options and increasing the number in the Maximum Detected Stars field.
There is also a limit on how faint the detected stars can be. Decreasing the value in the Star Detection SNR field will make the program look for fainter stars. Note that a very low value of SNR will increase the run time of the detection routine considerably. Don't go below 2 or so.
To remove the detected stars from the display, use Stars/Remove Detected Stars or press shift-S.
Automatically detected stars and manually marked (user) stars are displayed with different symbols and deleted with separate commands, but otherwise equivalent. The program considers automatically detected stars somewhat expendable, but tries not to remove user stars unless specifically requested.
A second class of stars handled by GCX are catalog stars. They can be loaded from catalogs if installed on the system, or from star files.
Installing catalogs will be described later in this manual. For the moment, we will load the example recipy file from the data directory of the distribution.
Select File/Load Recipy from the menu, then select the example recipy file in the data directory (uori.rcp) and click ok.
Three types of stars will show up. Diamond-shaped ones are field stars. They are used to fit and validate the WCS. Target-shaped symbols are the standard stars. Their magnitudes are used to photometrically calibrate the frame. Cross symbols are ``variable'' or ``target'' stars - stars that we want to measure, but we don't know their magnitude in advance.2.6
To find out more about a star, right-click on a star symbol, and select Edit Star from the pop-up menu. This will open a dialog and display information about the star, which can be edited. The name, coordinates and comments fields should be obvious. Two types of magnitudes are shown: standard magnitudes are obtained from the catalog or recipy file; instrumental magnitudes are measured by the program.
A magnitude entry looks like this:
<band_name>(<system>)=<magnitude>/<error>The error and system fields are optional. The band name is the name of the filter ('v', 'b', etc). The system describes the source of the data. For instance, v(aavso) means 'v' magnitudes taken from aavso charts, while b(landolt) would be used for 'b' magnitudes of landolt standards.
For more information about stars, please see Chapter 4
If no information is known about the position of the field, the WCS is called ``invalid''. This can happen if the frame doesn't have WCS information in the header. When some information is available, we say the we have an ``initial WCS''. The program will treat wcs information from the header as approximate. If we have an initial WCS and some field stars, we can match the positions of the field stars with stars detected from the frame. If the program finds a good-enough match, it will decide that the WCS can be reliably used, and mark the WCS as 'valid'.
Our example frame already has an initial WCS. We have field stars loaded from the recipy file (or we could have some from GSC). We will first press S to detect starts from the frame. Select Wcs/Auto Pairs (or press P). This will match the stars and create pairs, which are drawn with dotted lines. Next, press Shift-W (or Wcs/Fit Wcs from Pairs), and the program will fit the WCS so that the pairs overlap, and display the mean error of the fit in the status bar. If enough pairs are fitted and the error is small enough, the fit will be validated.
Pressing M or Wcs/Auto Wcs will do all the above steps in one operation (detect stars, load field stars from GSC if possible, find pairs and fit the WCS). Pressing shift-M or Wcs/Quiet Auto Wcs will do the same, but will remove the detected stars and field stars after the fit. It will do nothing if the WCS is already valid.
The fitting algorithm can be tuned by changing parameters under WCS fitting options in the options dialog.
Once we have a valid WCS, we have new uses for the detected and user stars. Clicking on them will print their true coordinates on the status bar. It is also possible to mark them as variable stars, so they can be measured, or as standard stars, so they can participate in the photometry solution (for example when inputting data from a paper chart).
Choose a few detected stars, right click on them and choose Edit Star. Now check the ``variable'' flag. The star will be transformed into a variable, and its symbol changed to a cross.
Now that we have our valid WCS and we know which stars we want to measure and which standards to use, the actual photometry is easy: just press shift-P or Processing/Quick Aperture Photometry.
A quick result for the first variable star is printed in the status bar. All stars' magnitudes are updated, and can be examined using the Edit Star function.
The reduction process has a number of parameters, which can be accessed through the options dialog, under Aperture Photometry Defaults. For more details about the photometry process check Chapter 7.
All the clicking in this section can be eliminated with one command. From the toplevel directory, run:
gcx data/uori-v-001.fits.gz -P data/uori.rcpThe program will load the frame, load the recipy, fit the WCS and run the photometry. A report will be written to standard out (all debugging messages are printed to stderr, so redirecting stdout to a file will write just the report to that file. For example:
gcx data/uori-v-001.fits.gz -P data/uori.rcp >outfwill write the report to outf.