Add-Mask Node

Purpose & Use Cases

The add-mask node applies polygon-based masks to images using coordinate arrays to define masked regions. It creates weighted blending effects within polygon boundaries, perfect for selective image modifications and region-based processing from AI detection or manual selection.

Real-World Applications:

• AI Object Masking: Apply masks from AI detection results with polygon coordinates
• ROI Processing: Highlight or modify regions of interest defined by coordinate boundaries
• Selective Enhancement: Apply effects only within specific geometric areas
• Quality Control: Overlay inspection results on products using detected boundaries
• Medical Analysis: Highlight detected anomalies or structures with polygon masks

[PLACEHOLDER - Add GIF showing various masking operations including product cutouts and artistic effects]

Input/Output Specification

Inputs

• Base Image: The image to which the polygon mask will be applied
• Polygon Coordinates: Array of [x, y] coordinate pairs defining mask boundary
• Mask Parameters: Strength and fill color via configuration

Outputs

• Masked Image: Original image with weighted blending applied within polygon area
• Selective Processing: Areas within polygon receive mask treatment based on strength setting
• Format Options: Raw image object or encoded file formats

Configuration Options

Input Paths

• Image Path: Location of base image to mask (default: msg.payload.image)
• Polygon Path: Location of coordinate array (default: msg.payload.default.masks[0].mask[0])
• Path Sources: msg.*, flow.*, global.*

Output Configuration

• Output Path: Where to store masked result (default: msg.payload)
• Output Format: Raw, JPEG, PNG, WebP
• Quality Settings: Compression settings for lossy formats

Polygon Mask Options

Coordinate System

• Normalized Coordinates: All coordinates must be in range [0, 1]
• Format: Array of [x, y] pairs: [[x1,y1], [x2,y2], [x3,y3], ...]
• Relative Positioning: 0.0 = left/top edge, 1.0 = right/bottom edge

Mask Strength

• Range: 0-100% (0 = no effect, 100 = maximum blending)
• Default: 50% for balanced effect
• Purpose: Controls intensity of mask blending within polygon

Fill Color

• Format: Hex color code (e.g., #FF0000 for red)
• Default: White (#FFFFFF)
• Purpose: Color used for blending within masked polygon area

Output Format Options

• Raw: Standard image object with alpha channel
• PNG: Full transparency preservation (recommended)
• WebP: Modern format with transparency support
• JPEG: Not recommended (transparency becomes background color)

Performance Notes

C++ Backend Processing

• Optimized Alpha Processing: Fast alpha channel manipulation
• Edge Smoothing: High-quality anti-aliasing for smooth mask edges
• Memory Efficient: Direct alpha channel writing without full image copying
• Format Handling: Proper handling of different input mask formats

Mask Processing Algorithms

• Grayscale Conversion: Efficient luminance-to-alpha conversion
• Edge Detection: Smart edge smoothing for professional results
• Threshold Processing: Fast binary mask generation when needed

Real-World Examples

AI Object Detection Highlighting

// AI detection provides polygon coordinates
msg.detectedObjects[0] = {
  polygon: [[0.1, 0.2], [0.8, 0.2], [0.8, 0.7], [0.1, 0.7]],
  confidence: 0.95
};
msg.payload.image = originalImage;
msg.payload.default.masks[0].mask[0] = msg.detectedObjects[0].polygon;

[Image + AI Polygons] → [Add-Mask: 30% red overlay] → [Highlighted Detections]

Quality Control ROI

// Define inspection region
msg.inspectionRegion = [
  [0.25, 0.25], [0.75, 0.25], 
  [0.75, 0.75], [0.25, 0.75]
];

[Product Image] → [Function: Set ROI] → [Add-Mask: 50% yellow] → [Inspection Overlay]

Medical Annotation

// Radiologist defined region
msg.anomalyRegion = [
  [0.4, 0.3], [0.6, 0.3], [0.65, 0.5], 
  [0.6, 0.7], [0.4, 0.7], [0.35, 0.5]
];

[Medical Scan] → [Function: Set Polygon] → [Add-Mask: 40% red] → [Annotated Scan]

Custom Selection Processing

// User-defined polygon selection
msg.userSelection = [
  [0.0, 0.0], [1.0, 0.0], [1.0, 0.5], [0.0, 0.5]
]; // Top half of image

[Image] → [Function: Set Selection] → [Add-Mask: 70% blue tint] → [Selective Processing]

Batch Region Processing

[Image Array] → [AI Detection] → [Extract Polygons] → [Add-Mask: Highlight] → [Processed Results]

Process multiple images with AI-detected regions.

Common Issues & Troubleshooting

Invalid Polygon Coordinates

• Issue: Error messages about invalid coordinate format or ranges
• Solution: Ensure coordinates are arrays of [x,y] pairs with values in [0,1] range
• Format: [[0.1,0.2], [0.8,0.2], [0.8,0.7], [0.1,0.7]]

Empty or Missing Polygons

• Issue: No masking effect applied to image
• Solution: Verify polygon path contains valid coordinate array
• Check: Ensure polygon array is not empty and coordinates are properly formatted

Polygon Outside Image Bounds

• Issue: Mask effect not visible or only partially applied
• Cause: Polygon coordinates outside [0,1] normalized range
• Solution: Validate all coordinates are between 0.0 and 1.0

Incorrect Path Configuration

• Issue: Node cannot find image or polygon data
• Solution: Verify input paths match your message structure
• Default Paths: msg.payload.image and msg.payload.default.masks[0].mask[0]

Weak or Invisible Mask Effects

• Issue: Mask blending barely visible on image
• Solution: Increase mask strength percentage or adjust fill color contrast
• Optimization: Use colors that contrast well with image content

Integration Patterns

E-commerce Product Processing

Product Photo → Background Detection → Generate Mask → Add-Mask → Clean Cutout

Automated product cutout generation for online catalogs.

Portrait Enhancement Workflow

Portrait → Create Vignette → Add-Mask → Color Enhancement → Artistic Portrait

Professional portrait processing with masking effects.

Logo Production Pipeline

Design → Shape Creation → Mask Generation → Add-Mask → Export Formats

Convert solid designs into transparent logo formats.

Medical Analysis Pipeline

Scan → Region Detection → Mask Creation → Add-Mask → Analysis → Report

Medical imaging analysis with region masking.

Advanced Usage

Dynamic Mask Creation

// Generate circular mask based on image dimensions
const width = msg.image.width;
const height = msg.image.height;
const radius = Math.min(width, height) / 3;

msg.maskType = 'circular';
msg.maskRadius = radius;
msg.maskCenter = { x: width/2, y: height/2 };

Conditional Mask Processing

// Apply different mask processing based on image type
if (msg.imageType === 'product') {
  msg.maskInversion = false;
  msg.smoothEdges = true;
  msg.featherAmount = 2;
} else if (msg.imageType === 'portrait') {
  msg.maskInversion = true; // Vignette mask
  msg.smoothEdges = true;
  msg.featherAmount = 5;
}

Quality-Based Processing

// Adjust processing based on output requirements
if (msg.outputUse === 'web') {
  msg.outputFormat = 'webp';
  msg.featherAmount = 1; // Minimal feathering for web
} else if (msg.outputUse === 'print') {
  msg.outputFormat = 'png';
  msg.featherAmount = 3; // More feathering for print
  msg.smoothEdges = true;
}

Batch Mask Application

// Apply same mask to multiple images
msg.images.forEach((img, index) => {
  img.maskSettings = {
    invert: false,
    smooth: true,
    feather: 2
  };
});

Best Practices

Mask Creation

• Create masks at same resolution as target images for best quality
• Use soft brushes or gradients for smooth edge transitions
• Test masks with sample images before batch processing
• Save masks as high-quality grayscale or alpha channel images

Edge Quality

• Enable smooth edges for professional results
• Use appropriate feathering amounts (1-3 pixels for web, 2-5 for print)
• Consider anti-aliasing requirements for your final output
• Test edge quality at actual display size

Format Selection

• PNG: Best for transparency preservation and quality
• WebP: Good compression with transparency support
• Raw: For continued processing chains
• Avoid JPEG: For images requiring transparency

Performance Optimization

• Use appropriately sized masks (don't oversample)
• Process masks separately from color correction when possible
• Use raw format for processing chains
• Consider memory usage with large high-resolution images

Quality Considerations

• Match mask resolution to target image resolution
• Use high-quality source masks without compression artifacts
• Test transparency results in final display context
• Consider edge quality requirements for intended use

Production Workflow

• Maintain original images before masking
• Create standardized mask templates for consistent results
• Implement quality checks for edge smoothness
• Document mask settings for reproducible results