Skip to content

topojson.core.topology

Topology

Bases: Hashmap

Returns a TopoJSON topology for the specified geometric object. TopoJSON is an extension of GeoJSON providing multiple approaches to compress the geographical input data. These options include simplifying the linestrings or quantizing the coordinates but foremost the computation of a topology.

Parameters:

Name Type Description Default
data _any_ geometric type

Geometric data that should be converted into TopoJSON, such as GeoJSON, shapely geometries, a GeoDataFrame or a Polars DataFrame with a column of WKB (polars-st). It is possible to provide a list of multiple GeoDataFrames as separate objects. In this case it is required to provide an equal length list of the names of the objects for parameter object_name.

 required
topology boolean

Specify if the topology should be computed for deriving the TopoJSON. Default is True.

 True
prequantize (boolean, int, dict)

If the prequantization parameter is specified, the input geometry is quantized prior to computing the topology, the returned topology is quantized, and its arcs are delta-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. The grid is then derived from the bounding box of the input. Alternatively, provide a fixed TopoJSON transform as a dict ({"scale": [kx, ky], "translate": [x0, y0]}) to quantize on a grid that does not depend on the input, for example the transform of a previously computed Topology (topo.output["transform"]). The grid then stays the same when features are added or removed. Default is True (which correspond to a quantize factor of 1e5).

 True
topoquantize (boolean, int or dict)

If the topoquantization parameter is specified, the input geometry is quantized after the topology is constructed. If the topology is already quantized this will be resolved first before the topoquantization is applied. As for prequantize, a fixed TopoJSON transform can be given as a dict. See for more details the prequantize parameter. Default is False.

 False
presimplify (boolean, float)

Apply presimplify to remove unnecessary points from linestrings before the topology is constructed. This will simplify the input geometries; lines are simplified one by one, so shared borders can drift apart, unless simplify_with is geos. True uses a tolerance of 2. Default is False.

 False
toposimplify (boolean, float)

Apply toposimplify to remove unnecessary points from arcs after the topology is constructed. This will simplify the constructed arcs without altering the topological relations. Sensible values for coordinates stored in degrees are in the range of 0.0001 to 10. Defaults to False.

 False
shared_coords boolean

Sets the strategy to detect junctions. When set to False a path is considered shared when coordinates are the same path (path-connected). The path-connected strategy is more 'correct', but slightly slower. When set to True a path is considered shared when all coordinates appear in both paths (coords-connected). Default is False.

 False
prevent_oversimplify boolean

If this setting is set to True, the simplification is slower, but the likelihood of producing valid geometries is higher as it prevents oversimplification. Simplification happens on paths separately, so this setting is especially relevant for rings with no partial shared paths. This is also known as a topology-preserving variant of simplification. With toposimplify, a ring that would be reduced to fewer than three points keeps the vertices to stay a triangle. Default is True.

 True
simplify_with str

Sets the package to use for simplifying (both pre- and toposimplify). Choose between shapely, simplification or geos. Shapely adopts solely Douglas-Peucker and simplification both Douglas-Peucker and Visvalingam-Whyatt. The package simplification is known to be quicker than shapely. geos applies to presimplify only: it simplifies the polygons together as a coverage (shapely.coverage_simplify, Visvalingam-Whyatt), so that shared borders stay matched and each ring stays at least a triangle; other lines are simplified with shapely. The polygons should form a valid coverage (shapely.coverage_is_valid). Default is shapely.

 'shapely'
simplify_algorithm str

Choose between dp and vw, for Douglas-Peucker or Visvalingam-Whyatt respectively. vw will only be selected if simplify_with is set to simplification. Default is dp.

 'dp'
winding_order str

Determines the winding order of the features in the output geometry. Choose between CW_CCW for clockwise orientation for outer rings and counter- clockwise for interior rings. Or CCW_CW for counter-clockwise for outer rings and clockwise for interior rings. Default is CW_CCW for TopoJSON.

 'CW_CCW'
object_name Union[str, list[str]]

Name to use as key for the objects in the topojson file. This name is used for writing and reading topojson file formats. It is possible to define multiple objects within the topojson file. In this case it is required to provide a list of the referenced object_name in combination with an equal length list of data objects. Default is a single object named data.

 'data'
ignore_index bool

If set to true existing ids/indexes of geojson FeatureCollections will be ignored and overwritten. Otherwise features with ids will use their existing one. If indexes are not ignored and a duplicate id exists an exception will be raised. Default is false.

 False

to_dict 

to_dict(options: bool = False, state: bool = False) -> dict[str, Any]

Convert the Topology to a dictionary.

Parameters:

Name Type Description Default
options boolean

If True, the options also will be included. Default is False

 False
state boolean

If True, the options and a hash of the input geometry of each feature (source_hashes) are included, so that Topology.read_json and sync can continue from it. Default is False

 False

to_svg 

to_svg(separate: bool = False) -> None

Display the arcs and junctions as SVG.

Parameters:

Name Type Description Default
separate boolean

If True, each of the arcs will be displayed separately. Default is False

 False

to_json 

to_json(fp: str | PathLike[str] | None = None, options: bool = False, pretty: bool = False, indent: int = 4, maxlinelength: int = 88, state: bool = False) -> str | None

Convert the Topology to a JSON object.

Parameters:

Name Type Description Default
fp str

If set, writes the object to a file on drive. Default is None.

 None
options boolean

If True, the options also will be included. Default is False.

 False
pretty boolean

If pretty=True, the JSON object will be 'pretty', depending on the ident and maxlinelength options. If pretty=False, it will compact, eliminating whitespace. Default is False.

 False
indent int

If style='pretty', declares the indentation of the objects. Default is 4.

 4
maxlinelength int

If style='pretty', declares the maximum length of each line. Default is 88.

 88
state boolean

If True, the options and a hash of the input geometry of each feature (source_hashes) are included, so that Topology.read_json and sync can continue from it in a next run. Default is False.

 False

to_geojson 

to_geojson(fp: str | PathLike[str] | None = None, pretty: bool = False, indent: int = 4, maxlinelength: int = 88, validate: bool = False, winding_order: WindingOrder = 'CCW_CW', decimals: int | None = None, object_name: str | int = 0) -> str | None

Convert the Topology to a GeoJSON object. Remember that this will destroy the computed Topology.

Parameters:

Name Type Description Default
fp str

If set, writes the object to a file on drive. Default is None

 None
pretty boolean

If pretty=True, the JSON object will be 'pretty', depending on the ident and maxlinelength options. If pretty=False, it will compact, eliminating whitespace. Default is False.

 False
indent int

If pretty=True, declares the indentation of the objects. Default is 4.

 4
maxlinelength int

If pretty=True, declares the maximum length of each line. Default is 88.

 88
validate boolean

Set to True to validate each feature before inclusion in the GeoJSON. Only features that are valid geometries objects will be included. Default is False.

 False
winding_order str

Determines the winding order of the features in the output geometry. Choose between CW_CCW for clockwise orientation for outer rings and counter- clockwise for interior rings. Or CCW_CW for counter-clockwise for outer rings and clockwise for interior rings. Default is CCW_CW for GeoJSON.

 'CCW_CW'
decimals int or None

Evenly round the coordinates to the given number of decimals. Default is None, which means no rounding is applied.

 None
object_name (str, int)

The name or the index of the object within the Topology to display. Default is index 0.

 0

to_gdf 

to_gdf(crs: Any = None, validate: bool = False, winding_order: WindingOrder = 'CCW_CW', object_name: str | int = 0) -> geopandas.GeoDataFrame

Convert the Topology to a GeoDataFrame. Remember that this will destroy the computed Topology.

Note: This function use not the TopoJSON driver within Fiona, but a custom implemented more robust variant. See for info the to_geojson() function.

Parameters:

Name Type Description Default
crs (str, dict)

coordinate reference system to set on the resulting frame. Default tries to use crs from data-input, otherwise is None.

 None
validate boolean

Set to True to validate each feature before inclusion in the GeoJSON. Only features that are valid geometries objects will be included. Default is False.

 False
winding_order str

Determines the winding order of the features in the output geometry. Choose between CW_CCW for clockwise orientation for outer rings and counter- clockwise for interior rings. Or CCW_CW for counter-clockwise for outer rings and clockwise for interior rings. Default is CCW_CW for GeoJSON.

 'CCW_CW'
object_name (str, int)

Name or index of the object. Default is index 0 to select the first object.

 0

to_polars 

to_polars(crs: Any = None, validate: bool = False, winding_order: WindingOrder = 'CCW_CW', object_name: str | int = 0) -> polars.DataFrame

Convert the Topology to a Polars DataFrame: the id and the properties as columns, and the geometry as WKB in the column geometry, as polars-st stores it. With a CRS that has an EPSG code, the WKB is EWKB with this code as SRID, so that polars-st knows the CRS. Remember that this will destroy the computed Topology.

Parameters:

Name Type Description Default
crs (str, int, CRS)

coordinate reference system of the geometries, such as "EPSG:4326". Default tries to use crs from data-input, otherwise is None.

 None
validate boolean

Set to True to validate each feature before inclusion in the GeoJSON. Only features that are valid geometries objects will be included. Default is False.

 False
winding_order str

Determines the winding order of the features in the output geometry. Choose between CW_CCW for clockwise orientation for outer rings and counter- clockwise for interior rings. Or CCW_CW for counter-clockwise for outer rings and clockwise for interior rings. Default is CCW_CW for GeoJSON.

 'CCW_CW'
object_name (str, int)

Name or index of the object. Default is index 0 to select the first object.

 0

to_alt 

to_alt(color: str | None = None, tooltip: bool = True, projection: str = 'identity', object_name: str | int = 0) -> altair.Chart

Display as Altair visualization.

Parameters:

Name Type Description Default
color str

Assign an property attribute to be used for color encoding and renders the Altair visualization as geoshape. Remember that most of the time the wanted attribute is nested within properties. Moreover, specific type declaration is required. Eg color='properties.name:N'. Default is None (render as mesh).

 None
tooltip boolean

Option to include or exclude tooltips on geoshape objects Default is True.

 True
projection str

Defines the projection of the visualization. Defaults to a non-geographic, Cartesian projection (known by Altair as identity).

 'identity'
object_name (str, int)

The name or the index of the object within the Topology to display. Default is index 0.

 0

to_widget 

to_widget(slider_toposimplify: Slider | None = None, slider_topoquantize: Slider | None = None, slider_keep: Slider | None = None) -> Any

Create an interactive widget based on Altair. The widget includes sliders to interactively change the toposimplify and topoquantize settings. With an algorithm "share of vertices", the keep slider sets the share of the vertices to keep instead of the tolerance.

Parameters:

Name Type Description Default
slider_toposimplify dict

The dict should contain the following keys: min, max, step, value. Default is {"min": 0, "max": 10, "step": 0.01, "value": 0.01}.

 None
slider_topoquantize dict

The dict should contain the following keys: min, max, value, base. Default is {"min": 1, "max": 6, "step": 1, "value": 1e5, "base": 10}.

 None
slider_keep dict

The dict should contain the following keys: min, max, step, value. Default is {"min": 0, "max": 1, "step": 0.01, "value": 0.1}.

 None

topoquantize 

topoquantize(quant_factor: float | Transform, inplace: Literal[False] = False) -> Self

topoquantize(quant_factor: float | Transform, inplace: Literal[True]) -> None

topoquantize(quant_factor: float | Transform, inplace: bool = False) -> Self | None

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.

Parameters:

Name Type Description Default
quant_factor float or dict

Quantization factor: the number of steps on each axis of the bounding box. Or a fixed TopoJSON transform as a dict ({"scale": [kx, ky], "translate": [x0, y0]}), for example a grid with cells that are a multiple of those of prequantize, so that each quantized point is also a point of the finer grid.

 required
inplace bool

If True, do operation inplace and return None. Default is False.

 False

Returns:

Type Description
object or None

Quantized coordinates and delta-encoded arcs if inplace is False.

toposimplify 

toposimplify(epsilon: float | None = None, simplify_algorithm: Algorithm | None = None, simplify_with: Package | None = None, prevent_oversimplify: bool | None = None, inplace: Literal[False] = False, keep: float | None = None) -> Self

toposimplify(epsilon: float | None = None, simplify_algorithm: Algorithm | None = None, simplify_with: Package | None = None, prevent_oversimplify: bool | None = None, *, inplace: Literal[True], keep: float | None = None) -> None

toposimplify(epsilon: float | None = None, simplify_algorithm: Algorithm | None = None, simplify_with: Package | None = None, prevent_oversimplify: bool | None = None, inplace: bool = False, keep: float | None = None) -> Self | None

Apply toposimplify to remove unnecessary points from arcs after the topology is constructed. This will simplify the constructed arcs without altering the topological relations. Sensible values for coordinates stored in degrees are in the range of 0.0001 to 10.

Parameters:

Name Type Description Default
epsilon float

tolerance parameter. Give either epsilon or keep.

 None
simplify_algorithm str

Choose between dp and vw, for Douglas-Peucker or Visvalingam-Whyatt respectively. vw will only be selected if simplify_with is set to simplification. Default is None, meaning that the default (dp) is not overwritten.

 None
simplify_with str

Sets the package to use for simplifying. Choose between shapely or simplification. Shapely adopts solely Douglas-Peucker and simplification both Douglas-Peucker and Visvalingam-Whyatt. The package simplification is known to be quicker than shapely. geos applies to presimplify only and raises a ValueError here. Default is None, meaning that the default (shapely) is not overwritten.

 None
prevent_oversimplify boolean

If this setting is set to True, the simplification is slower, but the likelihood of producing valid geometries is higher as it prevents oversimplification. Simplification happens on paths separately, so this setting is especially relevant for rings with no partial shared paths. This is also known as a topology-preserving variant of simplification. With toposimplify, a ring that would be reduced to fewer than three points keeps the vertices to stay a triangle. Default is None, meaning that the default (True) is not overwritten.

 None
inplace bool

If True, do operation inplace and return None. Default is False.

 False
keep float

Instead of epsilon, the share of the vertices to keep, between 0 and 1: the inner vertices of the arcs that the algorithm removes last are kept, the ends of the arcs always. The result is that of the matching epsilon. Douglas-Peucker uses its own implementation, whatever simplify_with; Visvalingam-Whyatt (simplify_algorithm="vw") uses the package simplification. With prevent_oversimplify a ring stays at least a triangle.

 None

Returns:

Type Description
object or None

Topology object with simplified linestrings if inplace is False.

read_json classmethod 

read_json(fp: str | PathLike[str] | IO[str]) -> Self

Read a Topology from a TopoJSON file. If the file was written with to_json(..., state=True), the options and source hashes are restored, so that add, remove and sync can continue from it.

Parameters:

Name Type Description Default
fp str, path or file-like object

TopoJSON file to read.

 required

Returns:

Type Description
Topology

add 

add(data: Any, object_name: str | None = None) -> Self

Add features to the Topology without recomputing it. Existing arcs are cut where the new features share a path with them; the result is the same as a full build on the same quantization grid.

Parameters:

Name Type Description Default
data GeoDataFrame or GeoSeries

Features to add. The index is used as feature id and must not exist yet.

 required
object_name str

Object to add the features to. Only needed if the Topology has more than one object.

 None

Returns:

Type Description
Topology

self, so that calls can be chained.

remove 

remove(ids: Iterable[Hashable], object_name: str | None = None) -> Self

Remove features from the Topology without recomputing it. Arcs that are no longer used are dropped and arcs are merged where a point is no longer a junction. Compared to a full build, a ring that is no longer cut can start at another vertex, and the bbox (recomputed from the quantized data) can differ by at most half a grid cell.

Parameters:

Name Type Description Default
ids iterable

Ids of the features to remove.

 required
object_name str

Object to remove the features from. Only needed if the Topology has more than one object.

 None

Returns:

Type Description
Topology

self, so that calls can be chained.

sync 

sync(data: Any, object_name: str | None = None) -> Self

Make the Topology equal to data: features that are new are added, features that are gone are removed and features with a changed geometry are replaced. Unchanged features are left as they are. What happened is stored in self.last_sync.

Comparing uses a hash of the input geometry of each feature. These hashes are kept on the Topology and written with to_json(..., state=True).

Parameters:

Name Type Description Default
data GeoDataFrame or GeoSeries

The complete set of features; the index is the feature id.

 required
object_name str

Object to synchronise. Only needed if the Topology has more than one object.

 None

Returns:

Type Description
Topology

self, so that calls can be chained.