基本構造体¶

DataType¶

OpenCV のその他のプリミティブなデータ型に対する “traits” クラステンプレート．

template<typename _Tp> class DataType
{
    // value_type は常に _Tp と等しくなります．
    typedef _Tp value_type;

    // _Tp の処理で利用される中間型です．
    // uchar, signed char, unsigned char, signed short, int に対しては int ，
    // float に対しては float ， double に対しては double ， ...
    typedef <...> work_type;
    // マルチチャンネルデータの場合，これは各チャンネルのデータ型になります．
    typedef <...> channel_type;
    enum
    {
        // CV_8U ... CV_64F
        depth = DataDepth<channel_type>::value,
        // 1 ...
        channels = <...>,
        // '1u', '4i', '3f', '2d' など．
        fmt=<...>,
        // CV_8UC3, CV_32FC2 ...
        type = CV_MAKETYPE(depth, channels)
    };
};

クラステンプレート DataType は，OpenCV の基本的なデータ型や以下の定義に従うその他の型，に対する説明的なクラスです． OpenCV の基本的なデータ型は， unsigned char, bool, unsigned char, signed char, unsigned short, signed short, int, float, double の 1 つ，あるいは， 1 つの型の値のタプルで，その場合タプル内の値はすべて同じ型になります． OpenCV の CvMat の表記法 CV _ 8U ... CV _ 32FC3, CV _ 64FC2 に慣れているならば，基本的な型は CV_<bit-depth>{U|S|F}C<number_of_channels> の形式で一意な識別子を与えることができるもの，としても定義できます． Vec は，この基本的なデータ型の 1 つのインスタンスを格納できる OpenCV の汎用的な構造です．また， std::vector , Mat , Mat_ , SparseMat , SparseMat_ や， Vec() のインスタンスを格納できるその他のコンテナは，このような型の複数のインスタンスを格納できます．

DataType クラスは基本的に，対象となるクラスにフィールドやメソッドを追加せずに（C/C++ の基本的なデータ型に何かを追加するのは実際に不可能です），このような基本的なデータ型の説明を提供するために利用されます．このテクニックは，C++ では traits クラスとして知られています．使われるのは DataType 自身ではなく，以下のように特殊化したものです：

template<> class DataType<uchar>
{
    typedef uchar value_type;
    typedef int work_type;
    typedef uchar channel_type;
    enum { channel_type = CV_8U, channels = 1, fmt='u', type = CV_8U };
};
...
template<typename _Tp> DataType<std::complex<_Tp> >
{
    typedef std::complex<_Tp> value_type;
    typedef std::complex<_Tp> work_type;
    typedef _Tp channel_type;
    // DataDepth は別の traits クラス
    enum { depth = DataDepth<_Tp>::value, channels=2,
        fmt=(channels-1)*256+DataDepth<_Tp>::fmt,
        type=CV_MAKETYPE(depth, channels) };
};
...

このクラスの主な目的は，コンパイル時の型情報を OpenCV と互換性のあるデータ型識別子に変換することです．例えば：

// 30x40 の浮動小数点型行列を確保します．
Mat A(30, 40, DataType<float>::type);

Mat B = Mat_<std::complex<double> >(3, 3);
// 以下の文は， 6, 2 を表示します /* つまり， depth == CV_64F, channels == 2 */
cout << B.depth() << ", " << B.channels() << endl;

つまり，この traits クラスは，ユーザがどんなデータ型を使用しているかを，たとえそのデータ型が OpenCV の組み込み型ではないとしても，OpenCV に教えるために利用されます（OpenCV は適切に特殊化されたクラステンプレート DataType<complex<_Tp> > を定義するので，上述の行列 B の初期化はコンパイルされます）また，この機構は generic algorithm の実装に役立ちます（OpenCV内でもそのように使われています）．

Point_¶

2 次元座標上の点のためのクラステンプレート．

template<typename _Tp> class Point_
{
public:
    typedef _Tp value_type;

    Point_();
    Point_(_Tp _x, _Tp _y);
    Point_(const Point_& pt);
    Point_(const CvPoint& pt);
    Point_(const CvPoint2D32f& pt);
    Point_(const Size_<_Tp>& sz);
    Point_(const Vec<_Tp, 2>& v);
    Point_& operator = (const Point_& pt);
    template<typename _Tp2> operator Point_<_Tp2>() const;
    operator CvPoint() const;
    operator CvPoint2D32f() const;
    operator Vec<_Tp, 2>() const;

    // 内積を計算します． (this->x*pt.x + this->y*pt.y)
    _Tp dot(const Point_& pt) const;
    // 倍精度の演算を用いて内積を計算します．
    double ddot(const Point_& pt) const;
    // この点が矩形 "r" 内に入っていれば真値を返します．
    bool inside(const Rect_<_Tp>& r) const;

    _Tp x, y;
};

このクラスは，その座標値 $x$ と $y$ によって指定される 2 次元の点を表現します．このクラスのインスタンスは， C の構造体である CvPoint や CvPoint2D32f と交換可能です．また，点の座標を指定の型に変換するためのキャスト演算子も存在します．浮動小数点型座標から整数座標への変換は，丸めることで行われます．通常は，それぞれの座標に対して saturate_cast 演算を行います．上述の宣言にあるクラスメンバに加えて，座標点に対する以下の処理が実装されています：

pt1 = pt2 + pt3;
pt1 = pt2 - pt3;
pt1 = pt2 * a;
pt1 = a * pt2;
pt1 += pt2;
pt1 -= pt2;
pt1 *= a;
double value = norm(pt); // L2 ノルム
pt1 == pt2;
pt1 != pt2;

利便性のために，以下のように型の別名が定義されています：

typedef Point_<int> Point2i;
typedef Point2i Point;
typedef Point_<float> Point2f;
typedef Point_<double> Point2d;

ここでは，短い例を示します：

Point2f a(0.3f, 0.f), b(0.f, 0.4f);
Point pt = (a + b)*10.f;
cout << pt.x << ", " << pt.y << endl;

Point3_¶

3 次元座標上の点のためのクラステンプレート．

template<typename _Tp> class Point3_
{
public:
    typedef _Tp value_type;

    Point3_();
    Point3_(_Tp _x, _Tp _y, _Tp _z);
    Point3_(const Point3_& pt);
    explicit Point3_(const Point_<_Tp>& pt);
    Point3_(const CvPoint3D32f& pt);
    Point3_(const Vec<_Tp, 3>& v);
    Point3_& operator = (const Point3_& pt);
    template<typename _Tp2> operator Point3_<_Tp2>() const;
    operator CvPoint3D32f() const;
    operator Vec<_Tp, 3>() const;

    _Tp dot(const Point3_& pt) const;
    double ddot(const Point3_& pt) const;

    _Tp x, y, z;
};

このクラスは，その座標値 $x$ , $y$ , $z$ によって指定される 3 次元の点を表現します．このクラスのインスタンスは， C の構造体 CvPoint2D32f と交換可能です． Point_ の場合と同様に，3 次元点の座標を別の型に変換する事が可能で，さらにベクトル計算や比較演算もサポートされています．

以下のような型の別名が利用可能です：

typedef Point3_<int> Point3i;
typedef Point3_<float> Point3f;
typedef Point3_<double> Point3d;

Size_¶

画像や矩形のサイズを表現するためのクラステンプレート．

template<typename _Tp> class Size_
{
public:
    typedef _Tp value_type;

    Size_();
    Size_(_Tp _width, _Tp _height);
    Size_(const Size_& sz);
    Size_(const CvSize& sz);
    Size_(const CvSize2D32f& sz);
    Size_(const Point_<_Tp>& pt);
    Size_& operator = (const Size_& sz);
    _Tp area() const;

    operator Size_<int>() const;
    operator Size_<float>() const;
    operator Size_<double>() const;
    operator CvSize() const;
    operator CvSize2D32f() const;

    _Tp width, height;
};

Size_ クラスは， 2 つのメンバが x と y ではなく width と height という名前になっていることを除けば， Point_ と同じです．この構造は，古い OpenCV の構造体 CvSize や CvSize2D32f に対して相互に変換可能です．また，このクラスでも Point_ に対する計算や比較演算と同様のものが利用できます．

OpenCVでは，型の別名を以下の用に定義しています：

typedef Size_<int> Size2i;
typedef Size2i Size;
typedef Size_<float> Size2f;

Rect_¶

2 次元の矩形を表現するためのクラステンプレート．

template<typename _Tp> class Rect_
{
public:
    typedef _Tp value_type;

    Rect_();
    Rect_(_Tp _x, _Tp _y, _Tp _width, _Tp _height);
    Rect_(const Rect_& r);
    Rect_(const CvRect& r);
    // (x, y) <- org, (width, height) <- sz
    Rect_(const Point_<_Tp>& org, const Size_<_Tp>& sz);
    // (x, y) <- min(pt1, pt2), (width, height) <- max(pt1, pt2) - (x, y)
    Rect_(const Point_<_Tp>& pt1, const Point_<_Tp>& pt2);
    Rect_& operator = ( const Rect_& r );
    // Point_<_Tp>(x, y) を返します
    Point_<_Tp> tl() const;
    // Point_<_Tp>(x+width, y+height) を返します
    Point_<_Tp> br() const;

    // Size_<_Tp>(width, height) を返します
    Size_<_Tp> size() const;
    // width*height を返します
    _Tp area() const;

    operator Rect_<int>() const;
    operator Rect_<float>() const;
    operator Rect_<double>() const;
    operator CvRect() const;

    // x <= pt.x && pt.x < x + width &&
    // y <= pt.y && pt.y < y + height ? true : false
    bool contains(const Point_<_Tp>& pt) const;

    _Tp x, y, width, height;
};

矩形は，左上コーナの座標（OpenCV ではデフォルトで， Rect_::x と Rect_::y を左上コーナーと解釈しますが，ユーザのアルゴリズムでは x と y を左下のコーナから数える可能性もあります）と，矩形の幅と高さによって表現されます．

OpenCV におけるもう 1 つの前提は，矩形の上側と左側の境界線は矩形に含まれ，右側と下側の境界線は含まれない，ということです．例えば，以下のような場合に， Rect_::contains メソッドは true を返します．

$x \leq pt.x < x+width, y \leq pt.y < y+height$

OpenCV では，画像の ROI （ ROIは Rect_<int> によって指定されます）を処理するループは以下のように実装されます：

for(int y = roi.y; y < roi.y + rect.height; y++)
    for(int x = roi.x; x < roi.x + rect.width; x++)
    {
        // ...
    }

クラスのメンバに加えて，矩形に対する以下の処理が実装されています：

$\texttt{rect} = \texttt{rect} \pm \texttt{point}$ （あるオフセット分だけ矩形を移動する）
$\texttt{rect} = \texttt{rect} \pm \texttt{size}$ （ある量だけ矩形を縮小あるいは拡大する）
rect += point, rect -= point, rect += size, rect -= size （複合代入）
rect = rect1 & rect2 （矩形の共通部分）
rect = rect1 | rect2 （ rect2 と rect3 を含む最小面積の矩形）
rect &= rect1, rect |= rect1 （上記に相当する複合代入）
rect == rect1, rect != rect1 （矩形同士の比較）

[例] ここでは，矩形同士における半順序化がどのように決定されているのかを示します（rect1 $\subseteq$ rect2）：

template<typename _Tp> inline bool
operator <= (const Rect_<_Tp>& r1, const Rect_<_Tp>& r2)
{
    return (r1 & r2) == r1;
}

利便性のため，以下のような型の別名が利用可能です：

typedef Rect_<int> Rect;

RotatedRect¶

回転を考慮した矩形．

class RotatedRect
{
public:
    // コンストラクタ
    RotatedRect();
    RotatedRect(const Point2f& _center, const Size2f& _size, float _angle);
    RotatedRect(const CvBox2D& box);

    // 回転した矩形に対する，最小の（回転していない）外接矩形を返します
    Rect boundingRect() const;
    // CvBox2D に対する後方互換性
    operator CvBox2D() const;

    // 矩形の重心
    Point2f center;
    // サイズ
    Size2f size;
    // degree で表現される回転角度
    float angle;
};

RotatedRect クラスは，古い CvBox2D を置き換え，それと完全な互換性を保ちます．

TermCriteria¶

反復アルゴリズムのための停止基準．

class TermCriteria
{
public:
    enum { COUNT=1, MAX_ITER=COUNT, EPS=2 };

    // コンストラクタ
    TermCriteria();
    // type は， MAX_ITER, EPS, MAX_ITER+EPS の内の1つです．
    // type = MAX_ITER の場合は，反復回数だけが問題になります．
    // type = EPS の場合は，要求精度（イプシロン）だけが問題になります．
    //    （もっとも，大抵のアルゴリズムでは反復回数に何らかの制限を設けますが）
    // type = MAX_ITER + EPS の場合は，反復回数が既定値に達するか，
    // あるいは，要求精度が達成された場合にアルゴリズムが停止します．
    TermCriteria(int _type, int _maxCount, double _epsilon);
    TermCriteria(const CvTermCriteria& criteria);
    operator CvTermCriteria() const;

    int type;
    int maxCount;
    double epsilon;
};

TermCriteria は，古い CvTermCriteria を置き換え，それと完全な互換性を保ちます．

Matx¶

小さい行列のためのクラステンプレート．

template<typename T, int m, int n> class Matx
{
public:
    typedef T value_type;
    enum { depth = DataDepth<T>::value, channels = m*n,
           type = CV_MAKETYPE(depth, channels) };

    // 様々なメソッド
    ...

    Tp val[m*n];
};

typedef Matx<float, 1, 2> Matx12f;
typedef Matx<double, 1, 2> Matx12d;
...
typedef Matx<float, 1, 6> Matx16f;
typedef Matx<double, 1, 6> Matx16d;

typedef Matx<float, 2, 1> Matx21f;
typedef Matx<double, 2, 1> Matx21d;
...
typedef Matx<float, 6, 1> Matx61f;
typedef Matx<double, 6, 1> Matx61d;

typedef Matx<float, 2, 2> Matx22f;
typedef Matx<double, 2, 2> Matx22d;
...
typedef Matx<float, 6, 6> Matx66f;
typedef Matx<double, 6, 6> Matx66d;

このクラスは，コンパイル時に型とサイズが既知である小さい行列を表します．より柔軟な型が必要な場合は， Mat を利用してください．行列 M の要素には， M(i,j) という表記でアクセス可能です．また，一般的な行列演算の大部分（ MatrixExpressions を参照してください）が，利用可能です． Matx に実装されていない操作が必要な場合は，その行列を Mat に変換したり，そこから戻したりすることも簡単に行えます．

Matx33f m(1, 2, 3,
          4, 5, 6,
          7, 8, 9);
cout << sum(Mat(m*m.t())) << endl;

Vec¶

短い数値ベクトル用のクラステンプレート．

template<typename T, int cn> class Vec : public Matx<T, cn, 1>
{
public:
    typedef T value_type;
    enum { depth = DataDepth<T>::value, channels = cn,
           type = CV_MAKETYPE(depth, channels) };

    // 様々なメソッド
};

typedef Vec<uchar, 2> Vec2b;
typedef Vec<uchar, 3> Vec3b;
typedef Vec<uchar, 4> Vec4b;

typedef Vec<short, 2> Vec2s;
typedef Vec<short, 3> Vec3s;
typedef Vec<short, 4> Vec4s;

typedef Vec<int, 2> Vec2i;
typedef Vec<int, 3> Vec3i;
typedef Vec<int, 4> Vec4i;

typedef Vec<float, 2> Vec2f;
typedef Vec<float, 3> Vec3f;
typedef Vec<float, 4> Vec4f;
typedef Vec<float, 6> Vec6f;

typedef Vec<double, 2> Vec2d;
typedef Vec<double, 3> Vec3d;
typedef Vec<double, 4> Vec4d;
typedef Vec<double, 6> Vec6d;

Vec は， Matx の特別な場合です． Vec<T,2> と Point_ は相互に変換可能で， Vec<T,3> と Point3_ も同様です．また， Vec<T,4> は CvScalar や Scalar に変換することができます． Vec の要素にアクセスするには， operator[] を利用します．また，期待されるベクトル演算もすべて実装されています：

$\texttt{v1} = \texttt{v2} \pm \texttt{v3}$ , $\texttt{v1} = \texttt{v2} * \alpha$ , $\texttt{v1} = \alpha * \texttt{v2}$ （さらに，それぞれに相当する複合代入演算．これらの操作は，計算結果のベクトル要素に saturate_cast.3C.3E を適用することに注意してください）
v1 == v2, v1 != v2
norm(v1) ( $L_2$ -norm)

Vec クラスは，マルチチャンネル配列のピクセルタイプを記述するために利用されています． Mat_ の説明を参照してください．

Scalar_¶

4-要素ベクトル．

template<typename _Tp> class Scalar_ : public Vec<_Tp, 4>
{
public:
    Scalar_();
    Scalar_(_Tp v0, _Tp v1, _Tp v2=0, _Tp v3=0);
    Scalar_(const CvScalar& s);
    Scalar_(_Tp v0);
    static Scalar_<_Tp> all(_Tp v0);
    operator CvScalar() const;

    template<typename T2> operator Scalar_<T2>() const;

    Scalar_<_Tp> mul(const Scalar_<_Tp>& t, double scale=1 ) const;
    template<typename T2> void convertTo(T2* buf, int channels, int unroll_to=0) const;
};

typedef Scalar_<double> Scalar;

クラステンプレート Scalar_ および，その倍精度表現のインスタンス Scalar は， 4 要素のベクトルを表します．これらは Vec<_Tp, 4> から派生しているため，典型的な 4-要素ベクトルとして利用でき，さらに CvScalar と相互に変換可能です． Scalar 型は，OpenCV でピクセル値を処理するために広く利用されており，以前の OpenCV で同様に利用されていた CvScalar を手軽に代替することができます．

Range¶

シーケンス内の，連続した部分シーケンス（別名，スライス）を表します．

class Range
{
public:
    Range();
    Range(int _start, int _end);
    Range(const CvSlice& slice);
    int size() const;
    bool empty() const;
    static Range all();
    operator CvSlice() const;

    int start, end;
};

このクラスは，行列（ Mat() ）の行または列の区間を指定するため，またその他多くの目的で利用されます． Range(a,b) は基本的に， Matlab の a:b や Python(numpy) の a..b などと等しいものです． Python での表現と同様に， start は範囲に含まれる左側の境界， end は範囲に含まれない右側の境界です．このような半開区間は，通常 $[start,end)$ と表記されます．

スタティックメソッド Range::all() は，丁度 Matlab での ” : ” や Python(numpy) での ” ... ” と同じように「シーケンス全体」あるいは「範囲全体」を意味する特別な変数を返します．

Range を扱う OpenCV のすべてのメソッドおよび関数は，この特別な値 Range::all() をサポートします．しかしもちろん，ユーザ独自の処理では明示的にそれをチェックして対処する必要があります：

void my_function(..., const Range& r, ....)
{
    if(r == Range::all()) {
        // 全データを処理
    }
    else {
        // [r.start, r.end) を処理
    }
}

Ptr¶

参照カウント方式のスマートポインタクラステンプレート．

template<typename _Tp> class Ptr
{
public:
    // デフォルトコンストラクタ
    Ptr();
    // オブジェクトポインタをラップするコンストラクタ
    Ptr(_Tp* _obj);
    // デストラクタ： release() を呼び出します
    ~Ptr();
    // コピーコンストラクタ． ptr の参照カウントをインクリメントします．
    Ptr(const Ptr& ptr);
    // 代入演算子．（ release() によって）自分の参照カウントをデクリメントし，
    // ptr の参照カウンタをインクリメントします．
    Ptr& operator = (const Ptr& ptr);
    // 参照カウンタをインクリメントします．
    void addref();
    // 参照カウンタをデクリメントします． 0 になった場合，
    // delete_obj() が呼ばれます．
    void release();
    // ユーザ指定のカスタムオブジェクト削除処理．
    // デフォルトでは "delete obj" が呼ばれます．
    void delete_obj();
    // obj == 0 の場合 true を返します．
    bool empty() const;

    // オブジェクトのフィールドとメソッドにアクセスする手段を提供します．
    _Tp* operator -> ();
    const _Tp* operator -> () const;

    // 内部のオブジェクトポインタを返します．
    // このメソッドのおかげで， _Tp* の代わりに
    // Ptr<_Tp> を利用できます．
    operator _Tp* ();
    operator const _Tp*() const;
protected:
    // カプセル化されたオブジェクトポインタ
    _Tp* obj;
    // 参照カウンタ
    int* refcount;
};

Ptr<_Tp> クラスは，対応する型のポインタをラップするクラステンプレートです．これは，Boost ライブラリ（ http://www.boost.org/doc/libs/1_40_0/libs/smart_ptr/shared_ptr.htm ）や， C++0x 標準にある shared_ptr と同様のものです．

このクラスを利用すると，以下のような事が可能になります：

C++ のクラスや C の構造体に対するデフォルトコンストラクタ，コピーコンストラクタ，代入演算子が実現できます．ファイルやウィンドウ， mutex ， socket などのオブジェクトに対して，コピーコンストラクタや代入演算子を定義するのは難しい事です．一方で，OpenCV の複雑な分類器のようなオブジェクトに対しては，コピーコンストラクタが存在せず，実装するのも簡単ではありません．また，OpenCV やユーザ自身のデータ構造体の中には C で書かれたものもあるでしょう．しかし，コピーコンストラクタやデフォルトコンストラクタは，プログラミングを非常に簡単にします．さらに，（例えば， STL のコンテナなどで）必要になる事も多いでしょう．このような複雑なオブジェクト TObj へのポインタを Ptr<TObj> という風にラッピングする事で，必要とするすべてのコンストラクタや割り当て演算子を自動的に得ることができます．
上述の処理はデータサイズに関係なく非常に高速に，つまり “O(1)” の定数時間で行われます．実際， std::vector などの構造体はコピーコンストラクタと割り当て演算子を提供しますが，データ構造体が大きい場合この処理には無視できない時間がかかります．しかし，その構造体が Ptr<> でラッピングされていれば，データサイズとは関係なく小さいオーバーヘッドで済みます．
C の構造体でも自動的にデストラクションが可能になります．以下の FILE* を用いた例を参照してください．
異種オブジェクトのコレクションが実現できます．標準の STL，他の多くの C++ や OpenCV のコンテナは，同じ型，同じサイズのオブジェクトしか格納することができません．異なる型のオブジェクトを同じコンテナに収める古典的な方法は，代わりに基底クラス base_class_t* のポインタを格納することですが，それは自動的なメモリ管理を諦めることになります．ここで再び，単純なポインタの代わりに Ptr<base_class_t>() を利用することで，この問題を解決できます．

Ptr クラスは，ラッピングされたオブジェクトをブラックボックスとして扱います．参照カウンタは個別に確保，管理されます．ポインタクラスが知っておく必要があるのは，オブジェクトの解放の方法だけです．それは， Ptr::delete_obj() メソッドにカプセル化され，参照カウンタが 0 になったときに呼ばれます．このメソッドはデフォルトで delete obj; を呼ぶので，オブジェクトが C++ のクラスインスタンスである場合は，追加のコーディングは必要ありません．しかし，オブジェクトが別の方法で解放される場合は，専用のメソッドを作る必要があります．例えば， FILE をラッピングしたい場合は， delete_obj を以下のような感じで実装します：

template<> inline void Ptr<FILE>::delete_obj()
{
    fclose(obj); // さらにポインタをクリアする必要はありません．
                 // その処理，この外側で行われます．
}
...

// 使い方
Ptr<FILE> f(fopen("myfile.txt", "r"));
if(f.empty())
    throw ...;
fprintf(f, ....);
...
// Ptr<FILE> のデストラクタによって， FILE は自動的に閉じられます．

注意：参照のインクリメント/デクリメント処理は，不可分な処理として実装されているので，このクラスをマルチスレッドアプリケーションで利用しても通常は安全です．また，参照カウンタを利用する Mat() やその他の OpenCV のクラスも同様です．

Mat¶

OpenCV C++ の n-次元の密な配列クラス．

class CV_EXPORTS Mat
{
public:
    // ... 大量のメソッド ...
    ...

    /*! 複数のビットフィールドを含みます：
         - マジックシグネチャ
         - 連続性フラグ
         - ビット深度
         - チャンネル数
     */
    int flags;
    //! 配列の次元 >= 2
    int dims;
    //! 行数および列数．配列が 2 次元以上の場合は (-1, -1) となります．
    int rows, cols;
    //! データを指すポインタ
    uchar* data;

    //! 参照カウンタを指すポインタ．
    // ユーザが確保したデータを指す配列の場合，このポインタは NULL になります．
    int* refcount;

    // その他のメンバ
    ...
};

クラス Mat は，シングルチャンネル，またはマルチチャンネルの，密な n-次元数値配列です．実数，複素数値のベクトルや行列，グレースケール画像，カラー画像，ボクセルボリューム，ベクトル場，ポイントクラウド，テンソル，ヒストグラム（ただし，超高次元ヒストグラムの場合は， SparseMat の方が適しているかもしれません）などを格納するのに利用されます．配列 $M$ のデータレイアウトは，配列 M.step[] によって定義され，要素 $(i_0,...,i_{M.dims-1})$ （ここで， $0\leq i_k<M.size[k]$ ）のアドレスは次のように求められます：

$addr(M_{i_0,...,i_{M.dims-1}}) = M.data + M.step[0]*i_0 + M.step[1]*i_1 + ... + M.step[M.dims-1]*i_{M.dims-1}$

2 次元配列の場合は，上述の式は，次のように簡略化できます：

$addr(M_{i,j}) = M.data + M.step[0]*i + M.step[1]*j$

また， M.step[i] >= M.step[i+1] （実際は， M.step[i] >= M.step[i+1]*M.size[i+1] ）であることに注意してください．つまり，2 次元の行列は行毎に格納され，3 次元の行列は平面毎に格納される，という風になっています． M.step[M.dims-1] が最小で，これは常に要素サイズ M.elemSize() と一致します．

これは， Mat のデータレイアウトが， OpenCV 1.x の CvMat , IplImage および CvMatND と完全に互換性があることを意味します．Numpy (ndarray)，Win32 (device independent bitmap) などの標準的なツールキットやSDKの密な配列型，つまり，ピクセルの位置を計算するために “steps” （別名 “strides”）を利用する任意の配列に対しても同様です．この互換性により，ユーザが確保したデータに対する Mat ヘッダを作成し，OpenCV の関数を用いて，その値を置換しながら処理することが可能になります．

Mat オブジェクトを作成する方法はたくさんありますが，ここではポピュラーなものをいくつか示します：

create(nrows, ncols, type) メソッドや，それと同様のコンストラクタ Mat(nrows, ncols, type[, fillValue]) を利用します．

指定されたサイズ，型の新しい配列が確保されます．ここで

type は， cvCreateMat の場合と同じ意味を持ちます．

例えば，

CV_8UC1 は 8 ビットでシングルチャンネルの行列，

CV_32FC2 は 2 チャンネル（つまり複素数）浮動小数点型の配列を表します．
```
// 1+3j で埋められた 7x7 の複素行列を作成します．
cv::Mat M(7,7,CV_32FC2,Scalar(1,3));
// そして， M を 100x60 で 15 チャンネル 8 ビットの行列に変更します．
// 行列の以前の内容は解放されます．
M.create(100,60,CV_8UC(15));
```
この章のイントロダクションでも述べたように， create() は，現在の配列の形状や型が指定されたものと異なる場合のみ，新しい行列を確保します．
similarly to above, you can create a multi-dimensional array:
```
// 100x100x100 で 8 ビットの配列を作成します．
int sz[] = {100, 100, 100};
cv::Mat bigCube(3, sz, CV_8U, Scalar::all(0));
```
Mat コンストラクタに次元数 =1 が渡された場合でも，列数が 1 に設定された 2 次元の配列が作成されることに注意してください．これが， Mat::dims が常に >=2 （配列が空の場合は 0 にもなり得ます）である理由です．
コンストラクタや代入演算子を利用します．この場合，右辺は配列か matrix expression になります．詳しくは以下を参照してください．同じくイントロダクションで述べたように，配列の代入はヘッダをコピーして参照カウンタを増加させるだけなので O(1) の処理です．必要なときには Mat::clone() メソッドを使って，配列の完全なコピー（つまり，深いコピー）を得ることができます．

別の配列の一部分に対するヘッダを作成します．これは，配列の 1 行や 1 列，複数行や複数列，矩形領域（代数では小行列式と呼ばれます），対角要素などに対して可能です．新しいヘッダも同じデータを参照するので，この様な処理も O(1) です．この特徴を利用すると，例えば以下のように，配列の一部を実際に変更することができます．

// 5 行目 を 3 倍して， 3 行目に足します．
M.row(3) = M.row(3) + M.row(5)*3;

// 7 列目を 1 列目にコピーします．
// M.col(1) = M.col(7); // これは動作しません
Mat M1 = M.col(1);
M.col(7).copyTo(M1);

// 新たに 320x240 の画像を作成します．
cv::Mat img(Size(320,240),CV_8UC3);
// ROI を選択します．
cv::Mat roi(img, Rect(10,10,100,100));
// ROI を (0,255,0) （ RGB 空間での緑）で埋めます．
// 320x240 の元の画像は変更されます．
roi = Scalar(0,255,0);

datastart および dataend メソッドが追加されたおかげで， locateROI() を用いてメインの “コンテナ” 配列内の部分配列の相対位置を計算することができます．

Mat A = Mat::eye(10, 10, CV_32S);
// 1 列目（範囲に含む）から 3 列目（含まない）までを A として抽出します
Mat B = A(Range::all(), Range(1, 3));
// 5 行目（範囲に含む）から 9 行目（含まない）までを B として抽出します
// つまり， C ~ A(Range(5, 9), Range(1, 3))
Mat C = B(Range(5, 9), Range::all());
Size size; Point ofs;
C.locateROI(size, ofs);
// サイズは (width=10,height=10) ， ofs は (x=1, y=5)

行列全体の場合と同様に，深いコピーが必要ならば，抽出された部分行列の clone() メソッドを利用します．

ユーザが確保したデータに対するヘッダを作成します．これは，以下の場合に有用です：
1. OpenCVを用いた「別の」データの処理
  
  （例えば， DirectShow のフィルタや， gstreamer の処理モジュールなどを実装する場合）
```
void process_video_frame(const unsigned char* pixels,
                         int width, int height, int step)
{
    cv::Mat img(height, width, CV_8UC3, pixels, step);
    cv::GaussianBlur(img, img, cv::Size(7,7), 1.5, 1.5);
}
```
2. 小さい行列の手軽な初期化および/または超高速な要素アクセス
```
double m[3][3] = {{a, b, c}, {d, e, f}, {g, h, i}};
cv::Mat M = cv::Mat(3, 3, CV_64F, m).inv();
```
このように「ユーザが確保したデータに対するヘッダを作成する」場合， CvMat や IplImage から Mat への変換が，非常に頻繁に行われる事があります．このために， CvMat や IplImage へのポインタをとる専用のコンストラクタと，データをコピーするか否かを指定するオプションフラグが存在します．

また，

Mat から CvMat や IplImage への後方変換は，キャスト演算子 Mat::operator CvMat() const と Mat::operator IplImage() によって提供されます．この演算子は，データをコピー しません ．
```
IplImage* img = cvLoadImage("greatwave.jpg", 1);
Mat mtx(img); // IplImage* -> cv::Mat の変換
CvMat oldmat = mtx; // cv::Mat -> CvMat の変換
CV_Assert(oldmat.cols == img->width && oldmat.rows == img->height &&
    oldmat.data.ptr == (uchar*)img->imageData && oldmat.step == img->widthStep);
```

MATLAB 形式 zeros(), ones(), eye() の配列初期化，つまり：

// 倍精度の単位行列を作成して，それを M に足します．
M += Mat::eye(M.rows, M.cols, CV_64F);

カンマ区切りの初期化子：
```
// 3x3 の倍精度単位行列を作成します．
Mat M = (Mat_<double>(3,3) << 1, 0, 0, 0, 1, 0, 0, 0, 1);
```
ここでは，まず（後で述べる） Mat_ クラスのコンストラクタに適切なパラメータを与えて呼び出し，さらに << 演算子に続いて，定数，変数，式などから成るカンマ区切りの値を与えています．また，コンパイルエラーを避けるために，カッコが必要なことにも注意してください．

一度作成された配列は，参照カウント機構により自動的に管理されます（ただし，ユーザが確保したデータに対して配列ヘッダが作成される場合を除きます．この場合，ユーザ自身がデータを処理しなければいけません）．配列データは，それを指し示すものがなくなった場合に解放されます．配列のデストラクタが呼ばれるよりも前に，その配列ヘッダによって指されるデータを解放したい場合は， Mat::release() を利用してください．

配列クラスに関して次に学ぶ重要事項は，要素へのアクセスです．各配列要素のアドレスを計算する方法は既に述べました．通常は，コード内でその式を直接使う必要はありません．配列の型（ Mat::type() メソッドを利用して得ることができます）が既知ならば，次のようにして 2 次元配列の要素 $M_{ij}$ にアクセスすることができます：

M.at<double>(i,j) += 1.f;

ここでは， M が倍精度の浮動小数点型配列だと仮定しています．また，異なる次元数に対応する複数の at メソッドが用意されています．

行列の行全体を処理する必要がある場合に最も効率的な方法は，最初の行のポインタを取得して，純粋な C 言語の演算子 [] を利用することです：

// 値が正である要素の合計を求めます．
// （ここで M は倍精度行列と仮定します）
double sum=0;
for(int i = 0; i < M.rows; i++)
{
    const double* Mi = M.ptr<double>(i);
    for(int j = 0; j < M.cols; j++)
        sum += std::max(Mi[j], 0.);
}

上述のような処理は，実際は配列の形には依存せず，配列要素を 1 つ 1 つ処理する（または，配列同士の足し算のように，複数の配列の同じ座標にある要素を処理する）だけです．このような処理は要素ワイズと呼ばれ，すべての入出力配列が連続であるか，つまり，各行末にギャップが存在しないかどうかをチェックするのが常套手段です．もしそうならば，長く続く 1 つの行であるかのように処理できます．

// 値が正である要素の合計を求めます，最適化版
double sum=0;
int cols = M.cols, rows = M.rows;
if(M.isContinuous())
{
    cols *= rows;
    rows = 1;
}
for(int i = 0; i < rows; i++)
{
    const double* Mi = M.ptr<double>(i);
    for(int j = 0; j < cols; j++)
        sum += std::max(Mi[j], 0.);
}

値が連続する行列の場合，外側のループは 1 回だけ実行されるのでオーバーヘッドが小さくなります．これは，特に小さい行列の場合に顕著です．

最後に，行と行の間のギャップをスキップする STL 形式の優れたイテレータの例を述べます：

// 値が正である要素の合計を求める，イテレータ利用版
double sum=0;
MatConstIterator_<double> it = M.begin<double>(), it_end = M.end<double>();
for(; it != it_end; ++it)
    sum += std::max(*it, 0.);

行列のイテレータは，ランダムアクセスイテレータなので， std::sort() を含むすべての STL アルゴリズムに適用できます．

Matrix Expressions¶

これは，実装されている行列演算の一覧であり，組み合わせて任意の複雑な表現を行うこともできます（ここで A と B は行列を表し， s はスカラ（ Scalar ）を， $\alpha$ は実数値のスカラ（ double ）を表します）．

加算，減算，符号反転： $A \pm B,\;A \pm s,\;s \pm A,\;-A$
スケーリング： $A*\alpha$ , $A*\alpha$
要素毎の積，商： $A.mul(B), A/B, \alpha/A$
行列の積： $A*B$
転置： $A.t() \sim A^t$
逆行列，擬似逆行列，連立方程式，最小二乗問題の解：

$A.inv([method]) \sim A^{-1}, A.inv([method])*B \sim X:\,AX=B$
比較： $A\gtreqqless B,\;A \ne B,\;A \gtreqqless \alpha,\;A \ne \alpha$ .

比較結果は，8 ビットのシングルチャンネルマスクで，（特定の要素，あるいは要素の組が条件を満たしていれば）255 か，（そうでなければ）0 にセットされます．
ビット単位の論理演算： A & B, A & s, A | B, A | s, A textasciicircum B, A textasciicircum s, ~ A
要素単位の最小値，最大値： $min(A, B), min(A, \alpha), max(A, B), max(A, \alpha)$
要素単位の絶対値： $abs(A)$
外積，内積： $A.cross(B), A.dot(B)$
行列かスカラを返す，行列，行列同士，スカラに対するあらゆる演算．例えば，

norm() , mean() , sum() , countNonZero() , trace() ,

determinant() , repeat() など．
行列の初期化子（ eye(), zeros(), ones() ），行列のカンマ区切り初期化子，行列コンストラクタ，部分行列を抽出する演算子（ Mat() の説明を参照してください）．
結果を適切な型に変換するための verb “Mat_<destination_type>()” コンストラクタ．

また，カンマ区切りの初期化子，あるいはその他の演算は，曖昧さを回避するために明示的に Mat() や verb “Mat_<T>()” コンストラクタを呼び出す必要があるかもしれない事に注意してください．

以下は， Mat のメソッドの正式な説明です．

ナビゲーション

基本構造体¶

DataType¶

Point_¶

Point3_¶

Size_¶

Rect_¶

RotatedRect¶

TermCriteria¶

Matx¶

Vec¶

Scalar_¶

Range¶

Ptr¶

Mat¶

Matrix Expressions¶

cv::Mat::Mat¶

cv::Mat::Mat¶

cv::Mat::operator =¶

cv::Mat::operator MatExpr¶

cv::Mat::row¶

cv::Mat::col¶

cv::Mat::rowRange¶

cv::Mat::colRange¶

cv::Mat::diag¶

cv::Mat::clone¶

cv::Mat::copyTo¶

cv::Mat::convertTo¶

cv::Mat::assignTo¶

cv::Mat::setTo¶

cv::Mat::reshape¶

cv::Mat::t¶

cv::Mat::inv¶

cv::Mat::mul¶

cv::Mat::cross¶

cv::Mat::dot¶

cv::Mat::zeros¶

cv::Mat::ones¶

cv::Mat::eye¶

cv::Mat::create¶

cv::Mat::addref¶

cv::Mat::release¶

cv::Mat::resize¶

Mat::push_back¶

Mat::pop_back¶

cv::Mat::locateROI¶

cv::Mat::adjustROI¶

cv::Mat::operator()¶

cv::Mat::operator CvMat¶

cv::Mat::operator IplImage¶

cv::Mat::total¶

cv::Mat::isContinuous¶

cv::Mat::elemSize¶

cv::Mat::elemSize1¶

cv::Mat::type¶

cv::Mat::depth¶

cv::Mat::channels¶

cv::Mat::step1¶

cv::Mat::size¶

cv::Mat::empty¶

cv::Mat::ptr¶

cv::Mat::at¶

cv::Mat::begin¶

cv::Mat::end¶

Mat_¶

NAryMatIterator¶

SparseMat¶

SparseMat_¶

ヘルプとフィードバック

目次

前のトピックへ

次のトピックへ

このページ

クイック検索

ナビゲーション