From db580dda8d2bf4c0e3aee3639e053cef6c58b80f Mon Sep 17 00:00:00 2001 From: Zaida Zhou <58739961+zhouzaida@users.noreply.github.com> Date: Wed, 7 Jul 2021 13:10:04 +0800 Subject: [PATCH] [Docs] Build Chinese docs (#1073) * Remove _build directroy in docs_zh_CN * Change utils title to Chinese * Translate documents * Translate documents * Use symbolic link to avoid repeated images * Use symbolic link to avoid repeated images * fix readme.md * update copyright * refactor docs * rename title to Chinese --- .gitignore | 1 + docs/conf.py | 4 +- docs/index.rst | 2 + docs/understand_mmcv/data_process.md | 2 +- docs/understand_mmcv/io.md | 4 +- docs_zh_CN/Makefile | 19 ++ docs_zh_CN/_static | 1 + docs_zh_CN/api.rst | 48 +++ docs_zh_CN/community.rst | 7 + docs_zh_CN/community/contributing.md | 3 + docs_zh_CN/conf.py | 195 +++++++++++++ docs_zh_CN/deployment.rst | 11 + docs_zh_CN/deployment/onnx.md | 3 + .../deployment/onnxruntime_custom_ops.md | 3 + docs_zh_CN/deployment/onnxruntime_op.md | 3 + docs_zh_CN/deployment/tensorrt_custom_ops.md | 3 + docs_zh_CN/deployment/tensorrt_plugin.md | 3 + docs_zh_CN/faq.md | 3 + docs_zh_CN/get_started.rst | 9 + docs_zh_CN/get_started/build.md | 3 + docs_zh_CN/get_started/installation.md | 3 + docs_zh_CN/get_started/introduction.md | 3 + docs_zh_CN/index.rst | 21 ++ docs_zh_CN/make.bat | 35 +++ docs_zh_CN/mmcv-logo.png | 1 + docs_zh_CN/understand_mmcv.rst | 15 + docs_zh_CN/understand_mmcv/cnn.md | 3 + docs_zh_CN/understand_mmcv/config.md | 3 + docs_zh_CN/understand_mmcv/data_process.md | 275 ++++++++++++++++++ docs_zh_CN/understand_mmcv/io.md | 119 ++++++++ docs_zh_CN/understand_mmcv/ops.md | 3 + docs_zh_CN/understand_mmcv/registry.md | 3 + docs_zh_CN/understand_mmcv/runner.md | 3 + docs_zh_CN/understand_mmcv/utils.md | 3 + docs_zh_CN/understand_mmcv/visualization.md | 3 + 35 files changed, 815 insertions(+), 5 deletions(-) create mode 100644 docs_zh_CN/Makefile create mode 120000 docs_zh_CN/_static create mode 100644 docs_zh_CN/api.rst create mode 100644 docs_zh_CN/community.rst create mode 100644 docs_zh_CN/community/contributing.md create mode 100644 docs_zh_CN/conf.py create mode 100644 docs_zh_CN/deployment.rst create mode 100644 docs_zh_CN/deployment/onnx.md create mode 100644 docs_zh_CN/deployment/onnxruntime_custom_ops.md create mode 100644 docs_zh_CN/deployment/onnxruntime_op.md create mode 100644 docs_zh_CN/deployment/tensorrt_custom_ops.md create mode 100644 docs_zh_CN/deployment/tensorrt_plugin.md create mode 100644 docs_zh_CN/faq.md create mode 100644 docs_zh_CN/get_started.rst create mode 100644 docs_zh_CN/get_started/build.md create mode 100644 docs_zh_CN/get_started/installation.md create mode 100644 docs_zh_CN/get_started/introduction.md create mode 100644 docs_zh_CN/index.rst create mode 100644 docs_zh_CN/make.bat create mode 120000 docs_zh_CN/mmcv-logo.png create mode 100644 docs_zh_CN/understand_mmcv.rst create mode 100644 docs_zh_CN/understand_mmcv/cnn.md create mode 100644 docs_zh_CN/understand_mmcv/config.md create mode 100644 docs_zh_CN/understand_mmcv/data_process.md create mode 100644 docs_zh_CN/understand_mmcv/io.md create mode 100644 docs_zh_CN/understand_mmcv/ops.md create mode 100644 docs_zh_CN/understand_mmcv/registry.md create mode 100644 docs_zh_CN/understand_mmcv/runner.md create mode 100644 docs_zh_CN/understand_mmcv/utils.md create mode 100644 docs_zh_CN/understand_mmcv/visualization.md diff --git a/.gitignore b/.gitignore index 43e4a4082f..b8e4f612f8 100644 --- a/.gitignore +++ b/.gitignore @@ -65,6 +65,7 @@ instance/ # Sphinx documentation docs/_build/ +docs_zh_CN/_build/ # PyBuilder target/ diff --git a/docs/conf.py b/docs/conf.py index c8abd31a7e..2307a980db 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -27,8 +27,8 @@ # -- Project information ----------------------------------------------------- project = 'mmcv' -copyright = '2018-2019, Kai Chen' -author = 'Kai Chen' +copyright = '2018-2021, OpenMMLab' +author = 'MMCV Authors' # The short X.Y version version = __version__ diff --git a/docs/index.rst b/docs/index.rst index f8f3b59077..64e796f9b1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,6 +1,8 @@ Welcome to MMCV's documentation! ================================ +You can switch between Chinese and English documents in the lower-left corner of the layout. + .. toctree:: :maxdepth: 2 diff --git a/docs/understand_mmcv/data_process.md b/docs/understand_mmcv/data_process.md index 35b9121ff2..79e9281b6c 100644 --- a/docs/understand_mmcv/data_process.md +++ b/docs/understand_mmcv/data_process.md @@ -13,7 +13,7 @@ import mmcv img = mmcv.imread('test.jpg') img = mmcv.imread('test.jpg', flag='grayscale') -img_ = mmcv.imread(img) # nothing will happen, img_ = img +img_ = mmcv.imread(img) # nothing will happen, img_ = img mmcv.imwrite(img, 'out.jpg') ``` diff --git a/docs/understand_mmcv/io.md b/docs/understand_mmcv/io.md index c1cef2ab12..50314d13d0 100644 --- a/docs/understand_mmcv/io.md +++ b/docs/understand_mmcv/io.md @@ -105,7 +105,7 @@ Then use `list_from_file` to load the list from a.txt. ['/mnt/a', '/mnt/b', '/mnt/c', '/mnt/d', '/mnt/e'] ``` -For example `b.txt` is a text file with 5 lines. +For example `b.txt` is a text file with 3 lines. ``` 1 cat @@ -113,7 +113,7 @@ For example `b.txt` is a text file with 5 lines. 3 panda ``` -Then use `dict_from_file` to load the list from a.txt. +Then use `dict_from_file` to load the dict from `b.txt` . ```python >>> mmcv.dict_from_file('b.txt') diff --git a/docs_zh_CN/Makefile b/docs_zh_CN/Makefile new file mode 100644 index 0000000000..51285967a7 --- /dev/null +++ b/docs_zh_CN/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs_zh_CN/_static b/docs_zh_CN/_static new file mode 120000 index 0000000000..ead5849d0e --- /dev/null +++ b/docs_zh_CN/_static @@ -0,0 +1 @@ +../docs/_static \ No newline at end of file diff --git a/docs_zh_CN/api.rst b/docs_zh_CN/api.rst new file mode 100644 index 0000000000..fb77ebaa94 --- /dev/null +++ b/docs_zh_CN/api.rst @@ -0,0 +1,48 @@ +API 文档 +========= + + +fileio +------- +.. automodule:: mmcv.fileio + :members: + +image +------ +.. automodule:: mmcv.image + :members: + +video +------ +.. automodule:: mmcv.video + :members: + +arraymisc +--------- +.. automodule:: mmcv.arraymisc + :members: + +visualization +-------------- +.. automodule:: mmcv.visualization + :members: + +utils +----- +.. automodule:: mmcv.utils + :members: + +cnn +---- +.. automodule:: mmcv.cnn + :members: + +runner +------ +.. automodule:: mmcv.runner + :members: + +ops +------ +.. automodule:: mmcv.ops + :members: diff --git a/docs_zh_CN/community.rst b/docs_zh_CN/community.rst new file mode 100644 index 0000000000..6ff519a7b0 --- /dev/null +++ b/docs_zh_CN/community.rst @@ -0,0 +1,7 @@ +社区 +=========== + +.. toctree:: + :maxdepth: 2 + + community/contributing.md diff --git a/docs_zh_CN/community/contributing.md b/docs_zh_CN/community/contributing.md new file mode 100644 index 0000000000..51df51aedf --- /dev/null +++ b/docs_zh_CN/community/contributing.md @@ -0,0 +1,3 @@ +## 贡献代码 + +欢迎有兴趣的朋友一起翻译 MMCV 文档。如有兴趣，请在 [MMCV issue](https://github.com/open-mmlab/mmcv/issues) 提 issue 确定翻译的文档。 diff --git a/docs_zh_CN/conf.py b/docs_zh_CN/conf.py new file mode 100644 index 0000000000..ab1db4a5c7 --- /dev/null +++ b/docs_zh_CN/conf.py @@ -0,0 +1,195 @@ +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys + +from m2r import MdInclude +from recommonmark.transform import AutoStructify + +sys.path.insert(0, os.path.abspath('..')) + +version_file = '../mmcv/version.py' +with open(version_file, 'r') as f: + exec(compile(f.read(), version_file, 'exec')) +__version__ = locals()['__version__'] + +# -- Project information ----------------------------------------------------- + +project = 'mmcv' +copyright = '2018-2021, OpenMMLab' +author = 'MMCV Authors' + +# The short X.Y version +version = __version__ +# The full version, including alpha/beta/rc tags +release = __version__ + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. + +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', + 'sphinx.ext.viewcode', + 'recommonmark', + 'sphinx.ext.autosectionlabel', + 'sphinx_markdown_tables' +] # yapf: disable + +autodoc_mock_imports = ['mmcv._ext', 'mmcv.utils.ext_loader', 'torchvision'] +autosectionlabel_prefix_document = True + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', +} + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'zh_CN' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'mmcvdoc' + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'mmcv.tex', 'mmcv Documentation', 'Kai Chen', 'manual'), +] + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [(master_doc, 'mmcv', 'mmcv Documentation', [author], 1)] + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'mmcv', 'mmcv Documentation', author, 'mmcv', + 'One line description of project.', 'Miscellaneous'), +] + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + +# -- Extension configuration ------------------------------------------------- + + +def setup(app): + app.add_config_value('no_underscore_emphasis', False, 'env') + app.add_config_value('m2r_parse_relative_links', False, 'env') + app.add_config_value('m2r_anonymous_references', False, 'env') + app.add_config_value('m2r_disable_inline_math', False, 'env') + app.add_directive('mdinclude', MdInclude) + app.add_config_value('recommonmark_config', { + 'auto_toc_tree_section': 'Contents', + 'enable_eval_rst': True, + }, True) + app.add_transform(AutoStructify) diff --git a/docs_zh_CN/deployment.rst b/docs_zh_CN/deployment.rst new file mode 100644 index 0000000000..c9e150a98a --- /dev/null +++ b/docs_zh_CN/deployment.rst @@ -0,0 +1,11 @@ +部署 +======== + +.. toctree:: + :maxdepth: 2 + + deployment/onnx.md + deployment/onnxruntime_op.md + deployment/onnxruntime_custom_ops.md + deployment/tensorrt_plugin.md + deployment/tensorrt_custom_ops.md diff --git a/docs_zh_CN/deployment/onnx.md b/docs_zh_CN/deployment/onnx.md new file mode 100644 index 0000000000..5268926d44 --- /dev/null +++ b/docs_zh_CN/deployment/onnx.md @@ -0,0 +1,3 @@ +# MMCV 中的 onnx 模块 (实验性质) + +欢迎有兴趣的朋友一起翻译 MMCV 文档。如有兴趣，请在 [MMCV issue](https://github.com/open-mmlab/mmcv/issues) 提 issue 确定翻译的文档。 diff --git a/docs_zh_CN/deployment/onnxruntime_custom_ops.md b/docs_zh_CN/deployment/onnxruntime_custom_ops.md new file mode 100644 index 0000000000..5b76dfeac5 --- /dev/null +++ b/docs_zh_CN/deployment/onnxruntime_custom_ops.md @@ -0,0 +1,3 @@ +# Onnxruntime 自定义算子 + +欢迎有兴趣的朋友一起翻译 MMCV 文档。如有兴趣，请在 [MMCV issue](https://github.com/open-mmlab/mmcv/issues) 提 issue 确定翻译的文档。 diff --git a/docs_zh_CN/deployment/onnxruntime_op.md b/docs_zh_CN/deployment/onnxruntime_op.md new file mode 100644 index 0000000000..845f30f55b --- /dev/null +++ b/docs_zh_CN/deployment/onnxruntime_op.md @@ -0,0 +1,3 @@ +# MMCV 中用于 ONNX Runtime 的自定义算子 + +欢迎有兴趣的朋友一起翻译 MMCV 文档。如有兴趣，请在 [MMCV issue](https://github.com/open-mmlab/mmcv/issues) 提 issue 确定翻译的文档。 diff --git a/docs_zh_CN/deployment/tensorrt_custom_ops.md b/docs_zh_CN/deployment/tensorrt_custom_ops.md new file mode 100644 index 0000000000..1b876e91e0 --- /dev/null +++ b/docs_zh_CN/deployment/tensorrt_custom_ops.md @@ -0,0 +1,3 @@ +# TensorRT 自定义算子 + +欢迎有兴趣的朋友一起翻译 MMCV 文档。如有兴趣，请在 [MMCV issue](https://github.com/open-mmlab/mmcv/issues) 提 issue 确定翻译的文档。 diff --git a/docs_zh_CN/deployment/tensorrt_plugin.md b/docs_zh_CN/deployment/tensorrt_plugin.md new file mode 100644 index 0000000000..60df06a517 --- /dev/null +++ b/docs_zh_CN/deployment/tensorrt_plugin.md @@ -0,0 +1,3 @@ +# MMCV 中用于自定义算子的 TensorRT 插件 (实验性质) + +欢迎有兴趣的朋友一起翻译 MMCV 文档。如有兴趣，请在 [MMCV issue](https://github.com/open-mmlab/mmcv/issues) 提 issue 确定翻译的文档。 diff --git a/docs_zh_CN/faq.md b/docs_zh_CN/faq.md new file mode 100644 index 0000000000..4a1a21a377 --- /dev/null +++ b/docs_zh_CN/faq.md @@ -0,0 +1,3 @@ +## 常见问题 + +欢迎有兴趣的朋友一起翻译 MMCV 文档。如有兴趣，请在 [MMCV issue](https://github.com/open-mmlab/mmcv/issues) 提 issue 确定翻译的文档。 diff --git a/docs_zh_CN/get_started.rst b/docs_zh_CN/get_started.rst new file mode 100644 index 0000000000..6187d31ebc --- /dev/null +++ b/docs_zh_CN/get_started.rst @@ -0,0 +1,9 @@ +介绍及安装 +=================== + +.. toctree:: + :maxdepth: 2 + + get_started/introduction.md + get_started/installation.md + get_started/build.md diff --git a/docs_zh_CN/get_started/build.md b/docs_zh_CN/get_started/build.md new file mode 100644 index 0000000000..9e1e99d404 --- /dev/null +++ b/docs_zh_CN/get_started/build.md @@ -0,0 +1,3 @@ +## 从源码编译 MMCV + +欢迎有兴趣的朋友一起翻译 MMCV 文档。如有兴趣，请在 [MMCV issue](https://github.com/open-mmlab/mmcv/issues) 提 issue 确定翻译的文档。 diff --git a/docs_zh_CN/get_started/installation.md b/docs_zh_CN/get_started/installation.md new file mode 100644 index 0000000000..c9370ded87 --- /dev/null +++ b/docs_zh_CN/get_started/installation.md @@ -0,0 +1,3 @@ +## 安装 MMCV + +欢迎有兴趣的朋友一起翻译 MMCV 文档。如有兴趣，请在 [MMCV issue](https://github.com/open-mmlab/mmcv/issues) 提 issue 确定翻译的文档。 diff --git a/docs_zh_CN/get_started/introduction.md b/docs_zh_CN/get_started/introduction.md new file mode 100644 index 0000000000..ad07681288 --- /dev/null +++ b/docs_zh_CN/get_started/introduction.md @@ -0,0 +1,3 @@ +## 介绍 MMCV + +欢迎有兴趣的朋友一起翻译 MMCV 文档。如有兴趣，请在 [MMCV issue](https://github.com/open-mmlab/mmcv/issues) 提 issue 确定翻译的文档。 diff --git a/docs_zh_CN/index.rst b/docs_zh_CN/index.rst new file mode 100644 index 0000000000..f4a26fe924 --- /dev/null +++ b/docs_zh_CN/index.rst @@ -0,0 +1,21 @@ +欢迎来到 MMCV 的中文文档！ +============================= + +您可以在页面左下角切换中英文文档。 + +.. toctree:: + :maxdepth: 2 + + get_started.rst + deployment.rst + understand_mmcv.rst + api.rst + faq.md + community.rst + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/docs_zh_CN/make.bat b/docs_zh_CN/make.bat new file mode 100644 index 0000000000..7893348a1b --- /dev/null +++ b/docs_zh_CN/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/docs_zh_CN/mmcv-logo.png b/docs_zh_CN/mmcv-logo.png new file mode 120000 index 0000000000..7dcca035f6 --- /dev/null +++ b/docs_zh_CN/mmcv-logo.png @@ -0,0 +1 @@ +../docs/mmcv-logo.png \ No newline at end of file diff --git a/docs_zh_CN/understand_mmcv.rst b/docs_zh_CN/understand_mmcv.rst new file mode 100644 index 0000000000..073ac4770b --- /dev/null +++ b/docs_zh_CN/understand_mmcv.rst @@ -0,0 +1,15 @@ +深入理解 MMCV +================= + +.. toctree:: + :maxdepth: 2 + + understand_mmcv/config.md + understand_mmcv/registry.md + understand_mmcv/runner.md + understand_mmcv/io.md + understand_mmcv/data_process.md + understand_mmcv/visualization.md + understand_mmcv/cnn.md + understand_mmcv/ops.md + understand_mmcv/utils.md diff --git a/docs_zh_CN/understand_mmcv/cnn.md b/docs_zh_CN/understand_mmcv/cnn.md new file mode 100644 index 0000000000..99dfa6cc00 --- /dev/null +++ b/docs_zh_CN/understand_mmcv/cnn.md @@ -0,0 +1,3 @@ +## 卷积神经网络 + +欢迎有兴趣的朋友一起翻译 MMCV 文档。如有兴趣，请在 [MMCV issue](https://github.com/open-mmlab/mmcv/issues) 提 issue 确定翻译的文档。 diff --git a/docs_zh_CN/understand_mmcv/config.md b/docs_zh_CN/understand_mmcv/config.md new file mode 100644 index 0000000000..bdbdb607f8 --- /dev/null +++ b/docs_zh_CN/understand_mmcv/config.md @@ -0,0 +1,3 @@ +## 配置 + +欢迎有兴趣的朋友一起翻译 MMCV 文档。如有兴趣，请在 [MMCV issue](https://github.com/open-mmlab/mmcv/issues) 提 issue 确定翻译的文档。 diff --git a/docs_zh_CN/understand_mmcv/data_process.md b/docs_zh_CN/understand_mmcv/data_process.md new file mode 100644 index 0000000000..3aab943273 --- /dev/null +++ b/docs_zh_CN/understand_mmcv/data_process.md @@ -0,0 +1,275 @@ +## 数据处理 + +### 图像 + +图像模块提供了一些图像预处理的函数，该模块依赖 `opencv` 。 + +#### 读取/保存/显示 + +使用 `imread` 和 `imwrite` 函数可以读取和保存图像。 + +```python +import mmcv + +img = mmcv.imread('test.jpg') +img = mmcv.imread('test.jpg', flag='grayscale') +img_ = mmcv.imread(img) # 相当于什么也没做 +mmcv.imwrite(img, 'out.jpg') +``` + +从二进制中读取图像 + +```python +with open('test.jpg', 'rb') as f: + data = f.read() +img = mmcv.imfrombytes(data) +``` + +显示图像文件或已读取的图像 + +```python +mmcv.imshow('tests/data/color.jpg') + +for i in range(10): + img = np.random.randint(256, size=(100, 100, 3), dtype=np.uint8) + mmcv.imshow(img, win_name='test image', wait_time=200) +``` + +#### 色彩空间转换 + +支持的转换函数： + +- bgr2gray +- gray2bgr +- bgr2rgb +- rgb2bgr +- bgr2hsv +- hsv2bgr + +```python +img = mmcv.imread('tests/data/color.jpg') +img1 = mmcv.bgr2rgb(img) +img2 = mmcv.rgb2gray(img1) +img3 = mmcv.bgr2hsv(img) +``` + +#### 缩放 + +有三种缩放图像的方法。所有以 `imresize_*` 开头的函数都有一个 `return_scale` 参数，如果 +该参数为 `False` ，函数的返回值只有调整之后的图像，否则是一个元组 `(resized_img, scale)` 。 + +```python +# 缩放图像至给定的尺寸 +mmcv.imresize(img, (1000, 600), return_scale=True) + +# 缩放图像至与给定的图像同样的尺寸 +mmcv.imresize_like(img, dst_img, return_scale=False) + +# 以一定的比例缩放图像 +mmcv.imrescale(img, 0.5) + +# 缩放图像至最长的边不大于1000、最短的边不大于800并且没有改变图像的长宽比 +mmcv.imrescale(img, (1000, 800)) +``` + +#### 旋转 + +我们可以使用 `imrotate` 旋转图像一定的角度。旋转的中心需要指定，默认值是原始图像的中心。有 +两种旋转的模式，一种保持图像的尺寸不变，因此旋转后原始图像中的某些部分会被裁剪，另一种是扩大 +图像的尺寸进而保留完整的原始图像。 + +```python +img = mmcv.imread('tests/data/color.jpg') + +# 顺时针旋转图像30度 +img_ = mmcv.imrotate(img, 30) + +# 逆时针旋转图像90度 +img_ = mmcv.imrotate(img, -90) + +# 顺时针旋转图像30度并且缩放图像为原始图像的1.5倍 +img_ = mmcv.imrotate(img, 30, scale=1.5) + +# 以坐标(100, 100)为中心顺时针旋转图像30度 +img_ = mmcv.imrotate(img, 30, center=(100, 100)) + +# 顺时针旋转图像30度并扩大图像的尺寸 +img_ = mmcv.imrotate(img, 30, auto_bound=True) +``` + +#### 翻转 + +我们可以使用 `imflip` 翻转图像。 + +```python +img = mmcv.imread('tests/data/color.jpg') + +# 水平翻转图像 +mmcv.imflip(img) + +# 垂直翻转图像 +mmcv.imflip(img, direction='vertical') +``` + +#### 裁剪 + +`imcrop` 可以裁剪图像的一个或多个区域，每个区域用左上角和右下角坐标表示，形如(x1, y1, x2, y2) + +```python +import mmcv +import numpy as np + +img = mmcv.imread('tests/data/color.jpg') + +# 裁剪区域 (10, 10, 100, 120) +bboxes = np.array([10, 10, 100, 120]) +patch = mmcv.imcrop(img, bboxes) + +# 裁剪两个区域，分别是 (10, 10, 100, 120) 和 (0, 0, 50, 50) +bboxes = np.array([[10, 10, 100, 120], [0, 0, 50, 50]]) +patches = mmcv.imcrop(img, bboxes) + +# 裁剪两个区域并且缩放区域1.2倍 +patches = mmcv.imcrop(img, bboxes, scale_ratio=1.2) +``` + +#### 填充 + +`impad` and `impad_to_multiple` 可以用给定的值将图像填充至给定的尺寸。 + +```python +img = mmcv.imread('tests/data/color.jpg') + +# 用给定值将图像填充至 (1000, 1200) +img_ = mmcv.impad(img, shape=(1000, 1200), pad_val=0) + +# 用给定值分别填充图像的3个通道至 (1000, 1200) +img_ = mmcv.impad(img, shape=(1000, 1200), pad_val=[100, 50, 200]) + +# 用给定值填充图像的左、右、上、下四条边 +img_ = mmcv.impad(img, padding=(10, 20, 30, 40), pad_val=0) + +# 用3个值分别填充图像的左、右、上、下四条边的3个通道 +img_ = mmcv.impad(img, padding=(10, 20, 30, 40), pad_val=[100, 50, 200]) + +# 将图像的四条边填充至能够被给定值整除 +img_ = mmcv.impad_to_multiple(img, 32) +``` + +### 视频 + +视频模块提供了以下的功能： + +- 一个 `VideoReader` 类，具有友好的 API 接口可以读取和转换视频 +- 一些编辑视频的方法，包括 `cut` ， `concat` ， `resize` +- 光流的读取/保存/变换 + +#### VideoReader + +`VideoReader` 类提供了和序列一样的接口去获取视频帧。该类会缓存所有被访问过的帧。 + +```python +video = mmcv.VideoReader('test.mp4') + +# 获取基本的信息 +print(len(video)) +print(video.width, video.height, video.resolution, video.fps) + +# 遍历所有的帧 +for frame in video: + print(frame.shape) + +# 读取下一帧 +img = video.read() + +# 使用索引获取帧 +img = video[100] + +# 获取指定范围的帧 +img = video[5:10] +``` + +将视频切成帧并保存至给定目录或者从给定目录中生成视频。 + +```python +# 将视频切成帧并保存至目录 +video = mmcv.VideoReader('test.mp4') +video.cvt2frames('out_dir') + +# 从给定目录中生成视频 +mmcv.frames2video('out_dir', 'test.avi') +``` + +#### 编辑函数 + +有几个用于编辑视频的函数，这些函数是对 `ffmpeg` 的封装。 + +```python +# 裁剪视频 +mmcv.cut_video('test.mp4', 'clip1.mp4', start=3, end=10, vcodec='h264') + +# 将多个视频拼接成一个视频 +mmcv.concat_video(['clip1.mp4', 'clip2.mp4'], 'joined.mp4', log_level='quiet') + +# 将视频缩放至给定的尺寸 +mmcv.resize_video('test.mp4', 'resized1.mp4', (360, 240)) + +# 将视频缩放至给定的倍率 +mmcv.resize_video('test.mp4', 'resized2.mp4', ratio=2) +``` + +#### 光流 + +`mmcv` 提供了以下用于操作光流的函数： + +- 读取/保存 +- 可视化 +- 流变换 + +我们提供了两种将光流dump到文件的方法，分别是非压缩和压缩的方法。非压缩的方法直接将浮点数值的光流 +保存至二进制文件，虽然光流无损但文件会比较大。而压缩的方法先量化光流至 0-255 整形数值再保存为 +jpeg图像。光流的x维度和y维度会被拼接到图像中。 + +1. 读取/保存 + +```python +flow = np.random.rand(800, 600, 2).astype(np.float32) +# 保存光流到flo文件 (~3.7M) +mmcv.flowwrite(flow, 'uncompressed.flo') +# 保存光流为jpeg图像 (~230K)，图像的尺寸为 (800, 1200) +mmcv.flowwrite(flow, 'compressed.jpg', quantize=True, concat_axis=1) + +# 读取光流文件，以下两种方式读取的光流尺寸均为 (800, 600, 2) +flow = mmcv.flowread('uncompressed.flo') +flow = mmcv.flowread('compressed.jpg', quantize=True, concat_axis=1) +``` + +2. 可视化 + +使用 `mmcv.flowshow()` 可视化光流 + +```python +mmcv.flowshow(flow) +``` + +![progress](../_static/flow_visualization.png) + +3. 流变换 + +```python +img1 = mmcv.imread('img1.jpg') +flow = mmcv.flowread('flow.flo') +warpped_img2 = mmcv.flow_warp(img1, flow) +``` + +img1 (左) and img2 (右) + +![raw images](../_static/flow_raw_images.png) + +光流 (img2 -> img1) + +![optical flow](../_static/flow_img2toimg1.png) + +变换后的图像和真实图像的差异 + +![warpped image](../_static/flow_warp_diff.png) diff --git a/docs_zh_CN/understand_mmcv/io.md b/docs_zh_CN/understand_mmcv/io.md new file mode 100644 index 0000000000..8d3844f77c --- /dev/null +++ b/docs_zh_CN/understand_mmcv/io.md @@ -0,0 +1,119 @@ +## 文件输入输出 + +文件输入输出模块提供了两个通用的 API 接口用于读取和保存不同格式的文件。 + +### 读取和保存数据 + +`mmcv` 提供了一个通用的 api 用于读取和保存数据，目前支持的格式有 json、yaml 和 pickle。 + +```python +import mmcv + +# 从文件中读取数据 +data = mmcv.load('test.json') +data = mmcv.load('test.yaml') +data = mmcv.load('test.pkl') +# 从文件对象中读取数据 +with open('test.json', 'r') as f: + data = mmcv.load(f, file_format='json') + +# 将数据序列化为字符串 +json_str = mmcv.dump(data, file_format='json') + +# 将数据保存至文件 (根据文件名后缀反推文件类型) +mmcv.dump(data, 'out.pkl') + +# 将数据保存至文件对象 +with open('test.yaml', 'w') as f: + data = mmcv.dump(data, f, file_format='yaml') +``` + +我们提供了易于拓展的方式以支持更多的文件格式。我们只需要创建一个继承自 `BaseFileHandler` 的 +文件句柄类并将其注册到 `mmcv` 中即可。句柄类至少需要重写三个方法。 + +```python +import mmcv + +# 支持为文件句柄类注册多个文件格式 +# @mmcv.register_handler(['txt', 'log']) +@mmcv.register_handler('txt') +class TxtHandler1(mmcv.BaseFileHandler): + + def load_from_fileobj(self, file): + return file.read() + + def dump_to_fileobj(self, obj, file): + file.write(str(obj)) + + def dump_to_str(self, obj, **kwargs): + return str(obj) +``` + +举 `PickleHandler` 为例。 + +```python +import pickle + +class PickleHandler(mmcv.BaseFileHandler): + + def load_from_fileobj(self, file, **kwargs): + return pickle.load(file, **kwargs) + + def load_from_path(self, filepath, **kwargs): + return super(PickleHandler, self).load_from_path( + filepath, mode='rb', **kwargs) + + def dump_to_str(self, obj, **kwargs): + kwargs.setdefault('protocol', 2) + return pickle.dumps(obj, **kwargs) + + def dump_to_fileobj(self, obj, file, **kwargs): + kwargs.setdefault('protocol', 2) + pickle.dump(obj, file, **kwargs) + + def dump_to_path(self, obj, filepath, **kwargs): + super(PickleHandler, self).dump_to_path( + obj, filepath, mode='wb', **kwargs) +``` + +### 读取文件并返回列表或字典 + +例如， `a.txt` 是文本文件，一共有5行内容。 + +``` +a +b +c +d +e +``` + +使用 `list_from_file` 读取 `a.txt` 。 + +```python +>>> mmcv.list_from_file('a.txt') +['a', 'b', 'c', 'd', 'e'] +>>> mmcv.list_from_file('a.txt', offset=2) +['c', 'd', 'e'] +>>> mmcv.list_from_file('a.txt', max_num=2) +['a', 'b'] +>>> mmcv.list_from_file('a.txt', prefix='/mnt/') +['/mnt/a', '/mnt/b', '/mnt/c', '/mnt/d', '/mnt/e'] +``` + +同样， `b.txt` 也是文本文件，一共有3行内容。 + +``` +1 cat +2 dog cow +3 panda +``` + +使用 `dict_from_file` 读取 `b.txt` 。 + +```python +>>> mmcv.dict_from_file('b.txt') +{'1': 'cat', '2': ['dog', 'cow'], '3': 'panda'} +>>> mmcv.dict_from_file('b.txt', key_type=int) +{1: 'cat', 2: ['dog', 'cow'], 3: 'panda'} +``` diff --git a/docs_zh_CN/understand_mmcv/ops.md b/docs_zh_CN/understand_mmcv/ops.md new file mode 100644 index 0000000000..db8d8966da --- /dev/null +++ b/docs_zh_CN/understand_mmcv/ops.md @@ -0,0 +1,3 @@ +## CUDA 算子 + +欢迎有兴趣的朋友一起翻译 MMCV 文档。如有兴趣，请在 [MMCV issue](https://github.com/open-mmlab/mmcv/issues) 提 issue 确定翻译的文档。 diff --git a/docs_zh_CN/understand_mmcv/registry.md b/docs_zh_CN/understand_mmcv/registry.md new file mode 100644 index 0000000000..4fbbcb3e7f --- /dev/null +++ b/docs_zh_CN/understand_mmcv/registry.md @@ -0,0 +1,3 @@ +## 注册器 + +欢迎有兴趣的朋友一起翻译 MMCV 文档。如有兴趣，请在 [MMCV issue](https://github.com/open-mmlab/mmcv/issues) 提 issue 确定翻译的文档。 diff --git a/docs_zh_CN/understand_mmcv/runner.md b/docs_zh_CN/understand_mmcv/runner.md new file mode 100644 index 0000000000..c729c7acee --- /dev/null +++ b/docs_zh_CN/understand_mmcv/runner.md @@ -0,0 +1,3 @@ +## 执行器 + +欢迎有兴趣的朋友一起翻译 MMCV 文档。如有兴趣，请在 [MMCV issue](https://github.com/open-mmlab/mmcv/issues) 提 issue 确定翻译的文档。 diff --git a/docs_zh_CN/understand_mmcv/utils.md b/docs_zh_CN/understand_mmcv/utils.md new file mode 100644 index 0000000000..7b8755a952 --- /dev/null +++ b/docs_zh_CN/understand_mmcv/utils.md @@ -0,0 +1,3 @@ +## 辅助函数 + +欢迎有兴趣的朋友一起翻译 MMCV 文档。如有兴趣，请在 [MMCV issue](https://github.com/open-mmlab/mmcv/issues) 提 issue 确定翻译的文档。 diff --git a/docs_zh_CN/understand_mmcv/visualization.md b/docs_zh_CN/understand_mmcv/visualization.md new file mode 100644 index 0000000000..968631bc6e --- /dev/null +++ b/docs_zh_CN/understand_mmcv/visualization.md @@ -0,0 +1,3 @@ +## 可视化 + +欢迎有兴趣的朋友一起翻译 MMCV 文档。如有兴趣，请在 [MMCV issue](https://github.com/open-mmlab/mmcv/issues) 提 issue 确定翻译的文档。