mirror of https://github.com/marceloprates/prettymaps.git synced 2026-09-26 09:11:55 +02:00

Files

T

Marcelo de Oliveira Rosa Prates 3ef70792e2 Replace tutorial notebook with marimo + static docs (#144 )

* Replace tutorial notebook with marimo + static docs

Jupyter notebooks (.ipynb) are hostile to code review: every cell output
is a base64-embedded blob that churns on every run, and a 27 MB
examples.ipynb is essentially unreviewable. Moving the canonical
tutorial to a git-friendly marimo notebook and a static Markdown
walkthrough keeps code review diffs small, makes the source diffable
in pull requests, and lets the rendered tutorial live alongside the
library on the GitHub Pages site.

- Replace notebooks/examples.ipynb with notebooks/tutorial.py
  (marimo notebook, 35 cells, 15.1 KB).
- Add docs/tutorial.md with the same walkthrough rendered as Markdown
  plus 10 inline PNGs at docs/img/tour-01..tour-10-*.png extracted
  from the original notebook's cell outputs.
- Add Tutorial entry to mkdocs.yml nav; link from docs/index.md and
  README.md. README's inline tutorial block is replaced with a pointer
  table to docs/tutorial.md (README: 1062 -> 112 lines).
- Add marimo>=0.23.0 to requirements.txt; update .gitignore to keep
  the new tutorial.py whitelisted and to ignore marimo caches
  (__marimo__/, *.marimo).
- Fix mkdocs.yml site_url placeholder
  (yourusername.github.io -> marceloprates.github.io) so the GitHub
  Pages site's canonical links and sitemap point at the real domain.
- The 23 unrelated demo notebooks that lived alongside the tutorial
  are kept untracked in notebooks/untracked/ (gitignored as before).

* Restore README tutorial pointer and update Colab link

Follow-up to the tutorial-marimo conversion. The previous rebase onto
the upstream CI commit (ba59f1f) accidentally dropped the new README.md
rewrite because 'git checkout --ours' during a rebase selects the
upstream side, not the commit being applied. This restores the
112-line README.md with the tutorial pointer and updates the Colab
link from notebooks/examples.ipynb to notebooks/tutorial.py.

* Remove obsolete generate-readme CI workflow

The generate-readme.yml workflow and the notebooks_to_readme.sh script
it depended on were designed to run notebooks/examples.ipynb and
regenerate README.md from its cell outputs. Since examples.ipynb is
gone (replaced by the marimo notebook and static docs/tutorial.md),
this pipeline has no purpose and was failing the PR check.

Also removes the 13 orphan temp_readme_*.png files that the CI had
committed to pictures/README/ in ba59f1f — their source notebook
no longer exists.

2026-07-30 12:24:36 -03:00

5.4 KiB

Raw Permalink Blame History

prettymaps

A minimal Python library to draw customized maps from OpenStreetMap created using the osmnx, matplotlib, shapely and vsketch packages.

This work is licensed under a GNU Affero General Public License v3.0 (you can make commercial use, distribute and modify this project, but must disclose the source code with the license and copyright notice)

Note about crediting and NFTs:

Please keep the printed message on the figures crediting my repository and OpenStreetMap (mandatory by their license).
I am personally against NFTs for their environmental impact, the fact that they're a giant money-laundering pyramid scheme and the structural incentives they create for theft in the open source and generative art communities.
I do not authorize in any way this project to be used for selling NFTs, although I cannot legally enforce it. Respect the creator.
The AeternaCivitas and geoartnft projects have used this work to sell NFTs and refused to credit it. See how they reacted after being exposed: AeternaCivitas, geoartnft.
I have closed my other generative art projects on Github and won't be sharing new ones as open source to protect me from the NFT community.

As seen on Hacker News:

prettymaps subreddit

Tutorial (marimo) · Google Colaboratory Demo

Installation

Install locally:

Install prettymaps with:

pip install prettymaps

Install on Google Colaboratory:

Install prettymaps with:

!pip install -e "git+https://github.com/marceloprates/prettymaps#egg=prettymaps"

Then restart the runtime (Runtime -> Restart Runtime) before importing prettymaps

Run front-end

After prettymaps is installed, you can run the front-end (streamlit) application from the prettymaps repository using:

streamlit run app.py

Tutorial

The full tutorial is at docs/tutorial.md — a markdown walkthrough with rendered images, the [Plot] dataclass fields, the layers/style parameters, presets, multiplot, hillshade, and keypoints.

Quick start:

import prettymaps

plot = prettymaps.plot('Stad van de Zon, Heerhugowaard, Netherlands')

Resource	Where to find it
Full tutorial (markdown + images)	`docs/tutorial.md`
Interactive marimo notebook (runnable)	`notebooks/tutorial.py`
Open in Google Colab	Open in Colab
Streamlit front-end	`streamlit run app.py`

Run the tutorial locally (marimo)

# Install marimo (already in requirements.txt)
pip install marimo

# Open the notebook in your browser
marimo edit notebooks/tutorial.py

Customizing parameters

The most important prettymaps.plot() parameters are:

layers — dict of OpenStreetMap layers to fetch.
style — dict of matplotlib style parameters per layer.
preset — load a JSON preset (e.g. 'default', 'minimal', 'macao', 'tijuca').
circle / radius / dilate — boundary shape.

plot is a dataclass with geodataframes (per-layer GeoDataFrames), fig, and ax.

plot = prettymaps.plot(
    'Praça Ferreira do Amaral, Macau',
    circle=True,
    radius=1100,
    layers={
        "water": {"tags": {"natural": ["water", "bay"]}},
        "building": {"tags": {"building": True}},
    },
    style={
        "water": {"fc": "#a1e3ff", "ec": "#2F3737"},
        "building": {"palette": ["#FFC857", "#E9724C", "#C5283D"]},
    },
)

See docs/tutorial.md for the full set of examples (Macau, Bom Fim, mosaic, Barcelona plotter, Tijuca, multiplot, hillshade, Garopaba keypoints).

5.4 KiB Raw Permalink Blame History