draw_boxes Plugin
Author: xwang152-jack
Version: 1.5.2
Type: Tool Plugin
Contact: xwang152@163.com
Overview
A Dify tool plugin for image annotation visualization. It receives image files and annotation information, then returns images with drawn bounding boxes and labels. Perfect for visualizing object detection and image segmentation results.
Key Features
- Annotation Drawing: Draw bounding boxes and labels on images
- Dify File Support: Native support for Dify file objects (recommended)
- Flexible Coordinates: Support both relative (0-1000) and absolute (pixel) coordinates
- CJK Font Support: Optimized font loading for Chinese/Japanese/Korean labels
- Custom Styling: Customizable colors, line width, and font size
- Error Handling: Comprehensive parameter validation
Parameters
Required
| Parameter | Type | Description |
|---|
image_file | file | Image file to annotate |
annotations | string | Annotation data (JSON string) |
Optional
| Parameter | Type | Default | Description |
|---|
box_color | string | #ff0000 | Bounding box color (hex) |
text_color | string | #ffffff | Text color (hex) |
line_width | number | 2 | Line width (1-20) |
font_size | number | 16 | Font size (8-72) |
coordinate_type | string | relative | Coordinate type: relative or absolute |
Annotation Format
{
"annotations": [
{
"bbox": [x1, y1, x2, y2],
"label": "person",
"confidence": 0.95
}
]
}
Coordinate Types
Relative Coordinates (0-1000):
bbox: [100, 200, 300, 400] → converted to pixel coordinates- Default mode for better compatibility
Absolute Coordinates (pixels):
bbox: [50, 100, 150, 200] → used directly as pixel coordinates- Set
coordinate_type: "absolute" to use this mode
Usage in Dify Workflow
- Add the
draw_boxes tool node to your workflow
- Connect an image file to the
image_file parameter
- Provide annotation JSON from a vision model or other source
- The tool outputs an annotated image with bounding boxes
Output Format
Success:
{
"success": true,
"annotation_count": 2,
"image_size": {"width": 800, "height": 600},
"message": "成功绘制2个标注"
}
Error:
{
"success": false,
"error": "Error description",
"error_code": 400
}
Error Codes
| Code | Description |
|---|
| 400 | Parameter error |
| 404 | Image loading failed |
| 413 | Image too large (>4096x4096) |
| 422 | Invalid annotation format |
| 500 | Internal server error |
Limitations
- Maximum image size: 4096x4096 pixels
- Maximum annotations: 100 per image
- Line width range: 1-20
- Font size range: 8-72
CJK Font Support
For proper Chinese/Japanese/Korean label display, ensure your Dify environment has CJK fonts installed:
# Debian/Ubuntu
apt-get install -y fonts-noto-cjk
# Alpine Linux
apk add font-noto-cjk
Installation
pip install -r requirements.txt
License
See PRIVACY.md for privacy policy.
Changelog
v1.5.2 (2025-12-18)
- Added automatic Chinese font downloading (WenQuanYi Micro Hei) to fix "tofu" character issues in containerized environments
- Improved font fallback mechanism
v1.5.1 (2025-12-18)
- Fixed an issue where label font size adjustments were ignored when using the fallback default font
- Updated default font loading to support dynamic sizing (requires Pillow>=10.0.0)
v1.2.0 (2025-12-07)
- Breaking Change: Changed
image_data (string) to image_file (file type) for better Dify integration
- Added native Dify File object support
- Improved CJK font loading priority for Chinese/Japanese/Korean labels
- Enhanced debug logging for troubleshooting
v1.1.1
- Bug fixes and stability improvements
v1.0.0 (2025-09-27)
- Initial release
- Relative and absolute coordinate modes
- Smart format detection
Support
Contact: xwang152@163.com or submit an issue.