CXCORE リファレンス マニュアル
- 基本構造体（Basic Structures）
- 配列操作（Operations on Arrays）
- 動的構造体（Dynamic Structures）
- 描画関数（Drawing Functions）
- データ永続性と実行時型情報（Data Persistence and RTTI）
- その他の関数（Miscellaneous Functions）
- エラーハンドリングとシステム関数（Error Handling and System Functions）
配列操作（Operations on Arrays）
線形代数（Linear Algebra）
DotProduct
ユークリッド距離に基づく2つの配列の内積を計算する
double cvDotProduct( const CvArr* src1, const CvArr* src2 );
- src1
- 1番目の入力配列．
- src2
- 2番目の入力配列．
関数cvDotProductはユークリッド幾何学における内積を計算し，その結果を返す．
src1•src2 = sumI(src1(I)*src2(I))
マルチチャンネル配列の場合，全てのチャンネルの結果が累算される．特にaを複素ベクトルとすると，cvDotProduct(a,a) は ||a||2を返す．この関数は，多次元配列を1行，1レイヤーずつ処理することもできる．
Normalize
指定のノルムになるように，あるいは値が指定の範囲になるように，配列を正規化する
void cvNormalize( const CvArr* src, CvArr* dst,
double a=1, double b=0, int norm_type=CV_L2,
const CvArr* mask=NULL );
- src
- 入力配列．
- dst
- 出力配列．インプレース処理が可能．
- a
- 出力配列の最小値または最大値，あるいは出力配列のノルム．
- b
- 出力配列の最大値または最小値．
- norm_type
- 正規化のタイプ．以下のうち一つを用いることができる．
CV_C - 配列のC-norm（絶対値の最大値）を正規化
CV_L1 - 配列のL1-norm（絶対値の合計）を正規化
CV_L2 - 配列のL2-norm（ユークリッド距離）を正規化
CV_MINMAX - 配列の値が指定の範囲に収まるようにスケーリングとシフトを行う．
- mask
- 操作マスク．特定の配列要素のみを正規化するためのマスク．
関数cvNormalizeは，入力配列をそのノルム，または値が特定の値や範囲になるように正規化する．
norm_type==CV_MINMAXのとき，
dst(i,j)=(src(i,j)-min(src))*(b'-a')/(max(src)-min(src)) + a', （mask(i,j)!=0 の場合）
dst(i,j)=src(i,j) （それ以外の場合）
ここで b'=MAX(a,b)，a'=MIN(a,b)．min(src) と max(src) はそれぞれ入力配列の全体，または指定された部分集合について計算した全体の最小値と最大値である．
norm_type!=CV_MINMAXのとき，
dst(i,j)=src(i,j)*a/cvNorm(src,0,norm_type,mask), （mask(i,j)!=0 の場合）
dst(i,j)=src(i,j) （それ以外の場合）
以下に，簡単な例を示す．
float v[3] = { 1, 2, 3 };
CvMat V = cvMat( 1, 3, CV_32F, v );
// 単位ベクトルの生成
// これは，以下と等しい．
// for(int i=0;i<3;i++) v[i]/=sqrt(v[0]*v[0]+v[1]*v[1]+v[2]*v[2]);
cvNormalize( &V, &V );
CrossProduct
二つの3次元ベクトルの外積を計算する
void cvCrossProduct( const CvArr* src1, const CvArr* src2, CvArr* dst );
- src1
- 1番目の入力ベクトル．
- src2
- 2番目の入力ベクトル．
- dst
- 出力ベクトル．
関数 cvCrossProduct は，二つの3次元ベクトルの外積を計算する．
dst = src1 × src2, (dst1 = src12src23 - src13src22 , dst2 = src13src21 - src11src23 , dst3 = src11src22 - src12src21).
ScaleAdd
スケーリングされた配列ともう一つの配列の和を計算する
void cvScaleAdd( const CvArr* src1, CvScalar scale, const CvArr* src2, CvArr* dst );
#define cvMulAddS cvScaleAdd
- src1
- 1番目の入力配列
- scale
- 1番目の配列のためのスケールファクタ．
- src2
- 2番目の入力配列．
- dst
- 出力配列．
関数cvScaleAddは，スケーリングされた配列ともう一つの配列の和を計算する．
dst(I)=src1(I)*scale + src2(I)
全ての配列パラメータは同じタイプで同じサイズでなくてはならない．
GEMM
汎用的な行列の乗算を行う
void cvGEMM( const CvArr* src1, const CvArr* src2, double alpha,
const CvArr* src3, double beta, CvArr* dst, int tABC=0 );
#define cvMatMulAdd( src1, src2, src3, dst ) cvGEMM( src1, src2, 1, src3, 1, dst, 0 )
#define cvMatMul( src1, src2, dst ) cvMatMulAdd( src1, src2, 0, dst )
- src1
- 1番目の入力配列．
- src2
- 2番目の入力配列．
- alpha
- 乗算結果に対するスケーリング係数．以下の説明を参照．
- src3
- 3番目の入力配列（シフト用）．もしシフトしない場合はNULLにできる．
- beta
- 3番目の入力配列に対するスケーリング係数．以下の説明を参照．
- dst
- 出力配列．
- tABC
- 操作フラグ．0または以下の値の組み合わせ．
CV_GEMM_A_T - src1を転置
CV_GEMM_B_T - src2を転置
CV_GEMM_C_T - src3を転置
例：CV_GEMM_A_T+CV_GEMM_C_Tは， alpha*src1T*src2 + beta*src3Tに対応する．
関数cvGEMMは汎用的な行列の乗算を行う．
dst = alpha*op(src1)*op(src2) + beta*op(src3), ここで， op(X) は X あるいは XT
全ての行列は同じデータタイプ，同じサイズである必要がある．実数あるいは複素数の浮動小数点型の行列がサポートされている．
Transform
すべての配列要素を行列により変換する
void cvTransform( const CvArr* src, CvArr* dst, const CvMat* transmat, const CvMat* shiftvec=NULL );
- src
- 1番目の入力配列．
- dst
- 出力配列．
- transmat
- 変換行列．
- shiftvec
- オプションのシフトベクトル．
関数cvTransformは，srcの全て要素に行列変換を行い，その結果をdst に保存する．
dst(I)=transmat*src(I) + shiftvec または dst(I)k=sumj(transmat(k,j)*src(I)j) + shiftvec(k)
つまり，Nsrc個の要素をもつベクトルとして取り扱い， M×N行列transmatとシフトベクトルshiftvec を用いて， Mチャンネル配列dstの一つの要素へと変換する． shiftvec を transmatへ埋め込むという選択もある． この場合，transmatはM×N+1の行列でなければならず，最右列はシフトベクトルとして扱われる．
入力配列と出力配列は共にデプスが等しく，サイズあるいは選択されたROIのサイズが同じでなければならない．transmatとshiftvecは浮動小数点型の実数行列でなくてはならない．
この関数は，N次元点集合の幾何変換，任意の色空間の線形変換，チャンネルのシャッフル等に使用される．
PerspectiveTransform
ベクトルの透視投影変換を行う
void cvPerspectiveTransform( const CvArr* src, CvArr* dst, const CvMat* mat );
- src
- 3チャンネルの浮動小数点型入力配列．
- dst
- 3チャンネルの浮動小数点型出力配列．
- mat
- 3×3 または 4×4 の変換行列．
関数cvPerspectiveTransformは，以下のように，srcのすべての要素を2次元あるいは3次元ベクトルとして扱い，これを変換する．
(x, y, z) -> (x’/w, y’/w, z’/w) または
(x, y) -> (x’/w, y’/w),
ここで，
(x’, y’, z’, w’) = mat4x4*(x, y, z, 1) または
(x’, y’, w’) = mat3x3*(x, y, 1)
w = w’ （w’!=0 の場合）
inf （そうでない場合）
MulTransposed
行列と転置行列の乗算を行う
void cvMulTransposed( const CvArr* src, CvArr* dst, int order, const CvArr* delta=NULL );
- src
- 入力行列．
- dst
- 出力行列．
- order
- 転置した行列をかける順番．
- delta
- オプション配列，乗算する前にsrcから引かれる．
関数cvMulTransposedはsrcとその転置行列との乗算を計算する．
この関数は，以下のように計算を行う．
dst=(src-delta)*(src-delta)T
（order=0 の場合）
dst=(src-delta)T*(src-delta)
（そうでない場合）．
Trace
行列のトレースを返す
CvScalar cvTrace( const CvArr* mat );
- mat
- 入力行列．
関数cvTraceは，行列matの対角成分の和を返す．
tr(src1)=sumimat(i,i)
Transpose
行列の転置を行う
void cvTranspose( const CvArr* src, CvArr* dst );
#define cvT cvTranspose
- src
- 入力行列．
- dst
- 出力行列．
関数cvTransposeは行列srcを転置する．
dst(i,j)=src(j,i)
注釈：複素行列の場合，複素数の共役化は行わない．共役は別に計算されるべきである．例として，cvXorS のサンプルコードを参照すること．
Det
行列式を返す
double cvDet( const CvArr* mat );
- mat
- 入力行列．
関数cvDetは，正方行列matの行列式を返す． 小さい行列に対しては直接法が，大きい行列に対してはガウスの消去法が使用される． 正定値対称行列については，U=V=NULLとしてSVDを実行し， その後Wの対角要素の内積として行列式を計算することも可能である．
Invert
逆行列または擬似逆行列を求める
double cvInvert( const CvArr* src, CvArr* dst, int method=CV_LU );
#define cvInv cvInvert
- src
- 入力行列．
- dst
- 出力行列．
- method
- 逆行列を求める手法．
CV_LU - 最適なピボット選択によるガウスの消去法
CV_SVD - 特異値分解（SVD）
CV_SVD_SYM - 正定値対称行列のための特異値分解
関数cvInvertはsrcの逆行列を計算し，その結果をdstに入れる．
LUの場合，この関数はsrcの行列式を返す（srcは正方行列でなくてなならない）． 行列式が0の場合， 逆行列は計算できずdstは0で埋められる．
SVDの場合，この関数はsrcの条件数の逆数（大きい特異値に対する小さい特異値の比）を返す． また，srcが全て0のときは0を返す． もし，srcが非正則行列の場合，SVDを用いる方法では擬似逆行列を計算する．
Solve
連立一次方程式または最小二乗問題を解く
int cvSolve( const CvArr* A, const CvArr* B, CvArr* X, int method=CV_LU );
- A
- 入力行列．
- B
- 連立一次方程式の右辺．
- X
- 出力解．
- method
- 逆行列の解法．
CV_LU - 最適なピボット選択によるガウスの消去法
CV_SVD - 特異値分解
CV_SVD_SYM - 対称正定値行列のための特異値分解．
関数cvSolveは，連立一次方程式または最小二乗問題を解く（後者は特異値分解を用いて解くことが可能である）．
dst = arg minX||A*X-B||
methodにCV_LU を指定した場合，Aが正則行列であれば１を返し，そうでなければ0を返す． 後者の場合は，dstの値は有効ではない．
SVD
浮動小数点型の実数行列の特異値分解を行う
void cvSVD( CvArr* A, CvArr* W, CvArr* U=NULL, CvArr* V=NULL, int flags=0 );
- A
- 入力M×N行列．
- W
- 特異値行列の結果 (M×N または N×N)または ベクトル（N×1）．
- U
- 任意の左直交行列 (M×M または M×N)． もしCV_SVD_U_Tが指定された場合，上で述べた，行と列の数は入れ替わる．
- V
- 任意の右直交行列（N×N)．
- flags
- 操作フラグ．0または以下の値の組み合わせ．
- CV_SVD_MODIFY_A を指定すると，計算中に行列Aの変更を行うことができる． このフラグの指定は処理速度を向上させる．
- CV_SVD_U_T means that the tranposed matrix U is returned. Specifying the flag はUの転置行列を返すことを意味する．このフラグの指定は処理速度を向上させる．
- CV_SVD_V_T はVの転置行列を返すことを意味する．このフラグの指定は処理速度を向上させる．
関数cvSVDは，行列Aを二つの直交行列と一つの対角行列の積に分解する．
A=U*W*VT
ここで，Wは特異値の対角行列であり，特異値の1次元のベクトルとして表現する事もできる．すべての特異値は非負の値を持ち，降順にソートされる （UとVの行も共に）．
SVDアルゴリズムは数値的にロバストであり，その典型的な応用は，以下のようになる．
- 行列Aが正方行列で正定値対称行列として定義されている（例えば，それが共変動行列である）とき，厳密な固有値問題の解法である． このケースにおいてWは固有値のベクトルとなり，U=Vは固有ベクトルの行列となる． （したがって，固有ベクトルが必要となる場合は，UまたはVの片方だけを計算すればよい)．
- 方程式よりも未知数が多い線形問題（過少システム）における厳密な解法．
- 未知数よりも方程式が多い線形問題（過多システム）における最小二乗法による解法． これと前述の場合には，methodにCV_SVDを指定した関数cvSolveが実行される．
- ランク（０ではない特異値の数），条件数（最大の特異値と最小の特異値との比率），行列式（特異値の積に等しい行列式の絶対値）などの，様々な行列特徴量の高精度な計算．ここにリストされたすべての項目は U行列と V行列の計算を必要としない．
SVBkSb
特異値の後退代入を行う
void cvSVBkSb( const CvArr* W, const CvArr* U, const CvArr* V,
const CvArr* B, CvArr* X, int flags );
- W
- 特異値の行列またはベクトル．
- U
- 左直交行列（転置されているかもしれない）
- V
- 右直交行列（転置されているかもしれない）
- B
- 行列Aの擬似逆行列に乗ずるための行列．オプションのパラメータ． 省略されている場合，それは適切なサイズの単位行列であると仮定される（そのためXはAの再構成された擬似逆行列となる）．
- X
- 出力行列．後退代入の結果．
- flags
- 操作フラグ．cvSVDでのflagsと一致していなければならない．
関数cvSVBkSbは，分解される行列A（cvSVDを参照）と行列Bのための後退代入を計算する．
X=V*W-1*UT*B
ここで，
W-1(i,i)=1/W(i,i) （W(i,i) > epsilon•sumiW(i,i) の場合）
0 （それ以外の場合）
また，epsilonは行列のデータタイプに依存する小さな数値である．
この関数はcvSVDと 共に，cvInvert， cvSolveの内部で用 いられる．これら（svd と bksb) の低レベル関数を使用する状況があるとすれば，高レベル関数（inv と solve）において一時的な行列の確保を避けるためであろう．EigenVV
対称行列の固有値と固有ベクトルを計算する
void cvEigenVV( CvArr* mat, CvArr* evects, CvArr* evals, double eps=0 );
- mat
- 入力対称正方行列．処理中に変更される．
- evects
- 固有ベクトルの出力行列．連続した行として保存される．
- evals
- 固有値ベクトルの出力ベクトル．降順に保存される（もちろん固有値と固有ベクトルの順番は一致する）．
- eps
- 対角化の精度（一般的に，DBL_EPSILON=≈10-15 で十分である）．
関数cvEigenVVは，行列matの固有値と固有ベクトルを計算する．
mat*evects(i,:)' = evals(i)*evects(i,:)' （MTALAB表記）
行列matの内容はこの関数によって破壊される．
現在，この関数はcvSVDより遅く，精度も低い． そこで，matが正定値行列であることが既知のとき (例えば共変動行列）は， 行列matの固有値，固有ベクトルを求めるために（特に，固有ベクトルが必要とされない場合）， cvSVDを使用することが推奨される． これは，
cvEigenVV(mat, eigenvals, eigenvects);の代わりに
cvSVD(mat, eigenvals, eigenvects, 0, CV_SVD_U_T + CV_SVD_MODIFY_A);を呼ぶということである．
CalcCovarMatrix
ベクトル集合の共変動行列を計算する
void cvCalcCovarMatrix( const CvArr** vects, int count, CvArr* cov_mat, CvArr* avg, int flags );
- vects
- 入力ベクトル．これらはすべて同じタイプで同じサイズでなくてはならない． ベクトルは1次元である必要はなく，2次元（例えば，画像）などでも構わない．
- count
- 入力ベクトルの数．
- cov_mat
- 浮動小数点型の正方な出力共変動行列．
- avg
- 入力または出力配列（フラグに依存する） - 入力ベクトルの平均ベクトル．
- flags
- 操作フラグ．以下の値の組み合わせ．
CV_COVAR_SCRAMBLED - 出力共変動行列は次のように計算される．
scale*[vects[0]-avg,vects[1]-avg,...]T*[vects[0]-avg,vects[1]-avg,...]
すなわち，共変動行列はcount×countである． そのような一般的でない共変動行列は，非常に大きなベクトル集合に対する高速な主成分分析のために使用される（例えば，顔認識のための固有顔）． この「スクランブルされた」行列の固有値は，真共変動行列の固有値と一致し， そして「真の」固有ベクトルは「スクランブルされた」共変動行列の固有ベクトルから容易に計算できる．
CV_COVAR_NORMAL - 出力共変動行列は次のように計算される．
scale*[vects[0]-avg,vects[1]-avg,...]*[vects[0]-avg,vects[1]-avg,...]T
つまり，cov_matはすべての入力ベクトルの要素の合計と同じサイズの一般的な共変動行列となる． CV_COVAR_SCRAMBLEDとCV_COVAR_NORMALのどちらか一つは必ず指定されなくてはならない．
CV_COVAR_USE_AVG - このフラグが指定された場合，関数は入力ベクトルから平均を計算せず，引数で指定された平均ベクトルを使用する． 平均が何らかの方法で既に計算されている場合，または共変動行列が部分的に計算されている場合 （この場合，avgは入力ベクトルの一部の平均ではなく，全ての平均ベクトルである）に有用である．
CV_COVAR_SCALE - このフラグが指定された場合， 共変動行列は入力ベクトルの数によってスケーリングされる．
CV_COVAR_ROWS - 全ての入力ベクトルは単一の行列（vects[0]）の行として保存されることを意味する． この場合，countは無視される．そしてavgは適切な大きさの1行のベクトルでなければならない．
CV_COVAR_COLS - 全ての入力ベクトルは単一の行列（vects[0]）の列として保存されることを意味する． この場合，countは無視される．そしてavgは適切な大きさの1列のベクトルでなければならない．
関数cvCalcCovarMatrixは，共変動行列と，オプションで入力ベクトル集合の平均を計算する． この関数は，主成分分析やマハラノビス距離によるベクトルの比較等に用いられる．
Mahalanobis
二つのベクトルのマハラノビス距離を計算する
double cvMahalanobis( const CvArr* vec1, const CvArr* vec2, CvArr* mat );
- vec1
- 1番目の1次元入力ベクトル．
- vec2
- 2番目の1次元入力ベクトル．
- mat
- 逆共変動行列．
関数cvMahalanobisは，二つのベクトル間の重み付き距離を計算し，それを返す．
d(vec1,vec2)=sqrt( sumi,j {mat(i,j)*(vec1(i)-vec2(i))*(vec1(j)-vec2(j))} )
cvCalcCovarMatrixを用いて共変動行列が計算され， さらにcvInvert関数（行列が非正則行列である可能性があるので，methodにCV_SVDが選択されたもの）を用いて逆行列を求める．
CalcPCA
ベクトル集合の主成分分析を行う
void cvCalcPCA( const CvArr* data, CvArr* avg,
CvArr* eigenvalues, CvArr* eigenvectors, int flags );
- data
- 入力データ．それぞれのベクトルは単一行（CV_PCA_DATA_AS_ROW）か，単一列（CV_PCA_DATA_AS_COL）である．
- avg
- 平均ベクトル．関数内で計算されるか，ユーザによって与えられる．
- eigenvalues
- 出力である共変動行列の固有値．
- eigenvectors
- 出力である共変動行列の固有ベクトル（つまり，主成分）．一つの行が一つのベクトルを意味する．
- flags
- 操作フラグ．以下の値の組み合わせ．
CV_PCA_DATA_AS_ROW - 行としてベクトルが保存される（つまり，あるベクトルの全ての要素は連続的に保存される）
CV_PCA_DATA_AS_COL - 列としてベクトルが保存される（つまり，あるベクトル成分に属する値は連続的に保存される）
（上の２つのフラグは互いに排他的である）
CV_PCA_USE_AVG - 事前に計算された平均ベクトルを用いる
関数cvCalcPCAは，ベクトル集合の主成分分析を行う． まず，cvCalcCovarMatrixを用いて共変動行列を計算し，固有値，固有ベクトルを求める． 固有値，固有ベクトルの出力個数は，MIN(rows(data),cols(data))と等しいか，または少ない．
ProjectPCA
指定された部分空間にベクトルを投影する
void cvProjectPCA( const CvArr* data, const CvArr* avg,
const CvArr* eigenvectors, CvArr* result );
- data
- 入力データ．それぞれのベクトルは単一行か，単一列である．
- avg
- 平均ベクトル．単一行ベクトルの場合，それはdataの行として入力ベクトルが保存されていることを意味する． そうでない場合は，単一列ベクトルであり，そのときのベクトルはdataの列として保存されている．
- eigenvectors
- 固有ベクトル（主成分）．一つの行が一つのベクトルを意味する．
- result
- 出力である分解係数の行列．行の数はベクトルの数と同じでなくてはならない． 列の数はeigenvectorsの列の数より小さいか同じでなくてはならない． 列の数が少ない場合，入力ベクトルは，第cols(result)主成分までを基底とする部分空間に投影される．
関数cvProjectPCAは，入力ベクトルを正規直交基底（eigenvectors）で表現される部分空間に投影する． 内積を計算する前に，avgベクトルが入力ベクトルから減算される．
result(i,:)=(data(i,:)-avg)*eigenvectors' // CV_PCA_DATA_AS_ROW 配置の場合
BackProjectPCA
投影係数から元のベクトルを再構築する
void cvBackProjectPCA( const CvArr* proj, const CvArr* avg,
const CvArr* eigenvects, CvArr* result );
- proj
- 入力データ．cvProjectPCAのresultと同様のフォーマット．
- avg
- 平均ベクトル．もし単一行ベクトルの場合，出力ベクトルがresultの行として保存されていることを意味する． そうでない場合は，単一列ベクトルであり，そのときはresultの列として保存される．
- eigenvectors
- 固有ベクトル（主成分）．一つの行が一つのベクトルを意味する．
- result
- 出力である再構築されたベクトルの行列．
関数cvBackProjectPCAは，投影係数からベクトルを再構築する．
result(i,:)=proj(i,:)*eigenvectors + avg // CV_PCA_DATA_AS_ROW 配置の場合