# -*- mode: pod; coding: utf-8; tab-width: 4; -*-
=encoding utf8

=head1 名前

Cv::More - L<Cv|Cv::Nihongo> をもう少し Perl で使いやすくしたいね。

=head1 概要

 use Cv::More qw(cs);

=head1 説明

C<Cv::More> は、L<Cv|Cv::Nihongo> から実験的な機能を切り離して整理する
ためのパッケージです。C<Cv> が拡張しやすくなると考えています。
C<Cv::More> は、C<Cv> の一部を切り離したものなので、使わないことを明示
しない限り取り込みます。

 use Cv;              # Cv::More を使う
 use Cv qw(:nomore);  # Cv::More を使わない

=head2 追加または拡張したメソッド

=head3 Perlの配列を使うメソッド

=over

=item FitEllipse2()

 my $box2d = Cv->FitEllipse2($points);

戻り値は CvBox2D です。cs のときには、リストコンテクストで呼ばれると、
次のとおり要素が展開されます。

 use Cv::More qw(cs);
 my ($center, $size, $angle) = Cv->FitEllipse2($points);

Perl のリストで表わした点と、それを FitEllipse2() で処理した結果を描き
表示するサンプルを示します。

 my $img = Cv::Image->new([250, 250], CV_8UC3)->fill(cvScalarAll(255));
 $img->origin(1);
 my @pts = (map { [ map { $_ / 4 + rand $_ / 2 } @{$img->size} ] } 1 .. 20);
 $img->circle($_, 3, &color, 1, CV_AA) for @pts;
 my $box = Cv->fitEllipse(\@pts);
 $img->polyLine([[Cv->boxPoints($box)]], -1, &color, 1, CV_AA);
 $img->ellipseBox($box, &color, 1, CV_AA);
 $img->show("FitEllipse2");
 Cv->waitKey;
 sub color { [ map { rand 255 } 1 .. 3 ] }


=item FitLine()

FitLine() には、次の 2つの呼出し形式があります。Perl では (1) の使い方
になると思いますが、OpenCV の C言語のインターフェースに合わせた (2) の
使い方もできます。

 my $line = Cv->FitLine($points, $dist_type, $param, $reps, $aeps);     # (1)
 Cv->FitLine($points, $dist_type, $param, $reps, $aeps, my $line);      # (2)

パラメータはたくさんありますが、$points 以外は省略できます。入力
$points は、2次元の点または 3次元の点のリストで、結果は、この $points
の次元数で決まります。

 my $points2d = [ [$x1, $y1], [$x2, $y2], ... ];
 my ($vx, $vy, $x0, $y0) = Cv->FitLine($points2d, ...);
 my $points3d = [ [$x1, $y1, $z1], [$x2, $y2, $z2], ... ];
 my ($vx, $vy, $vz, $x0, $y0, $z0) = Cv->FitLine($points3d, ...);

いくつかの点の集りにフィッティングさせた直線を描いてみましょう。

 my @pts = ([ 50, 50 ], [ 100, 120 ], [ 150, 150 ], [ 200, 150 ]);
 my ($vx, $vy, $x0, $y0) = Cv->fitLine(\@pts); 
 $img->line((map { [ $_, $vy / $vx * ($_ - $x0) + $y0 ] } 20, 230),
			cvScalarAll(200), 3, CV_AA);

サンプルのはじめと終りは C<FitEllipse2()> を参照してください。


=item MinAreaRect2()

 my $box2d = Cv->MinAreaRect2($points);
 my ($center, $size, $angle) = Cv->MinAreaRect2($points);

戻り値は CvBox2D です。FitEllipse2() と同じような結果を返しますが。重ね
合わせてみると違いが分ります。

 for ([ [ Cv->fitEllipse(\@pts)  ], [ 200, 200, 200 ] ],
      [ [ Cv->minAreaRect(\@pts) ], [ 100, 100, 255 ] ]) {
   $img->polyLine([[Cv->boxPoints($_->[0])]], -1, $_->[1], 1, CV_AA);
   $img->ellipseBox($_->[0], $_->[1], 1, CV_AA);
 }

サンプルのはじめと終りは C<FitEllipse2()> を参照してください。

C言語のインタフェースは次のとおり。メモリストレージを渡すこともできます。

 CvBox2D cvMinAreaRect2(const CvArr* points, CvMemStorage* storage=NULL)

Cv-0.15 までは、Perl の点のリストを Cv::Seq::Point にして使っていました。
そのときはメモリストレージを使っていました。しかし、Cv-0.16 で Perl の
点のリストを Cv::Mat に直したので、メモリストレージは使いません。


=item MinEnclosingCircle()

 my $circle = Cv->MinEnclosingCircle($points);                          # (1)
 my ($center, $radius) = Cv->MinEnclosingCircle($points);               # (1')
 Cv->MinEnclosingCircle($points, my $center, my $radius);               # (2)

戻り値は、円の中心の座標 $center と半径 $radius です。CvBox2D の形に合
わせて重ね合わせてみましょう。

 my $rectangle = Cv->minAreaRect2(\@pts);
 my $ellipse = Cv->fitEllipse2(\@pts);
 my ($center, $radius) = Cv->minEnclosingCircle(\@pts);
 my $circle = [ $center, [ ($radius * 2) x 2 ], 0 ];
 for ([ $rectangle, [ 200, 200, 200 ] ],
      # [ $ellipse,   [ 200, 200, 200 ] ],
      [ $circle,    [ 100, 100, 255 ] ]) {
   $img->polyLine([[Cv->boxPoints($_->[0])]], -1, $_->[1], 1, CV_AA);
   $img->ellipseBox($_->[0], $_->[1], 1, CV_AA);
 }

サンプルで使った乱数による点のリストを処理してもあまり面白くないかもし
れませね。点が表わすものを C<FitEllipse2()>, C<FitLine()>,
C<MinAreaRect2()>, C<MinEnclosingCircle()> の中から元の形に合うものを選
ぶといいでしょう。サンプルはどれも似ているので、そのはじめと終りは
C<FitEllipse2()> から持って来てください。

(注意) MinEnclosingCircle() の戻り値は、Cv-0.15 まで (1') の形式でした。
つまり、いつも ($center, $radius) を返していました。しかし、Cv-0.16 で
メソッドの戻り値を揃え [$center, $radius] を返すことにしました。

=item BoundingRect()

 my $rect = Cv->BoundingRect($points)
 my ($x, $y, $width, $height) = Cv->BoundingRect($points)

点を囲む傾いていない矩形を求めます。傾いている矩形には
C<MinAreaRect2()> を使います。戻り値は CvRect なので、CvBox2D に直すと
C<EllipseBox()> や C<BoxPoints()> とのつながりが良くなります。
CvRect から CvBox2D への変換は次のとおり。

 my $box2d = [ [ $x + $width / 2, $y + $height / 2 ], [ $width, $height ], 0 ];


=item ContourArea()

 my $s = Cv->ContourArea($points)
 my $s = Cv->ContourArea($points, $slice)

点で囲まれる領域の面積を求めます。

 my @pts = ([100, 100], [100, 200], [200, 200], [200, 100]);
 my $s = Cv->contourArea(\@pts);

この面積 $s は、縦x横 (100x100) になります。


=item Transform()

 my $dst = Cv->Transform([ $pt1, $pt2, ... ], $transmat);               # (1)
 my @dst = Cv->Transform([ $pt1, $pt2, ... ], $transmat);               # (1')
 Cv->Transform([ $pt1, $pt2, ... ], my $dst, $transmat);                # (2)

 my @points = ( [$x1, $y1], [$x2, $y2], ... );
 my $arr = Cv::Mat->new([], CV_32FC2, @points);
 my $dst = $arr->Transform($transmat);                                  # (3)
 $arr->Transform(my $dst, $transmat);                                   # (4)

 my $dst = $arr->WarpAffine($transmat);                                 # (5)
 $arr->warpTransform(my $dst, $transmat);                               # (6)


=item Affine()

GetQuadrangleSubPix() を使って、画像やマトリクスの回転と縮小を行います。

  my $mapMatrix = [ [ $A11, $A12, $b1 ],
                    [ $A21, $A22, $b2 ] ];
  my $dst = $src->Affine($mapMatrix);

この Affine() は、GetQuadrangleSubPix() の変換行列を作るのが面倒だった
ので、その対処として作ったものです。拡張した new() を使えば次の書き方で
も同じことができます。

  $src->GetQuadrangleSubPix(
          Cv::Mat->new([], &Cv::CV_32FC1,
                       [ $A11, $A12, $b1 ],
                       [ $A21, $A22, $b2 ],
                       ));

こうしてみると、考えずに Affine() のようなものを作るのは良くないことで、
GetQuadrangleSubPix() が $mapMatrix に C<Cv::Mat> と Perl の配列のどち
らでも扱えるようにするのが良かったと分りました。これもそのうちに考えて
みることにします。

=item new()

=item m_new()

OpenCV の画像やマトリクスのオブジェクトは、大きさと要素の型を指定して作
ります。C<Cv::Createなんとか()> か C<Cv::なんとか::new()> で作ります。
C<m_new()> は、C<Cv::なんとか::new()> を再定義し、初期値を扱えるように
拡張します。

 my $mat1 = Cv::Mat->new([], 要素の型, 初期値のリスト);
 my $mat2 = Cv::Mat->new(マトリクスの大きさ, 要素の型);
 my $mat3 = $mat->new();
 my $mat4 = $mat->new(マトリクスの大きさ);
 my $mat5 = $mat->new(要素の型);

C<m_new()> が拡張するのは、上の C<$mat1> を作る例です。マトリクスの大き
さを指定するところに C<[]> を指定します。具体的な使い方については、
L</Perlの配列でマトリクスを作る> を参照してください。他の例は、いまの
C<Cv> の C<new()> でもできます。


=item Set()

=item m_set()

 $mat->Set($index, $value);

$index は配列のリファレンスで、より具体的に次のとおり書くことができます。

 $mat->Set([], $value);       # マトリクス $mat 全体に $value を代入する
 $mat->Set([$i], $value);     # マトリクス $mat の $i 行に〜
 $mat->Set([$i, $j], $value); # マトリクス $mat の $i 行 $j 列に〜

このように C<m_set()> は C<Set()> を拡張し、C<Set()> が 要素を 1つずつ
代入していたところで、要素をひとまとめに代入することを可能にします。

それは、C<$index> で指定されたマトリクスの要素の数と C<$value> で指定さ
れた要素の値の数のバランスがとれるように、C<$index> を補うか C<$value>
をばらし、そして、マトリクスの要素に値を 1つずつ代入するというものです。
インデクス C<$index> が C<$mat> の要素を特定するために十分でないときは、
足りないインデクスを補うために、C<$value> が値のリストなら C<$value> を
ばらして 1つずつ C<m_set()> で再帰的に処理します。つまり、

 $mat->m_set([@$index, $_], $value->[$_]) for 0 .. $#{$value};

そうでない (C<$value> をばらせない) ときは、次のとおり単にインデクスに
0 を補います。正確には、Nx1 のマトリクスの x1 のインデクスに相当する部
分を 0 で補うのがいいと思いますが、次に示す手抜きでも十分でしょう。

 $mat->m_set([@$index, 0], $value);


=item ToArray()

 my @array = $arr->ToArray();                                           # (1)
 my @array = $arr->ToArray($slice);                                     # (2)

シーケンスまたはマトリクス (1xN, Nx1) を Perl の点の配列に変換します。
シーケンスを変換する cvCvtSeqToArray() をマトリクスも変換できるように拡
張したものです。従って、範囲を与える $slice を指定することができます。
これは、cvSlice() で作るか、単にはじめ $start と終り $end を対にした配
列のリファレンス [$start, $end] で表わすことができます。省略したときは
$arr のすべての要素を変換します。

cvCvtSeqToArray() を元にしたので同じ呼出し形式も使えます。つまり、次の
使い方もできます。でも使わないかもしれませんね。

 $arr->ToArray(\my @array);
 $arr->ToArray(\my @attay, $slice);

(注意) Perl の配列のようにインデクスに負数が使えると便利なことがありま
すが、これはできません。そのうち考えてみようと思っています。

 my @array = $arr->ToArray([ -1, 1 ]);
 my @array = $arr->ToArray([ 1, -1 ]);

=back


=head3 その他のメソッド

=over

=item GetBuildInformation()

  my $info = Cv->GetBuildInformation()
  my %info = Cv->GetBuildInformation()

OpenCV 2.4.0 からビルド時の情報が取り出せるます。コンテクトがスカラなら
cv::getBuildInformation() の戻り値を返し、リストなら次のような結果を返
します。

  'OpenCV modules' => {
	'Disabled by dependency' => '-',
	'Unavailable' => 'androidcamera java ocl',
	'Disabled' => 'world',
	'To be built' => 'core imgproc flann highgui features2d calib3d ml video objdetect contrib nonfree photo legacy gpu python stitching ts videostab'
  },
  'Version control' => 'commit:6484732',
  'Linker flags (Debug)' => {
	'Precompiled headers' => 'YES'
  },
  ...

これは、C<HasModule()> でOpenCV で利用可能なモジュールを確認するために
使用しています。

=item HasModule()

 my $hasCore = Cv->HasModule('core');

OpenCV がどのようなモジュールを有効にしてビルドされたかを返します。

=back

=head1 バグ

=over

=item *

=back

=head1 参考

L<Cv::Nihongo|Cv::Nihongo>

=head1 著作権

Yuta MASUDA E<lt>yuta.masuda@newdaysys.co.jpE<gt>

Copyright (c) 2012 by Yuta MASUDA.

All rights reserved. This program is free software; you can
redistribute it and/or modify it under the same terms as Perl itself.

=cut
