explaingit

lllyasviel/toondecompose

Analysis updated 2026-07-09 · repo last pushed 2023-08-31

130PythonAudience · developerComplexity · 4/5DormantSetup · hard

TLDR

ToonDecompose automatically breaks cartoon animations into separate moving layers called sprites. Give it animation frames and it extracts each object as its own image sequence with movement data, no manual masking required.

Mindmap

mindmap
  root((repo))
    What it does
      Breaks animation into sprites
      Automatic no manual masking
      Outputs image sequences
      Outputs movement data
    How it works
      Optical flow for pixel motion
      Analyzes movement boundaries
      Estimates sprite transforms
      Refines all layers together
    Requirements
      CUDA GPU required
      No CPU fallback
      GPU model affects results
    Use cases
      Edit animation layers
      Reuse sprite components
      Game development assets
    Audience
      Animators
      Game developers
      Researchers
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

What do people build with it?

USE CASE 1

Separate a running character from the background in a cartoon clip for independent editing or reuse

USE CASE 2

Extract moving objects from an existing animation as reusable sprite layers for game development

USE CASE 3

Pull individual elements out of a complex animation for research on motion decomposition

What is it built with?

PythonCUDAOptical Flow

How does it compare?

lllyasviel/toondecomposeredbyte1337/credspyvibeforge1111/vibeship-scanner
Stars130132123
LanguagePythonPythonPython
Last pushed2023-08-312026-03-04
MaintenanceDormantMaintained
Setup difficultyhardeasyeasy
Complexity4/51/52/5
Audiencedeveloperops devopsvibe coder

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · hard Time to first run · 1h+

Requires a CUDA-enabled GPU, CPU-only mode does not work, and results may vary depending on your specific GPU model.

The explanation does not mention a license, so the usage terms are unclear.

In plain English

ToonDecompose takes a cartoon animation and automatically breaks it apart into separate moving pieces, called "sprites." You give it a sequence of frames from an animation and tell it how many objects or components you want. It gives you back each component as its own sequence of images, along with data describing how each one moves over time. The whole process is automatic, you don't need to manually outline or mask anything. The tool works in stages. First it figures out how every pixel moves between frames using a technique called optical flow. Then it analyzes those movement patterns to guess where the boundaries of each object are. After that, it estimates how each sprite shifts, rotates, or scales from frame to frame. Finally, it refines all of these estimates together to produce clean, separated sprite layers. The whole pipeline involves running several Python scripts in sequence, and processing a 78-frame clip takes roughly 40 minutes on a decent GPU. This would be useful for animators, game developers, or researchers who want to pull individual elements out of an existing animation, for example, separating a running character from the background so each layer can be edited, reused, or repositioned independently. The project includes a real test case using 78 frames from the anime "Violet Evergarden," chosen because it's a genuinely challenging clip with a character in fast motion. One notable aspect is that the results are sensitive to your GPU model. The author tested several cards and found that some produce identical results while others deviate, and the cause isn't fully understood. You need a CUDA-enabled GPU, CPU-only mode doesn't work. The methods behind the tool are described in a SIGGRAPH Asia 2022 paper by the same author, and the project is still being actively refined.

Copy-paste prompts

Prompt 1
I have a sequence of frames from a 2D cartoon animation. How do I use ToonDecompose to automatically separate the moving character from the background into individual sprite layers?
Prompt 2
I want to extract 3 moving components from an animation clip using ToonDecompose. What Python scripts do I run in sequence and how do I specify the number of objects?
Prompt 3
How do I set up and run ToonDecompose on my machine with a CUDA GPU? What are the steps from cloning the repo to getting separated sprite image sequences?
Prompt 4
Can ToonDecompose give me movement data describing how each extracted sprite shifts, rotates, or scales across frames? How do I access that transformation data?

Frequently asked questions

What is toondecompose?

ToonDecompose automatically breaks cartoon animations into separate moving layers called sprites. Give it animation frames and it extracts each object as its own image sequence with movement data, no manual masking required.

What language is toondecompose written in?

Mainly Python. The stack also includes Python, CUDA, Optical Flow.

Is toondecompose actively maintained?

Dormant — no commits in 2+ years (last push 2023-08-31).

What license does toondecompose use?

The explanation does not mention a license, so the usage terms are unclear.

How hard is toondecompose to set up?

Setup difficulty is rated hard, with roughly 1h+ to a first successful run.

Who is toondecompose for?

Mainly developer.

Open on GitHub → Explain another repo

This repo across BitVibe Labs

Verify against the repo before relying on details.