The Region System — an Introduction

Written: May 22, 2026 Target version: v0.1.6

PixPipeline's region system is built around one idea: instead of painting an image directly, first divide the picture into "regions", then work on those.

It shines at jobs like splitting a rock face into facets, building wavering bands on water, overlaying ore or grime onto just part of an image, or shading only the areas near a boundary.

Ordinary image nodes handle "pixels with colors". Region nodes handle a separate intermediate type, the RegionMap, which knows the region ID of every pixel, plus each region's area, center, adjacency, and whether the map wraps horizontally or vertically.

What you can do

The typical region workflow is:

1. Create regions
2. Clean up tiny regions and IDs
3. Select the regions you need
4. Convert to ordinary images — colors, lines, distances, masks, heights

Concrete uses include:

• Facet splits for rocks and terrain
• Bands for water depth or strata
• Overlaying small regions: ore, grime, patches of grass
• Extracting boundaries as pixel-art-friendly lines
• Shading or highlighting only near boundaries
• Assigning colors or patterns per region
• Creating regions only inside a mask
• Making regions that wrap for tileable materials

What a RegionMap is

A RegionMap previews like a color-coded image, but it is not a regular image.

Each pixel stores a region ID, not a color. The preview colors are temporary hues that make IDs easier to tell apart.

If one pixel has region ID 3 and its neighbor has ID 4, there is a region boundary between them. Region Border and Region Distance build boundary lines and distance images from exactly these ID differences.

Compared to ordinary images

Ordinary image:

• Each pixel holds a color
• Usable directly for compositing and output
• Similar colors do not imply the same region

RegionMap:

• Each pixel holds a region ID
• Never used directly as the final image
• Same ID = same region, reliably
• Carries area, center, adjacency, and border-contact information

preview vs regions

Most region nodes output both regions and preview.

regions is the real payload — connect it to further region processing.

preview is an ordinary color-coded image for visual checking. If you want ID processing downstream, connect regions.

labels is helper data that overlays ID numbers in the inspector; you normally never wire it yourself.

The node families

Region nodes are grouped by purpose.

Create

Nodes that produce the initial RegionMap.

When unsure, start with Region Cells. Want point-centered regions → Region Voronoi; directional bands → Region Bands / Region Strata; quantized natural variation → Region Noise.

Edit

Nodes that refine an existing RegionMap.

Editing turns raw generation into workable material: too many fragments → Region Merge Small; want predictable IDs → Region Remap; one ID appearing in several places → Region Split Islands.

Select

Nodes that pick regions by ID, area, border contact, or adjacency.

For image compositing and color work, use Region Mask; to continue region processing, use Region Filter.

Render

Nodes that convert a RegionMap into usable images or lines.

The final look of your artwork mostly comes from these nodes.

Info

Nodes for reading region information rather than making pictures.

These do not output preview images. To actually build masks or regions from adjacency, use Region Neighbor Select.

Core workflows

1. Facets for a rock face or terrain

The most basic chain:

Region Cells
  -> Region Merge Small
  -> Region Fill
  -> output / compositing

Region Cells splits the screen into facets, Region Merge Small removes tiny shards, Region Fill colors them.

For rocks, follow Region Fill with palette tweaks and shading to separate the facets tonally.

2. Boundary lines

Region Cells
  -> Region Merge Small
  -> Region Border
  -> compositing

Region Border gives you an immediate black-and-white boundary image. For line data you can stroke and clean up later, use Region Boundary Trace.

3. Shadows near boundaries

Distance from the boundary lets you shade only the edges of regions.

Region Cells
  -> Region Distance
  -> mask for color adjustment / compositing

Region Distance outputs an image that is white near boundaries and black far from them (or the reverse).

A max distance of 1–3 makes thin, pixel-art-friendly rims and shadows. Increase it for wider gradients.

4. Overlaying ore and grime

Compositing separately built regions:

Region Strata or Region Cells
  -> base regions

Region Scatter
  -> overlay regions

base + overlay
  -> Region Compose
  -> Region Fill

Build strata or a rock face as the base, scatter ore/grime as small regions, and overlay. If you plan to address IDs afterwards, set Region Compose's ID handling to "offset overlapping IDs" or "repack IDs" so the result is easy to inspect.

5. Regions only inside a silhouette

Shape or image mask
  -> Region Cells' mask input
  -> Region Fill

With a mask connected, regions are created only in the white, opaque areas — ideal when a large shape (clothes, a rock silhouette, an island) comes first and the internal facets come second.

A pixel counts as inside the mask when luma * alpha >= 0.5. Everything else is treated as OUTSIDE.

6. Wrapping edges for tiles

For tilemap materials, the repeat seams must be invisible.

Region Cells or Region Voronoi
  -> wrap X / wrap Y on
  -> Region Merge Small
  -> Region Fill

With wrapping on, regions are built as if the opposite edges were connected. The wrap flags are stored in the RegionMap, so Region Merge Small, Region Border, Region Distance, and Region Neighbor Select all treat cross-edge neighbors as adjacent.

An arbitrary mask, however, overrides wrapping — masked shapes and edge loops do not mix.

7. Patterns per region

To vary color or pattern by region, use Region Pattern Assign.

Region Cells
  -> Region Pattern Assign
  -> compositing

Region Fill paints plain colors; Region Pattern Assign is the production-oriented version that assigns looks using region ID, area, and adjacency — dark rock for large regions, bright chips for small ones, a special color for border-touching regions, and so on.

8. Prep for isometric assets

Regions also prepare isometric material:

Region Strata or Region Cells
  -> Region Height
  -> height image / shading

Region Height builds a grayscale image with a height per region — the raw material for rocky ledges, terrain elevation, or isometric relief.

Keep the RegionMap alive on a separate branch: even after making the height image, the original IDs can still produce masks and boundaries.

Favorite combinations

Natural rock facets

Region Cells
  -> Region Warp
  -> Region Merge Small
  -> Region Fill
  -> Region Border

Split, distort slightly, absorb the shards, then paint. Take Region Border from a separate branch if you want linework.

Strata plus ore

Region Strata
  -> base

Region Scatter
  -> ore

Region Compose
  -> Region Pattern Assign

Boundary-only masks

Region Cells
  -> Region Distance
  -> compositing / color adjustment

Brighten or darken only near boundaries. Small max distance → thin rims; large → broad shadows.

Check IDs, then select

Region Cells
  -> Region Debug Preview

Region Cells
  -> Region Mask

Confirm IDs with Region Debug Preview, then turn just the ones you need into a mask with Region Mask.

Important semantics

IDs are not the preview colors

Preview colors are for inspection only. Two regions with similar colors may have different IDs — and one ID may appear in several disconnected places.

To read IDs precisely, use each node's "show IDs" option or Region Debug Preview.

One ID can appear in several places

Region Noise and Image To Regions quantize values into IDs, so the same ID can occur in separate islands. To treat each island separately, append Region Split Islands.

Merge-small is not "merge everything"

Region Merge Small exists to blend away regions that are too small. min area is in pixels: at 16, regions under 16 pixels get absorbed. Its job is removing noise and shards, not collapsing the map into one blob.

Watch the size when regions come from images

Image To Regions adopts the input image's size as the RegionMap size. To match the final canvas, resize the image first — or generate regions procedurally at the target size with Region Cells, Region Noise, or Region Voronoi, which is the more robust default.

Mask input threshold

Generator mask inputs judge validity from luma and alpha:

luma * alpha >= 0.5

Only pixels meeting this are inside; the rest is OUTSIDE.

OUTSIDE is not a region

OUTSIDE is a special value meaning "no region here": outside masks, removed by filters, or simply empty. When building boundaries or distances, whether you count contact with OUTSIDE can change the result.

Wrap flags propagate downstream

A RegionMap with wrap X/Y carries that information along, so merging, boundaries, distances, and neighbor selection all treat the far edges as adjacent — essential for tiles.

Note that enabling wrap_x / wrap_y on Image To Regions does not make a non-seamless source image seamless; the flags only tell downstream region processing to connect the edges.

Picking a node

Common stumbles

The preview looks fine but downstream ID targeting misbehaves

The same ID probably appears in several places. Check with Region Debug Preview and, if needed, split with Region Split Islands.

Some regions seem to lack ID labels

With wrapping enabled, a region spanning the left/right (or top/bottom) edges is one region, and its label is drawn at a single representative spot. Use Region Debug Preview when in doubt.

Boundary lines look thick

Region Border renders the boundary between adjacent regions as an image, which can appear about two pixels wide depending on settings. For true line data use Region Boundary Trace; for rims and shadows near boundaries, Region Distance is often easier to tune.

Wrapping stopped working when I connected a mask

Arbitrary mask shapes and edge wrapping are conceptually incompatible; the mask wins and wrapping is disabled.

Regions from a saved noise image don't match the canvas size

Image To Regions uses the input image's size. Resize the image first, or generate the regions at the final size with a region generator node.

Info nodes show no preview

Region Info and Region Adjacency do not draw images — they output Maps of information. Use Region Debug Preview for visual checks and Region Neighbor Select to select using that information.

A recommended first graph

If regions are new to you, this chain shows the whole picture:

Region Cells
  -> Region Merge Small
  -> Region Debug Preview

You will see how regions form and how IDs are assigned.

Then build looks:

Region Cells
  -> Region Merge Small
  -> Region Fill

And add boundaries or shadows on separate branches:

Region Merge Small
  -> Region Border

Region Merge Small
  -> Region Distance

Regions are not a one-node system: they are small steps — create, refine, select, render — that you compose. Once comfortable, overlay maps with Region Compose and assign per-region looks with Region Pattern Assign for full production workflows.