Metadata-Version: 2.4
Name: opentrons-bioart-sim
Version: 1.0.0
Summary: Local simulator & visualizer for Opentrons OT-2 bio-art protocols — no robot required
Author: Rafael Pérez Aguirre
License-Expression: MIT
Project-URL: Homepage, https://github.com/Mozta/opentrons-bioart-sim
Project-URL: Bug Tracker, https://github.com/Mozta/opentrons-bioart-sim/issues
Project-URL: HTGAA Course, https://htgaa.org
Project-URL: Opentrons Art Designer, https://opentrons-art.rcdonovan.com
Keywords: opentrons,bio-art,htgaa,simulation,synthetic-biology,fluorescent-proteins
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opentrons
Requires-Dist: matplotlib
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# Opentrons Bio-Art Simulator

[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![HTGAA 2026](https://img.shields.io/badge/HTGAA-2026-purple.svg)](https://htgaa.org)

**Run and visualize Opentrons OT-2 bio-art protocols locally — no robot required.**

Simulate protocols generated by the [Opentrons Art Designer](https://opentrons-art.rcdonovan.com/) or custom HTGAA protocols. Preview your fluorescent protein artwork on a virtual Petri dish before using real hardware.

---

## Features

- **Full mock** of the Opentrons Python API (`ProtocolContext`, pipette, labware, modules)
- **Automatic color mapping** for 30+ fluorescent proteins (sfGFP → lime, mRFP1 → red, etc.)
- **Matplotlib visualization** of the Petri dish with droplets and smears
- **Save images** directly from the command line
- **Volume tracking** — detects waste and cross-contamination
- **Zero dependencies** beyond `opentrons` and `matplotlib`

---

## Installation

### From source (recommended)

```bash
git clone https://github.com/Mozta/opentrons-bioart-sim.git
cd opentrons-bioart-sim
python -m venv venv
source venv/bin/activate    # macOS/Linux
pip install -e .
```

### Dependencies only

```bash
pip install opentrons matplotlib
```

---

## Usage

### Option 1 — CLI (command line)

```bash
# Run an example protocol
opentrons-bioart-sim examples/octocat.py

# Change the Petri dish background
opentrons-bioart-sim examples/octocat.py --background agar

# Save to file without displaying
opentrons-bioart-sim examples/OTDesign_02-23-26_11-56-55.py --save output.png --no-show

# See all options
opentrons-bioart-sim --help
```

### Option 2 — One-liner in Python

```python
from opentrons_bioart_sim import simulate_protocol

mock = simulate_protocol('examples/octocat.py', background='black')
```

### Option 3 — Manual control

```python
from opentrons_bioart_sim import OpentronsMock

well_colors = {
    'A1': 'sfGFP',
    'A2': 'mRFP1',
    'A3': 'Azurite',
    # ...
}

mock = OpentronsMock(well_colors)
run(mock)                          # your run(protocol) function
mock.visualize(save_path='art.png')  # render the Petri dish
```

---

## Petri Dish Backgrounds

| Value     | Description                      |
| --------- | -------------------------------- |
| `'black'` | Dark agar plate (default)        |
| `'agar'`  | Normal agar plate (beige)        |
| `'paper'` | Paper insert (outline only)      |

---

## Supported Fluorescent Proteins

| Protein     | Visual Color      | Protein       | Visual Color      |
| ----------- | ----------------- | ------------- | ----------------- |
| sfGFP       | lime              | mRFP1         | red               |
| mCherry     | firebrick         | mKO2          | orange            |
| Venus       | yellow            | Azurite       | royalblue         |
| mTurquoise2 | turquoise         | TagBFP        | blue              |
| mClover3    | green             | mWasabi       | lightgreen        |
| mNeonGreen  | greenyellow       | mScarlet_I    | tomato            |
| mPlum       | purple            | Electra2      | deepskyblue       |
| mJuniper    | darkgreen         | EGFP          | lime              |

> **30+ proteins supported** — see [`colors.py`](src/opentrons_bioart_sim/colors.py) for the full list.

---

## Project Structure

```
opentrons-bioart-sim/
├── src/opentrons_bioart_sim/    # Installable package
│   ├── __init__.py              #   Public API exports
│   ├── cli.py                   #   Command-line interface
│   ├── colors.py                #   Protein → color mapping
│   ├── mock.py                  #   Mock Opentrons API classes
│   └── visualization.py         #   Petri dish rendering
├── examples/                    # Example protocols
│   ├── octocat.py
│   ├── siempre_tuyo.py
│   ├── OTDesign_02-23-26_11-56-55.py
│   └── OTDesign_02-23-26_18-57-12.py
├── notebooks/                   # Original HTGAA Colab notebooks
├── tests/                       # Test suite
├── pyproject.toml               # Build configuration
├── README.md
├── CONTRIBUTING.md
└── LICENSE
```

---

## Architecture

| Class              | Simulates                  | Key Responsibility |
| ------------------ | -------------------------- | ------------------- |
| `OpentronsMock`    | `ProtocolContext`          | Entry point — loads labware, modules, pipettes |
| `PipetteSim`       | `InstrumentContext`        | Tracks droplets, smears, volumes, colors |
| `LabwareMock`      | `Labware`                  | Well plates, tip racks, custom plates |
| `WellMock`         | `Well`                     | Individual well positions and colors |
| `ModuleMock`       | Hardware modules           | Temperature, thermocycler modules |

---

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Lint
ruff check src/ tests/
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.

---

## Credits

- **Original HTGAA Colab Notebook** — by **Eyal Perry**, **Laura Maria Gonzalez**, **Dominika Wawrzyniak**, **Alex Hadik**, **Suvin Sundararajan**, and **Ronan Donovan**. Their notebook served as the foundation codebase for this project.
- **María José Rivas Arreola** — whose HTGAA coursework inspired the creation of this standalone tool for the community.
- **[HTGAA](https://htgaa.org)** — How To Grow (Almost) Anything course
- **[Opentrons Art Designer](https://opentrons-art.rcdonovan.com/)** by RC Donovan — web tool for designing bio-art protocols
- **[Opentrons](https://opentrons.com/)** — open-source lab robotics

---

## License

MIT — see [LICENSE](LICENSE) for details.

---

<p align="center">
  Made with 🧬 + 🎨 by <a href="https://github.com/Mozta">Rafael Pérez Aguirre (@Mozta)</a>
</p>
