VREAD

Description

Reads vector (line and point) data from a text file to a new PCIDSK file vector layer.

Note: Use FIMPORT to read interchange formats generated by many third-party GIS software programs.

Parameters

vread(filv, vecunit, file, dbsn, dbsd)

Name	Type	Caption	Length	Value range
FILV *	str	Input vector file name	1 -
VECUNIT	str	Vector units	0 - 16	PIXEL \| UTM \| METER \| LONG/LAT Default: PIXEL
FILE *	str	Output file name	1 -
DBSN	str	Output vector segment name	0 -	Default: VREAD
DBSD	str	Output vector segment description	0 -

* Required parameter

Parameter descriptions

FILV

Specifies the name of the text file on disk, from which the vector data values are read.

See 'Formats' in the Details section for information about the layout of vector and point data in the file.

VECUNIT

Specifies the type of units in which the vector coordinates are stored. This defines the range and accuracy for coordinates, and ensures that vector segments with different units cannot be merged. VECUNIT cannot specify a map projection (except UTM).

Supported units are:

PIXEL: image pixel and line numbers
UTM: UTM Easting and Northing coordinates
METER: meters
LONG/LAT: Longitude and Latitude

If LONG/LAT is specified, longitude and latitude may be entered either as real numbers, or as degrees, minutes, seconds, and hemisphere with NO BLANKS OR COMMAS between the d, ' and " symbols, as follows:

-DDD.DDDDD	| decimal degrees (with/without sign)
DDdMM'SS.SS"H	| d ' " symbols are separators (no blanks/commas)

For example: -15.5005 longitude can be specified as 15d30'1.8"W

VECUNIT can specify the UTM grid zone number and row, and Earth model, as follows:

"UTM mm r Ennn"

where:

mm: is the two-digit zone number between 1 and 60
r: is the zone row. A single letter between N and X for north of the equator, and between C and M for south of the equator. Zone rows A, B, Y and Z are not supported; rows I and O do not exist.
Ennn: specifies the Earth model, where the model number is between 0 and 19. If the Earth model is not specified, it is assumed to be E000 (Clarke 1866). The Earth model can be specified for LONG/LAT (and other units except PIXEL), as follows: VECUNIT="LONG/LAT Ennn"

For more information about how to specify VECUNIT, as well as a list of supported Earth models, refer to "Projections and Earth models" in the Technical Reference section of the Online Help.

PIXEL coordinates have a range of (+ or -) 2097151 and a resolution rounded to the thousandth.

UTM and METRE coordinates handle 0 to 10,000,000 metres N (or E) and have a resolution rounded to the nearest cm.

LONG/LAT coordinates have a range of (+ or -) 180 degrees and a resolution rounded to 2.5 cm at the equator.

The MAS function can be used to set projections information for a segment after reading with VREAD, if the required projection is not one of those supported directly for the VECUNIT parameter.

FILE

Specifies the name of the PCIDSK file to receive the new vector segment and output vector data.

DBSN

Specifies a name (up to 8 characters) for the output segment.

If this parameter is not specified, the default segment name "VREAD" is used.

DBSD

Optionally describes (in up to 64 characters) the contents or origins of the output data.

Details

VREAD reads vector information (points and/or lines) of the following format from a user-generated text file. The contents and form of this file are defined in the 'Formats' section below.

When VREAD runs, the contents of the text file (FILV) are read and a new vector segment (Type VEC:116) is created in the PCIDSK file (FILE) to hold the information. The coordinates of the created vector are in units specified by VECUNIT (Vector Units). The created vector segment is given a defined segment name (DBSN) and, optionally, a description (DBSD).

If a text file generated by a third-party software product is to be read, use FIMPORT instead. For a list of supported formats, see "GDB file formats" in the Technical Reference section of the Online Help. For ISIF format, use VECREAD.

Formats

The vector and point information in the text file must have the following form:

   Structure Type       Attribute Value (optional)
   X-Coordinate         Y-Coordinate
   X-Coordinate         Y-Coordinate
   ...

where:

Structure Type: is the character string 'LINE' or 'POINT'
Attribute Value: is an integer value
X-coordinates and Y-coordinates: are real or integer values

Fields are separated by one or more blanks, one or more tabs, and/or one comma.

For example:

 LINE,0
 428720    3734400
 444080.0  3734400
 444080,   3719040.0
 428720.0, 3719040.0
 428720,   3734400
 POINT 128
 436400.5  3726720

If VECUNIT is set to "LONG/LAT", coordinates may be specified either as real values, or as degrees, minutes, seconds and hemisphere separated by d, ', and " symbols with no blanks in between the symbols. For example:

117d36'10.04"W     or     33.749014

Up to 200 characters per text record may be used for text files. Each field within a text file can have up to 16 characters and is separated by one or more spaces and/or one comma.

A second special format is supported for point information. This has the following layout:

 X-Coordinate Y-Coordinate  Attribute ... Attribute
 X-Coordinate Y-Coordinate  Attribute ... Attribute
 X-Coordinate Y-Coordinate  Attribute ... Attribute
 . . .

In every input line, the third argument is treated as an attribute, and, if numeric, is also assigned to the Z coordinate.

For example:

 433567.0  373400.0   546 1.0 Village
 434000.0  373500.0   456 2.0 Town
 . . .

creates vertices:

 X = 433567.0  Y = 373400.0   Z = 546
    Attributes Integer1 = 546   Real2 = 1.0 String3 = Village
 X = 434000.0  Y = 373500.0   Z = 456
    Attributes Integer1 = 456   Real2 = 2.0 String3 = Town
  . . .

This format is automatically assumed if the first line of the file does not contain the word LINE or POINT, which would mean the first format is being used. This second special format is supported because it is more commonly used for elevation and other data sets. Attribute data can be read in integer, real, or alphanumeric form. The attribute name is derived from the attribute's type and number; for example, "Integer1", "Real2", "String3".

Examples

The text file border.txt contains UTM coordinates of a bounding rectangle for the image in irvine.pix. The bounding rectangle is assigned an attribute value of 0 and an interior point an attribute value of 128.

 LINE,0
 428720    3734400
 444080.0  3734400
 444080,   3719040.0
 428720.0, 3719040.0
 428720,   3734400
 POINT 128
 436400.5  3726720

To read this information into a vector segment in irvine.pix, use the following commands:

from pci.vread import vread

filv	=	"border.txt"
vecunit	=	"UTM 11 S E000"
file	=	"irvine.pix"
dbsn	=	"BORDER"
dbsd	=	"UTM Bounding rectangle for Irvine image"

vread( filv, vecunit, file, dbsn, dbsd )

The output vector segment contains the following data, as reported by VECREP:

 VECREP  Vector Segment Report

 irvine.pix                  [S   10PIC     512P     512L] 14-Aug-90
 33:BORDER    Type:116 [Vectors/Polygons]    Update: 15:18  1-Jun-91
    Contents: UTM Bounding rectangle for Irvine image
 Length:    0.5 Kbytes     Units: UTM 11 S E000    Structures:     2
 Bounds:    428720.00 E, 3719040.00 N), ( 444080.00 E, 3734400.00 N)
 Structure    1   Type: Line  Vertices:  5  Group:  0  Attribute:  0
 428720.00 E,   3734400.00 N            444080.00 E,    3734400.00 N
 444080.00 E,   3719040.00 N            428720.00 E,    3719040.00 N
 428720.00 E,   3734400.00 N
 Structure    2   Type: Point               Group:  0  Attribute:128
 436400.50 E,   3726720.00 N

The text file longlat.txt contains longitude and latitude coordinates of the same bounding rectangle for irvine.pix. Coordinates are either real numbers or deg/min/sec strings. Both formats are allowed in the same text file.