Paperclip processor that is aware of the faces found on the image
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Paperclip::FaceCrop is a Paperclip processor that is aware of the faces found on the image so that they aren't cropped or aren't shown too small while generating the thumbnails. It can use the OpenCV library or the web service(or both at the same time) for the facial recognition.



If you want to use OpenCV on your own server, you need to install:

In case you get the error message /ext/opencv/cverror.cpp:143: error: ‘CV_GpuCufftCallError’ was not declared in this scope while installing the ruby binding, checkout the OpenCV_2.2 branch or just remove the line 143 from /ext/opencv/cverror.cpp

In order to use the service, you will also need to register in order to get your api key and api secret for your application.


  • Add to your application Gemfile

        gem 'paperclip-facecrop'
  • Type

        bundle install
  • Write an initializer setting the detectors configuration (initializers/paperclip.rb for example):


Set the path of the haarcascade filters:

      Paperclip::FaceCrop.detectors = {
        'OpenCV' =>  { 
          :face => %w(/usr/local/share/opencv/haarcascades/haarcascade_frontalface_alt_tree.xml)

You can use more than one filter to try more accurate searches:

      Paperclip::FaceCrop.detectors = {
        'OpenCV' =>  { 
          :face => %w(/usr/local/share/opencv/haarcascades/haarcascade_frontalface_alt_tree.xml

In order to try to avoid some false positives, you can also specify other classifiers to detect other parts of the face. In that case, only the found areas that contain parts like a mouth, an eye or a nose will be considered a face:

      Paperclip::FaceCrop.detectors = {
        'OpenCV' =>  { 
          :face => %w(/usr/local/share/opencv/haarcascades/haarcascade_frontalface_alt_tree.xml
          :parts => %w(/usr/local/share/opencv/haarcascades/haarcascade_mcs_nose.xml

      Paperclip::FaceCrop.detectors = {
        'FaceCom' => { :api_key => "<YOUR API KEY>", :api_secret => "<YOUR API SECRET>"}


Just specify your image styles as usual and set :face_crop as the processor:

class Image < ActiveRecord::Base

  has_attached_file :attachment, 
      :styles => {:thumbnail => "200x125#"}, 
      :processors => [:face_crop]

In case no faces were found, it will behave simply as the Paperclip::Thumbnail processor

You can also set the debug mode to draw on the image the detected regions:

Paperclip::FaceCrop.debug = Rails.env.development?

Each detector will draw the found regions in different colors( detector in red and OpenCV in green)


Copyright (c) 2011 Borja Martín Sánchez de Vivar -, released under the MIT license
The photo used as example belongs to Jesper Rønn-Jensen