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 TopoJson

Remarks

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

NameDescription
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.cs

Writes 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

features GeoFeatureCollection
The features.
options TopoJsonWriterOptions?
The options, or null for the defaults.

Returns

string The TopoJSON text.

Exceptions

ArgumentException
A position is not finite.

FormatObjects(IReadOnlyDictionary<string, GeoFeatureCollection>, TopoJsonWriterOptions?)

TopoJson.cs

Writes 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

objects IReadOnlyDictionary<string, GeoFeatureCollection>
The features of each object by name, in the order to write them.
options TopoJsonWriterOptions?
The options, or null for the defaults.

Returns

string The TopoJSON text.

Exceptions

ArgumentException
A collection is null or a position is not finite.

Parse overloads

Parse(string)

TopoJson.cs

Reads the features of all the objects of a TopoJSON topology.

public static GeoFeatureCollection Parse(string json)
Parameters
json string
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.cs

Reads 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
json string
The TopoJSON text.
objectName string
The name of the object.
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.cs

Reads 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

json string
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.cs

Reads the features of all the objects of a TopoJSON topology.

public static GeoFeatureCollection Read(Stream utf8Json)
Parameters
utf8Json Stream
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.cs

Reads 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
utf8Json Stream
The TopoJSON document, encoded in UTF-8. It is left open.
objectName string
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.cs

Reads 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

utf8Json Stream
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.cs

Writes 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

features GeoFeatureCollection
The features.
utf8Json Stream
The stream to write to. It is left open.
options TopoJsonWriterOptions?
The options, or null for the defaults.

Exceptions

ArgumentException
A position is not finite.

WriteObjects(IReadOnlyDictionary<string, GeoFeatureCollection>, Stream, TopoJsonWriterOptions?)

TopoJson.cs

Writes 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

objects IReadOnlyDictionary<string, GeoFeatureCollection>
The features of each object by name, in the order to write them.
utf8Json Stream
The stream to write to. It is left open.
options TopoJsonWriterOptions?
The options, or null for the defaults.

Exceptions

ArgumentException
A collection is null or a position is not finite.