132 lines
4.1 KiB
Markdown
132 lines
4.1 KiB
Markdown
# PocketFlow Visualization
|
|
|
|
This directory contains tools for visualizing PocketFlow workflow graphs using interactive D3.js visualizations.
|
|
|
|
## Overview
|
|
|
|
The visualization tools allow you to:
|
|
|
|
1. View PocketFlow nodes and flows as an interactive graph
|
|
2. See how different flows connect to each other
|
|
3. Understand the relationships between nodes within flows
|
|
|
|
## Features
|
|
|
|
- **Interactive Graph**: Nodes can be dragged to reorganize the layout
|
|
- **Group Visualization**: Flows are displayed as groups with dashed borders
|
|
- **Inter-Group Links**: Connections between flows are shown as dashed lines connecting group boundaries
|
|
- **Action Labels**: Edge labels show the actions that trigger transitions between nodes
|
|
|
|
## Requirements
|
|
|
|
- Python 3.6 or higher
|
|
- Modern web browser (Chrome, Firefox, Edge) for viewing the visualizations
|
|
|
|
## Usage
|
|
|
|
### 1. Basic Visualization
|
|
|
|
To visualize a PocketFlow graph, you can use the `visualize_flow` function in `visualize.py`:
|
|
|
|
```python
|
|
from visualize import visualize_flow
|
|
from your_flow_module import your_flow
|
|
|
|
# Generate visualization
|
|
visualize_flow(your_flow, "Your Flow Name")
|
|
```
|
|
|
|
This will:
|
|
1. Print a Mermaid diagram to the console
|
|
2. Generate a D3.js visualization in the `./viz` directory
|
|
|
|
### 2. Running the Example
|
|
|
|
The included example shows an order processing pipeline with payment, inventory, and shipping flows:
|
|
|
|
```bash
|
|
# Navigate to the directory
|
|
cd cookbook/pocketflow-minimal-flow2flow
|
|
|
|
# Run the visualization script
|
|
python visualize.py
|
|
```
|
|
|
|
This will generate visualization files in the `./viz` directory.
|
|
|
|
### 3. Viewing the Visualization
|
|
|
|
After running the script:
|
|
|
|
1. Host with
|
|
```
|
|
cd ./viz/
|
|
```
|
|
|
|
2. Interact with the visualization:
|
|
- **Drag nodes** to reorganize
|
|
- **Hover over nodes** to see node names
|
|
- **Observe connections** between nodes and flows
|
|
|
|
## Customizing the Visualization
|
|
|
|
### Adjusting Layout Parameters
|
|
|
|
You can adjust the force simulation parameters in `visualize.py` to change how nodes and groups are positioned:
|
|
|
|
```javascript
|
|
// Create a force simulation
|
|
const simulation = d3.forceSimulation(data.nodes)
|
|
// Controls the distance between connected nodes
|
|
.force("link", d3.forceLink(data.links).id(d => d.id).distance(100))
|
|
// Controls how nodes repel each other - lower values bring nodes closer
|
|
.force("charge", d3.forceManyBody().strength(-30))
|
|
// Centers the entire graph in the SVG
|
|
.force("center", d3.forceCenter(width / 2, height / 2))
|
|
// Prevents nodes from overlapping - acts like a minimum distance
|
|
.force("collide", d3.forceCollide().radius(50));
|
|
```
|
|
|
|
### Styling
|
|
|
|
Adjust the CSS styles in the HTML template inside `create_d3_visualization` function to change colors, shapes, and other visual properties.
|
|
|
|
## How It Works
|
|
|
|
The visualization process consists of three main steps:
|
|
|
|
1. **Flow to JSON Conversion**: The `flow_to_json` function traverses the PocketFlow graph and converts it to a structure with nodes, links, and group information.
|
|
|
|
2. **D3.js Visualization**: The JSON data is used to create an interactive D3.js visualization with:
|
|
- Nodes represented as circles
|
|
- Flows represented as dashed rectangles containing nodes
|
|
- Links showing connections within and between flows
|
|
|
|
3. **Group Boundary Connections**: The visualization calculates intersection points with group boundaries to ensure inter-group links connect at the borders rather than centers.
|
|
|
|
## Extending the Visualization
|
|
|
|
You can extend the visualization tools by:
|
|
|
|
1. Adding new node shapes
|
|
2. Implementing additional layout algorithms
|
|
3. Adding tooltips with more detailed information
|
|
4. Creating animation for flow execution
|
|
|
|
## Troubleshooting
|
|
|
|
If you encounter any issues:
|
|
|
|
- Make sure your flow objects are properly constructed with nodes connected correctly
|
|
- Check the browser console for any JavaScript errors
|
|
- Verify that the generated JSON data structure matches what you expect
|
|
|
|
## Example Output
|
|
|
|
The visualization displays:
|
|
- Payment processing flow nodes
|
|
- Inventory management flow nodes
|
|
- Shipping flow nodes
|
|
- Group boundaries around each flow
|
|
- Connections between flows (Payment → Inventory → Shipping)
|