BioCartoon
BioCartoon is a free and open-source tool for creating biology figures with illustrations. We compile existing open biology-focused illustration resources and introduce our own illustrations in a single database with a graphical interface for search and figure generation.
This repository holds the icon database and the biocartoon command-line interface. The desktop app, web app, and website are in biocartoon-app.
Usage
Web application: app.biocartoon.com
Install Desktop application: www.biocartoon.com/download
Resources:
15,393 icons and 6 templates across 8 resources.
- "DNA colored" by DBCLS, Bioicons (https://togotv.dbcls.jp/en/pics.html), CC-BY-4.0 (https://creativecommons.org/licenses/by/4.0/)
- "Lymphocyte" by DBCLS, Bioicons (https://togotv.dbcls.jp/en/pics.html), CC-BY-4.0 (https://creativecommons.org/licenses/by/4.0/)
- "heart" by Servier, Bioicons (https://smart.servier.com/), CC-BY-3.0 (https://creativecommons.org/licenses/by/3.0/)
- "Mouse" by DBCLS, Bioicons (https://togotv.dbcls.jp/en/pics.html), CC-BY-4.0 (https://creativecommons.org/licenses/by/4.0/)
- "Human male" by DBCLS, Bioicons (https://togotv.dbcls.jp/en/pics.html), CC-BY-4.0 (https://creativecommons.org/licenses/by/4.0/)
- "DNA" by Resolve to Save Lives, Health Icons (https://healthicons.org/icon/filled/body/dna), CC0
- "Cell Nuclei" by Resolve to Save Lives, Health Icons (https://healthicons.org/icon/filled/body/cell-nuclei), CC0
- "Heart" by Resolve to Save Lives, Health Icons (https://healthicons.org/icon/filled/body/heart-organ), CC0
- "Rat" by Resolve to Save Lives, Health Icons (https://healthicons.org/icon/filled/zoonoses/animal-rat), CC0
Command-Line Interface and MCP server
The biocartoon command searches the published catalog from a shell:
pip install biocartoon
If your shell then says biocartoon: command not found, pip put the program in a folder that is
not on your PATH (pip names it in a warning near the end of its output): add that folder to PATH,
or install with pipx install biocartoon or uv tool install biocartoon, which handle PATH for you.
The package is the compiled program alone, with no Python dependencies. To build it from source
instead, run cd catalog && cargo build --release (giving target/release/biocartoon). This
build searches icons; its MCP server also lists the shared slide templates. The BioCartoon desktop
editor ships a fuller biocartoon that adds templates to search and the app command.
On Windows, the build also needs the Visual Studio Build Tools with the C++ workload
(winget install Microsoft.VisualStudio.2022.BuildTools --override "--passive --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"),
and must run from PowerShell or cmd: Git Bash's own link command shadows the MSVC linker.
-
biocartoon search "TERM": icons and templates matching TERM, best first. With no TERM it pages
through everything.
--icons / --templates: only that kind--tags T,...: icons and templates with one of these tags (a whole tag, any case)--source S: icons from a collection (a code or name from biocartoon --sources)--author A: icons by an author (part of the name, any case)--category C: icons in a category (a slug from biocartoon --categories)--subcategory S: icons in a subcategory (a slug from biocartoon --categories)--source-category [S:]C: icons in a collection's own category (from biocartoon --source-categories)--license L: icons under a license (CC-BY-4.0, CC0-1.0, ...)--file-type svg|png: icons published as SVG, or as a PNG only
Repeat a filter for several values: an icon matching any of them passes. An icon has to pass
every filter given.
--sql: run TERM as read-only SQL on the catalog.
-
biocartoon get ID: everything about one icon: license, credit, PNG/SVG URLs, colour variants
-
biocartoon fetch ID: download the SVG, or the PNG when the source publishes no SVG (--png or --svg for that type only, --out FILE|DIR, --max-side N for a smaller PNG)
-
biocartoon sync: download the newest published catalog
-
biocartoon bulk-download: the whole catalog into one folder with a README (contents, licenses, and the equivalent curl/sqlite3 commands, which it also prints as it goes); running it again fetches only what is missing
--files all|metadata|artwork|icons|templates: what to get (comma-separate several; artwork is icons and templates; default all)--metadata-ext sqlite|csv|tsv|xlsx|json: the icon and template catalogs' format (default sqlite)--artwork-ext png|svg: sets both of the next two (templates have no SVG, so they come as PNG)--icons-ext svg|png: default svg, with a PNG where the source publishes no SVG
Examples
Find an icon, check its license, and download it:
$ biocartoon search mitochondria --icons --limit 2
BA001199 bioart Mitochondria (Cells and Organelles; 2084x2084) matched: title,description
BA000413 bioart Damaged Mitochondria (Cells and Organelles; 1705x1174) matched: title,tags,description
$ biocartoon get BA001505 # credit, license, PNG/SVG URLs, colour variants
$ biocartoon fetch BA001505 --out ~/Desktop # the SVG
$ biocartoon fetch BA001505 --max-side 512 --out neuron.png # a smaller PNG
Contribute your own illustrations (held for review before they are published):
biocartoon upload figures/ --license CC-BY-4.0 --credit "Your Name" --dry-run # check first
biocartoon upload figures/ --license CC-BY-4.0 --credit "Your Name" --category cells --tags "neuron, axon"
Narrow a search by collection, category, author, license or file type:
biocartoon --sources # codes: BA, BI, SV, SD, HI, RE, OM, ...
biocartoon --categories # slugs: cells, cells.cell_types, ...
biocartoon search "pyramidal neuron" --source BA # NIH BioArt only
biocartoon search neuron --source BA --source SD # BioArt or SciDraw
biocartoon search mitochondria --category cells.organelles_and_cell_components
biocartoon search --category viruses --sort az --limit 40 --offset 40 # page 2 of all viruses
biocartoon search neuron --subcategory cell_types --file-type svg # SVG cell types
biocartoon search --license CC0-1.0 --license PD --category cells # free of attribution
biocartoon search --author kissinger --source BA --sort popular # one illustrator
biocartoon search --source-category "BA:Cellular Processes" --source-category "BA:Proteins"
biocartoon --categories --source SD # what SciDraw covers
Icons, templates or both (templates need the editor's build of biocartoon):
biocartoon search "cell" # icons, then templates
biocartoon search "cell" --icons
biocartoon search "cell" --templates
Query the catalog with SQL (read-only):
biocartoon search --sql # the schema
biocartoon search "select license, count(*) as n from assets group by license order by n desc"
# warning: running the search term as SQL; pass --no-sql to search for the words instead
biocartoon search --sql "select id, title from assets where svg_key is not null and title like '%ribosome%'"
biocartoon search "with dendrites" --no-sql # words, even though it starts with WITH
From a script: every command takes --json, and search results come back as
{"icons": [...], "templates": [...]}:
# download the SVG of the best match that has one (Servier and uploads are PNG only)
mkdir -p icons
for t in neuron astrocyte microglia; do
id=$(biocartoon search "$t" --icons --limit 10 --json | jq -r '[.icons[] | select(.svg_url)][0].id')
biocartoon fetch "$id" --svg --out icons/
done
biocartoon get BA001505 --json | jq -r .credit # the attribution line to print
Drive the running desktop editor (editor's build only):
biocartoon app state # page size and every item on the slide
biocartoon app insert_asset '{"asset":"BA001505","x":200,"y":120,"width":300}'
biocartoon app move_items '{"ids":[3],"dx":48}'
biocartoon app render '{"path":"slide.png"}'
Download the whole catalog (well over 1 GB), or parts of it:
biocartoon bulk-download # everything, into ./biocartoon-catalog
biocartoon bulk-download --files metadata --metadata-ext xlsx # the catalogs as spreadsheets
biocartoon bulk-download --files icons --icons-ext png --output-dir icons/
biocartoon bulk-download --files templates --templates-ext biocartoon # templates to open in the editor
Keep the local catalog current, and connect an assistant:
biocartoon sync
claude mcp add biocartoon -- biocartoon mcp
Repository Structure
catalog/ Rust crate biocartoon-catalog: the catalog library, the `biocartoon` CLI and MCP server
src/catalog.rs the SQLite catalog and the search over it (shared with the editor, so ranking matches)
src/query.rs synchronous catalog access for the CLI and MCP server
src/cli.rs the `biocartoon` commands
src/mcp.rs the MCP server (`biocartoon mcp`)
src/taxonomy.rs BioCartoon's own categories, mapped from each source's
src/templates.rs the published slide templates
src/upload.rs `biocartoon upload`: submits images to the submissions Worker
pyproject.toml packages the binary for PyPI (`pip install biocartoon`)
data/ Python pipeline that builds and publishes the catalog
scrape_sources.py download Bioicons, Health Icons, OpenMoji, Reactome, SciDraw, Servier
scrape_bioart.py download NIH NIAID BioArt Source
rasterize.py render SVGs to PNGs
build_assets_db.py build data/assets.sqlite (the master database) from the scrapes
upload_r2.py upload asset files to the R2 bucket (resumable)
uploads.py collect approved community contributions from the bucket
publish_catalog.py publish the trimmed, gzipped catalog to R2 for the app and CLI
sync.py incremental sync of new upstream assets (add-only)
publish_poll.py runs publishes queued with "Publish catalog now" on the review page
refresh_credits.py rewrite every asset's credit line
readme_stats.py regenerate the resources table above
config.py bucket names, URLs and other brand-dependent settings
requirements.txt Python packages for the pipeline (`pip install -r data/requirements.txt`)
schedule/ installs a weekly launchd job that runs sync.py (+ the publish poller)
worker/ Cloudflare Workers (TypeScript) for community contributions
src/submit.ts api.biocartoon.com: validate, rate-limit and hold submissions for review
src/review.ts review.biocartoon.com: approve or reject (behind Cloudflare Access)
src/publish.ts copies an approved submission into the public bucket
src/publish_requests.ts the "Publish catalog now" queue the Mac polls
src/stars.ts star counts on catalog assets
migrations/ D1 database schema
test/ unit tests (`npm test`)
.github/workflows/ CI tests and the PyPI release
Database Structure
The catalog is published as two gzipped SQLite files, built from the master database
(data/assets.sqlite) by data/publish_catalog.py. File keys (svg_key, png_key, json_key,
thumb_key) are paths in the public bucket, so a file lives at https://assets.biocartoon.com/<key>.
assets.sqlite.gz
One row per icon in the assets table. Only rows that are uploaded to the bucket and have a PNG are published.
| column | type | description |
|---|
id | TEXT, primary key | two letters for the source (BA bioart, BI bioicons, HI healthicons, OM openmoji, RE reactome, SD scidraw, SV servier, UG user upload, BC an upload in the official BioCartoon library), then a number unique across the catalog (e.g. BA001505); never reused |
source | TEXT | short source name: bioart, bioicons, healthicons, openmoji, reactome, scidraw, servier, user |
source_name | TEXT | display name of the source (e.g. Servier Medical Art) |
source_id | TEXT | the asset's id in the upstream collection; unique together with source |
title | TEXT | asset title |
variant | TEXT | BioArt colour scheme or Health Icons style, when the source has variants |
description | TEXT | upstream description, if any |
category | TEXT | the source's category path (e.g. Anatomy and The Human Body / Cardiovascular system / Arteries) |
tags | TEXT | JSON array of keywords (the source's, or the uploader's) |
license | TEXT | normalized license: PD, CC0-1.0, CC-BY-3.0, CC-BY-4.0, CC-BY-SA-3.0, CC-BY-SA-4.0, MIT, BSD |
license_raw | TEXT | the license as the source states it |
license_url | TEXT | link to the license text |
attribution_required | INTEGER |
Indexes cover source, license, category and the unique pair (source, source_id).
assets_fts is an FTS5 full-text index (Porter stemming) over title, description, tags,
category and variant, joined to assets by rowid:
SELECT a.id, a.title, a.license, a.png_key
FROM assets_fts JOIN assets a ON a.rowid = assets_fts.rowid
WHERE assets_fts MATCH 'mitochondria' ORDER BY rank LIMIT 10;
templates.sqlite.gz
One row per slide template in the templates table.
| column | type | description |
|---|
id | TEXT, primary key | <slug>-<hash> (e.g. eukaryotic-cell-5a1e09d5a6) |
title | TEXT | template title |
description | TEXT | short description |
category | TEXT | BioCartoon category (e.g. Cell biology) |
tags | TEXT | JSON array of keywords the author gave it ([] for none) |
author | TEXT | template author |
license | TEXT | normalized license, as in assets |
created_at | TEXT | ISO 8601 creation time |
json_key | TEXT | bucket key of the template document (templates/<id>/template.json) |
thumb_key | TEXT | bucket key of the thumbnail (templates/<id>/thumb.png) |
json_local, thumb_local | TEXT | build-time paths; empty in the published catalog |
A meta key–value table (k, v) is reserved for catalog metadata.
License
Copyright (c) 2026 Joseph Rich. This repository is open source under the BSD 2-Clause License. The editor in biocartoon-app is under the GNU AGPL v3.0. Third-party illustrations and icons keep their own licenses --- see NOTICE.md.
Contributing
Contributions are welcome --- see CONTRIBUTING.md. Contributors keep the copyright
in their work, and artists are credited under the name they choose.
Other Links
Website: www.biocartoon.com
Database and CLI source code: github.com/josephrich98/biocartoon
Application and website source code: github.com/josephrich98/biocartoon-app
Icon SQLite database: assets.biocartoon.com/catalog/assets.sqlite.gz
Template SQLite database: assets.biocartoon.com/catalog/templates.sqlite.gz
Support
If biocartoon is useful to you, you can buy me a coffee ☕
