# happy95059/video_combine architecture

> Architecture diagram of the GitHub repository happy95059/video_combine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/happy95059/video_combine
- Repository: https://github.com/happy95059/video_combine

## Overview

##### Project Type and Purpose
- Project type: Open-source CLI tool (Python) for image/video steganography.
- Purpose: “Combine” one file (B) into another (A) to produce C (which visually resembles B), and generate a “Trans” module (key) that allows lossless back-and-forth conversion between C and C̄.

##### File Structure
- Top-level:
- code/ – Python scripts (example.py, img_combine.py, video_combine.py, 影片測試.py)
- data/ – sample inputs/outputs (.mp4, .avi)
- README.md, LICENSE, .gitignore
- No separate frontend/backend—this is a command-line utility.
- Key scripts:
- img_combine.py – orchestrates image bit-plane merge & extract
- video_combine.py – wraps video I/O around the same bit-plane logic
- example.py / 影片測試.py – usage examples/tests

##### README for Architectural Insights
- Core operations: Combine(A, B) → C ; Trans(C) → C̄
- Underlying mechanism: breakdown into bit planes, three methods of interleaving/compressing bit-planes.
- Dependencies: Uses FFV1 (via FFmpeg) for lossless AVI encoding; OpenCV or similar for reading/writing frames.

##### Main Components
a. Entry Point (CLI scripts)
- img_combine.py
- video_combine.py
- example.py / test script
b. File I/O Layer
- Image I/O (JPEG, PNG → NumPy arrays)
- Video I/O (MP4 → frames → AVI via FFV1)
c. Steganography Core
- Bit-Plane Extractor
- Method Selector (method1, method2, method3)
- Bit-Plane Merger (Combine logic)
- Compressor/Decompressor for X1, X2 planes
d. Trans (Converter/Key) Module
- Stores transformation rules (e.g., which bit-planes or shuffle maps)
- Used to invert C → original B or A
e. Output Layer
- Writes combined media (C) to data/
- Writes “trans” key/config file

##### Relationships & Data Flow
1. User invokes CLI script → passes paths for A and B.
2. File I/O layer reads A and B → delivers raw frames or pixel arrays.
3. Steganography Core:
- Extracts bit planes from A & B
- Depending on chosen method, merges them into new bit planes → forms C
- Generates Trans key (compress/shuffle maps)
4. Output Layer writes:
- C (as AVI or image)
- Trans key/config
5. For Trans operation: CLI loads C + Trans key → Steganography Core reconstructs original B (or A)

##### Architectural Patterns & Principles
- Separation of Concerns: I/O, Core Logic, CLI/Examples
- Plug-in–style methods: easily add new bit-plane combination methods
- Data flow is strictly linear/streaming: frame → bit-plane → merge → output

##### Essential Elements
- Version info or key config file format as a note off to the side

- Clearly demarcates each layer of your steganography tool
- Illustrates the three combination methods as plug-in modules
- Highlights how “Combine” and “Trans” operations share the same core logic
- Allows new contributors to quickly see where to extend or modify behavior
- Shows dependencies on external tools (FFmpeg) and libraries (OpenCV)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Layer"
        IMG["img_combine.py"]:::cli
        VID["video_combine.py"]:::cli
        EX["example.py"]:::cli
        TEST["影片測試.py"]:::cli
    end

    subgraph "File I/O Layer"
        IO_IMG["Image I/O\n(JPEG/PNG→array)"]:::io
        IO_VID["Video I/O\n(MP4→frames→AVI)"]:::io
    end

    subgraph "Stego Core"
        EXTR["Bit-Plane Extractor"]:::core
        SEL["Method Selector\n(method1/2/3)"]:::core
        MERG["Bit-Plane Merger"]:::core
        COMP["Compressor/\nDecompressor"]:::core
    end

    TRANS["Trans Key Manager"]:::trans

    subgraph "Output Writer"
        OUT_MEDIA["C Output\n(media file)"]:::output
        OUT_KEY["Trans Key File"]:::output
    end

    subgraph "Sample Data"
        S1["video1.mp4"]:::data
        S2["video2.mp4"]:::data
    end

    subgraph "Tests/Examples"
        TESTBOX["Usage Tests"]:::cli
    end

    EX --> IMG
    EX --> VID
    TEST --> IMG
    TEST --> VID

    IMG -->|"reads A/B"| IO_IMG
    VID -->|"reads A/B"| IO_VID

    S1 --> IO_VID
    S2 --> IO_VID

    IO_IMG -->|"raw frames"| EXTR
    IO_VID -->|"raw frames"| EXTR

    EXTR -->|"bit-plane data"| SEL
    SEL -->|"selected planes"| MERG
    MERG -->|"merged planes"| COMP
    COMP -->|"C file data"| OUT_MEDIA
    COMP -->|"trans rules"| OUT_KEY

    OUT_MEDIA -.->|"C file + key"| TRANS
    TRANS -->|"reconstruct B/A"| EXTR

    classDef cli fill:#cce5ff,stroke:#004085,color:#004085;
    classDef io fill:#d4edda,stroke:#155724,color:#155724;
    classDef core fill:#fff3cd,stroke:#856404,color:#856404;
    classDef trans fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef output fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef data fill:#d1ecf1,stroke:#0c5460,color:#0c5460;

    click IMG "https://github.com/happy95059/video_combine/blob/main/code/img_combine.py"
    click VID "https://github.com/happy95059/video_combine/blob/main/code/video_combine.py"
    click EX "https://github.com/happy95059/video_combine/blob/main/code/example.py"
    click TEST "https://github.com/happy95059/video_combine/blob/main/code/影片測試.py"
    click S1 "https://github.com/happy95059/video_combine/blob/main/data/video1.mp4"
    click S2 "https://github.com/happy95059/video_combine/blob/main/data/video2.mp4"
    click OUT_MEDIA "https://github.com/happy95059/video_combine/blob/main/data/video_combine.avi"
    click OUT_KEY "https://github.com/happy95059/video_combine/blob/main/data/video_trans.avi"
```
