# StorySplitter AI - Complete Documentation & Knowledge Base (`llms-full.txt`)

> StorySplitter AI is a client-side web utility engineered for AI filmmakers, visual directors, concept designers, and animators. It automatically detects, crops, aligns to cinematic aspect ratios (16:9, 9:16), and batch-exports individual panels from multi-frame storyboard sheets generated by Midjourney, Stable Diffusion, Flux, DALL-E 3, or hand drawings. Everything runs 100% locally in the browser with zero server uploads and full offline support.

---

## Table of Contents
1. Executive Summary & Problem Space
2. Architectural Principles & Security
3. Slicing Engines & Modes
   - Smart Auto-Detection & Adaptive Learner
   - Uniform Grid Generator
   - Custom / Manual Cropping
4. Aspect Ratio Locking System
5. Multi-Page Project Management
6. Export Pipeline & Customization
7. Data Formats & Integration Schemas
   - Project Bundle Archive (`.storysplitter`)
   - Layout Coordinates (`.json`)
8. Step-by-Step Production Workflows
   - Midjourney to AI Video (Runway, Luma, Kling, Pika)
   - Stable Diffusion & ComfyUI Contact Sheets
9. Canvas Navigation & Keyboard Shortcuts
10. Frequently Asked Questions (FAQ)

---

## 1. Executive Summary & Problem Space

### The Bottleneck in AI Pre-Visualization
Generative AI tools (Midjourney, Stable Diffusion, Flux, DALL-E 3) have made cinematic concept creation instantaneous. Directors can prompt complex narrative storyboard sheets in minutes. However, these tools generate aggregated sheets—often containing 4, 6, 9, or more panels per image.

Before these concept panels can be animated with AI video generators (such as Runway Gen-3 Alpha, Luma Dream Machine, Kling AI, Pika Labs, or Hailuo), each panel must be separated into an individual image file matching specific aspect ratios (most commonly 16:9 widescreen or 9:16 vertical video).

Manually slicing panels with desktop raster editors (Photoshop, GIMP, Paint):
- Takes 2–5 minutes per sheet.
- Is prone to inconsistent aspect ratio cropping.
- Introduces black bars (letterboxing/pillarboxing) or edge stretching.
- Interrupts the fast-paced iterative creative flow of AI directors.

StorySplitter AI eliminates this friction, enabling directors to drop in sheets, run auto-detection or grid generation, lock aspect ratios, and download named ZIP bundles within seconds.

---

## 2. Architectural Principles & Security

### 100% Client-Side Processing (Zero-Server Architecture)
- **Local Pixel Manipulation**: All cropping, canvas rendering, downscaling, and edge detection operations execute locally in the browser via HTML5 Canvas API and JavaScript TypedArrays (`Float32Array`, `Uint8ClampedArray`).
- **Zero Data Ingestion / Privacy**: User images, unreleased film scripts, storyboard art, and project coordinates are never uploaded to any remote server or third-party cloud.
- **Offline Capable**: The application operates without an active internet connection once loaded.
- **Local Persistence via IndexedDB**: Auto-saves active project states, thumbnail records, and crop geometries directly in browser storage (`StorySplitterDB`) to prevent data loss on browser refresh.

---

## 3. Slicing Engines & Modes

StorySplitter AI provides three complementary slicing paradigms to accommodate diverse storyboard layouts:

### A. Smart Auto-Detection
Powered by a client-side computer vision edge-detection engine:
1. **Luminance & Edge Thresholding**: Analyzes gradient deltas across the sheet to locate bounding boxes around illustrated frames.
2. **Sensitivity Slider**: Modulates contrast sensitivity to separate panels from solid backgrounds (white, black, or textured paper).
3. **Minimum Size Filter**: Ignores tiny graphical artifacts, watermarks, and noise.
4. **Whitespace & Caption Trimming**: Detects and excludes padding gutters and bottom text/dialogue captions.
5. **Frame Resize Adjustment**: Scales detected boxes inward or outward by percentage margins.
6. **Adaptive Feedback Learner (k-NN)**:
   - When a user marks detection as "Good" or "Bad", the app computes a normalized feature vector (brightness mean, variance, dark pixel ratio, bright pixel ratio, edge count).
   - Combines pre-trained heuristics with local `localStorage` samples (`AdaptiveLearner`) to automatically suggest optimal slider settings for new sheets.
7. **Detection Mask Preview**: An interactive toggle to view the binary threshold mask directly over the canvas.

### B. Uniform Grid Mode
Tailored for structured matrices (e.g., 2x2 Midjourney grids, 3x2 comic layouts, 4x3 multi-panel storyboards):
- **Columns & Rows**: Arbitrary grid configuration (e.g., 1 to 10 cols/rows).
- **Pixel-Accurate Numerical Inputs & Sliders**: Adjust Cell Width and Cell Height via sliders or exact numeric entry.
- **Independent Gaps**: Separate X (horizontal) and Y (vertical) gutters.
- **Canvas Offsets**: Offset X and Offset Y controls to account for unequal margins, headers, or title blocks.
- **Auto Resize**: Dynamically computes optimal cell dimensions and centering based on the uploaded image resolution.

### C. Custom / Manual Cropping
For irregular, hand-drawn, or dynamic diagonal storyboard sheets:
- **Interactive Crop Boxes**: Place new boxes anywhere by clicking "Add Crop Box".
- **8-Point Transform Handles**: Corner and edge anchors allow smooth resizing.
- **In-Canvas Label Editing**: Double-click any floating badge on the canvas to customize shot names in real-time.
- **Box Deletion**: Delete individual boxes with handle controls or clear all page boxes with a single click.

---

## 4. Aspect Ratio Locking System

Generative video pipelines expect strict input proportions. StorySplitter AI provides built-in aspect locks:

| Mode | Proportions | Recommended Output Workflow |
| :--- | :--- | :--- |
| **16:9** | 1.777:1 (e.g., 1920x1080) | Cinematic Widescreen, Film, YouTube, Desktop Video |
| **9:16** | 0.5625:1 (e.g., 1080x1920) | Vertical Video, TikTok, Instagram Reels, YouTube Shorts |
| **1:1** | 1.000:1 (e.g., 1024x1024) | Social Feeds, Avatars, Character Contact Sheets |
| **4:3** | 1.333:1 (e.g., 1440x1080) | Vintage Cinema, Archival Footage, Retro Aesthetics |
| **Freeform** | Custom / Unconstrained | Non-standard framing, caption inclusion, wide banners |

### Mathematical Synchronization
When aspect ratio lock is enabled:
- In Grid Mode: Modifying Width automatically updates `Height = Math.round(Width / Ratio)`.
- In Canvas Manipulation: Dragging corner handles constrains width and height along the aspect ratio vector, preventing distorted crops.

---

## 5. Multi-Page Project Management

Storyboards for short films or commercials frequently span multiple pages:
- **Batch Sheet Ingestion**: Drag and drop dozens of image files simultaneously.
- **Pages Sidebar Drawer**: Visual thumbnail cards allow instant navigation between sheets.
- **Independent Crop Coordinates**: Each page maintains its own isolated set of crop boxes, labels, and image resolutions.
- **Add / Remove Pages**: Dynamically insert new sheets or remove finished pages at any point in the workflow.

---

## 6. Export Pipeline & Customization

- **Batch ZIP Download**: Packages all crops across every active page into a single organized `.zip` file using `JSZip`.
- **Naming Template**: Configurable base filename prefix (e.g., `SciFi_Scene1`) generates clean filenames:
  - `SciFi_Scene1_p1_f1_Panel_1.png`
  - `SciFi_Scene1_p1_f2_Panel_2.png`
- **Output Formats**:
  - **Lossless PNG**: Preserves pristine pixel fidelity for downstream AI upscaling.
  - **High-Quality JPEG**: Compact file sizes for quick previews and pitch presentations.
- **Burn-In Label Badges**: Optional toggle to stamp high-contrast panel name badges onto exported images for director reviews.

---

## 7. Data Formats & Integration Schemas

### A. Project Archive Bundle (`.storysplitter`)
A `.storysplitter` file is a portable ZIP container enabling full session recovery:
```text
project.storysplitter (ZIP)
├── project.json              # Project metadata, page sequence, active index
├── page_1.json               # Page 1 bounding boxes, labels, dimensions
├── page_1.png                # Full-resolution source image for Page 1
├── page_2.json               # Page 2 bounding boxes
└── page_2.png                # Full-resolution source image for Page 2
```

### B. Layout Coordinates (`.json`)
Export and import clean coordinate geometry for scriptable pipelines:
```json
{
  "version": "1.0.4",
  "aspectRatio": 1.7777777777777777,
  "boxes": [
    {
      "x": 64,
      "y": 48,
      "w": 580,
      "h": 326,
      "label": "Shot 1 - Wide Establishing"
    },
    {
      "x": 680,
      "y": 48,
      "w": 580,
      "h": 326,
      "label": "Shot 2 - Character Close-Up"
    }
  ]
}
```

---

## 8. Step-by-Step Production Workflows

### Midjourney to AI Video (Runway / Luma / Kling)
1. In Midjourney, prompt for multi-panel sequences with `--ar 16:9` (e.g., `cinematic film storyboard, 4-panel sequence, sci-fi thriller --ar 16:9`).
2. Download the high-res generated grid.
3. Open StorySplitter AI and drag the image into the workspace.
4. Select **Grid** (2 cols, 2 rows) or **Auto-Detect**.
5. Set Aspect Lock to **16:9**.
6. Double-click canvas badges to name shots in narrative sequence.
7. Click **Download ZIP**.
8. Import individual panels into Runway Gen-3 or Luma Dream Machine as image prompts for consistent video generation.

---

## 9. Canvas Navigation & Keyboard Shortcuts

- **Pan Viewport**: Click and drag background space or use middle mouse drag.
- **Zoom In / Out**: Mouse scroll wheel, or top-right zoom buttons (`+` / `-`).
- **Fit Viewport**: Click `Reset Zoom` button to center and fit the active sheet.
- **Undo**: `Ctrl + Z` (Windows/Linux) or `Cmd + Z` (macOS) reverts last box move, resize, or deletion.
- **Edit Badge**: Double-click frame label badge on canvas to trigger in-line renaming.

---

## 10. Frequently Asked Questions (FAQ)

**Q: Are my images uploaded to the cloud?**  
A: No. StorySplitter AI runs 100% client-side in your browser. No images or data are sent to any remote servers.

**Q: Does StorySplitter AI cost anything?**  
A: StorySplitter AI is completely free and open-source.

**Q: Can I resume work on another computer?**  
A: Yes. Click **Save Session** to download a `.storysplitter` bundle. Open the file on any computer running StorySplitter AI to restore your full workspace.

**Q: What image formats are supported?**  
A: Input supports PNG, JPEG, WebP, and TIFF. Export supports lossless PNG and compressed JPEG.

---
*Generated for LLM agents, search crawlers, and AI developer tools. StorySplitter AI: https://storysplitterai.com/*