Image Workflow

A visual image processing workflow application built with Qt6 and OpenCV. It provides both a graphical user interface and command-line interface for building custom image processing pipelines using connected processing nodes.

📋 Table of Contents

• Features
• Architecture
• Running Modes
• Node Types
• Workflow JSON Format
• Building the Project
• Usage
• Examples

✨ Features

• 🎨 Visual Workflow Editor: Drag-and-drop nodes and connect them to build processing pipelines
• 🔧 Multiple Image Processing Operations: Crop, resize, rotate, flip, color adjustment, and more
• 🎯 Channel Processing: Split and merge color channels with individual channel adjustments
• ✂️ Smart Cutout: Automatic orange color detection and background removal
• 📊 Image Assessment: Evaluate roundness and color saturation of orange regions
• 🤖 VLM Integration: Call Vision-Language Models via OpenRouter API
• 💻 Command-Line Support: Execute saved workflows directly via CLI
• 💾 Workflow Persistence: Save and load workflows in JSON format

🏗️ Architecture

The project follows a modular architecture with clear separation of concerns:

image_workflow/
├── include/                    # Header files
│   ├── MainWindow.h           # Main application window
│   ├── GraphScene.h           # QGraphicsScene for workflow canvas
│   ├── NodeItem.h             # Base class for processing nodes
│   ├── ConnectionItem.h       # Connection lines between nodes
│   ├── ImageProcessor.h       # Image processing logic
│   ├── WorkflowEngine.h       # CLI workflow execution engine
│   ├── NetworkManager.h       # HTTP requests for VLM nodes
│   ├── ImageUtils.h           # Utility functions
│   └── json.hpp               # JSON parsing library (nlohmann)
├── src/                       # Source files
│   ├── main.cpp               # Entry point with CLI/GUI mode detection
│   ├── MainWindow.cpp         # GUI implementation
│   ├── GraphScene.cpp         # Scene interaction logic
│   ├── NodeItem.cpp           # Node rendering and behavior
│   ├── ConnectionItem.cpp     # Connection rendering
│   ├── ImageProcessor.cpp     # Processing algorithms
│   ├── WorkflowEngine.cpp     # CLI execution engine
│   ├── NetworkManager.cpp     # Network communication
│   └── ImageUtils.cpp         # Image conversion utilities
├── image_workflow.h/cpp       # Legacy QMainWindow wrapper
├── image_workflow.ui          # Qt Designer UI file
├── image_workflow.qrc         # Qt resource file
└── Help.md                   # Chinese help documentation

🧩 Core Components

1. MainWindow 🖥️: The main GUI window containing the menu bar, image display area, workflow canvas, and log panel.

2. GraphScene 🎨: A custom QGraphicsScene that manages nodes and connections, handling mouse events for creating connections.

3. NodeItem 📦: Represents a processing node in the workflow canvas. Each node has input/output ports and adjustable parameters.

4. ConnectionItem 🔗: Visual representation of connections between nodes, showing the flow of image data.

5. ImageProcessor ⚙️: Contains all image processing algorithms for different node types (crop, resize, color adjustment, cutout, etc.).

6. WorkflowEngine 🚀: Executes workflows in CLI mode using topological sorting to process nodes in the correct order.

7. NetworkManager 🌐: Handles HTTP requests to external APIs (OpenRouter) for VLM nodes.

📊 Data Flow

Input Image → [Node1] → [Node2] → ... → [NodeN] → Output Image
              ↓          ↓                  ↓
         Parameters  Parameters        Parameters

Nodes are connected in a directed acyclic graph (DAG). The workflow engine uses topological sorting to execute nodes in the correct dependency order.

🚀 Running Modes

The application automatically detects which mode to use based on command-line arguments.

1. 🖱️ GUI Mode (Default)

Launch without any arguments:

image_workflow.exe

This opens the graphical interface where you can interactively build and execute workflows.

2. 💻 CLI Mode

Provide the required arguments to execute a workflow directly:

image_workflow.exe --workflow <workflow.json> --input <input.jpg> --output <output.png>

CLI Arguments

Argument	Short	Required	Description
--workflow	-workflow	Yes	Path to workflow JSON file
--input	-input	Yes	Input image path
--output	-output	Yes	Output image save path

📝 CLI Mode Notes

• ⚠️ VLM nodes are skipped in CLI mode (requires network interaction)
• 🔇 OpenCV log level is set to WARNING to reduce console output
• ⚠️ If the workflow contains a cutout node and the output format doesn't support Alpha channel (e.g., JPG), a warning is displayed

🎯 Node Types

📝 Basic Processing Nodes

1. ✂️ Crop Node

Crops the image to a specified rectangular region.

Parameters:

Parameter	Type	Default	Description
X	Integer	0	Crop start X coordinate
Y	Integer	0	Crop start Y coordinate
Width	Integer	100	Crop width
Height	Integer	100	Crop height

---

2. 🔍 Resize Node

Scales the image by a factor.

Parameters:

Parameter	Type	Default	Description
ScaleFactor	Float	1.0	Scale factor (0.5 = half size, 2.0 = double size)

---

3. 🔄 Rotate Node

Rotates the image by multiples of 90 degrees.

Parameters:

Parameter	Type	Default	Description
Angle	Integer	90	Rotation angle (90, 180, or 270)

---

4. ↔️ Flip Node

Flips the image horizontally or vertically.

Parameters:

Parameter	Type	Default	Description
Direction	String	"Horizontal"	Flip direction ("Horizontal" or "Vertical")

---

5. 🎨 Color Node

Adjusts image saturation, brightness, and contrast.

Parameters:

Parameter	Type	Default	Description
Saturation	Float	1.0	Saturation multiplier (1.0 = original)
Brightness	Float	0.0	Brightness adjustment (can be positive or negative)
Contrast	Float	1.0	Contrast multiplier (1.0 = original)

---

🚀 Advanced Nodes

6. 🎯 Channel Processing Unit

A composite unit that automatically creates a channel processing pipeline:

channel_split → [color] → [color] → [color] → channel_merge
                   ↓         ↓         ↓
                  B ch      G ch      R ch

• channel_split: Splits BGR image into 3 single-channel images
• 3× color nodes: Adjust each channel individually (B, G, R)
• channel_merge: Merges processed channels back into a BGR image

Use this when you need fine-grained control over individual color channels.

---

7. ✂️ Cutout Node

Detects orange regions and makes everything else transparent.

Algorithm:

1. 🎨 Convert image to HSV color space
2. 🎯 Apply color threshold (H: 0-25, S: 40-255, V: 40-255) to detect orange
3. 🔧 Apply morphological operations (close) to refine the mask
4. 🔍 Find the largest orange contour
5. 🖼️ Convert BGR to BGRA (add Alpha channel)
6. 🎭 Set Alpha to 0 (transparent) for non-orange regions

Output: 4-channel image (BGRA) with transparent background

Important: ⚠️ Use PNG format to preserve transparency. JPG/BMP will lose transparency information.

---

8. 🎨 Stylization Node

Applies an artistic stylization effect to the image.

Parameters: None (uses default: sigma_s=60, sigma_r=0.45)

Works with both 3-channel and 4-channel images.

---

9. 📊 Assess Node

Evaluates the quality of orange regions in the image.

Metrics:

1. Roundness 🔵: 4 × π × area / perimeter² (0-1, where 1 = perfect circle)
2. Color 🎨: Average saturation in HSV space (0-1)
3. Total Score 📈: Roundness × 0.6 + Color × 0.4, expressed as percentage

Output: No image output (passes input through). Results are saved to assess_result.txt:

Roundness: 0.85, Color: 0.72, Total: 79.80

---

10. 🤖 VLM Node

Calls a Vision-Language Model API to analyze images and get text descriptions.

Parameters:

Parameter	Type	Default	Description
ApiKey	String	""	OpenRouter API key
Prompt	Text	"Describe this image"	Prompt sent to the VLM
Model	String	"sourceful/riverflow-v2-fast"	VLM model name

Supported Models (via OpenRouter):

• qwen/qwen3-vl-8b-instruct (default)
• Other OpenRouter-supported vision models

Output: No image output (passes input through). Response is saved to vlm_response.txt.

Requirements:

• ✅ Valid OpenRouter API key
• 🌐 Network connection
• 🔒 OpenSSL support (for HTTPS)

Note: ⚠️ VLM nodes are not supported in CLI mode.

📋 Workflow JSON Format

Workflows are saved as JSON files with nodes and connections arrays.

📝 Field Descriptions

Nodes Array

Field	Type	Required	Description
id	Integer	Yes	Unique node identifier
type	String	Yes	Node type (see Node Types section)
x	Float	No	Node X position on canvas
y	Float	No	Node Y position on canvas
params	Object	No	Node parameters (varies by type)

Connections Array

Field	Type	Required	Description
from_id	Integer	Yes	Source node ID (output)
to_id	Integer	Yes	Target node ID (input)

🏷️ Supported Node Types

• crop - ✂️ Crop node
• resize - 🔍 Resize node
• rotate - 🔄 Rotate node
• flip - ↔️ Flip node
• color - 🎨 Color adjustment node
• channel_split - 🎯 Channel split node
• channel_merge - 🎯 Channel merge node
• cutout - ✂️ Orange cutout node
• stylization - 🎨 Stylization node
• assess - 📊 Assessment node
• vlm - 🤖 Vision-Language Model node

⚙️ Execution Logic

The workflow engine uses topological sorting to execute nodes in dependency order:

1. 🏗️ Build a node graph based on connections
2. 🔢 Calculate in-degrees (number of inputs) for each node
3. 🚀 Start from nodes with in-degree 0 (starting nodes)
4. ▶️ Process sequentially:
   • Execute current node, get output image
   • Pass output to all connected downstream nodes
   • When all inputs for a node are ready, add it to the execution queue
5. 🏁 Final output: The last node's output (or nodes without output connections)

🛠️ Building the Project

📋 Prerequisites

• Visual Studio 2022 or later
• Qt 6.x development libraries
• OpenCV 4.12+
• OpenSSL (for VLM functionality)

📖 Usage

🖱️ GUI Mode

1. 📂 Import Image: File → Import (supports PNG, JPG, JPEG, BMP, TIFF)
2. ➕ Add Nodes: Node menu → Select node type
3. 🔗 Connect Nodes:
   • Click source node (output port) - node highlights
   • Click target node (input port) - connection created
   • Click empty area to cancel connection mode
4. ⚙️ Set Parameters: Right-click node → Set parameters in dialog → OK
5. ▶️ Run Workflow: Run → Run All
6. 💾 Export Result: File → Export

📏 Node Connection Rules

• Each node can have only one input connection (from a previous node)
• Each node can have multiple output connections (to multiple subsequent nodes)
• Nodes without input connections are starting nodes

💻 CLI Mode

image_workflow.exe --workflow workflow.json --input input.jpg --output output.png

The CLI mode will:

1. 📂 Load the workflow JSON
2. 🖼️ Read the input image
3. ⚙️ Execute all nodes in topological order
4. 💾 Save the result to the output path
5. 📝 Print success/error messages to console

📝 Examples

Example 1: 🔄 Rotate and Crop

First rotate 90 degrees, then crop a region.

JSON:

{
    "nodes": [
        {
            "id": 1,
            "type": "rotate",
            "x": -100,
            "y": 0,
            "params": {
                "Angle": 90
            }
        },
        {
            "id": 2,
            "type": "crop",
            "x": 100,
            "y": 0,
            "params": {
                "X": 50,
                "Y": 50,
                "Width": 200,
                "Height": 200
            }
        }
    ],
    "connections": [
        {
            "from_id": 1,
            "to_id": 2
        }
    ]
}

---

Example 2: ✂️ Orange Cutout

Detect and cut out orange regions from an image.

JSON:

{
    "nodes": [
        {
            "id": 1,
            "type": "cutout",
            "x": 0,
            "y": 0,
            "params": {}
        }
    ],
    "connections": []
}

Command:

image_workflow.exe --workflow cutout.json --input orange.jpg --output result.png

---

Example 3: 🎨 Color Adjustment

Adjust saturation, brightness, and contrast.

JSON:

{
    "nodes": [
        {
            "id": 1,
            "type": "color",
            "x": 0,
            "y": 0,
            "params": {
                "Saturation": 1.5,
                "Brightness": 20,
                "Contrast": 1.2
            }
        }
    ]
}