Python API

The Map class

FlotteKarte is designed for the use of the Map class, which provides a simple interface for converting a Matplotlib matplotlib.axes.Axes instance into a map by means of a PROJ string.

The Map class does not offer a large number of methods but a small number of cartography-related functionality. All plotting functionality can be performed normally on the matplotlib.axes.Axes instance in projected coordinates. A call to Map.plot_axes() adds coordinate ticks and map boundary, turning the two-dimensional canvas into a map.

class flottekarte.Map(proj_str, ax, xlim=None, ylim=None, proj=None, bisection_offset='auto', minimum_node_distance='auto', atol='auto')

A minimalistic map plotting tool using PROJ, pyproj, and Matplotlib.

Parameters

  • proj_str (str) – The legacy PROJ string definition of a projection.

  • ax (matplotlib.axes.Axes) – The axes to transform into a map.

  • xlim (tuple[float,float], optional) – The maximum x extent of the map (\(x_\mathrm{min}\), \(x_\mathrm{max}\)).

  • ylim (tuple[float,float], optional) – The maximum y extent of the map (\(y_\mathrm{min}\), \(y_\mathrm{max}\)).

  • proj (pyproj.Proj, optional) – A pyproj.Proj instance that corresponds to proj_str.

  • bisection_offset (float, optional) – Critical offset that determines whether a path segment will be refined. If the center of a spherical geodesic is offset further than this value from the center of the line segment in projected coordinates, the line segment is split (bisected). Given in projected coordinates. If not given, will be set to a fraction of the map extent.

  • minimum_node_distance (float, optional) – Stopping criterion for the segment refinement. If the two end points of a line segment are closer than this distance, the segment will not be split in refinement. Given in projected coordinates. If not given, will be set to a fraction of the map extent.

  • atol (float, optional) – Absolute tolerance to which a non-rectangular map boundary will be determined. This parameter is used when it has been determined that the bounding rectangle defined by xlim and ylim contains space that is not actually part of the image of the projection (e.g. when working with a global projection or close to the boundaries of an oblique projection). Given in projected coordinates. If not given, will be set to a fraction of the map extent.

add_data(dataset, **kwargs)

Add data loaded from the data submodule.

Parameters

dataset (GeoJSON) – A data set from the flottekarte.data submodule. Currently that includes only the GeoJSON class.

See also

GeoJSON

static for_data(lon, lat, proj_str, ax, margin_rel=0.05)

Generate a Map fitting some data in a given projection.

Parameters

  • lon (array_like) – Longitudes of the data set.

  • lat (array_like) – Latitudes of the data set.

  • proj_str (str) – The legacy PROJ string definition of a projection.

  • margin_rel (float, optional) – Introduce a margin relative to the extent of the data in projected coordinates.

Returns

Return type

Map

plot_axes(tick_spacing=1.0, which_ticks='auto', linewidth=0.8, fontsize=8.0, rotate_labels=True, ticks_bot=True, ticks_top=True, ticks_left=True, ticks_right=True, remove_overlaps=True)

Add axes and ticks to the plot.

Parameters

  • tick_spacing (float, optional) – Spacing of ticks in degrees.

  • which_ticks (str or list, optional) – The type of ticks to favor, longitude or latitude. If given as a list, has to be a four-element list that contains one of lon or lat per part of the boundary. Note: currently not used.

  • linewidth (float, optional) – Line width of boundary and ticks.

  • fontsize (float, optional) – Font size, in point, of coordinate tick labels.

  • rotate_labels (bool, optional) – Whether to rotate the labels parallel to the map boundary at the tick position.

  • ticks_bot (bool, optional) – Whether to plot ticks on the bottom axis. For a non-rectangular map shape, ‘bottom axis’ refers to all ticks that extend beyond ymin.

  • ticks_top (bool, optional) – Whether to plot ticks on the top axis. For a non-rectangular map shape, ‘top axis’ refers to all ticks that extend beyond ymax.

  • ticks_left (bool, optional) – Whether to plot ticks on the left axis. For a non-rectangular map shape, ‘left axis’ refers to all ticks that extend beyond xmin.

  • ticks_right (bool, optional) – Whether to plot ticks on the right axis. For a non-rectangular map shape, ‘right axis’ refers to all ticks that extend beyond xmax.

  • remove_overlaps (bool, optional) – Whether to apply the overlap removal algorithm.

Notes

The overlap algorithm uses a tick weighting scheme to remove the least weighted ticks whenever two ticks overlap. This tick weighting scheme considers, in descending order of importance, the following attributes of each tick:

  1. Is the tick requested?

  2. Is the tick part of a grid line intersecting the boundary?

  3. Is the tick at a “nice” value? (E.g. 0°, 90°, zero modul for a number of common divisiors)

plot_grid(tick_spacing_degree=10, max_lat=90.0, bisection_offset=None, minimum_node_distance=None, linewidth=0.8, **kwargs)

Add a geographic coordinte grid to the plot.

Parameters

  • tick_spacing_degree (int, optional) – Spacing of ticks in degrees.

  • max_lat (float, optional) – Maximum absolute latitude up to which to draw the grid lines.

  • bisection_offset (float, optional) – Critical offset that determines whether a path segment will be refined. If the center of a spherical geodesic is offset further than this value from the center of the line segment in projected coordinates, the line segment is split (bisected). Given in projected coordinates. If not given, will be set to a fraction of the map extent.

  • minimum_node_distance (float, optional) – Stopping criterion for the segment refinement. If the two end points of a line segment are closer than this distance, the segment will not be split in refinement. Given in projected coordinates. If not given, will be set to a fraction of the map extent.

  • linewidth (float, optional) – Width of the grid lines.

  • kwargs (optional) – Passed to matplotlib.LineCollection.

The GeoJSON class

This class allows to load data from a GeoJSON and plot it using Map.add_data().

class flottekarte.GeoJSON(fname, proj, xlim=None, ylim=None)

Loads data from a GeoJSON.

Parameters

  • fname (str) – Path to the GeoJSON file. Alternatively anything that can be accepted by open().

  • proj (str or pyproj.Proj) – Projection to evaluate the geometries in.

  • xlim (tuple[float,float], optional) – Selection x extent in projected coordinates. Given as \((x_\mathrm{min},x_\mathrm{max})\).

  • ylim (tuple[float,float], optional) – Selection y extent in projected coordinates. Given as \((y_\mathrm{min},y_\mathrm{max})\).

Notes

If no extents are given, all geometries are loaded. So far, only polygon and multipolygon geometries are loaded.

get_extent()

Get x and y limits.

Returns

  • xlim (tuple[float,float]) – x extents \((x_\mathrm{min},x_\mathrm{max})\)

  • ylim (tuple[float,float]) – y extents \((y_\mathrm{min},y_\mathrm{max})\)

get_polygon_patches(**kwargs)

Get matplotlib patches of the polygons and multipolygons.

Parameters

kwargs (optional) – Parameters to pass to the patch collection.

Returns

Patches for all polygons and multipolygons.

Return type

matplotlib.collections.PatchCollection