README
¶
go-shapefile
go-shapefile is a Go parser for the "shapefile" GIS file format. The package can be used to read shapefiles, and optionally convert them into GeoJSON "features" (supported by go-geojson) - allowing a shapefile to be written directly to databases such as PostGIS, MongoDB, or Couchbase, etc.
The package does not currently support writing of files.
Usage
How you choose to use this package will depend on your use case. go-shapefile supports reading the shapefiles in the following forms:
- .zip file containing mandatory .shp and .dbf files, with optional .cpg file
- Unzipped .shp and .dbf files, with optional character encoding
- .shp and .dbf files separately, with optional character encoding
Basic example
Reading a zipped shapefile is achieved by using the ZipScanner. The example below shows a basic example of this, where error handling has been omitted for brevity.
file, err := os.Open("path/to/ne_110m_admin_0_sovereignty.zip")
stat, err := r.Stat()
// Create new ZipScanner
// The filename can be replaced with an empty string if you don't want to check filenames inside the zip file
scanner := shapefile.NewZipScanner(file, stat.Size(), "ne_110m_admin_0_sovereignty.zip")
// Optionally get file info: shape type, number of records, bounding box, etc.
info, err := scanner.Info()
fmt.Println(info)
// Start the scanner
err = scanner.Scan()
// Call Record() to get each record in turn, until either the end of the file, or an error occurs
for {
record := scanner.Record()
if record == nil {
break
}
// Each record contains a shape (from .shp file) and attributes (from .dbf file)
fmt.Println(record)
}
// Err() returns the first error encountered during calls to Record()
err = scanner.Err()
GeoJSON example
Using the example above, we can optionally convert shapefile records to GeoJSON features. go-shapefile achieves this by using go-geojson, meaning that you can use the standard json.Marshal to produce a JSON object that can be understood by any software that can work with the GeoJSON standard.
record := scanner.Record()
feature := record.GeoJSONFeature()
jsonData, err := json.Marshal(feature)
fmt.Println(string(jsonData))
Features
This package has been primarily developed to work with Natural Earth, so may only contain the subset of shapefile features relevant to those data files. The "shapefile" format is actually a collection of files, of which this package currently supports the "shape" (.shp), "attribute" (.dbf) and character encoding (.cpg) files.
Shape file (.shp)
The .shp file contains the geometry data in the form of variable-length records. A single record represents a particular shape type, although the records in a single file must all represent the same type. go-shapefile supports the following types:
| Shape type | Supported |
|---|---|
| Point | ✔ |
| Polyline | ✔ |
| Polygon | ✔ |
| MultiPoint | ❌ |
| PointZ | ❌ |
| PolylineZ | ❌ |
| PolygonZ | ❌ |
| MultiPointZ | ❌ |
| PointM | ❌ |
| PolylineM | ❌ |
| PolygonM | ❌ |
| MultiPointM | ❌ |
| MultiPatch | ❌ |
Format specification: https://www.esri.com/library/whitepapers/pdfs/shapefile.pdf.
Attribute file (.dbf)
The .dbf file contains attributes for each shape in the .shp file. Attributes are stored in the form of records, which consist of a number of fields. Field names and values are not standardized - they are specified as part of the .dbf file to suit the particular use case.
This file uses a format called "dBase", of which there are several variations in varying degrees of usage. The most common are dBase IV and dBase V, but go-shapefile currently only supports IV. Below is an overview of the supported field types:
| Field type | Supported |
|---|---|
| Character/string | ✔ |
| Numeric | ✔ |
| Date | ✔ |
| Floating point | ✔ |
| Logical | ❌ |
| Memo | ❌ |
Note that dBase V contains many more field types.
Character endoding file (.cpg)
The .cpg file is optional and contains the character encoding used inside the .dbf file. By default, and in this file's absense, the character encoding is assumed to be ASCII, but this file can be used to support Unicode strings. go-shapefile supports the encoding labels defined by https://encoding.spec.whatwg.org/#names-and-labels.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Attributes ¶
Attributes provides access to the dbf record.
type FieldDesc ¶
type FieldDesc interface {
Name() string
}
FieldDesc provides information about an attribute field.
type FieldDescList ¶
type FieldDescList []FieldDesc
FieldDescList is a list of field descriptors.
func (FieldDescList) Exists ¶
func (l FieldDescList) Exists(name string) bool
Exists reutnrs true if the named field exists, and false otherwise.
type GeoJSONOption ¶
type GeoJSONOption func(*geoJSONConfig)
GeoJSONOption funcs can be passed to Record.GeoJSONFeature().
func RenameProperties ¶
func RenameProperties(oldNews map[string]string) GeoJSONOption
RenameProperties allows shapefile field names to be mapped to user-defined GeoJSON property names.
type Info ¶
type Info struct {
BoundingBox shp.BoundingBox
NumRecords uint32
ShapeType shp.ShapeType
Fields FieldDescList
}
Info contains combined information from the pair of input files.
type Option ¶
type Option func(*options)
Option funcs can be passed to NewScanner().
func CharacterDecoder ¶
CharacterDecoder sets dbf.CharacterDecoder.
type Record ¶
type Record struct {
shp.Shape
Attributes
}
Record consists of a shape (read from the .shp file) and attributes (from the .dbf file).
func (Record) GeoJSONFeature ¶
func (r Record) GeoJSONFeature(opts ...GeoJSONOption) *geojson.Feature
GeoJSONFeature creates a GeoJSON Feature for the Shapefile Record.
type Scannable ¶
type Scannable interface {
AddOptions(...Option)
Info() (*Info, error)
Scan() error
Record() *Record
Err() error
}
Scannable provides read access to a shapefile.
type Scanner ¶
type Scanner struct {
// contains filtered or unexported fields
}
Scanner parses a pair or shp and dbf files.
func NewScanner ¶
NewScanner creates a new Scanner for the provided shp and dbf files.
func (*Scanner) AddOptions ¶
AddOptions allows additional options to be set after the scanner has already been created.
func (*Scanner) Err ¶
Err returns the first error encountered when parsing records. It should be called after calling the Record method for the last time.
func (*Scanner) Record ¶
Record returns each record found in the shp and dbf files. A single record consists of a shape and a set of attributes. nil is returned once the last record has been read, or an error occurs - the Err method should be used to check for an error at this point.
type TablePrinter ¶
type TablePrinter struct {
// contains filtered or unexported fields
}
TablePrinter implements a tabulated view of a shapefile.
func NewTablePrinter ¶
func NewTablePrinter(s Scannable, fields ...string) (*TablePrinter, error)
NewTablePrinter creates a TablePrinter for the supplied shapefile, optionally displaying only the specified field names.
func (TablePrinter) PrettyPrint ¶
func (p TablePrinter) PrettyPrint(out io.Writer) error
PrettyPrint writes a pretty ASCII table to the supplied destination.
type ZipScanner ¶
type ZipScanner struct {
// contains filtered or unexported fields
}
ZipScanner wraps Scanner, providing a simple method of reading a zipped shapefile.
func NewZipScanner ¶
NewZipScanner creates a ZipScanner for the supplied zip file. The filename parameter should be the zip file's name (as stored on disk), and MUST match the names of the contained shp and dbf files.
func (*ZipScanner) AddOptions ¶
func (s *ZipScanner) AddOptions(opts ...Option)
AddOptions allows additional options to be set after the scanner has already been created.
func (*ZipScanner) Err ¶
func (s *ZipScanner) Err() error
Err returns the first error encountered when parsing records. It should be called after calling the Shape method for the last time.
Source Files
Directories