catdata.txt
catdata.txt — Plain Text, 10 KB (10724 bytes)
File contents
! Catalog data file -- example and explanation ! Any line beginning with the ! character is a comment # So is any line beginning with the # character ! And, anything in a line starting with ! or # is commentary. ! ! The FIRST character in a line is treated specially, it ! identifies the type of object. A @ character denotes an ! observed object, and a * character denotes a reference ! or position alignment star. ! ! Fields within a line are separated by "whitespace" which is ! any number of contiguous spaces or tabs. This means that no ! field can contain any space or tab character! ! ! There are 3 required fields immediately following the initial ! character in a line: name, right ascension, declination ! ! All fields following the [name, right ascension, declination] set ! are optional. If they are not present, default values are used. ! These optional fields are described below. ! ! Any characters starting with the first ! or # following the first ! character in the line, and continuing to the end of the line are ! an in-line comment. Such a comment is associated with the object, ! and is repeated at the end of the object line associated with that ! object in other files generated by the software system, such as ! the .SMF, .obw and .obx files. Anything associated with the object ! may be put in such a comment and passed through the software system. ! (NOTE that this is a release 2.08 feature) ! ! Often, one begins the file with some comments indicating what the ! object list is for, how it was made, other files which it may be ! used with, the center position to be used in the .obs file, ! and any other things which might be needed later. ! # This is a test file with no scientific purpose # center about 2.50 -0.000 ! ! We will need at least a few reference stars: *ref1 02:30:38 0:11:32 *ref2 02:29:22 0:11:31 *ref3 02:29:21 -0:11:16 ! ! The right ascension is in hours, and declination in degrees. ! We can use colons to separate hours:minutes:seconds and ! degrees:minutes:seconds. These sub-fields may also have ! decimal fractions within them. Or, we can have decimal hours ! and decimal degrees. The program is smart enough to mix ! these, as long as there are no spaces in the field. ! *ref4 02.499850 -0.165235 *ref5 02.501323 -0:00:12.44 ! ! If your list has right ascension in degrees, that can be used, ! but all positions in the file must be done in the same way, with ! all the right ascensions in degrees. To do that, put a line at the ! start of the file (at least before any data) which has starting in ! the first column, "&RADEGREE" - less the quotes, of course. The ! special character & is used for advanced features. ! ! If your list has right ascension in degrees, it can be used, by ! adding a special line before those objects: &RADEGREE *ref6 37.50443 -0.01153 ! and lines following it have the right ascension in degrees ! rather than the usual hours. If later objects, or files, will ! be in hours scale, use the special line &RAHOUR ! which will cause reading to take positions as hours again. ! If you mix several files with some using degrees and others ! using hours, put the correct special line at the start of ! each file to get things right. ! ! When positions are written to .obw, .obx or .SMF files, the ! right ascensions will always be in hours, the default scale, ! even if the object input for those positions was degrees. ! ! Now, we need to add some objects which are potentially to be ! observed. Following the position, we can add the first optional ! field, a priority. ! @ob002 02:30:02 -0:01:12 -2.0 @ob003 02:29:37 -0:03:13 5.0 @ob004 02:30:30 +0:05:01 Pri=6.2 ! ! The @ character denotes an observed object. We can use a + sign ! on the declination, or leave it off. The priority is a decimal ! number, and operates sorta like magnitudes, with numerically smaller ! values denoting the more important objects; a first priority object ! is more desirable than a second priority object and a priority 1.0 ! will be used instead of a 2.0 if they conflict and other things ! are equal. If priority is omitted, a default value is assigned. ! ! The object ob002 above has a negative priority, so it must be very ! important indeed. A sufficiently negative priority may be used to ! indicate a "must have" object which will not be removed from the ! data even if it conflicts with another object or reference star. ! ! NOTE -- Keyword input format documented here is a new feature ! of software release 2.08 and later. ! It DOES NOT WORK on release 2.07 and former programs. ! ! The priority of the "ob004" object is given by a keyword, and ! all output files from release 2.08 will take this input, and ! also produce output files using the keyword form. Files in the ! older positional (non-keyword) form will also be accepted. ! In any object line, any legacy positional parameters must precede ! any keyword parameters. Keyword parameters may be in any order, ! and the keywords themselves are read in a case-independent manner. ! ! The use count field is written by the maskgen program in a file ! with the object catalog format to allow creation of multiple masks ! for a single position and catalog set. It looks somewhat like this: ! @ob005 02:30:21.435 -0:08:16.22 Pri=12.33 @ob006 02:30:21.437 -0:08:21.03 Pri=10.11 Use=1 ! ! The above shows that ob006 was used in a mask, and ob005 was not. ! ! The default use count is zero, and will be omitted in the output ! if it is zero. ! ! Here are the keyword parameters currently available: ! ! Pri Priority, as a floating point value ! Use Use count, an integer ! Width Slit width, arc seconds ! Shape Slit shape, an integer or name (see below) ! Alen Slit length, arc seconds in slit position direction ! Blen Slit length, arc seconds in the other direction ! Tilt Slit tilt, in degrees, counterclockwise from dispersion normal ! PA Slit Position Angle, from North toward East, on sky. ! ! These keywords are case independent, and currently only the first two ! characters of each keyword are needed. The keyword is separated from ! its value by the "=" sign, and no spaces are allowed within the ! keyword=value item. If any new keywords are added, they will be ! documented here. ! ! The use count is written in the .obw file for each object which is used ! in a mask, and increments its previous value. ! ! The shapes allowed are: 0 = Circle, 1 = Square, 2 = Rectangle ! For the first two, only a width is defined, for the rectangle the ! alen and blen are lengths with respect to the "object" position. ! For the symmetric shapes, the object is always in the center. ! Reference objects are always square. ! Other objects are by default rectangle (slit) shape, but may be ! set to circle or square as needed; use the "shape" pulldown in ! intgui to set "slit" (rectangle), "hole" (circle) or "box" (square). ! The shape=xxx keyword=value pair will also recognize the names ! "circle" (or "hole"), "square" (or "box") and "rectangle" (or "slit") ! in addition to the integers. Those names are case-insensitive, and ! may be abbreviated to the first 2 characters. (Release 2.09+ only). ! ! Slits are by default at a tilt of zero degrees, and are normal to ! the dispersion direction. The slit orientation on the sky is a ! parameter of the observation (in the intgui window) and selects the ! dispersion direction which is in the .obs file. The tilt parameter ! allows the slit to be tilted with respect to this default. The ! positive tilt is counter-clockwise on the sky, corresponding to an ! increase in sky position angle. ! ! The default values for slit width, shape, alen, blen and tilt are ! all set in the .obs file by inputs in the intgui program. There is ! no intgui window for tilt, but it can be edited into the .obs file, ! see the "faq.txt" file for how to do this. ! ! The PA parameter is another way to specify a tilted slit, and instead ! of being relative to the instrument position angle in the .obs file, ! it is the actual position angle desired for the slit on the sky, ! measured in degrees from North toward East. The Position Angle should ! not be zero or negative, use values from 0.01 through 360.0; this ! range is not (yet) enforced by the reading program. ! Some examples: ! @ob007 2:29:55.855 -0:02:22.44 Pri=3 width=0.75 alen=4.5 blen=3.5 @ob031 2:30:12.664 0:05:14.32 Pri=-8 alen=18.5 blen=17 pa=46.35 @ob008 2:29:53.766 -0:05:33.80 pr=9 blen=6 alen=6 @ob009 2.499873 -0.12765 width=0.8 pri=9 # Magnitude 10.7 @ob654 2:30:15.678 0:07:12.32 7.5 0.58 2 5.0 5.0 pa=38.6 ! Double star ! ! Here object "ob007" requires a non-standard slit width, and the ! slit lengths are also non-standard. Object "ob031" has a very ! high priority (decimal point is optional), is longer than the ! others, and needs to be oriented with the sky position angle ! of 46.35 degrees. Object "ob008" has a "low" priority (note that ! the keyword can be abbreviated "pr" to 2 letters) and also has ! non-default slit lengths. Object "ob009" has probably been entered ! from another list as R.A. and Dec. are in decimal hours and degrees, ! and we want a non-standard slit width for it. ! Object "ob654" is an ancient entry from an old file in which the ! data is in positional form, it should be written as: @ob654 2:30:15.678 0:07:12.32 pri=7.5 wid=0.58 alen=5 blen=5 pa=38.6 ! but the program is smart enough to read the older data that it ! could read before and put the values in the right places. Note ! that a position angle was added at the end. Keyword parameters may ! follow legacy positional parameters, but no positional parameter ! can follow a keyword. And comments must come last in the line. ! Object lines can be up to 1000 characters long in release 2.08. ! ! Also, if a keyword is repeated, or both tilt and PA are given, the ! last one processed in the line (left to right) is the value used. ! ! As previously stated, keyword parameters may be in any order, and ! the keywords themselves are not case sensitive. ! ! If you have older data in positional format, the values were read ! in this order: ! Priority, use count (if no decimal point), slit width (with decimal), ! shape integer, A-len, B-len, tilt. ! This is now obsolete, but older files will be read correctly until ! further improvements would create a conflict. ! ! ! That's all there is to it. Naturally, a real object catalog file ! would have many (perhaps thousands) of objects in it, and relatively ! few comments. You can put in as many as you want (the sky's the ! limit), and multiple object catalog files may be used. They are all ! combined into a single list in the program. !