path: root/pkg/images/imcoords/doc/ccget.hlp

.help ccget Oct00 images.imcoords
.ih
NAME
ccget -- extract objects in a user specified field from a text file catalog
.ih
USAGE
ccget input output lngcenter latcenter lngwidth latwidth
.ih
PARAMETERS
.ls input
The input text file catalog(s). The text file columns must be
delimited by whitespace and all the input catalogs must have the same format.
.le
.ls output
The output catalogs containing the extracted objects. The number of
output catalogs must be one or equal to the number of input catalogs.
.le
.ls lngcenter, latcenter
The center of the field containing the objects to be extracted. Lngcenter and
latcenter are assumed to be in the coordinate system specified by
\fIfcsystem\fR, e.g. ra and dec for equatorial systems, galactic longitude and
latitude for galactic systems, etc. and in the units specified by
\fIfclngunits\fR and \fIlatunits\fR.
.le
.ls lngwidth, latwidth
The width of the user specified field in degrees.
.le
.ls fcsystem = ""
The celestial coordinate system of the field center. If undefined fcsystem
defaults to the catalog celestial coordinate system specified by
\fIcatsystem\fR. The two systems of
most interest to users are "j2000" and "b1950". The full set of options is:

.ls equinox [epoch]
The equatorial mean place post-IAU 1976 (FK5) system if equinox is a
Julian epoch, e.g. J2000.0 or 2000.0, or the equatorial mean place
pre-IAU 1976 system (FK4) if equinox is a Besselian epoch, e.g. B1950.0
or 1950.0. Julian equinoxes are prefixed by a J or j, Besselian equinoxes
by a B or b. Equinoxes without the J / j or B / b prefix are treated as
Besselian epochs if they are < 1984.0, Julian epochs if they are >= 1984.0.
Epoch is the epoch of the observation and may be a Julian
epoch, a Besselian epoch, or a Julian date. Julian epochs
are prefixed by a J or j, Besselian epochs by a B or b.
Epochs without the J / j or B / b prefix default to the epoch type of
equinox if the epoch value <= 3000.0, otherwise epoch is interpreted as
a Julian date.  If undefined epoch defaults to equinox.
.le
.ls fk5 [equinox] [epoch]
The equatorial mean place post-IAU 1976 (FK5) system where equinox is
a Julian or Besselian epoch e.g. J2000.0  or B1980.0.
Equinoxes without the J / j or B / b prefix are treated as Julian epochs.
The default value of equinox is J2000.0.
Epoch is a Besselian epoch, a Julian epoch, or a Julian date.
Julian epochs are prefixed by a J or j, Besselian epochs by a B or b.
Epochs without the J / j or B / b prefix default to Julian epochs
if the epoch value <= 3000.0, otherwise epoch is interpreted as
a Julian date.  If undefined epoch defaults to equinox.
.le
.ls fk4 [equinox] [epoch]
The equatorial mean place pre-IAU 1976 (FK4) system where equinox is a
Besselian or Julian epoch e.g. B1950.0  or J2000.0,
and epoch is the Besselian epoch, the Julian epoch, or the Julian date of the
observation.
Equinoxes without the J / j or B / b prefix are treated
as Besselian epochs. The default value of equinox is B1950.0. Epoch
is a Besselian epoch, a Julian epoch, or a Julian date.
Julian epochs are prefixed by a J or j, Besselian epochs by a B or b.
Epochs without the J / j or B / b prefix default to Besselian epochs
if the epoch value <= 3000.0, otherwise epoch is interpreted as
a Julian date.  If undefined epoch defaults to equinox.
.le
.ls noefk4 [equinox] [epoch]
The equatorial mean place pre-IAU 1976 (FK4) system but without the E-terms
where equinox is a Besselian or Julian epoch e.g. B1950.0 or J2000.0,
and epoch is the Besselian epoch, the Julian epoch, or the Julian date of the
observation.
Equinoxes without the J / j or B / b prefix are treated
as Besselian epochs. The default value of equinox is B1950.0.
Epoch is a Besselian epoch, a Julian epoch, or a Julian date.
Julian epochs are prefixed by a J or j, Besselian epochs by a B or b.
Epochs without the J / j or B / b prefix default to Besselian epochs
if the epoch value <= 3000.0, otherwise epoch is interpreted as
a Julian day.  If undefined epoch defaults to equinox.
.le
.ls apparent epoch
The equatorial geocentric apparent place post-IAU 1976 system where
epoch is the epoch of observation.
Epoch is a Besselian epoch, a Julian epoch or a Julian date.
Julian epochs are prefixed by a J or j, Besselian epochs by a B or b.
Epochs without the J / j or B / b prefix default to Besselian
epochs if the epoch value < 1984.0, Julian epochs
if the epoch value <= 3000.0, otherwise epoch is interpreted as
a Julian date.
.le
.ls ecliptic epoch
The ecliptic coordinate system where epoch is the epoch of observation.
Epoch is a Besselian epoch, a Julian epoch, or a Julian date.
Julian epochs are prefixed by a J or j, Besselian epochs by a B or b.
Epochs without the J / j or B / b prefix default to Besselian epochs
if the epoch values < 1984.0, Julian epochs
if the epoch value <= 3000.0, otherwise epoch is interpreted as
a Julian day.
.le
.ls galactic [epoch]
The IAU 1958 galactic coordinate system.
Epoch is a Besselian epoch, a Julian epoch or a Julian date.
Julian epochs are prefixed by a J or j, Besselian epochs by a B or b.
Epochs without the J / j or B / b prefix default to Besselian
epochs if the epoch value < 1984.0, Julian epochs
if the epoch value <= 3000.0, otherwise epoch is interpreted as
a Julian date. The default value of epoch is B1950.0.
.le
.ls supergalactic [epoch]
The deVaucouleurs supergalactic coordinate system.
Epoch is a Besselian epoch, a Julian epoch or a Julian date.
Julian epochs are prefixed by a J or j, Besselian epochs by a B or b.
Epochs without the J / j or B / b prefix default to Besselian
epochs if the epoch value < 1984.0, Julian epochs
if the epoch value <= 3000.0, otherwise epoch is interpreted as
a Julian date. The default value of epoch is B1950.0.
.le

In all the above cases fields in [] are optional with the defaults as
described. The epoch field for the fk5, galactic, and supergalactic
coordinate systems is only used if the input coordinates are in the
equatorial fk4, noefk4, or fk5 systems and proper motions are supplied.
Since ccget does not currently support proper motions these fields are
not required.
.le

.ls fclngunits = "", fclatunits = ""
The units of the field center coordinates. The options are "hours", "degrees",
and "radians" for the ra / longitude coordinate and "degrees" and "radians"
for the dec / latitude coordinates. If fclngunits and fclatunits are undefined
they default to the preferred units for the given system, e.g. "hours" and
degrees" for equatorial systems and "degrees" and "degrees" for ecliptic,
galactic, and supergalactic systems.
.le
.ls colaliases = ""
The list of input catalog column aliases separated by commas. By default the
catalog columns are "c1", "c2", "c10", etc. If colaliases is defined then
the aliases are assigned to the columns in order. For example if colaliases
is "id,ra,dec,v,bv" then columns c1, c2, c3, c4, c5 will be assigned
the names id, ra, dec, v, and bv and any remaining columns in the input catalog
file will be assigned default names beginning with c6.
.le
.ls lngcolumn = "c2", latcolumn = "c3"
The input catalog columns containing the coordinates of catalog objects.
.le
.ls catsystem = "j2000"
The celestial coordinate system of the input catalog(s). The two systems of
most interest to users are "j2000" and "b1950". The full set of options is
described in the \fIfcsystem\fR parameter section.
.le
.ls catlngunits = "", catlatunits = ""
The units of the catalog coordinates. The options are "hours", "degrees",
and "radians" for the ra / longitude coordinate and "degrees" and "radians"
for the dec / latitude coordinates. If catlngunits and catlatunits are undefined
they default to the preferred units for the catalog system, e.g. "hours" and
degrees" for equatorial systems and "degrees" and "degrees" for ecliptic,
galactic, and supergalactic systems.
.le
.ls outsystem = ""
The celestial coordinate system of the output coordinates. If undefined
outsystem defaults to the celestial coordinate system of the catalog.
The two systems of most interest to users are "j2000" and "b1950". The
full set of options is described under the \fIfcsystem\fR parameter
section.
.le
.ls olngunits = "", olatunits = ""
The units of the output coordinates. The options are "hours", "degrees",
and "radians" for the ra / longitude coordinate and "degrees" and "radians"
for the dec / latitude coordinates. If olngunits and olatunits are undefined
they default to the preferred units for outsystem, e.g. "hours" and degrees" for
equatorial systems and "degrees" and "degrees" for ecliptic, galactic, and
supergalactic systems.
.le
.ls olngformat = "", olatformat=""
The output ra / longitude and dec / latitude formats if the output
celestial coordinate system is different from the catalog celestial
coordinate system. The defaults are "  %010.1h" for hours, "  %9h" for degrees
and "  %9.7g" for radians.
.le
.ls exprs = "c[*]"
The list of output columns and column expressions separated by commas.
By default the entire record for the extracted object is output exactly
as it is. The output columns can be individual columns e.g. c1 or c5
or column ranges, e.g. c[1-10] or c[2-4]. Column expressions are
expressions of the catalog columns, e.g c4 + c5.  Columns and column
expression are output in the order in which they appear in exprs.
.le
.ls formats = ""
An optional list of column formats separated by commas. Column formats must
be placeholders, e.g. the letter f for existing columns which are not
reformatted (with the possible exception of the coordinate columns).
Column expression formats may be any regular formatting expression.
For example if \fIexprs\fR is "c[1-3],c4+c5,c5+c7", then formats might be
"f,%7.3f,%7.3f".
.le
.ls verbose = yes
Print messages on the standard output about actions taken by the task.
.le

.ih
DESCRIPTION

Ccget extracts objects in a user specified field from the input catalogs
\fIinput\fR and writes the extracted records to the output
catalogs \fIoutput\fR.

The user field is specified by the parameters \fIlngcenter\fR, \fIlatcenter\fR,
\fIlngwidth\fR, and \fIlatwidth\fR, where the field center is entered in
the celestial coordinate system specified by \fIfcsystem\fR and the
units are specified by \fIfclngunits\fR and \fIfclatunits\fR. If fcsystem
is undefined it defaults to the value of the catalog coordinate system
\fIcatsystem\fR.

The input catalogs must be text files containing 2 or more columns separated
by whitespace. By default these columns are assigned names of the form
c1, c2, ..., cn. Legal columns names must have the form described
in the following column names section. Users may assign their own names
to the columns by setting
the \fIcolaliases\fR parameter. The input catalog columns \fIlngcolumn\fR and
\fIlatcolumn\fR must contain the ra / longitude and dec / latitude coordinates
of the catalog objects respectively. The parameters \fIcatsystem\fR,
\fIcatlngunits\fR, and \fIcatlatunits\fR specify the coordinate system
of the input catalog and its coordinate units respectively.

At task startup the user field center is transformed from the coordinate
system defined by \fIfcsystem\fR to the catalog coordinate system
\fIcatsystem\fR and the ra / longitude and dec / latitude limits of the
user field are computed. As each input catalog record is read, the catalog
coordinates are decoded and tested against these limits. If the 
object is inside the user field then the column and column
expressions specified by \fIexprs\fR are extracted from the input catalogs
and written to the output catalogs.

If the output celestial coordinate system \fIoutsystem\fR is
different from \fIcatsystem\fR, then the catalog coordinates are transformed
and to the output coordinates system, and written to the output catalog
in the units specified
by \fIolngunits\fR and \fIolatunits\fR, with the formats specified by
\fIolngformat\fR and \fIolatformat\fR. Existing columns are written to
the output catalog in the same
format they have in the input catalog. Column expressions are written
using the formats specified by \fIformats\fR or the builtin defaults
of %5b, %10d, %10g, or %s for boolean, integer, floating point, or
string columns  respectively.

.ih
COLUMN NAMES

By default column names are of the form c1, c2, ..., cN. However users can
also define their own column names, which must have the following syntax

.nf
	{a-zA-Z}[{a-zA-Z0-9._$}]*
.fi

where [] indicates optional, {} indicates a class, - indicates an ascii
range of characters, and * indicates zero or more occurrences. In words
a column name must begin with an alphabetic character and be followed
by any combination of alphabetic, digit, or '.', '_', and '$' characters.
The ccget task imposes a 19 character limit on the columns names so it is
best to keep them short.

.ih
COLUMN EXPRESSIONS

Expressions must consist of operands and operators. The operands may be
column names, numeric constants, functions, and quoted string constants.
Values given as sexagesimal strings are automatically converted to
decimal numbers. The operators are arithmetic, logical, and string.

The following operators are supported:

    
.nf
            +  -  *  /              arithmetic operators
            **                      exponentiation
            //                      string concatenation
            !  -                    boolean not, unary negation
            <  <= >  >=             order comparison (works for strings)
            == != && ||             equals, not equals, and, or
            ?=                      string equals pattern
            ? :                     conditional expression
.fi

The following intrinsic functions are supported:

    
.nf
            abs     atan2   deg     log     min     real    sqrt
            acos    bool    double  log10   mod     short   str
            asin    cos     exp     long    nint    sin     tan
            atan    cosh    int     max     rad     sinh    tanh
.fi

    
.ih
COLUMN FORMATS

A  format  specification has the form "%w.dCn", where w is the field
width, d is the number of decimal places or the number of digits  of
precision,  C  is  the  format  code,  and  n is radix character for
format code "r" only.  The w and d fields are optional.  The  format
codes C are as follows:

.nf
b       boolean (YES or NO)
c       single character (c or '\c' or '\0nnn')
d       decimal integer
e       exponential format (D specifies the precision)
f       fixed format (D specifies the number of decimal places)
g       general format (D specifies the precision)
h       hms format (hh:mm:ss.ss, D = no. decimal places)
m       minutes, seconds (or hours, minutes) (mm:ss.ss)
o       octal integer
rN      convert integer in any radix N
s       string (D field specifies max chars to print)
t       advance To column given as field W
u       unsigned decimal integer
w       output the number of spaces given by field W
x       hexadecimal integer
z       complex format (r,r) (D = precision)


Conventions for w (field width) specification:

    W =  n      right justify in field of N characters, blank fill
        -n      left justify in field of N characters, blank fill
        0n      zero fill at left (only if right justified)
absent, 0       use as much space as needed (D field sets precision)


Escape sequences (e.g. "\n" for newline):

\b      backspace   (not implemented)
\f      formfeed
\n      newline (crlf)
\r      carriage return
\t      tab
\"      string delimiter character
\'      character constant delimiter character
\\      backslash character
\nnn    octal value of character

Examples

%s          format a string using as much space as required
%-10s       left justify a string in a field of 10 characters
%-10.10s    left justify and truncate a string in a field of 10 characters
%10s        right justify a string in a field of 10 characters
%10.10s     right justify and truncate a string in a field of 10 characters

%7.3f       print a real number right justified in floating point format
%-7.3f      same as above but left justified
%15.7e      print a real number right justified in exponential format
%-15.7e     same as above but left justified
%12.5g      print a real number right justified in general format
%-12.5g     same as above but left justified

%h          format as nn:nn:nn.n
%15h        right justify nn:nn:nn.n in field of 15 characters
%-15h       left justify nn:nn:nn.n in a field of 15 characters
%12.2h      right justify nn:nn:nn.nn
%-12.2h     left justify nn:nn:nn.nn

%H          / by 15 and format as nn:nn:nn.n
%15H        / by 15 and right justify nn:nn:nn.n in field of 15 characters
%-15H       / by 15 and left justify nn:nn:nn.n in field of 15 characters
%12.2H      / by 15 and right justify nn:nn:nn.nn
%-12.2H     / by 15 and left justify nn:nn:nn.nn

\n          insert a newline
.fi

.ih
SOME BUILTIN CATALOG FORMATS

The nlandolt.dat catalog in noao$photcal/catalogs/ has the following format.

.nf
# Column     Quantity 

       1           id
       2           ra
       3          dec
       4            v
       5          b-v
       6          u-b
       7          v-r
       8          r-i
       9          v-i
      10            n   
      11            m 
      12       err(v)
      13     err(b-v)
      14     err(u-b)
      15     err(v-r)
      16     err(r-i)
      17     err(v-i)
.fi

where the coordinates are in j2000, the errors are all mean errors of the mean,
and n and m are the number of observations and number of independent nights
of observations respectively.

.ih
REFERENCES

The catalog references are

.nf
nlandolt.dat - Landolt, A.U. 1992, A.J. 104, 340
.fi

.ih
EXAMPLES

Example 1. Extract all Landolt standard stars within a 1 degree field
surrounding the position ra = 3:55:00 dec = 0:00:00 (J2000).

.nf
cl> ccget nlandolt.dat output 03:55:00.0 0:00:00 1.0 1.0
.fi

Example 2. Repeat example 1 but output the coordinates in the b1950
celestial coordinate system.

.nf
cl> ccget nlandolt.dat output 03:55:00.0 0:00:00 1.0 1.0 \
outsystem=b1950
.fi

Example 3. Repeat example 1 but extract only the id, ra, dec, v, 
and b-v fields from the Landolt catalog.  Note that since these
columns are the first five in the catalog they can be specified
as a range.

.nf
cl> ccget nlandolt.dat output 03:55:00.0 0:00:00 1.0 1.0 \
exprs="c[1-5]"
.fi

Example 4. Repeat example 1 but extract the id, ra, dec, b and
b-r colors. Note that b and b-r are not columns in the input catalog
but may be computed from them. Note also that formats should be
specified to give the desired spacing, although defaults will be
supplied.

.nf
cl> ccget nlandolt.dat output 03:55:00.0 0:00:00 1.0 1.0 \
exprs="c[1-3],c4+c5,c5+c7" formats="%7.3f,%7.3f
.fi

.ih
TIME REQUIREMENTS
.ih
BUGS
.ih
SEE ALSO
.endhelp