Now generate samples by batches.
[pysvrt.git] / README.md
1 # Introduction #
2
3 This is a port of the Synthetic Visual Reasoning Test problems to the
4 pytorch framework, with an implementation of two convolutional
5 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.