The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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;
 
 my $capture = Cv->CaptureFromCAM(0);
 while (my $frame = $capture->QueryFrame) {
   $frame->Flip(\0, 1)->ShowImage;
   my $c = Cv->WaitKey(100);
   last if $c >= 0;
 }

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. Cv::Image->new is Cv->CreateImage(), Cv::Mat->new is Cv->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);
     my $mat = Cv::Mat->new([ 240, 320 ], CV_8UC4);

    You can omit parameters and that will be inherited.

     my $sameone = $img->new;
     my $gray = $color->new(CV_8UC1);
  • 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);
     my $dst = $src->Add($src2, $mask);  # can't omit dst

    in this case, you can create $dst as follows:

     my $dst = $src->Add($src2, $src->new, $mask); 
  • 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);
  • The members of structure are same as function.

     my ($c, $d) = ($img->channels, $img->depth);
     my ($h, $w) = ($img->height, $img->width);
     my ($r, $c) = ($img->rows, $img->cols);
     my @sz = $img->sizes;

    But we can't use as lvalue.

     my $roi = $img->roi;              # GetImageROI($img)
     $img->roi($roi);                  # SetImageROI($img, $roi)
     my $coi = $img->coi;              # GetImageCOI($img)
     $img->coi($coi);                  # SetImageCOI($img, $coi)
  • There are functions Get() and Set(). They access an elements. You can call Get() as cvGetND(), and Set() as cvSetND(). So, you have to to call Fill() instead of calling the cvSetND().

     my $x = $mat->Get($i, $j);        # cvGetND($mat, [$i, $j])
     my $x = $mat->Get(\@idx);         # cvGetND($mat, \@idx);

    When the number of indexes is less than the number of the dimensions, 0 is complemented as indexes.

     $mat->Set([$i, $j, ...], $x);     # cvSetND($mat, [$i, $j, ...], $x)
     $mat->Set(\@idx, $x);             # cvSetND($mat, \@idx, $x)
     $mat->Fill($x);                   # cvSet($mat, $x)
  • Ptr() returns a string that from specified element up to the end of the line. Parameters are same as Get().

     my $str = $mat->Ptr($row, $col);  # cvPtrND($mat, [$row, $col]);
     my $str = $mat->Ptr($row);        # cvPtrND($mat, [$row]);
  • There are functions to split per channel and merge them.

     $rgb->Split($r, $g, $b);          # cvSplit($rgb, $r, $g, $b)
     my ($r, $g, $b) = $rgb->Split;    # cvSplit($rgb, $r, $g, $b)
     my $rgb = Cv->Merge($r, $g, $b);  # cvMerge([$r, $g, $b], $rgb);
  • cvAddS() and cvAdd() are integrated into Add(). The function which can be identified by the argument.

     my $ar2 = Cv->CreateImage();      # ref Cv::Image
     my $sc2 = cvScalar();             # ref ARRAY
     my $d = $ar->Add($ar2);           # cvAdd($ar, $ar2)
     my $d = $ar->Add($sc2);           # cvAddS($ar, $sc2)

    The integrated function as follows.

     AbsDiff(), Add(), And(), Cmp(), InRange(), Max(), Min(), Or(), Sub(),
     Xor()

Error Handling

Cv is now possible to detect errors that occur in the block protected as eval { ... }. (Cv-0.13)

 my $img = eval { Cv->createImage([-1, -1], 8, 3) };
 if ($@) {
    print STDERR "*** got error ***";
 }

EXPORT

You put names after use Cv, constants, functions ... to be imported. (Cv-0.14)

  • For example, the following two lines to import functions such as cvScalar() and the constants starting with IPL and CV.

     use Cv qw(:std);
     use Cv;                        # considering :std
  • For example, the following two lines to import all variables and functions of Cv.

     use Cv qw(:all);
     use Cv qw(/^(CV|IPL|cv)/);
  • If you do not want to import anything, put an empty list.

     use Cv ( );

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);
  • 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;

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

  • Threshold() updates the parameter threshold if threshold-type is CV_THRESH_OTSU. It looks like perl magic. So, you can use Threshold() is as follows:

     my $bin = $gray->threshold(my $thresh, 255, CV_THRESH_OTSU);
  • Constants used in the Perl world is converted into lib/Cv/Constant.pm from the header file using h2ph. If it failed, the version of the installed OpenCV is checked, and copied from the fallback/.

  • 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.

  • The following names that are the kind of alias are obsolete. Use the original names CV_SOMETHING because they are shorter. (Cv-0.13)

     Cv::MAKETYPE, Cv::MAT_DEPTH, Cv::MAT_CN, Cv::MAT_TYPE, Cv::ELEM_SIZE,
     Cv::NODE_TYPE, Cv::IS_SET_ELEM, Cv::SIZEOF
  • Usage of the CV_SIZEOF has changed. Write the name of structure of OpenCV that you want to know the size as follows. (Cv-0.13)

     CV_SIZEOF('CvContour')
  • When you don't like use Cv::More, you can put qw(:nomore) as use Cv option, and you could also put -more between 0.20 and 0.23. However, it was confusing to us, we have to change -nomore. (0.24)

SEE ALSO

http://github.com/obuk/Cv-Olive

AUTHOR

MASUDA Yuta <yuta.cpan@gmail.com>

LICENCE

Copyright (c) 2010, 2011, 2012, 2013 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.