NAME

Cv - helps you to make something around computer vision.

SYNOPSIS

 use Cv;
 my $image = Cv->LoadImage("/path/to/image", CV_LOAD_IMAGE_COLOR);
 $image->ShowImage("image");
 Cv->WaitKey;

DESCRIPTION

Cv is the Perl interface to the OpenCV computer vision library that originally developed by Intel. I'm making this module to use the computer vision more easily like a slogan of perl "Easy things should be easy, hard things should be possible."

The features are as follows.

• Cv was made along the online reference manual of C in the OpenCV documentation. For details, please refer to the http://opencv.willowgarage.com/.

• You can use CreateSomething() as a constructors.

   my $img = Cv->CreateImage([ 320, 240 ], IPL_DEPTH_8U, 3);
   my $mat = Cv->CreateMat([ 240, 320 ], CV_8UC3);

• You can also use new as a constructor, e.g. instead of Cv::Image->new is CreateImage(), Cv::Mat->new is CreateMat(). In the calling parameters, there are some difference in CreateImage() and CreateMat(). But there are no difference in Cv::something->new. This is because we create same object without knowing about original object in the Cv::Arr.

   my $img = Cv::Image->new([ 240, 320 ], CV_8UC3);

  You can omit parameters and that will be inherited.

   my $img2 = $img->new;
   my $img3 = $img->new(CV_8UC1);  # Cv::Image->new([240, 320], CV_8UC1)

• The OpenCV has a type IplImage* for handling an image object, and types CvMat*, CvMatND* and CvSparseMat* for a matrix object. These types are mapped as blessed reference of Cv::Image, Cv::Mat, Cv::MatND and Cv::SparseMat. The type of structures like CvSize and CvPoint are mapped as an array. For details, please refer to the typemap.

• You have to call cvReleaseImage() when you'll destroy the image object in the OpenCV application programs. But in the Cv, you don't have to call cvReleaseImage() because Perl calls DESTROY for cleanup. So the subroutine DESTROY has often been defined as an alias of cvReleaseImage(), cvReleaseMat(), ... and cvReleaseSomething().

  Some functions, eg. cvQueryFrame() return a reference but that cannot be destroyed. In this case, the reference is blessed with Cv::Somthing::Ghost, and identified. And disable destroying.

• You can use name of method, omitting "cv" from the OpenCV function name, and also use lowercase name beginning. For example, you can call cvCreateMat() as:

   my $mat = Cv->CreateMat(240, 320, CV_8UC3);
   my $mat = Cv->createMat(240, 320, CV_8UC3);

• When you omit the destination image or matrix (often named "dst"), Cv creates new destination if possible.

   my $dst = $src->Add($src2);

• Some functions in the OpenCV can handle inplace that use source image as destination one. To tell requesting inplace, you can use \0 as NULL for the destination.

   my $dst = $src->Flip(\0);

• cvAddS() and cvAdd() are integrated into Add(). Because we can identify them.

   my $dst = $src->Add($src2);        # calling cvAdd()
   my $dst = $src->Add([ 1, 2, 3 ]);  # cvAddS()

• cvFillConvexPoly() handles the array of points CvPoint. The function also needs the number of elements separately. Because the array of the language C is only a pointer to the beginning of it. In the Perl, the array unlike in C, we can know the number of elements. So, you don't need to pass the number of elements for cvFindCornerSubPix(), cvCreateMatND() and so, too.

• cvMinMaxLoc() stores values in given variables.

   $src->MinMaxLoc(my $min, my $max);

  In the Perl, you would think that even when multiple values returned to the caller might be more natural to use the return value like localtime and stat. But we chose to along the OpenCV documentation.

• We have a configuration to use Inline C. This makes it easy to test and extend a variety. How easy is as follows.

   use Cv::Config;
   use Inline C => Config => %Cv::Config::C;

TIPS

We'll show you the tips about using Cv that we studied from users.

• You can use EncodeImage() and Ptr() when you want to output images in your CGI without saving to the files.

   use Cv;
   my $img = Cv::Image->new([240, 320], CV_8UC3);
   $img->zero->circle([ 100, 100 ], 100, CV_RGB(255, 100, 100));
   print "Content-type: image/jpg\n\n";
   print $img->encodeImage(".jpg")->ptr;

  You can use that to convert for Imager.

   use Imager;
   my $imager = Imager->new(data => $img->encodeImage(".ppm")->ptr);

• You can attach the Cv header to the data defined in the Perl world. It is not a good manner, but you can get the way to access to that.

   my $data = pack("C*", 0 .. 255);
   my $mat = Cv::Mat->mew([16, 16], CV_8UC1, $data);
   substr($data, 0x41, 1) = 'x';
   print chr($mat->get([4, 1])->[0]), "\n";

SAMPLES

We rewrote some OpenCV samples in Cv, and put them in sample/.

•  bgfg_codebook.pl calibration.pl camshiftdemo.pl capture.pl
   contours.pl convexhull.pl delaunay.pl demhist.pl dft.pl distrans.pl
   drawing.pl edge.pl facedetect.pl fback_c.pl ffilldemo.pl find_obj.pl
   fitellipse.pl houghlines.pl image.pl inpaint.pl kalman.pl kmeans.pl
   laplace.pl lkdemo.pl minarea.pl morphology.pl motempl.pl
   mser_sample.pl polar_transforms.pl pyramid_segmentation.pl squares.pl
   stereo_calib.pl stereo_match.pl tiehash.pl video.pl watershed.pl

BUGS

• If you want to use new features of the OpenCV longer continue to progress, please add them to the xs. If you can place xs code in the package Cv or Cv::Arr, you don't need to consider about adjusting the names, e.g. omitting "cv", lowercase name beginning, because AUTOLOAD works in these packages. In other places, you can use Cv::aliases.

• If you want to use new constants, you can put it package Cv::Constant.

• In the version 0.07, we decided to remove keyword parameter. Because of that has large overhead. In this version, we decided to remove Cv::TieHash and Cv::TieArr, too. See sample/tiehash.pl.

• On cygwin, it is necessary to compile OpenCV.

SEE ALSO

http://sourceforge.net/projects/opencvlibrary/

AUTHOR

Yuta Masuda, <yuta.masuda@newdaysys.co.jp>

LICENCE

Copyright (c) 2010, 2011 by Masuda Yuta.

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