Implementation:PeterL1n BackgroundMattingV2 ImageSequenceWriter

Knowledge Sources	BackgroundMattingV2
Domains	Output_Management, Image_Processing
Last Updated	2026-02-09 00:00 GMT

Overview

Concrete tool for asynchronously writing PyTorch tensor batches as numbered image files provided by inference_video.py.

Description

ImageSequenceWriter saves tensor batches as individual image files (PNG or JPG) in a specified directory. Files are numbered sequentially with zero-padded 5-digit names (e.g., 00000.png). Writing is performed in background threads using threading.Thread to avoid blocking the GPU inference pipeline. Each batch spawns a new thread that converts tensors to PIL images and saves them.

Usage

Use when saving matting output as image sequences (--output-format image_sequences). Preferred over video output when lossless RGBA is needed (PNG supports alpha channels).

Code Reference

Source Location

• Repository: BackgroundMattingV2
• File: inference_video.py
• Lines: 93-109

Signature

class ImageSequenceWriter:
    def __init__(
        self,
        path: str,       # Output directory path
        extension: str    # File extension ('png' or 'jpg')
    ):
        """Creates output directory and initializes frame counter."""

    def add_batch(self, frames: Tensor) -> None:
        """
        Asynchronously save a batch of frames as numbered images.

        Args:
            frames: Tensor[B, C, H, W] float32, range 0-1
        """

    def _add_batch(self, frames: Tensor, index: int) -> None:
        """Background thread worker that saves frames to disk."""

Import

# Defined in inference_video.py (not a separate module)

I/O Contract

Inputs

Name	Type	Required	Description
path	str	Yes	Output directory path (created automatically)
extension	str	Yes	File extension: 'png' for RGBA, 'jpg' for RGB
frames	Tensor[B,C,H,W]	Yes	Batch of float tensors (0-1) to save

Outputs

Name	Type	Description
image files	Files	Numbered image files: {path}/00000.{ext}, 00001.{ext}, etc.

Usage Examples

Writing RGBA Composites

# Create writer for RGBA composite output
com_writer = ImageSequenceWriter('output/com', 'png')

# In inference loop
with torch.no_grad():
    for src, bgr in dataloader:
        pha, fgr = model(src.cuda(), bgr.cuda())[:2]
        com = torch.cat([fgr * pha.ne(0), pha], dim=1)  # RGBA
        com_writer.add_batch(com)
# Files saved as: output/com/00000.png, output/com/00001.png, ...

Related Pages

Implements Principle

• Principle:PeterL1n_BackgroundMattingV2_Image_sequence_writing