Has face

An Active model validator to validate that images contain faces by using the face.com API. The validator works by uploading images to face.com and then checking to see if any faces were tagged in the photo. It has been tested with carrierwave attachments but will work with any attachment type that correctly responds to a path method.

Has face is currently used in the Swoonme iPhone application to provide face validation for the API.

Requirements

• Rails 3.0 or greater
• An account for accessing the face.com API (They are free at the moment)

Installation

Add has_face to your Gemfile and then bundle

gem 'has_face'

Once installed run the generator to create an initializer

rails g has_face:install

Then open up config/initializers/has_face.rb and enter your face.com API details.

# config/initializers/has_face.rb
HasFace.configure do |config|
  config.api_key                  = 'your face.com API key'
  config.api_secret               = 'your face.com API secret'
  config.skip_validation_on_error = false
  config.transfer_method          = :upload
end

Usage

Simply add a validation to the image you want to ensure has faces:

class User < ActiveRecord::Base
  validates :avatar, :has_face => true
end

The allow_nil and allow_blank options are supported:

class User < ActiveRecord::Base
  validates :avatar, :has_face => true, :allow_blank => true
end

i18n

Error messages generated are i18n safe. To alter the error message shown add this to your config/locale/en.yml

en:
  activerecord:
    errors:
      messages:
        no_face: "We couldn't see a face in your photo, try taking another one."

Error Handling

By default has_face will raise either a HasFace::FaceAPIError or HasFace::HTTPRequestError on failure. You will need to catch these errors and then take the appropriate action in your application like so:

begin
  @user = User.create(params[:user])
rescue HasFace::FaceAPIError, HasFace::HTTPRequestError => e
  # Perform some sort of action.
end

If you would like to skip valdiation when a HTTP or API error occurs then simply turn on the skip_validation_on_error configuration option:

HasFace.configure do |config|
  config.skip_validation_on_error = true
end

If an error does occur then it will be logged as a warning in the log for your applications current environment.

Transfer Methods

The default behavior is to upload images to the face.com API. This allows images that are not publicly accessible to be validated as well, has_face also has the option to send the URL of the image to be validated instead of uploading the data, to use url transering simply set the configuration option:

HasFace.configure do |config|
  config.transfer_method = :url
end

You will also need to set the ActionController::Base.asset_host to the base URL your images are accessible at. This can be done in your environment.rb or the environment for your specific environment, eg production.rb or staging.rb.

Testing has_face

To speed up your test suite, you can disable face validations by setting the enable_validation config value to false, this is usally best done in your test config.

HasFace.enable_validation = false

Has Face supplies a matcher which you can use in your tests, to enable it, include the matchers module in your rspec config.

RSpec.configure do |config|
  config.include HasFace::Test::Matchers
end

Once included he matcher can be used:

context 'validations' do
  it { should validate_has_face_for :avatar }
end

The options allow_blank and allow_nil can also be passed to the matcher:

it { should validate_has_face_for :avatar, :allow_blank => true }

License

Has face is distributed under a standard MIT license, see LICENSE for further information.

Contributing

Fork on GitHub and after you’ve committed tested patches, send a pull request.

To get tests running simply run bundle install and then rspec spec