# ShapeLib Tools - User Guide

ShapeLib is maintained by Frank Warmerdam
This guide was created by Eduardo Patto Kanegae < eduardo~at~consultoria~dot~eti~dot~br >

- dbfcreate
- dbfadd
- dbfdump
- shpcreate
- shpadd
- shpdump
- shprewind
- Tools from ShapeLib 'contrib' directory
  - dbfinfo
  - dbfcat
  - shpinfo
  - shpcat
  - shpcentrd
  - shpdxf
  - shpfix

## 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 field_name and size width.
- -n field_name width decimals: creates a numeric field with name field_name, width of width and with decimals places sized by decimals.

Example
$ dbfcreate testbase -s NAME 20, -n AREA 9 3, -n VALUE 9 2
# this will create a file named testbase.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 testbase.dbf REGION1 25.656 150.22
# assuming that testbase.dbf has 3 fields( NAME, AREA and VALUE), this command line will insert a new record into testbase.dbf with the value "REGION1" for NAME, '25.656' 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 line per field.
- xbase_file: the name of an existing xBase file.

Example
$ dbfdump -h testbase.dbf
# assuming that testbase.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 25.656 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 testpolygon polygon
# this will create a point shapefile named testpolygon( in fact testpolygon.shp and testpolygon.shx 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.
- x1 y1 x2 y2 ... xn yn: 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 testpolygon 100000 7000000 250000 6500000 200000 6000000 100000 7000000
# assuming that testpolygon is a polygon shapefile, this command line will insert a new shape( a triangle) into testpolygon with the following XY coordinates:
vertice 0: 100000 7000000 ( this will also be the vertice where the shape starts and ends)
vertice 1: 250000 6500000
vertice 2: 200000 6000000
vertice 3: 100000 7000000

## 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.
- shp_file: the name of an existing shapefile.

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

    Shapefile Type: Polygon   # of Shapes: 1

    File Bounds: (  100000.000, 6000000.000,0,0)
             to  (  250000.000, 7000000.000,0,0)

    Shape:0 (Polygon)  nVertices=4, nParts=1
      Bounds:(  100000.000, 6000000.000, 0, 0)
          to (  250000.000, 7000000.000, 0, 0)
         (  100000.000, 7000000.000, 0, 0) Ring
         (  250000.000, 6500000.000, 0, 0)
         (  200000.000, 6000000.000, 0, 0)
         (  100000.000, 7000000.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 useful 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

## 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 testbase

    Info for testbase.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 conversion 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 testbase1 testbase2

## 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 testpolygon

    Info for testpolygon
    Polygon(5), 1 Records in file
    File Bounds: (         100000,        6000000)
            (         250000,        7000000)

## 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

## shpdxf

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

- shapefile: the name of an existing shapefile.
- idfield: explain

Example
$ shpdxf testshapefile IDFIELD
# explain the command

## 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: input file
- new_file: output file

Example
$ shpfix broken fixed