Suite of low-level modules to read ESRI Arc/Info generated Shape Files.
module ReadShapeHeader {
string+IPort2 ShapeFileName;
int+OPort2 ShapeType;
int+OPort2 NumberOfFeatures;
};
module ReadShapePoint {
string+IPort2 ShapeFileName;
int+IPort2 FeatureNumber;
int NumberOfPoints;
double+OPort2 Coordinates[NumberOfPoints][2];
int+OPort2 ShapeType;
int+OPort2 NumberOfFeatures;
int+OPort2 FeatureID[NumberOfPoints];
};
module ReadShapeArc {
string+IPort2 ShapeFileName;
int+IPort2 FeatureNumber;
int NumberOfPoints;
int NumberOfConnections;
int NumberOfPolylines;
double+OPort2 Coordinates[NumberOfPoints][2];
int+OPort2 ConnectList[NumberOfConnections];
int+OPort2 ShapeType;
int+OPort2 FeatureID[NumberOfPolylines];
};
module ReadShapePolygon {
string+IPort2 ShapeFileName;
int+IPort2 FeatureNumber;
int+IPort2 TriangulateAllPolygons = 0;
int NumberOfPoints;
int NumberOfPolyNodes;
int NumberOfConnections;
int NumberOfPolygons;
double+OPort2 Coordinates[NumberOfPoints][2];
int+OPort2 PolyNodes[NumberOfPolyNodes];
int+OPort2 ConnectList[NumberOfConnections];
int+OPort2 ShapeType;
int+OPort2 FeatureID[NumberOfPolygons];
};
module ReadShapePolygonAsLine {
string+IPort2 ShapeFileName;
int+IPort2 FeatureNumber;
int NumberOfPoints;
int NumberOfConnections;
int NumberOfPolylines;
double+OPort2 Coordinates[NumberOfPoints][2];
int+OPort2 ConnectList[NumberOfConnections];
int+OPort2 ShapeType;
int+OPort2 FeatureID[NumberOfPolylines];
};
This library contains a suite of low-level modules for reading Shape files into AVS/Express. Shape files are a binary file format that is exported by Arc/Info, and other GIS products from ESRI. The files contain point, line and polygon geometric information, generally representing vector-style map data, such as roads, cities, rivers, and area boundaries. This format is common in GIS (Geographic Information Systems) and can be used to combine data from a number of sources. These modules read Shape file contents, producing array structures as output. These outputs contain coordinate and connectivity data that can be used to create AVS/Express meshes by using array mapping modules. If you wish to create meshes automatically then a number of functional and user macros are available.
More information on shape files can be obtained from:
Environmental Systems Research Institute, Inc. (http://www.esri.com/)
Generally GIS data is exported in three related files:
Shapefiles (.shp), Index files (.shx), and dBASE attribute files (.dbf).
ESRI provides a service whereby Shape data of a region can be easily obtained from the ArcData Online web-site. By selecting a region of interest and specifying the details of your own map, the appropriate Shapefiles and dBase attribute files can then be downloaded. The web-site is located at:
http://www.esri.com/data/online/index.html
The modules in the ReadShapeMods library read all or parts of the geometric information in the ShapeFile format. Optionally, the ReadDbase project can also be used to read the attribute information contained in the dBASE files and combine all the data into one map display.
The current version of the ReadShape project adds support for 64 bit platforms. This support has currently only been tested on a SGI Origin 2000.
Most of the low-level modules retrieve geometry data from ShapeFiles. This data is output as a series of primitive arrays. Before this data can be used it must be converted into AVS/Express Mesh data. This can be done by using array mapping modules. A series of higher-level macros has been developed that does this automatically. The table below details the equivalence between low-level modules and higher-level program macros.
| Low-level Module | High-level Macro | Purpose |
| ReadShapeHeader | n/a | Extracts Header, Type information |
| ReadShapePoint | PointShape | Extracts Points, attribute positions |
| ReadShapeArc | ArcShape | Extracts Line (Polyline) information |
| ReadShapePolygon | PolygonShape | Extracts Polygons (Coverages) |
| ReadShapePolygonAsLine | PolygonAsLineShape | Extracts Polygons, converting to Lines |
ShapeFileFilename
The name of the file that should be read from. The parameter is of type string. The filename should specify the full path name of the file.
FeatureNumber
The feature that should be read from the ShapeFile. The parameter is of type int. If no feature number is provided all features are read from the ShapeFile.
ShapeType
A integer value specifying the type of ShapeFile being read. The shape type and appropriate module to read it can be found the following table:
| Number | Shape Name | Reading Module |
| 0 | Null Shape | n/a |
| 1 | Point Shape | ReadShapePoint |
| 3 | Arc Shape | ReadShapeArc |
| 5 | Polygon Shape | ReadShapePolygon or ReadShapePolygonAsLine |
| 8 | Multipoint Shape | ReadShapePoint |
Other values indicate that the Shape Type was found to be invalid.
NumberOfFeatures
A integer value specifying the numbers of features found in the ShapeFile. A feature is an individual object within the geometry described by the ShapeFile. For instance a feature may be a single Point, Line or Polygon.
NumberOfPoints NumberOfConnections NumberOfPolygons NumberOfPolyNodes NumberOfPolylines
These variables are used to specify the size of the various coordinate, connectivity and Feature ID arrays that are generated be the Shape reading modules. These values are not commonly used outside of the module and hence are not exported.
Coordinates[NumberOfPoints][2]
Floating point array containing the vertex coordinates read from the ShapeFile.
ConnectList[NumberOfConnections] PolyNodes[NumberOfPolyNodes]
Integer arrays containing the connectivity data read from the ShapeFile. Together with the vertex coordinates, this data can be used to generate meshes by using array mapping modules.
FeatureID[]
Integer array containing the numeric IDs of all the features read from the ShapeFile.
ShapeType NumberOfFeatures
Please see above for the purpose of these outputs.
The ReadDbase suite of modules can be combined with the ReadShape modules to combine attribute information with geometry information. The ReadShape low-level modules are also used by the PointShape, ArcShape, PolygonShape and PolygonAsLineShape Functional macros and the read_shape User macro.
Two example applications are provided that use a set of example data to illustrate how the ReadShape suite of modules and macros can be used.
The ReadShapeProgramEg application illustrates how the Program macros and ReadDbase modules can be used in a V script programming situation. If you are creating a complete application that is to be used by others then this application structure will probably work best.
The ReadShapeUserEg application illustrates how the three read_shape User macros can be used to read three series of data. The read_shape macro is intended to be used to quickly read and view ShapeFile data. Due to this the macro has a user interface and automatically determines the type of the ShapeFile being read. When this application is started it is likely that a number of error messages will be displayed. This is a transient condition caused by the order of network execution and can be safely ignored.
iac_proj/rd_shape/rshpmods.v contains the V definitions of the suite of ShapeFile reading modules.
This suite of modules is implemented by an underlying C++ class system, which is then connected to the AVS/Express cxx module system. Not all possible shape file entities will be mapped, in particular if the model contains holes, or nested structures.
The low-level ReadShapeMods library containing the low-level module suite does not specify a process. By default the express process will be used.
Steve Walker Advanced Visual Systems, Inc. Hanworth Lane, Chertsey Surrey, UK KT16 9JX
Andrew Dodd International AVS Centre
International AVS Centre Manchester Visualization Centre Manchester Computing University of Manchester Oxford Road Manchester United Kingdom M13 9PL