# B&W Flowchart Sketcher - User Manual This manual provides a detailed guide on installing, launching, and designing beautiful black-and-white (B&W) flowcharts using either the **Tkinter Desktop App** (`flowchart_app.py`) or the **Streamlit Web App** (`app.py`). --- ## Table of Contents 1. [System Requirements & Installation](#1-system-requirements--installation) 2. [Interface Overview](#2-interface-overview) 3. [Managing Nodes](#3-managing-nodes) 4. [Managing Edges (Connectors)](#4-managing-edges-connectors) 5. [Arranging & Laying Out the Chart](#5-arranging--laying-out-the-chart) 6. [Saving, Loading, & Exporting](#6-saving-loading--exporting) 7. [Tips for Creating Professional Diagrams](#7-tips-for-creating-professional-diagrams) --- ## 1. System Requirements & Installation ### Requirements - **Python**: Version 3.8 or higher. - **Operating System**: Windows, macOS, or Linux. ### Installation Steps 1. Clone or download the repository to your local machine. 2. Install the necessary dependencies (primarily `Pillow` for image generation, and `streamlit` if running the web application): ```bash pip install Pillow streamlit ``` --- ## 2. Interface Overview The program provides a unified side-by-side workspace: - **Left Panel (Sidebar)**: Input forms, lists, action triggers, and file operations. - **Right Panel (Canvas)**: Live preview area rendering the flowchart. In the desktop version, this canvas is scrollable and fully interactive with drag-and-drop support. --- ## 3. Managing Nodes Every node represents a step or symbol in your diagram. ### Adding a New Node 1. Navigate to the **Node Manager** section in the sidebar. 2. **Designation / Label (Short ID)**: Enter a short, unique name for the node (e.g., `Start`, `Step 1`, `A`, `Q1`). This ID serves as the identifier when connecting nodes with edges. 3. **Icon Shape**: Select a shape from the dropdown menu: - **Circle**: Typically used for start/end terminals or connectors. - **Oval**: Used for starting/ending process bounds. - **Square**: Standard process step, task, or operation. - **Diamond**: Decision point (creates branching paths). - **Inverted Triangle**: Data input/output, yield, or storage. 4. **Description**: Enter the text that will be displayed inside the node shape. This text automatically word-wraps to fit the shape boundaries. 5. Click **Add/Save Node**. The node will appear at the center of the canvas. ### Editing an Existing Node - **Desktop**: Click on a node in the Canvas. Its properties will load into the Node Manager. Change the shape or description, and click **Save Node**. - **Web**: Type the node's **Short ID** into the form. The details will update once you click **Add/Save Node**. ### Deleting a Node Select the node (or enter its ID in the form) and click **Delete Node**. This will also remove any connecting edges associated with that node. --- ## 4. Managing Edges (Connectors) Edges connect your nodes together. The application allows you to connect multiple nodes in a single input path. ### Adding Edges 1. Locate the **Edge Manager** section in the sidebar. 2. **Path**: Input a path of nodes using delimiters. Supported formats: - Arrows: `Start -> Step 1 -> Check` - Commas: `Start, Step 1, Check` - Spaces: `Start Step 1 Check` 3. **Connector Line Style**: Select the style of the lines: - **Straight**: A crisp, direct line from the border of the source node to the border of the target node. - **Curved**: A smooth, sweeping Bezier curve that arcs around other elements (helpful for loops). - **Dotted**: A dashed, clean B&W line (often used for alternative flow paths or data streams). 4. Click **Add Edges**. ### Deleting Edges In the **Edge List** section: 1. Select the edge you wish to delete from the listbox (formatted as `Source -> Target (Style)`). 2. Click **Delete Selected Edge**. --- ## 5. Arranging & Laying Out the Chart The application provides both automatic sorting and manual positioning. ### Auto-Layout Click the **Auto-Layout** button under Actions. The application will compute a clean, hierarchical tree layout from top to bottom based on the flow direction of your edges. Disconnected nodes or cycles will be handled gracefully. ### Manual Adjustments - **Desktop (Drag-and-Drop)**: Left-click on any node in the canvas and drag it with your mouse to your desired position. All arrows will stretch and pivot in real-time. - **Web (Coordinate Sliders)**: Expand the **Manual Node Positioning** section in the sidebar, select a node, and slide the X and Y coordinate controls to reposition it precisely. --- ## 6. Saving, Loading, & Exporting ### Save / Load Projects (JSON) To save your work so you can edit it later: - Click **Save Project** (Desktop) or **Download JSON Project File** (Web). This saves the configurations of all nodes (positions, shapes, text) and edges to a lightweight `.json` file. - Click **Load Project** (Desktop) or **Upload JSON Project** (Web) and select a previously saved `.json` file to restore the chart. ### Exporting Flowcharts (PNG) To export the diagram for use in your documents, slides, or papers: 1. Click **Export PNG** (Desktop) or **Download Flowchart Image** (Web). 2. Save the file. 3. The exported PNG features: - A clean white background (grid lines and editing highlights are hidden). - High-contrast B&W rendering. - **Auto-Cropping**: The image bounds are automatically cropped to the contents of the flowchart with a clean 50px border margin (no wasted blank space). --- ## 7. Tips for Creating Professional Diagrams - **Use the Grid**: In the desktop app, visual gridlines help you align nodes. - **Looping Back**: When drawing a connector that loops back to a previous stage (e.g. `Error -> Start`), set the edge style to **Curved** so it bows outward and does not overlap your straight, forward-flowing arrows. - **Decision Branches**: For diamonds (decisions), try to route one branch straight down and the other out to the side to keep the flow readable. - **Short Texts**: Keep description labels concise. Long descriptions will wrap to multiple lines, which can crowd smaller shapes like diamonds or circles.