FlatGeobuf Class
Reads and writes FlatGeobuf files (version 3): a binary format of features, encoded with FlatBuffers, with an optional spatial index that lets a reader get the features of a box without decoding the others.
public static class FlatGeobufRemarks
The reader reads the points, lines, polygons, their multi-geometries and the geometry collections, with their altitudes (Z) and their measures (M, a NaN value being no measure); the T and TM values are dropped, as the format does not define their meaning, and the curves, surfaces and triangles throw a FormatException. The collection is named after the name of the header. The property values have the .NET type of their column: a SByte, Byte, Boolean, Int16, UInt16, Int32, UInt32, Int64, UInt64, Single, Double, a String, a JsonElement for a JSON column (or the text when it is not valid JSON), a DateTimeOffset for a date-time column (a time without offset is UTC, and a value that cannot be parsed is kept as text) and an array of bytes for a binary column. The features have no identifier. The coordinate system of the header is not read: the coordinates are expected to be longitudes and latitudes.
The writer writes the header with the name of the collection, its bounds, the coordinate system EPSG:4326 (WGS 84), one geometry type when every geometry has the same type (else each geometry gets its type), and Z values when a position has an altitude (the positions without altitude get 0), and M values when a position has a measure (the positions without measure get NaN). The times of the positions are not written. The columns are the property names in the order they are first seen; a column gets the type of its values, Int64 for integers of different types, Double for numbers of different types, and the text of the values for other mixes. A date, a DateTime or a DateTimeOffset is a date-time column in ISO 8601, to the millisecond (GDAL reads at most 32 characters), an array of bytes a binary column, a JsonElement object or array a JSON column, and other values a string column of their text. A null value is not written. A feature without geometry, or with an empty one, is written without geometry. The identifiers of the features are not written.
With the spatial index, the default, the features are written along a Hilbert curve, the order of the index, and not in the order of the collection; the index is not written when a feature has no geometry.
Methods
| Name | Description |
|---|---|
| Read(Stream, FlatGeobufReaderOptions?) | Reads FlatGeobuf data from a stream. |
| Read(ReadOnlyMemory<byte>, FlatGeobufReaderOptions?) | Reads FlatGeobuf data. |
| Read(ReadOnlySpan<byte>, FlatGeobufReaderOptions?) | Reads FlatGeobuf data. |
| Read(string, FlatGeobufReaderOptions?) | Reads a FlatGeobuf file. |
| ReadFeaturesAsync(Stream, FlatGeobufReaderOptions?, CancellationToken) | Reads the features of FlatGeobuf data from a stream, one at a time, with bounded memory: only the feature being read is kept in memory. With FlatGeobufReaderOptions.Bounds, a spatial index and a seekable stream, only the nodes of the index that the search visits and the features it finds are read; a stream that cannot seek is read to its end, and the features outside of the box are skipped. |
| ReadFeaturesAsync(string, FlatGeobufReaderOptions?, CancellationToken) | Reads the features of a FlatGeobuf file one at a time, with bounded memory: only the feature being read is kept in memory. With FlatGeobufReaderOptions.Bounds and a spatial index, only the nodes of the index that the search visits and the features it finds are read from the file. |
| Write(GeoFeatureCollection, FlatGeobufWriterOptions?) | Writes features as FlatGeobuf data. |
| Write(GeoFeatureCollection, Stream, FlatGeobufWriterOptions?) | Writes features as FlatGeobuf data to a stream. |
| Write(GeoFeatureCollection, string, FlatGeobufWriterOptions?) | Writes features as a FlatGeobuf file, replacing the existing one. |
Read overloads
Read(Stream, FlatGeobufReaderOptions?)
FlatGeobuf.csReads FlatGeobuf data from a stream.
public static GeoFeatureCollection Read(Stream stream, FlatGeobufReaderOptions? options = null)Parameters
streamStream- The data. It is read to its end and left open.
optionsFlatGeobufReaderOptions?- The options, or
nullfor the defaults.
Returns
GeoFeatureCollection The features.
Exceptions
FormatException- The data is not valid FlatGeobuf, or has a geometry that is not supported.
Read(ReadOnlyMemory<byte>, FlatGeobufReaderOptions?)
FlatGeobuf.csReads FlatGeobuf data.
public static GeoFeatureCollection Read(ReadOnlyMemory<byte> data, FlatGeobufReaderOptions? options = null)Parameters
dataReadOnlyMemory<byte>- The data.
optionsFlatGeobufReaderOptions?- The options, or
nullfor the defaults.
Returns
GeoFeatureCollection The features.
Exceptions
FormatException- The data is not valid FlatGeobuf, or has a geometry that is not supported.
Read(ReadOnlySpan<byte>, FlatGeobufReaderOptions?)
FlatGeobuf.csReads FlatGeobuf data.
public static GeoFeatureCollection Read(ReadOnlySpan<byte> data, FlatGeobufReaderOptions? options = null)Parameters
dataReadOnlySpan<byte>- The data. The features do not refer to it once the method returns: the data can be memory that the caller frees, or the memory of a resource of an assembly.
optionsFlatGeobufReaderOptions?- The options, or
nullfor the defaults.
Returns
GeoFeatureCollection The features.
Exceptions
FormatException- The data is not valid FlatGeobuf, or has a geometry that is not supported.
Read(string, FlatGeobufReaderOptions?)
FlatGeobuf.csReads a FlatGeobuf file.
public static GeoFeatureCollection Read(string path, FlatGeobufReaderOptions? options = null)Parameters
pathstring- The path of the file.
optionsFlatGeobufReaderOptions?- The options, or
nullfor the defaults.
Returns
GeoFeatureCollection The features, in a collection named after the name of the header, else after the file, without its extension.
Exceptions
FormatException- The file is not valid FlatGeobuf, or has a geometry that is not supported.
ReadFeaturesAsync overloads
ReadFeaturesAsync(Stream, FlatGeobufReaderOptions?, CancellationToken)
FlatGeobuf.csReads the features of FlatGeobuf data from a stream, one at a time, with bounded memory: only the feature being read is kept in memory. With FlatGeobufReaderOptions.Bounds, a spatial index and a seekable stream, only the nodes of the index that the search visits and the features it finds are read; a stream that cannot seek is read to its end, and the features outside of the box are skipped.
public static IAsyncEnumerable<GeoFeature> ReadFeaturesAsync(Stream stream, FlatGeobufReaderOptions? options = null, CancellationToken cancellationToken = default)Parameters
streamStream- The data. It is read from its current position as the features are enumerated, and left open.
optionsFlatGeobufReaderOptions?- The options, or
nullfor the defaults. cancellationTokenCancellationToken- The token to cancel the reading.
Returns
IAsyncEnumerable<GeoFeature> The features, in the order of the data.
Exceptions
FormatException- The data is not valid FlatGeobuf, or has a geometry that is not supported. The features read before the error are returned first.
ReadFeaturesAsync(string, FlatGeobufReaderOptions?, CancellationToken)
FlatGeobuf.csReads the features of a FlatGeobuf file one at a time, with bounded memory: only the feature being read is kept in memory. With FlatGeobufReaderOptions.Bounds and a spatial index, only the nodes of the index that the search visits and the features it finds are read from the file.
public static IAsyncEnumerable<GeoFeature> ReadFeaturesAsync(string path, FlatGeobufReaderOptions? options = null, CancellationToken cancellationToken = default)Parameters
pathstring- The path of the file.
optionsFlatGeobufReaderOptions?- The options, or
nullfor the defaults. cancellationTokenCancellationToken- The token to cancel the reading.
Returns
IAsyncEnumerable<GeoFeature> The features, in the order of the file. The file is opened when the enumeration starts, and closed when it ends.
Exceptions
FormatException- The file is not valid FlatGeobuf, or has a geometry that is not supported. The features read before the error are returned first.
Write overloads
Write(GeoFeatureCollection, FlatGeobufWriterOptions?)
FlatGeobuf.csWrites features as FlatGeobuf data.
public static byte[] Write(GeoFeatureCollection features, FlatGeobufWriterOptions? options = null)Parameters
featuresGeoFeatureCollection- The features.
optionsFlatGeobufWriterOptions?- The options, or
nullfor the defaults.
Returns
byte[] The data.
Exceptions
ArgumentException- A position is not finite.
Write(GeoFeatureCollection, Stream, FlatGeobufWriterOptions?)
FlatGeobuf.csWrites features as FlatGeobuf data to a stream.
public static void Write(GeoFeatureCollection features, Stream stream, FlatGeobufWriterOptions? options = null)Parameters
featuresGeoFeatureCollection- The features.
streamStream- The stream. It is left open.
optionsFlatGeobufWriterOptions?- The options, or
nullfor the defaults.
Exceptions
ArgumentException- A position is not finite.
Write(GeoFeatureCollection, string, FlatGeobufWriterOptions?)
FlatGeobuf.csWrites features as a FlatGeobuf file, replacing the existing one.
public static void Write(GeoFeatureCollection features, string path, FlatGeobufWriterOptions? options = null)Parameters
featuresGeoFeatureCollection- The features.
pathstring- The path of the file.
optionsFlatGeobufWriterOptions?- The options, or
nullfor the defaults.
Exceptions
ArgumentException- A position is not finite.