Documentation
¶
Overview ¶
Package shpio reads and writes ESRI Shapefiles as gobi Frames.
A Shapefile is a set of side-by-side files sharing a base name:
- <base>.shp — geometry records
- <base>.shx — offset index (produced/consumed automatically)
- <base>.dbf — dBase III attribute table
- <base>.prj — optional WKT projection sidecar
This package implements the 1998 ESRI Shapefile Technical Description end-to-end for the geometry types most real-world data uses: Null (0), Point (1), PolyLine (3), Polygon (5), MultiPoint (8), and their XYZ variants (11, 13, 15, 18). M ("measure") variants (types 21-28) are not currently supported.
Reader: ReadFile(base) returns a Frame with the attributes as leading columns and a WKB "geometry" column at the end, tagged with the CRS from <base>.prj when present.
Writer: WriteFile(f, base) walks the geometry column to pick the Shapefile geometry type (all rows must share compatible type), emits the .shp / .shx / .dbf, and writes a .prj sidecar when the geometry column carries a known EPSG code.
Index ¶
- Constants
- Variables
- func ReadFile(base string, opts *ReadOptions) (*gobi.Frame, error)
- func ReadStructs[T any](base string, opts *ReadOptions) ([]T, error)
- func WriteFile(f *gobi.Frame, base string, opts *WriteOptions) error
- func WriteStructs[T any](rows []T, base string, opts *WriteOptions) error
- type ReadOptions
- type WriteOptions
Constants ¶
const ( ShapeNull = 0 ShapePoint = 1 ShapePolyLine = 3 ShapePolygon = 5 ShapeMultiPoint = 8 ShapePointZ = 11 ShapePolyLineZ = 13 ShapePolygonZ = 15 ShapeMultiPointZ = 18 )
Shapefile shape type codes per the ESRI 1998 technical description.
Variables ¶
var ErrInvalidShapefile = errors.New("shpio: invalid shapefile")
ErrInvalidShapefile is returned for malformed or unsupported shapefile input.
Functions ¶
func ReadFile ¶
func ReadFile(base string, opts *ReadOptions) (*gobi.Frame, error)
ReadFile reads the shapefile whose base name is `base` (no `.shp` suffix) and returns a Frame with attribute columns from the .dbf plus a geometry column. Pass nil opts for defaults.
func ReadStructs ¶ added in v0.3.0
func ReadStructs[T any](base string, opts *ReadOptions) ([]T, error)
ReadStructs reads a Shapefile (`base.shp` + sibling `.dbf` etc.) and decodes each row into a T. Column names are matched against T's fields via gobi's tag resolution under the "shp" namespace: `shp:"NAME10"` tags take priority. Because Shapefile / DBF field names are limited to 10 ASCII characters, the "shp" tag is particularly useful for aliasing Go's longer field names down to their storage names. Resolution fallback: `shp:` → `gobi:` → csv → field name. `shp:"-"` skips a field. Fields tagged `geom:"true"` map to the shapefile's geometry column.
type Row struct {
ID int64 `shp:"OBJECTID"`
Name string `shp:"NAME" gobi:"name"`
Population int64 `shp:"POP10"` // 10-char DBF-friendly alias
Geometry []byte `geom:"true"`
Notes string `shp:"-"` // omit from output
}
rows, err := shpio.ReadStructs[Row]("counties", nil)
Wraps ReadFile + gobi.ToStructs.
func WriteFile ¶
func WriteFile(f *gobi.Frame, base string, opts *WriteOptions) error
WriteFile writes f to base+".shp", base+".shx", base+".dbf" (and a minimal base+".prj" when the geometry column carries a known EPSG). base may include or omit ".shp"; both are accepted.
The geometry column is picked automatically (the first tagged geometry column, or "geometry" if present). All rows must share a compatible shape type — mixed Point / LineString / Polygon rows are rejected. Pass nil opts for defaults.
func WriteStructs ¶ added in v0.3.0
func WriteStructs[T any](rows []T, base string, opts *WriteOptions) error
WriteStructs encodes rows into a Shapefile. Column names come from the "shp" tag namespace (see ReadStructs).
Types ¶
type ReadOptions ¶
type ReadOptions struct{}
ReadOptions reserves a slot for future read-time configuration (e.g., .prj override, dbf encoding hint, M-variant handling). Currently empty — pass nil.
The struct exists so future options can be added without breaking the ReadFile signature. Matches the naming pattern used by parquetio, csvio, gpkgio, geojsonio, kmlio, and pgio.
type WriteOptions ¶
type WriteOptions struct{}
WriteOptions reserves a slot for future write-time configuration (e.g., forced geometry-type override, .prj injection, custom .dbf field spec). Currently empty — pass nil.
Source Files