ruby-opencv/README.rdoc

= OpenCV

The initial Open Computer Vision library was originally developed by Intel 
Corporation. Recent development has been headed by Willow Garage, Inc.

* OpenCV project home http://opencv.willowgarage.com/wiki/
  * Download http://sourceforge.net/projects/opencvlibrary/
* Ruby/OpenCV original author's web page http://blueruby.mydns.jp/opencv

== DESCRIPTION:

OpenCV wrapper for Ruby

== FEATURES/PROBLEMS:

* Some OpenCV functions are wrapped.
* Ruby 1.8.7, 1.9.3 and OpenCV 2.4.2 are supported.

== DEPENDENCIES:

* OpenCV (required)
  * Ruby/OpenCV relies on the OpenCV library http://opencv.willowgarage.com/wiki/InstallGuide

* Microsoft Visual C++ (for mswin32)
  * http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-cpp-express

* MinGW and MSYS (for mingw32)
  * gcc, g++ and MSYS are needed.
  * http://www.mingw.org


== INSTALLATION:
=== Install Ruby/OpenCV manually
==== Unix/Linux/Mac

  $ git clone git://github.com/ruby-opencv/ruby-opencv.git
  $ cd ruby-opencv
  $ git checkout master # for OpenCV 2.4 or later. To use OpenCV 2.3, type "git checkout OpenCV_2.3" instead
  $ ruby extconf.rb --with-opencv-dir=/path/to/opencvdir
  $ make
  $ make install

==== Windows (mswin32)

Use *nmake* instead of *make*.

  $ git clone git://github.com/ruby-opencv/ruby-opencv.git
  $ cd ruby-opencv
  $ git checkout master # for OpenCV 2.4 or later. To use OpenCV 2.3, type "git checkout OpenCV_2.3" instead
  $ ruby extconf.rb --with-opencv-dir=C:\path\to\opencvdir\install  # for your own built OpenCV library
  $ nmake
  $ nmake install

To use pre-built OpenCV libraries, set the following option to extconf.rb.

  $ ruby extconf.rb --with-opencv-include=C:\path\to\opencvdir\build\include --with-opencv-lib=C:\path\to\opencvdir\build\x86\vc10\lib


==== Windows (mingw32)

Type the following commands on the *MSYS* *console*.

  $ git clone git://github.com/ruby-opencv/ruby-opencv.git
  $ cd ruby-opencv
  $ git checkout master # for OpenCV 2.4 or later. To use OpenCV 2.3, type "git checkout OpenCV_2.3" instead
  $ ruby extconf.rb --with-opencv-dir=/C/path/to/opencvdir/install  # for your own built OpenCV library
  $ make
  $ make install

To use pre-built OpenCV libraries, set the following option to extconf.rb.

  $ ruby extconf.rb --with-opencv-include=/c/path/to/opencvdir/build/include --with-opencv-lib=/c/path/to/opencvdir/build/x86/mingw/lib


==== NOTE:

*/path/to/opencvdir* is the path you installs OpenCV library (default: /usr/local).

For example, if you install OpenCV library to */opt/local/* like:

  $ cmake -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX=/opt/local/ ./OpenCV-2.4.2
  $ make
  $ make install

Install Ruby/OpenCV with the following command:

  $ ruby extconf.rb --with-opencv-dir=/opt/local
  $ make
  $ make install


=== Create Ruby/OpenCV Gem
You can also install this library creating a gem like:

  $ git clone git://github.com/ruby-opencv/ruby-opencv.git
  $ cd ruby-opencv
  $ git checkout master # for OpenCV 2.4 or later. To use OpenCV 2.3, type "git checkout OpenCV_2.3" instead
  $ bundle install
  $ rake gem
  $ gem install pkg/opencv-*.gem -- --with-opencv-dir=/path/to/opencvdir

To add ruby-opencv in your Gemfile:

  $ echo -e "\n"'gem "opencv", :git => "https://github.com/ruby-opencv/ruby-opencv"' >> Gemfile
  $ bundle config build.opencv --with-opencv-dir=/path/to/opencvdir
  $ bundle install  # or bundle update

== SYNOPSIS:
=== Show Image using GUI Component

  #!/usr/bin/env ruby
  require "opencv"

  image = OpenCV::IplImage.load("sample.jpg")
  window = OpenCV::GUI::Window.new("preview")
  window.show(image)
  OpenCV::GUI::wait_key

=== Face Detection

Here is a sample face detection program that doesn't rely on the GUI components.
In order for this to work you must copy the OpenCV haarcascades data into a 
subfolder called data.

  #!/usr/bin/env ruby
  require "opencv"

  if ARGV.length < 2
    puts "Usage: your_app_name source dest"
    exit
  end
 
  data = "./data/haarcascades/haarcascade_frontalface_alt.xml"
  detector = OpenCV::CvHaarClassifierCascade::load(data)
  image = OpenCV::IplImage.load(ARGV[0])
  detector.detect_objects(image).each do |region|
    color = OpenCV::CvColor::Blue
    image.rectangle! region.top_left, region.bottom_right, :color => color
  end
  image.save_image(ARGV[1])

For more samples, see examples/*.rb

== LICENSE:

The BSD Liscense

see LICENSE.txt