Installation

README.md

@@ -48,13 +48,16 @@ There are two ways to use the python package of basicsr, which are provided in t
 
 - :arrow_right: [installation mode](https://github.com/xinntao/BasicSR-examples/tree/installation): 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.
+This `installation` branch uses the *installation mode* for illustration. We recommend using this mode for practical use.
 
 ```bash
-git clone https://github.com/xinntao/BasicSR-examples.git
+git clone -b installation https://github.com/xinntao/BasicSR-examples.git
 cd BasicSR-examples
+python setup.py develop  # need to install
 ```
 
+**Note that**: the installation model requires a package name for installation. We use `basicsrexamples` as the package name.
+
 ### Preliminary
 
 Most deep-learning projects can be divided into the following parts:
@@ -106,7 +109,7 @@ 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](data/example_dataset.py). It has the following steps.
+An example of this dataset is in [basicsrexamples/data/example_dataset.py](basicsrexamples/data/example_dataset.py). It has the following steps.
 
 1. Read Ground-Truth (GT) images. BasicSR provides [FileClient](https://github.com/xinntao/BasicSR/blob/master/basicsr/utils/file_client.py) for easily reading files in a folder, LMDB file and meta_info txt. In this example, we use the folder mode. For more reading modes, please refer to [basicsr/data](https://github.com/xinntao/BasicSR/tree/master/basicsr/data)
 1. Synthesize low resolution images. We can directly implement the data procedures in the `__getitem__(self, index)` function, such as downsampling and adding JPEG compression. Many basic operations can be found in [[basicsr/data/degradations]](https://github.com/xinntao/BasicSR/blob/master/basicsr/data/degradations.py), [[basicsr/data/tranforms]](https://github.com/xinntao/BasicSR/blob/master/basicsr/data/transforms.py) ,and [[basicsr/data/data_util]](https://github.com/xinntao/BasicSR/blob/master/basicsr/data/data_util.py)
@@ -151,7 +154,7 @@ datasets:
 
 #### :two: arch
 
-An example of architecture is in [archs/example_arch.py](archs/example_arch.py). It mainly builds the network structure.
+An example of architecture is in [basicsrexamples/archs/example_arch.py](basicsrexamples/archs/example_arch.py). It mainly builds the network structure.
 
 **Note**:
 
@@ -174,7 +177,7 @@ network_g:
 
 #### :three: model
 
-An example of model is in [models/example_model.py](models/example_model.py). It mainly builds the training process of a model.
+An example of model is in [basicsrexamples/models/example_model.py](basicsrexamples/models/example_model.py). It mainly builds the training process of a model.
 
 In this file:
 1. We inherit `SRModel` from basicsr. Many models have similar operations, so you can inherit and modify from [basicsr/models](https://github.com/xinntao/BasicSR/tree/master/basicsr/models). In this way, you can easily implement your ideas, such as GAN model, video model, *etc*.
@@ -222,7 +225,7 @@ train:
 
 The whole training pipeline can reuse the [basicsr/train.py](https://github.com/xinntao/BasicSR/blob/master/basicsr/train.py) in BasicSR.
 
-Based on this, our [train.py](train.py) can be very concise:
+Based on this, our [basicsrexamples/train.py](basicsrexamples/train.py) can be very concise:
 
 ```python
 import os.path as osp
@@ -243,7 +246,7 @@ if __name__ == '__main__':
 So far, we have completed the development of our project. We can quickly check whether there is a bug through the `debug` mode:
 
 ```bash
-python train.py -opt options/example_option.yml --debug
+python basicsrexamples/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~
@@ -253,7 +256,7 @@ With `--debug`, the program will enter the debug mode. In the debug mode, the pr
 After debugging, we can have the normal training.
 
 ```bash
-python train.py -opt options/example_option.yml
+python basicsrexamples/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:
@@ -268,13 +271,36 @@ So far, you have finished developing your own projects using `BasicSR`. Isn't it
 
 You can use BasicSR-Examples as a template for your project. Here are some modifications you may need.
 
+As GitHub does not support a specific branch as a template, we need extra steps to use the `installation` branch as the template.
+
+1. Click `Use this template` and remember to check the `[ ] Include all branches` checkbox
+2. Change the installation branch to the master branch
+    ```bash
+    git clone -b installation YOUR_REPO  # clone the installation branch
+    cd REPO_NAME
+    git branch -m installation master  # rename the installation branch to master
+    git push -f origin master  # force push the local master branch to remote
+    git push origin --delete installation  # delete the remote installation branch
+    ```
+
+You may need to modify the following files:
+
 1. Set up the *pre-commit* hook
     1. In the root path, run:
     > pre-commit install
 1. Modify the `LICENSE`<br>
     This repository uses the *MIT* license, you may change it to other licenses
 
-The simple mode do not require many modifications. Those using the installation mode may need more modifications. See [here](https://github.com/xinntao/BasicSR-examples/blob/installation/README.md#As-a-Template)
+As the installation mode requires the package name, you also need to modify all the `basicsrexamples` names to YOUR_PACKAGE_NAME.
+Here are the detailed locations that contain the `basicsrexamples` name:
+1. The `basicsrexamples` folder
+1. [setup.py](setup.py#L9); &emsp; [setup.py](setup.py#L48); &emsp;[setup.py](setup.py#L91)
+1. [basicsrexamples/train.py](basicsrexamples/train.py#L4-L6)
+1. [basicsrexamples/archs/\_\_init\_\_.py](basicsrexamples/archs/__init__.py#L11)
+1. [basicsrexamples/data/\_\_init\_\_.py](basicsrexamples/data/__init__.py#L11)
+1. [basicsrexamples/models/\_\_init\_\_.py](basicsrexamples/models/__init__.py#L11)
+
+You also need to modify the corresponding information in the [setup.py](setup.py#L88-L113).
 
 ## :e-mail: Contact
 

README_CN.md

@@ -46,13 +46,16 @@
 - :arrow_right: [简单模式](https://github.com/xinntao/BasicSR-examples/tree/master): 项目的仓库不需要安装，就可以运行使用。但它有局限：不方便 import 复杂的层级关系；在其他位置也不容易访问本项目中的函数
 - :arrow_right: [安装模式](https://github.com/xinntao/BasicSR-examples/tree/installation): 项目的仓库需要安装 `python setup.py develop`，安装之后 import 和使用都更加方便
 
-作为简单的入门和讲解， 我们使用*简单模式*的样例，但在实际使用中我们推荐*安装模式*。
+这个`installation`分支使用 *安装模式* 进行说明。在实际使用中我们也推荐 *安装模式*。
 
 ```bash
-git clone https://github.com/xinntao/BasicSR-examples.git
+git clone -b installation https://github.com/xinntao/BasicSR-examples.git
 cd BasicSR-examples
+python setup.py develop  # need to install
 ```
 
+**注意**: 安装模式需要一个 包的名字 来安装。在这里，我们使用 `basicsrexamples` 作为包名。
+
 ### 预备
 
 大部分的深度学习项目，都可以分为以下几个部分：
@@ -102,7 +105,7 @@ python scripts/prepare_example_data.py
 
 这个部分是用来确定喂给模型的数据的。
 
-这个 dataset 的例子在[data/example_dataset.py](data/example_dataset.py) 中，它完成了:
+这个 dataset 的例子在[basicsrexamples/data/example_dataset.py](basicsrexamples/data/example_dataset.py) 中，它完成了:
 1. 我们读取 Ground-Truth (GT) 的图像。读取的操作，BasicSR 提供了[FileClient](https://github.com/xinntao/BasicSR/blob/master/basicsr/utils/file_client.py), 可以方便地读取 folder, lmdb 和 meta_info txt 指定的文件。在这个例子中，我们通过读取 folder 来说明，更多的读取模式可以参考 [basicsr/data](https://github.com/xinntao/BasicSR/tree/master/basicsr/data)
 1. 合成低分辨率的图像。我们直接可以在 `__getitem__(self, index)` 的函数中实现我们想要的操作，比如降采样和添加 JPEG 压缩。很多基本操作都可以在 [[basicsr/data/degradations]](https://github.com/xinntao/BasicSR/blob/master/basicsr/data/degradations.py), [[basicsr/data/tranforms]](https://github.com/xinntao/BasicSR/blob/master/basicsr/data/transforms.py) 和 [[basicsr/data/data_util]](https://github.com/xinntao/BasicSR/blob/master/basicsr/data/data_util.py) 中找到
 1. 转换成 Torch Tensor，返回合适的信息
@@ -145,7 +148,7 @@ datasets:
 
 #### :two: arch
 
-Architecture 的例子在 [archs/example_arch.py](archs/example_arch.py)中。它主要搭建了网络结构。
+Architecture 的例子在 [basicsrexamples/archs/example_arch.py](basicsrexamples/archs/example_arch.py)中。它主要搭建了网络结构。
 
 **注意**：
 1. 需要在 `ExampleArch` 前添加 `@ARCH_REGISTRY.register()`，以便注册好新写的 arch。这个操作主要用来防止出现同名的 arch，从而带来潜在的 bug
@@ -167,7 +170,7 @@ network_g:
 
 #### :three: model
 
-Model 的例子在 [models/example_model.py](models/example_model.py)中。它主要搭建了模型的训练过程。
+Model 的例子在 [basicsrexamples/models/example_model.py](basicsrexamples/models/example_model.py)中。它主要搭建了模型的训练过程。
 在这个文件中：
 1. 我们从 basicsr 中继承了 `SRModel`。很多模型都有相似的操作，因此可以通过继承 [basicsr/models](https://github.com/xinntao/BasicSR/tree/master/basicsr/models) 中的模型来更方便地实现自己的想法，比如GAN模型，Video模型等
 1. 使用了两个 Loss： L1 和 L2 (MSE) loss
@@ -213,7 +216,7 @@ train:
 
 整个 training pipeline 可以复用 basicsr 里面的 [basicsr/train.py](https://github.com/xinntao/BasicSR/blob/master/basicsr/train.py)。
 
-基于此，我们的 [train.py](train.py)可以非常简洁。
+基于此，我们的 [basicsrexamples/train.py](basicsrexamples/train.py)可以非常简洁。
 
 ```python
 import os.path as osp
@@ -234,7 +237,7 @@ if __name__ == '__main__':
 至此，我们已经完成了我们这个项目的开发，下面可以通过 `debug` 模式来快捷地看看是否有问题:
 
 ```bash
-python train.py -opt options/example_option.yml --debug
+python basicsrexamples/train.py -opt options/example_option.yml --debug
 ```
 
 只要带上 `--debug` 就进入 debug 模式。在 debug 模式中，程序每个iter都会输出，8个iter后就会进行validation，这样可以很方便地知道程序有没有bug啦~
@@ -244,7 +247,7 @@ python train.py -opt options/example_option.yml --debug
 经过debug没有问题后，我们就可以正式训练了。
 
 ```bash
-python train.py -opt options/example_option.yml
+python basicsrexamples/train.py -opt options/example_option.yml
 ```
 
 如果训练过程意外中断需要 resume, 则使用 `--auto_resume` 可以方便地自动resume：
@@ -258,13 +261,37 @@ python train.py -opt options/example_option.yml --auto_resume
 
 你可以使用 BasicSR-Examples 作为你项目的模板。下面主要展示一下你可能需要的修改。
 
+由于 GitHub 不支持将特定分支作为模板，因此我们需要额外的步骤来使用`installation`分支作为模板。
+
+1. 点击 `Use this template`；记得勾选 `[ ] Include all branches`
+2. 将 安装分支 修改为 主分支
+    ```bash
+    git clone -b installation YOUR_REPO  # clone the installation branch
+    cd REPO_NAME
+    git branch -m installation master  # rename the installation branch to master
+    git push -f origin master  # force push the local master branch to remote
+    git push origin --delete installation  # delete the remote installation branch
+    ```
+
+你需要根据需要修改以下文件:
+
 1. 设置 *pre-commit* hook
     1. 在文件夹根目录, 运行
     > pre-commit install
 1. 修改 `LICENSE` 文件<br>
     本仓库使用 *MIT* 许可, 根据需要可以修改成其他许可
 
-使用 简单模式 的基本不需要修改，使用 安装模式 的可能需要较多修改，参见[这里](https://github.com/xinntao/BasicSR-examples/blob/installation/README_CN.md#As-a-Template)
+由于安装模式需要包名，因此还需要将所有`basicsrexamples`名称修改为 YOUR_PACKAGE_NAME。
+以下是包含`basicsrexamples`名称的详细位置：
+
+1. The `basicsrexamples` folder
+1. [setup.py](setup.py#L9); &emsp; [setup.py](setup.py#L48); &emsp;[setup.py](setup.py#L91)
+1. [basicsrexamples/train.py](basicsrexamples/train.py#L4-L6)
+1. [basicsrexamples/archs/\_\_init\_\_.py](basicsrexamples/archs/__init__.py#L11)
+1. [basicsrexamples/data/\_\_init\_\_.py](basicsrexamples/data/__init__.py#L11)
+1. [basicsrexamples/models/\_\_init\_\_.py](basicsrexamples/models/__init__.py#L11)
+
+你也需要修改文件 [setup.py](setup.py#L88-L113) 中的相应信息。
 
 ## :e-mail: 联系
 

basicsrexamples/__init__.py

@@ -0,0 +1,5 @@
+# flake8: noqa
+from .archs import *
+from .data import *
+from .models import *
+from .version import __gitsha__, __version__

archs/__init__.py → basicsrexamples/archs/__init__.py

@@ -8,4 +8,4 @@
 arch_folder = osp.dirname(osp.abspath(__file__))
 arch_filenames = [osp.splitext(osp.basename(v))[0] for v in scandir(arch_folder) if v.endswith('_arch.py')]
 # import all the arch modules
-_arch_modules = [importlib.import_module(f'archs.{file_name}') for file_name in arch_filenames]
+_arch_modules = [importlib.import_module(f'basicsrexamples.archs.{file_name}') for file_name in arch_filenames]

data/__init__.py → basicsrexamples/data/__init__.py

@@ -8,4 +8,4 @@
 data_folder = osp.dirname(osp.abspath(__file__))
 dataset_filenames = [osp.splitext(osp.basename(v))[0] for v in scandir(data_folder) if v.endswith('_dataset.py')]
 # import all the dataset modules
-_dataset_modules = [importlib.import_module(f'data.{file_name}') for file_name in dataset_filenames]
+_dataset_modules = [importlib.import_module(f'basicsrexamples.data.{file_name}') for file_name in dataset_filenames]

basicsrexamples/losses/__init__.py

@@ -0,0 +1,11 @@
+import importlib
+from os import path as osp
+
+from basicsr.utils import scandir
+
+# automatically scan and import loss modules for registry
+# scan all the files that end with '_loss.py' under the loss folder
+loss_folder = osp.dirname(osp.abspath(__file__))
+loss_filenames = [osp.splitext(osp.basename(v))[0] for v in scandir(loss_folder) if v.endswith('_loss.py')]
+# import all the loss modules
+_model_modules = [importlib.import_module(f'basicsrexamples.losses.{file_name}') for file_name in loss_filenames]

basicsrexamples/losses/example_loss.py

@@ -0,0 +1,26 @@
+from torch import nn as nn
+from torch.nn import functional as F
+
+from basicsr.utils.registry import LOSS_REGISTRY
+
+
+@LOSS_REGISTRY.register()
+class ExampleLoss(nn.Module):
+    """Example Loss.
+
+    Args:
+        loss_weight (float): Loss weight for Example loss. Default: 1.0.
+    """
+
+    def __init__(self, loss_weight=1.0):
+        super(ExampleLoss, self).__init__()
+        self.loss_weight = loss_weight
+
+    def forward(self, pred, target, **kwargs):
+        """
+        Args:
+            pred (Tensor): of shape (N, C, H, W). Predicted tensor.
+            target (Tensor): of shape (N, C, H, W). Ground truth tensor.
+            weight (Tensor, optional): of shape (N, C, H, W). Element-wise weights. Default: None.
+        """
+        return self.loss_weight * F.l1_loss(pred, target, reduction='mean')

models/__init__.py → basicsrexamples/models/__init__.py

@@ -8,4 +8,4 @@
 model_folder = osp.dirname(osp.abspath(__file__))
 model_filenames = [osp.splitext(osp.basename(v))[0] for v in scandir(model_folder) if v.endswith('_model.py')]
 # import all the model modules
-_model_modules = [importlib.import_module(f'models.{file_name}') for file_name in model_filenames]
+_model_modules = [importlib.import_module(f'basicsrexamples.models.{file_name}') for file_name in model_filenames]

basicsrexamples/train.py

@@ -0,0 +1,12 @@
+# flake8: noqa
+import os.path as osp
+
+import basicsrexamples.archs
+import basicsrexamples.data
+import basicsrexamples.losses
+import basicsrexamples.models
+from basicsr.train import train_pipeline
+
+if __name__ == '__main__':
+    root_path = osp.abspath(osp.join(__file__, osp.pardir, osp.pardir))
+    train_pipeline(root_path)

options/example_option.yml

@@ -65,9 +65,8 @@ train:
 
   # losses
   l1_opt:
-    type: L1Loss
+    type: ExampleLoss
     loss_weight: 1.0
-    reduction: mean
 
   l2_opt:
     type: MSELoss