|
# Learn about Configs |
|
|
|
MMDetection and other OpenMMLab repositories use [MMEngine's config system](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/config.html). It has a modular and inheritance design, which is convenient to conduct various experiments. |
|
|
|
## Config file content |
|
|
|
MMDetection uses a modular design, all modules with different functions can be configured through the config. Taking Mask R-CNN as an example, we will introduce each field in the config according to different function modules: |
|
|
|
### Model config |
|
|
|
In MMDetection's config, we use `model` to set up detection algorithm components. In addition to neural network components such as `backbone`, `neck`, etc, it also requires `data_preprocessor`, `train_cfg`, and `test_cfg`. `data_preprocessor` is responsible for processing a batch of data output by dataloader. `train_cfg`, and `test_cfg` in the model config are for training and testing hyperparameters of the components. |
|
|
|
```python |
|
model = dict( |
|
type='MaskRCNN', # The name of detector |
|
data_preprocessor=dict( # The config of data preprocessor, usually includes image normalization and padding |
|
type='DetDataPreprocessor', # The type of the data preprocessor, refer to https://mmdetection.readthedocs.io/en/latest/api.html#mmdet.models.data_preprocessors.DetDataPreprocessor |
|
mean=[123.675, 116.28, 103.53], # Mean values used to pre-training the pre-trained backbone models, ordered in R, G, B |
|
std=[58.395, 57.12, 57.375], # Standard variance used to pre-training the pre-trained backbone models, ordered in R, G, B |
|
bgr_to_rgb=True, # whether to convert image from BGR to RGB |
|
pad_mask=True, # whether to pad instance masks |
|
pad_size_divisor=32), # The size of padded image should be divisible by ``pad_size_divisor`` |
|
backbone=dict( # The config of backbone |
|
type='ResNet', # The type of backbone network. Refer to https://mmdetection.readthedocs.io/en/latest/api.html#mmdet.models.backbones.ResNet |
|
depth=50, # The depth of backbone, usually it is 50 or 101 for ResNet and ResNext backbones. |
|
num_stages=4, # Number of stages of the backbone. |
|
out_indices=(0, 1, 2, 3), # The index of output feature maps produced in each stage |
|
frozen_stages=1, # The weights in the first stage are frozen |
|
norm_cfg=dict( # The config of normalization layers. |
|
type='BN', # Type of norm layer, usually it is BN or GN |
|
requires_grad=True), # Whether to train the gamma and beta in BN |
|
norm_eval=True, # Whether to freeze the statistics in BN |
|
style='pytorch', # The style of backbone, 'pytorch' means that stride 2 layers are in 3x3 Conv, 'caffe' means stride 2 layers are in 1x1 Convs. |
|
init_cfg=dict(type='Pretrained', checkpoint='torchvision://resnet50')), # The ImageNet pretrained backbone to be loaded |
|
neck=dict( |
|
type='FPN', # The neck of detector is FPN. We also support 'NASFPN', 'PAFPN', etc. Refer to https://mmdetection.readthedocs.io/en/latest/api.html#mmdet.models.necks.FPN for more details. |
|
in_channels=[256, 512, 1024, 2048], # The input channels, this is consistent with the output channels of backbone |
|
out_channels=256, # The output channels of each level of the pyramid feature map |
|
num_outs=5), # The number of output scales |
|
rpn_head=dict( |
|
type='RPNHead', # The type of RPN head is 'RPNHead', we also support 'GARPNHead', etc. Refer to https://mmdetection.readthedocs.io/en/latest/api.html#mmdet.models.dense_heads.RPNHead for more details. |
|
in_channels=256, # The input channels of each input feature map, this is consistent with the output channels of neck |
|
feat_channels=256, # Feature channels of convolutional layers in the head. |
|
anchor_generator=dict( # The config of anchor generator |
|
type='AnchorGenerator', # Most of methods use AnchorGenerator, SSD Detectors uses `SSDAnchorGenerator`. Refer to https://github.com/open-mmlab/mmdetection/blob/main/mmdet/models/task_modules/prior_generators/anchor_generator.py#L18 for more details |
|
scales=[8], # Basic scale of the anchor, the area of the anchor in one position of a feature map will be scale * base_sizes |
|
ratios=[0.5, 1.0, 2.0], # The ratio between height and width. |
|
strides=[4, 8, 16, 32, 64]), # The strides of the anchor generator. This is consistent with the FPN feature strides. The strides will be taken as base_sizes if base_sizes is not set. |
|
bbox_coder=dict( # Config of box coder to encode and decode the boxes during training and testing |
|
type='DeltaXYWHBBoxCoder', # Type of box coder. 'DeltaXYWHBBoxCoder' is applied for most of the methods. Refer to https://github.com/open-mmlab/mmdetection/blob/main/mmdet/models/task_modules/coders/delta_xywh_bbox_coder.py#L13 for more details. |
|
target_means=[0.0, 0.0, 0.0, 0.0], # The target means used to encode and decode boxes |
|
target_stds=[1.0, 1.0, 1.0, 1.0]), # The standard variance used to encode and decode boxes |
|
loss_cls=dict( # Config of loss function for the classification branch |
|
type='CrossEntropyLoss', # Type of loss for classification branch, we also support FocalLoss etc. Refer to https://github.com/open-mmlab/mmdetection/blob/main/mmdet/models/losses/cross_entropy_loss.py#L201 for more details |
|
use_sigmoid=True, # RPN usually performs two-class classification, so it usually uses the sigmoid function. |
|
loss_weight=1.0), # Loss weight of the classification branch. |
|
loss_bbox=dict( # Config of loss function for the regression branch. |
|
type='L1Loss', # Type of loss, we also support many IoU Losses and smooth L1-loss, etc. Refer to https://github.com/open-mmlab/mmdetection/blob/main/mmdet/models/losses/smooth_l1_loss.py#L56 for implementation. |
|
loss_weight=1.0)), # Loss weight of the regression branch. |
|
roi_head=dict( # RoIHead encapsulates the second stage of two-stage/cascade detectors. |
|
type='StandardRoIHead', |
|
bbox_roi_extractor=dict( # RoI feature extractor for bbox regression. |
|
type='SingleRoIExtractor', # Type of the RoI feature extractor, most of methods uses SingleRoIExtractor. Refer to https://github.com/open-mmlab/mmdetection/blob/main/mmdet/models/roi_heads/roi_extractors/single_level_roi_extractor.py#L13 for details. |
|
roi_layer=dict( # Config of RoI Layer |
|
type='RoIAlign', # Type of RoI Layer, DeformRoIPoolingPack and ModulatedDeformRoIPoolingPack are also supported. Refer to https://mmcv.readthedocs.io/en/latest/api.html#mmcv.ops.RoIAlign for details. |
|
output_size=7, # The output size of feature maps. |
|
sampling_ratio=0), # Sampling ratio when extracting the RoI features. 0 means adaptive ratio. |
|
out_channels=256, # output channels of the extracted feature. |
|
featmap_strides=[4, 8, 16, 32]), # Strides of multi-scale feature maps. It should be consistent with the architecture of the backbone. |
|
bbox_head=dict( # Config of box head in the RoIHead. |
|
type='Shared2FCBBoxHead', # Type of the bbox head, Refer to https://github.com/open-mmlab/mmdetection/blob/main/mmdet/models/roi_heads/bbox_heads/convfc_bbox_head.py#L220 for implementation details. |
|
in_channels=256, # Input channels for bbox head. This is consistent with the out_channels in roi_extractor |
|
fc_out_channels=1024, # Output feature channels of FC layers. |
|
roi_feat_size=7, # Size of RoI features |
|
num_classes=80, # Number of classes for classification |
|
bbox_coder=dict( # Box coder used in the second stage. |
|
type='DeltaXYWHBBoxCoder', # Type of box coder. 'DeltaXYWHBBoxCoder' is applied for most of the methods. |
|
target_means=[0.0, 0.0, 0.0, 0.0], # Means used to encode and decode box |
|
target_stds=[0.1, 0.1, 0.2, 0.2]), # Standard variance for encoding and decoding. It is smaller since the boxes are more accurate. [0.1, 0.1, 0.2, 0.2] is a conventional setting. |
|
reg_class_agnostic=False, # Whether the regression is class agnostic. |
|
loss_cls=dict( # Config of loss function for the classification branch |
|
type='CrossEntropyLoss', # Type of loss for classification branch, we also support FocalLoss etc. |
|
use_sigmoid=False, # Whether to use sigmoid. |
|
loss_weight=1.0), # Loss weight of the classification branch. |
|
loss_bbox=dict( # Config of loss function for the regression branch. |
|
type='L1Loss', # Type of loss, we also support many IoU Losses and smooth L1-loss, etc. |
|
loss_weight=1.0)), # Loss weight of the regression branch. |
|
mask_roi_extractor=dict( # RoI feature extractor for mask generation. |
|
type='SingleRoIExtractor', # Type of the RoI feature extractor, most of methods uses SingleRoIExtractor. |
|
roi_layer=dict( # Config of RoI Layer that extracts features for instance segmentation |
|
type='RoIAlign', # Type of RoI Layer, DeformRoIPoolingPack and ModulatedDeformRoIPoolingPack are also supported |
|
output_size=14, # The output size of feature maps. |
|
sampling_ratio=0), # Sampling ratio when extracting the RoI features. |
|
out_channels=256, # Output channels of the extracted feature. |
|
featmap_strides=[4, 8, 16, 32]), # Strides of multi-scale feature maps. |
|
mask_head=dict( # Mask prediction head |
|
type='FCNMaskHead', # Type of mask head, refer to https://mmdetection.readthedocs.io/en/latest/api.html#mmdet.models.roi_heads.FCNMaskHead for implementation details. |
|
num_convs=4, # Number of convolutional layers in mask head. |
|
in_channels=256, # Input channels, should be consistent with the output channels of mask roi extractor. |
|
conv_out_channels=256, # Output channels of the convolutional layer. |
|
num_classes=80, # Number of class to be segmented. |
|
loss_mask=dict( # Config of loss function for the mask branch. |
|
type='CrossEntropyLoss', # Type of loss used for segmentation |
|
use_mask=True, # Whether to only train the mask in the correct class. |
|
loss_weight=1.0))), # Loss weight of mask branch. |
|
train_cfg = dict( # Config of training hyperparameters for rpn and rcnn |
|
rpn=dict( # Training config of rpn |
|
assigner=dict( # Config of assigner |
|
type='MaxIoUAssigner', # Type of assigner, MaxIoUAssigner is used for many common detectors. Refer to https://github.com/open-mmlab/mmdetection/blob/main/mmdet/models/task_modules/assigners/max_iou_assigner.py#L14 for more details. |
|
pos_iou_thr=0.7, # IoU >= threshold 0.7 will be taken as positive samples |
|
neg_iou_thr=0.3, # IoU < threshold 0.3 will be taken as negative samples |
|
min_pos_iou=0.3, # The minimal IoU threshold to take boxes as positive samples |
|
match_low_quality=True, # Whether to match the boxes under low quality (see API doc for more details). |
|
ignore_iof_thr=-1), # IoF threshold for ignoring bboxes |
|
sampler=dict( # Config of positive/negative sampler |
|
type='RandomSampler', # Type of sampler, PseudoSampler and other samplers are also supported. Refer to https://github.com/open-mmlab/mmdetection/blob/main/mmdet/models/task_modules/samplers/random_sampler.py#L14 for implementation details. |
|
num=256, # Number of samples |
|
pos_fraction=0.5, # The ratio of positive samples in the total samples. |
|
neg_pos_ub=-1, # The upper bound of negative samples based on the number of positive samples. |
|
add_gt_as_proposals=False), # Whether add GT as proposals after sampling. |
|
allowed_border=-1, # The border allowed after padding for valid anchors. |
|
pos_weight=-1, # The weight of positive samples during training. |
|
debug=False), # Whether to set the debug mode |
|
rpn_proposal=dict( # The config to generate proposals during training |
|
nms_across_levels=False, # Whether to do NMS for boxes across levels. Only work in `GARPNHead`, naive rpn does not support do nms cross levels. |
|
nms_pre=2000, # The number of boxes before NMS |
|
nms_post=1000, # The number of boxes to be kept by NMS. Only work in `GARPNHead`. |
|
max_per_img=1000, # The number of boxes to be kept after NMS. |
|
nms=dict( # Config of NMS |
|
type='nms', # Type of NMS |
|
iou_threshold=0.7 # NMS threshold |
|
), |
|
min_bbox_size=0), # The allowed minimal box size |
|
rcnn=dict( # The config for the roi heads. |
|
assigner=dict( # Config of assigner for second stage, this is different for that in rpn |
|
type='MaxIoUAssigner', # Type of assigner, MaxIoUAssigner is used for all roi_heads for now. Refer to https://github.com/open-mmlab/mmdetection/blob/main/mmdet/models/task_modules/assigners/max_iou_assigner.py#L14 for more details. |
|
pos_iou_thr=0.5, # IoU >= threshold 0.5 will be taken as positive samples |
|
neg_iou_thr=0.5, # IoU < threshold 0.5 will be taken as negative samples |
|
min_pos_iou=0.5, # The minimal IoU threshold to take boxes as positive samples |
|
match_low_quality=False, # Whether to match the boxes under low quality (see API doc for more details). |
|
ignore_iof_thr=-1), # IoF threshold for ignoring bboxes |
|
sampler=dict( |
|
type='RandomSampler', # Type of sampler, PseudoSampler and other samplers are also supported. Refer to https://github.com/open-mmlab/mmdetection/blob/main/mmdet/models/task_modules/samplers/random_sampler.py#L14 for implementation details. |
|
num=512, # Number of samples |
|
pos_fraction=0.25, # The ratio of positive samples in the total samples. |
|
neg_pos_ub=-1, # The upper bound of negative samples based on the number of positive samples. |
|
add_gt_as_proposals=True |
|
), # Whether add GT as proposals after sampling. |
|
mask_size=28, # Size of mask |
|
pos_weight=-1, # The weight of positive samples during training. |
|
debug=False)), # Whether to set the debug mode |
|
test_cfg = dict( # Config for testing hyperparameters for rpn and rcnn |
|
rpn=dict( # The config to generate proposals during testing |
|
nms_across_levels=False, # Whether to do NMS for boxes across levels. Only work in `GARPNHead`, naive rpn does not support do nms cross levels. |
|
nms_pre=1000, # The number of boxes before NMS |
|
nms_post=1000, # The number of boxes to be kept by NMS. Only work in `GARPNHead`. |
|
max_per_img=1000, # The number of boxes to be kept after NMS. |
|
nms=dict( # Config of NMS |
|
type='nms', #Type of NMS |
|
iou_threshold=0.7 # NMS threshold |
|
), |
|
min_bbox_size=0), # The allowed minimal box size |
|
rcnn=dict( # The config for the roi heads. |
|
score_thr=0.05, # Threshold to filter out boxes |
|
nms=dict( # Config of NMS in the second stage |
|
type='nms', # Type of NMS |
|
iou_thr=0.5), # NMS threshold |
|
max_per_img=100, # Max number of detections of each image |
|
mask_thr_binary=0.5))) # Threshold of mask prediction |
|
``` |
|
|
|
### Dataset and evaluator config |
|
|
|
[Dataloaders](https://mmengine.readthedocs.io/en/latest/tutorials/dataset.html) are required for the training, validation, and testing of the [runner](https://mmengine.readthedocs.io/en/latest/tutorials/runner.html). Dataset and data pipeline need to be set to build the dataloader. Due to the complexity of this part, we use intermediate variables to simplify the writing of dataloader configs. |
|
|
|
```python |
|
dataset_type = 'CocoDataset' # Dataset type, this will be used to define the dataset |
|
data_root = 'data/coco/' # Root path of data |
|
backend_args = None # Arguments to instantiate the corresponding file backend |
|
|
|
train_pipeline = [ # Training data processing pipeline |
|
dict(type='LoadImageFromFile', backend_args=backend_args), # First pipeline to load images from file path |
|
dict( |
|
type='LoadAnnotations', # Second pipeline to load annotations for current image |
|
with_bbox=True, # Whether to use bounding box, True for detection |
|
with_mask=True, # Whether to use instance mask, True for instance segmentation |
|
poly2mask=True), # Whether to convert the polygon mask to instance mask, set False for acceleration and to save memory |
|
dict( |
|
type='Resize', # Pipeline that resizes the images and their annotations |
|
scale=(1333, 800), # The largest scale of the images |
|
keep_ratio=True # Whether to keep the ratio between height and width |
|
), |
|
dict( |
|
type='RandomFlip', # Augmentation pipeline that flips the images and their annotations |
|
prob=0.5), # The probability to flip |
|
dict(type='PackDetInputs') # Pipeline that formats the annotation data and decides which keys in the data should be packed into data_samples |
|
] |
|
test_pipeline = [ # Testing data processing pipeline |
|
dict(type='LoadImageFromFile', backend_args=backend_args), # First pipeline to load images from file path |
|
dict(type='Resize', scale=(1333, 800), keep_ratio=True), # Pipeline that resizes the images |
|
dict( |
|
type='PackDetInputs', # Pipeline that formats the annotation data and decides which keys in the data should be packed into data_samples |
|
meta_keys=('img_id', 'img_path', 'ori_shape', 'img_shape', |
|
'scale_factor')) |
|
] |
|
train_dataloader = dict( # Train dataloader config |
|
batch_size=2, # Batch size of a single GPU |
|
num_workers=2, # Worker to pre-fetch data for each single GPU |
|
persistent_workers=True, # If ``True``, the dataloader will not shut down the worker processes after an epoch end, which can accelerate training speed. |
|
sampler=dict( # training data sampler |
|
type='DefaultSampler', # DefaultSampler which supports both distributed and non-distributed training. Refer to https://mmengine.readthedocs.io/en/latest/api/generated/mmengine.dataset.DefaultSampler.html#mmengine.dataset.DefaultSampler |
|
shuffle=True), # randomly shuffle the training data in each epoch |
|
batch_sampler=dict(type='AspectRatioBatchSampler'), # Batch sampler for grouping images with similar aspect ratio into a same batch. It can reduce GPU memory cost. |
|
dataset=dict( # Train dataset config |
|
type=dataset_type, |
|
data_root=data_root, |
|
ann_file='annotations/instances_train2017.json', # Path of annotation file |
|
data_prefix=dict(img='train2017/'), # Prefix of image path |
|
filter_cfg=dict(filter_empty_gt=True, min_size=32), # Config of filtering images and annotations |
|
pipeline=train_pipeline, |
|
backend_args=backend_args)) |
|
val_dataloader = dict( # Validation dataloader config |
|
batch_size=1, # Batch size of a single GPU. If batch-size > 1, the extra padding area may influence the performance. |
|
num_workers=2, # Worker to pre-fetch data for each single GPU |
|
persistent_workers=True, # If ``True``, the dataloader will not shut down the worker processes after an epoch end, which can accelerate training speed. |
|
drop_last=False, # Whether to drop the last incomplete batch, if the dataset size is not divisible by the batch size |
|
sampler=dict( |
|
type='DefaultSampler', |
|
shuffle=False), # not shuffle during validation and testing |
|
dataset=dict( |
|
type=dataset_type, |
|
data_root=data_root, |
|
ann_file='annotations/instances_val2017.json', |
|
data_prefix=dict(img='val2017/'), |
|
test_mode=True, # Turn on the test mode of the dataset to avoid filtering annotations or images |
|
pipeline=test_pipeline, |
|
backend_args=backend_args)) |
|
test_dataloader = val_dataloader # Testing dataloader config |
|
``` |
|
|
|
[Evaluators](https://mmengine.readthedocs.io/en/latest/tutorials/evaluation.html) are used to compute the metrics of the trained model on the validation and testing datasets. The config of evaluators consists of one or a list of metric configs: |
|
|
|
```python |
|
val_evaluator = dict( # Validation evaluator config |
|
type='CocoMetric', # The coco metric used to evaluate AR, AP, and mAP for detection and instance segmentation |
|
ann_file=data_root + 'annotations/instances_val2017.json', # Annotation file path |
|
metric=['bbox', 'segm'], # Metrics to be evaluated, `bbox` for detection and `segm` for instance segmentation |
|
format_only=False, |
|
backend_args=backend_args) |
|
test_evaluator = val_evaluator # Testing evaluator config |
|
``` |
|
|
|
Since the test dataset has no annotation files, the test_dataloader and test_evaluator config in MMDetection are generally equal to the val's. If you want to save the detection results on the test dataset, you can write the config like this: |
|
|
|
```python |
|
# inference on test dataset and |
|
# format the output results for submission. |
|
test_dataloader = dict( |
|
batch_size=1, |
|
num_workers=2, |
|
persistent_workers=True, |
|
drop_last=False, |
|
sampler=dict(type='DefaultSampler', shuffle=False), |
|
dataset=dict( |
|
type=dataset_type, |
|
data_root=data_root, |
|
ann_file=data_root + 'annotations/image_info_test-dev2017.json', |
|
data_prefix=dict(img='test2017/'), |
|
test_mode=True, |
|
pipeline=test_pipeline)) |
|
test_evaluator = dict( |
|
type='CocoMetric', |
|
ann_file=data_root + 'annotations/image_info_test-dev2017.json', |
|
metric=['bbox', 'segm'], # Metrics to be evaluated |
|
format_only=True, # Only format and save the results to coco json file |
|
outfile_prefix='./work_dirs/coco_detection/test') # The prefix of output json files |
|
``` |
|
|
|
### Training and testing config |
|
|
|
MMEngine's runner uses Loop to control the training, validation, and testing processes. |
|
Users can set the maximum training epochs and validation intervals with these fields. |
|
|
|
```python |
|
train_cfg = dict( |
|
type='EpochBasedTrainLoop', # The training loop type. Refer to https://github.com/open-mmlab/mmengine/blob/main/mmengine/runner/loops.py |
|
max_epochs=12, # Maximum training epochs |
|
val_interval=1) # Validation intervals. Run validation every epoch. |
|
val_cfg = dict(type='ValLoop') # The validation loop type |
|
test_cfg = dict(type='TestLoop') # The testing loop type |
|
``` |
|
|
|
### Optimization config |
|
|
|
`optim_wrapper` is the field to configure optimization-related settings. The optimizer wrapper not only provides the functions of the optimizer, but also supports functions such as gradient clipping, mixed precision training, etc. Find more in [optimizer wrapper tutorial](https://mmengine.readthedocs.io/en/latest/tutorials/optim_wrapper.html). |
|
|
|
```python |
|
optim_wrapper = dict( # Optimizer wrapper config |
|
type='OptimWrapper', # Optimizer wrapper type, switch to AmpOptimWrapper to enable mixed precision training. |
|
optimizer=dict( # Optimizer config. Support all kinds of optimizers in PyTorch. Refer to https://pytorch.org/docs/stable/optim.html#algorithms |
|
type='SGD', # Stochastic gradient descent optimizer |
|
lr=0.02, # The base learning rate |
|
momentum=0.9, # Stochastic gradient descent with momentum |
|
weight_decay=0.0001), # Weight decay of SGD |
|
clip_grad=None, # Gradient clip option. Set None to disable gradient clip. Find usage in https://mmengine.readthedocs.io/en/latest/tutorials/optimizer.html |
|
) |
|
``` |
|
|
|
`param_scheduler` is a field that configures methods of adjusting optimization hyperparameters such as learning rate and momentum. Users can combine multiple schedulers to create a desired parameter adjustment strategy. Find more in [parameter scheduler tutorial](https://mmengine.readthedocs.io/en/latest/tutorials/param_scheduler.html) and [parameter scheduler API documents](https://mmengine.readthedocs.io/en/latest/api/generated/mmengine.optim._ParamScheduler.html#mmengine.optim._ParamScheduler) |
|
|
|
```python |
|
param_scheduler = [ |
|
# Linear learning rate warm-up scheduler |
|
dict( |
|
type='LinearLR', # Use linear policy to warmup learning rate |
|
start_factor=0.001, # The ratio of the starting learning rate used for warmup |
|
by_epoch=False, # The warmup learning rate is updated by iteration |
|
begin=0, # Start from the first iteration |
|
end=500), # End the warmup at the 500th iteration |
|
# The main LRScheduler |
|
dict( |
|
type='MultiStepLR', # Use multi-step learning rate policy during training |
|
by_epoch=True, # The learning rate is updated by epoch |
|
begin=0, # Start from the first epoch |
|
end=12, # End at the 12th epoch |
|
milestones=[8, 11], # Epochs to decay the learning rate |
|
gamma=0.1) # The learning rate decay ratio |
|
] |
|
``` |
|
|
|
### Hook config |
|
|
|
Users can attach Hooks to training, validation, and testing loops to insert some operations during running. There are two different hook fields, one is `default_hooks` and the other is `custom_hooks`. |
|
|
|
`default_hooks` is a dict of hook configs, and they are the hooks must be required at the runtime. They have default priority which should not be modified. If not set, runner will use the default values. To disable a default hook, users can set its config to `None`. Find more in [HOOK](https://mmengine.readthedocs.io/en/latest/tutorials/hook.html). |
|
|
|
```python |
|
default_hooks = dict( |
|
timer=dict(type='IterTimerHook'), # Update the time spent during iteration into message hub |
|
logger=dict(type='LoggerHook', interval=50), # Collect logs from different components of Runner and write them to terminal, JSON file, tensorboard and wandb .etc |
|
param_scheduler=dict(type='ParamSchedulerHook'), # update some hyper-parameters of optimizer |
|
checkpoint=dict(type='CheckpointHook', interval=1), # Save checkpoints periodically |
|
sampler_seed=dict(type='DistSamplerSeedHook'), # Ensure distributed Sampler shuffle is active |
|
visualization=dict(type='DetVisualizationHook')) # Detection Visualization Hook. Used to visualize validation and testing process prediction results |
|
``` |
|
|
|
`custom_hooks` is a list of all other hook configs. Users can develop their own hooks and insert them in this field. |
|
|
|
```python |
|
custom_hooks = [] |
|
``` |
|
|
|
### Runtime config |
|
|
|
```python |
|
default_scope = 'mmdet' # The default registry scope to find modules. Refer to https://mmengine.readthedocs.io/en/latest/advanced_tutorials/registry.html |
|
|
|
env_cfg = dict( |
|
cudnn_benchmark=False, # Whether to enable cudnn benchmark |
|
mp_cfg=dict( # Multi-processing config |
|
mp_start_method='fork', # Use fork to start multi-processing threads. 'fork' usually faster than 'spawn' but maybe unsafe. See discussion in https://github.com/pytorch/pytorch/issues/1355 |
|
opencv_num_threads=0), # Disable opencv multi-threads to avoid system being overloaded |
|
dist_cfg=dict(backend='nccl'), # Distribution configs |
|
) |
|
|
|
vis_backends = [dict(type='LocalVisBackend')] # Visualization backends. Refer to https://mmengine.readthedocs.io/en/latest/advanced_tutorials/visualization.html |
|
visualizer = dict( |
|
type='DetLocalVisualizer', vis_backends=vis_backends, name='visualizer') |
|
log_processor = dict( |
|
type='LogProcessor', # Log processor to process runtime logs |
|
window_size=50, # Smooth interval of log values |
|
by_epoch=True) # Whether to format logs with epoch type. Should be consistent with the train loop's type. |
|
|
|
log_level = 'INFO' # The level of logging. |
|
load_from = None # Load model checkpoint as a pre-trained model from a given path. This will not resume training. |
|
resume = False # Whether to resume from the checkpoint defined in `load_from`. If `load_from` is None, it will resume the latest checkpoint in the `work_dir`. |
|
``` |
|
|
|
## Iter-based config |
|
|
|
MMEngine's Runner also provides an iter-based training loop except for epoch-based. |
|
To use iter-based training, users should modify the `train_cfg`, `param_scheduler`, `train_dataloader`, `default_hooks`, and `log_processor`. |
|
Here is an example of changing an epoch-based RetinaNet config to iter-based: `configs/retinanet/retinanet_r50_fpn_90k_coco.py` |
|
|
|
```python |
|
# Iter-based training config |
|
train_cfg = dict( |
|
_delete_=True, # Ignore the base config setting (optional) |
|
type='IterBasedTrainLoop', # Use iter-based training loop |
|
max_iters=90000, # Maximum iterations |
|
val_interval=10000) # Validation interval |
|
|
|
|
|
# Change the scheduler to iter-based |
|
param_scheduler = [ |
|
dict( |
|
type='LinearLR', start_factor=0.001, by_epoch=False, begin=0, end=500), |
|
dict( |
|
type='MultiStepLR', |
|
begin=0, |
|
end=90000, |
|
by_epoch=False, |
|
milestones=[60000, 80000], |
|
gamma=0.1) |
|
] |
|
|
|
# Switch to InfiniteSampler to avoid dataloader restart |
|
train_dataloader = dict(sampler=dict(type='InfiniteSampler')) |
|
|
|
# Change the checkpoint saving interval to iter-based |
|
default_hooks = dict(checkpoint=dict(by_epoch=False, interval=10000)) |
|
|
|
# Change the log format to iter-based |
|
log_processor = dict(by_epoch=False) |
|
``` |
|
|
|
## Config file inheritance |
|
|
|
There are 4 basic component types under `config/_base_`, dataset, model, schedule, default_runtime. |
|
Many methods could be easily constructed with one of these models like Faster R-CNN, Mask R-CNN, Cascade R-CNN, RPN, SSD. |
|
The configs that are composed by components from `_base_` are called the _primitive_. |
|
|
|
For all configs under the same folder, it is recommended to have only **one** _primitive_ config. All other configs should inherit from the _primitive_ config. In this way, the maximum of inheritance level is 3. |
|
|
|
For easy understanding, we recommend contributors to inherit from existing methods. |
|
For example, if some modification is made based on Faster R-CNN, users may first inherit the basic Faster R-CNN structure by specifying `_base_ = ../faster_rcnn/faster-rcnn_r50_fpn_1x_coco.py`, then modify the necessary fields in the config files. |
|
|
|
If you are building an entirely new method that does not share the structure with any of the existing methods, you may create a folder `xxx_rcnn` under `configs`, |
|
|
|
Please refer to [mmengine config tutorial](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/config.html) for detailed documentation. |
|
|
|
By setting the `_base_` field, we can set which files the current configuration file inherits from. |
|
|
|
When `_base_` is a string of a file path, it means inheriting the contents from one config file. |
|
|
|
```python |
|
_base_ = './mask-rcnn_r50_fpn_1x_coco.py' |
|
``` |
|
|
|
When `_base_` is a list of multiple file paths, it means inheriting from multiple files. |
|
|
|
```python |
|
_base_ = [ |
|
'../_base_/models/mask-rcnn_r50_fpn.py', |
|
'../_base_/datasets/coco_instance.py', |
|
'../_base_/schedules/schedule_1x.py', '../_base_/default_runtime.py' |
|
] |
|
``` |
|
|
|
If you wish to inspect the config file, you may run `python tools/misc/print_config.py /PATH/TO/CONFIG` to see the complete config. |
|
|
|
### Ignore some fields in the base configs |
|
|
|
Sometimes, you may set `_delete_=True` to ignore some of the fields in base configs. |
|
You may refer to [mmengine config tutorial](https://mmengine.readthedocs.io/en/latest/advanced_tutorials/config.html) for a simple illustration. |
|
|
|
In MMDetection, for example, to change the backbone of Mask R-CNN with the following config. |
|
|
|
```python |
|
model = dict( |
|
type='MaskRCNN', |
|
backbone=dict( |
|
type='ResNet', |
|
depth=50, |
|
num_stages=4, |
|
out_indices=(0, 1, 2, 3), |
|
frozen_stages=1, |
|
norm_cfg=dict(type='BN', requires_grad=True), |
|
norm_eval=True, |
|
style='pytorch', |
|
init_cfg=dict(type='Pretrained', checkpoint='torchvision://resnet50')), |
|
neck=dict(...), |
|
rpn_head=dict(...), |
|
roi_head=dict(...)) |
|
``` |
|
|
|
`ResNet` and `HRNet` use different keywords to construct. |
|
|
|
```python |
|
_base_ = '../mask_rcnn/mask-rcnn_r50_fpn_1x_coco.py' |
|
model = dict( |
|
backbone=dict( |
|
_delete_=True, |
|
type='HRNet', |
|
extra=dict( |
|
stage1=dict( |
|
num_modules=1, |
|
num_branches=1, |
|
block='BOTTLENECK', |
|
num_blocks=(4, ), |
|
num_channels=(64, )), |
|
stage2=dict( |
|
num_modules=1, |
|
num_branches=2, |
|
block='BASIC', |
|
num_blocks=(4, 4), |
|
num_channels=(32, 64)), |
|
stage3=dict( |
|
num_modules=4, |
|
num_branches=3, |
|
block='BASIC', |
|
num_blocks=(4, 4, 4), |
|
num_channels=(32, 64, 128)), |
|
stage4=dict( |
|
num_modules=3, |
|
num_branches=4, |
|
block='BASIC', |
|
num_blocks=(4, 4, 4, 4), |
|
num_channels=(32, 64, 128, 256))), |
|
init_cfg=dict(type='Pretrained', checkpoint='open-mmlab://msra/hrnetv2_w32')), |
|
neck=dict(...)) |
|
``` |
|
|
|
The `_delete_=True` would replace all old keys in `backbone` field with new keys. |
|
|
|
### Use intermediate variables in configs |
|
|
|
Some intermediate variables are used in the configs files, like `train_pipeline`/`test_pipeline` in datasets. |
|
It's worth noting that when modifying intermediate variables in the children configs, users need to pass the intermediate variables into corresponding fields again. |
|
For example, we would like to use a multi-scale strategy to train a Mask R-CNN. `train_pipeline`/`test_pipeline` are intermediate variables we would like to modify. |
|
|
|
```python |
|
_base_ = './mask-rcnn_r50_fpn_1x_coco.py' |
|
|
|
train_pipeline = [ |
|
dict(type='LoadImageFromFile'), |
|
dict(type='LoadAnnotations', with_bbox=True, with_mask=True), |
|
dict( |
|
type='RandomResize', scale=[(1333, 640), (1333, 800)], |
|
keep_ratio=True), |
|
dict(type='RandomFlip', prob=0.5), |
|
dict(type='PackDetInputs') |
|
] |
|
test_pipeline = [ |
|
dict(type='LoadImageFromFile'), |
|
dict(type='Resize', scale=(1333, 800), keep_ratio=True), |
|
dict( |
|
type='PackDetInputs', |
|
meta_keys=('img_id', 'img_path', 'ori_shape', 'img_shape', |
|
'scale_factor')) |
|
] |
|
train_dataloader = dict(dataset=dict(pipeline=train_pipeline)) |
|
val_dataloader = dict(dataset=dict(pipeline=test_pipeline)) |
|
test_dataloader = dict(dataset=dict(pipeline=test_pipeline)) |
|
``` |
|
|
|
We first define the new `train_pipeline`/`test_pipeline` and pass them into dataloader fields. |
|
|
|
Similarly, if we would like to switch from `SyncBN` to `BN` or `MMSyncBN`, we need to substitute every `norm_cfg` in the config. |
|
|
|
```python |
|
_base_ = './mask-rcnn_r50_fpn_1x_coco.py' |
|
norm_cfg = dict(type='BN', requires_grad=True) |
|
model = dict( |
|
backbone=dict(norm_cfg=norm_cfg), |
|
neck=dict(norm_cfg=norm_cfg), |
|
...) |
|
``` |
|
|
|
### Reuse variables in \_base\_ file |
|
|
|
If the users want to reuse the variables in the base file, they can get a copy of the corresponding variable by using `{{_base_.xxx}}`. E.g: |
|
|
|
```python |
|
_base_ = './mask-rcnn_r50_fpn_1x_coco.py' |
|
|
|
a = {{_base_.model}} # Variable `a` is equal to the `model` defined in `_base_` |
|
``` |
|
|
|
## Modify config through script arguments |
|
|
|
When submitting jobs using `tools/train.py` or `tools/test.py`, you may specify `--cfg-options` to in-place modify the config. |
|
|
|
- Update config keys of dict chains. |
|
|
|
The config options can be specified following the order of the dict keys in the original config. |
|
For example, `--cfg-options model.backbone.norm_eval=False` changes the all BN modules in model backbones to `train` mode. |
|
|
|
- Update keys inside a list of configs. |
|
|
|
Some config dicts are composed as a list in your config. For example, the training pipeline `train_dataloader.dataset.pipeline` is normally a list |
|
e.g. `[dict(type='LoadImageFromFile'), ...]`. If you want to change `'LoadImageFromFile'` to `'LoadImageFromNDArray'` in the pipeline, |
|
you may specify `--cfg-options data.train.pipeline.0.type=LoadImageFromNDArray`. |
|
|
|
- Update values of list/tuples. |
|
|
|
If the value to be updated is a list or a tuple. For example, the config file normally sets `model.data_preprocessor.mean=[123.675, 116.28, 103.53]`. If you want to |
|
change the mean values, you may specify `--cfg-options model.data_preprocessor.mean="[127,127,127]"`. Note that the quotation mark `"` is necessary to |
|
support list/tuple data types, and **NO** white space is allowed inside the quotation marks in the specified value. |
|
|
|
## Config name style |
|
|
|
We follow the below style to name config files. Contributors are advised to follow the same style. |
|
|
|
``` |
|
{algorithm name}_{model component names [component1]_[component2]_[...]}_{training settings}_{training dataset information}_{testing dataset information}.py |
|
``` |
|
|
|
The file name is divided into five parts. All parts and components are connected with `_` and words of each part or component should be connected with `-`. |
|
|
|
- `{algorithm name}`: The name of the algorithm. It can be a detector name such as `faster-rcnn`, `mask-rcnn`, etc. Or can be a semi-supervised or knowledge-distillation algorithm such as `soft-teacher`, `lad`. etc. |
|
- `{model component names}`: Names of the components used in the algorithm such as backbone, neck, etc. For example, `r50-caffe_fpn_gn-head` means using caffe-style ResNet50, FPN and detection head with Group Norm in the algorithm. |
|
- `{training settings}`: Information of training settings such as batch size, augmentations, loss trick, scheduler, and epochs/iterations. For example: `4xb4-mixup-giou-coslr-100e` means using 8-gpus x 4-images-per-gpu, mixup augmentation, GIoU loss, cosine annealing learning rate, and train 100 epochs. |
|
Some abbreviations: |
|
- `{gpu x batch_per_gpu}`: GPUs and samples per GPU. `bN` indicates N batch size per GPU. E.g. `4xb4` is the short term of 4-GPUs x 4-images-per-GPU. And `8xb2` is used by default if not mentioned. |
|
- `{schedule}`: training schedule, options are `1x`, `2x`, `20e`, etc. |
|
`1x` and `2x` means 12 epochs and 24 epochs respectively. |
|
`20e` is adopted in cascade models, which denotes 20 epochs. |
|
For `1x`/`2x`, the initial learning rate decays by a factor of 10 at the 8/16th and 11/22th epochs. |
|
For `20e`, the initial learning rate decays by a factor of 10 at the 16th and 19th epochs. |
|
- `{training dataset information}`: Training dataset names like `coco`, `coco-panoptic`, `cityscapes`, `voc-0712`, `wider-face`. |
|
- `{testing dataset information}` (optional): Testing dataset name for models trained on one dataset but tested on another. If not mentioned, it means the model was trained and tested on the same dataset type. |
|
|