NAME¶
gcx - astronomical image processing and photometry
SYNOPSIS¶
gcx [
options]
[files...]
DESCRIPTION¶
gcx is an astronomical image processing and data reduction tool, with an
easy to use graphical user interface. It provides a complete set of data
reduction functions for CCD photometry, with frame WCS fitting, automatic star
identification, aperture photometry of target and standard stars, single-frame
ensemble photometry solution finding, multi-frame color coefficient fitting,
extinction coefficient fitting, and all-sky photometry, as well as
general-purpose astronomical image processing functions (bias, dark, flat,
frame alignment and stacking); It can function as a FITS viewer.
For automating data reduction of large numbers of frames,
gcx implements
recipe files. These files contain specific information about the
objects measured in each field. Once a recipe file is created for a given
field, any number of frames of that field can be reduced without user
intervention.
The program can control CCD cameras and telescopes, and implement automatic
observation scripting. Cameras are controlled through a hardware-specific
server, to which gcx connects through a TCP socket. It generates FITS files
with comprehensive header information.
Telescopes and mounts using the LX200 protocol are supported.
gcx uses
it's automatic field identification functions to refine telecope pointing
accuracy.
OPTIONS¶
When invoked without arguments, the program runs in GUI mode. Most functions are
also accessible through command line options, descibed below.
- -h, --help
- Print command line options.
- --help-all
- Print all the on-line help on stdout.
- --version
- Print program version.
- -D, --debug <level>
- Set debug level to <level>; 0=quiet, 4=noisy.
- -o, --output <file_name>
- Set output file name for import, convert and frame
operations.
- -r, --rcfile <config_file>
- Load configuration file.
- -S, --set <option>=<value>
- Set the value of an option overriding the configuration
file.
- -i, --interactive
- Force display frames as they are being processed.
Observation Scripting, Photometry and File Conversion
Options¶
- -p, --recipe <recipe_file>
- Load recipe file (searches rcp_path).
- -P, --phot-run <recipe_file>
- Load recipe file and run photometry in batch mode. Report
in native format.
- -V, --phot-run-aavso <recipe_file>
- Load recipe file and run photometry in batch mode. Report
in AAVSO format.
If <recipe_file> is set to one of the following three special tokens, the
recipe will change depeding on information in the frame header:
- _TYHCO_
- will create a recipe on-the-fly from Tycho catalog data (if
available);
- _OBJECT_
- will search the recipe path for a file with the same name
as the object in the frame (ending in .rcp);
- _AUTO_
- will search for a recipe by object name, and if that is not
found, create a tycho one.
- --import <catalog name>
- Convert a tabular catalog file to the gcx Lisp-like format.
Reads stdin. Current table formats are: gcvs, gcvs-pos, landolt,
henden, sumner.
- --merge <recipe_file>
- Merge a new recipe file over the one loaded with the
--recipe option. Checks are made for either positional or name
duplicates. Only stars brighter than mag_limit are merged.
- --set-target
- Specify a target object to be merged into a recipe file. It
will also set the recipe object, ra and dec fields.
- --make-tycho-rcp <radius>
- Create a recipe file for the object specified with
--object using tycho2 stars in a box radius arcminutes
around the object.
- --rcp-to-aavso <recipe_file>
- Convert a recipe file to the aavso db (tab-delimited)
format. If the file argument is '-', stdin is read. The recipe
comment and star comment fields are interpreted to get some db fields. See
the --help-all output for more info.
- -T, --rep-to-table <report_file>
- Convert a report file to tabular format. If an output file
name is not specified (with the '-o' argument), stdout is used. If
the file argument is '-', stdin is read. The format of the table is
specified by the value of the .file.tab_format option, see
below.
- -O, --obsfile <obs_file>
- Load/run observation scripting file (searches
obs_path).
- -n, --to-pnm
- Convert a fits file to 8-bit pnm. If an output file name is
not specified (with the '-o' argument), stdout is used.
- -j, --object
- Specify a target object (useful for setting an initial wcs
when there isn't enough information present in the fits headers).
- --mag-limit
- Set a magnitude limit for the output of import and merge
commands.
CCD Reduction Options¶
- -d, --dark <dark_frame>
- Set the dark frame / do dark subtraction.
- -b, --bias <bias_frame>
- Set the bias frame / do bias subtraction.
- -f, --flat <flat_frame>
- Set the flat field frame / flatfield.
- -G, --gaussian-blur <fwhm>
- Set blur FWHM / apply Gaussian blur.
- -a, --align <align_ref_frame>
- Set the alignment reference frame / align frames.
- -A, --add-bias <bias>
- Set the value of a constant bias to add to all frames / add
a bias to frames.
- -M, --multiply <multiplier>
- Set a constant to multiply all frames with / multiply
frames by a scalar.
Multiplication is performed before addition.
- -u, --update-file
- Save reduction results overwriting the original files.
- -s, --stack
- Stack the frames using the method set in the configration
file; for some methods additive background alignment is performed.
- -F, --superflat
- Stack the frames using an multiplicative background
alignment procedure; the frames should be already dark-substracted.
- -N, --no-reduce
- Do not run the reduction operations, just load the frame
list / reduction options.
When any of the CCD reduction options is set and the
-i flag is not
specified, the reduction operations are run in batch mode on all the supplied
fits files. When no output file is specified or
-i is set, the files
are loaded into the batch processing file list, the reduction options set in
the dialog, and the program starts up in gui mode
The report converter option converts the native gcx output to a fixed-width
tabular format that is easy to import in other programs for further
processing. The table's format is defined by the
.file.tab_format
configuration option. The option string consists of tokens separated by
spaces. There are two types of tokens: option tokens, and column tokens.
Options tokens set global table options when present. They can appear anywhere
in the format string.
- tablehead
- Generate a table header line containing the column
titles.
- collist
- Generate a list of columns with position information at the
start of the output.
- res_stats
- Generate a line with descriptive statistics on the stars'
residuals at the end of each frame.
Column tokens specify what information gets output in each column. The first
column token corresponds to the first output column, and so on in order. Each
column token can optionally be followed by a specifier of the form:
width.precision. The width excludes a single character spacer between the
columns. Supported colum tokens are:
- name [w]
- Output the star's designator.
- ra [w]
- Output the right ascension in h:m:s format.
- dra [w.p]
- Output the right ascension in decimal degrees format.
- dec [w]
- Output the declination in d:m:s format.
- ddec [w.p]
- Output the declination in decimal degrees format.
- smag [w.p] <band>
- Output the standard magnitude with the given name.
- serr [w.p] <band>
- Output the error of the standard magnitude with the given
name.
- imag [w.p] <band>
- Output the instrumental magnitude with the given name.
- ierr [w.p] <band>
- Output the error of the instrumental magnitude with the
given name.
- flags [w]
- Output reduction flags and the star type.
- observation [w]
- Output the name of the observation (a synthetic name that
can be used to group stars reduced from the same frame.
- airmass [w.p]
- Output the airmass of the observation.
- jdate [w.p]
- Output the Julian date of the observation.
- mjd [w.p]
- Output the modified Julian date of the observation.
- filter [w]
- Output the filter name used for the observation.
- xc/yc [w.p]
- Output the frame coordintes of the star's centroid.
- xerr/yerr [w.p]
- Output the estimated centroiding errors.
- dx/dy [w.p]
- Output the amount the star was moved from it's catalog
position when the measuring aperture was centered.
- residual [w.p]
- Output the star's residual in the ensemble solution.
- stderr [w.p]
- Output the star's standard error (residual divided by the
estimated error).
Fields for which data is not available are left blank.
Image Navigation and Object Selection¶
- Middle click or space bar
- Pan cursor.
- '='
- Zoom in around cursor.
- '-'
- Zoom out.
- Left button drag left/right
- Adjust brightness.
- Left button drag up/down
- Adjust contrast,
- 0
- Auto scale intensity.
- 9
- Scale Min-Max.
- 1-8
- Auto scale with different intensity spans 1 is sharpest, 8
is dullest.
- Left click on an object
- Select object (and deselect all others).
- Shift-left click on an object
- Add to selection.
- Ctrl-left click on a star image
- Mark star (if not too faint).
- Left click on image
- Show local image statistics.
- Right click on image
- Pop-up the main menu.
- Right click on an object
- Pop-up the star menu.
Many useful commands have keyboard accelerators; they are displayed in the
menus.
FILES¶
The native image file format of gcx is FITS. The program will read 16-bit
integer and 32-bit float files (BITPIX = 16 or BITPIX = -32), and save 16-bit
integer files. The internal representation of images is in 32-bit floating
point.
gcx supports transparent compression and decompression of fits files when
zcat and
gzip are available and their path is set in the
corresponding options.
Configuration options are stored in
~/.gcxrc. The options can be edited
in GUI mode, or directly in the file itself. A template configuration file can
be created by selecting "save" in the option editing dialog.
The program reads several object catalog formats. See the relevant chapter in
the User's manual for information on how to set up catalogs. Catalogs are
normally placed under
/usr/share/gcx/catalogs.
Documentation files usually reside in the "docs" directory of the
source distribution or in
/usr/share/doc/gcx.
Example data is distributed separately from the main source. When installed from
a package it usually goes to
/usr/share/doc/gcx/examples.
SEE ALSO¶
GCX User´s Manual; gnuplot(1);
gzip(1);
zcat(1);
README.vizquery.
AUTHOR¶
gcx was written by Radu Corlan, with valuable contributions from
Alexandru Dan Corlan (Tycho2 searching, porting of GSC searching code); Liam
Girdwood (various routines from the libnova library); Pertti Paakkonen (GUI
improvements). The star search algorithm is similar to (and inspired by) the
one in Elwood Downey's XEphem. WCS conversion routines are taked from classic
AIPS. The GSC scanning routines are adapted from the code distributed with the
catalog.