diagram2code 0.1.5

Convert simple diagram images into runnable code (matplotlib/graphviz).

diagram2code

Convert simple flowchart-style diagrams into runnable Python programs.

diagram2code takes a diagram image (rectangular steps + arrows), detects the flow, and generates:

• a graph representation (graph.json)
• a runnable Python program (generated_program.py)
• optional debug visualizations (debug_nodes.png, debug_arrows.png)
• an optional exportable bundle (--export)

This project is designed for learning, prototyping, and experimentation, not for production-grade diagram parsing. :contentReference[oaicite:1]{index=1}

---

Table of Contents

1. Installation
2. Quick Start
3. Using Labels
4. Export Bundle
5. Generated Files
6. Examples
7. Limitations

---

Installation

Clone the repo and install in editable mode:

git clone https://github.com/Nimil785477/diagram2code.git
cd diagram2code

python -m venv .venv

Activate the environment

# Linux / macOS
source .venv/bin/activate

# Windows (PowerShell)
.\.venv\Scripts\Activate.ps1

Install:

pip install -e .

Basic (no OCR)

pip install diagram2code

With OCR support(optional)

pip install diagram2code[ocr]

You must also install Tesseract OCR on your system:

• Windows: https://github.com/UB-Mannheim/tesseract/wiki
• macOS:

brew install tesseract

• Ubuntu/Debian:

sudo apt install tesseract-ocr

Then run:

diagram2code image.png --extract-labels

This matches exactly what your code already does ✔️

---

(Optional but recommended) Add a runtime hint

You already handle this well, but one tiny UX improvement:

In cli.py, after --extract-labels failure, you could optionally print:

safe_print("Hint: install OCR support with `pip install diagram2code[ocr]` and install Tesseract.")

Generate a labels template (no OCR)

If you want to label nodes manually, generate a template file:

diagram2code path/to/diagram.png --out outputs --labels-template

Quick Start

Run diagram2code on a simple diagram:

diagram2code tests/fixtures/branching.png --out outputs

This will write outputs (see Generated Files)

Inspect the detected graph (print summary)

You can inspect the detected nodes, edges, and labels using --print-graph.

diagram2code tests/fixtures/branching.png --out outputs --print-graph.

This will:

• run the full detection pipeline
• write all normal output files
• print a human-readable graph summary to the console

Example Output:

Graph summary
Labels source: none
Nodes: 4
  - id=0 bbox=(40, 40, 76, 76) label=''
Edges: 4
  - 0 -> 1

Dry-run mode

If you only want to inspect the result without writing any files, use:

diagram2code diagram.png --dry-run --print-graph

In dry-run mode:

• detection still runs fully
• no files are written
• OCR does not write labels.json
• export bundles are not created

Using Labels

You can provide custom labels for nodes using a JSON file

Example labels.json

{
  "0": "Step_1_Load_Data",
  "1": "Step_2_Train_Model"
}

Run with labels

python -m diagram2code.cli diagram.png --out outputs --labels labels.json

The exported program will then use labeled function names (sanitized into valid Python identifiers).

Label resolution order (important)

When multiple label sources are possible, diagram2code resolves labels in the following priority order:

1. Explicit labels file

   diagram2code diagram.png --labels labels.json
   

2. Auto-detect labels.json inside export directory

   diagram2code diagram.png --export export_out
   

   If export_out/labels.json exists, it is automatically loaded.
3. OCR extraction

   diagram2code diagram.png --extract-labels
   

4. Fallback
   • If none of the above are provided, nodes have empty label The active source is shown when using --print-graph:

   Labels source: auto (export_out/labels.json)
   

Export Bundle

The --export flag creates a self-contained runnable bundle(easy to share). If labels.json exists inside the export directory, it will be automatically used on subsequent runs.

python -m diagram2code.cli diagram.png --out outputs --export export_bundle

When using --export, the following files are copied:

export_bundle/
├── generated_program.py
├── graph.json
├── labels.json            (if provided)
├── debug_nodes.png        (if exists)
├── debug_arrows.png       (if exists)
├── render_graph.py        (if exists)
├── run.ps1
├── run.sh
└── README_EXPORT.md

Running the exported bundle

Windows (PowerShell):

cd export_bundle
.\run.ps1

Linux/macOS:

cd export_bundle
bash run.sh

or directly:

python generated_program.py

Generated Files

After a normal run (--out outputs):

File	Description
preprocessed.png	Binary image used for detection
debug_nodes.png	Detected rectangles overlay
debug_arrows.png	Detected arrows overlay (if enabled)
graph.json	Graph structure (nodes + edges)
render_graph.py	Script to visualize the graph
generated_program.py	Generated executable Python program

Examples

CLI Usage Examples

Basic run (writes outputs to outputs/):

python -m diagram2code path/to/image.png

Export a runnable bundle:

python -m diagram2code path/to/image.png --export out

Render the detected graph (top-down layout):

python -m diagram2code path/to/image.png --export out --render-graph --render-layout topdown

Render the graph as SVG:

python -m diagram2code path/to/image.png --export out --render-graph --render-format svg

Run without writing debug artifacts:

python -m diagram2code path/to/image.png --no-debug

Diagram Examples

Simple linear flow

[ A ] → [ B ] → [ C ]

Branching flow

      → [ B ]
[ A ]
      → [ C ]

OCR (Optional)

diagram2code can extract text labels using Tesseract OCR.

Requirements:

• System: tesseract-ocr
• Python: pytesseract

If OCR is unavailable, the pipeline still works and labels default to empty.

Limitations

• Only rectangular nodes are supported
• Arrow detection is heuristic-based
• Complex curves, diagonals, or overlapping arrows may fail
• No text extraction from inside shapes
• Not intended for UML, BPMN, or hand-drawn diagrams

Demo

Convert a simple diagram image into runnable Python code:

diagram2code tests/fixtures/simple.png --out demo_outputs --extract-labels