Realistic, procedurally generated coffee stains for QGIS print layouts.
Procedurally generate realistic coffee stains — cup rings, spills, drips — and drop them onto a QGIS print layout. Every stain is unique, seed-reproducible, and grounded in the physics of drying droplets on paper.
- Copy the
coffee_stain_pluginfolder into your QGIS plugins directory:- Windows:
…\QGIS3\profiles\default\python\plugins\ - macOS / Linux:
~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/
- Windows:
- In QGIS open Plugins → Manage and Install Plugins, enable Show experimental plugins, then activate Coffee Stain.
Requires QGIS ≥ 3.22. Uses only numpy (bundled with QGIS) and, when present,
scipy.ndimage (optional — a radial fallback is used if it is unavailable).
- Open a print layout (Project → New Print Layout).
- Click the Coffee Stain button on the toolbar.
- Choose a preset or adjust the parameters — the preview updates live.
- Click Add to layout. The stain is inserted at the centre of the first page as a
QgsLayoutItemPictureusing the Multiply blend mode, so it reads as a translucent stain over your map. - Drag and resize it like any other layout item. Each Add uses a fresh random seed unless Lock seed is checked.
Generated PNGs are written to <project>/coffee_stains/. The seed, parameters and
algorithm version are stored as item custom properties for reproducibility.
| Parameter | Meaning |
|---|---|
| Preset | Ready-made bundle of the parameters below. |
| Stain type | Cup ring · Spill · Drip. |
| Palette | Coffee · Espresso · Latte · Archive (ochre). |
| Size | Stain size on the layout, in millimetres. |
| Darkness | Overall opacity of the deposit. |
| Ring strength | Intensity of the edge ring (coffee-ring effect). |
| Edge roughness | Contour irregularity (kept low for cup rings). |
| Wicking | Absorption into paper: shapes the edge through porosity and, when strong, fades the deposit. |
| Splashes | Number of satellite droplets (Poisson-disk spread). |
| Rings | Number of concentric stick-slip rings (power-law spacing, denser near the edge). |
| Central spot | Marangoni-style central deposition (inverse coffee-ring). |
| Network (interior) | Dewetting network texture inside filled areas. |
| Uniformity | Paper type: 0 = crisp ring, 1 = uniform disc. |
| Seed / Lock seed | Random seed; lock it to reproduce the same stain. |
| Raster DPI | Target export DPI (the effective render size is capped for speed). |
| Multiply blend | Blend the stain over the map (recommended). |
Cup just lifted · Dried espresso · Coffee with milk · Archival map · Inverse ring (Marangoni) · Hydrophilic paper (disc) · Dragged cup · Cartographer's disaster.
The generator is not a fluid simulation; it reproduces the outcome of well-studied mechanisms. Models actually used:
- Deegan, R. D., Bakajin, O., Dupont, T. F., Huber, G., Nagel, S. R., Witten, T. A. (1997). Capillary flow as the cause of ring stains from dried liquid drops. Nature 389, 827–829. — the edge-ring density profile.
- Weon, B. M., Je, J. H. (2010). Capillary force repels coffee-ring effect. Phys. Rev. E 82, 015305(R). — multiple concentric rings with power-law spacing.
- Baek, S. et al. (2018). Inverse coffee-ring effect / central (Marangoni) deposition. — the central-spot term.
- Li, Y., Lan, D., Wang, Y. (2017). Dewetting-mediated pattern formation inside the coffee ring. — the interior network texture.
- Nilghaz, A., Zhang, Y., Shen, W. (2015). Coffee stains on paper. — the ring ↔ uniform-disc axis for different paper types.
- Dou, R., Derby, B. Formation of coffee stains on porous surfaces. — porosity coupling and the Deegan exponent λ = (π − 2θ) / (2π − 2θ).
Further reading that informed the design:
- Larson, R. G. (2012). Re-Shaping the Coffee Ring. Angew. Chem. Int. Ed. 51, 2546–2548.
- Kim & Weon (2018). Evaporation of strong coffee drops.
- Bansal, L., Seth, P., Murugappan, B., Basu, S. (2018). Suppression of coffee ring: (Particle) size matters. Appl. Phys. Lett. 112, 211605.
- Han, P., Yang, L. et al. (2025). Suppression of the coffee-ring effect induced by laser. ACS Omega 10, 35785–35792.
- Mampallil, D., Eral, H. B. (2018). A review on suppression and utilization of the coffee-ring effect. Adv. Colloid Interface Sci. 252, 38–54.
- Patari, S., Mahapatra, P. S. (2022). Imbibition of liquids through a paper substrate. Langmuir 38, 4736–4746.
- Gerlero, G. S. et al. (2022). Validity of capillary imbibition models in paper-based microfluidics. Transp. Porous Media 141, 359.
GPL-3.0-or-later — see LICENSE.