README.md

   1 # Introduction #
   2
   3 This is a wrapper for [`PyTorch`](http://pytorch.org) for the
   4 [`Synthetic Visual Reasoning Test,`](https://fleuret.org/git/svrt)
   5 with an implementation of two convolutional networks to solve them.
   6
   7 # Installation and test #
   8
   9 Executing
  10
  11 ```
  12 make -j -k
  13 ./test-svrt.py
  14 ```
  15
  16 should generate an image
  17 [`example.png`](https://fleuret.org/git-extract/pysvrt/example.png) in
  18 the current directory.
  19
  20 Note that the image generation does not take advantage of GPUs or
  21 multi-core, and can be as fast as 10,000 vignettes per second and as
  22 slow as 40 on a 4GHz i7-6700K.
  23
  24 # Vignette generation and compression #
  25
  26 ## Vignette sets ##
  27
  28 The file [`svrtset.py`](https://fleuret.org/git-extract/pysvrt/svrtset.py) implements the classes `VignetteSet` and
  29 `CompressedVignetteSet` both with a constructor
  30
  31 ```
  32 __init__(problem_number, nb_samples, batch_size, cuda = False, logger = None)
  33 ```
  34
  35 and a method
  36
  37 ```
  38 (torch.FloatTensor, torch.LongTensor) get_batch(b)
  39 ```
  40
  41 which returns a pair composed of a 4d 'input' Tensor (i.e. single
  42 channel 128x128 images), and a 1d 'target' Tensor (i.e. Boolean
  43 labels).
  44
  45 ## Low-level functions ##
  46
  47 The main function for generating vignettes is
  48
  49 ```
  50 torch.ByteTensor svrt.generate_vignettes(int problem_number, torch.LongTensor labels)
  51 ```
  52
  53 where
  54
  55  * `problem_number` indicates which of the 23 problem to use
  56  * `labels` indicates the boolean labels of the vignettes to generate
  57
  58 The returned ByteTensor has three dimensions:
  59
  60  * Vignette index
  61  * Pixel row
  62  * Pixel col
  63
  64 The two additional functions
  65
  66 ```
  67 torch.ByteStorage svrt.compress(torch.ByteStorage x)
  68 ```
  69
  70 and
  71
  72 ```
  73 torch.ByteStorage svrt.uncompress(torch.ByteStorage x)
  74 ```
  75
  76 provide a lossless compression scheme adapted to the ByteStorage of
  77 the vignette ByteTensor (i.e. expecting a lot of 255s, a few 0s, and
  78 no other value).
  79
  80 This compression reduces the memory footprint by a factor ~50, and may
  81 be usefull to deal with very large data-sets and avoid re-generating
  82 images at every batch. It induces a little overhead for decompression,
  83 and moving from CPU to GPU memory.
  84
  85 See vignette_set.py for a class CompressedVignetteSet using it.
  86
  87 # Testing convolution networks #
  88
  89 The file
  90 [`cnn-svrt.py`](https://fleuret.org/git-extract/pysvrt/cnn-svrt.py)
  91 provides the implementation of two deep networks designed by Afroze
  92 Baqapuri during an internship at Idiap, and allows to train them with
  93 several millions vignettes on a PC with 16Gb and a GPU with 8Gb.