 |
OpenCV 4.13.0
Open Source Computer Vision
|
読み込み中...
検索中...
見つかりません
|
OpenCV 4.13.0
Open Source Computer Vision
|
前のチュートリアル: 画像の基本操作
次のチュートリアル: 移行ガイド
| 原著者 | Maksim Shabunin |
| 互換性 | OpenCV >= 3.0 |
Doxygen は、次のような多くの優れた機能を備えたドキュメント生成システムである:
OpenCVライブラリの既存ドキュメントはdoxygen形式に変換されている。
公式の ダウンロード および インストール のページを参照してほしい。一部のLinuxディストリビューションでもdoxygenパッケージが提供されている。
ドキュメント全体は、さまざまな場所から集められる:
次の図は、opencv リポジトリにおける一般的なドキュメントの配置場所を表している:
バージョン3.0以降、すべての新しいモジュールは opencv_contrib リポジトリに置かれており、こちらはレイアウトがやや異なる:
関数・クラスやその他の構成要素のドキュメントを追加するには、その定義の直前に専用のコメントを挿入するだけでよい。次のように行う:
/** @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);
ここでは次のことが分かる:
/** ... */
brief コマンドは、続く段落が簡潔な説明であることを示す @brief
f[ と f] コマンドの間に書かれたTeX数式 \f[ ... \f]
param コマンドは、続く単語が引数の名前であり、続くテキストがその引数の説明であることを示す。すべての引数はリストにまとめられる @param
sa コマンドは、いくつかのクラス・メソッド・ページ・URLへの参照を含む「関連項目(See also)」の段落を開始する。 @sa
生成される参照項目は次のようになる: 
「More...」リンクをたどると、関数のドキュメントに移動する: 
1行の短いコメントには、異なるコメント構文を使うことができる:
//! type of line
enum LineTypes {
FILLED = -1,
LINE_4 = 4, //!< 4-connected line
LINE_8 = 8, //!< 8-connected line
LINE_AA = 16 //!< antialiased line
};
各引数の説明:
//!
< は、このコメントがドキュメント化された対象の後ろに位置することを示す //!<
生成されるドキュメントブロックは次のようになる: 
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
Doxygenはいくつかの拡張を伴うMarkdown記法をサポートしている。簡単な構文リファレンスを以下に示す。詳細は Markdown support を参照のこと。
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](http://opencv.org) automatic links: <http://opencv.org> or even: http://opencv.org
Level1 ====== Level2 ------ ### Level3 #### Level4
任意の見出しに一意の識別子を割り当て、他の場所から参照できるようにすることができる。
Header {#some_unique_identifier}
------
...
See @ref some_unique_identifier for details
各ページは、先頭にページタイトルと識別子を含む追加のLevel1見出しを持つべきである:
Writing documentation for OpenCV {#tutorial_documentation}
================================
doxygenドキュメントからの例:
First Header | Second Header ------------- | ------------- Content Cell | Content Cell Content Cell | Content Cell
最もよく使われるdoxygenコマンドを、短い例とともにここで説明する。利用可能なコマンドの完全な一覧と詳細な説明については、Command reference を参照のこと。
param - 関数の引数の説明。
隣接する複数の記述は1つのリストにまとめられる。この名前の引数が実際の関数シグネチャに見つからない場合、doxygenの警告が生成される。関数は、ドキュメント化された引数をまったく持たないか、すべての引数をドキュメント化するかのいずれかでなければならない。
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
トグルボタンは、選択された構成（例: プログラミング言語、OS、IDE）を表示するために使用する。
ドキュメントでボタンを使用するには、add_toggle および end_toggle コマンドを使用する。
add_toggle コマンドは次のいずれかにできる
例:
@add_toggle{Button Name}
text / code / doxygen commands
@end_toggle
例えば、テキストとcode スニペットを伴うトグルボタンの使用例:
### 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" である。
/**
@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
このセクションで説明する手順は、ドキュメント作成時のチェックリストとして使用できる。同じ順序で行う必要はないが、一部の手順は前の手順に依存する。もちろん、これらの手順は基本的なガイドラインにすぎず、創意工夫の余地は常にある。
初心者の開発者でも理解できるくらい十分にシンプルなサンプルアプリケーションを作る。簡潔に書き、分かりやすいコメントを記述し、起こりうるすべての実行時エラーを避けようとしたり、汎用的なユーティリティにしようとしたりしないこと。目的はアイデアを示すことである。そして1つのソースファイルに収まるべきである!
このファイルのコードブロックをチュートリアルに挿入したい場合は、特別なdoxygenコメントでマークする(こちらを参照)。
チュートリアルを複数のプログラミング言語で書きたい場合は、コメントとコードを切り替えるためのトグルボタンを使う(こちらを参照)。
アプリケーションの実行結果を収集する。それは「before/after」の画像でも、性能を表す何らかの数値でも、あるいは動画でもよい。
後でチュートリアルで使用するために、適切な形式で保存する:
-DBUILD_EXAMPLES=ON オプションが有効になっているときにOpenCVライブラリと一緒にコンパイルされるようにする。@prev_tutorial{identifier}
@next_tutorial{identifier} @prev_tutorial{#tutorial_documentation} 正しい: @prev_tutorial{tutorial_documentation} 結果を説明し、あらかじめ追加しておいた画像やその他の結果を挿入する。
YouTube動画を追加するには、例えば www.youtube.com/watch?v= ViPN810E0SU の場合、youtube{Video ID} を使う:
@youtube{ViPN810E0SU}新しく作成したチュートリアルを対応する目次に追加する。必要な目次を持つ "table_of_content_*.markdown" ファイルを見つけ、既存のものと同様に新しいレコードをそこに配置するだけである。
それは単に、特別な subpage コマンドを持つリスト項目であり、ページを子として示し、既存のページ階層に配置する。リスト項目のインデント、段落間の空行、特別な italic マーカーにも注意すること。
1.12.0