Available Layer Types in Prettymaps: Streets, Water, and Buildings

Prettymaps renders maps by pulling OpenStreetMap data into named layers—streets, water, and building—where each identifier triggers a distinct fetch, transform, and draw pipeline.

The marceloprates/prettymaps library generates artistic maps by organizing OpenStreetMap (OSM) data into semantic layers. Understanding the available layer types in prettymaps is essential because each name controls how geometries are retrieved, whether they are treated as graphs or polygons, and how they appear in the final composition.

Core Prettymaps Layer Types

Prettymaps recognizes specific string names that determine how OSM data is queried and what geometry type is produced.

Streets

The streets layer is a graph-based layer. In prettymaps/fetch.py, the function unified_osm_request detects this name and calls osmnx.graph_from_polygon to retrieve the street network inside the query polygon. The graph is then converted with ox.graph_to_gdfs. In prettymaps/draw.py, the helper gdf_to_shapely dispatches to graph_to_shapely, turning every edge into a buffered line whose width can be customized. This produces the main road network rendered as thick or thin lines.

Water

The water layer uses ox.features.features_from_polygon with the OSM tag { "natural": "water" }. It produces a collection of LineString and Polygon geometries representing rivers, streams, canals, and lakes. The name waterway is also accepted and uses the tag "waterway", making it ideal for river networks and canals. When rendered, these typically appear as blue-coloured water bodies.

Building

The building layer pulls OSM features with the tag { "building": True }. Because it is not part of the special graph-based family, unified_osm_request falls back to a simple feature query. The raw geometries are polygons or multipolygons representing building footprints. In prettymaps/draw.py, these pass through geometries_to_shapely and are rendered as solid or outlined blocks that create the urban texture.

Fetch and Render Pipeline

The distinction between layer types is hard-coded in two core files.

In prettymaps/fetch.py, unified_osm_request decides whether a layer belongs to the graph family. Only streets, railway, and waterway receive the ox.graph_from_polygon treatment. All other names—including water and building—are fetched as standard OSM features.

In prettymaps/draw.py, gdf_to_shapely routes graph-based layers to graph_to_shapely and everything else to geometries_to_shapely. For non-graph layers, geometries_to_shapely simply buffers points or lines if a point_size or line_width is supplied; otherwise it passes the geometry through unchanged.

Style control happens through dictionaries such as GPX_STYLE or user-provided style arguments, where you can set face colour (fc), edge colour (ec), line width (lw), and hatch patterns per layer name.

Customizing Layers in Code

You can configure the available layer types in prettymaps directly inside the layers and style arguments of pm.plot.

Basic Three-Layer Map

import prettymaps as pm

pm.plot(
    query="Porto Alegre, Brazil",
    layers={
        "streets": {"width": 1.5},          # street network (graph)

        "water":   {"fc": "#a0c8f0"},       # water bodies (polygons)

        "building": {"fc": "#d9c5a1"},      # building footprints

    },
    style={
        "streets": {"ec": "#475657", "lw": 0},
        "water":   {"ec": "#2F3737"},
        "building": {"ec": "#2F3737"},
    },
    figsize="a4",
    show=True,
)

Custom Street Widths and Transparent Buildings

pm.plot(
    query="Manhattan, NY",
    layers={
        "streets": {"width": {"motorway": 4, "primary": 2, "secondary": 1}},
        "building": {"fc": "#F1E6D0", "alpha": 0.6},
        "water": {"fc": "#CDE4F5"},
    },
    style={},
    show=True,
)

Combining Water and Waterway Layers

pm.plot(
    query="Zurich, Switzerland",
    layers={
        "streets":  {},
        "building": {},
        "water":    {},                 # natural water (lakes, ponds)

        "waterway": {"fc": "#6AA9FF"}  # rivers & canals

    },
    style={},
    show=True,
)

Auxiliary Layers and Fallback Behavior

Beyond the three main visual layers, prettymaps defines auxiliary layers such as hillshade, sea, gpx, and perimeter. These support extra effects like relief shading, sea masks, and GPS track overlays, but they are not visualized as standard streets, water, or buildings.

When a layer name is not one of the recognized graph-based identifiers, prettymaps automatically falls back to geometries_to_shapely. This behavior ensures that any valid OSM feature tag can be passed through and rendered without requiring explicit hard-coding in the library.

Summary

• streets is fetched as an OSMnx graph, converted to GeoDataFrames, and rendered as buffered lines via graph_to_shapely.
• water queries natural=water features, while waterway queries waterway features; both produce LineString or Polygon geometries.
• building queries building=True features and produces Polygon or MultiPolygon footprints.
• prettymaps/fetch.py and prettymaps/draw.py split the pipeline into graph-based vs. geometry-based processing.
• Layer appearance is controlled through the layers and style dictionaries passed to pm.plot.

Frequently Asked Questions

What are the default layer types available in prettymaps?

Prettymaps supports three primary visual layer types out of the box: streets for road networks, water for natural water bodies, and building for structure footprints. It also accepts waterway as a variant of the water layer and provides auxiliary layers such as hillshade, sea, gpx, and perimeter for additional effects.

How does prettymaps fetch street networks differently from water or buildings?

According to the marceloprates/prettymaps source code, the unified_osm_request function in prettymaps/fetch.py treats streets as a graph. It uses osmnx.graph_from_polygon and ox.graph_to_gdfs, whereas water and building are fetched as standard OSM features through ox.features.features_from_polygon.

Can I plot both water and waterway in the same prettymaps composition?

Yes. The water layer renders natural water bodies like lakes and ponds, while waterway targets linear features such as rivers and canals. You can include both keys in the layers dictionary simultaneously and assign each its own style parameters.

Where does the conversion from OSM data to Shapely geometries happen?

The conversion is handled in prettymaps/draw.py. The gdf_to_shapely helper dispatches graph-based layers to graph_to_shapely and all other layers to geometries_to_shapely, which either buffers points and lines or passes polygon geometries through unchanged.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}