import ulg

ulg.element("wildflower_meadow").fill        # '#DADDBC': look colours up, never invent them
ulg.resolve("osm", landuse="meadow", meadow="wildflower")    # 'wildflower_meadow'
ulg.resolve("alkis", objart="41008", funktion="4420")         # 'green_space'

gdf["element"] = ulg.classify(gdf, "osm")     # OSM, ALKIS, XPlanung, CORINE … → elements
ulg.render_svg(gdf, scale=500, path="plan.svg")         # print-ready SVG, true to scale
ulg.render_svg(gdf, scale=1500, theme="planzv")         # the same data as a Bauleitplan
ulg.indicators(ulg.flatten(gdf))              # sealing, biotope area factor, runoff, canopy

What it is#

• 173 elements in English and German (vegetation, trees, water, ground, 33 surfaces, land use, buildings, furniture, boundaries, planning and analysis overlays), each with a fill, a texture per level of detail, a line or point symbol, aliases and documented coefficients.
• A style that stays GIS-exact. Marks are placed on the ground, not on the feature, so patterns continue across polygons and tile seamlessly; the hand-drawn outline never moves more than half a line width off the true edge.
• 26 crosswalks from OSM tags, ALKIS/NAK, XPlanung, PlanZV, basemap.de, LBM-DE, BKompV, BayKompV, FFH, the Berlin biotope map, DIN 276, CORINE, Urban Atlas, CLC+, EUNIS, HILUCS, LUCAS, ESA WorldCover, LCZ, and the Dutch, Swiss, Austrian and English national models: 3 926 classes, each with a fit grade.
• Seven themes: the mellow house style plus PlanZV, ALKIS, basemap.de, BfN landscape planning, OpenStreetMap Carto and a black-and-white drawing, with the published colour values.
• Standards built in: ISO 11091 and PlanZV status symbols for trees, DIN 18920 root protection zones, Berlin BFF, DIN 1986-100 runoff, the EU Nature Restoration Regulation's urban green space, WCAG-checked legibility including colour-vision deficiencies.
• Everywhere: SVG and Matplotlib; QGIS (QML with the hand-drawn outline and scale-dependent detail); OGC SLD; MapLibre sprites and layers with trees and streets in metres; CSS and DTCG design tokens; a command line; a skill for AI coding agents.

Install#

pip install "urban-landscape-graphics[all] @ git+https://github.com/UrbanSens/Urban-Landscape-Graphics"

Python 3.10+. Core dependencies are NumPy and Shapely; [all] adds GeoPandas and Matplotlib. PNG output uses rsvg-convert, CairoSVG or Inkscape if one is installed. Check the installation:

ulg check

To try the examples or to work on the library, use a clone:

git clone https://github.com/UrbanSens/Urban-Landscape-Graphics.git
cd Urban-Landscape-Graphics
pip install -e ".[dev]"
python examples/quickstart.py

Documentation#

Start at Contents:

1. Origins: from the Englischer Garten and the 1808 Bavarian survey to GIS
2. The style guide: principles, palette, textures, symbols, drawing order, legibility
3. The catalog: all elements and their coefficients
4. Python: drawing, classifying, measuring, the command line
5. GIS and web: QGIS, GeoServer, MapLibre, tokens
6. Standards: what the style conforms to, with the full standards report
7. For AI agents: ulg agent install
8. Extending: how the style guide grows

Repository#

src/ulg/          the package; src/ulg/data holds the catalog, palette, themes and crosswalks as JSON
docs/             documentation (German, English in docs/en), generated reference pages, research
examples/         runnable examples, sample data, a MapLibre page
tools/            builders for the documentation images, logo, reference pages and HTML; data formatter
tests/            pytest suite
.github/          tests and the documentation site (GitHub Pages) run on every push

Working on the library: the rules and commands are in Working on ulg (for people and coding agents alike) and in the chapter Extending.

Licence and credit#

ulg is free software under the MIT licence: use it, change it, ship it in commercial products, and keep the licence notice with the code. The maps and sheets you draw with it are yours.

Please reference us. If ulg or the UrbanSens Ecological Vector Style helped with a map, a plan, a report, a tender or a paper, say so in the caption or in the list of sources:

Map style: UrbanSens Ecological Vector Style (ulg), urbansens.de

ulg.credit_line() returns it as a string (with the version number; ulg.credit_line("de") gives the German one). The style sheets and the catalog sheets (the inventory of all elements) that ulg draws carry a small UrbanSens mark in the corner. Leave it on when you share them (credit=False turns it off); your own maps are never stamped. BibTeX, APA, the logo rules and third-party notices: Licence and credit.

Status#

Version 0.1.0 (2026-09-30), UrbanSens. See Changelog. Standards were researched on 2026-09-30; the standards report lists what was verified, what is paywalled and what to re-check when standards change.

Landscapes were drawn by hand long before they were mapped by computer. The mellow palette, the small tufts and crowns and the calm outlines of the UrbanSens style are not an invention; they are a selection from a tradition that began in the garden plans and survey offices of the early nineteenth century, several of them in Munich, where UrbanSens works.

1.1 A park painted in green: Munich, 1789–1806#

In August 1789 Elector Karl Theodor decreed a public park along the Isar in Munich, at the initiative of Benjamin Thompson, later Count Rumford. Friedrich Ludwig von Sckell shaped it as a landscape garden; it opened in 1792 and, at 3.75 km², is one of the largest city parks in the world: the Englischer Garten. Sckell directed Munich's court gardens from 1804 until his death in 1823.

Look at the colours of this sheet: pale greens for the meadows, a deeper green for woods, clear blue for water, brick red for roofs, all on warm paper. Two hundred and twenty years later the UrbanSens palette uses the same relations: light, low-chroma fills, darker marks of the same hue, saturated colour only where something needs attention.

1.2 Stone, ink and the survey: the Bavarian Uraufnahme, 1808–1864#

In the 1790s Alois Senefelder found that a smooth slab of Solnhofen limestone, drawn on with greasy ink and wetted, would print: lithography. From 1809 he served as inspector of the royal lithographic institute in Munich, and the Bavarian survey took up the new technique early.

In 1808 Bavaria began the Uraufnahme, the first complete survey of every parcel in the kingdom, for the land tax. Surveyors worked at 1:5 000, at 1:2 500 for villages and in parts of Franconia even at 1:1 250. More than 23 000 sheets were drawn, engraved on limestone plates and printed; the stones are still kept by the Bavarian surveying office (LDBV).

The surveyors did not choose their marks freely. The 1808 instruction for the tax survey prescribed a sign for every kind of ground, and it reads like the first draft of a texture catalog:

Deciduous and coniferous woods, bushes, meadows, mossy meadows, pastures and waste ground, moss, gardens, vineyards and hop gardens each have their own small mark; buildings, boundaries, paths, rivers and bridges their own line. Replace Wiesen with meadow, Waldungen · Laubholz with woodland_deciduous and Gärten with garden, and this page becomes a legend of the catalog in chapter 3.

1.3 Crowns, tufts and washes: the language of garden plans#

Landscape architects drew with the same means. In Peter Joseph Lenné's plan for the Berlin Tiergarten the woods are built out of thousands of small crowns, the open lawns keep the paper tone and the paths are left white.

Rural maps followed conventions every reader knew. The archive description of this manuscript map from Württemberg lists them: houses red, fields brown, vineyards with vine symbols, meadows green, woods as tree symbols, paths brown, the rivers blue ("drawn by eye and freehand").

der nach dem Aug und freier Faust ist gezeichnet worden

end of the title of the Enzberg plan, Landesarchiv Baden-Württemberg, Hauptstaatsarchiv Stuttgart N 3 Nr. 47 (in English: which was drawn by eye and freehand)

Three habits of these drawings became rules of the style: marks are made by hand but placed with care (the wobble never hides the true edge); texture says what a surface is (crowns for trees, tufts for meadow, waves for water); and colour stays quiet so that the plan can carry a message.

1.4 From colour words to codes: the twentieth century#

Planning law turned conventions into rules. The German Planzeichenverordnung (PlanZV) first set federal plan symbols for land-use and zoning plans on 19 January 1965; the current version dates from 18 December 1990 and was last amended on 12 August 2025. It names its colours only in words (Grün mittel, Blau mittel) and gives one of the most useful rules for vegetation symbols: an open centre marks a tree to be planted, a filled centre a tree to be preserved (No. 13.2).

Die Planzeichen sollen in Farbton, Strichstärke und Dichte den Planunterlagen so angepaßt werden, daß deren Inhalt erkennbar bleibt.

Planzeichenverordnung 1990, § 2 Abs. 3 (in English: the symbols are to be adapted in hue, line weight and density to the base map so that its content stays recognisable)

In 1969 Ian McHarg's Design with Nature laid transparent maps of soils, water, slopes and vegetation on top of one another to find where building would do least harm: the layered map that geographic information systems made routine. The international standard for landscape drawings, ISO 11091 (1994), fixed how plans tell existing from proposed: thin lines for what is there, thick lines for what is planned. The cadastre went digital with the ALKIS model of the German surveying authorities, its object types and its signature catalogue.

1.5 Open data and ecological targets: the twenty-first century#

Since 2004 OpenStreetMap has described the surface of the world in open tags (landuse=meadow, surface=gravel, natural=tree), and its Carto style made them a common visual language. In 2017 the Federal Agency for Nature Conservation (BfN) published a catalogue of plan symbols for landscape plans: light tints without outlines for areas of low to moderate value, saturated colours with a black outline for areas of high value, and brown vertical dashes for fallow. This style adopts that convention.

In 2024 the EU Nature Restoration Regulation (2024/1991) made urban green space and tree canopy a legal target: no net loss by 2030 compared with 2024, and an increasing trend from 2031, measured with Copernicus data. What a map shows as green is now also what a city reports.

By 31 December 2030, Member States shall ensure that there is no net loss in the total national area of urban green space and of urban tree canopy cover in urban ecosystem areas […] compared to 2024.

Regulation (EU) 2024/1991 (Nature Restoration Regulation), Article 8(1)

1.6 2026: one catalog#

UrbanSens set out the visual language it wanted for its maps on one sheet: habitat types and surface materials in a clean, mellow, lightly hand-drawn vector style that works at every scale.

A clean, consistent and scalable visual language to represent nature, surfaces and biodiversity in a professional, architectural style, using simple vector patterns and symbols.

UrbanSens, reference sheet of the Ecological Vector Style

The brief: the UrbanSens reference sheet for the Ecological Vector Style.	The result: the same sheet, generated by ulg sheet from the catalog.

ulg turns that sheet into a library. It keeps the look (quiet colours, textures that say what a surface is, trees drawn to scale) and ties every element to the conventions this chapter traced: the codes of ALKIS, XPlanung, the biotope lists and OpenStreetMap, the status symbols of PlanZV and ISO 11091, the coefficients planners report, and the official colours of each convention when a map has to follow them.

Image credits#

The historical images are linked from Wikimedia Commons, not copied into the repository; they need an internet connection to display.

The sheet above is not a drawing of the style but a product of it: ulg sheet renders it from the same data that styles your maps, so the guide and the maps cannot drift apart. The German version is img/style-sheet-de.png.

2.1 Five principles#

The UrbanSens reference sheet names five design principles. The library turns each of them into something that can be checked:

Vector-based (polygonizable, GIS compatible) · Subtle, natural color palette · Consistent iconography and line weights · Minimal, non-photorealistic, architectural style · Scalable detail (works at all zoom levels)

UrbanSens, reference sheet of the Ecological Vector Style, "Design principles"

2.2 Colour#

The palette has 21 families of primitive colours, addressed as family.step. Elements, themes and exporters refer to tokens only; changing a token changes every map, sheet and export at once.

Rules

• Areas use the light steps (100–400); texture marks use darker steps of the same family (600–900), so a texture always reads as part of its surface.
• Outlines are the fill darkened by a fixed amount (settings.json → outline_darken), unless an element sets its own.
• Saturated colour is reserved for meaning: the signal family marks what is planned, removed, protected or highlighted. Never use it for land cover.
• Neighbouring land covers must differ by at least ΔE₀₀ 10 in colour, or else in texture or outline (checked by ulg check, see 2.8).

For analysis layers there are ready ramps and class palettes in the same tonal range:

ulg.ramp("heat", 5)                  # ['#F7F1DC', '#F6D5A5', '#EFAC77', '#DB805F', '#B5574F']
ulg.category_of("utci", 34.2)        # {'id': 'strong_heat', 'min': 32, 'max': 38, 'color': '#F0B273', ...}

2.3 Textures#

Seventeen texture motifs draw every surface. Each element picks one or two motifs and their inks from the palette:

How textures behave

• Anchored to the ground. Mark positions are derived from ground coordinates, not from the feature. Two neighbouring polygons of the same element continue each other's pattern, and a map panned or tiled shows the same marks in the same places.
• Seamless tiles. For QGIS, SLD and the web the same motifs are drawn into periodic tiles that repeat without seams.
• Clipped to their area. Crowns and marks never spill over the feature edge, so drawing order never changes the look of clean data.
• Density by level of detail (2.6), not by feature size, so a texture looks the same on a small and a large polygon.

2.4 Lines#

Line elements use the ISO 128 series from settings.json → line_weights: hair 0.13, fine 0.18, regular 0.25, medium 0.35, bold 0.5, heavy 0.7, extra 1.0 mm. Texture marks are drawn finer than the finest outline on purpose: they must never compete with a boundary.

Lines and roads or paths that arrive as centre lines (OpenStreetMap highways) are drawn above all land cover. Area elements such as roads and footways become strips of their real width (see 2.7).

2.5 Symbols#

Trees are drawn to scale. A crown is a lobed outline of the tree's real diameter (attribute crown_diameter, or the element default), with a branch star from 1:1 500 upwards. When a stem diameter or girth (stammumfang in cm) is known, the stem is drawn to scale too.

Status follows the standards. One grammar serves all planning drawings:

The root protection zone (ulg.root_protection_zone()) is the crown drip line plus 1.50 m (columnar trees plus 5.00 m) after DIN 18920; the minimum distance for trenches is four times the stem girth, at least 2.50 m.

Pictograms mark furniture and ecological structures (bench, bin, lamp, bicycle stand, sign, play equipment, planter, bollard, deadwood, stone pile, nesting aid …). They are drawn at a fixed paper size, so they stay legible at every scale, and enlarged automatically in legends and sheets.

2.6 Levels of detail#

ulg.lod_for_scale(500) → 3, ulg.lod_for_zoom(18) → 2. Give the scale; do not switch textures off by hand.

2.7 Drawing order#

Real data is often stacked: OpenStreetMap maps a park as one polygon and the lawn, the pond and the paths inside it as further polygons on top. The style draws in bands so that stacked data looks right and clean data is unaffected:

Inside the ground band smaller areas are drawn on top of larger ones, the rule OpenStreetMap Carto uses for land cover. A playground inside a park, a lawn covering the park, a meadow inside the lawn and a clearing inside a wood all stay visible, and a complex such as a park never hides the surfaces mapped inside it. Water comes above the ground band because ponds are routinely mapped on top of parks and woods. ulg.flatten() applies the same order to the geometry itself, which turns stacked data into a clean partition for area statistics.

2.8 Legibility#

ulg check (and the test suite) enforces three rules:

1. Distinguishable. Two land covers that are closer than ΔE₀₀ 10 must differ in texture or outline. Pairs that differ in nothing are errors.
2. Colour-vision safe. The same test is repeated after simulating protanopia, deuteranopia and tritanopia (Machado et al. 2009). Meaning never depends on hue alone (WCAG 2 success criterion 1.4.1).
3. Marks with contrast. Texture marks are measured against their fill; the report lists the weakest, and symbols and boundaries follow WCAG 1.4.11 for non-text contrast.

2.9 Typography and layout#

Sheets, legends and titles use a humanist sans-serif (Avenir Next, falling back to Nunito Sans, Source Sans 3, Helvetica Neue, Arial), ink.900 for titles and ink.500 for secondary text, small capitals with wide tracking for section heads, and thin ink.200 rules. Maps are laid out in paper millimetres at the chosen scale.

2.10 Themes: the same map in other conventions#

The house style is mellow. Six further themes redraw the same data in an official or familiar convention, with the colour values of the published source: planzv (land-use and zoning plans), alkis (cadastral map), basemap (basemap.de), bfn (landscape planning), osm (OpenStreetMap Carto) and mono (black-and-white drawing after ISO 11091). Official themes use flat colours and exact lines. Sources and evidence: Standards and reference/themes.md.

2.11 Do and don't#

2.12 The mark#

The logo spells ulg with three things of a landscape plan, each drawn by the library from a catalog element: a pond in the shape of a u (water), a tree-lined path as the l (waterbound and tree), and a tree crown with a stream as the tail of the g (tree and watercourse). The hand-drawn outline and the texture marks are the renderer's, so the mark is a specimen of the style: exact geometry underneath, an imperfect drawing on top.

The name is set in Rethink Sans (SIL Open Font License) and converted to outlines, so the files need no font. Keep a free margin of half the height of the mark around it, show it at no less than 24 px tall (use ulg-mark-small.svg below 40 px), and do not recolour it: the colours are palette tokens (water.300, sand.300, leaf.300–leaf.600). python tools/build_logo.py redraws every file from the catalog, so a change of the palette changes the logo with it.

The UrbanSens mark. The style sheet, the catalog sheets and the figures of this documentation carry the small UrbanSens logo in a corner, with the website and the version; credit=False leaves it out. Details and the credit request: Licence and credit.

An element is one kind of thing you can put on a map: a wildflower meadow, gravel turf, a street tree, a retaining wall, a planned tree, a heat hotspot. Every map, sheet, legend and export of the library is drawn from these elements, and every external classification is translated into them.

3.1 What is in it#

The complete list with ids, English and German names and aliases is reference/element-list.md; every element is drawn on the catalog pages below.

3.2 The pages#

All pages together: img/catalog-sheet.svg (vector, true to size). Regenerate with ulg sheet --catalog -o catalog.svg or python tools/build_docs.py sheets.

3.3 Anatomy of an element#

Elements live in src/ulg/data/elements/*.json, one file per theme group, keyed by id:

"meadow": {
  "group": "vegetation.grass",
  "geometry": ["polygon"],
  "z": 20,
  "label":       {"en": "Meadow", "de": "Wiese"},
  "description": {"en": "Taller, more diverse grass, mown once or twice a year. Medium biodiversity.",
                  "de": "Höherer, vielfältigerer Bewuchs, ein- bis zweischürig. Mittlere Biodiversität."},
  "fill": "grass.400",
  "wash": true,
  "textures": [{"motif": "grass_tufts", "ink": "grass.700", "ink2": "grass.600"}],
  "attributes": {"sealing": "unsealed", "vegetated": true, "biodiversity": 3, "bdla_class": 1,
                 "bff": 1.0, "bff_1990": 1.0, "runoff_cs": 0.2, "runoff_cm": 0.1,
                 "albedo": 0.18, "emissivity": 0.97, "nrr_urban_green": true, "layer": "ground"},
  "aliases": ["Mähwiese", "Extensivwiese", "Extensivgrünland", "hay meadow", "grassland"]
}

In Python:

el = ulg.element("gravel_turf")
el.name("de")          # 'Schotterrasen'
el.fill                # hex colour, resolved from the palette token
el.attributes          # {'sealing': 'partly', 'bdla_class': 3, 'bff': 0.4, 'bff_1990': 0.5, 'runoff_cs': 0.3, 'runoff_cm': 0.2, ...}
ulg.codes_for("wildflower_meadow")   # the classes of other schemes that map onto it

3.4 Attributes: coefficients that travel with the style#

The same id that picks a colour also carries the numbers planners need. Values are copied from the named sources and never interpolated: a surface without a published value has none, and ulg.indicators() reports how much of the site had a value (coverage) instead of guessing.

Full table per element: reference/attributes.md.

Layers. layer: ground elements tile the site (land cover). layer: roof elements (green roofs, solar panels) lie on buildings and replace the building surface in runoff and albedo; they add their BFF credit on top. layer: overlay elements (boundaries, planning and analysis overlays, tree canopy) are drawn over everything and never counted as area.

Complexes. Elements with is_complex (residential area, park, cemetery, allotments, airport …) stand for a whole site with its internal surfaces. Map either the complex or its parts; if you map both, the parts are drawn on top and ulg.flatten() gives each square metre to the part.

3.5 Finding the right element#

ulg.find("Schotterrasen")      # [gravel_turf, lawn, gravel, wood_deck]
ulg.find("Rasengitter")        # [grass_pavers, grass_joint_paving]
ulg.resolve("osm", highway="footway", surface="compacted")    # 'waterbound'

ulg find Blumenwiese

ulg show wildflower_meadow --json

ulg list --group surface

Search looks at ids, English and German names and all aliases. If nothing fits, the feature should become unknown (drawn as a neutral hatch) until an element is added, see Extending.

4.1 Install#

pip install -e ".[all]"

Python 3.10 or newer. The core needs only NumPy and Shapely; geopandas (reading GIS files, indicators on data frames) and matplotlib (plots, the MapLibre sprite) come with the all extra. PNG output uses the first SVG rasteriser it finds: rsvg-convert, CairoSVG or Inkscape.

Check the installation:

ulg --version

ulg check

ulg check prints the legibility report of the catalog and ends with OK.

4.2 The style as data#

import ulg

lawn = ulg.element("lawn")
lawn.name("de"), lawn.fill              # ('Rasen', '#CDD2A9')

[el.id for el in ulg.find("Schotterrasen")]   # ['gravel_turf', 'lawn', 'gravel', 'wood_deck']
ulg.color("water.300")                  # '#BED2DD', a palette token
ulg.color("lawn")                       # '#CDD2A9', an element's fill
ulg.fills("polygon")                    # {'lawn': '#CDD2A9', 'meadow': '#C5CB9D', ...}
ulg.ramp("heat", 5)                     # ['#F7F1DC', '#F6D5A5', '#EFAC77', '#DB805F', '#B5574F']
ulg.categories("klimatop")              # climatope classes with labels and colours
ulg.themes()                            # {'mellow': 'UrbanSens mellow (house style)', 'alkis': ..., ...}

ulg.fills() alone already styles a map in any tool:

gdf.plot(color=gdf.element.map(ulg.fills()))

4.3 Your data#

Everything that draws or measures accepts

• a GeoDataFrame with a column of element ids (by="element" by default),
• a GeoJSON FeatureCollection (dict) with the id in the properties,
• a list of (geometry, element_id) or (geometry, element_id, properties) tuples.

Use a projected CRS in metres (EPSG:25832 for Bavaria). Geographic GeoDataFrames are reprojected to UTM automatically; textures, widths and areas need metres.

Useful attributes are read when present: crown_diameter (also diameter_crown, kronendurchmesser …) sizes tree crowns, stammumfang (cm) or stem_diameter (m) draws stems to scale, and width, lanes or the OSM highway class set the width of roads and paths given as centre lines.

If your data uses another classification, translate it (4.5). If it uses your own codes, pass a mapping:

ulg.render_svg(gdf, by="nutzung", mapping={"Rasen": "lawn", "Weg": "waterbound", "Teich": "water"})

4.4 Drawing#

SVG, true to scale#

from ulg.datasets import demo_park_gdf

gdf = demo_park_gdf()                                  # Angerpark, the demo quarter, EPSG:25832
svg = ulg.render_svg(gdf, scale=1500, path="park.svg") # 1:1500, in paper millimetres
svg.lod                                                # 2, the level of detail chosen from the scale

Options that matter:

PNG and PDF: ulg.render.rasterize("park.svg", "park.png", dpi=200), or convert the SVG with Inkscape (inkscape park.svg --export-type=pdf). The SVG opens true to size in Inkscape, Illustrator and Affinity, and every feature group carries its element id as data-element.

Matplotlib#

ax = ulg.plot(gdf, scale=3000)            # a new figure sized so that 1 paper mm is 1 mm
ax.figure.savefig("park.png", dpi=150)

import matplotlib.pyplot as plt
fig, ax = plt.subplots(figsize=(8, 6))
ulg.plot(gdf, ax=ax)                      # into an existing axes; the axes decide the scale
other_layer.plot(ax=ax, zorder=10)        # then draw your own layers on top

Legends#

from ulg.legend import used_elements

ids = used_elements(zip(gdf.geometry, gdf.element))           # the elements on the map, in order
ulg.legend_svg(ids, lang="de", title="Legende", columns=2).save("legend.svg")

ax.legend(handles=ulg.legend_handles(["lawn", "meadow", "water"], lang="de"))   # flat Matplotlib legend

Style sheets#

ulg.style_sheet("style.svg")                       # the one-page overview (section 2)
ulg.style_sheet("style-de.svg", lang="de")
ulg.catalog_sheet("catalog.svg")                   # every element
ulg.catalog_sheet("trees.svg", groups=["trees"], title="Trees")
ulg.style_sheet("plain.svg", credit=False)         # without the small UrbanSens mark in the corner

The sheets carry that mark by default; ulg.legend_svg(..., credit=True) adds it to a legend, and your own maps never get one. ulg.credit_line() returns the line for a caption or a list of sources ('Style: UrbanSens Ecological Vector Style (ulg 0.1.0) · urbansens.de', German with lang="de"). More in Licence and credit.

4.5 Classifying external data#

A crosswalk translates the classes of another scheme (OSM tags, ALKIS object types, XPlanung, BKompV/BayKompV biotope codes, CORINE, Urban Atlas and 20 more) into element ids.

ulg.resolve("osm", landuse="grass")                       # 'lawn'
ulg.resolve("osm", highway="footway", surface="compacted") # 'waterbound'
ulg.resolve("alkis", objart="41008", funktion="4420")     # 'green_space'
ulg.resolve("clc", "141")                                 # 'green_space'
ulg.explain("clc", "141")
# {'code': '141', 'name': 'Green urban areas', 'element': 'green_space', 'fit': 'exact',
#  'color': '#FFA6FF', 'evidence': 'V', 'level': 3, 'maes': 'Urban', 'note': 'Pink in the official legend, not green.'}

gdf["element"] = ulg.classify(gdf, "osm")        # every column of every row takes part in matching
gdf["element"] = ulg.classify(gdf, "clc", column="code_18")   # or a single code column
ulg.official_colors("clc")["141"]                 # '#FFA6FF', the scheme's own legend colour
ulg.codes_for("wildflower_meadow")                # the reverse: which classes map onto an element

Rules worth knowing:

• The most specific entry wins (natural=wetland + wetland=reedbed beats natural=wetland).
• Column names are matched through aliases (Objektart, OBJART, objart all work).
• Hierarchical codes fall back to their group (EUNIS E2.64 → E2.6 → E2).
• Unmatched rows become unknown and are drawn as a neutral hatch, so gaps stay visible. Pass default=None to get None instead.
• Each entry has a fit grade (exact, narrower, broader, nearest or none), so you can see how faithful a translation is.

All schemes: ulg.schemes(), or reference/crosswalks.md.

4.6 OpenStreetMap: stacked areas and centre lines#

OSM data stacks areas (park → grass → pond) and maps streets and paths as lines. The renderer handles both: areas are layered like OSM Carto (smaller on top within the land-cover band), and roads, footways and squares that arrive as lines are drawn as strips of their real width.

import geopandas as gpd

osm = gpd.read_file("examples/data/osm_sample.geojson").to_crs(25832)
osm["element"] = ulg.classify(osm, "osm")
ulg.render_svg(osm, scale=1000, path="block.svg")

For figures, flatten first: ulg.flatten() cuts every area by those drawn above it and turns centre lines into areas, so each square metre is counted once.

flat = ulg.flatten(osm)          # GeoDataFrame in a metric CRS, no overlaps in the ground cover
ulg.indicators(flat)["sealed_share"]

Carriageways are drawn as road whatever their surface tag; paths, squares and pitches show their material. The full walk-through is examples/osm_workflow.py.

4.7 Site figures#

site = gdf[gdf.layer.isin(["landcover", "trees"])]
figures = ulg.indicators(site)

Coefficients are never guessed: a surface without a published value lowers the coverage figure instead. Green roofs and solar panels count on top of the buildings they cover.

Trees. ulg.root_protection_zone(trees) returns DIN 18920 root protection zones (crown drip line plus 1.50 m, columnar trees plus 5.00 m) and the minimum trench distance (min_trench_distance_m, four times the girth, at least 2.50 m):

zones = ulg.root_protection_zone(trees, columnar_field="saeulenform")
zones.to_file("root_zones.gpkg")

4.8 From the terminal#

The ulg command (also python -m ulg) does the same without writing code; add --json for machine-readable output and --lang de for German names.

4.9 Recipes#

A 1:500 site plan from an ALKIS extract

alkis = gpd.read_file("alkis.gpkg", layer="tatsaechliche_nutzung")
alkis["element"] = ulg.classify(alkis, "alkis")
ulg.render_svg(alkis, scale=500, path="lageplan.svg")

A Bauleitplan look for a draft

ulg.render_svg(plan, scale=1000, theme="planzv", path="entwurf.svg")

Analysis colours on top of the style

ax = ulg.plot(site, theme="mono", lod=1)                       # quiet base map
cells.plot(ax=ax, zorder=50, alpha=0.8,
           color=[ulg.category_of("utci", v)["color"] for v in cells.utci])

A web map with folium

import folium
m = folium.Map(location=[48.15, 11.58], zoom_start=17, tiles=None)
folium.GeoJson(gdf.to_crs(4326), style_function=ulg.style_function()).add_to(m)

More: examples/ · API: reference/api.md

ulg export all out/            # everything below; or: qgis | sld | web | tokens

Every export takes --theme (mellow, planzv, alkis, basemap, bfn, osm, mono) and --lang de for German labels. Your data needs one attribute with element ids (default element); classify it first if it comes in another scheme (4.5).

5.1 QGIS#

Files

What the styles do

• Textures are seamless SVG pattern tiles embedded in the file (base64:), so the QML needs no SVG search path and no plugin.
• Hand-drawn outline: a geometry generator applies wave_randomized() in paper millimetres, seeded by the feature id; the amplitude stays under half the line width, so the ink covers the true edge. Needs QGIS 3.24 or later; official themes use exact lines.
• Level of detail (--lod auto): a rule-based renderer switches textures at 1:750, 1:2 500 and 1:10 000, exactly like the Python renderer. A fixed --lod 2 gives a simpler categorized renderer.
• Trees are SVG markers sized in map units from crown_diameter (or the element default), so crowns are true to scale at every zoom.
• Roads and paths given as centre lines (OSM highways) are drawn in the lines style as strips of their real width: a geometry generator buffers the line by width, lanes or the highway class.
• Drawing order follows the catalog bands, then larger areas first ($area DESC), so stacked data looks as in Python.

Tested by rendering headlessly with PyQGIS 3.36 (tools/qgis_render.py); the XML follows what QGIS writes itself and loads in 3.28 and later. A ready project: python examples/qgis_project.py.

5.2 OGC SLD for GeoServer and INSPIRE#

ulg export sld out/ writes ulg_polygons.sld, ulg_lines.sld and ulg_points.sld, one Rule per element filtered on the element attribute, with

• a flat PolygonSymbolizer fill plus a GraphicFill of the element's pattern tile (patterns/<id>.svg),
• stroke widths converted from millimetres to pixels at 96 dpi, dashes and casings for lines,
• ExternalGraphic point symbols (symbols/<id>.svg) for pictograms and crowns, well-known marks for dots.

SLD cannot express the procedural outline or scale-dependent detail, so the style degrades gracefully: flat fill, pattern tile, plain outline. That is also the form INSPIRE view services expect. Upload the folder with its patterns/ and symbols/ subfolders into the GeoServer style directory.

5.3 MapLibre GL#

The demo quarter in MapLibre GL, zoom 17.	Detail at zoom 19: pattern tiles, pond, reed belt and boardwalk.

ulg export web out/ writes, among others:

Prepare the data with to_geojson(): it writes RFC 7946 GeoJSON in WGS 84 and adds area_m2, which the layers use to draw smaller areas above larger ones.

from ulg.export.web import to_geojson
to_geojson(gdf, "site.geojson", columns=["element", "crown_diameter"])

Use the layers

const layers = await (await fetch("ulg/maplibre-layers.json")).json();
new maplibregl.Map({
  container: "map",
  style: {
    version: 8,
    sprite: new URL("ulg/ulg-sprite", location.href).href,
    sources: { ulg: { type: "geojson", data: "site.geojson" } },
    layers: [{ id: "paper", type: "background", paint: { "background-color": "#F5F5F1" } }, ...layers]
  }
});

For vector tiles, pass source_layer= to maplibre_layers(). Metre-based sizes use the latitude of your data (latitude= in export_web). Crown sizes are read from crown_diameter, diameter_crown, kronendurchmesser and the other size attributes the Python renderer knows. MapLibre cross-fades fill patterns between zoom levels, so textures are sharpest at whole zoom levels.

The example. examples/web/ is a complete page. Build it and serve it:

python examples/web/build.py

python -m http.server 8765 --directory examples/web

Open http://localhost:8765 for the demo quarter, or http://localhost:8765/?data=osm for the OpenStreetMap-style block with stacked areas and streets as centre lines. The same page is live at urbansens.github.io/Urban-Landscape-Graphics/demo/ (the documentation workflow rebuilds it on every push). The page is in German by default; add ?lang=en for English (/?lang=en&data=osm).

5.4 Leaflet, folium, OpenLayers#

Leaflet-style APIs take a style callback with flat colours:

folium.GeoJson(gdf.to_crs(4326), style_function=ulg.style_function()).add_to(m)

For textures in SVG-based renderers, include patterns.svg (one <pattern id="ulg-<id>"> per element) and fill paths with url(#ulg-lawn). OpenLayers and deck.gl can use the sprite PNG and its JSON index as an atlas.

5.5 Design tokens and apps#

ulg export tokens out/

5.6 Print and illustration#

SVG output is laid out in millimetres at the map scale: open it in Inkscape, Illustrator or Affinity and it is true to size. Every feature group carries data-element="<id>", so layers can be selected and restyled by element. For PDF:

inkscape plan.svg --export-type=pdf

6.1 What "conform" means here#

Colour is almost never law. The only statutory plan symbology in Germany, the PlanZV, names colours in words, applies only to land-use and zoning plans and allows deviations as long as the plan stays legible. What is fixed are codes, symbols with a meaning, and numbers.

Eine Verletzung von Vorschriften der Absätze 1 bis 4 ist unbeachtlich, wenn die Darstellung, Festsetzung, Kennzeichnung, nachrichtliche Übernahme oder der Vermerk hinreichend deutlich erkennbar ist.

Planzeichenverordnung 1990, § 2 Abs. 5 (in English: a breach of the rules of paragraphs 1 to 4 is immaterial when the content is clearly recognisable)

The library therefore conforms in five ways:

The research behind this was done in seven streams on 2026-09-30, each value marked by how it was verified: V read in the primary source, V* read through an extraction or sampled from an official swatch, S from a secondary source, R recalled and not verified.

6.2 Themes#

Official themes switch the hand-drawn outline off and use flat fills, as the originals do. Elements without an entry of their own take the colour of the category they belong to in that convention; the evidence of every colour is written into the theme file (see reference/themes.md).

6.3 Crosswalks#

Every entry states how faithful the translation is:

Biotope schemes carry their valuation: BKompV entries hold the biotope value (0–24, or per age class), BayKompV entries the value points (0–15) and the legal protection. Official legend colours are kept per class (ulg.official_colors("clc")), so a map that must use CORINE's pink for green urban areas can. Details, sources and licence notes per scheme: reference/crosswalks.md.

6.4 Coefficients#

Values are copied, never interpolated. Where two instruments disagree (a water-bound path has a low BFF weight but a high runoff coefficient), both are kept, because they answer different questions.

6.5 Drawing conventions#

6.6 Deliberate departures#

The house style is free where no rule binds it, and says so:

• Protected biotopes are a green hatch; the Bavarian biotope viewer uses magenta. Use the bfn theme or recolour the overlay where the local convention matters.
• Boundaries follow landscape-plan practice rather than every official line: the site boundary is a neutral solid line (the Bauvorlagenverordnung uses a violet long dash), protected-area boundaries a green chain line (PlanZV 13.3 uses groups of strokes), flood zones a hatch (PlanZV 10.2 a wavy border).
• Lawn, meadow and wildflower meadow share one colour family, as in every scheme researched; the house style separates them by texture, not by hue.
• Paving materials are a house-level distinction: no European scheme and only a few German ones know them, so external codes resolve to generic elements (sealed, concrete_pavers) rather than to a guessed material.
• Climate classes (klimatop, utci, pet) use house colours in the customary hue order; no numeric colour standard exists yet (VDI 3787 Blatt 12 is in preparation).

6.7 Keeping current#

Standards change: PlanZV was amended in 2025, CLC 2024 is due, DIN 18920 appeared in a new edition in 2026. The report lists what to watch and the state on 2026-09-30 (report 5.4). When a source changes, update the element, theme or crosswalk file, note the edition in its version or evidence field, run the tests and regenerate the sheets (Extending).

Licences. Codes and published colour values are facts and are cited, not copied as artwork. Symbol files of the BfN (CC BY-ND / all rights reserved) and UKHab (licence-gated) are not bundled; the library draws its own symbols after the same conventions. When you publish a map in the basemap theme, credit "© basemap.de / BKG" (report 5.3).

An agent asked to "make a map of the site with the meadows and the new trees" will otherwise invent a green and a tree symbol. With ulg installed it can look everything up instead. The library ships its own instructions for agents and a command to install them into any project.

7.1 Install the guide into a project#

ulg agent install --dir path/to/project

This writes

• .claude/skills/urban-landscape-graphics/SKILL.md: an Agent Skill that Claude Code loads when a task involves maps, plans, habitats, land cover, legends or indicators (use --agents for the cross-agent .agents/skills/ location, or both flags);
• a short section between <!-- ulg:start --> and <!-- ulg:end --> in the project's AGENTS.md (created if missing, never duplicated), which agents read at the start of every session.

ulg agent

prints the full guide (the same text as src/ulg/data/agent/AGENTS.md).

7.2 The rules agents follow#

1. Look up, never invent. Colours, textures and symbols come from the catalog: ulg find "Blumenwiese" --json, ulg show wildflower_meadow --json, ulg.element(id).
2. Classify with crosswalks. ulg.classify(gdf, "osm"), ulg.resolve("alkis", objart=..., funktion=...). ulg schemes lists the 26 schemes. Unmatched features become unknown: report them, do not hide them.
3. Metric data. Render and measure in metres (EPSG:25832 in Bavaria).
4. Scale, not detail. Pass scale=; the level of detail follows.
5. Themes for official looks. theme="planzv", "alkis", "basemap", "bfn", "osm", "mono"; never recolour the house style by hand.
6. Coefficients have sources. Missing values stay missing; coverage says how much was known.
7. Stacked data. OSM and sketch data overlap; drawing handles it, measuring needs ulg.flatten().
8. Credit UrbanSens. ulg is MIT licensed and asks to be mentioned. When an agent delivers or describes a map, it suggests ulg.credit_line() for the caption or the sources. The sheets the library draws keep their small UrbanSens mark (credit=False only on request); agents never put logos on the user's own maps.

7.3 Machine-readable answers#

Every command answers in JSON with --json, and names in German with --lang de:

ulg find Schotterrasen --json -n 1

[{"id": "gravel_turf", "label": {"en": "Gravel turf", "de": "Schotterrasen"}, "group": "surface.permeable",
  "geometry": ["polygon"], "fill": "#CDD4C8", "outline": "#AAB6A2", "ink": "#9A9A98",
  "motifs": ["pebbles", "grass_ticks"]}]

ulg resolve osm leisure=pitch surface=artificial_turf --json

{"scheme": "osm", "query": {"leisure": "pitch", "surface": "artificial_turf"}, "element": "artificial_turf",
 "fill": "#BFCBB8", "outline": "#9DAD93", "ink": "#7C907F", "official_color": "#88E0BE",
 "name": "leisure=pitch + surface=artificial_turf", "note": null}

ulg show <id> --json adds the description, textures, symbol, attributes and aliases.

The whole catalog as one file for tools in other languages: ulg export tokens out/ → catalog.json.

7.4 Example requests and what the agent does#

7.5 Working on the library itself#

Agents that change the library follow the repository's own AGENTS.md: data first, palette tokens only, sources for every value, ulg check and the tests must pass, and the reference pages and images are regenerated after data changes (Extending).

8.1 Where things live#

src/ulg/
  data/
    palette.json            colour tokens (family.step)
    settings.json           line weights, LOD breaks, ramps, class palettes, attribute docs, centre-line widths
    elements/*.json         the catalog, one file per theme group, keyed by element id
    themes/*.json           official conventions (planzv, alkis, basemap, bfn, osm, mono)
    crosswalks/*.json       26 external classifications -> element ids
    agent/                  SKILL.md, AGENTS.md, AGENTS.snippet.md for coding agents
  catalog.py                loading, palette resolution, themes
  crosswalk.py              resolve / classify / explain
  render/                   renderer: geometry, texture motifs, scene, SVG and Matplotlib backends
  export/                   QGIS, SLD, web (MapLibre), design tokens
  analysis.py               indicators, flatten, root protection zones
  check.py                  legibility report
  legend.py, sheet.py       legends and style sheets
  brand.py                  the UrbanSens credit: website, logo, credit line, the small mark on the sheets
tools/                      build_docs.py, build_html.py, build_logo.py, build_reference.py, format_data.py, qgis_render.py
  html/                     style sheet, script and font of the HTML documentation
tests/                      pytest suite
docs/                       the documentation in German (default); docs/en is the English version;
                            docs/reference and docs/html are generated, docs/img holds the figures
examples/                   runnable examples and the MapLibre page
LICENSE, CITATION.cff       MIT licence and the machine-readable reference

Data first. Almost every change is a change to a JSON file. Python code changes only when the style needs a new kind of mark (a motif or a pictogram) or a new capability.

8.2 Add an element#

1. Check that it is missing. ulg find "<German and English names>". Many "new" things are aliases of an existing element. Then add the alias instead.
2. Pick the group and file. Vegetation in 10_…/20_…, trees in 30_trees.json, water, ground, surfaces, land use, built, points, lines, overlays in their files.
3. Write the entry with palette tokens only:

"wood_pasture": {
  "group": "vegetation.woody",
  "geometry": ["polygon"],
  "z": 20,
  "label":       {"en": "Wood pasture", "de": "Hutewald / Weide mit Bäumen"},
  "description": {"en": "Grazed grassland with scattered old trees. Very high biodiversity.",
                  "de": "Beweidetes Grünland mit locker stehenden alten Bäumen. Sehr hohe Biodiversität."},
  "fill": "fallow.200",
  "textures": [
    {"motif": "grass_tufts", "ink": "fallow.700", "ink2": "grass.700", "keep": 0.45},
    {"motif": "canopy", "ink": "leaf.800", "tones": ["leaf.400", "leaf.500", "leaf.300"],
     "crown_m": 12.0, "pack": 3.4, "keep": 0.7}
  ],
  "attributes": {"sealing": "unsealed", "bff": 1.0, "runoff_cm": 0.1, "nrr_urban_green": true, "layer": "ground"},
  "aliases": ["Hutewald", "Hutung", "Waldweide", "wood pasture", "wooded pasture"]
}

4. Choose z by band (style guide 2.7): 20 for anything that covers the ground (including complexes), 30–33 for water and what lies on it, 50–66 for hedges and built structures, 66–76 for trees and points, 84–98 for overlays.
5. Attributes only with a source. Use the keys documented in settings.json → attributes; leave a coefficient out rather than estimate it. A new attribute needs its own entry there (meaning, source, evidence).
6. Aliases in both languages, including the terms of the standards that name this thing (ALKIS, BKompV, OSM): search and agents rely on them.
7. Connect it: point the crosswalk entries that describe it to the new id (8.6).
8. Check and regenerate (8.8).

8.3 Add or change a colour#

Colours live only in palette.json. Stay in the tonal range of the family: light steps (100–400) for fills, darker steps (500–900) for marks. ulg check shows whether a change brings two land covers closer than ΔE₀₀ 10 without a texture difference, also for simulated colour-vision deficiencies. Changing a token changes every element, theme export and sheet that uses it. That is the point, but note it in the changelog.

8.4 Add a texture motif#

A motif is a function in src/ulg/render/motifs.py:

def my_motif(region, p, ctx: Ctx) -> list:
    """What it draws, in one line."""
    x, y, s = G.scatter(region, ctx, p["spacing"], salt=p.get("salt", 31), keep=p["keep"])
    ...
    return [Paths(...), Dots(...)]

• region is the polygon, p the parameters merged from DEFAULTS[motif] (per LOD) and the element's texture entry, ctx carries the scale (ctx.u metres per paper mm), the LOD and the hand-drawn factor.
• Place marks with the ground-anchored helpers (G.scatter, _span_lines, the R streams), never with an unseeded random generator: that keeps patterns continuous across neighbouring polygons, reproducible, and seamless when drawn into tiles (ctx.period).
• Sizes are in paper millimetres; convert with ctx.u.
• Register it in MOTIFS and give it DEFAULTS for LOD 1–3. tests/test_render_engine.py checks that tiles repeat without seams.

8.5 Add a pictogram or a theme#

Pictograms are small vector drawings in PICTOGRAMS (src/ulg/render/scene.py): a list of parts (kind, coordinates, fill role, stroke role, width), coordinates in units of the symbol radius, roles fill, ink, paper, accent taken from the element's symbol.

Themes are JSON files in src/ulg/data/themes/:

A new theme appears in ulg.themes(), the CLI --theme options and all exporters automatically.

8.6 Add or extend a crosswalk#

One file per scheme in src/ulg/data/crosswalks/; the format is in reference/crosswalk-format.md. Essentials:

• metadata: title, publisher, version, source, license_note, key, fields (column aliases), optional hierarchy, suffixes, fallback_pattern;
• one entry per class with code or match, name, element (or null), fit, and color only if the scheme's own legend colour was verified;
• the most specific match wins, then file order.

python -m pytest tests/test_crosswalks.py validates every file. Add spot checks for the lookups your project relies on.

8.7 Tools#

8.8 Checklist for every change#

python tools/format_data.py

ulg check

python -m pytest

python tools/build_reference.py

python tools/build_docs.py sheets

python tools/build_html.py

Then look at the regenerated sheets: the style is visual, and the sheets are its review copy. A change to the text of the documentation is made in both languages (8.11).

8.9 Versions and the living style guide#

The style is versioned with the package (pyproject.toml, ulg.__version__ and palette.json → version move together) and every release is described in CHANGELOG.md:

Proposals for the style work best as a picture: a crop of the sheet or a map with the problem, the element ids involved, and, for anything official, the source. Apps pick up a release through ulg export tokens / ulg export web; QGIS projects by reloading the exported QML files; agents through the installed skill, which reads the installed package.

8.10 Publishing#

Two GitHub workflows in .github/workflows/ run on every push to main:

Generated files are not committed: docs/html/, examples/output/ and the exported web style in examples/web/ulg/ are rebuilt by the workflows or by the commands in 8.7. What is committed are the images in docs/img/ (sheets, maps, banners, logos), because they are the review copy of the style. Regenerate them with python tools/build_docs.py and python tools/build_logo.py before committing a change that alters how the style looks. The GitHub social preview (1280 × 640 px, set by hand under Settings > General) is docs/img/social-preview.png (German) or social-preview-en.png, made by python tools/build_docs.py social.

8.11 Two languages#

The documentation exists in German and English, and German is the default:

The reference pages, the research files, the examples, the changelog and AGENTS.md are English only; both sites contain them, and the German menu marks them with EN. The German text uses the formal Sie, and it is translated for meaning and idiom rather than word by word. Keep file names, heading numbers, figures and the number of code blocks identical in both languages; tests/test_docs_i18n.py compares the two trees. Text in figures comes from tools/build_docs.py, which draws every language-dependent image twice. The language switch of the site needs nothing: the builder pairs the pages by file name.

Two house rules apply to all text, in both languages: no em dashes (write a comma, a colon, parentheses or a full stop) and no spaced en dashes in their place. tests/test_style_rules.py checks this.