Package: pytopojson
pyTopoJSONpyTopoJSONis based on the work ofMike Bostockand it provides
tools for converting GeoJSON toTopoJSON.
SeeHow to Infer Topologyfor details
on how the topology is constructed. See alsous-atlasandworld-atlasfor pre-built TopoJSON.InstallationDependenciespytopojsonrequires:NumPy (>= 1.15.0)User installationIf you already have a working installation of NumPy,
the easiest way to installpytopojsonis usingpip:pip install pytopojsonAPI Reference#pytopojson.topology.Topology()<>You must create aTopologyobject to compute the topology:# Import topologyfrompytopojsonimporttopology# Create Topology objecttopology_=topology.Topology()# Call it using a GeoJSON (dict) object, a name for the object and a quantization value (optional)topojson=topology_({"object_name":geojson},quantization=quantization)This returns a TopoJSON topology for the specifiedGeoJSONobjects.
The returned topology makes a shallow copy of the inputobjects:
the identifier, bounding box, properties and coordinates of input objects may
be shared with the output topology.If aquantizationparameter is specified, the input geometry is quantized
prior to computing the topology, the returned topology is quantized, and its
arcs aredelta-encoded.
Quantization is recommended to improve the quality of the topology if the
input geometry is messy (i.e., small floating point error means that
adjacent boundaries do not have identical values); typical values are powers
of ten, such as 1e4, 1e5 or 1e6.#pytopojson.feature.Feature(topology,object)<>Returns the GeoJSON Feature or FeatureCollection for the specifiedobjectin
the giventopology. If the specified object is a string, it is treated astopology*['objects'][object]. Then, if the object is a GeometryCollection,
a FeatureCollection is returned, and each geometry in the collection is
mapped to a Feature. Otherwise, a Feature is returned. The returned feature is
a shallow copy of the sourceobject: they may share identifiers, bounding
boxes, properties and coordinates.Some examples:A point is mapped to a feature with a geometry object of type "Point".Likewise for line strings, polygons, and other simple geometries.A null geometry object (of type null in TopoJSON) is mapped to a feature
with a null geometry object.A geometry collection of points is mapped to a feature collection of
features, each with a point geometry.A geometry collection of geometry collections is mapped to a feature
collection of features, each with a geometry collection.Seetest_feature.pyfor more examples.#pytopojson.merge.Merge(topology,objects)<>Returns the GeoJSON MultiPolygon geometry object representing the union for
the specified array of Polygon and MultiPolygonobjectsin the giventopology. Interior borders shared by adjacent polygons are removed.
SeeMerging Statesfor an example.
The returned geometry is a shallow copy of the sourceobject: they may share
coordinates.#pytopojson.merge.MergeArcs(topology,objects)<>Equivalent totopojson.merge.Merge(), but returns TopoJSON rather
than GeoJSON. The returned geometry is a shallow copy of the sourceobject:
they may share coordinates.#pytopojson.mesh.Mesh(topology[,object[,filter]])<>Returns the GeoJSON MultiLineString geometry object representing the mesh for
the specifiedobjectin the giventopology. This is useful for rendering
strokes in complicated objects efficiently, as edges that are shared by
multiple features are only stroked once. Ifobjectis not specified, a mesh
of the entire topology is returned. The returned geometry is a shallow copy of
the sourceobject: they may share coordinates.An optionalfilterfunction may be specified to prune arcs from the returned
mesh using the topology. The filter function is called once for each candidate
arc and takes two arguments,aandb, two geometry objects that share that
arc. Each arc is only included in the resulting mesh if the filter function
returnsTrue. For typical map topologies the geometriesaandbare
adjacent polygons and the candidate arc is their boundary. If an arc is only
used by a single geometry thenaandbare identical. This property is
useful for separating interior and exterior boundaries; an easy way to produce
a mesh of interior boundaries is:# Import topologyfrompytopojsonimportmesh# Create Mesh object and filtermesh_=mesh.Mesh()custom_filter=lambdax,y:x!=yinteriors=mesh_(topology,object_,custom_filter)See thiscounty choroplethfor example.
Note: theaandbobjects are TopoJSON objects (pulled directly from the
topology), and not automatically converted to GeoJSON features as bytopojson.feature.Feature().#pytopojson.mesh.MeshArcs(topology[,object[,filter]])<>Equivalent totopojson.mesh.Mesh(), but returns TopoJSON rather than
GeoJSON. The returned geometry is a shallow copy of the sourceobject: they
may share coordinates.#pytopojson.neighbors.Neighbors(objects)<>Returns an array representing the set of neighboring objects for each object
in the specifiedobjectsarray. The returned array has the same number of
elements as the input array; each elementiin the returned array is the
array of indexes for neighbors of objectiin the input array. For example,
if the specified objects array contains the featuresfooandbar, and
these features are neighbors, the returned array will be[[1], [0]],
indicating thatfoois a neighbor ofbarand vice versa. Each array of
neighbor indexes for each object is guaranteed to be sorted in ascending order.For a practical example, see theworld mapwith topological coloring.Transforms#pytopojson.bbox.BBox(topology)<>Returns the computedbounding boxof the specifiedtopology[x₀,y₀,x₁,y₁] wherex₀ is the minimumx-value,y₀ is the minimumy-value,x₁ is the maximumx-value, andy₁ is the maximumy-value. If thetopologyhas no points and no arcs,
the returned bounding box is [∞, ∞, -∞, -∞]. (This method ignores the existingtopology.bbox, if any.)#pytopojson.quantize.Quantize(topology,transform)<>Returns a shallow copy of the specifiedtopologywithquantized and delta-encodedarcs according to the specifiedtransformobject.
If thetopologyis already quantized, an error is thrown. See alsotopoquantize.If a quantization numbernis specified instead of atransformobject, the
corresponding transform object is first computed using the bounding box of the
topology. In this case, the quantization numbernmust be a positive integer
greater than one which determines the maximum number of expressible values per
dimension in the resulting quantized coordinates; typically, a power of ten is
chosen such as 1e4, 1e5 or 1e6. If thetopologydoes not already have atopology.bbox, one is computed usingtopojson.bbox.BBox.#pytopojson.transform.Transform(transform)<>If the specifiedtransformobjectis non-null, returns apointtransformfunctionto remove
delta-encoding and apply the transform. If thetransformis null, returns
the identity function.#pytopojson.untransform.Untransform(transform)<>If the specifiedtransformobjectis non-null, returns apointtransformfunctionto apply
quantized delta-encoding and remove the transform. If thetransformis null,
returns the identity function. See alsotopojson.quantize.Quantize().Command-Line ReferenceSome command-line tools are also provided:geo2topo#geo2topo[options…]
[name=]file…<>Converts one or more GeoJSON objects to an output topology. For example, to
convert a GeoJSON FeatureCollection in the input file us-states.json to a
TopologyJSON topology in the output file us.json:pythongeo2topo.pystates=us-states.json>us.jsonThe resulting topology has a “states” object which corresponds to the input
geometry. For convenience, you can omit the object name and specify only the
outputfilename; the object name will then be the basename of the file,
with the directory and extension removed. For example, to convert the
states.json GeoJSON FeatureCollection to a TopologyJSON topology with the
“states” object in us.json:pythongeo2topo.pystates.json>us.jsonAny properties and identifiers of inputfeature objectsare
propagated to the output. If you want to transform or filter properties,
tryndjson-clias demonstrated inCommand-Line Cartography.#geo2topo-h#geo2topo--helpOutput usage information.#geo2topo-V#geo2topo--versionOutput the version number.#geo2topo-ofile#geo2topo--outfileSpecify the output TopoJSON file name. Defaults to “-” for stdout.#geo2topo-qcount#geo2topo--quantizationcountSpecify a pre-quantization parameter. 0 disables quantization. Seepytopojson.topology.Topologyfor a description of
quantization.topo2geo#topo2geo[options…]
[name=]file…<>Converts one or more TopoJSON objects from an input topology to one or more
GeoJSON features. For example, to convert the "states" TopoJSONGeometryCollectionobject inus.jsonto a GeoJSON feature collection inus-states.json:pythontopo2geo.pystates=us-states.json<us.jsonFor convenience, you can omit the object name and specify only the filename;
the object name will be the basename of the file, with the directory and
extension removed. For example, to convert the "states" TopoJSONGeometryCollectionobject inus.jsonto a GeoJSON feature collection instates.json:pythontopo2geo.pystates.json<us.jsonSee alsogeo2topo.To list the available object names, use--list.#topo2geo-h#topo2geo--helpOutput usage information.#topo2geo-V#topo2geo--versionOutput the version number.#topo2geo-ifile#topo2geo--infileSpecify the input TopoJSON file name. Defaults to "-" for stdin.#topo2geo-l#topo2geo--listList the names of the objects in the input topology, and then exit. For
example, this:pythontopo2geo.py-l<us.jsonWill output this:counties
states
nationtopoquantize#topoquantize[options…] -q  [input]<>Quantizes the coordinates of the input TopoJSON topology anddelta-encodesthe topology’s arcs. The quantization parameterqmust be a positive integer
greater than one, and determines the maximum expressible number of unique
values per dimension in the resulting quantized coordinates; typically, a power
of ten is chosen such as 1e4, 1e5 or 1e6. If thetopologydoes not already
have abbox, one is computed and assigned. If thetopologyis
already quantized, an error is thrown. See alsopytopojson.quantize.Quantize.#topoquantize-h#topoquantize--helpOutput usage information.#topoquantize-V#topoquantize--versionOutput the version number.#topoquantize-iinput#topoquantize--ininputSpecify the input TopoJSON. Defaults to "-" for stdin.#topoquantize-ooutput#topoquantize--outoutputSpecify the output TopoJSON file name. Defaults to "-" for stdout.