NUMREAD -- Read Image Data from Text File

Reads image grey level values stored in a text file, then writes the data to image database channel(s).

Progress of this program can be monitored. See MONITOR section.

See Also: IMAGERD, VREAD, NUMWRIT

PARAMETERS

NUMREAD is controlled by the following global parameters: 

Name     Prompt                                  Count     Type
FILE     Database File Name                      1-64      Char
DBGEO    Database Georeferencing Segment         0-1       Int
DBOC     Database Output Channel List            1-1024    Int
DBOW     Database Output Window                  0-4       Int
NUMFORM  Numeric Format                          4-8       Char
TFILE    Text File Name                          1-64      Char
MEMSIZE  Working Memory Size (Mbytes)            0-1       Int

FILE

Specifies the name of the PCIDSK image file to receive the values stored in the text file. This file must already exist; it is not created by NUMREAD. 

 EASI>FILE="filespec"

DBGEO

Optionally specifies the georeferencing segment. This parameter is required if the input coordinates are georeferenced instead of pixel,line. 

 EASI>DBGEO=i       | Georeferencing segment 
 EASI>DBGEO=        | Default is 1.
Only simple georeferencing is supported: metres, UTM, equirectangular long/lat. Other projections are not supported.

DBOC

Specifies the database image channel(s) to receive the text file values. 

 EASI>DBOC=i

DBOW

Specifies the rectangular window on the database image channel(s) to which grey level values from the text file will be written. 

 EASI>DBOW=Xoffset,Yoffset,Xsize,Ysize
 EASI>DBOW=                            | default to entire database
Grey level values which fall outside this window are ignored.

TFILE

  Valid Values:   <filename, max. 64 characters>
  Default:        <none>
Specifies the name of the text file, which contains the data values that are to be read into the PCIDSK image channels.

MEMSIZE

  Valid Values:   0 <= x <= 2000
  Default:        16
Specifies the size (in Mbytes) of internal working memory buffer. In general NUMREAD will run faster with larger amounts of memory, however, it will work with any size of memory. 

 EASI> MEMSIZE = n       | Use n Mbytes.
 EASI>                   | defaults to 4

NUMFORM

  Valid Values:   COORD, GEOCOORD, DATA
  Default:        COORD
Specifies the format of the image data stored in the text file. Image data can be stored in one of three formats: coordinate, georeferenced, or data. 

 EASI>NUMFORM="COORD"          | coordinate format in pixel and line
 EASI>NUMFORM="GEOCOORD"       | coordinate format in georeferenced
 EASI>NUMFORM="DATA"           | data format
See the FORMAT subtopic for examples and details.

DETAILS

NUMREAD transfers image data in a text file (TFILE) to image channel(s) (DBOC) on a PCIDSK database file (FILE). If desired, the data read operation can be performed upon a restricted window (DBOW) within the output channels.

Image data can be stored in the text file in one of three possible formats: coordinate (NUMFORM="COORD"), georeferenced coordinate (NUMFORM="GEOCOORD"), or data (NUMFORM="DATA"). The georeferencing segment DBGEO may be specified if NUMFORM="GEOCOORD".

If more than one output channel is specified, then data in the text file are assumed to be stored in pixel interleaved form (BIP).

Data values will be truncated if they exceed the minimum/maximum allowable values in the output channel(s) DBOC. For example, if DBOC is an 8-bit unsigned channel type, then values less than 0 or greater than 255 will be truncated to 0 and 255, respectively.

The MEMSIZE parameter can be used to control the size of the internal working buffer of the output image. Making this large, ideally large enough for the entire input image, can dramatically speed up processing of input data with a NUMFORM of GEOCOORD, or COORD

Input text files with X and Y coordinates (NUMFORM="COORD" or NUMFORM="GEOCORD") will process quicker, if the text file has been sorted on the Y coordinate prior to running NUMREAD. This can be done with system sort commands. For example, on a UNIX platform, if file.txt has one X, Y, and greyscale value per record, the following: 

 EASI>sys "sort +1 -2 file.txt > sorted.txt"
runs the UNIX sort command on the file called file.txt and sorts it primarily on the second field (the Y coordinate) and secondarily on the first field (the X coordinate) and directs the sorted text records to a new file called sorted.txt, which could then be used as TFILE for NUMREAD.

The number of input points that were out of the database output window are counted by NUMREAD and printed to the screen if greater than zero. Since out of range, these points are ignored.

MONITOR

Program progress can be monitored by printing the percentage of completed processing in odometer fashion. A system parameter, MONITOR, controls this activity: 

 EASI>MONITOR="ON"        | turn monitor ON  (default)
 EASI>MONITOR="OFF"       | turn monitor OFF (recommended if
                          | running in batch/background mode)
The MONITOR parameter is used only when NUMFORM is equal to DATA.

EXAMPLE

Read grey level values from the text file TEST.TXT (where data are stored in coordinate form) and write to the database (TEST.PIX) only those values which are within the specified image window (0,0,10,10). Values outside this window in TEST.TXT are ignored.

Text file TEST.TXT has the following data values: 

 5  5 10     6  6 11    6  5 12    5  6 13    11  4 14    4  11 100
 1  1  1    10 10 10
The output channel 5 is cleared using the CLR program. 

 EASI>FILE="TEST.PIX"
 EASI>DBOC=5
 EASI>DBOW=0,0,10,10
 EASI>RUN CLR
The NUMREAD program writes grey level values to the database. 

 EASI>TFILE="TEST.TXT"
 EASI>NUMFORM="COORD"
 EASI>RUN NUMREAD
NUM program prints report of numeric window (0,0,10,10) of image channel 5. 

 EASI>DBIC=5
 EASI>DBIW=0,0,10,10
 EASI>REPORT="TERM"
 EASI>RUN NUM

 NUM     Database Numeric Window     V5.3 EASI/PACE   13:28 03-AUG-94

 IM:[WILSON]TEST.PIX;1              [S 10PIC   256P   256L] 24-NOV-89
 8: NUMREAD Image data from Text file: test.txt       15:27 15-JAN-90

 Offset: (    0,    0)  Size: (   10,   10)

                                            1
        1   2   3   4   5   6   7   8   9   0
     +---------------------------------------
    1|  1   0   0   0   0   0   0   0   0   0
    2|  0   0   0   0   0   0   0   0   0   0
    3|  0   0   0   0   0   0   0   0   0   0
    4|  0   0   0   0   0   0   0   0   0   0
    5|  0   0   0   0  10  12   0   0   0   0
    6|  0   0   0   0  13  11   0   0   0   0
    7|  0   0   0   0   0   0   0   0   0   0
    8|  0   0   0   0   0   0   0   0   0   0
    9|  0   0   0   0   0   0   0   0   0   0
   10|  0   0   0   0   0   0   0   0   0  10

FORMAT

The data format expected by NUMREAD is determined by the value of the NUMFORM parameter. The possible values are COORD, GEOCOORD, and DATA.

For the coordinate ("COORD") format, the text file must contain two values for each pixel: database x-position (horizontal) and database y-position (vertical), followed by grey level value(s) for each input channel (interleaving mode).

The (x,y) position represents the pixel and line number on the image channel to which the corresponding grey level is written. If the number of output channels (DBOC) is one, then all three values must be stored on the same line. As many sets of values with (x,y) positions and grey levels can be stored an a line as desired, hence NUMREAD is able to read the output of a text file generated with NUMWRIT using the "COORDn" format.

If the (x,y) position is not within the specified window (DBOW) or not on the database file, then the pixel value is ignored and is not written to the image channel.

It may be possible that an error in the text file will result in the data being read incorrectly without any errors being detected and reported by the program; appropriate care should be taken to verify results when file corruption is suspected.

In the following example there are eight pixels represented at locations (5,5), (6,6), (6,5), (5,6), (11,4), (4,11), (1,1), and (10,10). They have image values 10, 11, 12, 13, 14, 100, 1 and 10.

Example: 

 5  5 10     6  6 11    6  5 12    5  6 13    11  4 14    4  11 100
 1  1  1    10 10 10
For the georeferenced coordinate ("GEOCOORD") format, the content of the text file is similar to that of the COORD format except that the (x,y) position is the georeferenced position. This is translated to a pixel/line coordinate using the information in the georeferencing segment (DBGEO).

Example: 

 428735 3734385 10
 428795 3734355 22
For the data ("DATA") format, the text file must contain one grey level value for each pixel to be written to the image channel. Pixel and line positions are assumed to be sequential, starting from left to right, and from top to bottom.

Example: 

 62  68  58  57  61  63  59  58  59  61
 62  60  59  56  59  63  60  63  63  57
 63  63  61  59  59  60  62  62  64  64
 61  63  63  64  58  58  57  61  66  61
 59  64  64  63  60  59  58  60  62  59
 59  60  62  64  65  62  62  60  58  55
 59  60  59  61  64  63  63  60  57  55
 62  60  58  56  62  65  60  58  57  58
 63  60  59  59  63  61  56  57  56  56
 61  60  59  63  63  57  57  57  56  55
About PCI Help Gateway