Pixelate faces: Ruby & ImageMagick

Tim Koschützki

Co-founder · Berlin, Germany · Show bio

Face pixelation is a powerful technique to enhance privacy by obscuring identifiable features in images. Whether you're building a social media app, a surveillance system, or simply want to anonymize images, automating face pixelation can be incredibly useful.

Why pixelate faces?

Face pixelation can reduce the visibility of identifying features. Detection can miss faces, and pixelation does not guarantee anonymity. Practical applications include:

• Social media platforms anonymizing user-uploaded images
• Surveillance footage anonymization
• Redacting faces as one part of a privacy protection process
• Protecting minors in public images
• Anonymizing research data containing human subjects

Setting up Ruby and ImageMagick

Use Ruby 3.2+, RMagick 7.x, the Google Cloud Vision 2.x gem, and ImageMagick 6.8.9+ or 7. RMagick needs a C++ compiler and ImageMagick development headers when its native extension is built:

# For macOS
brew install imagemagick pkg-config
gem install rmagick -v '~> 7.0'
gem install google-cloud-vision -v '~> 2.0'

# For Ubuntu/Debian
sudo apt-get install build-essential pkg-config imagemagick libmagickwand-dev
gem install rmagick -v '~> 7.0'
gem install google-cloud-vision -v '~> 2.0'

Setting up Google Cloud Vision API

For face detection, we'll use Google Cloud Vision API, which provides accurate and reliable face detection capabilities.

1. Create a Google cloud project

1. Go to the Google Cloud Console⁠.
2. Create a new project or select an existing one.
3. Make note of your project ID and enable billing for the project.

2. Enable the vision API

1. Navigate to "APIs & Services" > "Library".
2. Search for "Vision API" and enable it.

3. Set up authentication

For local development, use Application Default Credentials with the Google Cloud CLI:

gcloud auth application-default login
gcloud auth application-default set-quota-project PROJECT_ID

The identity needs permission to use services in the quota project (serviceusage.services.use). For production, prefer an attached service account or Workload Identity Federation. If a downloaded service account key is necessary, store it outside source control and restrict access to it.

4. Configure a key file only if your deployment requires one

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your-project-credentials.json"

Integrating face detection with Ruby using Google Cloud Vision API

The examples below work on a local, single-frame JPEG or PNG with upright pixels. Normalize EXIF orientation before detection, and process that same normalized image locally so the coordinates match. Save the following two function definitions together in pixelate.rb:

require "google/cloud/vision"

def detect_faces(image_path)
  # Initialize the Vision client
  vision = Google::Cloud::Vision.image_annotator

  # Perform face detection
  response = vision.face_detection(
    image: image_path,
    max_results: 10
  )

  # Extract face coordinates
  faces = []
  response.responses.each do |res|
    if res.error && res.error.code != 0
      raise "Face detection failed (code #{res.error.code})"
    end
    if res.face_annotations.length >= 10
      raise "Face detection limit reached; review this image manually"
    end
    res.face_annotations.each do |face|
      vertices = face.bounding_poly.vertices
      raise "Missing face coordinates" if vertices.empty?

      # Calculate face rectangle
      x, right = vertices.map(&:x).minmax
      y, bottom = vertices.map(&:y).minmax

      faces << { x: x, y: y, width: right - x, height: bottom - y,
                 confidence: face.detection_confidence }
    end
  end

  faces
end

Applying pixelation effects with ImageMagick

Using RMagick, clamp each rectangle to the image, reduce it to at least one pixel, and enlarge it with nearest-neighbor sampling for visible pixel blocks. Release the native image allocations even when cropping or writing fails:

require 'rmagick'

def pixelate_faces(image_path, faces, pixelation_factor = 0.1, output_path = 'pixelated_output.jpg')
  unless pixelation_factor.finite? && pixelation_factor > 0 && pixelation_factor < 1
    raise ArgumentError, "Pixelation factor must be between 0 and 1"
  end
  raise ArgumentError, "No face regions to pixelate" if faces.empty?

  images = Magick::Image.read(image_path)
  raise ArgumentError, "Use a single-frame image" unless images.length == 1
  img = images.first

  faces.each do |face|
    x = [face.fetch(:x).floor, 0].max
    y = [face.fetch(:y).floor, 0].max
    right = [(face.fetch(:x) + face.fetch(:width)).ceil, img.columns].min
    bottom = [(face.fetch(:y) + face.fetch(:height)).ceil, img.rows].min
    width, height = right - x, bottom - y
    raise ArgumentError, "Face rectangle is outside the image" if width <= 0 || height <= 0

    face_region = small = pixelated = nil
    begin
      face_region = img.crop(x, y, width, height, true)
      small = face_region.sample([(width * pixelation_factor).floor, 1].max,
                                 [(height * pixelation_factor).floor, 1].max)
      pixelated = small.sample(width, height)
      img.composite!(pixelated, x, y, Magick::OverCompositeOp)
    ensure
      [face_region, small, pixelated].compact.each(&:destroy!)
    end
  end

  img.strip!
  img.write(output_path)
  output_path
ensure
  images&.each(&:destroy!)
end

Step-by-step Ruby code example

Append this wrapper to pixelate.rb to combine the two functions above. Only publish the output after a successful return, and review it for missed faces or identifying details:

require "google/cloud/vision"
require 'rmagick'

def pixelate_image(image_path, output_path = 'pixelated_output.jpg', pixelation_factor = 0.1)
  begin
    # Detect faces
    faces = detect_faces(image_path)

    if faces.empty?
      puts "No faces detected in the image."
      return false
    end

    pixelate_faces(image_path, faces, pixelation_factor, output_path)
    puts "Successfully pixelated #{faces.count} faces in '#{output_path}'"
    return true

  rescue StandardError => e
    warn "Face pixelation failed (#{e.class})"
  end

  return false
end

# Usage
exit(1) unless pixelate_image('input.jpg', 'output.jpg')

Optimizing performance and handling edge cases

API considerations

• Rate limits: The default request quota is 1,800 requests per minute, with separate feature quotas. Check your project's quotas and limits⁠.
• Image size: Maximum image size is 20 MB, but JSON requests have a separate 10 MB limit and base64 encoding increases payload size. Use small local images for this example.
• Batch processing: For multiple images, use batch requests to reduce API calls.
• Cost management: Monitor usage to stay within budget constraints.

Handling edge cases

• No faces detected: The wrapper returns false; review the image instead of treating it as anonymous.
• Low confidence detections: Keep them in a privacy workflow or send them for review. Discarding them can leave a visible face unredacted.
• Partial faces: The pixelation function clamps rectangles to the image bounds and rejects regions that do not overlap the image.

# Use confidence for review without removing faces from the pixelation input.
faces = detect_faces('input.jpg')
needs_review = faces.any? { |face| face[:confidence] < 0.7 }
puts "Manual review required" if needs_review

Alternative face detection APIs

If Google Cloud Vision doesn't meet your needs, consider these alternatives:

• Amazon Rekognition: Robust face detection with additional features like age estimation.
• Microsoft Azure Face API: Comprehensive facial analysis capabilities.
• Luxand Cloud: Specialized in facial recognition technology.

How does ImageMagick integrate with Ruby for image processing?

ImageMagick integrates with Ruby through the RMagick gem, providing a comprehensive set of image manipulation capabilities. This integration allows developers to:

• Resize, crop, and transform images
• Apply filters and effects
• Composite multiple images
• Convert between image formats
• Extract image metadata

The RMagick library wraps ImageMagick's functionality in a Ruby-friendly API, making complex image operations accessible through simple method calls.

Privacy considerations

Pixelation alone does not establish compliance with privacy law. Uploading an original image to a cloud detector also exposes that original to the provider. Review the processing arrangement and applicable requirements for your use case, and:

• Obtain proper consent when processing identifiable images.
• Implement data minimization by only storing necessary information.
• Document your processing activities.
• Consider whether you need to perform a Data Protection Impact Assessment (DPIA).
• Ensure secure handling of both original and processed images.

Conclusion

Automating face pixelation with Ruby, Google Cloud Vision API, and ImageMagick provides a powerful solution for privacy-focused applications. By combining cloud-based face detection with local image manipulation, you can create face redaction workflows with a review step for missed detections.

For more advanced image processing needs, consider exploring Transloadit's Image Processing API, which offers powerful tools for processing and transforming images at scale.