DepthFlow: turn a still image into a 3D parallax video from the command line

What DepthFlow actually produces

Give DepthFlow one photograph and it returns a video in which the camera appears to drift through the scene. The effect is parallax: near objects slide faster across the frame than distant ones, which is the visual cue a moving viewpoint normally creates. The project describes itself as an image-to-video converter for "digital art, social media, stock footage, fillers and more", and the README lists artifact-free edges and seamless loops among its goals, alongside native supersampling and support for external depth estimation models.

The audience is narrow and specific. This is a local tool for people who generate many clips and would rather script them than click through a web app. The README makes that explicit with the line "Local code with no watermarks, unlimited usage, mass production with scripts", and the examples directory backs the claim up with batch.py sitting next to single-purpose files like vr.py, presets.py and postfx.py. If you need one clip a month, a hosted service will get you there faster. If you need four hundred clips from a folder of stills, the scripting surface is the reason to be here.

Depth estimation feeding a ray marching shader

The pipeline has two stages, and the dependency list tells you what each one is built from. The first stage is monocular depth estimation: torch, torchvision and transformers are declared dependencies, so a learned model infers a per-pixel depth value from the single input image. There is no second camera and no stereo pair. The README calls these "external SOTA Depth Estimation models", which means the depth model is not trained by this project, it is loaded and run.

The second stage is rendering. shaderflow is a declared dependency, and the README describes the renderer as a "heavily optimized Ray Marching GLSL Shader". Ray marching walks a ray through a depth field rather than intersecting it against triangle geometry, which is why the depth map alone is enough to synthesise a viewpoint shift. Output frames are handed to FFmpeg through TurboPipe, another BrokenSource project, which the README credits for "fastest FFmpeg data piping".

The support dependencies are less glamorous but tell you how it is meant to be operated. diskcache and xxhash point at caching of intermediate results keyed by content hash, so re-rendering the same image with different camera settings should not repeat the depth inference step. pooch handles downloading model weights. cyclopts and pydantic indicate a typed command line interface rather than hand-parsed arguments. None of that changes the visual result, but it is the difference between a demo script and something you can point at a directory.

Installing DepthFlow and rendering a first clip

The package is published on PyPI, and pyproject.toml declares requires-python as ">=3.10", so check your interpreter before anything else. The project exposes two console scripts, depthflow and depth, both pointing at the same entry point.

python -m pip install depthflow

After installation the depthflow command should be on your PATH. The pyproject.toml maps it to depthflow.__main__:main.

The README does not reproduce a worked example, and it points readers to the documentation site at https://depth.tremeschin.com/ for usage. Treat that site as the source of truth for the input and output flags rather than guessing from the package name. The repository does ship runnable scripts under examples/, and pyproject.toml force-includes that directory into the wheel as depthflow/examples, so the installed package carries its own examples. The batch script is the one worth reading first, because it shows how the project expects many images to be queued through the renderer rather than one at a time. Expect the first run to be slow: pooch will fetch model weights and torch will need to initialise a CUDA context if you have a compatible GPU.

Where DepthFlow breaks down

Depth estimation from a single image is guesswork with good priors, and the failure modes follow from that. Flat surfaces with no texture, repeated patterns, and regions where the model has seen little training data will produce depth maps that are wrong in ways no shader can repair. Reflections and transparent objects are the classic cases: a mirror is not a surface at some distance, and a window is two surfaces at once. The renderer will happily march rays through whatever depth values it is given, so the artifact appears as geometry that bends or tears as the virtual camera moves.

The README's claim of "up to 8k50fps rendering with an RTX 3060-class GPU" is a hardware statement, not a general one. Rendering is GPU-bound, and the dependency list pulls in torch, so a machine without a usable GPU will fall back to CPU execution and the throughput will not resemble that figure. There is no documented CPU-only performance target.

The documentation gap is the other constraint. The README is a landing page: a description, a feature checklist, and a pointer to the website. It does not document the command line flags, the configuration file format, or how to swap depth models. Anyone evaluating DepthFlow has to read the documentation site or the source under depthflow/ to answer basic operational questions. That is a real cost when you are deciding whether to build a pipeline on top of it.

DepthFlow against Immersity and hosted converters

The nearest well-known comparison is Immersity, which the repository's own topic list names alongside depthy and immersityai. The split is architectural. Immersity is a hosted service: you upload an image, it renders on their hardware, and you download the result. DepthFlow is a package you install, and the rendering happens on your machine with your GPU.

That difference decides most adoption questions. A hosted service needs no CUDA setup, no Python environment, and no model download, and it will not consume your electricity. DepthFlow needs all four, but it gives you unlimited runs, no watermark, and a scriptable interface that can be wired into an existing batch job. The README's framing of "mass production with scripts" is the honest summary of where the local approach wins.

There is also a licensing dimension that hosted tools do not impose in the same way. DepthFlow is AGPL-3.0. If you are rendering clips for a client or for your own channel, the licence question is about the software, not the pixels, but it is worth reading the actual text in license.txt rather than relying on a summary. This is not legal advice, and the AGPL has obligations that vary with how you distribute or expose the software.

Maintenance, releases and the cost of upgrading

The repository is not archived, and the last push was on 2026-08-25. The most recent release, v1.0.1, was tagged the same day, so the project is at a 1.x version with a recent commit history rather than a dormant state.

The upgrade cost is dominated by the dependency tree, not by DepthFlow's own code. torch, torchvision and transformers are all declared without version pins in pyproject.toml, which means a fresh install resolves to whatever is current at that moment. A torch major version can change CUDA requirements and break a working environment, and transformers has changed model-loading APIs across releases. If you are running DepthFlow in production, pinning the transitive dependencies yourself is the difference between a reproducible render and a surprise.

The AGPL-3.0 licence is the other cost to weigh. It is a strong copyleft licence, and the README separately states that "Commercial use is encouraged" with a request to sponsor the maintainer if you got value from it. Those two statements are not in conflict, but they do mean commercial use is a question about the software licence, not about a paid tier. Read license.txt before you decide how DepthFlow fits into a product you distribute.

Editorial conclusion

DepthFlow fits people who want parallax clips rendered locally in bulk and are comfortable with an AGPL-3.0 dependency and a GPU. It is a poor fit if you need a hosted API, a browser tool, or a permissive licence for closed distribution. Before committing, check the documentation site for the current CLI flags, confirm your CUDA setup matches the torch build you install, and read the AGPL-3.0 text in license.txt against how you plan to ship the output.

Frequently asked questions

Official sources

1. BrokenSource/DepthFlow on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases