Principle:PeterL1n BackgroundMattingV2 Image sequence writing
| Knowledge Sources | |
|---|---|
| Domains | Output_Management, Image_Processing |
| Last Updated | 2026-02-09 00:00 GMT |
Overview
An asynchronous image output writer that saves PyTorch tensor batches as numbered image files using background threads for non-blocking I/O.
Description
Image sequence writing provides an alternative to video output that saves each frame as an individual image file (PNG for RGBA composites, JPG for other outputs). The writer uses Python's threading module to perform file I/O in background threads, preventing disk writes from blocking the GPU inference pipeline. Files are numbered sequentially with zero-padded 5-digit indices (e.g., 00000.png, 00001.png).
This approach is preferred over video output when:
- Lossless RGBA output is needed (PNG supports alpha channels; MP4 does not)
- Individual frame access is required for downstream processing
- Frame-accurate output without codec artifacts is needed
Usage
Use this principle when saving matting output as image sequences rather than video files. Select via --output-format image_sequences in the video inference script. One writer instance is created per output type.
Theoretical Basis
The asynchronous writing pattern uses a fire-and-forget thread model:
# Abstract async image writing
def add_batch(self, tensors):
Thread(target=self._write_batch, args=(tensors, self.index)).start()
self.index += batch_size
def _write_batch(self, tensors, start_index):
for i, tensor in enumerate(tensors):
image = tensor_to_pil(tensor)
image.save(f'{start_index + i:05d}.{extension}')
This pattern trades memory for throughput: frames are queued in thread memory while the main thread continues GPU inference.