Split Image Batch:
SplitImageBatch divides a batch of images, such as video frames, into up to eight smaller batches. This lets you send different groups of frames through separate processing branches, including multi-GPU upscaling workflows. You can keep neighboring frames together or distribute frames across branches in round-robin order. After processing, a compatible merge step can bring the batches back together; preserving the original frame order depends on how those branches are merged.
Split Image Batch Input Parameters:
images
The IMAGE batch to divide. Its first dimension represents the number of frames; the node expects a four-dimensional image batch in the shape [B,H,W,C]. A video-frame batch is a typical source. This input is required and has no default, minimum, or maximum specified in the node interface. If the batch has no frames, the node returns empty image parts rather than raising an error.
num_parts
The requested number of parts when frames_per_part is 0. Use it to match the number of processing branches you intend to connect. It defaults to 4, with a minimum of 1 and a maximum of 8, in steps of 1. When frames_per_part is greater than 0, the node calculates the number of parts from the batch size instead, so this setting no longer controls the split.
mode
Controls how frames are assigned to parts when frames_per_part is 0. The options are sequential and interleaved, with sequential as the default. Sequential mode keeps contiguous ranges of frames together, which is useful when each branch should receive a continuous portion of a video. Interleaved mode assigns frames round-robin across parts, such as frame 0 to the first part and frame 1 to the second. A positive frames_per_part forces sequential chunking regardless of this setting.
frames_per_part
An optional way to specify the intended size of each chunk instead of relying on num_parts. It defaults to 0, with a minimum of 0 and a maximum of 99999, in steps of 1. At 0, splitting follows num_parts and mode. Above 0, the node creates sequential chunks of that many frames, up to eight parts; the final part takes any remaining frames, even if that makes it larger than the requested size.
Split Image Batch Output Parameters:
part_1
The first IMAGE part. It contains the first assigned group of frames and is a natural starting point for your first processing branch. If no frames are assigned to it, it is an empty image batch.
part_2
The second IMAGE part. Connect it to a separate processing branch when your split produces at least two groups. It is empty when no frames are assigned to it.
part_3
The third IMAGE part. It carries the frames assigned to the third group, allowing another branch to process them independently. It is empty when unused.
part_4
The fourth IMAGE part. With the default num_parts setting of 4 and frames_per_part set to 0, this is one of the four requested parts. It is empty if the split assigns it no frames.
part_5
The fifth IMAGE part. Use it when your configuration produces a fifth frame group. Otherwise, it remains an empty image batch.
part_6
The sixth IMAGE part. It supplies a sixth processing branch with its assigned frames when that part is needed. Otherwise, it is empty.
part_7
The seventh IMAGE part. It contains the seventh assigned frame group when the split reaches this part. Otherwise, it is empty.
part_8
The eighth IMAGE part and the last available image output. It contains its assigned frames when needed. In size-based splitting, it also receives any frames left over after the earlier chunks if the eight-part limit is reached; otherwise, it is empty.
info
A STRING summary of the result. For a nonempty batch, it reports the total frame count, the number of nonempty parts, and the frame count in each nonempty part, for example 10 frames → 3 parts [4, 4, 2]. For an empty batch, it reports 0 frames → empty parts. Check this output to confirm how the frames were divided before processing them further.
total_frames
An INT containing the number of frames in the incoming image batch. Use it to check the original batch size independently of the per-part counts shown in info. An empty batch produces 0.
Split Image Batch Usage Tips:
- For a fixed number of processing branches, leave
frames_per_partat0and setnum_partsto the number of branches you plan to use, up to eight. Connect the correspondingpart_1throughpart_8outputs. - Choose
sequentialwhen a branch should process a continuous run of video frames. Chooseinterleavedwhen you want successive frames distributed round-robin across branches. Account for the chosen order when merging processed parts. - To target a particular chunk size, set
frames_per_partabove0. For example, a 10-frame batch withframes_per_partset to4produces sequential parts containing 4, 4, and 2 frames. In this configuration,num_partsandmodedo not determine the split. - Check
infobefore connecting every output to a processing branch. The node always provides eight IMAGE outputs, but some can be empty, especially when the batch is small or fewer than eight parts are requested. - If you use eight size-based parts, check whether the final part is larger than the others. It absorbs all remaining frames after the earlier size-limited chunks, so it may take longer to process.
Split Image Batch Common Errors and Solutions:
images must be a torch.Tensor [B,H,W,C]
- Explanation: The supplied value is not the image-batch tensor that the splitting function expects. The node cannot divide it into IMAGE parts.
- Solution: Connect an IMAGE batch, such as frames supplied by a compatible video-loading workflow, to
images. Check that the connection carries image data rather than a text, mask, or other value.
images must be [B,H,W,C], got shape (...)
- Explanation: The supplied image data does not have the required four-dimensional batch shape. The shape displayed in the message shows what the node received.
- Solution: Supply a batched IMAGE value with dimensions for frame count, height, width, and channels. If you have a single image or another data format, use a compatible conversion step before this node.
Input validation rejects num_parts, mode, or frames_per_part
- Explanation: The node interface limits
num_partsto integers from1to8,modetosequentialorinterleaved, andframes_per_partto integers from0to99999. The exact validation message depends on the host application. - Solution: Select a listed mode and keep both number settings within their displayed ranges. Set
frames_per_partto0when you wantnum_partsandmodeto control the split.
0 frames → empty parts
- Explanation: This is an informational result, not an error. The incoming batch contains no frames, so all eight IMAGE parts are empty and
total_framesis0. - Solution: Check the upstream image or video-loading step and confirm that it supplies frames before running downstream processing.
A processing branch receives an empty IMAGE part
- Explanation: SplitImageBatch always returns eight IMAGE parts, even when fewer parts contain frames. An empty part can therefore reach a connected branch that expects image data.
- Solution: Read
infoto see how many nonempty parts were produced, and connect or run only the corresponding branches. If you need more nonempty parts, supply enough frames and review your split settings.
Frames appear out of order after merging
- Explanation: In
interleavedmode, consecutive frames go to different parts. Simply placing each completed part after the previous one may not restore the original frame sequence. - Solution: Use a merge step configured for the splitting pattern you selected. For a workflow that joins parts consecutively, use
sequentialmode and keep the part outputs in their original order.
