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=