README.md

---
title: B&W Flowchart Sketcher
emoji: 📊
colorFrom: gray
colorTo: gray
sdk: streamlit
sdk_version: 1.35.0
app_file: app.py
pinned: false
license: mit
---

# B&W Flowchart Sketcher (Web & Desktop)

A premium, interactive utility to sketch clean, high-contrast, black-and-white flowcharts. This repository bundles two interfaces:
1. **Interactive Tkinter Desktop App** (`flowchart_app.py`): Supports canvas drag-and-drop node adjustments, visual drafting gridlines, and project serialization.
2. **Streamlit Web Application** (`app.py`): Designed for cloud deployment (Hugging Face Spaces) with interactive slider coordinates for node tuning.

---

## 📖 Table of Contents
- [Architecture & Schema Design](#-architecture--schema-design)
- [Mathematical Engine (Shapes & Ray Intersection)](#-mathematical-engine-shapes--ray-intersection)
- [Hierarchical Auto-Layout Solver](#-hierarchical-auto-layout-solver)
- [Consistent Text-Wrapping Engine](#-consistent-text-wrapping-engine)
- [Pillow Cropping & Vector-Like Rendering](#-pillow-cropping--vector-like-rendering)
- [Getting Started](#-getting-started)
- [Deployment on Hugging Face](#-deployment-on-hugging-face)

---

## 🏗️ Architecture & Schema Design

Both the desktop and web clients rely on a shared data schema managed by a backend model:

```
  +------------------+       +---------------------+
  |   Desktop GUI    |       |       Web GUI       |
  | (flowchart_app)  |       |      (app.py)       |
  +--------+---------+       +----------+----------+
           |                            |
           +-------------+--------------+
                         |
                         v
             +-----------+-----------+
             |   FlowchartModel      |
             |   - nodes {}          |
             |   - edges []          |
             +-----------+-----------+
                         |
           +-------------+-------------+
           |                           |
           v                           v
  +--------+--------+         +--------+--------+
  |  Pillow Export  |         |  JSON Project   |
  | (Vector-like)   |         |  Save/Load      |
  +-----------------+         +-----------------+
```

- **`Node`**: Houses coordinates `(x, y)`, dimension bounding boxes `(w, h)` matched to the shape, designation (short ID), shape name, and description.
- **`Edge`**: Houses connectivity mappings `(u -> v)` and styling properties (`style` = straight/curved/dotted).
- **`FlowchartModel`**: Provides path parsing (e.g. `A -> B -> C`), topological sorting layout, and JSON imports/exports.

---

## 📐 Mathematical Engine (Shapes & Ray Intersection)

To produce professional-grade diagrams, connector lines and arrowheads must terminate **precisely** at the boundary of a node shape, rather than drawing to its coordinate center (which causes overlaps). 

The mathematical engine calculates boundary intersections for every shape dynamically:

### 1. Ellipses (Circles & Ovals)
An oval centered at $(x_c, y_c)$ with semi-axes $a$ (horizontal radius) and $b$ (vertical radius) satisfies:
$$\frac{(x - x_c)^2}{a^2} + \frac{(y - y_c)^2}{b^2} = 1$$

To find where a ray in direction $(dx, dy)$ intersects the boundary, we solve for $t$:
$$t = \frac{1}{\sqrt{\frac{dx^2}{a^2} + \frac{dy^2}{b^2}}}$$
The boundary intersection point is $(x_c + t \cdot dx, y_c + t \cdot dy)$.

### 2. Polygons (Squares, Diamonds, Inverted Triangles)
For shapes represented by vertices, we cast a ray from the center $(x_c, y_c)$ to $(x_c + 10000 \cdot dx, y_c + 10000 \cdot dy)$ to ensure it crosses the boundary. We perform 2D segment-segment intersection against all edges of the polygon.

Given ray segment $AB$ and polygon edge $CD$:
$$P_{int} = A + t(B - A) = C + u(D - C)$$
Solving this linear system yields parameters $t$ and $u$. An intersection is valid if $0 \le t \le 1$ and $0 \le u \le 1$.

### 3. Curved Connector Splines
Curved connectors are drawn using **quadratic Bezier curves** parameterized by $t \in [0, 1]$:
$$B(t) = (1-t)^2 P_{start} + 2(1-t)t P_{ctrl} + t^2 P_{end}$$

- The control point $P_{ctrl}$ is computed by taking the midpoint of the node centers and offsetting it perpendicularly by 45 pixels.
- The boundary points $P_{start}$ and $P_{end}$ are computed using the ray-casting intersection formulas directed at $P_{ctrl}$.
- The arrowhead at $P_{end}$ is drawn aligned to the tangent vector $P_{end} - P_{ctrl}$, which represents the instantaneous direction of the curve at $t=1$.

---

## 🧮 Hierarchical Auto-Layout Solver

The layout solver uses a **Layered Hierarchical Graph Layout** algorithm:
1. **In-Degree Calculation**: Build an adjacency list and count incoming edges for every node.
2. **Topological Leveling (BFS)**: Node levels are assigned. Nodes with `in-degree = 0` start at Level 0. Outgoing neighbors are pushed to Level $L + 1$. Loops or cycles are broken by selecting a starter node when in-degrees are cyclic.
3. **Coordinate Allocation**: 
   - Levels are mapped to vertical coordinates ($Y$-coordinate) spaced 140px apart.
   - Nodes within the same level are sorted alphabetically (to ensure layout stability) and distributed symmetrically along the horizontal center ($X$-coordinate) with 150px spacing.

---

## ✍️ Consistent Text-Wrapping Engine

Because Tkinter Canvas and Pillow use different text-rendering engines, we implemented a custom, unified word-wrapper:
- Font metrics are queried dynamically using `font.measure` in Tkinter and `draw.textlength` in Pillow.
- The wrapper walks through the description, building text lines word-by-word. It splits to a new line as soon as the measured width exceeds the shape's specific maximum text boundaries.
- **Maximum margins** are customized for each shape to prevent text from overflowing corners (e.g. diamonds restrict width to $58\%$ of node width, whereas squares allow up to $82\%$).

---

## 🎨 Pillow Cropping & Vector-Like Rendering

When exporting a PNG:
1. The app calculates the bounding box of the entire flowchart:
   $$x_{min} = \min(x_i - w_i/2),\quad x_{max} = \max(x_i + w_i/2)$$
   $$y_{min} = \min(y_i - h_i/2),\quad y_{max} = \max(y_i + h_i/2)$$
2. It expands this box by a 50px margin on all sides.
3. The Pillow engine creates an image matching these exact cropped dimensions and applies a coordinate offset of $-(x_{min} - \text{margin}), -(y_{min} - \text{margin})$ to all drawing routines.
4. Shapes are rendered with crisp black borders, clean fills, and drop shadows offset by $+4\text{px}$ in light-gray, generating a beautiful modern aesthetic.

---

## 🚀 Getting Started

### Prerequisites
Ensure Python is installed and fetch dependencies:
```bash
pip install Pillow streamlit
```

### Running the Desktop Application
```bash
python flowchart_app.py
```

### Running the Web Application Locally
```bash
streamlit run app.py
```

---

## 🌐 Deployment on Hugging Face

This project is pre-configured for Hugging Face Spaces using the Streamlit SDK.

1. Create a new Space on [Hugging Face](https://huggingface.co/spaces) and choose the **Streamlit** SDK.
2. Link your local directory to the Git remote of the Space:
   ```bash
   git remote add origin https://huggingface.co/spaces/your-username/your-space-name
   ```
3. Push to Hugging Face:
   ```bash
   git push -u origin main --force
   ```