🗺️ Tilecraft

Streamlined CLI for OSM Vector Tile Generation

Generate beautiful vector tiles and MapLibre GL JS styles from OpenStreetMap data with smart caching and optimized feature extraction.

✨ Features

• 🗺️ OSM Integration: Direct OpenStreetMap data processing with intelligent tag handling
• 🎨 Beautiful Styles: Palette-based MapLibre GL JS style generation
• ⚡ Smart Caching: Avoid redundant processing with intelligent cache management
• 🚀 High Performance: Optimized processing with parallel feature extraction
• 🛠️ Professional Tools: Built on industry-standard tools (osmium, tippecanoe)
• 📦 Production Ready: MBTiles and optional PMTiles (via pmtiles CLI) for static hosting
• 🗂️ 50+ Feature Types: Comprehensive OSM feature support across 9 categories

🚀 Quick Start

Prerequisites

Install system dependencies (macOS):

brew install osmium-tool tippecanoe gdal

For other platforms, see Installation Guide.

Installation

# Clone repository
git clone https://github.com/username/tilecraft.git
cd tilecraft

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install tilecraft
pip install -e .

Basic Usage

# Generate tiles for Colorado rivers and forests
tilecraft generate \
  --bbox "-109.2,36.8,-106.8,38.5" \
  --features "rivers,forest,water" \
  --palette "subalpine dusk" \
  --name "colorado_nature"

# Quick urban mapping
tilecraft generate \
  --bbox "-122.5,37.7,-122.3,37.8" \
  --features "roads,buildings,parks,restaurants" \
  --palette "urban midnight" \
  --name "san_francisco"

# Comprehensive regional mapping
tilecraft generate \
  --bbox "-105.5,39.5,-105.0,40.0" \
  --features "rivers,lakes,mountains,forest,roads,buildings" \
  --palette "boreal forest" \
  --name "colorado_comprehensive"

Typical workflow

1. Install system tools (osmium, tippecanoe, GDAL, and pmtiles if you use --format pmtiles or both) and create a Python venv.
2. pip install -e . or pip install -r requirements.txt from the repo root.
3. Run tilecraft generate with --bbox, --features, --palette, and optionally --name, --format, --preview, zoom limits, etc.
4. Use the outputs under output/ (by default): .mbtiles / .pmtiles in output/tiles/, MapLibre style JSON in output/styles/, GeoJSON + schema.json in output/data/. OSM downloads are cached under output/cache/.
5. Point MapLibre GL JS (or a tile server) at the tiles and the generated style. Optional --preview builds a local HTML preview when MBTiles is kept on disk (--format mbtiles or both).

Palette colors are loaded from config/palettes.json when the name matches; otherwise Tilecraft uses small built-in fallback palettes (see Style palettes).

📖 CLI Commands

Main Commands

Generate Vector Tiles

tilecraft generate [OPTIONS]

Required:
  --bbox TEXT        Bounding box as 'west,south,east,north'
  --features TEXT    Comma-separated feature types (see 'tilecraft features')
  --palette TEXT     Style palette mood (e.g., 'subalpine dusk')

Optional:
  --output PATH      Output directory (default: output)
  --name TEXT        Project name for file naming
  --min-zoom INT     Minimum zoom level (default: 0)
  --max-zoom INT     Maximum zoom level (default: 14)
  --format TEXT      mbtiles, pmtiles, or both (default: both)
  --no-cache         Disable caching
  --preview          Generate preview after tile creation
  --verbose, -v      Verbose output
  --quiet, -q        Quiet mode

Explore Available Features

tilecraft features [OPTIONS]

Options:
  --category TEXT    Filter by category (water, natural, transportation, etc.)
  --search TEXT      Search feature names and descriptions
  --count INT        Number of features to show (default: 50)

Preview Vector Tiles

tilecraft preview MBTILES_PATH [OPTIONS]

Arguments:
  MBTILES_PATH       Path to .mbtiles file to preview

Options:
  --output PATH      Output directory for preview files (default: output/preview)
  --name TEXT        Custom name for the preview
  --verbose, -v      Verbose output

Check System Dependencies

tilecraft check [OPTIONS]

Options:
  --verbose, -v      Show detailed dependency information
  --fix              Show installation commands for missing dependencies

Usage Examples

Discover Features

# See all 50+ available features
tilecraft features

# Find water-related features
tilecraft features --search "water"

# See transportation options
tilecraft features --category "transportation"

# Explore natural features
tilecraft features --category "natural"

Natural Features Mapping

tilecraft generate \
  --bbox "-120.5,35.0,-120.0,35.5" \
  --features "rivers,forest,water,wetlands,mountains,beaches" \
  --palette "pacific northwest" \
  --name "big_sur_nature"

Urban Planning Analysis

tilecraft generate \
  --bbox "-74.1,40.6,-73.9,40.8" \
  --features "roads,buildings,parks,schools,hospitals,restaurants" \
  --palette "metropolitan" \
  --max-zoom 16 \
  --name "manhattan_urban"

Infrastructure Mapping

tilecraft generate \
  --bbox "-118.5,34.0,-118.0,34.5" \
  --features "roads,railways,airports,power_lines,bridges" \
  --palette "industrial" \
  --name "la_infrastructure"

Recreational Planning

tilecraft generate \
  --bbox "-106.0,39.0,-105.5,39.5" \
  --features "parks,playgrounds,sports_fields,golf_courses,mountains,rivers" \
  --palette "recreational" \
  --name "denver_recreation"

Preview Existing Tiles

# Preview any .mbtiles file with interactive viewer
tilecraft preview output/cache/co_power_lines.mbtiles

# Custom preview location  
tilecraft preview output/cache/denver_recreation.mbtiles --output output/denver-preview

# Preview generates:
# - Interactive HTML viewer with MapLibre GL
# - Tileserver-gl-light configuration
# - Complete setup instructions

📁 Output Structure

output/
├── tiles/
│   ├── project_name.mbtiles     # Vector tiles (tippecanoe)
│   └── project_name.pmtiles     # Same tiles as PMTiles (--format pmtiles or both)
├── styles/ 
│   └── project_name-style.json  # MapLibre GL JS style (palette-driven)
├── data/
│   ├── rivers.geojson           # Extracted feature data
│   ├── buildings.geojson
│   ├── roads.geojson
│   └── schema.json              # Rule-based tile schema
├── cache/
│   └── *.osm.pbf               # Cached OSM data
├── preview/                     # Generated by 'tilecraft preview'
│   ├── preview.html            # Interactive map viewer
│   ├── config.json             # Tileserver-gl-light config
│   └── README.md               # Preview setup instructions
└── README.md                   # Output documentation

🛠️ Installation

System Dependencies

macOS:

brew install osmium-tool tippecanoe gdal pmtiles

(pmtiles is required for --format pmtiles or the default both.)

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install osmium-tool tippecanoe gdal-bin python3-gdal

Windows (via conda):

conda install -c conda-forge osmium-tool tippecanoe gdal

Python Package

# From PyPI (when published)
pip install tilecraft

# Development installation
git clone https://github.com/username/tilecraft.git
cd tilecraft
pip install -e .[dev]

⚙️ Configuration

Environment Variables

Copy .env.example to .env and configure:

# Processing Configuration
TILECRAFT_CACHE_ENABLED=true

Supported Features

🗺️ 52 Feature Types Available Across 8 Categories:

• Water Features (6): rivers, water, lakes, wetlands, waterways, coastline
• Natural Features (8): forest, woods, mountains, peaks, cliffs, beaches, glaciers, volcanoes
• Land Use (7): parks, farmland, residential, commercial, industrial, military, cemeteries
• Transportation (8): roads, highways, railways, airports, bridges, tunnels, paths, cycleways
• Built Environment (5): buildings, churches, schools, hospitals, universities
• Amenities (6): restaurants, shops, hotels, banks, fuel_stations, post_offices
• Recreation (5): playgrounds, sports_fields, golf_courses, stadiums, swimming_pools
• Infrastructure (5): power_lines, wind_turbines, solar_farms, dams, barriers
• Administrative (2): boundaries, protected_areas

✨ All Features Fully Supported with:

• Optimized OSM Overpass queries
• Smart tag extraction and filtering
• Automatic geometry validation
• Efficient caching and processing

To see all available features:

# List all features by category
tilecraft features

# Search for specific features
tilecraft features --search "water"

# Filter by category
tilecraft features --category "transportation"

Style palettes

Canonical definitions live in config/palettes.json at the repository root. Each entry is keyed by palette name and includes description, background, and per-layer hex colors under layers. The --palette string is matched case-insensitively to those keys.

Palettes shipped in config/palettes.json include: subalpine dusk, desert canyon, pacific fog, arctic tundra, tropical canopy, urban night, prairie gold, mediterranean, boreal forest, high desert.

If the name is missing from the file (or the file is absent / invalid), Tilecraft logs a warning and falls back to a small built-in set, including e.g. subalpine dusk, desert sunset, and urban midnight—so older examples using those names still work.

To add or tweak colors, edit config/palettes.json and re-run tilecraft generate with the matching --palette name.

Example — subalpine dusk (dark mountain evenings, high contrast): layer color reference (same values as in config/palettes.json).

🔧 How It Works

Tilecraft streamlines OSM processing through:

1. Smart Feature Extraction: Efficiently extracts specific feature types using optimized osmium filters
2. Rule-based schema generation: Creates well-structured tile schemas from feature types and zoom settings
3. Palette-driven style creation: Generates MapLibre styles with chosen palettes and rendering rules
4. Advanced Caching: Prevents redundant downloads and processing for faster iteration
5. Graceful Resource Management: Proper cleanup prevents hanging and ensures smooth operation

🚨 Troubleshooting

Quick System Check

# Check all dependencies and get installation help
tilecraft check --verbose --fix

Common Issues

❌ "tilecraft command not found"

Solution: Install tilecraft in development mode

# Make sure you're in the tilecraft directory and virtual environment is active
source .venv/bin/activate
pip install -e .

❌ "No such option: --bbox"

Solution: Use the generate subcommand

# ❌ Wrong - missing 'generate'
tilecraft --bbox "..." --features "..." --palette "..."

# ✅ Correct - include 'generate' subcommand
tilecraft generate --bbox "..." --features "..." --palette "..."

❌ "tippecanoe not found"

Solutions:

# macOS
brew install tippecanoe

# Ubuntu/Debian  
sudo apt-get install tippecanoe

# Check installation
tippecanoe --version

❌ "CLI hangs after tile generation"

Solution: This has been fixed! The CLI now properly cleans up resources and exits gracefully.

❌ "Invalid bounding box format"

Solution: Use correct format: west,south,east,north

# ✅ Correct format
tilecraft generate --bbox "-109.2,36.8,-106.8,38.5" --features "rivers" --palette "subalpine dusk"

# ❌ Common mistakes:
# Missing quotes, wrong order, extra spaces

❌ "Unknown feature type"

Solution: Check available features

# See all available features
tilecraft features

# Search for specific features
tilecraft features --search "water"

# Check spelling - feature names are case-sensitive

Performance Tips

• Large regions: Use --max-zoom 12 instead of 14
• Memory issues: Process smaller bounding boxes
• Slow processing: Close other applications, use SSD storage
• Cache: Use --no-cache if running low on disk space

🚀 Development

Setup Development Environment

Use a virtual environment so pytest and the tilecraft command live in .venv/bin (or .venv\Scripts on Windows).

git clone https://github.com/username/tilecraft.git
cd tilecraft

# Create and activate venv (use python3.10+; 3.11/3.12 recommended if GDAL wheels are finicky)
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

python -m pip install -U pip
pip install -r requirements-dev.txt

# Install pre-commit hooks (optional)
pre-commit install

# Run tests
pytest

# Format code
black src/ tests/
ruff check src/ tests/

If .venv exists but has no bin/ (or install failed halfway), remove it and run python3 -m venv .venv again.

Runtime-only install (no dev tools): pip install -r requirements.txt

GDAL / pip install fails: This project depends on the gdal Python package, which must match your system GDAL. On macOS, try upgrading GDAL first (brew upgrade gdal), then run pip install -r requirements-dev.txt again. Alternatively install GDAL Python bindings via your distro or conda-forge so gdal-config --version matches the gdal package version pip installs.

Run tests with the venv activated (pytest) or explicitly: python -m pytest.

pyproject.toml enables coverage by default; for a quicker loop you can run
PYTEST_ADDOPTS='' pytest (or pytest --no-cov if your pytest supports it).

Live Overpass downloads are skipped unless you set RUN_NETWORK_TESTS=1 (see tests/test_osm_downloader.py).

Continuous Integration (GitHub Actions)

On every push or pull request to main / master, .github/workflows/ci.yml runs pytest on Ubuntu with Python 3.11 (system GDAL packages are installed so the gdal Python wheel can build or link). View results under the repository’s Actions tab; a green check means the test suite passed on GitHub’s runners.

Project Structure

tilecraft/
├── src/tilecraft/
│   ├── cli.py              # Command-line interface
│   ├── core/               # OSM processing
│   ├── ai/                 # Schema & style generators  
│   ├── models/             # Data models
│   └── utils/              # Utilities
├── tests/                  # Test suite
├── docs/                   # Documentation
└── examples/               # Usage examples

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make changes and add tests
4. Run tests: pytest
5. Format code: black . and ruff check .
6. Commit changes: git commit -m "Description"
7. Push and create Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• OpenStreetMap contributors
• Tippecanoe by Mapbox
• Osmium by OSM developers
• MapLibre GL JS community

📞 Support

• 🔧 System Check: tilecraft check --fix for installation help
• 🗺️ Feature Discovery: tilecraft features to explore options
• 🐛 Issues: Check existing issues or create new one
• 💬 Discussions: Community support and questions

---

"The best way to find out if you can trust somebody is to trust them." – Ernest Hemingway