Getting Started

Prerequisites

Python 3.14+
uv for dependency management
Go 1.24+ (for building the native sprite library)

Install

git clone https://github.com/Woosmap/map_style.git
cd map_style
uv sync --all-groups

Building the native sprite library

The sprite generator is a Go shared library loaded via ctypes:

make lib

Generate a style

# Classic streets
python -m map_style generate --style=streets -o style/streets_classic.json

# Satellite hybrid
python -m map_style generate --style=satellite -o style/streets_satellite.json

# With sprite generation
python -m map_style generate --style=streets -o style/streets.json --generate-sprite

The generate command produces:

The style JSON file
A woosmap.iconLibrary/ directory with the icon manifest and source files

With --generate-sprite, it also produces sprite.png, sprite@2x.png, sprite.json, sprite@2x.json.

Compare styles

python -m map_style diff style/streets.json style/streets_classic.json

See Style Diff for all comparison options.

Use as a library

"""Using map_style as a library to generate styles."""

from map_style.streets_classic import Style

style = Style()
mapbox_style, used_icons = style.render()

# Export to dict (ready for json.dump)
output = mapbox_style.model_dump(exclude_none=True, by_alias=True)

render() returns a tuple: the Pydantic MapboxStyle model and a set[str] of icon names referenced by the style.

Run tests

# Lint, typecheck, and tests
make tests

# Auto-fix lint and format
make format

Project structure

map_style/
├── generator/              # Core engine
│   ├── mapbox_style.py     # Pydantic models for Mapbox GL spec
│   ├── render.py           # LayerRenderer → Mapbox GL layers
│   ├── styler.py           # StyleTree (hierarchical style resolution)
│   ├── filters.py          # Filter expression builders
│   ├── tree.py             # Q class (Django-style query builder)
│   ├── poi.py              # POI layer builder
│   ├── sprite.py           # ctypes bindings to Go sprite lib
│   ├── color.py            # Color parsing and manipulation
│   └── data.py             # Layer and geometry type definitions
├── streets_classic/        # Classic streets style
│   ├── __init__.py         # Style class with render()
│   ├── colors.py           # Color palette
│   ├── mapping.py          # Layer-to-source mappings
│   ├── source.py           # Tile source definitions
│   ├── style.py            # StyleTree configuration
│   ├── roads.py            # Road layer definitions
│   ├── labels.py           # Label definitions
│   └── poi.py              # POI definitions
├── streets_satellite/      # Satellite hybrid (same structure)
├── streets_next/           # Next-gen style (WIP)
├── streets/                # Shared icon assets
│   ├── icons/              # SVG source icons
│   └── raster/             # PNG raster icons
├── diff.py                 # Style comparison engine
└── __main__.py             # CLI entry point
sprite/                     # Go sprite generator
├── sprite/                 # Core Go package
│   ├── sprite.go           # Layout, render, output
│   ├── icon_style.go       # Casing types (None, Rect, Circle, Filled)
│   └── required_icon.go    # Manifest model
└── pysprite/               # C-shared entry points for ctypes