Scroll Animator Pro Modular (v1.09)

Scroll Animator Pro is a high-performance Python application engineered for generating professional-grade animation sequences from static images / text. Version 1.09 represents a Hybrid Hub-and-Spoke design that integrates a CustomTkinter GUI while maintaining a supported legacy Command Line Interface.

The system encapsulates complex image processing, mathematical compositing, transparency management, and multi-format video encoding (GIF, WebP, MP4) into a streamlined user experience.

---

Development Conventions

• Testing: See docs/testing.md for verification and coverage instructions.
• Additive Modularity: New effects should be implemented in separate mod_name.py files or added to existing relevant modules (mod_img_effects.py, mod_text_effects.py). No files > 500 lines allowed.

🚀 Exhaustive Feature Catalog

1. 📜 Scroll Animator

Transform any static image into a mathematically perfect infinite vertical loop.

• Seamless Tiling: Calculates the exact pixel offset required for a jump-free loop based on the source image's height.
• Directional Control: Supports both Upward (classic credits) and Downward (falling) scroll directions.
• Speed Control: interactive slider support for precise floating-point durations (e.g., 12.75s).
• Duration Lock: "Lock Total Duration" toggle standardized across all panels for consistent timing.
• Viewport Geometry:
  • Full Height: Output matches the source image dimensions.
  • Windowed Mode: Define a specific canvas height (e.g., 500px); the engine automatically handles tiling to ensure the viewport is fully populated during the scroll.

2. ✨ Sequence & Transition Engine

Orchestrate transitions between multiple image assets.

• Cross-Fade Logic: Implements smooth linear opacity interpolation between sequential images.
• Blur Dissolve (Cinematic): A dual-phase transition where the active image blurs out as the next image blurs in.
• Aspect Ratio Harmonization: Automatically detects mismatched resolutions. All secondary images are center-cropped and resized to match the dimensions of the primary image to prevent stretching or "letterboxing."
• Visual Rhythm Bar: A live GUI visualization showing the timing distribution between "Hold" and "Transition" phases across the animation cycle.
• Duration Lock: Standardized "Lock Total Duration" checkbox that auto-calculates hold/fade times to maintain a target loop length.
• Performance Guard: Real-time warnings when Blur intensity exceeds safe rendering thresholds to prevent system hang.

3. 🔦 Advanced Image Effects

• Spotlight Focus: Create a moving focus reveal effect.
• Interactive Placement: Set Start and End anchors directly on the preview canvas (Green = Start, Red = End).
• Precision Control: Fine-tune coordinates via numerical entry or swap them instantly with a single button.
• Live Sliders: Real-time control over Focus Size (10-1000px), Edge Softness (blur radius), and Duration.
• Smart Detection: Automatically toggles between Opaque Mode (dimmed/blurred photo backgrounds) and Transparent Mode (alpha-masking for text/logos).
• Duration Lock: Standardized locking across panel attributes.

4. ✍️ Text Studio (Modular Effects)

Generate high-resolution video assets directly from raw text strings.

• Precision Layout:
  • Bounding Box Centering: Calculates the visual bounding box of font glyphs for perfect centering.
  • Vertical Alignment: Anchor text to Top, Center, or Bottom with pixel-perfect precision.
• Smart Duration Sync: SmartDurationControl synchronizes Total Duration with Start/End Hold and Effect times.
• Precision Numeric Controls (Pro-Header): New header entry fields for exact float timing input (e.g., 1.25s) with focus-aware synchronization.
• Smart Font Management:
  • Improved Loading: Background "Pre-Warming" of the font picker popup at launch.
  • Disk Caching: Persistent fonts_cache.json for faster font discovery on startup.
  • Smart Renaming: Automated conversion of cryptic suffixes (e.g., bd -> Bold, z -> Bold Italic) with stem-safety logic.
  • Improve Font Type Support: Native rendering for .ttf, .otf, and .ttc font files.
  • Advanced Picker: Full system font browser with "Recent Fonts" history tracking.
• Feature-Rich Effects Gallery:
  • Particle Vortex: Text shatters into thousands of particles with quadratic acceleration and automatic reading-hold calculation.
  • Focus Pulse: Triangle-wave blur transition (Clear -> Max -> Clear) with configurable Peak Hold duration.
  • Classic Typewriter: Character-by-character reveal with synchronous blinking cursor and smart duration sync.
  • Linear Wipe: Smooth gradient-based reveal moving horizontally with optional Seamless Fade Out.
• Production Safety Tools:
  • Pixel-Tight Auto Dimensions: Automatic canvas sizing with optimized padding strategies based on effect type.
  • Overflow Detection: Real-time warning if contents exceed the selected canvas width.

5. 🖱️ Interactivity & UI

• Sidebar State Persistence: The GUI remembers if the sidebar was collapsed or expanded between sessions to maintain user workspace preferences.
• Universal Drop Zones: Drag images directly onto load boxes or the Sequence Asset Rack.
• Smart Validation: Automatically ignores non-image files and shortcuts to prevent crashes.

---

🏗️ Technical Architecture

1. Hybrid Modular Design

The codebase is partitioned into a strict src/ package structure:

• main.py: Entry point with hybrid routing.
• src/gui/: CustomTkinter implementation with modular panels/ and components/.
• src/logic/: Decoupled "Spokes" for core animation algorithms.
• src/utils/: Shared toolset including utils_io.py for RIFF-level encoding and utils_system.py for dependency management.

2. WebP Rendering Improved Pipeline

The application implements RIFF-level frame memoization:

• Redundancy Detection: Identifies consecutive identical frames (common during "Hold" phases).
• Manual RIFF Assembly: Encodes unique frames once and assembles them into ANMF chunks with extended durations, significantly reducing file sizes without quality loss.

3. Render Cancellation (WIP, Limited by libraries)

• CancellationToken: Deep-propagation into every frame-generation loop for near-instant termination.
• Atomic IO Protection: Disables the "Stop" button during final disk writes to prevent file corruption.

---

⚙️ Performance & Resource Management

Metric	Specification	Rationale
Max Safe Resolution	1280 x 720	Caps RAM usage to prevent MemoryError during frame buffering.
Frame Rates	30 FPS / 60 FPS	User-selectable. 60 FPS provides smoother motion but doubles RAM footprint.
Dimension Guard	Even Pixels Only	Ensures compatibility with H.264 (MP4) codecs which fail on odd-numbered resolutions.
Memory Buffer	List Pre-allocation	Frames are held as PIL objects in RAM before encoding to maximize IO throughput.

---

🛠️ Installation & Setup

Prerequisites

• Python: 3.10 or higher.
• Dependencies: customtkinter, Pillow, opencv-python, numpy, tkinterdnd2.

Execution

1. CLI/GUI Via Terminal: **CLI will prompt for loading gui or cli

   python main.py

   (The CLI and Exe should automatically detect any missing libraries and offer to install them via pip if desired)

2. Launch via Executable: run ScrollAnimatorPro.exe

---

🧪 Development & Quality Assurance

Modular Test Suite

The project maintains high logical coverage via a refined pytest architecture:

• Master Runner: Execute python test/verification_suite.py for a full system health check.
• Unit Tests (test/unit/): Verify individual math utilities, config parsing, and image Standardization logic.
• Integration Tests (test/integration/): Validates the end-to-end generation of GIF, WebP, and MP4 artifacts for every effect module.

Build System

For distribution, use the PowerShell build script:

./build_exe.ps1

This script automates PyInstaller bundling, handles customtkinter asset injection, and produces a single-file Windows executable in the dist/ folder.

---

⚠️ Known Behaviors & Technical Notes

• MP4 Transparency: H.264 does not support alpha channels. The application allows users to manually select a background color (Black or White) for compositing transparent assets.
• GIF Transparency: Limited to 1-bit alpha. Software with "Soft Edges" (antialiasing) may show a white fringe. Use the "Snap Alpha" setting to mitigate this.
• OpenH264 Warning: On some Windows systems, OpenCV may log a warning about openh264-1.8.0-win64.dll. The application automatically falls back to mp4v codec, ensuring successful output.