Shapelib

http://shapelib.maptools.org/
Admin
Shapelib is a C library for reading, writing, and manipulating ESRI shapefiles and xBase database...
Tokens:16,975
Snippets:159
Trust Score:5.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Create New DBF File

Source: http://shapelib.maptools.org/manifest.html

Simple example program for creating a new .dbf file. Requires the dbfopen.c and shapefil.h files.

```c
#include <stdio.h>
#include <stdlib.h>
#include "shapefil.h"

int main( int argc, char **argv )
{
    DBFHandle       hDBF;

    // open the new dbf file
    hDBF = DBFOpen( "new.dbf", "wb" );
    if( hDBF == NULL )
    {
        fprintf( stderr, "Failed to create new.dbf\n" );
        return 1;
    }

    // add some columns
    if( !DBFAddField( hDBF, "Name", FTString, 50, 0 ) ) { fprintf( stderr, "Failed to add Name field\n" ); return 1; }
    if( !DBFAddField( hDBF, "Value", FTDouble, 12, 4 ) ) { fprintf( stderr, "Failed to add Value field\n" ); return 1; }

    // add a record
    DBFWriteIntegerAttribute( hDBF, 0, 0, 1 );
    DBFWriteStringAttribute( hDBF, 0, 1, "Test Value" );
    DBFWriteLogicalAttribute( hDBF, 0, 2, TRUE );

    // close the file
    DBFClose( hDBF );

    return 0;
}
```

--------------------------------

### Create New SHP and SHX Files

Source: http://shapelib.maptools.org/manifest.html

Simple example program for creating a new .shp and .shx file. Requires the shpopen.c and shapefil.h files.

```c
#include <stdio.h>
#include <stdlib.h>
#include "shapefil.h"

int main( int argc, char **argv )
{
    SHPHandle       hSHP;
    int             nShapeType, nEntities;
    double          adfMinBound[4], adfMaxBound[4];

    // open the new shape file
    hSHP = SHPCreate( "new.shp", SHPT_POINT );
    if( hSHP == NULL )
    {
        fprintf( stderr, "Failed to create new.shp\n" );
        return 1;
    }

    // add a shape
    int nVertices = 3;
    double x[] = {0.0, 1.0, 0.0};
    double y[] = {0.0, 0.0, 1.0};
    int nSolid = -1;
    SHPObject   *psShape = SHPCreateObject( SHPT_POINT, -1, 0, NULL, NULL, nVertices, x, y, NULL, NULL );
    if( psShape == NULL )
    {
        fprintf( stderr, "Failed to create shape object\n" );
        SHPClose( hSHP );
        return 1;
    }
    if( SHPWriteObject( hSHP, -1, psShape ) < 0 )
    {
        fprintf( stderr, "Failed to write shape object\n" );
        SHPDestroyObject( psShape );
        SHPClose( hSHP );
        return 1;
    }
    SHPDestroyObject( psShape );

    // close the file
    SHPClose( hSHP );

    return 0;
}
```

--------------------------------

### Display DBF File Contents

Source: http://shapelib.maptools.org/manifest.html

Simple example program for displaying the contents of a .dbf file. Requires the dbfopen.c and shapefil.h files.

```c
#include <stdio.h>
#include <stdlib.h>
#include "shapefil.h"

int main( int argc, char **argv )
{
    DBFHandle       hDBF;
    int             i, j, nFieldCount;

    // open the dbf file
    hDBF = DBFOpen( "test.dbf", "rb" );
    if( hDBF == NULL )
    {
        fprintf( stderr, "Failed to open test.dbf\n" );
        return 1;
    }

    // print header
    nFieldCount = DBFGetFieldCount( hDBF );
    for( i = 0; i < nFieldCount; i++ )
    {
        char szTitle[ 256 ];
        char cType;
        int nWidth, nDecimals;

        DBFGetFieldInfo( hDBF, i, szTitle, &cType, &nWidth, &nDecimals );
        printf( "%15s (%c)  ", szTitle, cType );
    }
    printf( "\n\n" );

    // print records
    for( i = 0; i < DBFGetRecordCount( hDBF ); i++ )
    {
        for( j = 0; j < nFieldCount; j++ )
        {
            char szValue[ 256 ];
            DBFGetValue( hDBF, i, j, szValue );
            printf( "%15s  ", szValue );
        }
        printf( "\n" );
    }

    // close the file
    DBFClose( hDBF );

    return 0;
}
```

--------------------------------

### Run Stream Test Script 1

Source: http://shapelib.maptools.org/manifest.html

A test script that should produce stream1.out. This will only work if you have the example data downloaded.

```bash
./makeshape.sh stream1.sh
```

--------------------------------

### Add Record to DBF File

Source: http://shapelib.maptools.org/manifest.html

Simple example program for adding a record to an existing .dbf file. Requires the dbfopen.c and shapefil.h files.

```c
#include <stdio.h>
#include <stdlib.h>
#include "shapefil.h"

int main( int argc, char **argv )
{
    DBFHandle       hDBF;

    // open the existing dbf file
    hDBF = DBFOpen( "existing.dbf", "rb+" );
    if( hDBF == NULL )
    {
        fprintf( stderr, "Failed to open existing.dbf\n" );
        return 1;
    }

    // add a record
    DBFWriteIntegerAttribute( hDBF, 0, 0, 1 );
    DBFWriteStringAttribute( hDBF, 0, 1, "Test Value" );
    DBFWriteLogicalAttribute( hDBF, 0, 2, TRUE );

    // close the file
    DBFClose( hDBF );

    return 0;
}
```

--------------------------------

### Add Shape to Existing SHP File

Source: http://shapelib.maptools.org/manifest.html

Simple example program for adding a shape to an existing shape file. Requires the shpopen.c and shapefil.h files.

```c
#include <stdio.h>
#include <stdlib.h>
#include "shapefil.h"

int main( int argc, char **argv )
{
    SHPHandle       hSHP;
    int             nShapeType, nEntities;
    double          adfMinBound[4], adfMaxBound[4];

    // open the existing shape file
    hSHP = SHPOpen( "existing.shp", "rb+" );
    if( hSHP == NULL )
    {
        fprintf( stderr, "Failed to open existing.shp\n" );
        return 1;
    }

    // add a shape
    int nVertices = 3;
    double x[] = {0.0, 1.0, 0.0};
    double y[] = {0.0, 0.0, 1.0};
    SHPObject   *psShape = SHPCreateObject( SHPT_POINT, -1, 0, NULL, NULL, nVertices, x, y, NULL, NULL );
    if( psShape == NULL )
    {
        fprintf( stderr, "Failed to create shape object\n" );
        SHPClose( hSHP );
        return 1;
    }
    if( SHPWriteObject( hSHP, -1, psShape ) < 0 )
    {
        fprintf( stderr, "Failed to write shape object\n" );
        SHPDestroyObject( psShape );
        SHPClose( hSHP );
        return 1;
    }
    SHPDestroyObject( psShape );

    // close the file
    SHPClose( hSHP );

    return 0;
}
```

--------------------------------

### Get Record Count - DBFGetRecordCount()

Source: http://shapelib.maptools.org/dbf_api.html

Retrieves the number of records in a .dbf file. Requires a valid DBF handle.

```c
int DBFGetRecordCount( const DBFHandle hDBF );
```

--------------------------------

### Get Field Count - DBFGetFieldCount()

Source: http://shapelib.maptools.org/dbf_api.html

Retrieves the number of fields in a .dbf file. Requires a valid DBF handle.

```c
int DBFGetFieldCount( const DBFHandle hDBF );
```

--------------------------------

### Get Field Index - DBFGetFieldIndex()

Source: http://shapelib.maptools.org/dbf_api.html

Finds the index (0-based) of a field by its name. Case-sensitive search.

```c
int DBFGetFieldIndex( const DBFHandle hDBF, const char *pszFieldName );
```

--------------------------------

### Get DBF file information

Source: http://shapelib.maptools.org/shapelib-tools.html

Use dbfinfo to display metadata about a DBF file, including the number of columns, records, and details of each field (name, type, width, decimals).

```bash
$ dbfinfo testbase
```

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


```

--------------------------------

### Get Field Information - DBFGetFieldInfo()

Source: http://shapelib.maptools.org/dbf_api.html

Retrieves detailed information about a specific field, including its name, width, and decimal places. The pszFieldName buffer should be at least 12 characters.

```c
DBFFieldType DBFGetFieldInfo( const DBFHandle hDBF, int iField, char * pszFieldName, int * pnWidth, int * pnDecimals );
```

--------------------------------

### Get Shapefile information

Source: http://shapelib.maptools.org/shapelib-tools.html

Use shpinfo to retrieve summary information about a Shapefile, including its type, record count, and file bounds.

```bash
$ shpinfo testpolygon
```

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

```

--------------------------------

### Create a DBF File - DBFCreate()

Source: http://shapelib.maptools.org/dbf_api.html

Creates a new, empty .dbf file. The file will be created at the specified path.

```c
DBFHandle DBFCreate( const char * pszDBFFile );
```

--------------------------------

### DBFCreate()

Source: http://shapelib.maptools.org/dbf_api.html

Creates a new, empty .dbf file.

```APIDOC
## DBFCreate()

### Description
Creates a new, empty .dbf file.

### Parameters
#### Path Parameters
- **pszDBFFile** (const char *) - Required - The name of the xBase (.dbf) file to create.

### Return Value
Returns a DBFHandle on success, or NULL on failure.
```

--------------------------------

### Open a DBF File - DBFOpen()

Source: http://shapelib.maptools.org/dbf_api.html

Opens an existing .dbf file for reading or read/write access. Use 'rb' for read-only and 'rb+' for read/write.

```c
DBFHandle DBFOpen( const char * pszDBFFile, const char * pszAccess );
```

--------------------------------

### DBFOpen()

Source: http://shapelib.maptools.org/dbf_api.html

Opens an existing .dbf file for reading or read/write access.

```APIDOC
## DBFOpen()

### Description
Opens an existing .dbf file for reading or read/write access.

### Parameters
#### Path Parameters
- **pszDBFFile** (const char *) - Required - The name of the xBase (.dbf) file to access.
- **pszAccess** (const char *) - Required - The fopen() style access string. Supported values are "rb" (read-only binary) and "rb+" (read/write binary).

### Return Value
Returns a DBFHandle on success, or NULL on failure.
```

--------------------------------

### Create a new Shapefile

Source: http://shapelib.maptools.org/shapelib-tools.html

Use shpcreate to initialize a new Shapefile. Specify the desired shape type, such as 'point', 'arc', 'polygon', or 'multipoint'.

```bash
$ shpcreate testpolygon polygon
```

--------------------------------

### Generate Supported Shapefile Types

Source: http://shapelib.maptools.org/manifest.html

A simple test harness to generate each of the supported types of shapefiles. Requires the shpopen.c and shapefil.h files.

```c
#include <stdio.h>
#include <stdlib.h>
#include "shapefil.h"

int main( int argc, char **argv )
{
    SHPHandle       hSHP;
    int             i, nShapeType;

    // test each shape type
    for( i = 1; i <= 8; i++ )
    {
        nShapeType = i;

        // create the shape file
        hSHP = SHPCreate( "test.shp", nShapeType );
        if( hSHP == NULL )
        {
            fprintf( stderr, "Failed to create test.shp for shape type %d\n", nShapeType );
            continue;
        }

        // add a shape
        int nVertices = 4;
        double x[] = {0.0, 1.0, 1.0, 0.0};
        double y[] = {0.0, 0.0, 1.0, 1.0};
        SHPObject   *psShape = SHPCreateObject( nShapeType, -1, 0, NULL, NULL, nVertices, x, y, NULL, NULL );
        if( psShape == NULL )
        {
            fprintf( stderr, "Failed to create shape object for shape type %d\n", nShapeType );
            SHPClose( hSHP );
            continue;
        }
        if( SHPWriteObject( hSHP, -1, psShape ) < 0 )
        {
            fprintf( stderr, "Failed to write shape object for shape type %d\n", nShapeType );
            SHPDestroyObject( psShape );
            SHPClose( hSHP );
            continue;
        }
        SHPDestroyObject( psShape );

        // close the file
        SHPClose( hSHP );
    }

    return 0;
}
```

--------------------------------

### Dump Quadtree Information

Source: http://shapelib.maptools.org/manifest.html

A simple program mainly showing information on quadtrees built using the quadtree API. Requires the shpopen.c and shapefil.h files.

```c
#include <stdio.h>
#include <stdlib.h>
#include "shapefil.h"

int main( int argc, char **argv )
{
    SHPHandle       hSHP;
    int             nShapeType, nEntities;
    double          adfMinBound[4], adfMaxBound[4];
    int             *panFID;

    // open the shape file
    hSHP = SHPOpen( "test.shp", "rb" );
    if( hSHP == NULL )
    {
        fprintf( stderr, "Failed to open test.shp\n" );
        return 1;
    }

    // get shapefile metadata
    SHPGetInfo( hSHP, &nShapeType, &nEntities, adfMinBound, adfMaxBound );

    // build quadtree
    panFID = (int *)malloc( sizeof(int) * nEntities );
    for( int i = 0; i < nEntities; i++ ) panFID[i] = i;
    int nTreeSize = SHPBuildQuadTree( hSHP, 8, adfMinBound, adfMaxBound, 0, NULL );
    if( nTreeSize < 0 )
    {
        fprintf( stderr, "Failed to build quadtree\n" );
        free( panFID );
        SHPClose( hSHP );
        return 1;
    }

    // dump quadtree information
    printf( "Quadtree Size: %d\n", nTreeSize );
    for( int i = 0; i < nTreeSize; i++ )
    {
        int nShapeCount;
        int *panShapes;
        SHPGetQuadNode( hSHP, i, &nShapeCount, &panShapes );
        printf( "Node %d: Shapes=%d\n", i, nShapeCount );
        for( int j = 0; j < nShapeCount; j++ )
        {
            printf( "  FID: %d\n", panShapes[j] );
        }
    }

    // clean up
    free( panFID );
    SHPClose( hSHP );

    return 0;
}
```

--------------------------------

### Create a new DBF file

Source: http://shapelib.maptools.org/shapelib-tools.html

Use dbfcreate to define the structure of a new xBase file. Specify string fields with '-s' and numeric fields with '-n', including width and decimal places for numeric types.

```bash
$ dbfcreate testbase -s NAME 20, -n AREA 9 3, -n VALUE 9 2
```

--------------------------------

### Get Native DBF Field Type

Source: http://shapelib.maptools.org/dbf_api.html

Retrieves the native data type of a field in a DBF file. Returns a character code representing the type. Requires a valid DBF handle and field index. Returns ' ' if the field index is out of range.

```c
char DBFGetNativeFieldType( const DBFHandle hDBF, int iField );
```

--------------------------------

### Run Stream Test Script 2

Source: http://shapelib.maptools.org/manifest.html

A test script that should produce stream2.out.

```bash
./makeshape.sh stream2.sh
```

--------------------------------

### SHPCreate Function Signature and Parameters

Source: http://shapelib.maptools.org/shp_api.html

Creates a new, empty shapefile for storing shapes of a specified type. The file is created with the given name and shape type.

```c
SHPHandle SHPCreate( const char * pszShapeFile, int nShapeType );

  pszShapeFile:		The name of the layer to access.  This can be the
			name of either the .shp or the .shx file or can
			just be the path plus the basename of the pair.

  nShapeType:		The type of shapes to be stored in the newly created
			file.  It may be either SHPT_POINT, SHPT_ARC,
			SHPT_POLYGON or SHPT_MULTIPOINT.
```

--------------------------------

### SHPCreate

Source: http://shapelib.maptools.org/shp_api.html

Creates a new, empty shape file with a specified shape type.

```APIDOC
## SHPCreate()

### Description
Creates a new, empty shape file with a specified shape type.

### Method
`SHPHandle SHPCreate( const char * pszShapeFile, int nShapeType );`

### Parameters
#### Path Parameters
- **pszShapeFile** (const char *) - The name of the layer to access. This can be the name of either the .shp or the .shx file or can just be the path plus the basename of the pair.
- **nShapeType** (int) - The type of shapes to be stored in the newly created file. It may be either SHPT_POINT, SHPT_ARC, SHPT_POLYGON or SHPT_MULTIPOINT.

### Return Value
- **SHPHandle** - A handle to the newly created shape file.
```

--------------------------------

### Create Simple SHP Object

Source: http://shapelib.maptools.org/shp_api.html

Use to create simple SHP objects like points or polygons. Free resources with SHPDestroyObject().

```c
SHPObject *
     SHPCreateSimpleObject( int nSHPType, int nVertices,
			    const double *padfX, const double * padfY,
			    const double *padfZ );
```

--------------------------------

### SHPCreateObject

Source: http://shapelib.maptools.org/shp_api.html

Creates a more sophisticated SHPObject with support for multiple parts and M values.

```APIDOC
## SHPCreateObject()

### Description
Creates a more sophisticated SHPObject with support for multiple parts and M values.

### Parameters
- **nSHPType** (int) - The SHPT_ type of the object to be created, such as SHPT_POINT, or SHPT_POLYGON.
- **iShape** (int) - The shapeid to be recorded with this shape.
- **nParts** (int) - The number of parts for this object. If this is zero for ARC, or POLYGON type objects, a single zero valued part will be created internally.
- **panPartStart** (const int *) - The list of zero based start vertices for the rings (parts) in this object. The first should always be zero. This may be NULL if nParts is 0.
- **panPartType** (const int *) - The type of each of the parts. This is only meaningful for MULTIPATCH files. For all other cases this may be NULL, and will be assumed to be SHPP_RING.
- **nVertices** (int) - The number of vertices being passed in padfX, padfY, and padfZ.
- **padfX** (const double *) - An array of nVertices X coordinates of the vertices for this object.
- **padfY** (const double *) - An array of nVertices Y coordinates of the vertices for this object.
- **padfZ** (const double *) - An array of nVertices Z coordinates of the vertices for this object. This may be NULL in which case they are all assumed to be zero.
- **padfM** (const double *) - An array of nVertices M (measure values) of the vertices for this object. This may be NULL in which case they are all assumed to be zero.

### Notes
The SHPDestroyObject() function should be used to free resources associated with an object allocated with SHPCreateObject(). This function computes a bounding box for the SHPObject from the given vertices.
```

--------------------------------

### Dump SHP File Vertices

Source: http://shapelib.maptools.org/manifest.html

Simple program for dumping all the vertices in a shapefile with an indication of the parts. Requires the shpopen.c and shapefil.h files.

```c
#include <stdio.h>
#include <stdlib.h>
#include "shapefil.h"

int main( int argc, char **argv )
{
    SHPHandle       hSHP;
    int             nShapeType, nEntities;
    double          adfMinBound[4], adfMaxBound[4];

    // open the shape file
    hSHP = SHPOpen( "test.shp", "rb" );
    if( hSHP == NULL )
    {
        fprintf( stderr, "Failed to open test.shp\n" );
        return 1;
    }

    // get shapefile metadata
    SHPGetInfo( hSHP, &nShapeType, &nEntities, adfMinBound, adfMaxBound );

    printf( "Shapefile Type: %d\n", nShapeType );
    printf( "Number of Shapes: %d\n", nEntities );
    printf( "Bounds: (%.1f, %.1f) - (%.1f, %.1f)\n",
            adfMinBound[0], adfMinBound[1],
            adfMaxBound[0], adfMaxBound[1] );

    // read and print shapes
    for( int i = 0; i < nEntities; i++ )
    {
        SHPObject   *psShape = SHReadObject( hSHP, i );
        if( psShape == NULL )
        {
            fprintf( stderr, "Failed to read shape %d\n", i );
            continue;
        }

        printf( "Shape %d: Type=%d, Vertices=%d, Parts=%d\n",
                i, psShape->nShapeType, psShape->nVertices, psShape->nParts );

        // print vertices
        for( int j = 0; j < psShape->nVertices; j++ )
        {
            printf( "  Vertex %d: (%.1f, %.1f)\n", j, psShape->padfX[j], psShape->padfY[j] );
        }

        // print parts
        for( int j = 0; j < psShape->nParts; j++ )
        {
            printf( "  Part %d: Index=%d, Type=%d\n", j, psShape->panPartStart[j], psShape->panPartType[j] );
        }

        SHPDestroyObject( psShape );
    }

    // close the file
    SHPClose( hSHP );

    return 0;
}
```

--------------------------------

### SHPCreateSimpleObject

Source: http://shapelib.maptools.org/shp_api.html

Creates a simple SHPObject with the specified type and vertices. Suitable for objects without complex part structures.

```APIDOC
## SHPCreateSimpleObject()

### Description
Creates a simple SHPObject with the specified type and vertices. Suitable for objects without complex part structures.

### Parameters
- **nSHPType** (int) - The SHPT_ type of the object to be created, such as SHPT_POINT, or SHPT_POLYGON.
- **nVertices** (int) - The number of vertices being passed in padfX, padfY, and padfZ.
- **padfX** (const double *) - An array of nVertices X coordinates of the vertices for this object.
- **padfY** (const double *) - An array of nVertices Y coordinates of the vertices for this object.
- **padfZ** (const double *) - An array of nVertices Z coordinates of the vertices for this object. This may be NULL in which case they are all assumed to be zero.

### Notes
Use the SHPCreateObject() function for more sophisticated objects. The SHPDestroyObject() function should be used to free resources associated with an object allocated with SHPCreateSimpleObject(). This function computes a bounding box for the SHPObject from the given vertices.
```

--------------------------------

### Dump DBF file contents and header

Source: http://shapelib.maptools.org/shapelib-tools.html

Use dbfdump to view the contents of a DBF file. Options include '-h' for header info, '-r' for raw numeric output, and '-m' for one-line-per-field output.

```bash
$ dbfdump -h testbase.dbf
```

```text
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 
```

--------------------------------

### SHPGetInfo Function Signature and Parameters

Source: http://shapelib.maptools.org/shp_api.html

Retrieves general information about an opened shapefile, including the number of entities, shape type, and bounding box.

```c
void SHPGetInfo( const SHPHandle hSHP, int * pnEntities, int * pnShapeType,
                 double * padfMinBound, double * padfMaxBound );

  hSHP:			The handle previously returned by SHPOpen()
			or SHPCreate().

  pnEntities:		A pointer to an integer into which the number of
			entities/structures should be placed.  May be NULL.

  pnShapetype:		A pointer to an integer into which the shapetype
			of this file should be placed.  Shapefiles may contain
		
either SHPT_POINT, SHPT_ARC, SHPT_POLYGON or
			SHPT_MULTIPOINT entities.  This may be NULL.

  padfMinBound:		The X, Y, Z and M minimum values will be placed into
                        this four entry array.  This may be NULL.

  padfMaxBound:		The X, Y, Z and M maximum values will be placed into
                        this four entry array.  This may be NULL.
```

--------------------------------

### SHPOpen

Source: http://shapelib.maptools.org/shp_api.html

Opens a shape file for reading or read/write access. It can accept the .shp or .shx filename, or just the base path.

```APIDOC
## SHPOpen()

### Description
Opens a shape file for reading or read/write access. It can accept the .shp or .shx filename, or just the base path.

### Method
`SHPHandle SHPOpen( const char * pszShapeFile, const char * pszAccess );`

### Parameters
#### Path Parameters
- **pszShapeFile** (const char *) - The name of the layer to access. This can be the name of either the .shp or the .shx file or can just be the path plus the basename of the pair.
- **pszAccess** (const char *) - The fopen() style access string. At this time only "rb" (read-only binary) and "rb+" (read/write binary) should be used.

### Return Value
- **SHPHandle** - A handle to the opened shape file.
```

--------------------------------

### Quadtree Spatial Search

Source: http://shapelib.maptools.org/manifest.html

Implements a simple quadtree algorithm for fast spatial searches of shapefiles. Requires the shpopen.c and shapefil.h files.

```c
#include <stdio.h>
#include <stdlib.h>
#include "shapefil.h"

int main( int argc, char **argv )
{
    SHPHandle       hSHP;
    int             nShapeType, nEntities;
    double          adfMinBound[4], adfMaxBound[4];
    int             *panFID;
    int             nTotalShapes, nShapesRead;

    // open the shape file
    hSHP = SHPOpen( "test.shp", "rb" );
    if( hSHP == NULL )
    {
        fprintf( stderr, "Failed to open test.shp\n" );
        return 1;
    }

    // get shapefile metadata
    SHPGetInfo( hSHP, &nShapeType, &nEntities, adfMinBound, adfMaxBound );

    // build quadtree
    panFID = (int *)malloc( sizeof(int) * nEntities );
    for( int i = 0; i < nEntities; i++ ) panFID[i] = i;
    int nTreeSize = SHPBuildQuadTree( hSHP, 8, adfMinBound, adfMaxBound, 0, NULL );
    if( nTreeSize < 0 )
    {
        fprintf( stderr, "Failed to build quadtree\n" );
        free( panFID );
        SHPClose( hSHP );
        return 1;
    }

    // perform spatial search
    double x[] = {0.5, 0.5};
    double y[] = {0.5, 0.5};
    int nSearchSize = SHPPointInQuadtree( hSHP, x[0], y[0], panFID, &nTotalShapes );
    if( nSearchSize < 0 )
    {
        fprintf( stderr, "Failed to perform spatial search\n" );
        free( panFID );
        SHPClose( hSHP );
        return 1;
    }

    printf( "Shapes found at (%.1f, %.1f):\n", x[0], y[0] );
    for( int i = 0; i < nTotalShapes; i++ )
    {
        printf( "  FID: %d\n", panFID[i] );
    }

    // clean up
    free( panFID );
    SHPClose( hSHP );

    return 0;
}
```

--------------------------------

### Center Polygons to Points with shpcentrd

Source: http://shapelib.maptools.org/shapelib-tools.html

Converts polygon shapefiles to point shapefiles, with each point representing the center of a polygon. Specify the input polygon shapefile and the desired output point shapefile name.

```bash
$ shpcentrd apolygonfile pointcentrd
```

--------------------------------

### SHPOpen Function Signature and Parameters

Source: http://shapelib.maptools.org/shp_api.html

Opens a shapefile for reading or writing. Specify the file path and access mode ('rb' for read-only, 'rb+' for read/write).

```c
SHPHandle SHPOpen( const char * pszShapeFile, const char * pszAccess );

  pszShapeFile:		The name of the layer to access.  This can be the
			name of either the .shp or the .shx file or can
			just be the path plus the basename of the pair.

  pszAccess:		The fopen() style access string.  At this time only
			"rb" (read-only binary) and "rb+" (read/write binary)
			should be used.
```

--------------------------------

### Add data to a DBF file

Source: http://shapelib.maptools.org/shapelib-tools.html

Use dbfadd to insert records into an existing DBF file. Ensure the number and order of provided values match the file's defined fields.

```bash
$ dbfadd testbase.dbf REGION1 25.656 150.22
```

--------------------------------

### SHPComputeExtents

Source: http://shapelib.maptools.org/shp_api.html

Computes and updates the bounding box for an existing SHPObject in place.

```APIDOC
## SHPComputeExtents()

### Description
Computes and updates the bounding box for an existing SHPObject in place.

### Parameters
- **psObject** (SHPObject *) - An existing shape object to be updated in place.

### Notes
This function modifies the provided SHPObject directly.
```

--------------------------------

### Export Shapefile to DXF with shpdxf

Source: http://shapelib.maptools.org/shapelib-tools.html

Exports an existing shapefile to DXF format. Requires the shapefile name and an ID field for reference. This tool is useful for interoperability with CAD software.

```bash
$ shpdxf testshapefile IDFIELD
```

--------------------------------

### SHPGetInfo

Source: http://shapelib.maptools.org/shp_api.html

Retrieves information about the shape file, including the number of entities, shape type, and bounding box.

```APIDOC
## SHPGetInfo()

### Description
Retrieves information about the shape file, including the number of entities, shape type, and bounding box.

### Method
`void SHPGetInfo( const SHPHandle hSHP, int * pnEntities, int * pnShapeType, double * padfMinBound, double * padfMaxBound );`

### Parameters
#### Path Parameters
- **hSHP** (const SHPHandle) - The handle previously returned by SHPOpen() or SHPCreate().
- **pnEntities** (int *) - A pointer to an integer into which the number of entities/structures should be placed. May be NULL.
- **pnShapeType** (int *) - A pointer to an integer into which the shapetype of this file should be placed. May be NULL.
- **padfMinBound** (double *) - The X, Y, Z and M minimum values will be placed into this four entry array. May be NULL.
- **padfMaxBound** (double *) - The X, Y, Z and M maximum values will be placed into this four entry array. May be NULL.
```

--------------------------------

### Create Complex SHP Object

Source: http://shapelib.maptools.org/shp_api.html

Use for creating more sophisticated SHP objects, including those with multiple parts. Free resources with SHPDestroyObject().

```c
SHPObject *
     SHPCreateObject( int nSHPType, int iShape,
                      int nParts, const int * panPartStart,
                      const int * panPartType,
                      int nVertices, const double *padfX, const double * padfY,
                      const double *padfZ, const double *padfM );
```

--------------------------------

### Dump Shapefile contents

Source: http://shapelib.maptools.org/shapelib-tools.html

Use shpdump to display the contents and metadata of a Shapefile. The '-validate' option can be used to check for invalid ring orderings.

```bash
$ shpdump testpolygon
```

```text
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)

```

--------------------------------

### DBFGetRecordCount()

Source: http://shapelib.maptools.org/dbf_api.html

Retrieves the number of records in a .dbf file.

```APIDOC
## DBFGetRecordCount()

### Description
Retrieves the number of records in a .dbf file.

### Parameters
#### Path Parameters
- **hDBF** (DBFHandle) - Required - The access handle for the file, as returned by DBFOpen() or DBFCreate().

### Return Value
Returns the number of records in the .dbf file.
```

--------------------------------

### DBF Field Types

Source: http://shapelib.maptools.org/dbf_api.html

Enumeration defining the possible types for fields within a .dbf file.

```c
typedef enum {
      FTString,		/* fixed length string field        */
      FTInteger,		/* numeric field with no decimals   */
      FTDouble,		/* numeric field with decimals      */
      FTLogical,		/* logical field                    */
      FTDate,		/* date field                       */
      FTInvalid		/* not a recognised field type      */
    } DBFFieldType;
```

--------------------------------

### DBFGetFieldInfo()

Source: http://shapelib.maptools.org/dbf_api.html

Retrieves information about a specific field in a .dbf file.

```APIDOC
## DBFGetFieldInfo()

### Description
Retrieves information about a specific field in a .dbf file, including its name, width, and decimal precision.

### Parameters
#### Path Parameters
- **hDBF** (DBFHandle) - Required - The access handle for the file, as returned by DBFOpen() or DBFCreate().
- **iField** (int) - Required - The field index to query (0 to n-1, where n is the field count).
- **pszFieldName** (char *) - Optional - If not NULL, the name of the requested field will be written to this buffer (at least 12 characters recommended).
- **pnWidth** (int *) - Optional - If not NULL, the width of the requested field will be returned here.
- **pnDecimals** (int *) - Optional - If not NULL, the number of decimal places for the field will be returned here.

### Return Value
Returns the type of the field (DBFFieldType). Possible values are FTString, FTInteger, FTDouble, FTLogical, FTDate, FTInvalid.
```

--------------------------------

### Write SHP Object to File

Source: http://shapelib.maptools.org/shp_api.html

Writes a shape object to a shapefile. Use -1 for iShape to write new shapes. Requires a handle opened with SHPOpen() or SHPCreate().

```c
int SHPWriteObject( SHPHandle hSHP, int iShape, const SHPObject *psObject );
```

--------------------------------

### DBFGetFieldCount()

Source: http://shapelib.maptools.org/dbf_api.html

Retrieves the number of fields in a .dbf file.

```APIDOC
## DBFGetFieldCount()

### Description
Retrieves the number of fields in a .dbf file.

### Parameters
#### Path Parameters
- **hDBF** (DBFHandle) - Required - The access handle for the file, as returned by DBFOpen() or DBFCreate().

### Return Value
Returns the number of fields in the .dbf file.
```

--------------------------------

### DBFAddField()

Source: http://shapelib.maptools.org/dbf_api.html

Adds a new field to a .dbf file.

```APIDOC
## DBAddField()

### Description
Adds a new field to a .dbf file. Note that not all xBase field types can be created (e.g., date fields).

### Parameters
#### Path Parameters
- **hDBF** (DBFHandle) - Required - The access handle for the file, as returned by DBFOpen() or DBFCreate().
- **pszFieldName** (const char *) - Required - The name of the new field (max 11 characters). Avoid special characters like spaces.
- **eType** (DBFFieldType) - Required - The type of the new field. Use FTString, FTInteger, or FTDouble.
- **nWidth** (int) - Required - The width of the field. For FTString, it's the max string length. For FTInteger, it's the max number of digits. For FTDouble, it's the total size.
- **nDecimals** (int) - Required - The number of decimal places for FTDouble fields. Should be zero for other types.

### Return Value
Returns the field number of the new field, or -1 if the addition failed.
```

--------------------------------

### DBFClose

Source: http://shapelib.maptools.org/dbf_api.html

Closes the access handle for a DBF file.

```APIDOC
## DBFClose()

### Description
Closes the access handle for a DBF file, releasing associated resources.

### Parameters
#### Path Parameters
- **hDBF** (DBFHandle) - Required - The access handle for the file to be closed.

### Returns
void
```

--------------------------------

### SHPClose

Source: http://shapelib.maptools.org/shp_api.html

Closes an opened shape file and frees associated resources.

```APIDOC
## SHPClose()

### Description
Closes an opened shape file and frees associated resources.

### Method
`void SHPClose( SHPHandle hSHP );`

### Parameters
#### Path Parameters
- **hSHP** (SHPHandle) - The handle previously returned by SHPOpen() or SHPCreate().
```

--------------------------------

### Add Field to DBF - DBFAddField()

Source: http://shapelib.maptools.org/dbf_api.html

Adds a new field to an open .dbf file. Field names are limited to 11 characters and should avoid special characters. Returns the new field number or -1 on failure.

```c
int DBFAddField( DBFHandle hDBF, const char * pszFieldName, DBFFieldType eType, int nWidth, int nDecimals );
```

--------------------------------

### Fix Shapefile ring order

Source: http://shapelib.maptools.org/shapelib-tools.html

Use shprewind to create a new Shapefile with corrected ring orderings from an input Shapefile.

```bash
$ shprewind badshapefile newshapefile
```

--------------------------------

### Concatenate DBF files

Source: http://shapelib.maptools.org/shapelib-tools.html

Use dbfcat to merge two DBF files. The '-f' option forces data conversion if types differ or nulls exist, and '-v' enables verbose output.

```bash
$ dbfcat -v testbase1 testbase2
```

--------------------------------

### Concatenate Shapefiles

Source: http://shapelib.maptools.org/shapelib-tools.html

Use shpcat to append the contents of one Shapefile to another.

```bash
$ shpcat shapefile1 shapefile2
```

--------------------------------

### DBFReadDoubleAttribute

Source: http://shapelib.maptools.org/dbf_api.html

Reads a double-precision floating-point attribute from a DBF file.

```APIDOC
## DBFReadDoubleAttribute()

### Description
Reads a double-precision floating-point attribute from a specified record and field in a DBF file.

### Parameters
#### Path Parameters
- **hDBF** (DBFHandle) - Required - The access handle for the file to be queried.
- **iShape** (int) - Required - The record number (shape number) from which the field value should be read.
- **iField** (int) - Required - The field within the selected record that should be read.

### Returns
double - The value of the double attribute.
```

--------------------------------

### DBFGetFieldIndex()

Source: http://shapelib.maptools.org/dbf_api.html

Retrieves the index of a field by its name.

```APIDOC
## DBFGetFieldIndex()

### Description
Retrieves the index of a field by its name.

### Parameters
#### Path Parameters
- **hDBF** (DBFHandle) - Required - The access handle for the file, as returned by DBFOpen() or DBFCreate().
- **pszFieldName** (const char *) - Required - Name of the field to search for.

### Return Value
Returns the index of the field (0-based), or -1 if the field is not found.
```

--------------------------------

### DBFWriteDoubleAttribute

Source: http://shapelib.maptools.org/dbf_api.html

Writes a double-precision floating-point attribute to a DBF file.

```APIDOC
## DBFWriteDoubleAttribute()

### Description
Writes a double-precision floating-point value to a specified record and field in a DBF file.

### Parameters
#### Path Parameters
- **hDBF** (DBFHandle) - Required - The access handle for the file to be written.
- **iShape** (int) - Required - The record number (shape number) to which the field value should be written.
- **iField** (int) - Required - The field within the selected record that should be written.
- **dFieldValue** (double) - Required - The floating-point value that should be written.

### Returns
int - Success status (typically 1 for success, 0 for failure).
```

--------------------------------

### Write Integer Attribute to DBF

Source: http://shapelib.maptools.org/dbf_api.html

Writes an integer attribute to a specified record and field in a DBF file. Requires a valid DBF handle, record number, field index, and the integer value to write.

```c
int DBFWriteIntegerAttribute( DBFHandle hDBF, int iShape, int iField,
                              int nFieldValue );
```

--------------------------------

### Read Integer Attribute - DBFReadIntegerAttribute()

Source: http://shapelib.maptools.org/dbf_api.html

Reads an integer value from a specific record and field in a .dbf file. Requires a valid DBF handle.

```c
int DBFReadIntegerAttribute( DBFHandle hDBF, int iShape, int iField );
```

--------------------------------

### Close DBF File Handle

Source: http://shapelib.maptools.org/dbf_api.html

Closes the access handle for a DBF file, releasing associated resources. Requires a valid DBF handle.

```c
void DBFClose( DBFHandle hDBF );
```

--------------------------------

### Write Double Attribute to DBF

Source: http://shapelib.maptools.org/dbf_api.html

Writes a double-precision floating-point attribute to a specified record and field in a DBF file. Requires a valid DBF handle, record number, field index, and the double value to write.

```c
int DBFWriteDoubleAttribute( DBFHandle hDBF, int iShape, int iField,
                             double dFieldValue );
```

--------------------------------

### SHPReadObject Function Signature and Parameters

Source: http://shapelib.maptools.org/shp_api.html

Reads a specific shape object from an opened shapefile by its entity index. Note that bounds in the returned SHPObject may not always be accurate, especially for point types.

```c
SHPObject *SHPReadObject( const SHPHandle hSHP, int iShape );

  hSHP:			The handle previously returned by SHPOpen()
			or SHPCreate().

  iShape:		The entity number of the shape to read.  Entity
			numbers are between 0 and nEntities-1 (as returned
			by SHPGetInfo()).
```

--------------------------------

### DBFWriteNULLAttribute

Source: http://shapelib.maptools.org/dbf_api.html

Writes a NULL attribute to a DBF file.

```APIDOC
## DBFWriteNULLAttribute()

### Description
Writes a NULL value to a specified record and field in a DBF file.

### Parameters
#### Path Parameters
- **hDBF** (DBFHandle) - Required - The access handle for the file to be written.
- **iShape** (int) - Required - The record number (shape number) to which the field value should be written.
- **iField** (int) - Required - The field within the selected record that should be written.

### Returns
int - Success status (typically 1 for success, 0 for failure).
```
Tokens:
Raw