Node-RED Image Processing Toolkit

A comprehensive Node-RED package providing 17 specialized nodes for high-performance image processing using C++ OpenCV backend. Perfect for computer vision workflows, batch processing, and automated image manipulation.

🚀 Quick Start

Installation

# Quick setup
./install.sh

# Manual installation
cd rosepetal-image-engine && npm install && npm run build
cd ../node-red-contrib-rosepetal-image-tools && npm install
cd ~/.node-red && npm install /path/to/node-red-contrib-rosepetal-image-tools

Requirements

• Node.js 16+ with node-gyp support
• OpenCV 4.x (auto-detected via pkg-config)
• C++ compiler with C++17 support

📋 Node Categories

I/O Nodes - Data Flow Management

Node	Purpose	Key Features
image-in	Load images from filesystem	JPEG/PNG/WebP/etc. support, Sharp backend
image-out	Save images with timestamp naming	Auto-naming, overwrite protection, format conversion
array-in	Collect data into positioned arrays	Dynamic positioning, batch collection
array-out	Assemble arrays from multiple sources	Timeout protection, ordered assembly
array-select	Extract elements with flexible selection	Python-like slicing, range selection
queue	Buffer and pace message delivery	FIFO gating, rate control, timed expiry

Transform Nodes - Image Processing

Node	Purpose	Key Features
resize	Scale images with aspect ratio control	Proportional scaling, multiple modes
rotate	Rotate images with custom padding	Sub-pixel precision, background colors
crop	Extract regions with pixel/normalized coords	Dynamic coordinates, bounds checking
padding	Add configurable margins	Color customization, flexible sizing
filter	Apply enhancement filters	Blur, sharpen, edge, emboss, Gaussian
draw	Overlay points and lines on images	Normalized coordinates, typed inputs, C++ compositing

Mix Nodes - Image Composition

Node	Purpose	Key Features
concat	Combine images horizontally/vertically	Direction control, padding strategies
mosaic	Position images on canvas	Coordinate positioning, manual placement
advanced-mosaic	Complex layouts with custom positioning	Pixel-perfect control, layering

Blend Nodes - Advanced Compositing

Node	Purpose	Key Features
blend	Alpha blend two images with opacity	Background removal, color tolerance
add-mask	Apply polygon-based masks to regions	Coordinate arrays, mask strength control

Specialized Nodes - AI/ML Integration

Node	Purpose	Key Features
cropBB	Extract crops from AI bounding boxes	Object detection integration, confidence filtering
image-align	Ultra-fast image alignment using ECC algorithm	Translation correction, speed presets, real-time processing

Utility Nodes - Diagnostics

Node	Purpose	Key Features
clean-debug	Safe debug output for large payloads	Buffer cleaning, sidebar/console toggles, enable/disable button
block-detect	Background watchdog for event-loop blocking	No wires, configurable thresholds, live status metrics

Architecture & Performance

Two-Tier Design

• JavaScript Layer: Node-RED integration, validation, I/O handling
• C++ Layer: OpenCV-powered image processing for maximum performance

Performance Benefits

• Faster! than pure JavaScript implementations
• Parallel processing for array operations
• Memory efficient with optimized algorithms
• Async operations with real-time performance timing

Image Data Format

{
  data: Buffer,        // Raw pixel data
  width: number,       // Image width in pixels  
  height: number,      // Image height in pixels
  channels: number,    // Channel count (1, 3, 4)
  colorSpace: string,  // "GRAY", "RGB", "RGBA", "BGR", "BGRA"
  dtype: string        // "uint8" (standard)
}

🛠️ Development

Project Structure

node-red-contrib-rosepetal-image-tools/
├── docs/nodes/          # Individual node documentation
├── nodes/              # Node-RED node implementations
│   ├── io/             # I/O nodes
│   ├── transform/      # Transform nodes  
│   ├── mix/            # Composition nodes
│   ├── blend/          # Blending nodes
│   └── specialized/    # AI/ML nodes
├── lib/                # Shared utilities
└── assets/             # Documentation assets

rosepetal-image-engine/  # C++ processing engine
├── src/                # OpenCV implementations
├── binding.gyp         # Node.js addon configuration
└── package.json

Adding New Nodes

1. Implement C++ processing in rosepetal-image-engine/src/
2. Export function in src/main.cpp
3. Create Node-RED wrapper in appropriate nodes/ category
4. Add comprehensive documentation following existing patterns

🚨 Troubleshooting

Common Issues

• Build Failures: Ensure OpenCV 4.x installed and pkg-config available
• Missing Nodes: Check Node-RED installation path and package registration
• Performance Issues: Verify C++ addon built with optimization flags
• Memory Problems: Process large images in smaller batches

Performance Tips

• Use raw format for processing chains (fastest)
• Process arrays when possible for parallel execution
• Choose appropriate output formats for your destination
• Monitor node status displays for timing information

🤝 Contributing

• Issues: Report bugs and feature requests via GitHub
• Pull Requests: Contributions welcome for new nodes and optimizations
• Documentation: Help improve guides and examples

📄 License

This project is part of the Rosepetal development toolkit for Node-RED image processing applications.

---

💡 Pro Tip: Start with simple single-node workflows, then combine them into complex processing pipelines as you become familiar with the image format and node interactions.