opentrons-bioart-sim 1.0.0

Local simulator & visualizer for Opentrons OT-2 bio-art protocols — no robot required

Opentrons Bio-Art Simulator

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

Simulate protocols generated by the Opentrons Art Designer 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)

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

pip install opentrons matplotlib

---

Usage

Option 1 — CLI (command line)

# 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

from opentrons_bioart_sim import simulate_protocol

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

Option 3 — Manual control

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 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

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

# Run tests
pytest tests/ -v

# Lint
ruff check src/ tests/

See 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 — How To Grow (Almost) Anything course
• Opentrons Art Designer by RC Donovan — web tool for designing bio-art protocols
• Opentrons — open-source lab robotics

---

License

MIT — see LICENSE for details.

---

Made with 🧬 + 🎨 by Rafael Pérez Aguirre (@Mozta)