dynamic_image 3.0.9 → 3.1.0

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,12 +101,16 @@ 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!
 
@@ -87,6 +119,8 @@ module DynamicImage
         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)",

data/lib/dynamic_image/schema.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module DynamicImage
+  # = DynamicImage Schema
+  #
+  # The database schema {DynamicImage::Model} expects on the table holding the image.
+  #
+  # DynamicImage doesn't own that table. Unlike +dynamic_image_variants+, which has a fixed name and an engine
+  # migration, the image table is created in the application by the +dynamic_image:resource+ generator, under
+  # whatever name the application picked, and there may be more than one. This is the single definition of what it
+  # should contain.
+  #
+  # @see DynamicImage::Model
+  module Schema
+    # The expected columns, in the order they should appear in a migration. Each is described by its migration type
+    # and whether it accepts +NULL+.
+    #
+    # +frame_count+ and +alpha+ are nullable. NULL means the image predates them being recorded, which is not the
+    # same as knowing the image is a still or opaque.
+    #
+    # @return [Hash{Symbol => Hash}]
+    ATTRIBUTES = {
+      content_hash: { type: :string, null: false },
+      content_type: { type: :string, null: false },
+      content_length: { type: :integer, null: false },
+      filename: { type: :string, null: false },
+      colorspace: { type: :string, null: false },
+      real_width: { type: :integer, null: false },
+      real_height: { type: :integer, null: false },
+      frame_count: { type: :integer, null: true },
+      alpha: { type: :boolean, null: true },
+      crop_width: { type: :integer, null: true },
+      crop_height: { type: :integer, null: true },
+      crop_start_x: { type: :integer, null: true },
+      crop_start_y: { type: :integer, null: true },
+      crop_gravity_x: { type: :integer, null: true },
+      crop_gravity_y: { type: :integer, null: true }
+    }.freeze
+
+    # The expected indexes.
+    #
+    # @return [Array<Hash>]
+    INDEXES = [
+      { columns: %i[content_hash], unique: false }
+    ].freeze
+  end
+end

data/lib/dynamic_image/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DynamicImage
-  VERSION = "3.0.9"
+  VERSION = "3.1.0"
 end

data/lib/dynamic_image.rb

@@ -4,22 +4,82 @@ require "dis"
 require "vector2d"
 require "vips"
 
+require "dynamic_image/backfill"
 require "dynamic_image/belongs_to"
+require "dynamic_image/breakpoints"
 require "dynamic_image/controller"
 require "dynamic_image/digest_verifier"
 require "dynamic_image/engine"
 require "dynamic_image/errors"
 require "dynamic_image/format"
+require "dynamic_image/format_negotiator"
 require "dynamic_image/helper"
 require "dynamic_image/image_processor"
 require "dynamic_image/image_reader"
 require "dynamic_image/image_sizing"
-require "dynamic_image/jobs"
 require "dynamic_image/metadata"
 require "dynamic_image/model"
+require "dynamic_image/picture"
+require "dynamic_image/picture/format_policy"
 require "dynamic_image/processed_image"
+require "dynamic_image/ratio"
 require "dynamic_image/routing"
+require "dynamic_image/schema"
 
+# A Rails engine for image uploads. Rather than creating a pre-defined set of images when a file is uploaded, it
+# stores the original file and generates images on demand. It handles cropping, resizing, format and colorspace
+# conversion, and stores each processed size as a variant.
+#
+# Include {DynamicImage::Model} in the model holding the image and {DynamicImage::Controller} in the controller
+# serving it, then declare the routes with {DynamicImage::Routing#image_resources}. Views render images through the
+# helpers in {DynamicImage::Helper}, which sign the URLs.
+#
+# Files are stored with Dis, and processing is done with libvips.
+#
+# @see DynamicImage::Model
+# @see DynamicImage::Controller
+# @see DynamicImage::Helper
+# @see DynamicImage::ImageSizing
+# @see DynamicImage::ProcessedImage
 module DynamicImage
+  # The formats anything that renders images will understand. Fallback images in a <tt>picture</tt> are negotiated
+  # from this list, and it is the default for {DynamicImage.mailer_formats}.
+  #
+  # @return [Array<Symbol>] the format names, most preferred first
+  COMPATIBLE_FORMATS = %i[jpeg png gif].freeze
+
+  # Verifies the HMAC digests embedded in image URLs. Set by the engine from the application's key generator, which
+  # derives it from <tt>secret_key_base</tt>.
+  #
+  # @return [DynamicImage::DigestVerifier]
   cattr_accessor :digest_verifier
+
+  # The formats a view accepts when it doesn't pass <tt>format:</tt>. Also decides what
+  # {DynamicImage::Model#safe_content_type} considers safe.
+  #
+  # @return [Array<Symbol>] the format names, most preferred first
+  mattr_accessor :default_formats, default: %i[jpeg png gif webp]
+
+  # The formats a mailer view accepts when it doesn't pass <tt>format:</tt>.
+  #
+  # @return [Array<Symbol>] the format names, most preferred first
+  mattr_accessor :mailer_formats, default: COMPATIBLE_FORMATS
+
+  # The breakpoints responsive images are rendered at. This can be a range, an array of explicit widths, or a single
+  # width.
+  #
+  # @return [Range, Array<Integer>, Integer]
+  # @see DynamicImage::Breakpoints
+  mattr_accessor :default_breakpoints, default: 320..3200
+
+  # The ratio between two breakpoints. Lower means a closer fit to what the browser needs, at the price of more
+  # variants to generate and store.
+  #
+  # @return [Float]
+  mattr_accessor :breakpoint_step, default: 1.4
+
+  # The width of the fallback image in a <tt>picture</tt> element.
+  #
+  # @return [Integer]
+  mattr_accessor :picture_fallback_width, default: 1200
 end

data/lib/rails/generators/dynamic_image/resource/USAGE

@@ -0,0 +1,17 @@
+Description:
+    Creates a DynamicImage resource: a model including
+    DynamicImage::Model, a controller including DynamicImage::Controller,
+    a migration with the columns DynamicImage needs, and an
+    image_resources route.
+
+    Additional attributes are passed through to the migration, so a
+    resource can carry fields of its own.
+
+Example:
+    bin/rails generate dynamic_image:resource image
+
+        creates an Image model, an ImagesController and a migration.
+
+    bin/rails generate dynamic_image:resource photo caption:string
+
+        adds a caption column to the migration.