From 6c3599bd9dd7106de7b9167e5e5113e72e9ea435 Mon Sep 17 00:00:00 2001 From: CSH <40987381+csatsurnh@users.noreply.github.com> Date: Tue, 7 Mar 2023 11:47:10 +0800 Subject: [PATCH] [Doc] Add zh_cn models doc and fix en doc typo (#2703) as title --------- Co-authored-by: Miao Zheng <76149310+MeowZheng@users.noreply.github.com> --- docs/en/advanced_guides/models.md | 10 +- docs/zh_cn/advanced_guides/models.md | 176 ++++++++++++++++++++++++++- 2 files changed, 179 insertions(+), 7 deletions(-) diff --git a/docs/en/advanced_guides/models.md b/docs/en/advanced_guides/models.md index 8202e95b..84e6cb6a 100644 --- a/docs/en/advanced_guides/models.md +++ b/docs/en/advanced_guides/models.md @@ -1,7 +1,5 @@ # Models -# Models - We usually define a neural network in a deep learning task as a model, and this model is the core of an algorithm. [MMEngine](https://github.com/open-mmlab/mmengine) abstracts a unified model [BaseModel](https://github.com/open-mmlab/mmengine/blob/main/mmengine/model/base_model/base_model.py#L16) to standardize the interfaces for training, testing and other processes. All models implemented by MMSegmentation inherit from `BaseModel`, and in MMSegmentation we implemented forward and added some functions for the semantic segmentation algorithm. ## Common components @@ -22,9 +20,9 @@ In MMSegmentation, we abstract the network architecture as a **Segmentor**, it i **Neck** is the part that connects the backbone and heads. It performs some refinements or reconfigurations on the raw feature maps produced by the backbone. An example is **Feature Pyramid Network (FPN)**. -### Decode Head +### Decode head -**Decode Head** is the part that transforms the feature maps into a segmentation mask, such as **PSPNet**. +**Decode head** is the part that transforms the feature maps into a segmentation mask, such as **PSPNet**. ### Auxiliary head @@ -110,7 +108,7 @@ Parameters: - data (dict or tuple or list) - Data sampled from the dataset. In MMSegmentation, the data dict contains `inputs` and `data_samples` two fields. - optim_wrapper (OptimWrapper) - OptimWrapper instance used to update model parameters. -**Note:** [OptimWrapper](https://github.com/open-mmlab/mmengine/blob/main/mmengine/optim/optimizer/optimizer_wrapper.py#L17) provides a common interface for updating parameters, please refer to optimizer wrapper [documentation](https://mmengine.readthedocs.io/zh_CN/latest/tutorials/optim_wrapper.html) in [MMEngine](https://github.com/open-mmlab/mmengine) for more information. +**Note:** [OptimWrapper](https://github.com/open-mmlab/mmengine/blob/main/mmengine/optim/optimizer/optimizer_wrapper.py#L17) provides a common interface for updating parameters, please refer to optimizer wrapper [documentation](https://mmengine.readthedocs.io/en/latest/tutorials/optim_wrapper.html) in [MMEngine](https://github.com/open-mmlab/mmengine) for more information. Returns: @@ -157,7 +155,7 @@ The parameters of the `SegDataPreProcessor` constructor: - pad_val (float, optional) - Padding value. Default: 0. - seg_pad_val (float, optional) - Padding value of segmentation map. Default: 255. - bgr_to_rgb (bool) - whether to convert image from BGR to RGB. Defaults to False. -- rgb_to_bgr (bool) - whether to convert image from RGB to RGB. Defaults to False. +- rgb_to_bgr (bool) - whether to convert image from RGB to BGR. Defaults to False. - batch_augments (list\[dict\], optional) - Batch-level augmentations. Default to None. The data will be processed as follows: diff --git a/docs/zh_cn/advanced_guides/models.md b/docs/zh_cn/advanced_guides/models.md index 62dbea38..408a5786 100644 --- a/docs/zh_cn/advanced_guides/models.md +++ b/docs/zh_cn/advanced_guides/models.md @@ -1,3 +1,177 @@ # 模型 -ä¸æ–‡ç‰ˆæ–‡æ¡£æ”¯æŒä¸ï¼Œè¯·å…ˆé˜…读[英文版本](../../en/advanced_guides/models.md) +我们通常将深度å¦ä¹ 任务ä¸çš„神ç»ç½‘络定义为模型,这个模型å³æ˜¯ç®—æ³•çš„æ ¸å¿ƒã€‚[MMEngine](https://github.com/open-mmlab/mmengine) 抽象出了一个统一模型 [BaseModel](https://github.com/open-mmlab/mmengine/blob/main/mmengine/model/base_model/base_model.py#L16) ä»¥æ ‡å‡†åŒ–è®ç»ƒã€æµ‹è¯•å’Œå…¶ä»–过程。MMSegmentation 实现的所有模型都继承自 `BaseModel`,并且在 MMSegmention ä¸ï¼Œæˆ‘们实现了å‰å‘ä¼ æ’并为è¯ä¹‰åˆ†å‰²ç®—æ³•æ·»åŠ äº†ä¸€äº›åŠŸèƒ½ã€‚ + +## 常用组件 + +### 分割器(Segmentor) + +在 MMSegmentation ä¸ï¼Œæˆ‘们将网络架构抽象为**分割器**,它是一个包å«ç½‘络所有组件的模型。我们已ç»å®žçŽ°äº†**ç¼–ç 器解ç 器(EncoderDecoder)**å’Œ**级è”ç¼–ç 器解ç 器(CascadeEncoderDecoder)**,它们通常由**æ•°æ®é¢„处ç†å™¨**ã€**骨干网络**ã€**解ç 头**å’Œ**辅助头**组æˆã€‚ + +### æ•°æ®é¢„处ç†å™¨ï¼ˆData preprocessor) + +**æ•°æ®é¢„处ç†å™¨**是将数æ®å¤åˆ¶åˆ°ç›®æ ‡è®¾å¤‡å¹¶å°†æ•°æ®é¢„处ç†ä¸ºæ¨¡åž‹è¾“å…¥æ ¼å¼çš„部分。 + +### 主干网络(Backbone) + +**主干网络**是将图åƒè½¬æ¢ä¸ºç‰¹å¾å›¾çš„部分,例如没有最åŽå…¨è¿žæŽ¥å±‚çš„ **ResNet-50**。 + +### 颈部(Neck) + +**颈部**是连接主干网络和头的部分。它对主干网络生æˆçš„原始特å¾å›¾è¿›è¡Œä¸€äº›æ”¹è¿›æˆ–é‡æ–°é…置。例如 **Feature Pyramid Network(FPN)**。 + +### 解ç 头(Decode head) + +**解ç 头**是将特å¾å›¾è½¬æ¢ä¸ºåˆ†å‰²æŽ©è†œçš„部分,例如 **PSPNet**。 + +### 辅助头(Auxiliary head) + +**辅助头**是一个å¯é€‰ç»„件,它将特å¾å›¾è½¬æ¢ä¸ºä»…用于计算辅助æŸå¤±çš„分割掩膜。 + +## åŸºæœ¬æŽ¥å£ + +MMSegmentation å°è£… `BaseModel` 并实现了 [BaseSegmenter](https://github.com/open-mmlab/mmsegmentation/blob/1.x/mmseg/models/segmentors/base.py#L15) 类,主è¦æä¾› `forward`ã€`train_step`ã€`val_step` å’Œ `test_step` 接å£ã€‚接下æ¥å°†è¯¦ç»†ä»‹ç»è¿™äº›æŽ¥å£ã€‚ + +### forward + +<center> + <img src='../../../resources/encoder_decoder_dataflow.png' /> + <center>ç¼–ç 器解ç 器数æ®æµ</center> +</center> + +<center> + <center><img src='../../../resources/cascade_encoder_decoder_dataflow.png' /></center> + <center>级è”ç¼–ç 器解ç 器数æ®æµ</center> +</center> + +`forward` 方法返回è®ç»ƒã€éªŒè¯ã€æµ‹è¯•å’Œç®€å•æŽ¨ç†è¿‡ç¨‹çš„æŸå¤±æˆ–预测。 + +该方法应接å—三ç§æ¨¡å¼ï¼šâ€œtensorâ€ã€â€œpredict†和 “lossâ€ï¼š + +- “tensorâ€ï¼šå‰å‘推ç†æ•´ä¸ªç½‘ç»œå¹¶è¿”å›žå¼ é‡æˆ–å¼ é‡æ•°ç»„ï¼Œæ— éœ€ä»»ä½•åŽå¤„ç†ï¼Œä¸Žå¸¸è§çš„ `nn.Module` 相åŒã€‚ +- “predictâ€ï¼šå‰å‘推ç†å¹¶è¿”回预测值,这些预测值将被完全处ç†åˆ° `SegDataSample` 列表ä¸ã€‚ +- “lossâ€ï¼šå‰å‘推ç†å¹¶æ ¹æ®ç»™å®šçš„输入和数æ®æ ·æœ¬è¿”回æŸå¤±çš„`å—å…¸`。 + +**注:**[SegDataSample](https://github.com/open-mmlab/mmsegmentation/blob/1.x/mmseg/structures/seg_data_sample.py) 是 MMSegmentation çš„æ•°æ®ç»“构接å£ï¼Œç”¨ä½œä¸åŒç»„件之间的接å£ã€‚`SegDataSample` 实现了抽象数æ®å…ƒç´ `mmengine.structures.BaseDataElement`,请å‚阅 [MMMEngine](https://github.com/open-mmlab/mmengine) ä¸çš„ [SegDataSample 文档](https://mmsegmentation.readthedocs.io/zh_CN/1.x/advanced_guides/structures.html)å’Œ[æ•°æ®å…ƒç´ 文档](https://mmengine.readthedocs.io/zh_CN/latest/advanced_tutorials/data_element.html)了解更多信æ¯ã€‚ + +注æ„,æ¤æ–¹æ³•ä¸å¤„ç†åœ¨ `train_step` 方法ä¸å®Œæˆçš„åå‘ä¼ æ’或优化器更新。 + +å‚数: + +- inputs(torch.Tensor)- 通常为形状是(N, C, ...) çš„è¾“å…¥å¼ é‡ã€‚ +- data_sample(list\[[SegDataSample](https://github.com/open-mmlab/mmsegmentation/blob/1.x/mmseg/structures/seg_data_sample.py)\]) - 分割数æ®æ ·æœ¬ã€‚它通常包括 `metainfo` å’Œ `gt_sem_seg` ç‰ä¿¡æ¯ã€‚默认值为 None。 +- mode (str) - 返回什么类型的值。默认为 'tensor'。 + +返回值: + +- `dict` 或 `list`: + - 如果 `mode == "loss"`,则返回用于åå‘过程和日志记录的æŸå¤±å¼ é‡`å—å…¸`。 + - 如果 `mode == "predict"`,则返回 `SegDataSample` çš„`列表`,推ç†ç»“æžœå°†è¢«é€’å¢žåœ°æ·»åŠ åˆ°ä¼ é€’ç»™ forward 方法的 `data_sample` å‚æ•°ä¸ï¼Œæ¯ä¸ª `SegDataSeample` 包å«ä»¥ä¸‹å…³é”®è¯ï¼š + - pred_sm_seg (`PixelData`):è¯ä¹‰åˆ†å‰²çš„预测。 + - seg_logits (`PixelData`)ï¼šæ ‡å‡†åŒ–å‰è¯ä¹‰åˆ†å‰²çš„é¢„æµ‹æŒ‡æ ‡ã€‚ + - 如果 `mode == "tensor"`,则返回`å¼ é‡`或`å¼ é‡æ•°ç»„`çš„`å—å…¸`以供自定义使用。 + +### é¢„æµ‹æ¨¡å¼ + +我们在[é…置文档](../user_guides/1_config.md)ä¸ç®€è¦æ述了模型é…置的å—æ®µï¼Œè¿™é‡Œæˆ‘ä»¬è¯¦ç»†ä»‹ç» `model.test_cfg` å—段。`model.test_cfg` 用于控制å‰å‘行为,`"predict"` 模å¼ä¸‹çš„ `forward` 方法å¯ä»¥åœ¨ä¸¤ç§æ¨¡å¼ä¸‹è¿è¡Œï¼š + +- `whole_inference`:如果 `cfg.model.test_cfg.mode == 'whole'`,则模型将使用完整图åƒè¿›è¡ŒæŽ¨ç†ã€‚ + + `whole_inference` 模å¼çš„一个示例é…置: + + ```python + model = dict( + type='EncoderDecoder' + ... + test_cfg=dict(mode='whole') + ) + ``` + +- `slide_inference`:如果 `cfg.model.test_cfg.mode == ‘slide’`,则模型将通过滑动窗å£è¿›è¡ŒæŽ¨ç†ã€‚**注æ„:** 如果选择 `slide` 模å¼ï¼Œè¿˜åº”指定 `cfg.model.test_cfg.stride` å’Œ `cfg.model.test_cfg.crop_size`。 + + `slide_inference` 模å¼çš„一个示例é…置: + + ```python + model = dict( + type='EncoderDecoder' + ... + test_cfg=dict(mode='slide', crop_size=256, stride=170) + ) + ``` + +### train_step + +`train_step` 方法调用 `loss` 模å¼çš„å‰å‘接å£ä»¥èŽ·å¾—æŸå¤±`å—å…¸`。`BaseModel` 类实现默认的模型è®ç»ƒè¿‡ç¨‹ï¼ŒåŒ…括预处ç†ã€æ¨¡åž‹å‰å‘ä¼ æ’ã€æŸå¤±è®¡ç®—ã€ä¼˜åŒ–å’Œåå‘ä¼ æ’。 + +å‚数: + +- data (dict or tuple or list) - 从数æ®é›†é‡‡æ ·çš„æ•°æ®ã€‚在 MMSegmentation ä¸ï¼Œæ•°æ®å—å…¸åŒ…å« `inputs` å’Œ `data_samples` 两个å—段。 +- optim_wrapper (OptimWrapper) - 用于更新模型å‚æ•°çš„ OptimWrapper 实例。 + +**注:**[OptimWrapper](https://github.com/open-mmlab/mmengine/blob/main/mmengine/optim/optimizer/optimizer_wrapper.py#L17) æ供了一个用于更新å‚数的通用接å£ï¼Œè¯·å‚阅 [MMMEngine](https://github.com/open-mmlab/mmengine) ä¸çš„优化器å°è£…[文档](https://mmengine.readthedocs.io/zh_CN/latest/tutorials/optim_wrapper.html)了解更多信æ¯ã€‚ + +返回值: + +-Dict\[str, `torch.Tensor`\]ï¼šç”¨äºŽè®°å½•æ—¥å¿—çš„å¼ é‡çš„`å—å…¸`。 + +<center> + <img src='../../../resources/train_step.png' /> + <center>train_step æ•°æ®æµ</center> +</center> + +### val_step + +`val_step` 方法调用 `predict` 模å¼çš„å‰å‘接å£å¹¶è¿”回预测结果,预测结果将进一æ¥è¢«ä¼ 递给评测器的进程接å£å’Œé’©åçš„ `after_val_inter` 接å£ã€‚ + +å‚数: + +- data (`dict` or `tuple` or `list`) - 从数æ®é›†ä¸é‡‡æ ·çš„æ•°æ®ã€‚在 MMSegmentation ä¸ï¼Œæ•°æ®å—å…¸åŒ…å« `inputs` å’Œ `data_samples` 两个å—段。 + +返回值: + +- `list` - 给定数æ®çš„预测结果。 + +<center> + <img src='../../../resources/test_step.png' /> + <center>test_step/val_step æ•°æ®æµ</center> +</center> + +### test_step + +`BaseModel` ä¸ `test_step` 与 `val_step` 的实现相åŒã€‚ + +## æ•°æ®é¢„处ç†å™¨ï¼ˆData Preprocessor) + +MMSegmentation 实现的 [SegDataPreProcessor](https://github.com/open-mmlab/mmsegmentation/blob/1.x/mmseg/models/data_preprocessor.py#L13) 继承自由 [MMEngine](https://github.com/open-mmlab/mmengine) 实现的 [BaseDataPreprocessor](https://github.com/open-mmlab/mmengine/blob/main/mmengine/model/base_model/data_preprocessor.py#L18),æ供数æ®é¢„处ç†å’Œå°†æ•°æ®å¤åˆ¶åˆ°ç›®æ ‡è®¾å¤‡çš„功能。 + +Runner åœ¨æž„å»ºé˜¶æ®µå°†æ¨¡åž‹ä¼ é€åˆ°æŒ‡å®šçš„设备,而 [SegDataPreProcessor](https://github.com/open-mmlab/mmsegmentation/blob/1.x/mmseg/models/data_preprocessor.py#L13) 在 `train_step`ã€`val_step` å’Œ `test_step` ä¸å°†æ•°æ®ä¼ é€åˆ°æŒ‡å®šè®¾å¤‡ï¼Œä¹‹åŽå¤„ç†åŽçš„æ•°æ®å°†è¢«è¿›ä¸€æ¥ä¼ 递给模型。 + +`SegDataPreProcessor` æž„é€ å‡½æ•°çš„å‚数: + +- mean (Sequence\[Number\], å¯é€‰) - Rã€Gã€B 通é“çš„åƒç´ å¹³å‡å€¼ã€‚默认为 None。 +- std (Sequence\[Number\], å¯é€‰) - Rã€Gã€B 通é“çš„åƒç´ æ ‡å‡†å·®ã€‚é»˜è®¤ä¸º None。 +- size (tuple, å¯é€‰) - 固定的填充大å°ã€‚ +- size_divisor (int, å¯é€‰) - 填充大å°çš„é™¤æ³•å› å。 +- pad_val (float, å¯é€‰) - 填充值。默认值:0。 +- seg_pad_val (float, å¯é€‰) - 分割图的填充值。默认值:255。 +- bgr_to_rgb (bool) - 是å¦å°†å›¾åƒä»Ž BGR 转æ¢ä¸º RGB。默认为 False。 +- rgb_to_bgr (bool) - 是å¦å°†å›¾åƒä»Ž RGB 转æ¢ä¸º BGR。默认为 False。 +- batch_augments (list\[dict\], å¯é€‰) - 批é‡åŒ–çš„æ•°æ®å¢žå¼ºã€‚默认值为 None。 + +æ•°æ®å°†æŒ‰å¦‚下方å¼å¤„ç†ï¼š + +- 收集数æ®å¹¶å°†å…¶ç§»åŠ¨åˆ°ç›®æ ‡è®¾å¤‡ã€‚ +- 用定义的 `pad_val` 将输入填充到输入大å°ï¼Œå¹¶ç”¨å®šä¹‰çš„ `seg_Pad_val` 填充分割图。 +- å°†è¾“å…¥å †æ ˆåˆ° batch_input。 +- 如果输入的形状为 (3, H, W),则将输入从 BGR 转æ¢ä¸º RGB。 +- ä½¿ç”¨å®šä¹‰çš„æ ‡å‡†å·®å’Œå¹³å‡å€¼æ ‡å‡†åŒ–图åƒã€‚ +- 在è®ç»ƒæœŸé—´è¿›è¡Œå¦‚ Mixup å’Œ Cutmix 的批é‡åŒ–æ•°æ®å¢žå¼ºã€‚ + +`forward` 方法的å‚数: + +- data (dict) - 从数æ®åŠ è½½å™¨é‡‡æ ·çš„æ•°æ®ã€‚ +- training (bool) - 是å¦å¯ç”¨è®ç»ƒæ—¶æ•°æ®å¢žå¼ºã€‚ + +`forward` 方法的返回值: + +- Dictï¼šä¸Žæ¨¡åž‹è¾“å…¥æ ¼å¼ç›¸åŒçš„æ•°æ®ã€‚ -- GitLab