This version of the manual refers to an earlier version of the software.

Redaction

Redactions are black rectangles that are overlaid onto source images in order to obscure parts of them. This can be used for copyright protection, privacy protection, or censorship, without altering any source images. Different redactions can be applied to the same image dynamically for different audiences based on client IP address, cookies, and more.

Redactions are defined with x, y, width, and height properties corresponding to source image coordinates. Redacted regions will be blacked out at every intersecting crop region and scale.

Original image
Redactions applied

The redaction feature works via the delegate script. First, the delegate script must be enabled, and then, redactions.enabled must be set to true in the configuration file. The delegate script must implement a method called Cantaloupe::redactions that returns an array of source image redaction coordinates in response to a particular request.

Example

module Cantaloupe
  ##
  # See the argument and return value documentation in delegates.rb.sample.
  #
  def self.redactions(identifier, request_headers, client_ip, cookies)
    redactions = []
    # Add two redactions to an image with an identifier of "sample" for all
    # clients except localhost.
    if identifier == 'sample'
      unless %w(127.0.0.1 ::1/128).include?(client_ip)
        redactions << {
            'x' => 50,
            'y' => 65,
            'width' => 120,
            'height' => 105
        }
        redactions << {
            'x' => 673,
            'y' => 812,
            'width' => 1320,
            'height' => 620
        }
      end
    end
    redactions
  end
end

Processor Support

Not all processors support redaction; see the table of processor-supported features.

Implications

Performance

The performance of the redaction feature largely depends on the efficiency of the delegate script method implementation. Drawing of the redactions is very cheap, costing probably no more than a few milliseconds, in most cases.

Caching

Redaction coordinates are encoded in cached-image identifiers. When redaction settings change, cached redacted images will be re-generated automatically, and images with different redactions will be cached separately.