TopoJson Class
Reads and writes TopoJSON, the format of map files such as world-atlas and us-atlas: a Topology whose named objects reference arcs, so that a border shared by two polygons is stored once.
public static class TopoJsonRemarks
Each object of the topology is a collection of features: a GeometryCollection object gives a feature for each of its geometries, with their id and properties, and another object gives one feature. A GeometryCollection inside a feature becomes a GeoGeometryCollection, and a geometry whose type is null becomes a feature without geometry (or is skipped inside a GeoGeometryCollection).
The reader stitches the arcs, reversing those referenced by a negative index (~i), applies the transform of a quantized topology to the arcs (delta-encoded) and to the positions of the points (not delta-encoded), and keeps a third value of a position, which is never transformed, as the altitude. It ignores the bbox, the foreign members, and the id and properties of a GeometryCollection object. The properties are a String, a Double, a Boolean, null, or a JsonElement for an object or an array. A numeric id becomes its JSON text.
The writer writes each collection as a GeometryCollection object, and finds the arcs as topojson-server does: the lines and rings are cut at the junctions, the positions where they meet or part, and the identical arcs, in either direction, are written once. The rings are also cut at their first position, so they are read back starting at the same position. It closes the rings that are not, writes the altitudes as a third value (which GDAL does not read), the identifiers as strings, and the properties as GeoJson does. Without TopoJsonWriterOptions.Quantization, the features are read back as they were written; with it, the positions are rounded to a grid and the arcs delta-encoded.
Methods
| Name | Description |
|---|---|
| Format(GeoFeatureCollection, TopoJsonWriterOptions?) | Writes features as a TopoJSON topology with one object, named after GeoFeatureCollection.Name, or features when it is null. |
| FormatObjects(IReadOnlyDictionary<string, GeoFeatureCollection>, TopoJsonWriterOptions?) | Writes collections of features as the objects of a TopoJSON topology, which share their arcs. |
| Parse(string) | Reads the features of all the objects of a TopoJSON topology. |
| Parse(string, string) | Reads the features of an object of a TopoJSON topology, such as the countries of world-atlas. |
| ParseObjects(string) | Reads the objects of a TopoJSON topology, such as the countries and the land of world-atlas. |
| Read(Stream) | Reads the features of all the objects of a TopoJSON topology. |
| Read(Stream, string) | Reads the features of an object of a TopoJSON topology, such as the countries of world-atlas. |
| ReadObjects(Stream) | Reads the objects of a TopoJSON topology, such as the countries and the land of world-atlas. |
| Write(GeoFeatureCollection, Stream, TopoJsonWriterOptions?) | Writes features as a TopoJSON topology with one object, named after GeoFeatureCollection.Name, or features when it is null, encoded in UTF-8. |
| WriteObjects(IReadOnlyDictionary<string, GeoFeatureCollection>, Stream, TopoJsonWriterOptions?) | Writes collections of features as the objects of a TopoJSON topology, which share their arcs, encoded in UTF-8. |
Format(GeoFeatureCollection, TopoJsonWriterOptions?)
TopoJson.csWrites features as a TopoJSON topology with one object, named after GeoFeatureCollection.Name, or features when it is null.
public static string Format(GeoFeatureCollection features, TopoJsonWriterOptions? options = null)Parameters
featuresGeoFeatureCollection- The features.
optionsTopoJsonWriterOptions?- The options, or
nullfor the defaults.
Returns
string The TopoJSON text.
Exceptions
ArgumentException- A position is not finite.
FormatObjects(IReadOnlyDictionary<string, GeoFeatureCollection>, TopoJsonWriterOptions?)
TopoJson.csWrites collections of features as the objects of a TopoJSON topology, which share their arcs.
public static string FormatObjects(IReadOnlyDictionary<string, GeoFeatureCollection> objects, TopoJsonWriterOptions? options = null)Parameters
objectsIReadOnlyDictionary<string, GeoFeatureCollection>- The features of each object by name, in the order to write them.
optionsTopoJsonWriterOptions?- The options, or
nullfor the defaults.
Returns
string The TopoJSON text.
Exceptions
ArgumentException- A collection is
nullor a position is not finite.
Parse overloads
Parse(string)
TopoJson.csReads the features of all the objects of a TopoJSON topology.
public static GeoFeatureCollection Parse(string json)Parameters
jsonstring- The TopoJSON text.
Returns
GeoFeatureCollection The features of the objects, in the order of the document. The GeoFeatureCollection.Name is the name of the object when the topology has exactly one.
Exceptions
FormatException- The text is not valid JSON or not a TopoJSON topology.
Parse(string, string)
TopoJson.csReads the features of an object of a TopoJSON topology, such as the countries of world-atlas.
public static GeoFeatureCollection Parse(string json, string objectName)Parameters
Returns
GeoFeatureCollection The features of the object. The GeoFeatureCollection.Name is the name of the object.
Exceptions
FormatException- The text is not valid JSON or not a TopoJSON topology.
ArgumentException- The topology has no object named
objectName.
ParseObjects(string)
TopoJson.csReads the objects of a TopoJSON topology, such as the countries and the land of world-atlas.
public static IReadOnlyDictionary<string, GeoFeatureCollection> ParseObjects(string json)Parameters
jsonstring- The TopoJSON text.
Returns
IReadOnlyDictionary<string, GeoFeatureCollection> The features of each object by name, in the order of the document. The GeoFeatureCollection.Name of each collection is the name of its object.
Exceptions
FormatException- The text is not valid JSON or not a TopoJSON topology.
Read overloads
Read(Stream)
TopoJson.csReads the features of all the objects of a TopoJSON topology.
public static GeoFeatureCollection Read(Stream utf8Json)Parameters
utf8JsonStream- The TopoJSON document, encoded in UTF-8. It is left open.
Returns
GeoFeatureCollection The features of the objects, in the order of the document. The GeoFeatureCollection.Name is the name of the object when the topology has exactly one.
Exceptions
FormatException- The document is not valid JSON or not a TopoJSON topology.
Read(Stream, string)
TopoJson.csReads the features of an object of a TopoJSON topology, such as the countries of world-atlas.
public static GeoFeatureCollection Read(Stream utf8Json, string objectName)Parameters
utf8JsonStream- The TopoJSON document, encoded in UTF-8. It is left open.
objectNamestring- The name of the object.
Returns
GeoFeatureCollection The features of the object. The GeoFeatureCollection.Name is the name of the object.
Exceptions
FormatException- The document is not valid JSON or not a TopoJSON topology.
ArgumentException- The topology has no object named
objectName.
ReadObjects(Stream)
TopoJson.csReads the objects of a TopoJSON topology, such as the countries and the land of world-atlas.
public static IReadOnlyDictionary<string, GeoFeatureCollection> ReadObjects(Stream utf8Json)Parameters
utf8JsonStream- The TopoJSON document, encoded in UTF-8. It is left open.
Returns
IReadOnlyDictionary<string, GeoFeatureCollection> The features of each object by name, in the order of the document. The GeoFeatureCollection.Name of each collection is the name of its object.
Exceptions
FormatException- The document is not valid JSON or not a TopoJSON topology.
Write(GeoFeatureCollection, Stream, TopoJsonWriterOptions?)
TopoJson.csWrites features as a TopoJSON topology with one object, named after GeoFeatureCollection.Name, or features when it is null, encoded in UTF-8.
public static void Write(GeoFeatureCollection features, Stream utf8Json, TopoJsonWriterOptions? options = null)Parameters
featuresGeoFeatureCollection- The features.
utf8JsonStream- The stream to write to. It is left open.
optionsTopoJsonWriterOptions?- The options, or
nullfor the defaults.
Exceptions
ArgumentException- A position is not finite.
WriteObjects(IReadOnlyDictionary<string, GeoFeatureCollection>, Stream, TopoJsonWriterOptions?)
TopoJson.csWrites collections of features as the objects of a TopoJSON topology, which share their arcs, encoded in UTF-8.
public static void WriteObjects(IReadOnlyDictionary<string, GeoFeatureCollection> objects, Stream utf8Json, TopoJsonWriterOptions? options = null)Parameters
objectsIReadOnlyDictionary<string, GeoFeatureCollection>- The features of each object by name, in the order to write them.
utf8JsonStream- The stream to write to. It is left open.
optionsTopoJsonWriterOptions?- The options, or
nullfor the defaults.
Exceptions
ArgumentException- A collection is
nullor a position is not finite.