# Image Analogies with VGG16: A 2016 Tool Still Worth Knowing

> A look at awentzonline/image-analogies, a Python implementation of the Image Analogies paper using VGG16 feature maps, PatchMatch, and Keras. The project is dated but the approach remains instructive for style transfer and texture synthesis.

**awentzonline/image-analogies** — GitHub describes it as Generate image analogies using neural matching and blending.. The repository metadata lists Python as its primary language. The metadata lists the MIT license. This article stays within the project description and details documented in the GitHub repository README.

- Repository: https://github.com/awentzonline/image-analogies
- Stars: 3,499 · Forks: 280
- Language: Python
- License: MIT
- Published: 2026-08-13 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/awentzonline-image-analogies

## What This Project Solves and Who It Is For

The repository implements the Image Analogies problem: given a pair of images A and A' that form a before-and-after pair, and a new image B, produce a new image B' that transforms B in the same way A was transformed into A'. Think of a sketch paired with a finished painting, then a new sketch, and the tool generates a plausible finished painting. The intended audience is developers and researchers who want to experiment with this classic synthesis task using convolutional neural network features. The README explicitly credits the original Image Analogies paper from NYU and adapts the approach to use VGG16 feature maps. This is not a general-purpose image editor; it is a focused research implementation. The project has been archived, but the code remains accessible for study. The last push was in March 2016, so you are looking at a snapshot of deep learning practice from that era.

## How It Works: VGG16 Features, PatchMatch, and Losses

The core mechanism is a multi-scale optimization. The script takes A, A', and B, and iteratively adjusts B' to minimize a combination of losses. The analogy loss, weighted by --analogy-w, enforces that the transformation from B to B' matches the transformation from A to A' in feature space. The MRF loss, weighted by --mrf-w, encourages local coherence between A' and B' by matching patches. The content loss, weighted by --b-content-w, keeps B' close to B in content. There is also a total variation loss for smoothness. Patch matching uses the PatchMatch algorithm by default, which approximates nearest-neighbor matches quickly. A brute-force mode is available via --model=brute, but the README warns that this requires a powerful GPU and is Theano-only. The VGG16 network provides the feature maps, and the weights file is a reduced version containing only convolutional layers. The optimization runs at multiple scales, controlled by --scales and --min-scale, which is typical for such synthesis to capture both global structure and fine detail.

## Getting It Running: Commands and Configuration

Installation is via pip: `pip install neural-image-analogies`. The README recommends using virtualenv, and you need to set up Keras with either TensorFlow or Theano as the backend. Before running, you must download the VGG16 weights from the release page and place them in the current working directory, or pass `--vgg-weights` or set the `VGG_WEIGHT_PATH` environment variable. The basic command is `make_image_analogy.py image-A image-A-prime image-B prefix_for_output`. For example, `make_image_analogy.py images/arch-mask.jpg images/arch.jpg images/arch-newmask.jpg out/arch`. There is also an example script `render_example.sh` that takes an example name and optional weights path. Key parameters include `--width`, `--height`, `--scales`, `--iters`, and `--patch-size`. The default patch size is 1, but the README suggests `--patch-size=3` for nicer details. The `--a-scale-mode` parameter controls how A and A' are scaled relative to B, with options 'match', 'ratio', and 'none'. The default is 'ratio'. The `--pool-mode` parameter lets you choose between average and max pooling in the VGG network, affecting smoothness.

## Limitations and Failure Modes

The most obvious limitation is that A and A' must be the same size, and B and B' must also be the same size. The output size is the same as image B unless you specify otherwise. This constraint can be restrictive for real-world images that do not align. Another failure mode is speed. The README includes a section titled 'It's too slow' with suggestions like using TensorFlow on CPU, setting `--mrf-w=0` to skip local coherence optimization, and reducing the number of feature layers. On a 2016 MacBook Pro, a 512x512 image took approximately 12 minutes with TensorFlow and `--mrf-w=0`. That is slow by modern standards, and on a CPU-only machine, larger images could take much longer. The project is also tied to old versions of Keras, TensorFlow, and Theano. The README links to TensorFlow r0.7, which is ancient. This means you will likely encounter dependency conflicts if you try to install it today. The project is archived, so no updates are coming to fix these issues. If you need a tool that works out of the box with current libraries, this is the wrong choice.

## Alternatives: Different Approaches to Image Synthesis

The most direct alternative is the original Image Analogies implementation from the NYU project, which uses a different method based on Markov random fields and does not rely on deep neural networks. That approach is faster and more predictable for simple analogies, but it lacks the semantic features that VGG16 provides. Another alternative is neural style transfer, which is what this project's code was initially adapted from. Style transfer produces a single stylized image from a content image and a style image, whereas image analogies require a full A/A' pair and produce a transformation that can generalize to new B images. The README mentions that effects similar to the paper 'Combining Markov Random Fields and Convolutional Neural Networks for Image Synthesis' can be achieved by setting `--analogy-w=0` and using `--b-content-w`, which is a different balance of losses. If you want a modern, maintained tool, you could look at implementations of the same idea in PyTorch, but that is not covered here.

## Maintenance and License Considerations

The project is licensed under MIT, which gives you freedom to use, modify, and distribute the code, provided you retain the copyright notice. There is no maintenance activity; the last push was in 2016 and the repository is archived, meaning no further commits are expected. The release v0.0.5 exists solely to host the VGG16 weights, which are a separate concern. The weights file is derived from a gist by baraldilorenzo, and you should check the license of those weights before using them in a commercial product. The code itself depends on Keras and TensorFlow or Theano, which have their own licenses. The maintenance cost is effectively zero because there is no ongoing development, but the upgrade cost is high: you will need to pin old versions of dependencies and may need to patch the code to work with newer Python versions. The README does not mention Python version requirements, but given the 2016 date, it likely targets Python 2. That is a significant barrier for modern users. If you adopt this project, you are taking on the burden of making it run in a contemporary environment.

## Conclusion

Adopt this project if you are a researcher or hobbyist who wants to experiment with the Image Analogies algorithm using modern deep features, and you are comfortable with Python 2-era dependencies and manual weight downloads. Do not use it if you need a maintained library, production reliability, or support for current TensorFlow versions. Before adopting, verify that your GPU and driver are compatible with the old TensorFlow or Theano versions required, and download the VGG16 weights from the release page, because the script will not run without them. The project's value is historical and educational, not operational.

## FAQ

### What is image-analogies?

A Python implementation of image analogies. Given a source pair A and A-prime and a target image B, it synthesises a result that relates to B the way A-prime relates to A, using VGG16 feature maps, PatchMatch to approximate the best patch matches, and Markov random field style losses for blending. The code was adapted from a Keras neural style transfer example.

### How do I run make_image_analogy.py?

It takes four positional arguments: the two source images, the target image and an output prefix, for example `make_image_analogy.py images/arch-mask.jpg images/arch.jpg images/arch-newmask.jpg out/arch`. A and A-prime must be the same size, as must B and B-prime, and the output size follows B unless the width or height parameters say otherwise.

### Where do the VGG16 weights for image-analogies come from?

A separate download, not the package. The README points at a GitHub release for vgg16_weights.h5 and says the file holds only the convolutional layers of VGG16, ten percent of the full size. The script looks for it in the current working directory unless you pass `--vgg-weights` or set the `VGG_WEIGHT_PATH` environment variable.

### What does pip install neural-image-analogies install?

A distribution named neural-image-analogies, version 0.1.2 in the setup script, requiring Keras and Theano among others and installing scripts/make_image_analogy.py onto your path. The GitHub repository is named image-analogies and the only release tag is v0.0.5.

### How do I make image-analogies run faster?

The README lists five options that mostly trade quality for speed: use TensorFlow rather than Theano without a GPU, enable Theano OpenMP threading through environment variables, set `--mrf-w=0` to skip the local coherence optimisation, use fewer feature layers such as `--mrf-layers=conv4_1`, and generate a smaller image with `--width` or `--height`. Its one measured figure is about twelve minutes for a 512x512 image on one laptop.

## Sources

- [Official README](https://github.com/awentzonline/image-analogies#readme)
- [Project repository](https://github.com/awentzonline/image-analogies)
- [Release notes](https://github.com/awentzonline/image-analogies/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/awentzonline-image-analogies