# Stitch-InBetween.ps1

Generates interpolated in-between frames between two images using RIFE and encodes them into a video.

## Synopsis

Uses `rife-ncnn-vulkan` to interpolate frames between a first and last image, then encodes the result into an H.264 video using ffmpeg.

The script:

1. Validates that the input image files exist
2. Creates a dedicated temporary directory for input images
3. Copies the first and last images to the dedicated temp directory
4. Runs `rife-ncnn-vulkan.exe` to generate interpolated frames
5. Filters the generated frames to keep only the desired in-between sequence
6. Encodes the remaining frames into a video at the specified FPS

## Parameters

- **`-First`** (required): Full or relative path to the first image file (e.g., `First.png` or `D:\Images\First.png`)
- **`-Last`** (required): Full or relative path to the last image file (e.g., `Last.png` or `D:\Images\Last.png`)
- **`-TempDir`** (optional): Full absolute path to a temporary directory for intermediate PNG frames. Must end with `\`. Defaults to a system-generated temp subdirectory. This is separate from the dedicated input temp directory.
- **`-Frames`** (required): Number of frames to generate in the output video. Must be greater than 0
- **`-Video`** (required): Output video filename. If relative, resolved against current directory
- **`-FPS`** (optional): Frames per second for the output video (default: `24`)

## Frame Generation

The number of frames passed to `rife-ncnn-vulkan` is computed as:

```text
Count  = 4 + (($Frames - 1) * 2)
EndsAt = Count / 2
```

After generation, `rife-ncnn-vulkan` outputs files named `%08d.png`. The script deletes:

- `00000001.png` (copy of the first input image)
- All files with index greater than `EndsAt` (copy of the last input image and beyond)

Only the true interpolated frames (`00000002.png` through `00000{EndsAt}.png`) are passed to ffmpeg.

## Examples

**Basic interpolation:**

```powershell
.\Stitch-InBetween.ps1 -First "frame1.png" -Last "frame2.png" -Frames 30 -Video "output.mp4"
```

**Full paths with custom FPS:**

```powershell
.\Stitch-InBetween.ps1 -First "D:\Images\start.png" -Last "D:\Images\end.png" -Frames 60 -Video "result.mp4" -FPS 30
```

**Absolute paths for input and output:**

```powershell
.\Stitch-InBetween.ps1 -First "C:\Work\Frames\A.png" -Last "C:\Work\Frames\B.png" -Frames 24 -Video "D:\Output\clip.mp4"
```

**Custom temp directory:**

```powershell
.\Stitch-InBetween.ps1 -First "A.png" -Last "B.png" -Frames 24 -Video "clip.mp4" -TempDir "D:\Temp\rife\"
```

## Safe Execution

This script supports `-WhatIf` and `-Confirm` for safe execution:

- **`-WhatIf`**: Simulate the operation without actually generating frames or creating the video. Shows what would be done.
- **`-Confirm`**: Prompt for confirmation before clearing temp directory, generating frames, and creating the video.

**Simulate without making changes:**

```powershell
.\Stitch-InBetween.ps1 -First "frame1.png" -Last "frame2.png" -Frames 30 -Video "output.mp4" -WhatIf
```

**Prompt before operations:**

```powershell
.\Stitch-InBetween.ps1 -First "frame1.png" -Last "frame2.png" -Frames 30 -Video "output.mp4" -Confirm
```

## Existing Files and Temporary Directory

- **`-Video`**: if a file already exists at this path, it is deleted before generation starts. The old file is gone even if the generation fails later. Use `-WhatIf` to see the deletion first.
- **`-TempDir`**: if the folder already exists, **everything inside it is deleted recursively** before generation starts. Pass a dedicated folder that holds nothing you need. The default is a new folder under the system temporary directory, so no existing file is deleted.
- The input frames are copied to a second temporary folder under the system temporary directory. This folder is deleted after rife-ncnn-vulkan finishes successfully.
- Intermediate frames in `-TempDir` are deleted as described in [Frame Generation](#frame-generation).

## Notes

- Requires `rife-ncnn-vulkan.exe` (TNTwise fork, RIFE 4.26) in the system PATH
- Requires `ffmpeg` in the system PATH
- Requires the `RIFE_HOME` environment variable pointing to the rife-ncnn-vulkan install directory (the same folder that is on PATH). The script resolves the model directory from `%RIFE_HOME%\rife-v4.26`.
- Requires the `NCNN_GPU_ID` environment variable set to the desired GPU device ID passed to rife-ncnn-vulkan via the `-g` flag:
    - `-1` — CPU only (no Vulkan GPU required).
    - `0`  — First GPU.
    - `1`, `2`, etc. — Additional GPUs.
- The script creates a dedicated temporary directory for input images, separate from the `-TempDir` parameter
- Input images can be located anywhere on the filesystem and are copied to the dedicated temp directory
- The dedicated input temp directory is automatically cleaned up after frame generation
- The output temp directory (`-TempDir`) is created if it does not exist; its contents are always cleared before each run
- Output codec: libx264, CRF 8, pixel format yuv420p