docs: bug fixes, update docs (#271)

* feat: lazy import and auto install

* chore: add docs module

* fix: dummy input shape and import error

* chore: sync quantizer from upstream

* chore: restore vitepress pkgs

* refactor: lazy import support arch spec

* chore: sync latest buggy qta script

* fix: auto adjust img size based on model's input shape

* fix: update class meta from real datasets

* fix: import errors, auto install missing deps

* fix: add missing quan switch hook

* fix: wrong val worker numbers

* fix: custom datasets path, rtmdet qat config

* docs: update docs

* chore: ignore .npy file

* chore: cleanup

* fix: file name typo

* docs: allow remote access by default

* fix: workdir, input quantize sta, stale configs

* fix: workdir

* fix: sync batch norm breaks qat export

* docs: update contents

---------

Co-authored-by: nullptr <nullptr@localhost>
Co-authored-by: Baozhu Zuo <[email protected]>

Author: 3 people

.gitignore

@@ -58,3 +58,6 @@ docs/.vitepress/dist
 examples/
 work_dir/
 data/
+
+# numpy
+*.npy

configs/datasets/coco_detection.py

@@ -13,6 +13,10 @@
 # dataset settings
 dataset_type = CocoDataset
 data_root = "datasets/coco/"
+train_ann_file = "annotations/instances_train2017.json"
+val_ann_file = "annotations/instances_val2017.json"
+train_img_prefix = "train2017/"
+val_img_prefix = "val2017/"
 
 # Example to use different file client
 # Method 1: simply set the data root and let the file I/O module
@@ -68,8 +72,8 @@
     dataset=dict(
         type=dataset_type,
         data_root=data_root,
-        ann_file="annotations/instances_train2017.json",
-        data_prefix=dict(img="train2017/"),
+        ann_file=train_ann_file,
+        data_prefix=dict(img=train_img_prefix),
         filter_cfg=dict(filter_empty_gt=True, min_size=32),
         pipeline=train_pipeline,
     ),
@@ -84,8 +88,8 @@
     dataset=dict(
         type=dataset_type,
         data_root=data_root,
-        ann_file="annotations/instances_val2017.json",
-        data_prefix=dict(img="val2017/"),
+        ann_file=val_ann_file,
+        data_prefix=dict(img=val_img_prefix),
         test_mode=True,
         pipeline=test_pipeline,
         # batch_shapes_cfg=batch_shapes_cfg,
@@ -95,10 +99,11 @@
 
 val_evaluator = dict(
     type=CocoMetric,
-    ann_file=data_root + "annotations/instances_val2017.json",
+    ann_file=data_root + val_ann_file,
     metric="bbox",
     format_only=False,
     backend_args=backend_args,
+    sort_categories=True
 )
 test_evaluator = val_evaluator
 

configs/rtmdet_l_8xb32_300e_coco.py

@@ -7,7 +7,7 @@
     from .datasets.coco_detection import *
 
 from torchvision.ops import nms
-from torch.nn import SiLU, ReLU6, SyncBatchNorm, ReLU
+from torch.nn import SiLU, ReLU6, BatchNorm2d, ReLU
 from torch.optim.adamw import AdamW
 
 from mmengine.hooks import EMAHook
@@ -77,7 +77,7 @@
         deepen_factor=d_factor,
         widen_factor=w_factor,
         channel_attention=False,
-        norm_cfg=dict(type=SyncBatchNorm),
+        norm_cfg=dict(type=BatchNorm2d),
         act_cfg=dict(type=ReLU, inplace=True),
     ),
     neck=dict(
@@ -88,18 +88,18 @@
         out_channels=256,
         num_csp_blocks=1,
         expand_ratio=0.5,
-        norm_cfg=dict(type=SyncBatchNorm),
+        norm_cfg=dict(type=BatchNorm2d),
         act_cfg=dict(type=ReLU, inplace=True),
     ),
     bbox_head=dict(
         type=RTMDetHead,
         head_module=dict(
             type=RTMDetSepBNHeadModule,
-            num_classes=80,
+            num_classes=num_classes,
             in_channels=256,
             stacked_convs=2,
             feat_channels=256,
-            norm_cfg=dict(type=SyncBatchNorm),
+            norm_cfg=dict(type=BatchNorm2d),
             act_cfg=dict(type=ReLU, inplace=True),
             share_conv=True,
             pred_kernel_size=1,
@@ -133,6 +133,7 @@
     ),
 )
 
+
 deploy = dict(
     type=RTMDetInfer,
     data_preprocessor=dict(

configs/rtmdet_nano_8xb32_300e_coco.py

@@ -22,6 +22,7 @@
 from sscma.models import ExpMomentumEMA
 from sscma.quantizer import RtmdetQuantModel
 
+
 d_factor = 0.33
 w_factor = 0.25
 
@@ -48,14 +49,14 @@
     )
 )
 
+
 model["bbox_head"].update(train_cfg=model["train_cfg"])
 model["bbox_head"].update(test_cfg=model["test_cfg"])
 quantizer_config = dict(
     type=RtmdetQuantModel,
     bbox_head=model["bbox_head"],
     data_preprocessor=model["data_preprocessor"],  # data_preprocessor,
 )
-
 train_pipeline = [
     dict(
         type=LoadImageFromFile,

docs/.vitepress/config.ts

@@ -1,9 +1,12 @@
 import { defineConfig } from 'vitepress'
 
+import { withMermaid } from 'vitepress-plugin-mermaid'
+
 import en_US from './locales/en_US'
 import zh_CN from './locales/zh_CN'
 
-export default defineConfig({
+
+export default withMermaid(defineConfig({
     base: '/',
     title: 'SSCMA',
     lastUpdated: true,
@@ -46,4 +49,4 @@ export default defineConfig({
             { icon: 'github', link: 'https://github.com/Seeed-Studio/ModelAssistant' }
         ]
     }
-})
+}))

docs/.vitepress/locales/en_US.ts

@@ -2,20 +2,25 @@ import { defineConfig } from 'vitepress'
 
 export default defineConfig({
     lang: 'en-US',
-    description: 'SSCMA is an open-source project focused on embedded AI.',
+    description: '*SSCMA* is an open-source project focused on embedded artificial intelligence.',
 
     themeConfig: {
         nav: nav(),
         sidebar: { '/': sidebar() },
 
+        darkModeSwitchLabel: 'Toggle Appearance',
+        outlineTitle: 'Page Outline',
+        lastUpdatedText: 'Last Updated',
+        returnToTopLabel: 'Back to Top',
+
         editLink: {
             pattern: 'https://github.com/Seeed-Studio/ModelAssistant/edit/main/docs/:path',
-            text: 'Suggest changes to this page'
+            text: 'Suggest edits for this page'
         },
 
         footer: {
-            message: 'Released under the Apache 2.0 License',
-            copyright: 'Copyright © 2023-Present Seeed Studio & SSCMA Contributors',
+            message: 'Published under Apache 2.0 License',
+            copyright: 'Copyright © 2023-Present Seeed Studio and SSCMA Contributors'
         }
     }
 })
@@ -30,32 +35,69 @@ function nav() {
 function sidebar() {
     return [
         {
-            text: 'Introduction',
+            text: 'Getting Started',
             collapsed: false,
             items: [
-                { text: 'What is SSCMA?', link: '/en/introduction/overview' },
-                { text: 'Quick Start', link: '/en/introduction/quick_start' },
+                { text: 'What is SSCMA?', link: '/introduction/overview' },
+                { text: 'Quick Start', link: '/introduction/quick_start' },
+                { text: 'Installation Guide', link: '/introduction/installation' }
             ]
         },
-
         {
-            text: 'Edge Impulse',
+            text: 'Tutorials',
             collapsed: false,
             items: [
                 {
-                    text: 'Machine Learning Blocks',
-                    link: '/en/edgeimpulse/ei_ml_blocks',
+                    text: 'Workflow Overview',
+                    link: '/tutorials/overview',
+                },
+                {
+                    text: 'Model Training and Export',
+                    link: '/tutorials/training/overview',
+                    items: [
+                        { text: 'FOMO Model', link: '/tutorials/training/fomo' },
+                        { text: 'PFLD Model', link: '/tutorials/training/pfld' },
+                        { text: 'RTMDet Model', link: '/tutorials/training/rtmdet' },
+                        { text: 'VAE Model', link: '/tutorials/training/vae' }
+                    ]
                 },
+                {
+                    text: 'Model Deployment',
+                    link: '/tutorials/deploy/overview',
+                    items: [
+                        { text: 'Grove Vision AI V2', link: '/tutorials/deploy/grove_vision_ai_v2' },
+                        { text: 'XIAO ESP32S3 Sense', link: '/tutorials/deploy/xiao_esp32s3' }
+                    ]
+                }
+            ]
+        },
+        {
+            text: 'Customization',
+            collapsed: false,
+            items: [
+                { text: 'Basic Configuration Structure', link: '/custom/basics' },
+                { text: 'Model Structure', link: '/custom/model' },
+                { text: 'Training and Validation Pipelines', link: '/custom/pipelines' },
+                { text: 'Optimizers', link: '/custom/optimizer' },
+            ]
+        },
+        {
+            text: 'Datasets',
+            collapsed: false,
+            items: [
+                { text: 'Public Datasets', link: '/datasets/public' },
+                { text: 'Custom Datasets', link: '/datasets/custom' },
+                { text: 'Dataset Formats and Extensions', link: '/datasets/extension' },
             ]
         },
         {
             text: 'Community',
             collapsed: false,
             items: [
-                { text: 'FAQs', link: '/en/community/faqs' },
-                { text: 'Reference', link: '/en/community/reference' },
-                { text: 'Contribution', link: '/en/community/contributing' },
-                { text: 'Copyrights and Licenses', link: '/en/community/license' }
+                { text: 'FAQs', link: '/community/faqs' },
+                { text: 'Reference Documentation', link: '/community/reference' },
+                { text: 'Contribution Guide', link: '/community/contributing' },
+                { text: 'Open Source License', link: '/community/license' }
             ]
         }
     ]

docs/.vitepress/locales/zh_CN.ts

@@ -39,17 +39,55 @@ function sidebar() {
             collapsed: false,
             items: [
                 { text: '什么是 SSCMA?', link: '/zh_cn/introduction/overview' },
-                { text: '快速上手', link: '/zh_cn/introduction/quickstart' },
+                { text: '快速上手', link: '/zh_cn/introduction/quick_start' },
+                { text: '安装指南', link: '/zh_cn/introduction/installation' }
             ]
         },
         {
-            text: 'Edge Impulse',
+            text: '基础教程',
             collapsed: false,
             items: [
                 {
-                    text: 'Edge Impulse 机器学习块',
-                    link: '/zh_cn/edgeimpulse/ei_ml_blocks',
+                    text: '流程概览',
+                    link: '/zh_cn/tutorials/overview',
                 },
+                {
+                    text: '模型训练与导出',
+                    link: '/zh_cn/tutorials/training/overview',
+                    items: [
+                        { text: 'FOMO 模型', link: '/zh_cn/tutorials/training/fomo' },
+                        { text: 'PFLD 模型', link: '/zh_cn/tutorials/training/pfld' },
+                        { text: 'RTMDet 模型', link: '/zh_cn/tutorials/training/rtmdet' },
+                        { text: 'VAE 模型', link: '/zh_cn/tutorials/training/vae' }
+                    ]
+                },
+                {
+                    text: '模型部署',
+                    link: '/zh_cn/tutorials/deploy/overview',
+                    items: [
+                        { text: 'Grove Vision AI V2', link: '/zh_cn/tutorials/deploy/grove_vision_ai_v2' },
+                        { text: 'XIAO ESP32S3 Sense', link: '/zh_cn/tutorials/deploy/xiao_esp32s3' }
+                    ]
+                }
+            ]
+        },
+        {
+            text: '自定义',
+            collapsed: false,
+            items: [
+                { text: '基础配置结构', link: '/zh_cn/custom/basics' },
+                { text: '模型结构', link: '/zh_cn/custom/model' },
+                { text: '训练与验证管线', link: '/zh_cn/custom/pipelines' },
+                { text: '优化器', link: '/zh_cn/custom/optimizer' },
+            ]
+        },
+        {
+            text: '数据集',
+            collapsed: false,
+            items: [
+                { text: '公共数据集', link: '/zh_cn/datasets/public' },
+                { text: '自制数据集', link: '/zh_cn/datasets/custom' },
+                { text: '数据集格式与扩展', link: '/zh_cn/datasets/extension' },
             ]
         },
         {

docs/.vitepress/theme/style.css

@@ -84,3 +84,9 @@
 .DocSearch {
     --docsearch-primary-color: var(--vp-c-brand) !important;
 }
+
+
+.mermaid {
+    display: flex;
+    justify-content: center;
+}

docs/community/contributing.md

@@ -0,0 +1,52 @@
+# Contribute
+
+Contributions to [SSCMA](https://github.com/Seeed-Studio/ModelAssistant) are welcome! We welcome contributions of any kind, including but not limited to:
+
+- Fixing bugs
+
+  The steps for fixing code implementation errors are as follows:
+
+  If the submitted code changes are large, it is recommended to submit an issue first, and correctly describe the phenomenon of the issue, the cause and the way to reproduce it, and discuss and confirm the fixing plan.
+
+  Fix the bug and add the corresponding unit test, and submit the pull request.
+
+- New feature or component
+
+  If a new feature or module involves large code changes, it is recommended to submit an issue first to confirm the necessity of the feature.
+
+  Implement the new feature, add unit tests, and submit a pull request.
+
+- Documentation additions
+
+  Fix the documentation to submit a pull request directly.
+
+  The steps to add documentation or translate it into another language are as follows.
+
+  Submit an issue to confirm the need to add the documentation.
+
+## How to Contribute
+
+Please refer to the [Github Documentation - Collaborating](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).
+
+## Commit Style
+
+We recommend that you follow the following authoring principles when writing your commit, as this will make our project cleaner and easier to iterate.
+
+```
+build: build related changes
+chore: typo fixes, library updates, etc.
+ci: continue integration related changes
+deps: dependencies update
+docs: docs related changes
+feat: new feactures
+fix: fix issues
+perf: add perf results
+refactor: refactor components
+revert: undo some changes
+style: code style changes
+test: test cases changes
+```
+
+## Permissions Section
+
+After a contribution is submitted, you agree to the project's [License](./license).

docs/community/faqs.md

@@ -0,0 +1,3 @@
+# FAQs
+
+If you encounter any problems using SSCMA, submitting your questions on [SSCMA Issues](https://github.com/Seeed-Studio/ModelAssistant/issues) is welcomed, and we will reply to you as soon as possible. We also organize some common problems so that you can find solutions in a timely manner.