Documentation
¶
Overview ¶
Package geojsonio reads and writes gobi Frames as GeoJSON per RFC 7946.
Supports every geometry type in RFC 7946 §3.1 — Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeometryCollection — with optional Z coordinate values (RFC 7946 §3.1.1 allows a third position value for XYZ; higher dimensions are dropped on read per the RFC's "SHOULD NOT extend positions beyond three elements" guidance).
Coordinate reference systems are always WGS 84 (EPSG:4326) per the RFC. Non-WGS84 CRS specifications in the input's `crs` field are ignored on read — the RFC deprecated that field in 2016.
Entry points:
Marshal / Unmarshal — codec for a single geometry object. Used when embedding GeoJSON in another format or hand-parsing a specific feature.
MarshalFeature / UnmarshalFeature — Feature wrapper codec (geometry + properties + id).
ReadFile / ReadFileChunksFunc / WriteFile — Frame-level I/O. Reads a FeatureCollection (or line-delimited GeoJSON) into a Frame with a `geometry` column plus one column per unique property key. Writes a Frame back out as FeatureCollection.
ScanFile — LazyFrame entry point matching parquetio / gpkgio / csvio's shape. No predicate pushdown (JSON is sequential) but streaming + projection above the scan work.
Index ¶
- Constants
- Variables
- func Marshal(g geometry.Geometry) ([]byte, error)
- func MarshalFeature(g geometry.Geometry, properties map[string]any) ([]byte, error)
- func ReadFile(path string, opts *ReadOptions) (*gobi.Frame, error)
- func ReadFileChunksFunc(path string, opts *ReadOptions, fn func(*gobi.Frame) error) error
- func ScanFile(path string, opts *ReadOptions) *gobi.LazyFrame
- func ScanSchema(path string, opts *ReadOptions) (*arrow.Schema, error)
- func Unmarshal(data []byte) (geometry.Geometry, error)
- func UnmarshalFeature(data []byte) (geometry.Geometry, map[string]any, error)
- func WriteFile(df *gobi.Frame, path string, opts *WriteOptions) error
- type Feature
- type FeatureCollection
- type Format
- type ReadOptions
- type WriteOptions
Constants ¶
const DefaultChunkRows = 65_536
DefaultChunkRows is the target batch size for the streaming reader — matches parquetio's default.
Variables ¶
var ErrInvalidGeoJSON = errors.New("geojson: invalid input")
ErrInvalidGeoJSON is returned when the input is malformed or references an unsupported geometry type. Wrap-friendly: errors.Is(err, ErrInvalidGeoJSON) is true for every parse failure this package produces.
Functions ¶
func Marshal ¶
Marshal encodes a Geometry to its GeoJSON representation. The output is deterministic — keys appear in the order "type", "coordinates" (or "geometries" for GeometryCollection).
XYZ points emit three-element coordinate arrays; XY points emit two. Callers can inspect the input's Is3D() to know which they'll get.
func MarshalFeature ¶
MarshalFeature encodes a geometry + properties bag as a GeoJSON Feature (RFC 7946 §3.2). Passing a nil geometry emits a Feature with `"geometry": null`, which is valid per the RFC.
func ReadFile ¶
func ReadFile(path string, opts *ReadOptions) (*gobi.Frame, error)
ReadFile reads a GeoJSON file into a single Frame. The Frame has a `geometry` column (WKB Binary, tagged EPSG:4326 per RFC 7946) plus one column per distinct property key seen across all features. Missing properties on individual features come back as null.
Property column types are inferred by scanning every feature: the union type is picked as the "widest" compatible arrow type — Int64 promotes to Float64 if any value is fractional; a column with any string value stays String. When a column has mixed types that don't unify (e.g., some strings and some numbers), it comes out as String with every value stringified.
For files too large to fit in memory, use ReadFileChunksFunc.
func ReadFileChunksFunc ¶
ReadFileChunksFunc streams a GeoJSON file through fn one batch at a time. The batch size is opts.ChunkRows (default 65k features).
For FormatFeatureCollection, the reader walks the top-level `features` array with a streaming JSON decoder — bounded memory regardless of file size. For FormatLineDelimited, each line is parsed as one Feature.
The Frame passed to fn owns its arrow buffers; call frame.Retain() to hold it past the callback's return.
func ScanFile ¶
func ScanFile(path string, opts *ReadOptions) *gobi.LazyFrame
ScanFile returns a LazyFrame that reads path as GeoJSON when Collect is called.
Optimizer participation:
- Streaming: reads one batch at a time through ReadFileChunksFunc. Peak memory bounded to one batch.
- Projection: Frame.Select() above the scan drops unpicked property columns at the LazyFrame layer. Parse work isn't reduced — a streaming JSON decoder can't skip fields — but the emitted Frame only carries the columns downstream ops asked for.
- Predicate pushdown: not supported. JSON is sequential; any predicate is evaluated by the executor above the scan.
Schema inference is a whole-file walk on the first Collect — ScanFile can't produce a schema without reading every feature (property keys + types may vary across features). If ScanSchema fails (file missing, invalid JSON), the error surfaces at Collect time.
func ScanSchema ¶
func ScanSchema(path string, opts *ReadOptions) (*arrow.Schema, error)
ScanSchema reads path far enough to produce the arrow.Schema ReadFile would return. Requires a full walk of the file to collect the union of property keys — no cheaper option because GeoJSON doesn't put schema information in a header.
Callers that care about avoiding this walk should ReadFile directly; ScanFile only invokes ScanSchema when the LazyFrame optimizer explicitly asks for the schema.
func Unmarshal ¶
Unmarshal decodes a GeoJSON geometry object. The returned geometry has its CRS set to WGS 84 per RFC 7946. Coordinate arrays with three elements populate Z + set HasZ; two-element arrays yield 2D geometries.
func UnmarshalFeature ¶
UnmarshalFeature decodes a GeoJSON Feature into its geometry and property bag. Returns nil geometry (with nil error) when the feature carries `"geometry": null`.
func WriteFile ¶
func WriteFile(df *gobi.Frame, path string, opts *WriteOptions) error
WriteFile writes df to a GeoJSON file at path. Format is chosen by opts.Format (defaults to FeatureCollection). The Frame's geometry column identifies the geometry per feature; every other column becomes a property.
Column types map back to JSON as expected: Int64/Int32/Uint64/Uint32 → JSON number, Float64/Float32 → JSON number, Bool → JSON bool, String → JSON string, Timestamp → RFC 3339 string. Nulls emit as JSON null.
Types ¶
type Feature ¶
type Feature struct {
Type string `json:"type"`
Geometry json.RawMessage `json:"geometry"`
Properties map[string]any `json:"properties,omitempty"`
ID any `json:"id,omitempty"`
}
Feature is a GeoJSON Feature wrapper (RFC 7946 §3.2).
ID is left as an `any` because the RFC allows both string and number IDs; callers should type-switch on the concrete Go type. Properties is a free-form map — RFC 7946 doesn't constrain the value types, so JSON's usual (float64 / string / bool / nil / []any / map[string]any) shapes apply.
type FeatureCollection ¶
FeatureCollection is the top-level container GeoJSON files usually carry (RFC 7946 §3.3).
type Format ¶
type Format uint8
Format selects the on-disk shape.
const ( // FormatAuto picks LineDelimited for .geojsonl / .ndjson and // FeatureCollection otherwise. FormatAuto Format = iota // FormatFeatureCollection reads/writes a single // `{"type":"FeatureCollection","features":[...]}` document. FormatFeatureCollection // FormatLineDelimited reads/writes one Feature per line. Enables // bounded-memory streaming — the parser never needs to know // where the FeatureCollection ends before it can emit rows. FormatLineDelimited )
type ReadOptions ¶
type ReadOptions struct {
// Format selects the input shape. Defaults to FormatAuto, which
// picks LineDelimited when the file extension is `.geojsonl` /
// `.ndjson`, FeatureCollection otherwise.
Format Format
// Columns projects the output Frame to just the named columns.
// The geometry column is always kept — matches gpkgio's rule.
Columns []string
// Allocator overrides the arrow allocator. Defaults to
// memory.DefaultAllocator.
Allocator memory.Allocator
// ChunkRows caps the number of features per emitted batch in
// the streaming path. 0 → DefaultChunkRows. Ignored by
// ReadFile (whole-file materialization).
ChunkRows int
}
ReadOptions controls ReadFile / ReadFileChunksFunc / ScanFile.
type WriteOptions ¶
type WriteOptions struct {
// Format selects the output shape. Defaults to
// FeatureCollection.
Format Format
// GeomCol names the geometry column. Defaults to the first
// column tagged as gobi.GeometryField.
GeomCol string
// Indent, when non-empty, pretty-prints the output with that
// indent per level. Empty = compact single-line JSON (typical
// for machine-consumed files). Only applies to FeatureCollection
// output; line-delimited output is always compact so each line
// stays a single feature.
Indent string
}
WriteOptions controls WriteFile.
Source Files