.topojson

class: Topology

class Topology(data, topology=True, prequantize=True, topoquantize=False, presimplify=False, toposimplify=False, shared_coords=False, prevent_oversimplify=True, simplify_with='shapely', simplify_algorithm='dp', winding_order='CW_CCW', object_name='data')[source]

Object representation of a topology.

Note

Inherits from topojson.Topology with additional methods conforming to the HighchartsMeta interface.

Class Inheritance
Inheritance diagram of Topology

classmethod from_dict(as_dict: dict, allow_snake_case: bool = True)[source]

Construct an instance of the class from a dict object.

Parameters:

  • as_dict (dict) – A dict representation of the object.

  • allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python object representation of as_dict.

Return type:

HighchartsMeta

classmethod from_geodataframe(as_gdf, prequantize=False, **kwargs)[source]

Create a MapData instance from a geopandas.GeoDataFrame.

Parameters:

  • as_gdf (geopandas.GeoDataFrame) – The geopandas.GeoDataFrame containing the relevant map geometries.

  • prequantize (bool) – If True, will perform the TopoJSON optimizations (“quantizing the topology”) before generating the Topology instance. Defaults to False.

Return type:

MapData

classmethod from_geojson(as_geojson_or_file: str | bytes, allow_snake_case: bool = True, **kwargs)[source]

Construct an instance of the class from a JSON string.

Parameters:

  • as_geojson_or_file (str or bytes) – The GeoJSON string for the object or the filename of a file that contains the GeoJSON string.

  • allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python objcet representation of as_geojson_or_file.

Return type:

MapData

classmethod from_js_literal(as_str_or_file, allow_snake_case: bool = True, _break_loop_on_failure: bool = False)[source]

Return a Python object representation of a Highcharts JavaScript object literal.

Parameters:

  • as_str_or_file (str) – The JavaScript object literal, represented either as a str or as a filename which contains the JS object literal.

  • allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

  • _break_loop_on_failure (bool) – If True, will break any looping operations in the event of a failure. Otherwise, will attempt to repair the failure. Defaults to False.

Returns:

A Python object representation of the Highcharts JavaScript object literal.

Return type:

HighchartsMeta

classmethod from_json(as_json_or_file: str | bytes, allow_snake_case: bool = True)[source]

Construct an instance of the class from a JSON string.

Parameters:

  • as_json_or_file – The JSON string for the object or the filename of a file that contains the JSON string.

  • allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python objcet representation of as_json.

Return type:

MapData

classmethod from_topojson(as_topojson_or_file: str | bytes, allow_snake_case: bool = True, **kwargs)[source]

Construct an instance of the class from a TopoJSON string.

Parameters:

  • as_topojson_or_file (str or bytes) – The TopoJSON string for the object or the filename of a file that contains the TopoJSON string.

  • allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python objcet representation of as_topojson_or_file.

Return type:

MapData

to_alt(color=None, tooltip=True, projection='identity', object_name=0)[source]

Display as Altair visualization.

Parameters:

  • color (str or None) – Assign a 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'. Defaults to None, which renders as a mesh.

  • tooltip (bool) – Option to include or exclude tooltips on geoshape objects. Defaults to True.

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

  • object_name (str or int) – The name or the index of the object within the Topology to display. Defaults to index 0.

to_dict(options=False)[source]

Convert the Topology to a dict.

Parameters:

options (bool) – If True, options also will be included. Defaults to False.

Return type:

dict

to_gdf(crs=None, validate=False, winding_order='CCW_CW', object_name=0)[source]

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

Note

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

Parameters:

  • crs (str or dict or None) – coordinate reference system to set on the resulting frame. Default tries to use crs from data-input, otherwise is None.

  • validate (bool) – Set to True to validate each feature before inclusion in the GeoJSON. Only features that are valid geometries objects will be included. Defaults to False.

  • winding_order (str) –

    Determines the winding order of the features in the output geometry. Accepts:

    • 'CW_CCW' for clockwise orientation for outer rings and counter-clockwise for interior rings

    • 'CCW_CW' for counter-clockwise for outer rings and clockwise for interior rings.

    Default is CCW_CW for GeoJSON.

  • object_name (str or int) – Name or index of the object. Defaults to 0 to select the first object.

Return type:

geopandas.GeoDataFrame

to_geodataframe(object_name=None)[source]

Generate a GeoPandas.GeoDataFrame instance of the topology.

Parameters:

object_name (str or int or None) – If the map data contains multiple objects, you can generate serialize a specific object by specifying its name or index. Defaults to None, which behaves as an index of 0.

Return type:

geopandas.GeoDataFrame

to_geojson(fp=None, pretty=False, indent=4, maxlinelength=88, validate=False, winding_order='CCW_CW', decimals=None, object_name=0)[source]

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

Parameters:

  • fp (str or None) – If set, writes the object to a file on drive. Defaults to None.

  • pretty (bool) – If True, the JSON object will be ‘pretty’, depending on the ident and maxlinelength options. If False, it will be compact, eliminating whitespace. Default is False.

  • indent (int) – If pretty is True, determines object indentation. Defaults to 4.

  • maxlinelength (int) – If pretty is True, determines the maximum length of each line. Defaults to 88.

  • validate (bool) – 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.

  • winding_order (str) –

    Determines the winding order of the features in the output geometry. Accepts:

    • 'CW_CCW' for clockwise orientation for outer rings and counter-clockwise for interior rings

    • 'CCW_CW' for counter-clockwise for outer rings and clockwise for interior rings.

    Default is CCW_CW for GeoJSON.

  • decimals (int or None) – Evenly round the coordinates to the given number of decimals. Default is None, which means no rounding is applied.

  • object_name (str or int) – Name or index of the object. Defaults to 0 to select the first object.

to_js_literal(filename=None, encoding='utf-8', careful_validation=False) → str | None[source]

Return the object represented as a str containing the JavaScript object literal.

Parameters:

  • filename (Path-like) – The name of a file to which the JavaScript object literal should be persisted. Defaults to None

  • encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.

  • careful_validation – if True, will carefully validate JavaScript values

along the way using the esprima-python library. Defaults to False.

Warning

Setting this value to True will significantly degrade serialization performance, though it may prove useful for debugging purposes.

Return type:

str or None

to_json(filename=None, encoding='utf-8')[source]

Generate a JSON string/byte string representation of the object compatible with the Highcharts JavaScript library.

Note

This method will either return a standard str or a bytes object depending on the JSON serialization library you are using. For example, if your environment has orjson, the result will be a bytes representation of the string.

Parameters:

  • filename (Path-like) – The name of a file to which the JSON string should be persisted. Defaults to None

  • encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.

Returns:

A JSON representation of the object compatible with the Highcharts library.

Return type:

str or bytes

to_svg(separate=False)[source]

Display the arcs and junctions as SVG.

Parameters:

separate (bool) – If True, each of the arcs will be displayed separately. Defaults to False.

to_topojson(filename=None, encoding='utf-8')[source]

Generate a TopoJSON string/byte string representation of the object.

Note

This method will either return a standard str or a bytes object depending on the JSON serialization library you are using. For example, if your environment has orjson, the result will be a bytes representation of the string.

Parameters:

  • filename (Path-like) – The name of a file to which the JSON string should be persisted. Defaults to None

  • encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.

Returns:

A TopoJSON representation of the object

Return type:

str or bytes

to_widget(slider_toposimplify=None, slider_topoquantize=None)[source]

Create an interactive widget based on Altair. The widget includes sliders to interactively change the toposimplify and topoquantize settings.

Parameters:

  • slider_toposimplify (dict) – A dict which contains the keys: min, max, step, value. Defaults to: {"min": 0, "max": 10, "step": 0.01, "value": 0.01}

  • slider_topoquantize (dict) – A dict which contains the keys: min, max, value, base. Defaults to: {"min": 1, "max": 6, "step": 1, "value": 1e5, "base": 10}

topoquantize(quant_factor, inplace=False)[source]

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:

  • quant_factor (float) – tolerance parameter

  • inplace (bool) – If True, do operation in place and return None. Defaults to False.

Returns:

Quantized coordinates and delta-encoded arcs if inplace is False

Return type:

object or None

toposimplify(epsilon, simplify_algorithm=None, simplify_with=None, prevent_oversimplify=None, inplace=False)[source]

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:

  • epsilon (float) – tolerance parameter

  • simplify_algorithm (str or None) – Choose between 'dp' and 'vw', for Douglas-Peucker or Visvalingam-Whyatt respectively. 'vw' will only be supported if simplify_with is set to 'simplification'. Defaults to None, which behaves as 'dp'.

  • simplify_with (str or None) – Sets the package to use for simplifying. Choose between 'shapely' or 'simplification'. shapely only supports Douglas-Peucker and simplification supports both Douglas-Peucker and Visvalingam-Whyatt. The simplification package is known to be quicker than shapely. Defaults to None, which behaves as 'shapely'.

  • prevent_oversimplify (bool or None) – 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. Defaults to None, which behaves as True.

  • inplace (bool) – If True, do operation in place and return None. Defaults to False.

Returns:

Topology object with simplified linestrings if inplace is False, otherwise None

Return type:

Topology or None