pictomotion_pipeline/README.md

<p align="left">
  <img src="assets/pictomotion_pipline_banner.png" alt="Pictomotion Pipeline" width="75%">
</p>

> *An automated workflow that transforms AI-generated stills into cinematic 4 K motion.*

---

## 🧠 Overview

**Pictomotion Pipeline** is a modular, repeatable system for converting AI-generated images into high-resolution looping videos.  
It brings together **Midjourney**, **Upscayl**, and **FFmpeg** with optional **NVIDIA GPU acceleration**, enabling anyone to turn still frames into cinematic motion sequences.

---

## 🧩 Core Workflow

| Stage              | Tool                       | Description                                                   |
| ------------------ | -------------------------- | ------------------------------------------------------------- |
| 1️⃣ Image Creation | Midjourney                 | Generate still or short looping motion concepts.              |
| 2️⃣ Frame Export   | DaVinci Resolve / Kdenlive | Export video as PNG frame sequences.                          |
| 3️⃣ Upscaling      | Upscayl                    | Apply AI upscaling to each frame (2× – 4×).                   |
| 4️⃣ Recombine      | FFmpeg                     | Merge frames into a 4 K video with optional GPU acceleration. |
| 5️⃣ Mastering      | DaVinci / Kdenlive         | Add music, color grade, or effects (optional).                |

---

## 💻 Requirements

| Component  | Minimum                                                  | Recommended                |
| ---------- | -------------------------------------------------------- | -------------------------- |
| OS         | Windows 11 / Linux Mint 21+                              | Windows 11                 |
| GPU        | NVIDIA RTX 20-series +                                   | RTX 3070 or higher         |
| Disk Space | 20 GB free                                               | 50 GB+ for image sequences |
| Software   | Midjourney, Upscayl, FFmpeg, DaVinci Resolve or Kdenlive | Latest versions            |

---

## ⚙️ Installation & Setup

### 1️⃣ Install FFmpeg (Full GPU Build)

1. Download from [https://www.gyan.dev/ffmpeg/builds/](https://www.gyan.dev/ffmpeg/builds/)

2. Extract to  
   
   ```
   C:\ffmpeg\
   ```

3. Add to system PATH:  
   `C:\ffmpeg\bin`

4. Verify:
   
   ```bash
   ffmpeg -version
   ```

### 2️⃣ Install Upscayl

- Download the desktop version from [https://upscayl.org](https://upscayl.org)
- Launch and choose:
  - **Input:** frame folder
  - **Output:** upscaled folder
  - **Model:** General Photo
  - **Scale:** 3×
  - Click **Upscayl All Images**

### 3️⃣ Prepare Frame Sequence

- Export PNG frames from DaVinci Resolve or Kdenlive:
  
  ```
  C:\Projects\Pictomotion\frames\
  ```
  
  Example filenames:
  
  ```
  Timeline_86400.png
  Timeline_86401.png
  Timeline_86402.png
  ```

---

## 🚀 Usage

### **`pictomotion_pipeline.bat`**

Drop this batch file in your frame folder.

```batch
@echo off
setlocal EnableDelayedExpansion

set FRAMERATE=30
set OUTPUT_MP4=output_4k_video.mp4
set OUTPUT_PRORES=output_4k_prores.mov

echo =====================================
echo  🎬 Pictomotion Pipeline - Frame Recombine
echo =====================================
choice /c 12 /m "Choose render mode (1=GPU, 2=CPU): "
if errorlevel 2 set MODE=CPU
if errorlevel 1 set MODE=GPU

for %%F in (*.png) do (
    set FIRST_FILE=%%~nF
    goto FoundFirst
)
:FoundFirst
if "%FIRST_FILE%"=="" (
    echo ❌ No PNG files found!
    pause
    exit /b
)

for /f "tokens=1,2 delims=_" %%A in ("%FIRST_FILE%") do (
    set PREFIX=%%A_
    set NUM=%%B
)
for /f "tokens=* delims=0" %%A in ("%NUM%") do set START=%%A

if "%MODE%"=="GPU" (
    ffmpeg -framerate %FRAMERATE% -start_number %START% -i "%PREFIX%%%05d.png" ^
    -vf scale=3840:2160 -c:v hevc_nvenc -preset slow -b:v 20M -pix_fmt yuv420p %OUTPUT_MP4%
) else (
    ffmpeg -framerate %FRAMERATE% -start_number %START% -i "%PREFIX%%%05d.png" ^
    -vf scale=3840:2160 -c:v libx264 -crf 18 -preset slow %OUTPUT_MP4%
)

ffmpeg -framerate %FRAMERATE% -start_number %START% -i "%PREFIX%%%05d.png" ^
-vf scale=3840:2160 -c:v prores_ks -profile:v 3 %OUTPUT_PRORES%
pause
```

🟩 **GPU Mode** → Fast, HEVC (H.265) encoding with RTX  
🟦 **CPU Mode** → Slower but universal, uses x264

---

## 📁 Folder Structure

```mermaid
C:\Projects\Pictomotion\
 ├─ frames\
 │   ├─ Timeline_86400.png
 │   └─ ...
 ├─ frames_upscaled\
 │   ├─ Timeline_86400.png
 │   └─ ...
 ├─ recombine_auto_detect_gpu_toggle.bat
 ├─ output_4k_video.mp4
 └─ output_4k_prores.mov
```

---

## 🧰 Troubleshooting

| Issue                          | Cause                            | Fix                                              |
| ------------------------------ | -------------------------------- | ------------------------------------------------ |
| **“Width exceeds 4096”**       | 8 K frames with H.264            | Use HEVC NVENC or scale to 4 K                   |
| **“No capable devices found”** | Outdated NVIDIA drivers          | Update GeForce drivers                           |
| **Wrong FFmpeg version**       | PATH misordered                  | Move `C:\ffmpeg\bin` to top of PATH              |
| **Flicker in output**          | Frame variance from AI upscaling | Run `-vf deflicker` or RIFE/Video2X post-process |

---

## 🧠 Optional Enhancements

- Add background music or grade in DaVinci/Kdenlive.
- Use **Topaz Video AI** for temporal upscaling.
- Automate batch runs with **Cronicle** or **Portainer**.
- Integrate with **Trilium Notes** as a reusable template doc.

---

## 🏁 Output Summary

🎬 **output_4k_video.mp4** – HEVC H.265 4 K video (GPU or CPU)  
🎞️ **output_4k_prores.mov** – Editing-quality master  

---

## 🔖 Project Meta

| Field            | Value                                                |
| ---------------- | ---------------------------------------------------- |
| **Project Name** | *Pictomotion Pipeline*                               |
| **Category**     | AI / Video Processing                                |
| **Author**       | Europium Lab                                         |
| **Version**      | v1.0                                                 |
| **License**      | MIT (Open Source)                                    |
| **Keywords**     | Midjourney, Upscayl, FFmpeg, AI Video, GPU Rendering |