Metadata-Version: 2.1
Name: resnet-pytorch
Version: 0.1.0
Summary: An ResNet implements of PyTorch.
Home-page: https://github.com/Lornatang/ResNet-PyTorch
Author: Liu Changyu
Author-email: liuchangyu1111@gmail.com
License: Apache
Platform: UNKNOWN
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Requires-Python: >=3.5.0
Description-Content-Type: text/markdown
Requires-Dist: torch


# ResNet-PyTorch

### Update (Feb 20, 2020)

The update is for ease of use and deployment.

 * [Example: Export to ONNX](#example-export-to-onnx)
 * [Example: Extract features](#example-feature-extraction)
 * [Example: Visual](#example-visual)

It is also now incredibly simple to load a pretrained model with a new number of classes for transfer learning:

```python
from resnet_pytorch import ResNet 
model = ResNet.from_pretrained('resnet18', num_classes=10)
```

### Update (February 2, 2020)

This update allows you to use NVIDIA's Apex tool for accelerated training. By default choice `hybrid training precision` + `dynamic loss amplified` version, if you need to learn more and details about `apex` tools, please visit https://github.com/NVIDIA/apex.

### Overview
This repository contains an op-for-op PyTorch reimplementation of [Deep Residual Learning for Image Recognition](http://xxx.itp.ac.cn/abs/1512.03385).

The goal of this implementation is to be simple, highly extensible, and easy to integrate into your own projects. This implementation is a work in progress -- new features are currently being implemented.  

At the moment, you can easily:  
 * Load pretrained ResNet models 
 * Use ResNet models for classification or feature extraction 

_Upcoming features_: In the next few days, you will be able to:
 * Quickly finetune an ResNet on your own dataset
 * Export ResNet models for production

### Table of contents
1. [About ResNet](#about-resnet)
2. [Installation](#installation)
3. [Usage](#usage)
    * [Load pretrained models](#loading-pretrained-models)
    * [Example: Classify](#example-classification)
    * [Example: Extract features](#example-feature-extraction)
    * [Example: Export to ONNX](#example-export-to-onnx)
    * [Example: Visual](#example-visual)
4. [Contributing](#contributing) 

### About ResNet

If you're new to ResNets, here is an explanation straight from the official PyTorch implementation: 

Resnet models were proposed in "Deep Residual Learning for Image Recognition". Here we have the 5 versions of resnet models, 
which contains 5, 34, 50, 101, 152 layers respectively. Detailed model architectures can be found in Table 1. 

### Installation

Install from pypi:
```bash
pip install resnet_pytorch
```

Install from source:
```bash
git clone https://github.com/Lornatang/ResNet-PyTorch.git
cd ResNet-PyTorch
pip install -e .
``` 

### Usage

#### Loading pretrained models

Load an resnet18 network:
```python
from resnet_pytorch import ResNet
model = ResNet.from_name("resnet18")
```

Load a pretrained resnet18: 
```python
from resnet_pytorch import ResNet
model = ResNet.from_pretrained("resnet18")
```

Their 1-crop error rates on imagenet dataset with pretrained models are listed below.

| Model structure | Top-1 error | Top-5 error |
| --------------- | ----------- | ----------- |
|  resnet18       | 30.24       | 10.92       |
|  resnet34       | 26.70       | 8.58        |
|  resnet50       | 23.85       | 7.13        |
|  resnet101      | 22.63       | 6.44        |
|  resnet152      | 21.69       | 5.94        |

*Option B of resnet-18/34/50/101/152 only uses projections to increase dimensions.*

For results extending to the cifar10 dataset, see `examples/cifar`

#### Example: Classification

We assume that in your current directory, there is a `img.jpg` file and a `labels_map.txt` file (ImageNet class names). These are both included in `examples/simple`. 

All pre-trained models expect input images normalized in the same way,
i.e. mini-batches of 3-channel RGB images of shape `(3 x H x W)`, where `H` and `W` are expected to be at least `224`.
The images have to be loaded in to a range of `[0, 1]` and then normalized using `mean = [0.485, 0.456, 0.406]`
and `std = [0.229, 0.224, 0.225]`.

Here's a sample execution.

```python
import json

import torch
import torchvision.transforms as transforms
from PIL import Image

from resnet_pytorch import ResNet 

# Open image
input_image = Image.open("img.jpg")

# Preprocess image
preprocess = transforms.Compose([
  transforms.Resize(256),
  transforms.CenterCrop(224),
  transforms.ToTensor(),
  transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
])
input_tensor = preprocess(input_image)
input_batch = input_tensor.unsqueeze(0)  # create a mini-batch as expected by the model

# Load class names
labels_map = json.load(open("labels_map.txt"))
labels_map = [labels_map[str(i)] for i in range(1000)]

# Classify with ResNet18
model = ResNet.from_pretrained("resnet18")
model.eval()

# move the input and model to GPU for speed if available
if torch.cuda.is_available():
  input_batch = input_batch.to("cuda")
  model.to("cuda")

with torch.no_grad():
  logits = model(input_batch)
preds = torch.topk(logits, k=5).indices.squeeze(0).tolist()

print("-----")
for idx in preds:
  label = labels_map[idx]
  prob = torch.softmax(logits, dim=1)[0, idx].item()
  print(f"{label:<75} ({prob * 100:.2f}%)")
```

#### Example: Feature Extraction 

You can easily extract features with `model.extract_features`:
```python
import torch
from resnet_pytorch import ResNet 
model = ResNet.from_pretrained('resnet18')

# ... image preprocessing as in the classification example ...
inputs = torch.randn(1, 3, 224, 224)
print(inputs.shape) # torch.Size([1, 3, 224, 224])

features = model.extract_features(inputs)
print(features.shape) # torch.Size([1, 512, 1, 1])
```

#### Example: Export to ONNX  

Exporting to ONNX for deploying to production is now simple: 
```python
import torch 
from resnet_pytorch import ResNet 

model = ResNet.from_pretrained('resnet18')
dummy_input = torch.randn(16, 3, 224, 224)

torch.onnx.export(model, dummy_input, "demo.onnx", verbose=True)
```

#### Example: Visual

```text
cd $REPO$/framework
sh start.sh
```

Then open the browser and type in the browser address [http://127.0.0.1:10004/](http://127.0.0.1:10004/).

Enjoy it.

#### ImageNet

See `examples/imagenet` for details about evaluating on ImageNet.


