AntholoGIS

ShapeLib is a C library for development of applications to read/write ESRI ShapeFiles. It’s used by many FOSS-GIS projects and at its website you can also find bindings for Perl, Python, Ruby, Delphi, Tcl, .NET and PHP. ShapeLib package also include some nice tools for Shapefile handling. These tools are simple and powerfull command line gadgets that output messages at the console or generate new shapefiles.

This page is an updated version of “ShapeLib Tools – User Guide” created in 2004.

ShapeLib is maintained by  Frank Warmerdam
This guide was created by  Eduardo Patto Kanegae
Last revision: 2007-01-02

• dbfcreate
• dbfadd
• dbfdump
• shpcreate
• shpadd
• shpdump
• shprewind
• shputils
• Tools from ShapeLib ‘contrib’ source directory
  • dbfinfo
  • dbfcat
  • shpinfo
  • shpcat
  • shpcentrd
  • shpdata
  • shpdxf
  • shpfix
  • shpproj
  • shpwkb
• Third party tools ( not included with shapelib source)
  • shpdiff

dbfcreate

Purpose: creates a new and empty .dbf file.
Usage: dbfcreate xbase_file [[-s field_name width],[-n field_name width decimals]]…

• xbase_file: the name of xBase file to be created. Doesn’t need the extension.
• -s field_name width: creates a string field with name defined by field_name and size of width.
• -n field_name width decimals: creates a numeric field with name defined by field_name, width of width and with decimals places sized by decimals.

Example
$ dbfcreate testpoly -s NAME 20, -n AREA 9 3, -n VALUE 9 2
# this will create a file named testpoly.dbf with 3 fields: NAME ( string (20)), AREA ( float (9,3)) and VALUE ( float (9,2))

dbfadd

Purpose: adds a record into an existing .dbf file.
Usage: dbfadd xbase_file field_values

• xbase_file: the name of an existing xBase file.
• field_values: list of values to be inserted into the xBase file. You must specify a number of values equal to the number of fields the xBase file has. The order of values must also reflect the order of fields inside xBase file.

Example
$ dbfadd testpoly.dbf REGION1 5000 150.22
# assuming that testpoly.dbf has 3 fields( NAME, AREA and VALUE), this command line will insert a new record into testpoly.dbf with the value “REGION1″ for NAME, ‘5000′ for AREA and ‘150.22′ for VALUE field.

dbfdump

Purpose: dumps the content of a xBase file to the terminal.
Usage: dbfdump [-h] [-r] [-m] xbase_file

• -h: output header info( field descriptions).
• -r: output raw field info, numeric values not reformatted.
• -m: output one field per line.
• xbase_file: the name of an existing xBase file.

Example
$ dbfdump -h testpoly.dbf
# assuming that testpoly.dbf has 1 record( inserted by previous example using dbfadd), this command line will produce the following output:

Field 0: Type=String, Title=`NAME’, Width=20, Decimals=0
Field 1: Type=Double, Title=`AREA’, Width=9, Decimals=3
Field 2: Type=Double, Title=`VALUE’, Width=9, Decimals=2
NAME                     AREA     VALUE
REGION1              5000.000    150.22

shpcreate

Purpose: creates a new and empty shapefile.
Usage: shpcreate shp_file point|arc|polygon|multipoint

• shp_file: the name of shapefile to be created. Doesn’t need the extension.
• point|arc|polygon|multipoint: the type of shapefile that you wish to create. You must specify a valid option.

Example
$ shpcreate testpoly polygon
# this will create a point shapefile named testpoly( in fact, testpoly.shp and testpoly.shx files will be created).

shpadd

Purpose: adds a shape into an existing shapefile.
Usage: shpadd shp_file [[x y] [+]]*

• shp_file: the name of an existing shapefile.
• x₁ y₁ x₂ y₂ … x_n y_n: the set of x,y coordinates that describes the shape that you wish to add. Note that you must specify the correct number of parameters for a given type of shapefile. e.g.: for point shapefiles you have to pass 1 pair of XY coordinates and for a polygon shapefile you should pass at least 4 pairs of XY coordinates( where the first and the last point must have the same coordinates).

Example
$ shpadd testpoly 100 700 250 650 200 600 100 700
# assuming that testpoly is a polygon shapefile, this command line will insert a new shape( a triangle) into testpoly with the following XY coordinates:
vertice 0: 100 700( this will also be the vertice where the shape starts and ends)
vertice 1: 250 650
vertice 2: 200 600
vertice 3: 100 700

shpdump

Purpose: dumps content of shapefile showing information like shape type, file extents, total of objects and vertices coordinates.
Usage: shpdump [-validate] shp_file

• -validate: count the number of objects that has invalid ring orderings. Valid polygons have vertices defined in clockwise direction but a polygon can contain hole(s), which is defined by counterclockwise vertices after the container polygon
• shp_file: the name of an existing shapefile.

Example
$ shpdump testpoly
# assuming that testpoly is an existing shapefile previously created, this command line will output the following result:

Shapefile Type: Polygon   # of Shapes: 1
File Bounds: (  100.000, 600.000,0,0)
         to  (  250.000, 700.000,0,0)
Shape:0 (Polygon)  nVertices=4, nParts=1
  Bounds:(  100.000, 600.000, 0, 0)
      to (  250.000, 700.000, 0, 0)
     (  100.000, 700.000, 0, 0) Ring
     (  250.000, 650.000, 0, 0)
     (  200.000, 600.000, 0, 0)
     (  100.000, 700.000, 0, 0)

shprewind

Purpose: validates and resets the winding order of rings in polygon geometries to match the ordering required by shapefile specification. This is usefull for shapefiles having troubles when checked with a ’shpdump -validate’.
Usage: shprewind in_shp_file out_shp_file

• in_shp_file: the name of an existing shapefile.
• out_shp_file: the name of the new fixed shapefile that will be created.

Example
$ shprewind badshapefile newshapefile

shputils

Purpose: performs different operations against a given shapefile. This program can be used to display general information of a shapefile or to generate a new shapefile using its functions: FACTOR, SHIFT, SELECT, UNSEL, CLIP or ERASE. You can also execute more than one operation with a single command line.

Note: the shapefiles used by some of the examples bellow can be downloaded here. Extract the content of this zipfile and enter mexico folder.

Usage 1 : Describing a shapefile

Use this mode to display general information of a shapefile. Command output will display info such as shapefile bounds, number of objects in shapefile, number of fields in .dbf file, field definitions, field data ranges and mean values( for numeric fields only).
Usage: shputils shapefile [ALL]

• shapefile: the name of an existing shapefile.
• ALL: use this option only if the shapefile has more than 5,000 records.

Example
$ shputils states
# this command line will output the following result:
DESCRIBE: states.shp
Input Bounds: (-117.122,14.5505) – (-86.735,32.7208)   Entities: 32   DBF: 32
Available Items: (3)          RANGES (MEAN)
Real   12,3  AREA            512.050 to 95771.458    (23617.251)
String    4  CODE            MX01 to MX32
String   25  NAME            Aguascalientes to Zacatecas

Usage 2 : Changing the coordinate value units and shifting coordinates

Use the FACTOR function to change the coordinate units of a given shapefile. Note that you must know the current unit of the shapefile and provide this unit as an input parameter. You can also use the SHIFT function after the factor operation.
Usage: shputils in_shp out_shp FACTOR in_unit out_unit [SHIFT Xshift Yshift]

• in_shp: the name of an existing shapefile.
• out_shp: the name of the new shapefile that will be created( the program will use a convertion factor which depends the units provided as parameters).
• FACTOR: this mandatory word will tell shputils to performs the coordinate value units convertion function.
• in_unit: specify the coordinate unit of the input shapefile. One of the following values must be used: FEET, MILES, METERS or KM
• out_unit: specify the coordinate unit of the output shapefile. One of the following values must be used: FEET, MILES, METERS, KM or you can also provide a numeric value as factor.
• SHIFT: if SHIFT parameter is used, values for X and Y shifting must also be used.

Example
$ shputils testpoly testpoly_feet FACTOR METERS FEET SHIFT 5 -2.5
# this command line will output the following result bellow and will also generate a new shapefile named ‘testpoly_feet’:
Output file coordinate values will be factored by 3.28083
Input Bounds:  (100,600) – (250,700)   Entities: 1   DBF: 1
New Output File

Output Bounds: (333.083,1966) – (825.208,2294.08)   Entities: 1  DBF: 1

Usage 3 : Selecting objects using an integer field as filter

Use the SELECT or UNSEL functions to define records to be written or NOT for the output file. You must provide an integer field as filter. Other field types such as DOUBLE or STRING will cause the program to fail.
Usage: shputils in_shp out_shp SELECT|UNSEL field_name value_list

• in_shp: the name of an existing shapefile.
• out_shp: the name of the new shapefile that will be created.
• SELECT|UNSEL: use SELECT option to output only the records defined by field_name and value_list. The UNSEL option will do the opposite: will NOT output only the records defined by the condition.
• field_name: name of the integer field that will be used as filter.
• value_list: a comma separated list of values.

Example
$ shputils pline pline_selection SELECT OBJECT__ID 131980,131966,132123,132060
# this command line will output the following result bellow and will generate a new shapefile named ‘pline_selection’ containing only 4 records:
Input Bounds:  (1.29637e+006,228199) – (1.3027e+006,237185)   Entities: 460   DBF: 460
New Output File

Output Bounds: (1.30175e+006,233553) – (1.30239e+006,235049)   Entities: 4  DBF: 4

Usage 4 : Clipping and Erasing using a boundary extent or a mask shapefile

Use the CLIP or ERASE functions to create a new shapefile based on a given boundary extent or the boundary defined by a shapefile. The CLIP option will write only the objects that touches or falls completely inside a given boundary. The ERASE option will do the opposite of the CLIP option.
Usage: shputils in_shp out_shp CLIP|ERASE <minX minY maxX maxY|maskfile BOUNDARY> TOUCH|INSIDE

• in_shp: the name of an existing shapefile.
• out_shp: the name of the new shapefile that will be created.
• CLIP|ERASE: the CLIP option will write only the objects that touches or falls completely inside a given boundary. The ERASE option will do the opposite of the CLIP option.
• minX minY maxX maxY|maskfile BOUNDARY: you can use a rectangle boundary defined by {minX,minY,maxX,maxY} coordinates or also use a shapefile as a mask.
• TOUCH|INSIDE: use TOUCH or INSIDE option to define the type of spatial relationship between the boundary and shapefile geometries.

Examples
$ shputils states states1 CLIP -104.7577164 24.38385107 -98.25996094 30.37644768 TOUCH
# Example 1) a shapefile named states1 is created containing the 7 shapes( see grey items at the image bellow) that spatially touches the given extent( see red region in image bellow). The command will output something like this:
Clip Box: (-104.757716,24.383851) – (-98.259961,30.376448)
Input Bounds: (-117.122,14.5505) – (-86.735,32.7208)   Entities: 32   DBF: 32
New Output File

Output Bounds: (-109.146,21.0544) – (-97.1686,31.7868)   Entities: 7  DBF: 7

$ shputils states states2 CLIP -104.7577164 24.38385107 -98.25996094 30.37644768 INSIDE
# Example 2) a shapefile named states2 is created containing the only shape( see grey item at the image bellow) that is spatially inside the given extent( see red region in image bellow). The command will output something like this:
Clip Box: (-104.757716,24.383851) – (-98.259961,30.376448)
Input Bounds: (-117.122,14.5505) – (-86.735,32.7208)   Entities: 32   DBF: 32
New Output File

Output Bounds: (-103.955,24.56) – (-99.8078,29.8801)   Entities: 1  DBF: 1

$ shputils states states3 ERASE -104.7577164 24.38385107 -98.25996094 30.37644768 TOUCH
# Example 3) a shapefile named states3 is created containing the 25 shapes( see grey item at the image bellow) that DOES NOT spatially touch the given extent( see red region in image bellow). The command will output something like this:
Clip Box: (-104.757716,24.383851) – (-98.259961,30.376448)
Input Bounds: (-117.122,14.5505) – (-86.735,32.7208)   Entities: 32   DBF: 32
New Output File

Output Bounds: (-117.122,14.5505) – (-86.735,32.7208)   Entities: 25  DBF: 25

$ shputils states states4 ERASE -104.7577164 24.38385107 -98.25996094 30.37644768 INSIDE
# Example 4) a shapefile named states4 is created containing the 31 shapes( see grey item at the image bellow) that ARE NOT spatially inside the given extent( see red region in image bellow). The command will output something like this:
Clip Box: (-104.757716,24.383851) – (-98.259961,30.376448)
Input Bounds: (-117.122,14.5505) – (-86.735,32.7208)   Entities: 32   DBF: 32
New Output File

Output Bounds: (-117.122,14.5505) – (-86.735,32.7208)   Entities: 31  DBF: 31

$ shputils states states5 CLIP mymask.shp BOUNDARY TOUCH
# Example 5) in this case a file named mymask will be used as boundary filter.

dbfinfo

Purpose: displays basic information for a given xBase file, like number of columns, number of records and type of each column.
Usage: dbfinfo xbase_file

• xbase_file: the name of an existing xBase file.

Example
$ dbfinfo testpoly

Info for testpoly.dbf
3 Columns,  1 Records in file
           NAME          string  (20,0)
           AREA           float  (9,3)
          VALUE           float  (9,2)

dbfcat

Purpose: appends the records of a source xBase file into a destiny xBase file. Both files must have the same number of fields.
Usage: dbfcat [-v] [-f] from_DBFfile to_DBFfile

• -v: verbose mode.
• -f: forces data convertion if data field types is not the same at both files or if is there any null value into from_DBFfile.
• from_DBFfile: source xBase file.
• to_DBFfile: destiny xBase file.

Example
$ dbfcat -v file1 file2

shpinfo

Purpose: displays basic information for a given shapefile, like shapefile type, number of objects and its extents.
Usage: shpinfo shp_file

• shp_file: the name of an existing shapefile.

Example
$ shpinfo testpoly

Info for testpoly
Polygon(5), 1 Records in file
File Bounds: (         100,        600)

shpcat

Purpose: appends the content of a source shapefile into a destiny shapefile. Both files must be the same shapefile type.
Usage: shpcat from_shpfile to_shpfile

• from_shpfile: source shapefile
• to_shpfile: destiny shapefile

Example
$ shpcat shapefile1 shapefile2

shpcentrd

Purpose: computes XY centroid for polygon shapefiles.
Usage: shpcentrd shp_file new_shp_file

• shp_file: the name of an existing polygon shapefile.
• new_shp_file: the name of the point shapefile that will created.

Example
$ shpcentrd apolygonfile pointcentrd

shpdata

Purpose: calculates area, length and centroid for each object of a given shapefile.
Usage: shpdata shp_file

• shp_file: the name of an existing shapefile.

Example
$ shpdata testpoly
# this command line will output something like:
(shpdata) Ring(0) (0 for 4)
(shpdata)  Ring 0, 5000.000000 Area -1 dir
(shpdata) End Ring
(shpdata) Part (0) 5000.000000 Area  -1.000000 length, C (183.333333,650.000000)

        (         250,        700)

shpdxf

Purpose: creates a DXF file from an existing shapefile.
Usage: shpdxf shapefile idfield

• shapefile: the name of an existing shapefile.
• idfield: the name of an existing DBF name to be used as object ID.

Example
$ shpdxf testshapefile IDFIELD

shpfix

Purpose: Utility program to fix nulls and inconsistencies in Shapefiles as happens from time to time.
Usage: shpfix shpfile new_file record_to_blank

• shpfile: the name of an existing shapefile.
• new_file: the name of the shapefile that will created.
• record_to_blank: record number that will be supressed.

Example
$ shpfix broken fixed

shpproj

Purpose: reproject shapefiles using PROJ.4 functions.
Usage: shpproj shp_file new_shp -i=in_proj_file|-i=”in_params”|-i=geographic -o=out_proj_file|-o=”out_params”|-o=geographic

• shp_file: the name of an existing shapefile.
• new_shp: the name of the new shapefile that will be created.
• -i=in_proj_file|-i=”in_params”|-i=geographic: one of these options can be used to specify an INPUT spatial reference system:
  • a) a projection parameter file as in_proj_file – which is a text file with .prj extension and has one parameter per line. Check PROJ.4 documentation for further information about these parameters.
  • b) a string containing projection parameters. Example: “proj=utm zone=13 ellps=clrk66 datum=NAD27 units=m” ( NAD27 / UTM zone 13N )
  • c) using the keyword ‘geographic’ will tell shpproj that input coordinates system is geographic.
  • d) omitting input projection parameters. In this case, geographic coordinates( same as ‘-i=geographic’) will be used unless a .prj file exists with the same name of the input shapefile.
• -o=out_proj_file|-o=”out_params”|-o=geographic: one of these options can be used to specify an OUTPUT spatial reference system( same as above):
  • a) a projection parameter file as out_proj_file.
  • b) a string containing projection parameters.
  • c) using the keyword ‘geographic’ will tell shpproj that output coordinates system is geographic.
  • d) omitting output projection parameters. In this case, geographic coordinates( same as ‘-o=geographic’) will be used unless a .prj file exists with the same name of the output shapefile.

Examples
shpproj states states_gall -i=geographic -o=”init=epsg:53016″
# Example 1) assuming that you have downloaded these files, this command line will transform ’states’ shapefile from geographic to Sphere Gall Stereographic coordinate system into ’states_gall’ shapefile.

shpproj states_gall states_stere -o=”proj=stere lat_0=0 lon_0=0 x_0=0 y_0=0 a=6371000 b=6371000 units=m”
# Example 2) this command line will transform ’states_gall’ shapefile from Sphere Gall Stereographic to Sphere Stereographic coordinate system into ’states_stere’ shapefile. The -i option was omitted because states_gall.prj was already generated after the Example 1.

shpwkb

Purpose: OGC Well Known Binary test program( output only).
Usage: shpwkb shp_file wkb_file

• shp_file: the name of an existing shapefile.
• wkb_file: name of WKB output file to be created.

Example
$ shpwkb testpoly testpoly.wkb

gonna build a wkb
gonna write a wkb that is 86 bytes long

shpdiff

Purpose: compares two shape files, printing a human-readable summary of any differences. It is particularly useful to monitor changes made for a given shapefile. Both the attributes and the shapes are compared.
Usage: shpdiff original_shapefile comparison_shapefile

• original_shapefile: the name of an existing shapefile.
• comparison_shapefile: shapefile to be compared to the first file.

Example
$ shpdiff states states3
# assuming that you already played with shputils examples, this command line will generate the following output:

Original Shapefile Type: Polygon, 32 shapes 32 database records
Comparison Shapefile Type: Polygon, 25 shapes 25 database records

NOTE: Using column NAME to identify records
WARNING: Ingoring column "AREA"

Record 23: deleted from original
--------------------------------
AREA: 95771.458
CODE: MX06
NAME: Chihuahua

Record 24: deleted from original
--------------------------------
AREA: 57988.415
CODE: MX07
NAME: Coahuila De Zaragoza

Record 26: deleted from original
--------------------------------
AREA: 46463.611
CODE: MX10
NAME: Durango

Record 27: deleted from original
--------------------------------
AREA: 28881.617
CODE: MX32
NAME: Zacatecas

Record 28: deleted from original
--------------------------------
AREA: 24767.049
CODE: MX24
NAME: San Luis Potosi

Record 29: deleted from original
--------------------------------
AREA: 25139.835
CODE: MX19
NAME: Nuevo Leon

Record 30: deleted from original
--------------------------------
AREA: 30503.273
CODE: MX28
NAME: Tamaulipas