torch-image-dataset 0.0.4
Image datasets for Pytorch.
Requires Python: >=3.6
Keywords: python,pytorch,dataset,image

# torch image dataset
Install:
```
  pip install torch-image-dataset
```

## Requirements:
```
  pip install torch torchvision pillow opencv-python
```

### Additional requirements (optional)

For saving/loading the dataset in a database:
```
  conda install -c conda-forge python-lmdb
```

For fast image loaders:
```
  conda install -c conda-forge pyturbojpeg
  conda install -c conda-forge accimage
```

### Image Loaders
ImageLoaders are objects that can load an image from a path and decode it (additionally they can resize the image).
The image loaders available are: ```LoaderPIL``` (from pillow), ```LoaderOpenCV``` (from opencv), ```LoaderAccImage``` (from accimage) and ```LoaderTurboJPEG``` (from turbojpeg).
To initialize a loader:

```
  from imagedataset import LoaderOpenCV, Interpolation
  
  size = (224, 224)
  loader = LoaderOpenCV(size=size, interpolation=Interpolation.CV_AREA)
```

If the size is ```None``` there won't be any resize at loading time. The interpolation methods available are:

```
    CV_BILINEAR         (cv2.INTER_LINEAR)
    CV_BILINEAR_EXACT   (cv2.INTER_LINEAR_EXACT)
    CV_NEAREST          (cv2.INTER_NEAREST)
    CV_BICUBIC          (cv2.INTER_CUBIC)
    CV_LANCZOS          (cv2.INTER_LANCZOS4)
    CV_AREA             (cv2.INTER_AREA)

    PIL_NEAREST         (PIL Image.NEAREST)
    PIL_BICUBIC         (PIL Image.BICUBIC)
    PIL_BILINEAR        (PIL Image.BILINEAR
    PIL_LANCZOS         (PIL Image.LANCZOS)
    ACCIMAGE_BUILDIN    (interpolation of AccImage)
```
Not all loaders support all interpolations, but the opencv interpolations are accepted by all loaders (for example it is possible to use the CV_BILINEAR interpolation even in a LoaderPIL).

### Image Decoders
ImageDecoders are very similar to ImageLoaders but their ```__call__``` function accepts a ```bytes``` object and decodes to an image (and eventually resize it).
There is one decoder for each loader introduced before.
To create a decoder:
```
  decoder = DecoderPIL(size=(224,224), interpolation=Interpolation.CV_BICUBIC)
```

### Datasets

### AdvanceImageFolder
**Use case**: 
- keep track of pseudolabels (read/update).
- load full dataset into RAM to speed up training when disk memory access is slow.
- save and read the full dataset into a database to speed up training when the whole dataset cannot be stored in RAM.
- easy subsetting/splitting keeping the possibility to update and read pseudolabels.

Import:
```
  import imagedataset as id
```

The folder structure required is similar to the one of ``` torchvision.datasets.ImageFolder```:
```
  root\
    class1\
      img1
      img2
      ...
    class2\
      img1
      img2
      ...
    ...   
```

The dataset is initialized by indicating the root directory.
Additionally, the name of the dataset can be indicated and it is possible to load just a subset of the dataset. ```load_percentage``` specifies the percentage of images to load (randomly picked without repetitions) or ```indices``` can be used to select specific indices of the dataset.

```
  dataset = id.AdvanceImageFolder(root="path/to/mydataset/",
                                  name="incredible_dataset",
                                  load_percentage=1.,
                                  indices=None)
```

The return type of the dataset is ```types.SimpleNamespace``` with the following fields:
- image
- id
- index
- label
- pseudolabel

For example you can:

```
  item = dataset.__getitem__(0)
  image = item.image
  label = item.label
  pseudolabel = item.pseudolabel
  ...
```

To use a dataloader it is possible to use:
```
  loader = dataset.dataloader(batch_size=10)
```
Actually the dataloader function accepts the same arguments as ```torch.utils.data.DataLoader``` and returns a proper ```DataLoader``` with the appropriate ```collate_fn``` for batching.

**Note**: every tensor in the batch is of type int64 (classification labels) or uint8 (images or label arrays).

To speed up the training it is possible to use a ```CudaLoader``` that pre-fatches the samples:

```
  loader = dataset.cudaloader(batch_size=10)
```
**Note**: the CudaLoader convers images to floats but do not scale them, so they are still in range [0,255]. Additionally the CudaLoader can perform normalization, for instance to bring images in range [0,1] it is possible:
```
  loader = dataset.cudaloader(batch_size=10, mean=(0,0,0), std=(255, 255, 255))
```

To subset a dataset:
```
    my_subset = dataset.subset(indices=[0,1,2], ids=None)
```
It is possible to select the indices or the ids of images. The indices are the positions of images in the sequence from 0 to len(dataset)-1.
Ids are initialized as indices but they are kept constant while subsetting and splitting and, for this reason, it is possible to get the index of an image in the original dataset.

To split a dataset:

```
    train_d, val_d, test_d = dataset.random_split(percentages=[0.5, 0.3, 0.2])
```

To drop a random part of the dataset, let say we want to keep just 50% of dataset:
```
    dataset = datset.random_split(percentages=[0.5])
```  

To load the dataset into RAM just use:
```
  dataset.load_ram()
```
To write the dataset into a LMDB database:
```
  dataset.write_database("mydb/path/")
```

Then, to get a dataset that reads the database:
```
  dataset = id.from_database("mydb/path/")
```