dynamic_image 3.0.8 → 3.1.0

data/lib/dynamic_image/model.rb

@@ -8,8 +8,8 @@ require "dynamic_image/model/variants"
 module DynamicImage
   # = DynamicImage Model
   #
-  # ActiveModel extension for the model holding image data. It assumes your
-  # database table has at least the following attributes:
+  # ActiveModel extension for the model holding image data. The table needs at least the attributes in
+  # {DynamicImage::Schema::ATTRIBUTES}:
   #
   #   create_table :images do |t|
   #     t.string  :content_hash
@@ -24,7 +24,7 @@ module DynamicImage
   #     t.timestamps
   #   end
   #
-  # To use it, simply include it in your model:
+  # Include it in your model:
   #
   #   class Image < ActiveRecord::Base
   #     include DynamicImage::Model
@@ -32,23 +32,18 @@ module DynamicImage
   #
   # == Usage
   #
-  # To save an image, simply assign to the +file+ attribute.
+  # To save an image, assign to the +file+ attribute. The image is parsed and validated when the record is saved.
   #
   #   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.
+  # To read back the image data, access the +data+ attribute. The data is loaded lazily 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.
+  # 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,
@@ -56,10 +51,14 @@ module DynamicImage
   #   )
   #   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.
+  # 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.
+  #
+  # @see DynamicImage::Model::Dimensions
+  # @see DynamicImage::Model::Transformations
+  # @see DynamicImage::Model::Validations
+  # @see DynamicImage::Model::Variants
   module Model
     extend ActiveSupport::Concern
     include Dis::Model
@@ -72,33 +71,62 @@ module DynamicImage
       before_validation :read_image_metadata, if: :data_changed?
     end
 
-    # Returns true if the image is in the CMYK colorspace
+    # Returns true if the image holds more than one frame.
+    #
+    # Images stored before +frame_count+ existed have none, and are taken to be still.
+    #
+    # @return [Boolean]
+    def animated?
+      has_attribute?(:frame_count) && frame_count.to_i > 1
+    end
+
+    # Returns the alt text for the image, or nil if none has been set.
+    #
+    # DynamicImage doesn't add this column by default. Either create it yourself or override the method to
+    # provide your own implementation.
+    #
+    # Note that there is a distinction between nil and a blank string. <tt>alt=""</tt> means the image is
+    # purely decorative, while a missing attribute is an accessibility defect.
+    #
+    # @return [String, nil]
+    # @see DynamicImage::Helper#dynamic_image_tag
+    def alt_text
+      self[:alt_text] if has_attribute?(:alt_text)
+    end
+
+    # Returns true if the image is in the CMYK colorspace.
+    #
+    # @return [Boolean]
     def cmyk?
       colorspace == "cmyk"
     end
 
-    # Returns true if the image is in the grayscale colorspace
+    # Returns true if the image is in the grayscale colorspace.
+    #
+    # @return [Boolean]
     def gray?
       colorspace == "gray"
     end
 
-    # Returns true if the image is in the RGB colorspace
+    # Returns true if the image is in the RGB colorspace.
+    #
+    # @return [Boolean]
     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.
+    # Finds a web safe content type, negotiated against {DynamicImage.default_formats}.
+    #
+    # @return [String]
+    # @see DynamicImage::FormatNegotiator
     def safe_content_type
-      if safe_content_types.include?(content_type)
-        content_type
-      else
-        "image/jpeg"
-      end
+      DynamicImage::FormatNegotiator
+        .new(self).negotiate(DynamicImage.default_formats).content_type
     end
 
-    # Includes a timestamp fingerprint in the URL param, so
-    # that rendered images can be cached indefinitely.
+    # Includes a timestamp fingerprint in the URL param, so rendered images can be cached indefinitely.
+    #
+    # @return [String] the id and an +updated_at+ fingerprint
     def to_param
       [id, updated_at.utc.to_fs(cache_timestamp_format)].join("-")
     end
@@ -106,25 +134,26 @@ module DynamicImage
     private
 
     def read_image_metadata
-      metadata = DynamicImage::Metadata.new(Pathname(data_file_path))
       @valid_image = false
+      with_data_file do |path|
+        apply_image_metadata(DynamicImage::Metadata.new(path))
+      end
+    end
+
+    def apply_image_metadata(metadata)
       return unless metadata.valid?
 
       self.colorspace = metadata.colorspace
       self.real_width = metadata.width
       self.real_height = metadata.height
       self.content_type = metadata.content_type
+      self.frame_count = metadata.frame_count if has_attribute?(:frame_count)
+      self.alpha = metadata.alpha? if has_attribute?(:alpha)
       @valid_image = 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/picture/format_policy.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module DynamicImage
+  class Picture
+    # = DynamicImage Picture Format Policy
+    #
+    # Decides what a responsive image is rendered in. The <tt>source</tt> gets the best format available for
+    # output, transcoded unconditionally. The <tt>img</tt> gets one of {DynamicImage::COMPATIBLE_FORMATS}.
+    #
+    # @see DynamicImage::FormatNegotiator
+    class FormatPolicy
+      # The format the candidates are rendered in when the view doesn't ask for one.
+      DEFAULT_SOURCE_FORMAT = :webp
+
+      # @!attribute [r] record
+      #   @return [DynamicImage::Model]
+      # @!attribute [r] requested
+      #   @return [Symbol, Array<Symbol>, nil]
+      attr_reader :record, :requested
+
+      # @param record [DynamicImage::Model] the image
+      # @param requested [Symbol, Array<Symbol>, nil] the format the candidates are rendered in. A symbol forces
+      #   that format, an array is negotiated, nil takes the default.
+      def initialize(record, requested = nil)
+        @record = record
+        @requested = requested
+      end
+
+      # The format the candidates are rendered in.
+      #
+      # @return [DynamicImage::Format]
+      def source
+        @source ||= resolve(requested || default_source)
+      end
+
+      # The format the fallback image is rendered in.
+      #
+      # @return [DynamicImage::Format]
+      def fallback
+        @fallback ||= resolve(fallback_formats)
+      end
+
+      private
+
+      def default_source
+        record.animated? ? fallback_formats : DEFAULT_SOURCE_FORMAT
+      end
+
+      def resolve(value)
+        return negotiate(value) if value.is_a?(Array)
+
+        DynamicImage::Format.find(value) ||
+          raise(ArgumentError, "unknown format: #{value.inspect}")
+      end
+
+      def negotiate(formats)
+        DynamicImage::FormatNegotiator.new(record).negotiate(formats)
+      end
+
+      # An animated image keeps its own format if it can.
+      def fallback_formats
+        return DynamicImage::COMPATIBLE_FORMATS unless record.animated?
+
+        [stored_format_name, *DynamicImage::COMPATIBLE_FORMATS].compact
+      end
+
+      def stored_format_name
+        DynamicImage::Format.content_type(record.content_type)&.name
+      end
+    end
+  end
+end

data/lib/dynamic_image/picture.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module DynamicImage
+  # = DynamicImage Picture
+  #
+  # Everything needed to render an image responsively: the candidate widths, the signed URLs behind them, and the
+  # fallback the <tt>img</tt> points at.
+  #
+  # Sizing is expressed as an optional ratio instead of a size.
+  #
+  # @example
+  #   picture = DynamicImage::Picture.new(self, image, ratio: "16:9")
+  #   picture.srcset # => "/images/… 420w, /images/… 590w, …"
+  #   picture.src    # => "/images/…/1200x675/…jpg"
+  #
+  # @see DynamicImage::Breakpoints for how the widths are chosen
+  # @see DynamicImage::Helper#dynamic_picture_tag
+  class Picture
+    # The options this class consumes. Anything else is passed on to the router.
+    OPTIONS = %i[ratio sizes breakpoints step fallback_width format uncropped].freeze
+
+    # @!attribute [r] record
+    #   @return [DynamicImage::Model]
+    # @!attribute [r] ratio
+    #   @return [Float, nil]
+    # @!attribute [r] sizes
+    #   @return [String] the +sizes+ attribute
+    # @!attribute [r] breakpoints
+    #   @return [DynamicImage::Breakpoints] the candidate widths
+    # @!attribute [r] fallback_width
+    #   @return [Integer] the width asked for the fallback image
+    attr_reader :template, :record_or_array, :ratio, :sizes, :breakpoints, :fallback_width, :url_options
+
+    # @param template [ActionView::Base] the view context, for routing
+    # @param record_or_array [DynamicImage::Model, Array] the record, or an array of records for a nested route
+    # @param options [Hash]
+    # @option options [Numeric, Vector2d, String, nil] :ratio The aspect ratio to crop to, as a number, a vector, or a
+    #   string like <tt>"16:9"</tt>. Implies cropping. Omit for the image's own.
+    # @option options [String] :sizes The +sizes+ attribute
+    # @option options [Range, Array<Integer>, Integer] :breakpoints The widths to offer, overriding
+    #   {DynamicImage.default_breakpoints}
+    # @option options [Numeric] :step The step between breakpoints, overriding {DynamicImage.breakpoint_step}
+    # @option options [Integer] :fallback_width The width to ask for the fallback image, overriding
+    #   {DynamicImage.picture_fallback_width}
+    # @option options [Symbol, Array<Symbol>] :format The format the candidates are rendered in. A symbol forces
+    #   that format, an array is negotiated. Defaults to WebP, or the image's own format if it is animated.
+    # @option options [Boolean] :uncropped Size against the whole image, ignoring any pre-cropping. Defaults to
+    #   whether the URL points at the +uncropped+ action.
+    #
+    # Any options supported by +polymorphic_url+ are also accepted, and passed on to the router.
+    def initialize(template, record_or_array, options = {})
+      options = options.symbolize_keys
+      @template = template
+      @record_or_array = Array(record_or_array)
+      @ratio = DynamicImage::Ratio.parse(options[:ratio])
+      @sizes = options[:sizes] || "100vw"
+      @requested_format = options[:format]
+      @fallback_width = fallback_width_from(options)
+      @breakpoints = breakpoints_from(options)
+      @url_options = options.except(*OPTIONS)
+      @uncropped = options.fetch(:uncropped) { url_options[:action].to_s == "uncropped" }
+    end
+
+    # Returns true if the image is cropped, which it is whenever a ratio is given.
+    #
+    # @return [Boolean]
+    def crop?
+      !ratio.nil?
+    end
+
+    # The widest the image can be rendered at: its own width, or the width of the largest crop matching the ratio.
+    #
+    # @return [Integer]
+    def available_width
+      @available_width ||= sizing.available_width(ratio)
+    end
+
+    # The candidate widths, smallest first.
+    #
+    # @return [Array<Integer>]
+    def widths
+      @widths ||= breakpoints.widths(available_width)
+    end
+
+    # Every candidate, as the URL and the size it is actually rendered at.
+    #
+    # @return [Array<Hash>]
+    def variants
+      @variants ||= widths.map { |width| variant(width) }
+    end
+
+    # The +srcset+ attribute for the candidates, or nil if there are none. It belongs on the <tt>source</tt> when
+    # {#sources} has one, and on the <tt>img</tt> when it doesn't.
+    #
+    # @return [String, nil]
+    def srcset
+      return if variants.empty?
+
+      variants.map { |v| "#{v[:url]} #{v[:width]}w" }.join(", ")
+    end
+
+    # The sources to render, as +type+ and +srcset+ pairs.
+    #
+    # Empty when the candidates are in the same format as the fallback; {#srcset} goes on the <tt>img</tt> instead.
+    # That is what happens to an animated image, which keeps its own format.
+    #
+    # @return [Array<Hash>]
+    def sources
+      candidates = srcset
+      return [] if candidates.nil? || format == fallback_format
+
+      [{ type:, srcset: candidates }]
+    end
+
+    # The content type the candidates are rendered as, for the +type+ attribute.
+    #
+    # @return [String]
+    def type
+      format.content_type
+    end
+
+    # The format the fallback image is rendered in, negotiated from {DynamicImage::COMPATIBLE_FORMATS}.
+    #
+    # @return [DynamicImage::Format]
+    def fallback_format
+      format_policy.fallback
+    end
+
+    # The size asked for the fallback image, as a <tt>"{width}x{height}"</tt> string.
+    #
+    # @return [String]
+    def fallback_size
+      @fallback_size ||= size_for(fallback_width)
+    end
+
+    # The size the fallback image is actually rendered at. Smaller than {#fallback_size} when the image is.
+    #
+    # @return [Vector2d]
+    def dimensions
+      @dimensions ||= sizing.fit(fallback_size, crop: crop?).floor
+    end
+
+    # The URL for the fallback image.
+    #
+    # @return [String]
+    def src
+      url_for(fallback_size, fallback_format)
+    end
+
+    # The width of the fallback image.
+    #
+    # @return [Integer]
+    def width
+      dimensions.x.to_i
+    end
+
+    # The height of the fallback image.
+    #
+    # @return [Integer]
+    def height
+      dimensions.y.to_i
+    end
+
+    private
+
+    def fallback_width_from(options)
+      (options[:fallback_width] || DynamicImage.picture_fallback_width).to_i
+    end
+
+    def breakpoints_from(options)
+      DynamicImage::Breakpoints.new(options[:breakpoints], step: options[:step])
+    end
+
+    def record
+      record_or_array.last
+    end
+
+    def sizing
+      @sizing ||= DynamicImage::ImageSizing.new(record, uncropped: @uncropped)
+    end
+
+    def variant(width)
+      requested = size_for(width)
+      size = sizing.fit(requested, crop: crop?).floor
+      # {#url_for} fits the size it is given. +size+ has been floored to whole pixels, so it is no longer exactly
+      # proportional and would fit smaller a second time. Pass the request instead.
+      { url: url_for(requested, format),
+        width: size.x.to_i,
+        height: size.y.to_i }
+    end
+
+    def size_for(width)
+      return "#{width}x" unless ratio
+
+      "#{width}x#{(width / ratio).round}"
+    end
+
+    def url_for(requested_size, image_format)
+      template.dynamic_image_path(record_or_array,
+                                  url_options.merge(
+                                    size: requested_size,
+                                    crop: crop?,
+                                    format: image_format.mime_type.to_sym
+                                  ))
+    end
+
+    def format
+      format_policy.source
+    end
+
+    def format_policy
+      @format_policy ||= FormatPolicy.new(record, @requested_format)
+    end
+  end
+end

data/lib/dynamic_image/processed_image.rb

@@ -3,11 +3,22 @@
 module DynamicImage
   # = DynamicImage Processed Image
   #
-  # Handles all processing of images. Takes an instance of
-  # +DynamicImage::Model+ as argument.
+  # Crops, resizes and converts images, and reads back the processed data.
+  #
+  # Each processed size is stored as a variant, so subsequent calls for the same size are cheap.
+  #
+  # @example
+  #   size = DynamicImage::ImageSizing.new(image).fit("800x800")
+  #   data = DynamicImage::ProcessedImage.new(image, format: :jpg)
+  #                                      .cropped_and_resized(size)
   class ProcessedImage
+    # @return [DynamicImage::Model]
     attr_reader :record
 
+    # @param record [DynamicImage::Model] the image to process
+    # @param options [Hash]
+    # @option options [Boolean] :uncropped Ignore any crop stored on the record
+    # @option options [Symbol, String] :format Format to convert to. Defaults to the format of the stored image.
     def initialize(record, options = {})
       @record    = record
       @uncropped = options[:uncropped] ? true : false
@@ -15,28 +26,40 @@ module DynamicImage
       @format_name = "JPEG" if defined?(@format_name) && @format_name == "JPG"
     end
 
-    # Crops and resizes the image. Normalization is performed as well.
+    # Crops, resizes and normalizes the image.
     #
-    # ==== Example
+    # @param size [Vector2d] the size to render, in pixels
+    # @return [String] the image data as a binary string
+    # @raise [DynamicImage::Errors::InvalidImage] if the record isn't a valid image, or if the stored data can't be
+    #   processed
     #
+    # @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)
       return crop_and_resize(size) unless record.persisted?
 
       find_or_create_variant(size).data
     end
 
-    # Find or create a variant with the given size.
+    # Returns the variant for the given size, creating it if it doesn't already exist.
+    #
+    # @param size [Vector2d] the size to render, in pixels
+    # @return [DynamicImage::Variant]
+    # @raise [DynamicImage::Errors::InvalidImage] if the record isn't a valid image, or if the stored data can't be
+    #   processed
     def find_or_create_variant(size)
       find_variant(size) || create_variant(size)
     rescue ActiveRecord::RecordNotUnique
       find_variant(size)
     end
 
-    # Find a variant with the given size.
+    # Returns the variant for the given size, if one exists.
+    #
+    # Variants whose data has gone missing from storage are destroyed and treated as absent.
+    #
+    # @param size [Vector2d] the size to look for, in pixels
+    # @return [DynamicImage::Variant, nil] the variant, if one exists
     def find_variant(size)
       return nil unless record.persisted?
 
@@ -51,8 +74,10 @@ module DynamicImage
       end
     end
 
-    # Find or create a variant for the given size, returning the variant
-    # record (not data). Returns nil if the record is not persisted.
+    # Same as {#cropped_and_resized}, but returns the variant record instead of its data.
+    #
+    # @param size [Vector2d] the size to render, in pixels
+    # @return [DynamicImage::Variant, nil] the variant, or nil if the record isn't persisted
     def variant_for(size)
       return nil unless record.persisted?
 
@@ -61,6 +86,9 @@ module DynamicImage
       find_variant(size)
     end
 
+    # The format the image is rendered in. Defaults to the format of the stored image.
+    #
+    # @return [DynamicImage::Format]
     def format
       DynamicImage::Format.find(@format_name) || record_format
     end
@@ -73,18 +101,26 @@ module DynamicImage
     # * Optimizes GIFs
     # * Performs format conversion if the requested format is different
     #
-    # ==== Example
+    # @yield [image] an optional block to transform the image before it is written out
+    # @yieldparam image [DynamicImage::ImageProcessor] the processor
+    # @yieldreturn [DynamicImage::ImageProcessor] the transformed processor
+    # @return [String] the image data as a binary string
+    # @raise [DynamicImage::Errors::InvalidImage] if the record isn't a valid image, or if the stored data can't be
+    #   processed
     #
-    #   processed = DynamicImage::ProcessedImage.new(image, :jpeg)
+    # @example
+    #   processed = DynamicImage::ProcessedImage.new(image, format: :jpeg)
     #   jpg_data = processed.normalized
-    #
-    # Returns a binary string.
     def normalized
       require_valid_image!
 
-      image = DynamicImage::ImageProcessor.new(Pathname(record.data_file_path))
-      image = yield(image) if block_given?
-      image.convert(format).read
+      record.with_data_file do |path|
+        image = DynamicImage::ImageProcessor.new(path)
+        image = yield(image) if block_given?
+        image.convert(format).read
+      end
+    rescue Vips::Error => e
+      raise DynamicImage::Errors::InvalidImage, e.message
     end
 
     private

data/lib/dynamic_image/ratio.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module DynamicImage
+  # = DynamicImage Ratio
+  #
+  # Coerces an aspect ratio into a float. Strings, rationals, floats and vectors are all accepted.
+  #
+  # @example
+  #   DynamicImage::Ratio.parse("16:9")           # => 1.7777..
+  #   DynamicImage::Ratio.parse("16x9")           # => 1.7777..
+  #   DynamicImage::Ratio.parse(Rational(16, 9))  # => 1.7777..
+  #   DynamicImage::Ratio.parse(Vector2d(16, 9))  # => 1.7777..
+  module Ratio
+    class << self
+      # Returns the ratio as width divided by height.
+      #
+      # @param value [Numeric, Vector2d, String, nil] the ratio, as a number, a vector, or a string written with
+      #   <tt>:</tt>, <tt>x</tt> or <tt>/</tt> between the two sides
+      # @return [Float, nil]
+      # @raise [ArgumentError] if the value isn't a usable ratio
+      def parse(value)
+        return if value.nil?
+
+        ratio = coerce(value)
+        unless ratio.is_a?(Float) && ratio.positive? && ratio.finite?
+          raise ArgumentError, "invalid ratio: #{value.inspect}"
+        end
+
+        ratio
+      end
+
+      private
+
+      def coerce(value)
+        case value
+        when Numeric then value.to_f
+        when Vector2d then value.x.to_f / value.y
+        when String then value.split(%r{[:x/]}).map(&:to_f).reduce(:/)
+        end
+      end
+    end
+  end
+end

data/lib/dynamic_image/routing.rb

@@ -3,12 +3,23 @@
 module DynamicImage
   # = DynamicImage Routing
   #
-  # Extends +ActionDispatch::Routing::Mapper+ and provides a shortcut for
-  # defining routes for +DynamicImage::Controller+.
+  # Extends +ActionDispatch::Routing::Mapper+ and provides a shortcut for defining routes for
+  # +DynamicImage::Controller+.
   module Routing
-    # Declares an image resource.
+    # Declares an image resource, routing +show+ along with the +uncropped+, +original+ and +download+ member actions.
     #
+    # The default path includes the digest and an optional size. Pass +:path+ to change it if the resource collides
+    # with a directory in +public+.
+    #
+    # @param resource_name [Symbol, String] the resource
+    # @param options [Hash] options passed to +resources+, merged over the defaults
+    # @return [void]
+    #
+    # @example
     #   image_resources :avatars
+    #
+    # @example Keeping clear of public/images
+    #   image_resources :images, path: "dynamic_images/:digest(/:size)"
     def image_resources(resource_name, options = {})
       options = {
         path: "#{resource_name}/:digest(/:size)",