Batch Render

Overview

The core batch-production node for generating parameter variations from the same graph. It applies candidates from a list produced by nodes such as variant_range one at a time, evaluates the graph, and combines images with different colors, seeds, or angles into a single sprite sheet. This is where PixPipeline's strength in batch-producing variations takes shape.

Read this first

• This node applies each candidate received through items and creates one image.
• Unlike AnimationRender, which iterates over time, this node iterates over candidates.

What happens

The process is:

1. Select one item from items.
2. Apply its snapshot to the graph.
3. Render one result from the image input.
4. Repeat for every item.
5. Commit frames and spritesheet only after every item succeeds.

If any one item fails evaluation, the batch fails without returning a partial result.

Understanding the outputs

Start with this example

Build the following graph:

• PixelCanvas
• Brightness
• VariantRange
• BatchRender

Settings:

• VariantRange.key = strength
• VariantRange.start = 0
• VariantRange.end = 1
• VariantRange.count = 5
• Bind the strength parameter of Brightness to the strength variable.
• PixelCanvas.image -> Brightness.image -> BatchRender.image
• VariantRange.variants -> BatchRender.items

The candidates from VariantRange are:

[
  { "snapshot": { "values": { "strength": 0.0 } } },
  { "snapshot": { "values": { "strength": 0.25 } } },
  { "snapshot": { "values": { "strength": 0.5 } } },
  { "snapshot": { "values": { "strength": 0.75 } } },
  { "snapshot": { "values": { "strength": 1.0 } } }
]

BatchRender applies them to the graph one at a time, producing five images with different brightness levels.

records

[
  { "name": "strength=0.000", "snapshot": { "values": { "strength": 0.0 } } },
  { "name": "strength=0.250", "snapshot": { "values": { "strength": 0.25 } } },
  { "name": "strength=0.500", "snapshot": { "values": { "strength": 0.5 } } },
  { "name": "strength=0.750", "snapshot": { "values": { "strength": 0.75 } } },
  { "name": "strength=1.000", "snapshot": { "values": { "strength": 1.0 } } }
]

frames

[
  "<Image strength=0.0>",
  "<Image strength=0.25>",
  "<Image strength=0.5>",
  "<Image strength=0.75>",
  "<Image strength=1.0>"
]

count / frame_count

count = 5
frame_count = 5

Two-axis combination example

Place CartesianProduct before this node to batch candidates across two axes directly.

Example:

• VariantRange(key=strength, start=0, end=1, count=3)
• SeedRange(key=seed, start=10, count=2, step=1)
• CartesianProduct
• BatchRender

This produces 3 x 2 = 6 combinations.

BatchRender collects the snapshots inside CartesianProduct and treats them as candidates shaped like this:

{
  "snapshot": {
    "values": {
      "strength": 0.0,
      "seed": 10
    }
  }
}

Where snapshot keys are applied

Snapshot keys can target the graph in these forms:

1. variable id or name for a variable-bound parameter
2. node id, variable id, or variable name for a variable_ref node
3. a direct parameter in exact nodeId:paramId form

For beginners, matching the variable name is the clearest approach. For a direct parameter, both the frontend node id and parameter id must exist in the graph and match exactly, including case.

Common pitfalls

• Every frame has the same image: the snapshot key does not match anything in the graph. Check that the variable name (or nodeId:paramId) matches VariantRange.key.
• Confusing it with animation_render: that node iterates over time (all frames with the same settings), while this one iterates over candidates (one candidate per image). Combine them when you need both, such as batch-producing palette variants of a walk animation.
• Frame sizes vary: if the upstream graph contains solid_render or a similar node, set frame_mode = FixedCanvas to fix the dimensions (see the eight-direction asset example).
• Only one item fails: Batch Render is all-or-nothing. It does not return the successful subset; fix the failed candidate and evaluate the complete batch again.

Notes

• Each item is normalized to a VariantRecord before use.
• A Map returned by ListZip / CartesianProduct can be passed directly.
• Bookkeeping keys such as index / a_index / b_index are ignored automatically.
• If different combination axes contain the same snapshot key, Batch Render reports an error instead of choosing an implicit overwrite order. Merge the value explicitly.

Solid eight-direction assets

When batch-producing Solid Render camera azimuths in 45-degree increments, the shortest setup is to create a direct param key with VariantRange.

Example settings:

• Solid Render node ID: render
• VariantRange.key = render:azimuth
• VariantRange.start = 0
• VariantRange.end = 315
• VariantRange.count = 8
• Solid Render.frame_mode = FixedCanvas
• Solid Render.camera_angle_snap = 45
• BatchRender.columns = 8

Because BatchRender applies each snapshot to the graph individually, it can combine all eight directions with a consistent frame size.

Related nodes

• variant_range / seed_range — generate candidate lists (almost always paired with this node)
• cartesian_product — creates two-axis candidate combinations such as color × seed
• batch_export — exports the frames as files
• animation_render — use this for iteration over time (animation)