Landfall

Landfall turns geographic data into static map images with a small Python API. Plot points, routes, polygons, and circles; combine layers; or read GeoJSON and GeoPandas data. It uses py-staticmaps for map tiles and returns Pillow images.

_{Routes · translucent areas · layered maps}

Install

Landfall supports Python 3.8–3.13. Install the optional geo extra for GeoPandas and Shapely integration.

python -m pip install landfall
python -m pip install 'landfall[geo]'  # optional

The default OpenStreetMap tile provider needs network access when rendering. If you use a different tile provider, pass a py-staticmaps provider through tile_provider or configure a Context directly.

Make a map

import landfall

image = landfall.plot_points(
    [(27.88, -82.49), (27.92, -82.46), (27.94, -82.44)],
    colors="distinct",
    point_size=14,
    window_size=(640, 440),
    zoom=-1,
)
image.save("tampa-points.png")

Native coordinate pairs are (latitude, longitude). GeoJSON and Shapely positions are (longitude, latitude); Landfall converts them. For native inputs already in longitude/latitude order, use flip_coords=True.

Every plot_* function returns a PIL.Image.Image. Use Context when a map needs multiple kinds of shapes or an SVG result:

map_context = landfall.Context()
map_context.add_points([27.88, 27.92], [-82.49, -82.46], colors="distinct")
map_context.add_line([(27.88, -82.49), (27.92, -82.46)], color="red")
map_context.add_circle(27.88, -82.49, 1000, fill_color="#ff000064")
map_context.render_pillow(800, 600).save("combined.png")
map_context.render_svg(800, 600).saveas("combined.svg")

More maps you can run

route = [(27.88, -82.49), (27.90, -82.47),
         (27.92, -82.46), (27.94, -82.44)]
landfall.plot_line(
    route, color="#d12c31", width=5, window_size=(640, 440), zoom=-1
).save("route.png")

landfall.plot_circle(
    27.88, -82.49, 1000,
    color="#9b2727", fill_color="#d12c3155", width=3,
    window_size=(640, 440),
).save("coverage.png")

Circle radii are in meters by default; set radius_unit="kilometers" for kilometers. Colors can be names, hex values, RGB/RGBA tuples, or staticmaps.Color objects. Batch functions also accept the "distinct", "random", and "wheel" palettes. The checked-in images above were generated with examples/generate_doc_maps.py using real OpenStreetMap tiles; tile attribution appears in each image.

Documentation

Read the full documentation on Read the Docs.

The documentation index also links to example notebooks. For release history, see the changelog.

Support and license

Report bugs or request features through GitHub Issues. Landfall is released under the MIT license.