diff options
Diffstat (limited to 'pkg/images/imcoords/doc/ccget.hlp')
| -rw-r--r-- | pkg/images/imcoords/doc/ccget.hlp | 463 |
1 files changed, 463 insertions, 0 deletions
diff --git a/pkg/images/imcoords/doc/ccget.hlp b/pkg/images/imcoords/doc/ccget.hlp new file mode 100644 index 00000000..fef9afba --- /dev/null +++ b/pkg/images/imcoords/doc/ccget.hlp @@ -0,0 +1,463 @@ +.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 |