Layer Definitions

Overview

A layer connects:

Source data: Which vector tile layer to use
Geometry type: How to render (line, fill, symbol, etc.)
Filter: Which features to include
Style selector: Which styles to apply

Layer structure

"""Layer structure connecting source data, geometry, filter, and styling."""

from map_style.generator.data import GeometryType, Layer
from map_style.generator.tree import Q

layer = Layer(
    id="road.highway.motorway",  # Selector path for styling
    geometry_type=GeometryType.LINE,
    filter=Q(class__eq="motorway"),
    feature_type="road",
    element_types=["geometry"],
)

Geometry types

Type	Description	Paint Class
`LINE`	Roads, boundaries, rivers	`LinePaint`
`POLYGON`	Land use, water, buildings	`FillPaint`
`EXTRUDED_POLYGON`	3D buildings	`FillExtrusionPaint`
`SYMBOL`	Labels, POI icons	`SymbolPaint`
`CIRCLE`	Point markers	`CirclePaint`
`BACKGROUND`	Map background	`BackgroundPaint`

Filters

Filters select which features from the source layer to render.

Comparison operators

"""MapLibre GL filter comparison operators."""

from typing import Any

# Equality
filter_eq: list[Any] = ["==", "class", "motorway"]

# Inequality
filter_neq: list[Any] = ["!=", "class", "path"]

# Numeric comparison
filter_gte: list[Any] = [">=", "admin_level", 4]
filter_lt: list[Any] = ["<", "rank", 10]

Logical operators

"""MapLibre GL filter logical operators."""

from typing import Any

# All conditions must match
filter_all: list[Any] = ["all", ["==", "class", "motorway"], ["has", "ref"]]

# Any condition matches
filter_any: list[Any] = ["any", ["==", "class", "motorway"], ["==", "class", "trunk"]]

# Negation
filter_not: list[Any] = ["!", ["has", "name"]]

Membership

"""MapLibre GL filter membership operators."""

from typing import Any

# Value in list
filter_in: list[Any] = ["in", "class", "motorway", "trunk", "primary"]

# Value not in list
filter_not_in: list[Any] = ["!in", "class", "path", "track"]

Property checks

"""MapLibre GL filter property existence checks."""

from typing import Any

# Property exists
filter_has: list[Any] = ["has", "name"]

# Property missing
filter_not_has: list[Any] = ["!has", "ref"]

Feature types and element types

Metadata for API styling support:

"""Feature types and element types metadata on layers."""

from map_style.generator.data import GeometryType, Layer

layer = Layer(
    id="road.highway",
    geometry_type=GeometryType.LINE,
    feature_type="road.highway",  # Logical feature category
    element_types=["geometry", "labels"],  # What this layer renders
)

Layer ordering

Layers render in array order. Typical ordering:

Background
Land use (parks, water)
Buildings
Roads (casings first, then fills)
Boundaries
Labels (lowest priority first)
POI icons

Example: road layers

Roads typically need multiple layers for proper rendering:

"""Road layers: casing (outline) renders first, then fill on top."""

from map_style.generator.data import GeometryType, Layer
from map_style.generator.tree import Q

layers = [
    # Casing (outline) renders first
    Layer(
        id="road.highway.motorway_casing",
        geometry_type=GeometryType.LINE,
        filter=Q(class__eq="motorway"),
    ),
    # Fill renders on top of casing
    Layer(
        id="road.highway.motorway",
        geometry_type=GeometryType.LINE,
        filter=Q(class__eq="motorway"),
    ),
]

Example: POI layers

"""POI symbol layer with combined filters."""

from map_style.generator.data import GeometryType, Layer
from map_style.generator.tree import Q

layer = Layer(
    id="poi.restaurant",
    geometry_type=GeometryType.SYMBOL,
    filter=Q(class__eq="food_and_drink") & Q(subclass__eq="restaurant"),
    feature_type="poi.food_and_drink",
    element_types=["labels", "icon"],
)

Data sources

Define vector tile sources:

"""Vector tile source definitions."""

from map_style.generator import SourceLayerRef

sources: dict[str, SourceLayerRef] = {
    "transportation": SourceLayerRef(
        source="openmaptiles",
        layer="transportation",
    ),
    "poi": SourceLayerRef(
        source="openmaptiles",
        layer="poi",
    ),
}

The source name in Layer.source must match a key in the sources dict.