Shapefile SHP

Read and write Shapefile SHP and SHX files within Node JS.

Important: This is an ESM NodeJS only package.

Installation

npm install @coderundebug/shapefile-shp

Contents

• Introduction
• Quick Functions
• Shapefile SHP Reader
• Shapefile SHP Writer
• Shapefile SHX Reader
• Shapefile SHX Writer

Introduction

A Shapefile is a selection of files grouped together into a ZIP file. Each file contains different information that together is used to detail geographic map information. It comes with a *.shp file that gives the vector data, a *.shx file that is an index of the vector data, and a *.dbf file that is a dBase 3 database file containing attribute data about the different map areas.

This package is used to read and write the *.shp and *.shx data. Each type of shape has its own class object, which allows you to create a Shapefile SHP object and have it written to a file (with the index).

import { ShapefileShp } from "@coderundebug/shapefile-shp";
import { ShapefileShpReader } from "@coderundebug/shapefile-shp";

// Load in all the shapefile SHP data
const shapefileShp = ShapefileShpReader.load(sphPath);

// Log some of the details
console.log(shapefileShp.shapeType);
console.log(shapefileShp.shapeList.length);

The simplist method of loading in all the shapefile SHP data is to use the load function.

import { ShapefileShpReader } from "@coderundebug/shapefile-shp";
import { ShapefileShxReader } from "@coderundebug/shapefile-shp";

// Create reader objects
const shapefileShpReader = new ShapefileShpReader();
const shapefileShxReader = new ShapefileShxReader();

// Open the files
await shapefileShpReader.open(shpPath);
await shapefileShxReader.open(shxPath);

// Get index and then the polygon for the third shape
let shapeIndex = await shapefileShxReader.read(3);
let polygon = await shapefileShpReader.read(shapeIndex.offset);

// Log polygon
console.log(polygon);

// Close the files
await shapefileShpReader.close();
await shapefileShxReader.close();

Here we are using the index file to quickly find the location of the third polygon and read it in.

Below are the different shape type objects that can be used. You will need to search for the shapefile file format to better understand how the information is used to create map information.

import { Multipatch } from "@coderundebug/shapefile-shp";
import { Multipoint } from "@coderundebug/shapefile-shp";
import { MultipointM } from "@coderundebug/shapefile-shp";
import { MultipointZ } from "@coderundebug/shapefile-shp";
import { NullShape } from "@coderundebug/shapefile-shp";
import { Point } from "@coderundebug/shapefile-shp";
import { PointM } from "@coderundebug/shapefile-shp";
import { PointZ } from "@coderundebug/shapefile-shp";
import { Polygon } from "@coderundebug/shapefile-shp";
import { PolygonM } from "@coderundebug/shapefile-shp";
import { PolygonZ } from "@coderundebug/shapefile-shp";
import { Polyline } from "@coderundebug/shapefile-shp";
import { PolylineM } from "@coderundebug/shapefile-shp";
import { PolylineZ } from "@coderundebug/shapefile-shp";

// Other objects
import { BoundingBox } from "@coderundebug/shapefile-shp";
import { ShapeIndex } from "@coderundebug/shapefile-shp";
import { ShapeType } from "@coderundebug/shapefile-shp";
import { ShapefileShp } from "@coderundebug/shapefile-shp";
import { ShapefileShx } from "@coderundebug/shapefile-shp";

Quick Functions

There are some static functions that can help you perform some quick tasks.

Load

Load all the vector data from the shapefile SHP file into a ShapefileShp object.

ShapefileShpReader.load(shpPath);

Arguments

• shpPath - The full path of the shapefile SHP file to open.

Returns

A promise that resolves with a ShapefileShp object.

// Load in all the shapefile SHP data
const shapefileShp = await ShapefileShpReader.load(sphPath);

// For each shape
for (let index = 0; index < shapefileShp.shapeList.length; index++) {
    // Get shape
    const shape = shapefileShp.shapeList[index];

    // Log shape
    console.log(shape);
}

Save

Save the ShapefileShp object to a shapefile SHP file. This also creates the *.shx index file.

ShapefileShpWriter.save(shpPath, shapefileShp);

Arguments

• shpPath - The full path of the shapefile SHP file to open.

• shapefileShp - The ShapefileShp object that contains all the shape information.

Returns

A promise.

// Create the ShapefileShp object.
const shapefileShp = new ShapefileShp();

// Create point object
const point = new Point();
point.x = 1.23;
point.y = 2.34;

// Add point to shapefile SHP shape list
shapefileShp.shapeList.push(point);

// You will need to make sure the other Shapefile SHP properties are set correctly

// Save the data to the shapefile SHP data
await ShapefileShpWrite.save(sphPath, shapefileShp);

Shapefile SHP Reader

This class is used to read in shapefile SHP data.

Open

Open the shapefile SHP file.

open(shpPath);

Arguments

• shpPath - The full path of the shapefile SHP file to open.

Returns

A promise.

Example

import { ShapefileShpReader } from "@coderundebug/shapefile-shp";

// Create a shapefile SHP reader object
const shapefileShpReader = new ShapefileShpReader();

// Open the file
await shapefileShpReader.open('c:\\shapefile\\usa.shp');

// Read shapes...
// Close file...

Close

Close the already opened shapefile SHP file.

close();

Returns

A promise.

Example

import { ShapefileShpReader } from "@coderundebug/shapefile-shp";

// Create a shapefile SHP reader object
const shapefileShpReader = new ShapefileShpReader();

// Open the file
await shapefileShpReader.open('c:\\shapefile\\usa.shp');

// Read shapes...

// Close the file
await shapefileShpReader.close();

Read

Read in the next shape within the shapefile SHP file.

read([offset]);

Arguments

• [offset] - The offset within the shapefile SHP file where the shape record begins. This offset normally comes from the index file. If not used then the next shape record will be read.

Returns

A promise resolving to a one of the available shape objects, or null if the end of the file is reached.

Example

import { ShapefileShpReader } from "@coderundebug/shapefile-shp";

// Create a shapefile SHP reader object
const shapefileShpReader = new ShapefileShpReader();

// Open the file
await shapefileShpReader.open('c:\\shapefile\\usa.shp');

// Read next shapes
const shape1 = await shapefileShpReader.read();
const shape2 = await shapefileShpReader.read();
const shape3 = await shapefileShpReader.read();

// Close the file
await shapefileShpReader.close();

Properties

There are a number of different properties available.

shapefileShp

After opening the file you can get the shapefile SHP header information.

recordNumber

After reading in a record you can get it's record number value, which starts at 1.

contentLength

After reading in a record you can get the total content length (in bytes) that was read in.

offset

After reading in the record you can get the offset of the record where it was located within the SHP file.

Shapefile SHP Writer

This class is used to create shapefile SHP data.

Open

Open the shapefile SHP file to write to. This will remove any existing file.

open(shpPath);

Arguments

• shpPath - The full path of the shapefile SHP file to open.

Returns

A promise.

Example

import { ShapefileShpWriter } from "@coderundebug/shapefile-shp";

// Create a shapefile SHP writer object
const shapefileShpWriter = new ShapefileShpWriter();

// Open the file
await shapefileShpWriter.open('c:\\shapefile\\test.shp');

// Write shapes...
// Update header...
// Close file...

Close

Close the shapefile SHP file.

close();

Returns

A promise.

Example

import { ShapefileShpWriter } from "@coderundebug/shapefile-shp";

// Create a shapefile SHP writer object
const shapefileShpWriter = new ShapefileShpWriter();

// Open the file
await shapefileShpWriter.open('c:\\shapefile\\test.shp');

// Write shapes...
// Update header...

// Close file
await shapefileShpWriter.close();

Write

Write a shape object to the shapefile SHP file.

write(shape);

Arguments

• shape - The shape object to write. This can be one of the may different shape objects available.

Returns

A promise.

Example

import { Point } from "@coderundebug/shapefile-shp";
import { ShapefileShpWriter } from "@coderundebug/shapefile-shp";

// Create a shapefile SHP writer object
const shapefileShpWriter = new ShapefileShpWriter();

// Open the file
await shapefileShpWriter.open('c:\\shapefile\\test.shp');

// Create point shape
const point = new Point();
point.x = 1.23;
point.y = 2.34;

// Write shapes
await shapefileShpWriter.write(point);

// Update header...

// Close file
await shapefileShpWriter.close();

Update Header

Update the ShapefileShp object header information in the shapefile SHP file. As you write more and more shapes to the file, the overall file length will increase. Also, the minimum and maximum ranges will also be updated. After you have finished writing all the shapes to the file, you can update the properties within the ShapefileShp object and have it written to the file.

updateHeader(shapefileShp);

Arguments

• shapefileShp - The shapefile SHP object that contains the header information that will get written to the file.

Returns

A promise.

Example

import { Point } from "@coderundebug/shapefile-shp";
import { ShapefileShpWriter } from "@coderundebug/shapefile-shp";

// Create a shapefile SHP writer object
const shapefileShpWriter = new ShapefileShpWriter();

// Open the file
await shapefileShpWriter.open('c:\\shapefile\\test.shp');

// Create point shape
const point = new Point();
point.x = 1.23;
point.y = 2.34;

// Write shapes
await shapefileShpWriter.write(point);

// Set file length (header = 100) + (record header = 8) + (point content length = 20)
shapefileShpWriter.shapefileShp.fileLength = 100 + 8 + 20;

// Update header
await shapefileShpWriter.updateHeader(shapefileShpWriter.shapefileShp);

// Close file
await shapefileShpWriter.close();

Properties

There are a number of different properties available.

recordNumber

After writing a record you can get it's record number value, which starts at 1.

contentLength

After writing a record you can get the total content length (in bytes) that was just written in.

offset

After writing the record you can get the offset of the record where it is located within the SHP file.

Shapefile SHX Reader

This class is used to read in shapefile SHX index files.

Open

Open the shapefile SHX file.

open(shxPath);

Arguments

• shxPath - The full path of the shapefile SHX file to open.

Returns

A promise.

Example

import { ShapefileShxReader } from "@coderundebug/shapefile-shp";

// Create a shapefile SHX reader object
const shapefileShxReader = new ShapefileShxReader();

// Open the file
await shapefileShxReader.open('c:\\shapefile\\test.shx');

// Read index...
// Close file...

Close

Close the shapefile SHX file.

close();

Returns

A promise.

Example

import { ShapefileShxReader } from "@coderundebug/shapefile-shp";

// Create a shapefile SHX reader object
const shapefileShxReader = new ShapefileShxReader();

// Open the file
await shapefileShxReader.open('c:\\shapefile\\test.shx');

// Read index...

// Close file
await shapefileShxReader.close();

Read

Read in the next shape index within the shapefile SHX file.

read([number]);

Arguments

• [number] - The record number to get the index for. If this is not used then the next index is read in. You can use this to get the index of a shape record anywhere within the SHX file.

Returns

A promise resolving to a ShapeIndex object or null if the end of the file is reached.

Example

import { ShapefileShxReader } from "@coderundebug/shapefile-shp";

// Create a shapefile SHX reader object
const shapefileShxReader = new ShapefileShxReader();

// Open the file
await shapefileShxReader.open('c:\\shapefile\\test.shx');

// Read shape index for the 10th shape
const shapeIndex = await shapefileShxReader.read(10);

// Use the offset to read in the 10th shape within the SHP file

// Close file
await shapefileShxReader.close();

Properties

shapefileShx

After the file has been open you can get the ShapefileShx header object.

Shapefile SHX Writer

This class is used to create shapefile SHX index files.

Open

Open the shapefile SHX index file to write to. This will remove any existing file.

open(shxPath);

Arguments

• shxPath - The full path of the shapefile SHX index file to open.

Returns

A promise.

Example

import { ShapefileShxWriter } from "@coderundebug/shapefile-shp";

// Create a shapefile SHX writer object
const shapefileShxWriter = new ShapefileShxWriter();

// Open the file
await shapefileShxWriter.open('c:\\shapefile\\test.shx');

// Write index 1, 2, 3,...
// Update header...
// Close file...

Close

Close the shapefile SHX file.

close();

Returns

A promise.

Example

import { ShapefileShxWriter } from "@coderundebug/shapefile-shp";

// Create a shapefile SHX writer object
const shapefileShxWriter = new ShapefileShxWriter();

// Open the file
await shapefileShxWriter.open('c:\\shapefile\\test.shx');

// Write index 1, 2, 3,...
// Update header...

// Close file
await shapefileShxWriter.close();

Write

Write new index information to the shapefile SHX file.

write(offset, contentLength);

Arguments

• offset - The offset position location within the SHP file where the shape record begins.

• contentLength - The total content size of the shape record (not including the record header).

Returns

A promise.

Example

import { ShapefileShxWriter } from "@coderundebug/shapefile-shp";

// Create a shapefile SHX writer object
const shapefileShxWriter = new ShapefileShxWriter();

// Open the file
await shapefileShxWriter.open('c:\\shapefile\\test.shx');

// Write shape to SHP and get offset and content length

// Write index
await shapefileShxWriter.write(offset, contentLength);

// Update header...

// Close file
await shapefileShxWriter.close();

Update Header

Update the ShapefileShx object header information in the shapefile SHX file. As you write more and more indexes to the file, the overall file length will increase. You may also need to update the minimum and maximum ranges. After you have finished writing all the indexes, you will need to update the ShapefileShx object and have it written to the SHX file.

updateHeader(shapefileShx);

Arguments

• shapefileShx - The shapefile SHX object that contains the header information that will get written to the file.

Returns

A promise.

Example

import { ShapefileShxWriter } from "@coderundebug/shapefile-shp";

// Create a shapefile SHX writer object
const shapefileShxWriter = new ShapefileShxWriter();

// Open the file
await shapefileShxWriter.open('c:\\shapefile\\test.shx');

// Write shape to SHP and get offset and content length

// Write index
await shapefileShxWriter.write(offset, contentLength);

// Set file length (header = 100) + (index record [1] = 8)
shapefileShxWriter.shapefileShx.fileLength = 108;

// Update header
await shapefileShxWriter.updateHeader(shapefileShxWriter.shapefileShx);

// Close file
await shapefileShxWriter.close();