OpenCV 4.12.0
开源计算机视觉
加载中...
搜索中...
无匹配项
为OpenCV编写文档

目录

上一教程： 图像入门
下一教程： 过渡指南

原始作者马克西姆·沙布宁
兼容性OpenCV >= 3.0

Doxygen 概述

简介

Doxygen 是一个文档生成系统，具有许多强大的功能，例如

  • 解析程序源代码以生成真实准确的文档
  • 检查文档中的错误
  • 插入图片和公式
  • 使用 Markdown 语法和纯 HTML 进行精确文本格式化
  • 生成多种不同格式的文档

OpenCV 库的现有文档已转换为 Doxygen 格式。

安装

请查阅官方下载和安装页面。一些 Linux 发行版也可能提供 Doxygen 软件包。

生成文档

  • 获取 OpenCV 源代码（3.0 及更高版本）
  • 可选： 获取 OpenCV_contrib 源代码
  • 在源代码文件夹旁边创建构建目录并进入该目录
  • 运行 cmake（假设您将源代码放在 opencv 文件夹中）
    cmake -DBUILD_DOCS=ON ../opencv
    或者如果您也获取了 contrib 源代码
    cmake -DBUILD_DOCS=ON -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules ../opencv
  • 运行 make
    make doxygen
  • 在您喜欢的浏览器中打开 doc/doxygen/html/index.html 文件
  • 测试您的 Python 代码
    make check_pylint
    注意
    在运行 cmake 之前必须安装 Pylint 才能测试 Python 代码。您可以使用系统的包管理器或 pip 进行安装
    pip install pylint

快速入门

注意
这些说明专用于 OpenCV 库文档，其他项目可能使用不同的布局方案和文档约定。

文档位置

整个文档从许多不同的地方收集：

  • 源代码实体，如类、函数或枚举，应在其定义之前的相应头文件中进行文档编写。请参见下一节中的示例。
  • 页面是放置大量文本、图片和代码示例的好地方，这些内容不直接与任何源代码实体相关联。页面应位于单独的文件中，并包含在几个预定义的位置。本教程就是这种页面的一个示例。
  • 图片可用于说明所描述的事物。图片通常与页面位于相同的位置，可以插入到文档的任何地方。
  • 代码示例展示了如何在实际应用程序中使用该库。每个示例都是一个自包含文件，代表一个简单的应用程序。这些文件的一部分可以包含到文档和教程中，以演示函数调用和对象协作。
  • BibTeX 引用用于创建一个共同的参考文献列表。所有作为库功能基础的科学书籍、文章和会议论文都应放入此参考文献列表中。

以下方案表示 opencv 仓库的常见文档位置：

<opencv>
├── doc - doxygen 配置文件、根页面 (root.markdown.in)、BibTeX 文件 (opencv.bib)
│   ├── tutorials - 教程层次结构（页面和图片）
│   └── py_tutorials - Python 教程层次结构（页面和图片）
├── modules
│  > └── <模块名>
│      ├── doc - 模块的文档页面和图片
│      └── include - 头文件中的代码文档
└── samples - 所有代码示例的存放位置
├── cpp
│ └── tutorial_code - 教程代码示例的存放位置
└── ...
注意
自动代码解析器会在 include 文件夹及其子文件夹中查找所有头文件（".h, .hpp"，但排除 ".inl.hpp; .impl.hpp; _detail.hpp"）。一些模块特定的指令（组定义）和文档应放入 "include/opencv2/<module-name>.hpp" 文件中。
您可以将 C++ 模板实现和特化放入 Doxygen 忽略的单独文件（".impl.hpp"）中。
src 子文件夹中的文件未被解析，因为文档主要面向库用户而非开发人员。但仍可以通过在 cmake 脚本（doc/CMakeLists.txt）中自定义处理文件列表以及在 Doxygen 配置文件（doc/Doxyfile.in）中设置选项来生成完整的文档。

自 3.0 版本起，所有新模块都放置在 opencv_contrib 仓库中，其布局略有不同：

<opencv_contrib>
└── modules
└── <模块名>
├── doc - 文档页面和图片，BibTeX 文件 (<模块名>.bib)
├── include - 头文件中的代码文档
├── samples - 文档和教程的代码示例存放位置
└── tutorials - 教程页面和图片

示例

要为函数、类和其他实体添加文档，只需在其定义之前插入特殊注释，如下所示：

/** @brief Calculates the exponent of every array element.

The function exp calculates the exponent of every element of the input array:
\f[ \texttt{dst} [I] = e^{ src(I) } \f]

The maximum relative error is about 7e-6 for single-precision input and less than 1e-10 for
double-precision input. Currently, the function converts denormalized values to zeros on output.
Special values (NaN, Inf) are not handled.

@param src input array.
@param dst output array of the same size and type as src.

@sa log , cartToPolar , polarToCart , phase , pow , sqrt , magnitude
*/
CV_EXPORTS_W void exp(InputArray src, OutputArray dst);

您可以看到：

  • 特殊的 C 注释语法表示这是一个 Doxygen 注释
    /** ... */
  • 命令 brief 表示接下来的段落是简要描述
    @brief
  • 空行表示段落结束
  • f[ 和 f] 命令之间的 TeX 公式
    \f[ ... \f]
  • 命令 param 表示接下来的词是参数名称，其后的文本是参数描述；所有参数都放在一个列表中
    @param
  • 命令 sa 开始一个“另请参见”段落，其中包含对某些类、方法、页面或 URL 的引用。
    @sa

生成的引用项如下所示：

“更多...”链接将您带到函数文档：

另一个示例

可以使用不同的注释语法来表示单行短注释：

//! type of line
enum LineTypes {
    FILLED  = -1,
    LINE_4  = 4, //!< 4-connected line
    LINE_8  = 8, //!< 8-connected line
    LINE_AA = 16 //!< antialiased line
};

在这里

  • 特殊的 C++ 注释语法表示这是一个 Doxygen 注释
    //!
  • 附加符号 < 表示此注释位于被文档化实体之后
    //!<

生成的文档块如下所示：

更多细节

命令前缀

Doxygen 命令以 @ 或 \ 符号开头

@brief ...
or
\brief ...

注释语法

Doxygen 注释可以有不同的形式

C-style:
/** ... */
or
/*! ... */

C++-style
//! ...
or
/// ...

Lines can start with '*':
/**
 * ...
 * ...
 */

Can be placed after documented entity:
//!< ...
/**< ... */

段落结束

要结束段落，请插入空行或任何开始新段落的命令

@brief brief description paragraph
brief continues

new paragraph

@note new note paragraph
note paragraph continues

another paragraph
paragraph continues

命名

页面、锚点、组和其他命名实体在整个项目中应具有唯一的名称。最好以模块名称作为这些标识符的前缀。

@page core_explanation_1 Usage explanation
@defgroup imgproc_transform Image transformations
@anchor mymodule_interesting_note

支持的 Markdown

Doxygen 支持带有一些扩展的 Markdown 格式。下面描述了简短的语法参考，详情请访问 Markdown 支持。

列表

Bulleted:
- item1
- item2
Numbered:
1. item1
2. item2
or
-# item1
-# item2

强调

_italic_
__bold__
use html in complex cases:
<em>"path/to/file"</em>

链接

explicit link:
[OpenCV main site](https://opencv.ac.cn)
automatic links:
<https://opencv.ac.cn>
or even:
https://opencv.ac.cn

图片

![image caption](image path)

标题

Level1
======
Level2
------
### Level3
#### Level4

标题 ID

您可以为任何标题分配一个唯一标识符，以便从其他地方引用它。

Header {#some_unique_identifier}
------
...
See @ref some_unique_identifier for details

页面 ID

每个页面开头都应有一个额外的 Level1 标题，包含页面标题和标识符

Writing documentation for OpenCV {#tutorial_documentation}
================================

表格

Doxygen 文档中的示例

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

常用命令

这里描述了最常用的 Doxygen 命令，并附有简短示例。有关可用命令的完整列表和详细描述，请访问 命令参考。

基本命令

  • brief - 包含实体简要描述的段落

  • param - 函数参数的描述。

    多个相邻语句合并为一个列表。如果在实际函数签名中未找到具有此名称的参数，Doxygen 将生成警告。函数可以 没有 文档化的参数，也可以 所有 参数都应被文档化。

  • sa - “另请参见”段落，包含对类、函数、页面或 URL 的引用
  • note - 视觉上突出显示的“注意”段落。多个相邻语句合并为一个块。
  • return, returns - 描述函数的返回值
  • overload - 为函数描述添加固定文本：“这是一个重载成员函数，为方便起见提供。它与上述函数的区别仅在于它接受的参数。”
  • anchor - 放置一个不可见的命名锚点，可通过 ref 命令引用。它只能在页面中使用。

  • ref - 对命名部分、页面或锚点的显式引用。

    如果找不到此类实体，Doxygen 将生成警告。此命令有一个可选参数 - 链接文本。

    Doxygen 还会自动生成一些链接：如果文本包含在已文档化实体中可以找到的词，则会生成引用。可以通过在词前添加 % 符号来禁用此功能。

    Explicit reference: @ref MyClass
Explicit named reference: @ref example_page "Example page"
Implicit reference: cv::abc::MyClass1 or just MyClass1
Disable implicit reference: %MyClass1

  • f - 公式

    内联公式由 f$ 命令限定

    \f$ ... \f$

    块级公式由 f[ 和 f] 命令限定

    \f[ ... \f]

代码包含命令

要在文档中将某些文本标记为代码，使用 code 和 endcode 命令。

@code
float val = img.at<float>(borderInterpolate(100, img.rows, cv::BORDER_REFLECT_101),
                          borderInterpolate(-5, img.cols, cv::BORDER_WRAP));
@endcode

语法将根据当前解析的文件类型（.hpp 为 C++，.h 为 C）进行高亮显示，或者您可以在大括号中手动指定它

@code{.xml}

要将整个示例文件包含到文档中，使用 include 和 includelineno 命令。文件会在常见的示例位置中搜索，因此您只需指定其名称或路径的简短部分。includelineno 版本还会显示行号，但由于包含行号，因此会阻止复制粘贴。

@include samples/cpp/test.cpp

如果要包含现有示例文件的某些部分，请使用 snippet 命令。

首先，使用特殊的 Doxygen 注释标记文件中的所需部分

//! [var_init]
int a = 0;
//! [var_init]

然后将此片段包含到文档中

@snippet samples/cpp/test.cpp var_init
注意
目前，大多数此类部分包含都使用 dontinclude 命令，以与旧的 rST 文档兼容。但新创建的示例应使用 snippet 命令包含，因为此方法受处理文件更改的影响较小。

切换按钮包含命令

切换按钮用于显示选定的配置（例如，编程语言、操作系统、IDE）。

要在文档中使用这些按钮，需要使用 add_toggle 和 end_toggle 命令。

add_toggle 命令可以是：

  • 通用：add_toggle{Button Name}
  • 针对 C++：add_toggle_cpp
  • 针对 Java：add_toggle_java
  • 针对 Python：add_toggle_python

示例

@add_toggle{Button Name}

  text / code / doxygen commands

@end_toggle

例如，将切换按钮与文本和代码片段一起使用

### Buttons Example

@add_toggle_cpp

   Text for C++ button
   @snippet samples/cpp/tutorial_code/introduction/documentation/documentation.cpp hello_world

@end_toggle

@add_toggle_java

   Text for Java button
   @snippet samples/java/tutorial_code/introduction/documentation/Documentation.java  hello_world

@end_toggle

@add_toggle_python

   Text for Python button
   @snippet samples/python/tutorial_code/introduction/documentation/documentation.py hello_world

@end_toggle

结果如下所示：

按钮示例

如您所见，按钮会自动添加到上一个标题下方。

分组命令

所有代码实体都应放入代表 OpenCV 模块及其内部结构的命名组中，因此每个模块都应与一个同名组相关联。定义组和子组的好地方是该模块的主头文件："<module>/include/opencv2/<module>.hpp"。

注意
Doxygen 组被称为“模块”，并显示在“模块”页面上。
/**
@defgroup mymodule My great module
    optional description
@{
    @defgroup mymodule_basic Basic operations
        optional description
    @defgroup mymodule_experimental Experimental operations
        optional description
@}
*/

要将类和函数放入特定组中，只需在其文档中添加 ingroup 命令，或者用 addtogroup 命令包装整个代码块。

/** @brief Example function
    @ingroup mymodule
*/
or
/**
@addtogroup mymodule_experimental
@{
*/
... several functions, classes or enumerations here
/**
@}
*/

参考文献

使用 cite 命令插入对参考文献页面中列出的相关出版物的引用。

首先，将出版物 BibTeX 记录添加到 "<opencv>/doc/opencv.bib" 或 "<opencv_contrib>/modules/<module>/doc/<module>.bib" 文件中。

@ARTICLE{Bradski98,
    author = {Bradski, Gary R},
    title = {Computer vision face tracking for use in a perceptual user interface},
    year = {1998},
    publisher = {Citeseer}
}
注意
尽量不要添加重复的出版物，因为它可能会在以后混淆文档读者和作者。

然后使用 cite 命令进行引用

@cite Bradski98
注意
要获取出版物的 BibTeX 记录，可以使用 Google 学术搜索。找到出版物后，点击其“引用”链接，然后选择“BibTeX”选项：

循序渐进

本节中描述的步骤可在编写文档时用作检查清单。并非所有步骤都必须按相同顺序进行，但有些步骤确实依赖于之前的步骤。当然，这些步骤只是基本指南，总有发挥创造力的空间。

文档化函数

  1. 在函数定义之前添加空的 Doxygen 注释。
  2. 在开头添加 brief 命令，并简要描述函数含义。
  3. 添加函数的详细描述。
  4. 可选： 插入公式、图片和示例代码块以说明复杂情况
  5. 可选： 使用 param 命令描述每个参数。
  6. 可选： 使用 returns 命令描述函数的返回值。
  7. 可选： 添加“另请参见”部分，其中包含指向类似函数或类的链接
  8. 可选： 添加参考文献（如果有）。
  9. 测试您的代码。（Python：“make check_pylint”）
  10. 生成 Doxygen 文档并验证结果。

编写教程

  1. 构思教程中要说明的想法。

  2. 编写示例应用程序，应足够简单以便初级开发人员理解。言简意赅，编写描述性注释，不要试图避免所有可能的运行时错误或制作通用工具。您的目标是阐明想法。而且它应该适合一个源文件！

    如果您想将此文件中的代码块插入到教程中，请使用特殊的 Doxygen 注释标记它们（参见此处）。

    如果您想用多种编程语言编写教程，请使用切换按钮来实现替代注释和代码（参见此处）。

  3. 收集应用程序运行结果。可以是“前后”对比图片、表示性能的数字，甚至是视频。

    以适当的格式保存，以便稍后在教程中使用：

    • 对于简单的图表类图片，请使用无损“.png”格式。
    • 对于照片类图片，请使用有损“.jpg”格式。
    • 数字将以纯文本形式插入，可能格式化为表格。
    • 视频应上传到 YouTube。
  4. 在相应位置创建新的教程页面（".markdown" 文件）（参见此处），并将所有图像文件放在其附近（或在“images”子目录中）。同时放置您的示例应用程序文件，并确保在 cmake 步骤启用 -DBUILD_EXAMPLES=ON 选项时，它能与 OpenCV 库一起编译。
  5. 修改您的新页面
    • 添加页面标题和标识符，通常以 "tutorial_" 为前缀（参见此处）。您可以使用标识符添加指向上一篇和下一篇教程的链接。
      @prev_tutorial{identifier}
@next_tutorial{identifier}
      警告
      不要写入井号 (#)，例如：
      不正确
      @prev_tutorial{#tutorial_documentation}
      正确
      @prev_tutorial{tutorial_documentation}
    • 添加您的想法和教程目标的简要描述。
    • 描述您的程序和/或其有趣的部分。

    • 描述您的结果，插入之前添加的图片或其他结果。

      要添加 YouTube 视频，例如 www.youtube.com/watch?v= ViPN810E0SU，请使用 youtube{视频 ID}

      @youtube{ViPN810E0SU}
    • 添加参考文献（如果有）（参见此处）。

  6. 将新创建的教程添加到相应的目录中。只需找到包含所需表格的 "table_of_content_*.markdown" 文件，并以与现有记录类似的方式在其中添加新记录。

    它只是一个列表项，带有特殊的 subpage 命令，该命令将您的页面标记为子页面并将其放入现有页面层次结构中。另请注意列表项缩进、段落之间的空行和特殊的 斜体 标记。

  7. 生成 Doxygen 文档并验证结果。

参考文献

生成于 2025 年 7 月 3 日星期四 12:14:35，由  doxygen 1.12.0 为 OpenCV 生成。