BasicSR-Examples illustrates how to easily use BasicSR in your own project
MIT License
English | 简体中文
BasicSR repo
| simple mode example
| installation mode example
In this repository, we give examples to illustrate how to easily use BasicSR
in your own project.
🚩 Projects that use BasicSR
If you use BasicSR
in your open-source projects, welcome to contact me (by email or opening an issue/pull request). I will add your projects to the above list 😊
If this repo is helpful, please help to ⭐ this repo or recommend it to your friends. Thanks😊 Other recommended projects: ▶️ facexlib: A collection that provides useful face-relation functions. ▶️ HandyView: A PyQt5-based image viewer that is handy for view and comparison.
BasicSR
can be used in two ways:
pip install basicsr
Our example mainly focuses on the second one, that is, how to easily and concisely build your own project based on the basicsr package.
There are two ways to use the python package of basicsr, which are provided in two branches:
➡️ simple mode: the project can be run without installation. But it has limitations: it is inconvenient to import complex hierarchical relationships; It is not easy to access the functions in this project from other locations
➡️ installation mode: you need to install the project by running python setup.py develop
. After installation, it is more convenient to import and use.
As a simple introduction and explanation, we use the example of simple mode, but we recommend the installation mode in practical use.
git clone https://github.com/xinntao/BasicSR-examples.git
cd BasicSR-examples
Most deep-learning projects can be divided into the following parts:
When we are developing a new method, we often improve the data, arch, and model. Most training processes and basic functions are actually shared. Then, we hope to focus on the development of main functions instead of building wheels repeatedly.
Therefore, we have BasicSR, which separates many shared functions. With BasicSR, we just need to care about the development of data, arch, and model.
In order to further facilitate the use of BasicSR, we provide the basicsr package. You can easily install it through pip install basicsr
. After that, you can use the training process of BasicSR and the functions already developed in BasicSR~
Let's use a simple example to illustrate how to use BasicSR to build your own project.
We provide two sample data for demonstration:
You can easily download them by running the following command in the BasicSR-examples root path:
python scripts/prepare_example_data.py
The sample data are now in the datasets/example
folder.
Let's use a Super-Resolution task for the demo. It takes a low-resolution image as the input and outputs a high-resolution image. The low-resolution images contain: 1) CV2 bicubic X4 downsampling, and 2) JPEG compression (quality = 70).
In order to better explain how to use the arch and model, we use 1) a network structure similar to SRCNN; 2) use L1 and L2 (MSE) loss simultaneously in training.
So, in this task, what we should do are:
Let's explain it separately in the following parts.
We need to implement a new dataset to fulfill our purpose. The dataset is used to feed the data into the model.
An example of this dataset is in data/example_dataset.py. It has the following steps.
__getitem__(self, index)
function, such as downsampling and adding JPEG compression. Many basic operations can be found in [basicsr/data/degradations], [basicsr/data/tranforms] ,and [basicsr/data/data_util]
Note:
@DATASET_REGISTRY.register()
before ExampleDataset
. This operation is mainly used to prevent the occurrence of a dataset with the same name, which will result in potential bugs_dataset.py
, such as example_dataset.py
. In this way, the program can automatically import classes without manual importIn the option configuration file, you can use the new dataset:
datasets:
train: # training dataset
name: ExampleBSDS100
type: ExampleDataset # the class name
# ----- the followings are the arguments of ExampleDataset ----- #
dataroot_gt: datasets/example/BSDS100
io_backend:
type: disk
gt_size: 128
use_flip: true
use_rot: true
# ----- arguments of data loader ----- #
use_shuffle: true
num_worker_per_gpu: 3
batch_size_per_gpu: 16
dataset_enlarge_ratio: 10
prefetch_mode: ~
val: # validation dataset
name: ExampleSet5
type: ExampleDataset
dataroot_gt: datasets/example/Set5
io_backend:
type: disk
An example of architecture is in archs/example_arch.py. It mainly builds the network structure.
Note:
@ARCH_REGISTRY.register()
before ExampleArch
, so as to register the newly implemented arch. This operation is mainly used to prevent the occurrence of arch with the same name, resulting in potential bugs_arch.py
, such as example_arch.py
. In this way, the program can automatically import classes without manual importIn the option configuration file, you can use the new arch:
# network structures
network_g:
type: ExampleArch # the class name
# ----- the followings are the arguments of ExampleArch ----- #
num_in_ch: 3
num_out_ch: 3
num_feat: 64
upscale: 4
An example of model is in models/example_model.py. It mainly builds the training process of a model.
In this file:
SRModel
from basicsr. Many models have similar operations, so you can inherit and modify from basicsr/models. In this way, you can easily implement your ideas, such as GAN model, video model, etc.setup_optimizers
, validation
, save
, etc, are inherited from SRModel
Note:
@MODEL_REGISTRY.register()
before ExampleModel
, so as to register the newly implemented model. This operation is mainly used to prevent the occurrence of model with the same name, resulting in potential bugs_model.py
, such as example_model.py
. In this way, the program can automatically import classes without manual importIn the option configuration file, you can use the new model:
# training settings
train:
optim_g:
type: Adam
lr: !!float 2e-4
weight_decay: 0
betas: [0.9, 0.99]
scheduler:
type: MultiStepLR
milestones: [50000]
gamma: 0.5
total_iter: 100000
warmup_iter: -1 # no warm up
# ----- the followings are the configurations for two losses ----- #
# losses
l1_opt:
type: L1Loss
loss_weight: 1.0
reduction: mean
l2_opt:
type: MSELoss
loss_weight: 1.0
reduction: mean
The whole training pipeline can reuse the basicsr/train.py in BasicSR.
Based on this, our train.py can be very concise:
import os.path as osp
import archs # noqa: F401
import data # noqa: F401
import models # noqa: F401
from basicsr.train import train_pipeline
if __name__ == '__main__':
root_path = osp.abspath(osp.join(__file__, osp.pardir))
train_pipeline(root_path)
So far, we have completed the development of our project. We can quickly check whether there is a bug through the debug
mode:
python train.py -opt options/example_option.yml --debug
With --debug
, the program will enter the debug mode. In the debug mode, the program will output at each iteration, and perform validation every 8 iterations, so that you can easily know whether the program has a bug~
After debugging, we can have the normal training.
python train.py -opt options/example_option.yml
If the training process is interrupted unexpectedly and the resume is required. Please use --auto_resume
in the command:
python train.py -opt options/example_option.yml --auto_resume
So far, you have finished developing your own projects using BasicSR
. Isn't it very convenient~ 😁
You can use BasicSR-Examples as a template for your project. Here are some modifications you may need.
pre-commit install
LICENSE
The simple mode do not require many modifications. Those using the installation mode may need more modifications. See here
If you have any questions or want to add your project to the list, please email [email protected]
or [email protected]
.