cv::SparseMat クラス

The class SparseMat represents multi-dimensional sparse numerical arrays. [詳解]

#include <mat.hpp>

cv::SparseMat_< _Tp >に継承されています。

クラス
struct	Hdr
	疎行列のヘッダ[【詳解】（英語］
struct	Node
	疎行列ノード - ハッシュテーブルの要素[【詳解】（英語］

公開型
enum	{ MAGIC_VAL =0x42FD0000 , MAX_DIM =32 , HASH_SCALE =0x5bd1e995 , HASH_BIT =0x80000000 }
typedef SparseMatIterator	iterator
typedef SparseMatConstIterator	const_iterator

公開メンバ関数
	SparseMat ()
	様々なSparseMatコンストラクタ。
	SparseMat (int dims, const int *_sizes, int _type)
	SparseMat (const SparseMat &m)
	SparseMat (const Mat &m)
	~SparseMat ()
	デストラクタ
SparseMat &	operator= (const SparseMat &m)
	代入演算子．これはO(1)の演算で，データのコピーはありません．
SparseMat &	operator= (const Mat &m)
	対応するコンストラクタと同等
SparseMat	clone () const CV_NODISCARD
	行列の完全なコピーを作成します．
void	copyTo (SparseMat &m) const
	は，すべてのデータをコピー先の行列にコピーします．m の以前の内容はすべて消去されます。
void	copyTo (Mat &m) const
	疎な行列を密な行列に変換します．
void	convertTo (SparseMat &m, int rtype, double alpha=1) const
	すべての行列要素に，指定されたスケールファクタ alpha を掛け，その結果を指定されたデータ型に変換します．
void	convertTo (Mat &m, int rtype, double alpha=1, double beta=0) const
	疎な行列を，オプションで型変換やスケーリングを行い，密な n-dim 行列に変換します．[【詳解】（英語］
void	assignTo (SparseMat &m, int type=-1) const
void	create (int dims, const int *_sizes, int _type)
	疎な行列を再配置します．[【詳解】（英語］
void	clear ()
	疎行列のすべての要素を 0 にします．これは，ハッシュテーブルのクリアを意味します．
void	addref ()
	ヘッダへの参照カウンタを手動でインクリメントします．
void	release ()
size_t	elemSize () const
	疎な行列を古い形式の表現に変換し，すべての要素がコピーされます．[【詳解】（英語］
size_t	elemSize1 () const
	戻り値elemSize()/channels()
int	type () const
	疎な行列の要素の型を返す
int	depth () const
	疎な行列の要素の深さを返します．
int	channels () const
	チャンネルの数を返します．
const int *	size () const
	サイズの配列を返します．行列が割り当てられていない場合は，NULL を返します．
int	size (int i) const
	行列の i 番目の次元のサイズ（または 0）を返します．
int	dims () const
	行列の次元数を返します．
size_t	nzcount () const
	0 ではない要素の数（＝ハッシュテーブルのノード数）を返します．
size_t	hash (int i0) const
	要素のハッシュ値を計算します（1次元の場合）．
size_t	hash (int i0, int i1) const
	要素のハッシュ値を計算します（2次元の場合）
size_t	hash (int i0, int i1, int i2) const
	要素のハッシュ値を計算 (3Dの場合)
size_t	hash (const int *idx) const
	要素のハッシュ値を計算する(nDの場合)
void	erase (int i0, int i1, size_t *hashval=0)
	指定された要素の消去 (2Dの場合)
void	erase (int i0, int i1, int i2, size_t *hashval=0)
	指定された要素を消去する (3Dケース)
void	erase (const int *idx, size_t *hashval=0)
	指定された要素を消去 (nDの場合)
SparseMatIterator	end ()
	行列の終端にある，疎な行列のイテレータを返します．[【詳解】（英語］
SparseMatConstIterator	end () const
	行列の末尾にある読み取り専用の疎行列イテレータを返します．
template<typename _Tp >
SparseMatIterator_< _Tp >	end ()
	型付けされた疎行列のイテレータを行列の最後に返します。
template<typename _Tp >
SparseMatConstIterator_< _Tp >	end () const
	型付けされた読み取り専用の疎行列イテレータを，行列の末尾に返します。
template<typename _Tp >
_Tp &	value (Node *n)
	疎な行列ノードに格納されている値を返します．
template<typename _Tp >
const _Tp &	value (const Node *n) const
	疎な行列ノードに格納されている値を返します．
Node *	node (size_t nidx)
const Node *	node (size_t nidx) const
uchar *	newNode (const int *idx, size_t hashval)
void	removeNode (size_t hidx, size_t nidx, size_t previdx)
void	resizeHashTab (size_t newsize)
uchar *	ptr (int i0, bool createMissing, size_t *hashval=0)
	指定された要素へのポインタを返します（1 次元の場合）。[【詳解】（英語］
uchar *	ptr (int i0, int i1, bool createMissing, size_t *hashval=0)
	指定された要素へのポインタを返します（2Dの場合）．
uchar *	ptr (int i0, int i1, int i2, bool createMissing, size_t *hashval=0)
	指定された要素へのポインタを返します（3Dの場合）。
uchar *	ptr (const int *idx, bool createMissing, size_t *hashval=0)
	指定された要素へのポインタを返す（nDの場合）
template<typename _Tp >
_Tp &	ref (int i0, size_t *hashval=0)
	指定された要素への参照を返す（1次元の場合）[【詳解】（英語］
template<typename _Tp >
_Tp &	ref (int i0, int i1, size_t *hashval=0)
	指定された要素への参照を返す (2Dの場合)
template<typename _Tp >
_Tp &	ref (int i0, int i1, int i2, size_t *hashval=0)
	指定された要素への参照を返す (3Dの場合)
template<typename _Tp >
_Tp &	ref (const int *idx, size_t *hashval=0)
	指定された要素への参照を返す (nDの場合)
template<typename _Tp >
_Tp	value (int i0, size_t *hashval=0) const
	指定された要素の値を返します（1次元の場合）。[【詳解】（英語］
template<typename _Tp >
_Tp	value (int i0, int i1, size_t *hashval=0) const
	指定された要素の値を返す (2Dの場合)
template<typename _Tp >
_Tp	value (int i0, int i1, int i2, size_t *hashval=0) const
	指定された要素の値を返す (3Dの場合)
template<typename _Tp >
_Tp	value (const int *idx, size_t *hashval=0) const
	指定された要素の値を返す (nDの場合)
template<typename _Tp >
const _Tp *	find (int i0, size_t *hashval=0) const
	指定された要素へのポインタを返します（1 次元の場合）。[【詳解】（英語］
template<typename _Tp >
const _Tp *	find (int i0, int i1, size_t *hashval=0) const
	指定された要素へのポインタを返します（2Dの場合）．
template<typename _Tp >
const _Tp *	find (int i0, int i1, int i2, size_t *hashval=0) const
	指定された要素へのポインタを返します（3Dの場合）。
template<typename _Tp >
const _Tp *	find (const int *idx, size_t *hashval=0) const
	指定された要素へのポインタを返す（nDの場合）
SparseMatIterator	begin ()
	行列の先頭にある，疎な行列のイテレータを返します．[【詳解】（英語］
template<typename _Tp >
SparseMatIterator_< _Tp >	begin ()
	行列の先頭にある，疎な行列のイテレータを返します．
SparseMatConstIterator	begin () const
	行列の先頭にある，読み込み専用の疎行列イテレータを返します。
template<typename _Tp >
SparseMatConstIterator_< _Tp >	begin () const
	行列の先頭にある，読み込み専用の疎行列イテレータを返します。

公開変数類
int	flags
Hdr *	hdr

詳解

このクラスはSparseMatは，多次元の疎な数値配列を表します．

このような疎な配列は，次のような任意の型の要素を格納できます。Matが格納できるあらゆる型の要素を格納できます。疎なとは，0 ではない要素のみが格納されていることを意味します（ただし，疎な行列に対する演算の結果，格納されている要素の一部が実際に 0 になることがあります。SparseMat::erase). 0ではない要素は，ハッシュテーブルに格納されています．このハッシュテーブルは，要素が存在するかどうかにかかわらず，平均してO(1)の検索時間となるように，埋められるたびに大きくなります．要素へのアクセスには，以下の方法があります．

• クエリ操作 (SparseMat::ptrとその上位のSparseMat::ref,SparseMat::valueおよびSparseMat::find)などがあります．

  
  const
  int
  dims
  = 5;
  
  int
  size[5] = {10, 10, 10, 10, 10};
  
  SparseMat
  sparse_mat(dims,
  size, CV_32F);
  
  for(int
  i = 0; i < 1000; i++)
  {
  
  int
  idx[dims];
  
  for(int
  k = 0; k <
  dims; k++)
  
  idx[k] = rand() %
  size[k];
  
  sparse_mat.ref<float>(idx) += 1.f;
  }
  cout <<
  "nnz = "
  << sparse_mat.nzcount() << endl;

• 疎行列イテレータ．これらは MatIterator と似ていますが，以下とは異なりますNAryMatIterator. つまり，STL ユーザにはおなじみの反復ループです．

  
  // prints elements of a sparse floating-point matrix
  
  
  // and the sum of elements.
  
  SparseMatConstIterator_<float>
  
  it = sparse_mat.begin<float>(),
  
  it_end = sparse_mat.end<float>();
  
  double
  s = 0;
  
  int
  dims
  = sparse_mat.dims();
  
  for(; it != it_end; ++it)
  {
  
  // print element indices and the element value
  
  
  const
  SparseMat::Node* n = it.node();
  
  printf("(");
  
  for(int
  i = 0; i <
  dims; i++)
  
  printf("%d%s", n->idx[i], i <
  dims-1 ?
  ", "
  :
  ")");
  
  printf(": %g\n", it.value<float>());
  
  s += *it;
  }
  printf("Element sum is %g\n", s);

  このループを実行すると，要素が論理的な順序（辞書的，など）で列挙されていないことに気づくでしょう．このループを実行すると，要素は論理的な順序（辞書的，など）ではなく，ハッシュテーブルに格納されているのと同じ順序（半ランダム）で並んでいることに気づきます．ノードへのポインタを集めてソートすれば、適切な順序になります。ただし，行列に要素を追加すると，ノードへのポインタが無効になることがあるので注意が必要です．これは，バッファが再割り当てされる可能性があるために起こります．
• 2つ以上の疎な行列を同時に処理する必要がある場合は，上記2つの方法を組み合わせます．例えば，2つの浮動小数点型疎行列の正規化されていない相互相関を計算する場合は，この方法を利用します．

  
  double
  cross_corr(const
  SparseMat& a,
  const
  SparseMat& b)
  {
  
  const
  SparseMat
  *_a = &a, *_b = &b;
  
  // if b contains less elements than a,
  
  
  // it is faster to iterate through b
  
  
  if(_a->nzcount() > _b->nzcount())
  
  std::swap(_a, _b);
  
  SparseMatConstIterator_<float> it = _a->begin<float>(),
  
  it_end = _a->end<float>();
  
  double
  ccorr = 0;
  
  for(; it != it_end; ++it)
  
  {
  
  // take the next element from the first matrix
  
  
  float
  avalue = *it;
  
  const
  Node* anode = it.node();
  
  // and try to find an element with the same index in the second matrix.
  
  
  // since the hash value depends only on the element index,
  
  
  // reuse the hash value stored in the node
  
  
  float
  bvalue = _b->value<float>(anode->idx,&anode->hashval);
  
  ccorr += avalue*bvalue;
  
  }
  
  return
  ccorr;
  }

構築子と解体子

SparseMat() [1/3]

cv::SparseMat::SparseMat	(	int	dims,
		const int *	_sizes,
		int	_type
	)

これはオーバーロードされたメンバ関数です。利便性のために用意されています。元の関数との違いは引き数のみです。

引数

dims	配列の次元。
_sizes	すべてのデメンションでのスパースな行列サイズ。
_type	疎な行列のデータ型。

SparseMat() [2/3]

cv::SparseMat::SparseMat

(

const SparseMat &

m

)

これはオーバーロードされたメンバ関数です。利便性のために用意されています。元の関数との違いは引き数のみです。

引数

m	コピーコンストラクタの入力行列．m が密な行列（ocvMat）である場合，それは疎な表現に変換されます．

SparseMat() [3/3]

cv::SparseMat::SparseMat ( const Mat & m )

explicit

これはオーバーロードされたメンバ関数です。利便性のために用意されています。元の関数との違いは引き数のみです。

引数

m	コピーコンストラクタの入力行列．m が密な行列（ocvMat）である場合，それは疎な表現に変換されます．

関数詳解

begin()

SparseMatIterator cv::SparseMat::begin

(

)

行列の先頭にある，疎な行列のイテレータを返します．

疎な行列の最初の要素を指す疎な行列のイテレータを返します．

convertTo()

void cv::SparseMat::convertTo	(	Mat &	m,
		int	rtype,
		double	alpha = 1,
		double	beta = 0
	)		const

疎な行列を，オプションで型変換やスケーリングを行い，密な n-dim 行列に変換します．

引数

[out].	m	- 出力行列．操作の前に適切なサイズや型でなかった場合は，再割り当てされます．
[in].	rtype	- 希望する出力行列の型，というよりは，チャンネル数が入力と同じであることから得られる深さ．
[in].	alpha	- オプションのスケールファクタ
[in].	beta	- オプションで，スケーリングされた値に追加されるデルタ値．

create()

void cv::SparseMat::create	(	int	dims,
		const int *	_sizes,
		int	_type
	)

疎な行列を再配置します．

行列が既に適切なサイズと型を持っている場合は，単にclear()で単純にクリアされ，そうでない場合は，（release() を用いて）古い行列が解放され，新しい行列が確保されます．

elemSize()

size_t cv::SparseMat::elemSize

(

)

const

疎な行列を古い形式の表現に変換し，すべての要素がコピーされます．

は，各要素のサイズをバイト単位で返します（オーバーヘッド（要素が占める空間）は含みません）．SparseMat::Node要素が占める空間）は含まれません。

end()

SparseMatIterator cv::SparseMat::end

(

)

行列の終端にある，疎な行列のイテレータを返します．

疎な行列の最後の要素の次の要素を指す，疎な行列のイテレータを返します．

find()

template<typename _Tp >

const _Tp * cv::SparseMat::find	(	int	i0,
		size_t *	hashval = 0
	)		const

指定された要素へのポインタを返します（1 次元の場合）。

指定された疎行列の要素が存在する場合は，そのポインタを返します．

find<_Tp>(i0,...[,hashval])は次のものと同じです．(_const Tp*)ptr(i0,...false[,hashval]).

指定された要素が存在しない場合，このメソッドは NULL を返します。

ptr()

uchar * cv::SparseMat::ptr	(	int	i0,
		bool	createMissing,
		size_t *	hashval = 0
	)

指定された要素へのポインタを返します（1 次元の場合）。

1D, 2D, 3D に特化したバージョンと， n-D に特化した generic_type があります． 行列要素へのポインタを返します．

• 要素が存在する（0 ではない）場合は，そのポインタが返されます．
• 要素が存在せず，かつ createMissing=false の場合は，NULLポインタが返されます．
• 要素が存在せず createMissing=true であれば，新しい要素が作成され，0 で初期化されます．そのポインタが返されます．
• オプションの hashval ポインタが NULL でない場合，要素のハッシュ値は計算されず，代わりに *hashval が取得されます．

ref()

template<typename _Tp >

_Tp & cv::SparseMat::ref	(	int	i0,
		size_t *	hashval = 0
	)

指定された要素への参照を返す（1次元の場合）

指定された疎な行列要素への読み書き可能な参照を返します．

ref<_Tp>(i0,...[,hashval])は次のものと同じです．*(_Tp*)ptr(i0,...,true[,hashval]). このメソッドは，常に有効な参照を返します．要素が存在しない場合，その要素は作成され，0 で初期化されます．

value()

template<typename _Tp >

_Tp cv::SparseMat::value	(	int	i0,
		size_t *	hashval = 0
	)		const

指定された要素の値を返します（1次元の場合）。

指定された疎な行列の要素の値を返します。

value<_Tp>(i0,...[,hashval])は次のものと同じです．

{
const
_Tp* p = find<_Tp>(i0,...[,hashval]);
return
p ? *p : _Tp(); }

つまり，要素が存在しない場合，メソッドは 0 を返します。

---

このクラス詳解は次のファイルから抽出されました:

• mat.hpp