===============================================================================
This repository contains code related to

Deep Visual Analogy-Making
Scott Reed, Yi Zhang, Yuting Zhang, Honglak Lee
In Advances in Neural Information Processing Systems (NIPS), Montreal, 2015.

It is built on top of Caffe with a custom matcaffe wrapper that was needed at
the time. Since completing the project there have been several (officially
supported) versions of matcaffe that should be used for new projects.

This code release is for demonstrating our method and reproducing results only.
You can do with this code... whatever you want. And please cite our paper.

===============================================================================
Preparing the code:

- You will need to update Makefile.config to point to your corresponding 
  library locations.
- We tested on RHEL6.5, but it should work on other platforms with little to no
  modification (main dependency is Caffe).
- From the base directory of this project run

> make
> make matcaffe
> make pycaffe

===============================================================================
Getting the data:

You can download the data like this:

cd analogy
wget http://www-personal.umich.edu/~reedscot/files/nips2015-analogy-data.tar.gz
tar -xzvf nips2015-analogy-data.tar.gz
rm nips2015-analogy-data.tar.gz

===============================================================================
Results replication:

## Shapes ##

Table 1 and Figure 5 scatter plots: In analogy/shapes, in Matlab run
> train_shapes                % To train
> eval_predictions            % To evaluate
> demo_shapes_figures_videos  % Generate more examples.

## Sprites ##

Basic analogy models: add, dis, dis+cls: in Matlab run
> train_sprites               % To train; arguments specify add, dis or dis+cls.
> test_sprites_error_add      % To evaluate L_add model
> test_sprites_error_dis      % To evaluate L_dis model
> test_sprites_error_dis_cls  % To evaluate L_dis+cls model

Few-shot learning (Table 3, Figure 7): In analogy/sprites, in Matlab run
> train_sprites_fewshot       % To train; arguments specify add, dis or dis+cls.
> eval_sprites_fewshot        % To evaluate; paste in path to checkpoint to
                              % evaluate in this script.

Animation extrapolation (Figure 8, 9): In analogy/sprites, in Matlab run:
> train_sprites_manifold      % To train
> gen_sprites_manifold_fig    % To visualize (paste in your checkpoint)

Animation transfer with different pose (shown in NIPS talk):
> train_sprites_transfer      % To train
> gen_sprites_transfer_fig    % To visualize (paste in your checkpoint)

## Cars ##

Disentangling ID and pose (Table 4, Figure 10): Add you matlab liblinear path to
eval_cars_dis.m. Also add the path to the checkpoint you want to evaluate.
In analogy/cars, in Matlab run
> train_cars_dis  % To train disentangling model.
> eval_cars_dis   % To evaluate disentangling model.

3D pose changes by analogy (Figure 11): In analogy/cars, in Matlab run
> train_cars_analogy
> eval_cars_analogy

Note that when you load a new Caffe network in MATLAB, you will need to restart
MATLAB to clear the cache of the old network.

===============================================================================

