X-Git-Url: https://www.fleuret.org/cgi-bin/gitweb/gitweb.cgi?a=blobdiff_plain;f=README.md;h=f4e07af22d33e897e1f457d43d81a78dfd3387c3;hb=de4d7faef08d682d83c075253e532af54fd39c45;hp=450ccd2d2215db908c0010e68237185315a04130;hpb=3f98a24d12e9f0e062f195d92606a5ffbe651ff8;p=pysvrt.git

diff --git a/README.md b/README.md
index 450ccd2..f4e07af 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,50 @@
 # Introduction #
 
-This is the port of the Synthetic Visual Reasoning Test to the pytorch
-framework.
+This is a port of the Synthetic Visual Reasoning Test problems to the
+pytorch framework, with an implementation of two convolutional
+networks to solve them.
 
-The main function is
+# Installation and test #
+
+Executing
+
+```
+make -j -k
+./test-svrt.py
+```
+
+should generate an image example.png in the current directory.
+
+Note that the image generation does not take advantage of GPUs or
+multi-core, and can be as fast as 10,000 vignettes per second and as
+slow as 40 on a 4GHz i7-6700K.
+
+# Vignette generation and compression #
+
+## Vignette sets ##
+
+The svrtset.py implements the classes `VignetteSet` and
+`CompressedVignetteSet` with the following constructor
+
+```
+__init__(problem_number, nb_samples, batch_size, cuda = False, logger = None)
+```
+
+and the following method to return one batch
 
 ```
-torch.ByteTensor generate_vignettes(int problem_number, torch.LongTensor labels)
+(torch.FloatTensor, torch.LongTensor) get_batch(b)
+```
+
+as a pair composed of a 4d 'input' Tensor (i.e. single channel 128x128
+images), and a 1d 'target' Tensor (i.e. Boolean labels).
+
+## Low-level functions ##
+
+The main function for genering vignettes is
+
+```
+torch.ByteTensor svrt.generate_vignettes(int problem_number, torch.LongTensor labels)
 ```
 
 where
@@ -20,17 +58,32 @@ The returned ByteTensor has three dimensions:
  * Pixel row
  * Pixel col
 
-# Installation and test #
+The two additional functions
 
-Executing
+```
+torch.ByteStorage svrt.compress(torch.ByteStorage x)
+```
+
+and
 
 ```
-make -j -k
-./test-svrt.py
+torch.ByteStorage svrt.uncompress(torch.ByteStorage x)
 ```
 
-should generate an image example.png in the current directory.
+provide a lossless compression scheme adapted to the ByteStorage of
+the vignette ByteTensor (i.e. expecting a lot of 255s, a few 0s, and
+no other value).
 
-Note that the image generation does not take advantage of GPUs or
-multi-core, and can be as slow as 40 vignettes per second s on a 4GHz
-i7-6700K.
+This compression reduces the memory footprint by a factor ~50, and may
+be usefull to deal with very large data-sets and avoid re-generating
+images at every batch. It induces a little overhead for decompression,
+and moving from CPU to GPU memory.
+
+See vignette_set.py for a class CompressedVignetteSet using it.
+
+# Testing convolution networks #
+
+The file `cnn-svrt.py` provides the implementation of two deep
+networks designed by Afroze Baqapuri during an internship at Idiap,
+and allows to train them with several millions vignettes on a PC with
+16Gb and a GPU with 8Gb.