An automated film recovery tool for sixteenmm.org
Fewer artefacts
Change how the outline overlay is generated.
A number of small tweaks that greatly increase the level of detail we can show.



You can also use your local clone with git send-email.


An automated film recovery tool for sixteenmm.org.


At SIXTEENmm we often come across films we want in our collection, but the quality, due to age and rarity of the film, is often degraded to the point where watching is a painful experience except for those who can deeply appreciate the efforts of the original archivist.

This is a research project to not necessarily recover the original film, but rather to take a bad quality film and turn it into something that can be enjoyably watched, which may have a new and distinctive style to it.

This project began when we were attempting to restore what is generally considered to be the first full length film: "The Story of the Kelly Gang". A silent film produced in 1906, that covered the cultural icon of Ned Kelly, a bushranger often seen as a hero in Australian culture. Of the original film, which lasted over an hour, only twenty minutes or so remain, but the footage does include the final climax of the film.

Heavy inspiration was taken from the amazing "Trace Bitmap" feature of Inkscape, developed first by Bob Jamison. We perform a similar dance around quantization, but with less finesse and more hack. (However, no code was re-used.)


Issue Tracker

The project is ongoing, and usually requires heavy tweaking to match the footage one is trying to recover. This can be a very time-intensive process, and may require multiple renderings only to conclude it doesn't yet work for that particular piece of footage.

The project can sometimes work fairly well for black and white films. However, color films tend to turn out just "ok".

Example Image, dubious quality

Performance is currently one of the main development goals, and as such the project is frequently reworked towards this goal. This may include breaking changes.

Note: Once the project has reached a significant level of maturity, we will probably begin semantic versioning, making these breaking changes less painful. Until then, git hash is your best bet for pinning.

Note: During conversion, you may need more hard drive space than your /tmp mount has available. This is because every frame is turned into multiple bitmap files, which are completely uncompressed and highly ineffecient as a format. An argument to supply a different directory is available, preferrably pointing to an SSD with 300-400Gb free (just an estimate - it depends on the frame count and resolution of the film you are processing).

Current Limitations

  • An abitrary gap is added to the right hand side. (imagemagick reports the wrong width in some cases.)
  • It takes a long time to render the film.
  • Frame-to-frame colors sometimes change dramatically - an epilepsy risk.
  • Hard-coded codecs and filenames on output. (They suit us, not the general case.)

Performance Considererations

filmTrace does attempt to take advantage of multiple cores in your CPU. It'll spawn 2N+1 processes per core (or more depending on whether the core supports hyperthreading), each of which attacks a single frame of video.

In each of those processes, it spawns 255 or less greenlets, one for each color of the frame.

This significantly speeds up how fast the rendering is done - however there is a massive memory overhead for multiprocessing in Python, as it basically spawns a complete interpreter for each subprocess. If you run out of memory, you'll hit errors, and the final video (if it renders) will be corrupted in some way.

However, thankfully what we are doing inside each subprocess is not particularly memory intensive, but rather I/O intensive.




Only Linux is currently supported.

However it may be able to work under macOS or a BSD without changes. It likely won't function at all under Windows.


Each of these is expected to be available from PATH when calling filmTrace.

  • imagemagick's convert (usually in your package manager)
  • potrace (usually in your package manager)
  • ffmpeg (usually in your package manager)
  • librsvg (usually in your package manager)
Python dependencies

Only Python 3.6 or greater is currently supported.

You'll also need to handle the Python dependencies.

pip install -r requirements.txt


usage: filmTrace.py [-h] [--tmp TMP] [--no-sound-filter NO_SOUND_FILTER] film

positional arguments:

film The film file to process.

optional arguments:

-h, --help show this help message and exit

--tmp TMP A directory to write temporary files to. (WILL BE DELETED)

--no-sound-filter NO_SOUND_FILTER

                    Don't attempt to filter sound.


This project would not be possible without the efforts of significant individuals and projects.

Potrace by Peter Selinger. Without his work, none of this would be possible.

Image Magick. Whilst we could take other routes, and might in the future, this tool remains one of the essentials in a dev's toolkit if you touch images.

ffmpeg. Whilst often frustrating due to the number of ways you can tweak it, this utility can do almost everything you might need to do with video thanks to that level of power and complexity.

Inkscape. Whilst we don't employ it here, it showed us what might be possible, with a little bit of creativity.


Licensed under the Creative Commons 0 (CC0) 1.0 Universal license.

See the legal text for details.