updated readme, reqs

README.md

@@ -1,7 +1,81 @@
-# torchrs
-(WIP) PyTorch implementation of popular datasets and models in remote sensing
+# PyTorch Remote Sensing
+(WIP) PyTorch implementation of popular datasets and models in remote sensing tasks (Change Detection, Image Super Resolution, Land Cover Classification/Segmentation, Image-to-Image Translation, etc.) for various Optical (Sentinel-2, Landsat, etc.) and Synthetic Aperture Radar (SAR) (Sentinel-1) sensors.
 
 ## Installation
 ```
 pip install git+https://github.com/isaaccorley/torchrs
 ```
+
+## Datasets
+
+### PROBA-V Super Resolution
+
+<img src="./assets/proba-v.jpg" width="500px"></img>
+
+The [PROBA-V Super Resolution Challenge Dataset](https://kelvins.esa.int/proba-v-super-resolution/home/) is a Multi-image Super Resolution (MISR) dataset of images taken by the [ESA PROBA-Vegetation satellite](https://earth.esa.int/eogateway/missions/proba-v). The dataset contains sets of 300m low resolution (LR) images which can be used to generate 100m high resolution (HR) images. In addition to LR and HR imagery, the dataset contains Quality Masks (QM) for each LR image and a Status Mask (SM) for each HR image. Imagery are available for the Near-Infrared (NIR) and Red bands. The PROBA-V contains sensors which take imagery at 100 and 300 meter spatial resolutions with 5 and 1 day revisit rates, respectively. Generating high resolution estimates using low resolution imagery would effectively increase the frequency at which high resolution imagery is available for vegatation monitoring.
+
+The dataset can be downloaded using the `scripts/download_probav.sh` script and then used as below:
+
+```python
+import torchvision.transforms as T
+from torchrs.transforms import ToTensor
+from torchrs.datasets import PROBAV
+
+transform = T.Compose([ToTensor()])
+
+dataset = PROBAV(
+    root="path/to/dataset/",
+    split="train",          # or 'test'
+    band="RED",             # or 'NIR'
+    lr_transform=transform,
+    hr_transform=transform
+)
+
+x = dataset[0]
+"""
+x: dict(
+    lr: low res images  (t, 1, 128, 128)
+    qm: quality masks   (t, 1, 128, 128)
+    hr: high res image  (1, 384, 384)
+    sm: status mask     (1, 384, 384)
+)
+t varies by set of images (minimum of 9)
+"""
+```
+
+## Models
+
+### RAMS
+
+<img src="./assets/rams.png" width="500px"></img>
+
+Residual Attention Multi-image Super-resolution Network (RAMS) from 
+["Multi-Image Super Resolution of Remotely Sensed Images Using Residual Attention Deep Neural Networks",
+Salvetti et al. (2021)](https://www.mdpi.com/2072-4292/12/14/2207)
+
+RAMS is currently one of the top performers on the [PROBA-V Super Resolution Challenge](https://kelvins.esa.int/proba-v-super-resolution/home/). This Multi-image Super Resolution (MISR) architecture utilizes attention based method to extract spatial and 'temporal' features amongst a set of unregistered low resolution images to form a single high resolution image.
+
+```python
+import torch
+from torchrs.models import RAMS
+
+# increase resolution by factor of 3 (e.g. 128x128 -> 384x384)
+model = RAMS(
+    scale_factor=3,
+    t=9,
+    c=1,
+    num_feature_attn_blocks=12
+)
+
+# Input should be of shape (bs, t, c, h, w), where t is the number
+# of low resolution input images and c is the number of channels/bands
+lr = torch.randn(1, 9, 1, 128, 128)
+sr = model(x) # (1, 1, 384, 384)
+```
+
+
+## Tests
+
+```
+$ pytest -ra
+```

requirements.txt

@@ -2,3 +2,4 @@ torch
 torchvision
 einops
 numpy
+pillow

torchrs/datasets/probav.py

@@ -89,4 +89,9 @@ def __getitem__(self, idx: int) -> Tuple[torch.Tensor, torch.Tensor]:
         hr = self.hr_transform(hr)
         sm = torch.from_numpy(sm)
 
+        lrs = lrs.unsqueeze(dim=1)
+        qms = qms.unsqueeze(dim=1)
+        hr = hr.unsqueeze(dim=0)
+        sm = sm.unsqueeze(dim=0)
+
         return dict(lr=lrs, qm=qms, hr=hr, sm=sm)