Metadata-Version: 2.4
Name: biocartoon
Version: 0.4.3
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Multimedia :: Graphics
License-File: LICENSE
Summary: Search and download the BioCartoon catalog of open-licensed scientific illustrations from a shell or an MCP client
Keywords: biology,illustration,icons,scientific figures,mcp
Author: Joseph Rich
License-Expression: BSD-2-Clause
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://biocartoon.com
Project-URL: Repository, https://github.com/josephrich98/biocartoon

<p align="center">
  <img src="https://raw.githubusercontent.com/josephrich98/biocartoon-app/main/app/assets/logo.svg" alt="BioCartoon logo" width="160">
</p>

# BioCartoon

BioCartoon is a free and open-source tool for creating biology figures with illustrations. It
compiles existing open biology-focused illustration resources, along with its own illustrations,
into a single database with a graphical interface for search and figure generation.

This package is the `biocartoon` command-line interface and MCP server, which search and download
the database from a shell, a script, or an assistant such as Claude.

## Usage

Web application: [app.biocartoon.com](https://app.biocartoon.com)

Install Desktop application: [www.biocartoon.com/download](https://www.biocartoon.com/download)

## Resources

15,335 icons and 6 templates across 8 resources.

| source | icons | license |
|---|---|---|
| [BioCartoon](https://www.biocartoon.com) | 1 | CC0 |
| [Bioicons](https://bioicons.com) | 2,793 | CC BY / CC0 / CC BY-SA / MIT / BSD |
| [Health Icons](https://healthicons.org) | 749 | CC0 |
| [NIAID NIH BioArt Source](https://bioart.niaid.nih.gov) | 936 | Public Domain |
| [OpenMoji](https://openmoji.org) | 4,495 | CC BY-SA 4.0 |
| [Reactome icon library](https://reactome.org/icon-lib) | 2,569 | CC BY 4.0 |
| [SciDraw](https://scidraw.io) | 772 | CC BY 4.0 / CC0 |
| [Servier Medical Art](https://smart.servier.com) | 3,020 | CC BY 4.0 |

## Command-Line Interface and MCP server

```bash
pip install biocartoon        # or: pipx install biocartoon / uv tool 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. The first command that
needs the catalog downloads it; `biocartoon sync` updates it. 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.

- `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
    - `--favorites`: only the icons you starred (in the editor, or an app sharing its stars)
    - `--downloads`: only the icons downloaded for offline use (the editor's Settings > Offline)

    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
    - `--templates-ext png|biocartoon`: the thumbnail (default), or a `.biocartoon` file the editor opens
    - `--output-dir DIR` (default `./biocartoon-catalog`), `--jobs N` (parallel downloads, default 8), `--limit N` (the first N of each, to try it out)
- `biocartoon upload FILE...`: submit image files/folders to the database (approval required to merge in); `--tags T,...` adds words to find them by
- `biocartoon mcp`: serve the same tools over MCP, mostly for agents (e.g., `claude mcp add biocartoon -- biocartoon mcp`)
- `biocartoon --version`: the program's version, and when the local catalog was published and downloaded
- `biocartoon --sources`: list icon sources for `biocartoon search --source S`
- `biocartoon --categories`: list icon categories for `biocartoon search --category C`
- `biocartoon --source-categories`: list the collections' own categories for `biocartoon search --source-category S:C`

Run `biocartoon --help` for everything.

## Examples

Find an icon, check its license, and download it:

```bash
$ 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):

```bash
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:

```bash
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 --categories --source SD                        # what SciDraw covers
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"
```

Query the catalog with SQL (read-only):

```bash
biocartoon search --sql                                    # the schema
biocartoon search "select license, count(*) as n from assets group by license order by n desc"
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": [...]}`:

```bash
# 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
```

Download the whole catalog (well over 1 GB), or parts of it:

```bash
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:

```bash
biocartoon sync
claude mcp add biocartoon -- biocartoon mcp
```

The database schema is documented in the
[repository](https://github.com/josephrich98/biocartoon#database-structure).

## License

Copyright (c) 2026 Joseph Rich. The program is open source under the
[BSD 2-Clause License](https://github.com/josephrich98/biocartoon/blob/main/LICENSE). Every
illustration keeps its own upstream license (public domain, CC0, CC BY, CC BY-SA, ...): credit it
as its `credit` field says. See
[NOTICE.md](https://github.com/josephrich98/biocartoon/blob/main/NOTICE.md).

## Other Links

Website: [www.biocartoon.com](https://www.biocartoon.com)

Database and CLI source code: [github.com/josephrich98/biocartoon](https://github.com/josephrich98/biocartoon)

Application and website source code: [github.com/josephrich98/biocartoon-app](https://github.com/josephrich98/biocartoon-app)

Icon SQLite database: [assets.biocartoon.com/catalog/assets.sqlite.gz](https://assets.biocartoon.com/catalog/assets.sqlite.gz)

Template SQLite database: [assets.biocartoon.com/catalog/templates.sqlite.gz](https://assets.biocartoon.com/catalog/templates.sqlite.gz)

