VectorFlow

A local Windows desktop app that automatically redraws a video as animated cubic Bézier curves. Choose a video, preview the trace on one frame, convert the clip, and export the result. No manual tracing is required. The original concept is in idea.md.

The app has three places: Home (drop a video, pick a starting look, reopen a project), the Studio (watch, compare and inspect the curves), and the Editor (clean up paths and replace moving text or artwork). Both light and dark themes use graph-paper surfaces with amber and sage accents; switch with the sun/moon button in the top-right corner.

On Home, drag any of the four points in the Bézier playground to reshape the curve and see its coordinates. Double-click to reset it. This illustration is separate from converted video paths.

Start

Install 64-bit Python 3.11 through 3.14 with Python on PATH, then run setup.bat once. Python 3.11 is the tested version. Setup requires internet access, downloads the pinned dependencies (including an FFmpeg executable), and checks runtime imports, dependency consistency, and FFmpeg availability. It also supports the Windows py launcher when python is unavailable. When setup reports Ready, double-click Start VectorFlow.bat. Processing runs locally and does not upload the video.

For automated installation, run setup.bat --unattended to skip the final keypress. If setup fails, review the error and rerun it after fixing the Python installation or connection. Supported dependency wheels must be available for your Python version; setup does not compile packages from source.

The UI uses PySide6-Essentials, which supplies every Qt module used by VectorFlow, including SVG support and the UI test helpers. The larger Qt Addons package is not required. If Windows reports a path-too-long installation error, move the project to a shorter folder path and rerun setup. For missing runtime DLLs, install Microsoft's current Visual C++ x64 Redistributable.

python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
.venv\Scripts\python.exe -m vectorflow.app

Use

1. Choose or drop a video on Home (several at once queue up). Pick a starting look first if you like: Line art, Poster color or Detailed. The studio opens on the first frame.
2. Tune the trace settings in the right-hand panel: Outline or Filled color, Detail, Long edge, Frame rate and, for filled tracing, the number of Colors. Tracked regions lets you draw include/exclude boxes on the first frame; they follow motion during conversion. Sizes describe the longest edge, with aspect ratio preserved and no upscaling.
3. Click Preview this frame (P) to trace just the current frame in a second or two. The stage switches to Split so you can drag the divider between the source and the vectors. Adjust and preview again until it looks right.
4. Click Convert video. The stage updates as frames finish. With videos waiting in the queue, the button reads Convert all and converts them one after another with the same settings. Cancel at any time; completed frames remain, and Resume conversion (in the studio or on Home) continues where it stopped.
5. Switch views with 1 Source, 2 Vectors, 3 Split and 4 Mapping, then play or scrub the timeline. The timeline shows converted frames, replacement ranges (with lost-tracking points), saved edits (◆) and your in/out range. Watch the mapping (M) reveals the frame curve by curve.
6. Click any line on the stage to inspect its curve. The Curve panel shows x(t) and y(t) in image coordinates; Copy for Desmos, Copy LaTeX and Copy every curve in this frame for Desmos put them on the clipboard. Scroll to zoom, drag to pan, double-click to fit. The onion-skin button shows the previous frame's curves.
7. Click Edit (E) for the editor, and Export (Ctrl+E) for every output format.

Keyboard shortcuts

Studio		Editor
Space	Play / pause	V, T, Shift+I	Cleanup, text and artwork tools
← / → (Shift: 10)	Previous / next frame	[ / ]	Previous / next curve
1–4	Source, Vectors, Split, Mapping	Enter	Save shape
I / O / X	Set in, set out, clear range	Delete	Delete path
P	Preview this frame	Ctrl+Z / Ctrl+Shift+Z	Undo / redo
M	Watch the mapping	I / O	Replacement range
L / Shift+O	Loop / onion skin	+ / − / F	Zoom in, zoom out, fit
+ / − / 0	Zoom in, zoom out, fit	Esc	Back to the studio
Ctrl+N / Ctrl+O / Ctrl+H	Choose video, open project, Home

Editing workspace

The editor opens inside the main window. A tool rail on the left switches between cleanup, text and artwork; the canvas zooms with the scroll wheel and pans by dragging empty space or with the middle button; Done (Esc) returns to the studio.

• Cleanup: pick a path on the canvas or in the Paths list (filter by track number or fill color). Step through its curves with [ and ], drag the four handles, then Save shape. Simplify path refits it at the chosen tolerance, and shows how many curves remain before you apply it. Delete path removes unwanted geometry. Apply edits to chooses This frame or the Whole track; whole-track edits are stored in the path's anchor coordinates and follow its recorded motion. History lists every edit: undo, redo, or click a step to go back to it. Hole contours are preserved but do not have independent handles yet.
• Replace text: drag a box around the original text on the frame (this frame becomes the start), set the end with End here or O, type your words, pick a color (or sample one from the frame with the eyedropper), then Track & replace text. Text is fitted into the region and follows its motion. No OCR is needed: you choose the region.
• Replace artwork: mark the object the same way, choose PNG, WebP, JPEG or SVG artwork, and Track & replace object. Aspect ratio and transparency are preserved; SVG artwork is rasterized for compositing and copied into the project.
• Replacements are listed under the paths: hide one to compare, or delete it on its own.

Export

One export sheet covers every format, with a live preview:

• Video: MP4 (keeps available source audio), ProRes 4444 with alpha (video only), GIF loop.
• Vector: animated SVG, SVG frame sequence (ZIP), Lottie JSON, and raw curve data JSON.
• Images: transparent PNG sequence (ZIP), the current frame as SVG or PNG, and Desmos expressions for the current frame.

Options: Vectors only or With replacements (composited over the original footage), outline stroke color and width, background (transparent, dark, paper or a custom color), and range (whole clip, or the in/out range from the timeline). Cleanup edits are always resolved into exports. SVG composites embed a reconstructed raster background plus editable text or embedded artwork, so they are not entirely vector. Lottie exports contain vectors only. Exports are saved in the project's exports/ folder unless you choose another location.

Old projects remain readable. Reconvert an old video to create the path IDs needed for whole-track edits; those edits are disabled for legacy frames without IDs. Text/artwork tracking works from saved source previews even on older projects.

Projects

Projects are stored in outputs/<video-name>-<timestamp>-<id>/ and listed on Home, newest first, with thumbnails, length, status and disk size. Click one to open it, use Resume on an unfinished conversion, or right-click for Show in Explorer, Free up space and Delete project. Open project… opens a project.json from anywhere.

Free up space deletes the rendered PNG frames, which are the largest regenerable files. Vectors, source previews, edits and replacements are kept, and exports render frames again when needed.

Each project contains:

• project.json: source, dimensions, timing, settings, completion state.
• frames/000000.json: cubic control points, stable path IDs, motion transforms, region tracking, and fill styles.
• frames/000000.svg: scalable vector drawing; open in a browser or vector editor.
• frames/000000.png: rendered vectors, reused for MP4 encoding when nothing changed (removable with Free up space).
• frames/000000.jpg: source preview for the overlay.
• edits.json and edits-redo.json: reversible cleanup operations and the redo branch; original frame data is not overwritten.
• replacements.json and assets/: replacement timing, motion, visibility, and copied artwork/text assets.
• exports/: default location for exports.

Raw SVG/PNG files in frames/ represent the initial conversion. Use Export to include later edits and replacements.

Demo outputs and source videos are not included in this repository. Use a video you own or have permission to use.

How it works

OpenCV decodes frames at the requested output rate. Nearly stationary pixels are smoothed. Optical flow and conservative shape matching assign persistent path IDs; confident fits reuse curve topology. Tracked selections use affine motion estimation with local image-alignment refinement. Uncertain paths receive new IDs, and lost selected regions stop tracing instead of jumping to unrelated subjects. Filled-color mode learns a distinct palette from samples across the clip, then fits closed contours and holes. Pure vector SVGs contain actual C path commands.

The desktop UI uses PySide6. Conversion and FFmpeg export run outside the UI thread. Frames are written incrementally to disk rather than holding the entire video in memory. Playback follows elapsed time at the chosen speed, skipping display frames if necessary to avoid slowing the animation. A resumed conversion rebuilds the path, region and palette state from the last saved frame, so track IDs continue across the resume point.

References: OpenCV contour extraction, OpenCV optical flow, Pillow drawing API.

Current limits

• Tracking is geometric, not semantic character recognition. Fast deformation, occlusion, low texture, or cuts can break tracks. Lost regions need a newly marked segment; automatic reacquisition and body-pose/expression transfer are not implemented.
• Selected rectangles are not pixel-perfect subject segmentation. A moving box can include some background. If an exclusion track is lost, tracing pauses to avoid accidentally including excluded content.
• Color tracing is palette-based stylization. Small details and gradients can be lost, and fine contour topology can still change. It does not reproduce hand-curated Desmos artwork exactly.
• Replacement removes the marked region with local inpainting. Textured backgrounds may smear. Replacements do not pass behind foreground occluders automatically. Imported artwork follows affine motion rather than articulated poses.
• Replacements currently composite over the original source previews. To export pure transparent vectors, choose Vectors only in the export sheet. Replacement placement, font, and artwork are set when creating the operation; delete and recreate it to change those settings.
• Variable-frame-rate sources are treated using their reported nominal frame rate. Output timing is quantized to output frames; unusual variable-rate files may need conversion to constant frame rate first.
• Large or long videos can take time and substantial disk space because previews and vector frames are retained. Use Free up space or Delete project on Home when finished.
• Desmos support is copy/paste and text export; there is no live Desmos sync. No freehand pen tool, installer executable, or automatic updates are included.

License

VectorFlow's code and documentation are available under the MIT License. Copyright (c) 2026 Adwait Tagalpallewar. Third-party dependencies retain their own licenses; see Third-party notices. Source videos and generated media are not licensed by this repository.

Development

.venv\Scripts\python.exe -m unittest discover -s tests -v
.venv\Scripts\python.exe -m vectorflow.pipeline "input.mp4" "outputs/my-project" --seconds 3 --export
.venv\Scripts\python.exe tests/verify_studio.py

verify_studio.py builds a demo project and saves screenshots of Home, the studio, every editor tool and the export sheet to test-output/.

Omit --seconds to convert the whole video. The output project directory must not already exist. Source files are never modified. Feature commits separate the concept, curve fitting, conversion/export, UI, and subsequent refinements.