dynamic_image 1.0.4 → 2.0.0.beta1

data/lib/dynamic_image/image_sizing.rb

@@ -0,0 +1,156 @@
+# encoding: utf-8
+
+module DynamicImage
+  # = DynamicImage Image Sizing
+  #
+  # Calculates cropping and fitting for image sizes.
+  class ImageSizing
+    def initialize(record, options={})
+      @record = record
+      @uncropped = options[:uncropped] ? true : false
+    end
+
+    # Calculates crop geometry. The given vector is scaled
+    # to match the image size, since DynamicImage performs
+    # cropping before resizing.
+    #
+    # ==== Example
+    #
+    #   image = Image.find(params[:id]) # 320x200 image
+    #   sizing = DynamicImage::ImageSizing.new(image)
+    #
+    #   sizing.crop_geometry(Vector2d(100, 100))
+    #   # => [Vector2d(200, 200), Vector2d(60, 0)]
+    #
+    # Returns a tuple with crop size and crop start vectors.
+    def crop_geometry(ratio_vector)
+      # Maximize the crop area to fit the image size
+      crop_size = ratio_vector.fit(size).round
+
+      # Ignore pixels outside the pre-cropped area for now
+      center = crop_gravity - crop_start
+
+      start = center - (crop_size / 2).floor
+      start = clamp(start, crop_size, size)
+
+      [crop_size, (start + crop_start)]
+    end
+
+    # Returns crop geometry as an ImageMagick compatible string.
+    #
+    # ==== Example
+    #
+    #   image = Image.find(params[:id]) # 320x200 image
+    #   sizing = DynamicImage::ImageSizing.new(image)
+    #
+    #   sizing.crop_geometry(Vector2d(100, 100)) # => "200x200+60+0"
+    def crop_geometry_string(ratio_vector)
+      crop_size, start = crop_geometry(ratio_vector)
+      crop_size.floor.to_s + "+#{start.x.to_i}+#{start.y.to_i}"
+    end
+
+    # Adjusts +fit_size+ to fit the image dimensions.
+    # Any dimension set to zero will be ignored.
+    #
+    # ==== Options
+    #
+    # * <tt>:crop</tt> - Don't keep aspect ratio. This will allow
+    #   the image to be cropped to the requested size.
+    # * <tt>:upscale</tt> - Don't limit to the size of the image.
+    #   Images smaller than the given size will be scaled up.
+    #
+    # ==== Examples
+    #
+    #   image = Image.find(params[:id]) # 320x200 image
+    #   sizing = DynamicImage::ImageSizing.new(image)
+    #
+    #   sizing.fit(Vector2d(0, 100))
+    #   # => Vector2d(160.0, 100.0)
+    #
+    #   sizing.fit(Vector2d(500, 500))
+    #   # => Vector2d(320.0, 200.0)
+    #
+    #   sizing.fit(Vector2d(500, 500), crop: true)
+    #   # => Vector2d(200.0, 200.0)
+    #
+    #   sizing.fit(Vector2d(500, 500), upscale: true)
+    #   # => Vector2d(500.0, 312.5)
+    #
+    def fit(fit_size, options={})
+      fit_size = parse_vector(fit_size)
+      require_dimensions!(fit_size)     if options[:crop]
+      fit_size = size.fit(fit_size)     unless options[:crop]
+      fit_size = size.contain(fit_size) unless options[:upscale]
+      fit_size
+    end
+
+    private
+
+    def crop_gravity
+      if uncropped? && !record.crop_gravity?
+        size / 2
+      else
+        record.crop_gravity
+      end
+    end
+
+    def crop_start
+      if uncropped?
+        Vector2d.new(0, 0)
+      else
+        record.crop_start
+      end
+    end
+
+    def size
+      if uncropped?
+        record.real_size
+      else
+        record.size
+      end
+    end
+
+    # Clamps the rectangle defined by +start+ and +size+
+    # to fit inside 0, 0 and +max_size+. It is assumed
+    # that +size+ will always be smaller than +max_size+.
+    #
+    # Returns the start vector.
+    def clamp(start, size, max_size)
+      start += shift_vector(start)
+      start -= shift_vector(max_size - (start + size))
+      start
+    end
+
+    def parse_vector(v)
+      v.kind_of?(String) ? str_to_vector(v) : v
+    end
+
+    def record
+      @record
+    end
+
+    def require_dimensions!(v)
+      raise DynamicImage::Errors::InvalidSizeOptions unless v.x > 0 && v.y > 0
+    end
+
+    def shift_vector(vect)
+      vector(
+        vect.x < 0 ? vect.x.abs : 0,
+        vect.y < 0 ? vect.y.abs : 0
+      )
+    end
+
+    def str_to_vector(str)
+      x, y = str.match(/(\d*)x(\d*)/)[1,2].map(&:to_i)
+      Vector2d.new(x, y)
+    end
+
+    def uncropped?
+      @uncropped
+    end
+
+    def vector(x, y)
+      Vector2d.new(x, y)
+    end
+  end
+end

data/lib/dynamic_image/metadata.rb

@@ -0,0 +1,84 @@
+# encoding: utf-8
+
+module DynamicImage
+  # = DynamicImage Metadata
+  #
+  # Parses metadata from an image. Expects to receive image data as a
+  # binary string.
+  class Metadata
+    def initialize(data)
+      @data = data
+    end
+
+    # Returns the color space of the image as a string. The result will be one
+    # of the following: "rgb", "cmyk", "gray".
+    def colorspace
+      if valid?
+        case metadata[:colorspace]
+        when /rgb/i
+          "rgb"
+        when /cmyk/i
+          "cmyk"
+        when /gray/i
+          "gray"
+        end
+      end
+    end
+
+    # Returns the content type of the image.
+    def content_type
+      if valid?
+        "image/#{format.downcase}"
+      end
+    end
+
+    # Returns the dimensions of the image as a vector.
+    def dimensions
+      if valid?
+        Vector2d.new(*metadata[:dimensions])
+      end
+    end
+
+    # Returns the width of the image.
+    def width
+      dimensions.try(:x)
+    end
+
+    # Returns the height of the image.
+    def height
+      dimensions.try(:y)
+    end
+
+    # Returns the format of the image.
+    def format
+      if valid?
+        metadata[:format]
+      end
+    end
+
+    # Returns true if the image is valid.
+    def valid?
+      @data && metadata != :invalid
+    end
+
+    private
+
+    def metadata
+      @metadata ||= read_metadata
+    end
+
+    def read_metadata
+      image = MiniMagick::Image.read(@data)
+      image.auto_orient
+      metadata = {
+        colorspace: image[:colorspace],
+        dimensions: image[:dimensions],
+        format:     image[:format]
+      }
+      image.destroy!
+      metadata
+    rescue MiniMagick::Invalid
+      :invalid
+    end
+  end
+end

data/lib/dynamic_image/model/dimensions.rb

@@ -0,0 +1,95 @@
+# encoding: utf-8
+
+module DynamicImage
+  module Model
+    # = DynamicImage Model Dimensions
+    #
+    module Dimensions
+
+      # Returns the crop gravity.
+      #
+      # DynamicImage will try to keep the pixel represented by
+      # crop_gravity as close to the center as possible when cropping
+      # images.
+      #
+      # It is relative to 0,0 on the original image.
+      #
+      # Unless crop_gravity has been explicitely set, it defaults to
+      # the center of the cropped image.
+      def crop_gravity
+        if crop_gravity?
+          vector(crop_gravity_x, crop_gravity_y)
+        elsif cropped?
+          crop_start + (crop_size / 2)
+        elsif size?
+          size / 2
+        end
+      end
+
+      # Returns true if crop gravity has been explicitely set.
+      def crop_gravity?
+        crop_gravity_x.present? && crop_gravity_y.present?
+      end
+
+      # Returns the crop size, or nil if no cropping is applied.
+      def crop_size
+        if crop_size?
+          vector(crop_width, crop_height)
+        end
+      end
+
+      # Returns true if crop size has been set.
+      def crop_size?
+        crop_width? && crop_height?
+      end
+
+      # Returns the crop start if set, or Vector2d(0, 0) if not.
+      def crop_start
+        if crop_start?
+          vector(crop_start_x, crop_start_y)
+        else
+          vector(0, 0)
+        end
+      end
+
+      # Returns true if crop start has been set.
+      def crop_start?
+        crop_start_x.present? && crop_start_y.present?
+      end
+
+      # Returns true if the image is cropped.
+      def cropped?
+        crop_size? && real_size? && crop_size != real_size
+      end
+
+      # Returns the real size of the image, without any cropping applied.
+      def real_size
+        if real_size?
+          vector(real_width, real_height)
+        end
+      end
+
+      # Returns true if the size has been set.
+      def real_size?
+        real_width? && real_height?
+      end
+
+      # Returns the cropped size if the image has been cropped. If not,
+      # it returns the actual size.
+      def size
+        crop_size || real_size
+      end
+
+      # Returns true if the image has size set.
+      def size?
+        size ? true : false
+      end
+
+      private
+
+      def vector(x, y)
+        Vector2d.new(x, y)
+      end
+    end
+  end
+end

data/lib/dynamic_image/model/validations.rb

@@ -0,0 +1,94 @@
+# encoding: utf-8
+
+module DynamicImage
+  module Model
+    # = DynamicImage Model Validations
+    #
+    # Validates that all necessary attributes are valid. All of these are
+    # managed by +DynamicImage::Model+, so this is mostly for enforcing
+    # integrity.
+    module Validations
+      extend ActiveSupport::Concern
+      included do
+        validates_data_presence
+
+        validates :colorspace,
+          presence: true,
+          inclusion: { in: allowed_colorspaces }
+
+        validates :content_type,
+          presence: true,
+          inclusion: { in: allowed_content_types }
+
+        validates :content_length,
+          presence: true,
+          numericality: { greater_than: 0, only_integer: true }
+
+        validates :filename,
+          presence: true,
+          length: { maximum: 255 }
+
+        validates :real_width, :real_height,
+          numericality: { greater_than: 0, only_integer: true }
+
+        validates :real_width, :real_height,
+          numericality: { greater_than: 0, only_integer: true }
+
+        validates :crop_width, :crop_height,
+          :crop_gravity_x, :crop_gravity_y,
+          numericality: { greater_than: 0, only_integer: true },
+          allow_nil: true
+
+        validates :real_width, :real_height,
+          presence: true
+
+        validates :crop_width, presence: true, if: :crop_height?
+        validates :crop_height, presence: true, if: :crop_width?
+
+        validates :crop_start_x, presence: true, if: :crop_start_y?
+        validates :crop_start_y, presence: true, if: :crop_start_x?
+
+        validates :crop_gravity_x, presence: true, if: :crop_gravity_y?
+        validates :crop_gravity_y, presence: true, if: :crop_gravity_x?
+
+        validate :validate_crop_bounds, if: :cropped?
+        validate :validate_image, if: :data_changed?
+      end
+
+      module ClassMethods
+        def allowed_colorspaces
+          %w{
+            rgb
+            cmyk
+            gray
+          }
+        end
+
+        def allowed_content_types
+          %w{
+            image/gif
+            image/jpeg
+            image/pjpeg
+            image/png
+            image/tiff
+          }
+        end
+      end
+
+      private
+
+      def validate_crop_bounds
+        required_size = crop_start + crop_size
+        if required_size.x > real_size.x || required_size.y > real_size.y
+          self.errors.add(:crop_size, "is out of bounds")
+        end
+      end
+
+      def validate_image
+        unless valid_image?
+         self.errors.add(:data, :invalid)
+        end
+      end
+    end
+  end
+end

data/lib/dynamic_image/model.rb

@@ -0,0 +1,130 @@
+# encoding: utf-8
+
+require 'dynamic_image/model/dimensions'
+require 'dynamic_image/model/validations'
+
+module DynamicImage
+  # = DynamicImage Model
+  #
+  # ActiveModel extension for the model holding image data. It assumes your
+  # database table has at least the following attributes:
+  #
+  #   create_table :images do |t|
+  #     t.string  :content_hash
+  #     t.string  :content_type
+  #     t.integer :content_length
+  #     t.string  :filename
+  #     t.string  :colorspace
+  #     t.integer :real_width, :real_height
+  #     t.integer :crop_width, :crop_height
+  #     t.integer :crop_start_x, :crop_start_y
+  #     t.integer :crop_gravity_x, :crop_gravity_y
+  #     t.timestamps
+  #   end
+  #
+  # To use it, simply include it in your model:
+  #
+  #   class Image < ActiveRecord::Base
+  #     include DynamicImage::Model
+  #   end
+  #
+  # == Usage
+  #
+  # To save an image, simply assign to the +file+ attribute.
+  #
+  #   image = Image.create(file: params.permit(:file))
+  #
+  # This will automatically parse and validate the image when your record is
+  # saved.
+  #
+  # To read back the image data, access the +data+ attribute. This will lazily
+  # load the data from the store.
+  #
+  #   data = image.data
+  #
+  # == Cropping
+  #
+  # Images can be pre-cropped by setting +crop_width+, +crop_height+,
+  # +crop_start_x+ and +crop_start_y+. The crop dimensions cannot exceed the
+  # image size.
+  #
+  #   image.update(
+  #     crop_start_x: 15, crop_start_y: 20,
+  #     crop_width: 300, crop_height: 200
+  #   )
+  #   image.size # => Vector2d(300, 200)
+  #
+  # By default, images will be cropped from the center. You can control this
+  # by setting +crop_gravity_x+ and +crop_gravity_y+. DynamicImage will make
+  # sure the pixel referred to by these coordinates are present in the cropped
+  # image, and as close to the center as possible without zooming in.
+  module Model
+    extend ActiveSupport::Concern
+    include Dis::Model
+    include DynamicImage::Model::Dimensions
+    include DynamicImage::Model::Validations
+
+    included do
+      before_validation :read_image_metadata, if: :data_changed?
+    end
+
+    # Returns true if the image is in the CMYK colorspace
+    def cmyk?
+      colorspace == "cmyk"
+    end
+
+    # Returns true if the image is in the grayscale colorspace
+    def gray?
+      colorspace == "gray"
+    end
+
+    # Returns true if the image is in the RGB colorspace
+    def rgb?
+      colorspace == "rgb"
+    end
+
+    # Finds a web safe content type. GIF, JPEG and PNG images are allowed,
+    # any other formats should be converted to JPEG.
+    def safe_content_type
+      if safe_content_types.include?(content_type)
+        content_type
+      else
+        'image/jpeg'
+      end
+    end
+
+    # Includes a timestamp fingerprint in the URL param, so
+    # that rendered images can be cached indefinitely.
+    def to_param
+      [id, updated_at.utc.to_s(cache_timestamp_format)].join('-')
+    end
+
+    private
+
+    def read_image_metadata
+      metadata = DynamicImage::Metadata.new(self.data)
+      if metadata.valid?
+        self.colorspace = metadata.colorspace
+        self.real_width = metadata.width
+        self.real_height = metadata.height
+        self.content_type = metadata.content_type
+        @valid_image = true
+      else
+        @valid_image = false
+      end
+      true
+    end
+
+    def valid_image?
+      @valid_image ? true : false
+    end
+
+    def safe_content_types
+      %w{
+        image/png
+        image/gif
+        image/jpeg
+      }
+    end
+  end
+end

data/lib/dynamic_image/processed_image.rb

@@ -0,0 +1,119 @@
+# encoding: utf-8
+
+module DynamicImage
+  # = DynamicImage Processed Image
+  #
+  # Handles all processing of images. Takes an instance of
+  # +DynamicImage::Model+ as argument.
+  class ProcessedImage
+    def initialize(record, options={})
+      @record    = record
+      @uncropped = options[:uncropped] ? true : false
+      @format    = options[:format].to_s.upcase if options[:format]
+      @format    = "JPEG" if @format == "JPG"
+    end
+
+    # Returns the content type of the processed image.
+    #
+    # ==== Example
+    #
+    #   image = Image.find(params[:id])
+    #   DynamicImage::ProcessedImage.new(image).content_type
+    #   # => 'image/png'
+    #   DynamicImage::ProcessedImage.new(image, :jpeg).content_type
+    #   # => 'image/jpeg'
+    def content_type
+      "image/#{format}".downcase
+    end
+
+    # Crops and resizes the image. Normalization is performed as well.
+    #
+    # ==== Example
+    #
+    #   processed = DynamicImage::ProcessedImage.new(image)
+    #   image_data = processed.cropped_and_resized(Vector2d.new(200, 200))
+    #
+    # Returns a binary string.
+    def cropped_and_resized(size)
+      normalized do |image|
+        image.crop image_sizing.crop_geometry_string(size)
+        image.resize size
+      end
+    end
+
+    # Normalizes the image.
+    #
+    # * Applies EXIF rotation
+    # * CMYK images are converted to sRGB
+    # * Strips metadata
+    # * Performs format conversion if the requested format is different
+    #
+    # ==== Example
+    #
+    #   processed = DynamicImage::ProcessedImage.new(image, :jpeg)
+    #   jpg_data = processed.normalized
+    #
+    # Returns a binary string.
+    def normalized(&block)
+      require_valid_image!
+      process_data do |image|
+        image.combine_options do |combined|
+          image.auto_orient
+          image.colorspace('sRGB') if needs_colorspace_conversion?
+          yield(combined) if block_given?
+          image.strip
+        end
+        image.format(format) if needs_format_conversion?
+      end
+    end
+
+    private
+
+    def format
+      @format || record_format
+    end
+
+    def image_sizing
+      @image_sizing ||= DynamicImage::ImageSizing.new(record, uncropped: @uncropped)
+    end
+
+    def needs_colorspace_conversion?
+      record.cmyk?
+    end
+
+    def needs_format_conversion?
+      format != record_format
+    end
+
+    def process_data(&block)
+      image = MiniMagick::Image.read(record.data)
+      yield(image)
+      result = image.to_blob
+      image.destroy!
+      result
+    end
+
+    def record
+      @record
+    end
+
+    def record_format
+      case record.content_type
+      when 'image/png'
+        'PNG'
+      when 'image/gif'
+        'GIF'
+      when 'image/jpeg', 'image/pjpeg'
+        'JPEG'
+      when 'image/tiff'
+        'TIFF'
+      end
+    end
+
+    def require_valid_image!
+      unless record.valid?
+        raise DynamicImage::Errors::InvalidImage
+      end
+    end
+  end
+end

data/lib/dynamic_image/railtie.rb

@@ -0,0 +1,18 @@
+# encoding: utf-8
+
+module DynamicImage
+  class Railtie < ::Rails::Railtie
+    initializer "dynamic_image" do
+      ActionDispatch::Routing::Mapper.send :include, DynamicImage::Routing
+
+      config.after_initialize do |app|
+        secret = app.key_generator.generate_key('dynamic_image')
+        DynamicImage.digest_verifier = DynamicImage::DigestVerifier.new(secret)
+      end
+
+      ActiveSupport.on_load(:active_record) do
+        send :include, DynamicImage::BelongsTo
+      end
+    end
+  end
+end