Random Image From Batch(RandomImageFromBatch)

Description

The Random Image From Batch node (class RandomImageFromBatch) picks a sequence of frames from an image or mask batch within a selected index range. At randomness = 0 the picks are evenly spaced across the range; at randomness = 1 they are uniformly random without replacement; values in between blend linearly. The output is always sorted by batch index. Negative indices count from the end (-1 = last frame).

This node is useful for generating a controlled, reproducible subset of frames from a larger batch – for example, to create a sparse skip-frame sequence, or to select a random sample with a minimum or maximum gap between chosen frames.

Inputs

Outputs

Usage Notes

• Range definition: start_index and end_index define an inclusive range. If start_index > end_index the range is empty and no frames will be selected (the output will be an empty batch). Use negative indices to refer to the last frames conveniently (e.g., -1 for the last frame).
• Number of frames: num_frames must not exceed the number of frames in the range, otherwise behaviour is undefined (the node may clamp or error; refer to runtime messages).
• Randomness behaviour:
  • 0.0 → Frames are selected at equal intervals (linear spacing) across the range. The first pick is at the start, the last at the end.
  • 1.0 → Each pick is uniformly random without replacement (shuffle). Results are reproducible with a given seed.
  • 0.5 → Frames are placed at evenly spaced positions, then each one is jittered by a random offset proportional to the spacing (blend).
• Distance constraints (min_distance, max_distance):
  • These constraints are applied after the initial selection (whether random or evenly spaced). If constraints conflict with num_frames and the range length, the node will adjust picks to be as close as possible, clamping to the range boundaries.
  • A min_distance > 0 ensures picks are spread out. The node pushes later picks forward; the last pick may be later than the original end_index? (Actually, the description says “picks are pushed forward to satisfy this; later picks may clamp to the range end” – meaning picks will not extend beyond the range.)
  • A max_distance > 0 forces picks to stay close together. The node pulls picks in toward the start; if the range is too short, spacing may be reduced further.
  • Setting both to 0 (default) disables distance constraints entirely.
• Seed: The seed is only used when randomness > 0. For deterministic results across runs, keep the same seed and randomness value.
• Output sorting: Regardless of how the picks are made (random or sequential), the returned batch is always sorted by frame index, so later nodes receive the frames in order.

Example Use Cases

• Create a low-fps preview: Pick every N frames by setting randomness=0 and num_frames appropriate for the range length.
• Randomly sample frames for training: Set randomness=1, a large num_frames, and optionally min_distance to avoid near-identical frames.
• Evenly spaced with jitter: Set randomness=0.3 to break up harsh regular patterns while still keeping a roughly consistent tempo.