Документ взят из кэша поисковой машины. Адрес оригинального документа : http://www.atnf.csiro.au/computing/software/gipsy/tsk/gds2text.dc1 Дата изменения: Thu Apr 19 08:19:02 2001 Дата индексирования: Fri Jan 16 20:39:16 2009 Кодировка: Поисковые слова: m 63

Program: GDS2TEXT

Purpose: Put GDS image data in ASCII file and vv. Use a format
for the numbers. Add (physical coordinates) to the data
if in 'export' mode.

Category: UTILITY

File: gds2text.c

Author: M. Vogelaar

Keywords:

EXPORTFILE= Name of export ASCII file: [switch to read mode]

If a name is specified, an ASCII file is created to
store data from INSET=. If you press carriage return,
the program switches to read mode and will ask for
IMPORTFILE= If a given name already exists, FILESTAT=
must be specified.


FILESTAT= File exists, Overwrite, Append or New name? [O]/A/N

The file specified in EXPORTFILE= already exists.
Choose one og the following options.
O: Default, overwrite this file
A: Append to the existing file.
N: Prompt with EXPORTFILE= again to give another name.


IMPORTFILE= Name of import ASCII file: [stop program]

Specify the name of an ASCII file with data
to fill the image of INSET=
The data must be arranged in one column, the first
column of the ASCII file.


INSET= Give set, subsets:

Maximum number of subsets is 4096.
The set is either a set from which the data is
extracted (EXPORTFILE= is used) or a set to which ASCII
data is written (IMPORTFILE= is used).


BOX= Give box in ..... [entire subset]

Either the box from which the data is extracted or the
box to which data is written.


POSFORM= Do you want to import data with positions? Y/[N]

This keyword is only asked when you are in the 'IMPORT'
mode. The ASCII file on disk has format:

x1, x2, ... xn, image-value

where n is the dimension of the (sub)set that you
specified with INSET=

!!! If you entered more than one subset, then only the
FIRST subset is processed !!!


SHEET= Do you want a spreadsheet output? Y/[N]

This keyword is only asked when you are in the 'EXPORT'
mode and selected a 2-dimensional (sub)set.
Put ASCII data in sheet format i.e the ASCII file has
rows and columns equal to the number of rows and columns
in the selected box (BOX=). Therefore the input must be
2-dimensional. Data is separated by a comma.
Example: (SHEET=Y, FORMAT=ffff.f)

-20.0 , -15.0 , -10.0 , -5.0 ..........
-16.0 , -12.0 , -8.0 , -4.0
-12.0 , -9.0 , -6.0 , -3.0
-8.0 , -6.0 , -4.0 , -2.0
16.0 , 12.0 , 8.0 , b
.
.
.
.

FORMAT= Give format for image data output: [Calculated]

This keyword is only asked when you are in the 'EXPORT'
mode.
Write numbers to ASCII file in a user given output
format. See description for possible formats.
(e.g. FORMAT=ffffff.ffff
FORMAT=ggggg.ggg
FORMAT=ddddd )


XYZFORM= Do you want output in 'X-Y-data' format? Y/[N]

This keyword is only asked when you are in the 'EXPORT'
mode and selected a 2-dimensional (sub)set but did
not want output in 'sheet' format.
For 2-dim subsets it is possible to write (besides the
image data) the positions in grid- or physical coordinates
of each pixel value, to a file. The format of the output
ASCII file is then:

X position, Y position, Image value.

Example contents of file 'num.txt':
(FORMAT=eeeeee.eeeeeeeeee TOPHYS=Y)

44.943470940588 44.959986063360 1.6000000000E+01
44.957603199423 44.959992163481 1.2000000000E+01
44.971735463416 44.959996520713 8.0000000000E+00
44.985867730848 44.959999135052 b
45.000000000000 44.960000006498 -0.0000000000E+00
45.014132269152 44.959999135052 -4.0000000000E+00


TOPHYS= Do you want x and y in physical coords.: Y/[N]

(Only asked if XYZFORM=Y)
The X and Y values can be converted to values in units
given by the header of the input set (e.g. DEGREE, KM/S).
You can use a program like HEADER or FIXHED to find
the coordinates of the (sub)set axes.


BLANK= Value to replace a blank: [do not replace]

A blank in the image can be replaced by another value,
so that the output file will not contain the text that
represents a blank value. Usually the text for a blank
is 'b'. This also the default.


** SKIPBLANK= Skip writing blanks in file: [NO]

If you want to create a file with data from a set and,
at the same time, you want to skip writing blanks in
that file, use SKIPBLANK=Y


Note: If you want to write data values and physical coordinates
for one dimensional (sub)sets use program PPLOT with
the FILENAME= keyword.


Description: In GDS (GIPSY Data System) an image is an array of
floating point numbers and a descriptor is a file which
describes how this data is arranged in size and dimensio-
nality. Sometimes you want to examine or process part of
the image with tools not available in GIPSY. The easiest
way to exchange data is that of an ASCII file.
With this program and some knowledge of size and
dimensionality of the your GIPSY set, it is possible to
write image values to an ASCII file (EXPORTFILE=) and to
read values from a text file (IMPORTFILE=) to store in
the GIPSY set. With INSET= you determine the axis order
of your subset and with BOX= you specify which part of
the selected subset is used for extracting or receiving
data. The FITS keywords in the descriptor describing
the size and structure are:
NAXIS specifies the number of coordinate axes in the
image.
NAXIS1 specifies the number of pixels along the most
rapidly varying axis within the image.
CTYPE1 type of physical coordinate along first axis
NAXIS2 specifies the number of pixels along the second
most rapidly varying axis within the image.
etc.

If the set AURORA has for example the axes

RA from -64 to 63
DEC from -64 to 63
FREQ from 1 to 32

then the subset INSET=AURORA FREQ 1 defines a plane
with the RA axis as most rapidly varying axis and the
DEC axis as second most rapidly varying axis. If you
give BOX=-10 -3 10 3 and EXPORTFILE=export.txt,
the data from set AURORA will be extracted in rows
from RA=-10 to RA=10 starting at DEC=-3 and ending at
DEC=3. The numbers will be stored in one column in
the text file 'export.txt' If you want to examine a
RA profile at certain DEC, you need to remember the
width of your box i.e. 10-(-10)+1=21

Blanks:

If your set data has blanks, then the export ASCII file
will contain the text equivalence of a blank. If you
entered a value for BLANK= then this value will be
substituted for each blank in the input set. If the
import ASCII file contains numbers that cannot be
converted to a float, then a blank is substituted in
INSET=.


READING IMAGE DATA FROM ASCII FILE WITH POSITION
INFORMATION:

The format of the ASCII file is:

x1, x2, ... xn, image-value

The vector x1, x2, ... xn defines one position in
an n-dimensional subset. So your INSET= specification
must also be a n-dimensional structure.

Example:

ASCII file on disk "data.txt" contains:

2 3 2 23.2
3 4 3 30.5
0 0 2 80.0
10 10 1 67.9

The positions are grids in RA, DEC and FREQ. The 4th
number is the image value that you want to write to
the 3-dim set AURORA.

gds2text
GDS2TEXT Version 1.0 (May 3 1996)
GDS2TEXT EXPORTFILE=
GDS2TEXT IMPORTFILE=data.txt
GDS2TEXT INSET=AURORA
Set AURORA has 3 axes
RA-NCP from -4 to 5
DEC from -4 to 5
FREQ-OHEL from 0 to 9
GDS2TEXT BOX=
BOX range for set AURORA :
RA-NCP from -4 to 5
DEC from -4 to 5
FREQ-OHEL from 0 to 9
GDS2TEXT POSFORM=y
Wrote 3 image value(s) with positions from ASCII file to set
Found 1 position(s) outside BOX=




CREATING AN INPUT FILE FOR A SPREADSHEET:

If a (sub)set is 2-dimensional, it is possible to
write to an ASCII file in a spreadsheet format.
A spreadsheet consists of rows and columns. The
entries in a row are separated by colons. The rows
are separated by a newline character. The entries
are formatted according the string given in
FORMAT= Possible formats for the numbers are described
below. Blank values can be replaced by a unique
value. If a number cannot be formatted, an asterisk is
returned.



CREATING A FILE IN FORMAT X, Y, Z:

If a (sub)set is 2-dimensional, it is possible to
write to an ASCII file in a special format.
Two integer numbers (X, Y of a position) are followed
by the corresponding image value. This option is disabled
if SHEET=Y.


Possible formats:

The specification in FORMAT= is called a 'format image'.
A 'format image' is used to print numbers in a user given
format consisting of characters representing the
wanted output format. The syntax is:

flag(s) Zero or more flags, in any order, which modify the
meaning of the conversion specification. The flag
characters and their meanings are:

- The result of the conversion is left-
justified within the field.

+ The result of a signed conversion always
begins with a sign, "+" or "-".

string Characters, some with special meaning.
If the string (f.i. FFFFF.FF or gggg.gg or wwwww)
contains no dot, the number of characters specify
a minimum field width. For an output field, if the
converted value has fewer characters than the field
width, it is padded on the left (or right, if the
left-adjustment flag, - has been given) to the field
width.
If the string contains a dot, the total number of
characters including the dot is the minimum field width
and the number of characters after the dot is the
precision.

The characters are used to determine the conversion
type. If the string contains an:

'e' or 'E'
The floating-point-number argument is
printed in the style [-]drddde+dd,
where there is one digit before the
radix character, and the number of
digits after it is equal to the
precision. The E conversion character
produces a number with E introducing
the exponent instead of e. The
exponent always contains at least two
digits. However, if the value to be
printed requires an exponent greater
than two digits, additional exponent
digits are printed as necessary.

'g' or 'G'

The floating-point-number argument is
printed in style f or e (or int style E
n the case of a G conversion
character), with the precision
specifying the number of significant
digits. The style used depends on the
value converted; style e is used only
if the exponent resulting from the
conversion is less than -4 or greater
than or equal to the precision.

others
Strings without 'e', 'E', 'g' and 'G'
indicate a floating point conversion.
The floating point number argument is
printed in decimal notation in the
style [-]dddrddd, where the number of
digits after the radix character, r, is
equal to the precision specification.

If the result of a conversion is longer than the
field width, an asterisk is returned. If the
input number is a blank, the character 'b' is returned.



Examples: Format string: +eeeeee.eeee
Number: 43345.5436
Result: +4.3346e+04
Remark: exponential format
signed conversion
field width: 12
precision: 4

Format string: gggg.ggggg
Number: 34.43
Result: 34.430
Remark: Field width is 10
Number of significant digits is 5

Format string: +ffff.ff
Number: 23.456
Result: +23.46
Remark: signed conversion

Format string: -ffff
Number: 345.87
Result: 346
Remark: left justified

Format string: -+ffff.fff
Number: 34.43
Result: +34.430
Remark: left justified
signed conversion

Format string: eee.eeee
Number: 234.43
Result: *
Remark: Field width too small
for conversion

Format string: ffff.ff
Number: blank
Result: b
Remark: input was a blank



Notes:

Example: gds2text
GDS2TEXT Version 1.0 (Jul 28 1992)
GDS2TEXT EXPORTFILE=
GDS2TEXT IMPORTFILE=hallo
GDS2TEXT INSET=hi1277 1
Set hi1277 has 3 axes
RA---NCP from -64 to 63
DEC--NCP from -64 to 63
PARAM-SUM from 1 to 1
GDS2TEXT BOX=-10 -10 -4 -4
BOX range for set hi1277 :
RA---NCP from -10 to -4
DEC--NCP from -10 to -4
Converted 49 floats from ASCII file
GDS2TEXT +++ FINISHED +++

Updates: Jul 27, 1992: VOG, Document created.
Jul 23, 1993: VOG, Spreadsheet option implemented.
Sep 1, 1995: VOG, Physical coordinates in XYZ format
Mar 30, 2001: VOG, New keyword SKIPBLANK=