Note

: This project was developed with the assistance of generative AI. There may be some incomplete areas or room for improvement. If you find any issues, please let us know via Issues.

Features

🎨 10 Shape Types: Circle, Heart, Star, Diamond, Square, Hexagon, Triangle, Cross, Moon, Flower
🎯 Advanced Placement Control: Fine-tune overlap ratio, coverage, rotation, and scale
🚫 Exclusion Mask Support: Prevent placement in specific areas
🔗 Chain Placement: Connect multiple nodes in series for staged placement
🎨 Color Compositing: Combine up to 3 mask layers with individual colors
📏 Out-of-Bounds Placement: Set tolerance for natural placement extending to edges
⚡ Optimized Placement Algorithm: Dynamically excludes occupied areas for efficient placement

Installation

Via ComfyUI Manager (Recommended)

Open ComfyUI Manager
Select "Custom Nodes Manager"
Search for "TJ_PolkaDot" and install
Restart ComfyUI

Node List

1. Shape Mask Generator

Generates a single shape mask.

Parameters:

shape_type: Shape type (circle, heart, star, diamond, square, hexagon, triangle, cross, moon, flower)
size: Shape size in pixels

2. Advanced Shape Placement ★Main Feature

Places multiple shape masks within a region.

Inputs:

shape_mask: Shape mask to place (required)
region_mask: Mask defining placement area (optional, full canvas if omitted)
base_mask: Existing placement for chaining (optional)
exclusion_mask: Areas to avoid placement (optional)

Parameters:

count: Number of shapes to place (default: 30)
scale_min / scale_max: Scale range (default: 0.06 - 0.15)
rotation_min / rotation_max: Rotation angle range in degrees (default: -30 - 30)
overlap_ratio: Overlap tolerance (0-1, default: 0.5)
- 0.0 = No overlap allowed
- 1.0 = Full overlap allowed
coverage_min: Minimum coverage in region (0-1, default: 0.0)
- 0.0 = Any overlap with region is OK
- 1.0 = Must be fully inside region
exclusion_tolerance: Intrusion tolerance into exclusion zones (0-1, default: 0.0)
out_of_bounds_tolerance: Out-of-bounds tolerance (0-1, default: 0.0)
- 0.0 = Must be fully inside canvas
- 0.5 = Up to 50% can be outside (recommended)
max_consecutive_fails: Consecutive failures before early termination (default: 100)
seed: Random seed

Outputs:

MASK (all): Combined mask with all placements (includes base_mask)
MASK (new): Only newly added shapes from this node
JSON: Position, scale, and rotation info for each shape

3. Colored Mask Compositor

Composites multiple mask layers with individual colors.

Inputs:

base_image: Base image
mask_1 / mask_2 / mask_3: Mask layers (optional)

Parameters (per layer):

color_X_r/g/b: RGB color (0-255)
opacity_X: Opacity (0.0-1.0)
blend_mode_X: Blend mode (normal, multiply, screen, overlay, add)

4. Multi-Shape Mask Generator

Generates and places multiple shapes at once (simplified version).

5. Mask Intersection

Calculates the intersection area of two masks.

Usage Examples

Basic Usage

Create shape with Shape Mask Generator
Place with Advanced Shape Placement
Colorize with Colored Mask Compositor

Chain Placement

Staged placement of multiple shapes:

Shape(Heart) → Advanced Placement(count=50) → Advanced Placement(count=30, shape=Circle) → Compositor
                                    ↓
                              Connect MASK (new) to next base_mask

Exclusion Mask

Avoid placing over people, etc.:

Image → Mask Generation → Invert → Connect to exclusion_mask

Recommended Parameter Values

Dense Placement

count: 100-150
overlap_ratio: 0.7-0.8
out_of_bounds_tolerance: 0.3-0.5

Scattered Placement

count: 20-40
overlap_ratio: 0.2-0.4
out_of_bounds_tolerance: 0.5

Edge-to-Edge Placement

out_of_bounds_tolerance: 0.3 or higher

Troubleshooting

Not Reaching Target Count

Increase overlap_ratio (allow more overlap)
Increase max_consecutive_fails
Increase out_of_bounds_tolerance (allow edge placement)
Increase exclusion_tolerance (relax exclusion zones)

Biased Placement

Change seed for different randomness
Adjust region_mask to expand placement area

No Placement at Edges

Set out_of_bounds_tolerance to 0.3-0.5

Technical Details

Placement Algorithm

Get Valid Positions: Extract placeable pixel coordinates from region_mask
Shuffle: Randomize coordinates to prevent spatial bias
Dynamic Exclusion: Periodically exclude occupied areas to improve efficiency
Collision Detection: Check overlap ratio, coverage, and exclusion zones
Early Termination: Stop if consecutive failures exceed threshold

Performance

Places 150 shapes in 159 attempts (99.4% efficiency)
Fast even with dense placement thanks to dynamic occupied area exclusion

License

MIT License

Author

TJ16th

Contributing

Issues and Pull Requests are welcome!

Changelog

v0.1.0 (2025-11-03)

Initial release
10 shape types support
Advanced placement control
Chain placement support
Color compositing feature
Out-of-bounds placement support
Optimized placement efficiency