Documentation
¶
Overview ¶
Package kmlio reads and writes KML (Keyhole Markup Language, OGC 12-007r2) and KMZ (zipped KML) as gobi Frames.
KML always stores coordinates in WGS 84 (lon, lat[, alt]) per the OGC spec, so output frames have their geometry column tagged with EPSG:4326.
The reader flattens every <Placemark> in the document. Each placemark contributes one row with columns:
- name (string, from <name>)
- description (string, from <description>)
- geometry (WKB Binary, tagged EPSG:4326)
- <ext-key> one string column per distinct <ExtendedData><Data> name= attribute seen in the document
The writer emits one <Placemark> per row. String / numeric columns other than "name", "description", and the geometry column become <ExtendedData> entries.
KMZ support. KMZ is a zip archive containing one primary .kml file (by convention "doc.kml") plus optional resources. ReadFile and WriteFile auto-detect the format from the file extension (.kmz → KMZ). For Reader/Writer flows without a filename hint, set ReadOptions.Format / WriteOptions.Format to FormatKMZ. The reader prefers "doc.kml" but falls back to the first .kml entry in the archive so KMZ files produced by other tools (with names like "layer.kml") still parse.
Not implemented (out of scope):
- <Style>, <StyleMap>, <NetworkLink>, <Document> nesting semantics
- Time / TimeSpan primitives
- KMZ resource files (icons, images) — only the primary .kml entry is read; other entries in the archive are ignored
- Non-primitive KML geometries (Model, gx:Track)
Index ¶
- Variables
- func Read(r io.Reader, opts *ReadOptions) (*gobi.Frame, error)
- func ReadFile(path string, opts *ReadOptions) (*gobi.Frame, error)
- func Write(f *gobi.Frame, w io.Writer, opts *WriteOptions) error
- func WriteFile(f *gobi.Frame, path string, opts *WriteOptions) error
- type Format
- type ReadOptions
- type WriteOptions
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidKML = errors.New("kmlio: invalid input")
ErrInvalidKML is returned when the input isn't a well-formed KML or uses a construct this package doesn't support.
Functions ¶
func Read ¶
Read parses a KML document from r into a Frame. Pass nil opts for defaults.
For a KMZ archive from a Reader, set opts.Format = FormatKMZ. The reader will buffer the input to a bytes.Buffer (archive/zip needs io.ReaderAt with a known size) and locate the primary .kml entry inside the archive. FormatAuto on a Reader defaults to FormatKML — a raw Reader carries no filename hint.
func ReadFile ¶
func ReadFile(path string, opts *ReadOptions) (*gobi.Frame, error)
ReadFile parses path and returns a Frame. See package doc for the column shape. Pass nil opts for defaults. File extension picks between KML and KMZ (.kmz → KMZ) when opts.Format is FormatAuto.
func Write ¶
Write encodes f to w as a KML or KMZ document. Pass nil opts for KML defaults. Set opts.Format = FormatKMZ to emit a zip archive (single "doc.kml" entry) — needed for Writer-based flows where there's no filename to auto-detect from.
func WriteFile ¶
func WriteFile(f *gobi.Frame, path string, opts *WriteOptions) error
WriteFile writes f to path as KML or KMZ. See package doc for the column conventions the writer looks for. Pass nil opts for defaults. File extension picks between KML and KMZ (.kmz → KMZ) when opts.Format is FormatAuto.
Types ¶
type Format ¶ added in v0.1.1
type Format uint8
Format identifies the KML container flavor: raw XML or a zip-packaged .kmz. KMZ is a zip archive containing a single primary .kml file (by convention "doc.kml") plus optional resources (icons, images). Gobi's writer emits just the "doc.kml" entry; the reader accepts any archive containing at least one .kml file.
const ( // FormatAuto picks by file extension (.kmz → KMZ, otherwise // KML). Only meaningful for ReadFile / WriteFile; io.Reader / // io.Writer paths treat it as FormatKML. FormatAuto Format = iota // FormatKML is uncompressed XML — the canonical KML document. FormatKML // FormatKMZ is a zip archive containing a doc.kml entry. FormatKMZ )
type ReadOptions ¶
type ReadOptions struct {
// Format selects the on-disk shape. FormatAuto (the default)
// picks by file extension (.kmz → KMZ, otherwise KML) in
// ReadFile. For Read (io.Reader-based), FormatAuto behaves as
// FormatKML — a raw Reader has no filename hint. Set Format
// explicitly when reading KMZ from a Reader.
Format Format
}
ReadOptions controls the KML/KMZ reader.
type WriteOptions ¶
type WriteOptions struct {
// Format selects the on-disk shape. Same auto-detect rules as
// ReadOptions.Format — .kmz extension → KMZ, otherwise KML.
Format Format
}
WriteOptions controls the KML/KMZ writer.
Source Files