[fpie] Add video stream blending interface

README.md

@@ -88,13 +88,36 @@ $ fpie-gui -s test3_src.jpg -t test3_tgt.jpg -o result.jpg -b cuda -n 10000
 
 We provide a simple GUI for real-time seamless cloning. You need to use your mouse to draw a rectangle on top of the source image, and click a point in target image. After that the result will automatically be generated. In the end, you can press ESC to terminate the program.
 
+### Video and streams
+
+```bash
+$ fpie-video -s src.png -m mask.png -t input.mp4 -o output.mp4 -h1 100 -w1 100 -n 5000 -g max
+```
+
+`fpie-video` applies the same Poisson blending to each target frame. The target can be a video file, stream URL, or camera index supported by OpenCV/FFmpeg. If the source is a video, frames are consumed one by one; add `--loop-source` to repeat it when the target is longer.
+
+The same interface is available from Python:
+
+```python
+from fpie.video import BlendOptions, blend_video
+
+blend_video(
+    "src.png",
+    "input.mp4",
+    "output.mp4",
+    mask="mask.png",
+    mask_on_tgt=(100, 100),
+    options=BlendOptions(backend="numpy", iterations=5000),
+)
+```
+
 ### Backend and Solver
 
 We have provided 7 backends. Each backend has two solvers: EquSolver and GridSolver. You can find the difference between these two solvers in the next section.
 
 For different backend usage, please check out the related documentation [here](https://fpie.readthedocs.io/en/main/backend.html).
 
-For other usage, please run `fpie -h` or `fpie-gui -h` to see the hint.
+For other usage, please run `fpie -h`, `fpie-gui -h`, or `fpie-video -h` to see the hint.
 
 ## Benchmark Result
 

fpie/__init__.py

@@ -1,3 +1,3 @@
 """Fast Poisson Image Editing package."""
 
-__version__ = "0.3.2"
+__version__ = "0.3.3"

fpie/process.py

@@ -1,5 +1,6 @@
 """Processor abstractions and backend selection for PIE solvers."""
 
+import atexit
 import os
 from abc import ABC, abstractmethod
 from typing import Any
@@ -30,6 +31,8 @@ def _default_cpu_count() -> int:
 DEFAULT_BACKEND = "numpy"
 ALL_BACKEND = ["numpy"]
 MPI: Any | None = None
+_MPI_INITIALIZED_BY_FPIE = False
+_MPI_FINALIZER_REGISTERED = False
 
 try:
     from fpie import numba_solver
@@ -64,6 +67,9 @@ def _default_cpu_count() -> int:
     core_openmp = None
 
 try:
+    import mpi4py
+
+    mpi4py.rc.initialize = False
     from mpi4py import MPI as _MPI
 
     from fpie import core_mpi  # type: ignore
@@ -143,6 +149,28 @@ def step(self, iteration: int) -> tuple[np.ndarray, np.ndarray] | None:
         pass
 
 
+def _finalize_mpi() -> None:
+    """Finalize MPI when this module initialized it lazily."""
+    assert MPI is not None
+    if MPI.Is_initialized() and not MPI.Is_finalized():
+        MPI.Finalize()
+
+
+def _ensure_mpi_initialized() -> Any:
+    """Initialize MPI lazily when the MPI backend is explicitly selected."""
+    global _MPI_FINALIZER_REGISTERED  # noqa: PLW0603
+    global _MPI_INITIALIZED_BY_FPIE  # noqa: PLW0603
+
+    assert MPI is not None
+    if not MPI.Is_initialized():
+        MPI.Init_thread()
+        _MPI_INITIALIZED_BY_FPIE = True
+    if _MPI_INITIALIZED_BY_FPIE and not _MPI_FINALIZER_REGISTERED:
+        atexit.register(_finalize_mpi)
+        _MPI_FINALIZER_REGISTERED = True
+    return MPI
+
+
 class EquProcessor(BaseProcessor):
     """PIE Jacobi equation processor."""
 
@@ -167,9 +195,9 @@ def __init__(
         elif backend == "openmp" and core_openmp is not None:
             core = core_openmp.EquSolver(n_cpu)
         elif backend == "mpi" and core_mpi is not None:
-            assert MPI is not None
+            mpi = _ensure_mpi_initialized()
             core = core_mpi.EquSolver(min_interval)
-            rank = MPI.COMM_WORLD.Get_rank()
+            rank = mpi.COMM_WORLD.Get_rank()
         elif backend == "cuda" and core_cuda is not None:
             core = core_cuda.EquSolver(block_size)
         elif backend.startswith("taichi") and taichi_solver is not None:
@@ -306,9 +334,9 @@ def __init__(
         elif backend == "openmp" and core_openmp is not None:
             core = core_openmp.GridSolver(grid_x, grid_y, n_cpu)
         elif backend == "mpi" and core_mpi is not None:
-            assert MPI is not None
+            mpi = _ensure_mpi_initialized()
             core = core_mpi.GridSolver(min_interval)
-            rank = MPI.COMM_WORLD.Get_rank()
+            rank = mpi.COMM_WORLD.Get_rank()
         elif backend == "cuda" and core_cuda is not None:
             core = core_cuda.GridSolver(grid_x, grid_y)
         elif backend.startswith("taichi") and taichi_solver is not None: