fast-neural-style: feedforward stylization in Torch7 Lua

Why the network is trained once and then thrown away the loop

Gatys et al. stylize an image by running gradient descent on the pixels themselves, which costs minutes per picture. This repository takes the other route: it trains a feedforward network per style, then applies that network in a single pass at inference time. Once training is done the per-image cost collapses, and the paper claims the resulting networks run hundreds of times faster than the optimization loop. The audience is researchers who need that speed to iterate on an idea, and engineers who want a working reference for perceptual losses rather than a maintained product. The repository ships ten pretrained models in two families, so you can get an image through the pipeline before writing a line of training code. It also includes the slow path, `slow_neural_style.lua`, so you can compare both methods inside one codebase. The README claims 50 milliseconds for a 1200x630 image on a Pascal Titan X. That number is a paper claim on 2016 hardware, not a promise about your machine.

The forward pass is a Torch7 module loaded from a .t7 file

Nothing about the inference path is clever; the weight is the work. A trained model is a serialized Torch7 module sitting in the `models/` tree, and `fast_neural_style.lua` loads one with `-model`, reads content with `-input_image` or a whole directory with `-input_dir`, and writes the result to `-output_image` or `-output_dir`. Everything else is plumbing around the loaded network. Size control is a single flag, `-image_size`, and execution defaults to CPU. Adding `-gpu` with the device index moves the forward pass onto CUDA. That short option list is the entire inference surface, and `doc/flags.md` holds the long form. Because the network is a plain Torch7 module rather than a checkpoint format with its own tooling, there is no ONNX export path and no Python loading path anywhere in the tree.

Instance normalization models trade filter width for output size

The second model family exists because of the Ulyanov, Vedaldi and Lempitsky trick. Replacing batch normalization with instance normalization is a small edit to the graph, but the paper this repository implements says it changes the output quality noticeably. The `models/instance_norm` models keep the ECCV 2016 architecture and halve the number of filters per layer, so they are smaller and faster without the quality loss the README claims. Example outputs for this family are rendered at an image size of 1024, against 512 for the paper models. That contrast is a detail a skim misses: the README's higher-resolution samples line up exactly with the family whose weights you get for free from the download script. If you judge quality from the sample grids alone, you are comparing two different architectures at two different scales.

The web demo needs qlua, camera and qtlua

Real-time playback is not the same binary as batch inference. `webcam_demo.lua` pulls frames from a webcam and runs one or more models on them, and the README is explicit that it must be launched with `qlua` rather than `th`, because the demo draws a window. Passing two models as a comma-separated list runs them side by side in one stream, which is how the README's four-model-at-640x480 claim on a Pascal Titan X was produced. The demo also needs two Lua packages the batch script does not, so `camera` and `qtlua` are an extra install step you skip at your peril if you go straight from the README's model download to the webcam. The GPU flag here takes the same shape as in the inference script, but it is not optional: without a CUDA build there is no window to draw into.

Torch7, LuaRocks and pinned Python packages from 2016

Install Torch from the link the README gives, then let LuaRocks supply the rest. These four packages are the working core, and the model download is a separate shell script that pulls about 200MB of weights into `models/`.

luarocks install torch
luarocks install nn
luarocks install image
luarocks install lua-cjson

CUDA is opt-in through `cutorch` and `cunn`, and `cudnn` speeds up convolutions once the libraries sit in `/usr/local/cuda/lib64/`. With weights in place, the first stylization is one command:

th fast_neural_style.lua \
  -model models/eccv16/starry_night.t7 \
  -input_image images/content/chicago.jpg \
  -output_image out.png

You should see `out.png` written in the working directory. Underneath the Lua layer sits a Python stack pinned by `requirements.txt`: h5py 2.6.0, numpy 1.11.1, Pillow 3.3.1, scipy 0.18.0 and six 1.10.0. Those pins date from the original release. Whether a modern interpreter can still resolve numpy 1.11.1 is the first real obstacle a new user hits, and the README says nothing about newer versions or alternatives.

Failure modes that live outside the README

Three things go wrong before you see a stylized image. First, Torch7 itself is the retired part of this stack; a clean machine today needs a manual build before `th` exists. Second, the pinned Python packages block a fresh virtualenv on recent interpreters, and no fallback pin set is given. Third, `-gpu` assumes a working CUDA build, so a machine without one fails at argument time rather than falling back. There is no container recipe, no prebuilt binary and no CPU fallback path documented for the webcam demo. The README also names no release artifacts: the repository has no GitHub releases and no version tags to pin against, so every install tracks master. Model weights are versioned only by folder, `models/eccv16` for the paper and `models/instance_norm` for the newer family.

Where the Gatys comparison belongs: slow_neural_style.lua

The alternative that needs no new dependency is already in the tree. `slow_neural_style.lua` implements the optimization-based method, runs gradient descent on image pixels, and shares loss code with the feedforward training script so both approaches are computed identically. Against the older `jcjohnson/neural-style` it drops protobuf and loadcaffe and adds support for more CNN architectures including ResNets. For a genuine comparison of the two methods that is the better path, since shared loss code removes a variable. Outside this repository, PyTorch and ONNX reimplementations of fast neural style transfer are what current search interest points to, and the difference in approach is the one that matters: they load a checkpoint in a Python runtime you can pip install, while this code needs a Torch7 module load through `th` or `qlua`.

Editorial conclusion

Adopt this repository if you want to reproduce the ECCV 2016 numbers or study instance normalization in the exact form the paper described, and you have a machine where LuaRocks still builds. Do not adopt it for new production work, since a PyTorch or ONNX path is where current search interest sits, and the last push to master was on 2023-10-03. Before anything else, try `luarocks install torch` on your target machine, because a failure there ends the evaluation before a single image is styled.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. README
4. Releases