dynamic_image 3.0.9 → 3.1.0

data/lib/dynamic_image/image_sizing.rb

@@ -3,26 +3,37 @@
 module DynamicImage
   # = DynamicImage Image Sizing
   #
-  # Calculates cropping and fitting for image sizes.
+  # Calculates cropping and fitting for image sizes. The helpers use it to work out the dimensions of a rendered
+  # image, and it can be used on its own when you need the size without rendering anything: reserving space in a
+  # layout, filling in <tt>og:image:width</tt>, or laying out a PDF.
+  #
+  # @example
+  #   sizing = DynamicImage::ImageSizing.new(image)
+  #   sizing.fit("400x400") # => Vector2d(400.0, 250.0)
   class ImageSizing
+    # @param record [DynamicImage::Model] the image
+    # @param options [Hash]
+    # @option options [Boolean] :uncropped Ignore any crop stored on the record and size against the original image
     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.
+    # Calculates crop geometry. The given vector is scaled to match the image size, since cropping happens before
+    # resizing.
+    #
+    # The crop is positioned to keep the record's crop gravity as close to the center as possible, clamped to the
+    # bounds of the image.
     #
-    # ==== Example
+    # @param ratio_vector [Vector2d] the aspect ratio to crop to
+    # @return [Array(Vector2d, Vector2d)] the crop size and crop start
     #
+    # @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
@@ -36,18 +47,41 @@ module DynamicImage
       [crop_size, (start + crop_start)]
     end
 
-    # Adjusts +fit_size+ to fit the image dimensions.
-    # Any dimension set to zero will be ignored.
+    # Returns the widest the image can be rendered at, in pixels.
+    #
+    # Without a ratio this is the image's own width. With one it is the width of the largest crop matching that
+    # ratio.
+    #
+    # @param ratio [Numeric, Vector2d, String, nil] the aspect ratio, in any form {DynamicImage::Ratio} understands
+    # @return [Integer]
     #
-    # ==== Options
+    # @example
+    #   image = Image.find(params[:id]) # 320x200 image
+    #   sizing = DynamicImage::ImageSizing.new(image)
     #
-    # * <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.
+    #   sizing.available_width           # => 320
+    #   sizing.available_width(16.0 / 9) # => 320
+    #   sizing.available_width(9.0 / 16) # => 113
+    def available_width(ratio = nil)
+      ratio = DynamicImage::Ratio.parse(ratio)
+      return size.x.floor unless ratio
+
+      crop_geometry(vector(ratio, 1)).first.x.floor
+    end
+
+    # Adjusts +fit_size+ to fit the image dimensions. Any dimension set to zero will be ignored.
     #
-    # ==== Examples
+    # @param fit_size [Vector2d, String] the size to fit within, either a vector or a <tt>"{width}x{height}"</tt>
+    #   string. Either dimension may be omitted for a fixed width or height.
+    # @param options [Hash]
+    # @option options [Boolean] :crop Don't keep aspect ratio. This will allow the image to be cropped to the
+    #   requested size.
+    # @option options [Boolean] :upscale Don't limit to the size of the image. Images smaller than the given size will
+    #   be scaled up.
+    # @return [Vector2d] the resulting size
+    # @raise [DynamicImage::Errors::InvalidSizeOptions] if <tt>crop: true</tt> is given and either dimension is zero
     #
+    # @example
     #   image = Image.find(params[:id]) # 320x200 image
     #   sizing = DynamicImage::ImageSizing.new(image)
     #
@@ -62,7 +96,6 @@ module DynamicImage
     #
     #   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]
@@ -97,9 +130,8 @@ module DynamicImage
       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+.
+    # 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)

data/lib/dynamic_image/metadata.rb

@@ -4,13 +4,24 @@ module DynamicImage
   # = DynamicImage Metadata
   #
   # Parses metadata from an image. Accepts a Pathname, IO, or binary string.
+  #
+  # Every reader returns nil for data that isn't a readable image.
+  #
+  # @example
+  #   metadata = DynamicImage::Metadata.new(Pathname.new("image.jpg"))
+  #   metadata.valid?       # => true
+  #   metadata.content_type # => "image/jpeg"
+  #   metadata.dimensions   # => Vector2d(320, 200)
   class Metadata
+    # @param data [Pathname, IO, String] the image, as a path, an open file or a binary string
     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".
+    # Returns the color space of the image as a string. The result will be one of the following: "rgb", "cmyk",
+    # "gray".
+    #
+    # @return [String, nil]
     def colorspace
       return unless valid?
 
@@ -25,30 +36,61 @@ module DynamicImage
     end
 
     # Returns the content type of the image.
+    #
+    # @return [String, nil]
     def content_type
       reader.format.content_type if valid?
     end
 
+    # Returns the name of the detected format.
+    #
+    # @return [String, nil] the format name, such as "JPEG"
     def format
       reader.format.name if valid?
     end
 
-    # Returns the dimensions of the image as a vector.
+    # Returns the dimensions of the image as a vector. EXIF rotation is applied, so these are the dimensions the
+    # image has once normalized.
+    #
+    # @return [Vector2d, nil]
     def dimensions
       Vector2d.new(metadata[:width], metadata[:height]) if valid?
     end
 
     # Returns the width of the image.
+    #
+    # @return [Integer, nil] the width in pixels
     def width
       metadata[:width] if valid?
     end
 
     # Returns the height of the image.
+    #
+    # @return [Integer, nil] the height in pixels
     def height
       metadata[:height] if valid?
     end
 
-    # Returns true if the image is valid.
+    # Returns the number of frames. Animated formats can have more than one; everything else has a single frame.
+    #
+    # @return [Integer, nil] the number of frames
+    def frame_count
+      metadata[:frame_count] if valid?
+    end
+
+    # Returns true if the image has an alpha channel.
+    #
+    # This is the presence of the channel, not of actual transparency: an image can carry a fully opaque alpha
+    # channel. Reading it costs nothing, where scanning the channel for transparency would mean decoding every pixel.
+    #
+    # @return [Boolean, nil] true if the image has an alpha channel
+    def alpha?
+      metadata[:alpha] if valid?
+    end
+
+    # Returns true if the data is a readable image in a supported format.
+    #
+    # @return [Boolean]
     def valid?
       @data && reader.valid_header? && metadata != :invalid
     end
@@ -67,11 +109,20 @@ module DynamicImage
       image = reader.read
       width, height = dimensions_from(image)
       width, height = height, width if rotated?(image)
-      { width:, height:, colorspace: image.get("interpretation") }
+      { width:, height:,
+        colorspace: image.get("interpretation"),
+        frame_count: frame_count_from(image),
+        alpha: image.has_alpha? }
     rescue Vips::Error
       :invalid
     end
 
+    def frame_count_from(image)
+      return 1 unless image.get_fields.include?("n-pages")
+
+      image.get("n-pages")
+    end
+
     def dimensions_from(image)
       width = image.get("width")
       height = if image.get_fields.include?("page-height")

data/lib/dynamic_image/model/dimensions.rb

@@ -4,17 +4,17 @@ module DynamicImage
   module Model
     # = DynamicImage Model Dimensions
     #
+    # Vector accessors over the +real_*+ and +crop_*+ columns.
+    #
+    # +real_size+ is the size of the stored image. +size+ is the size after cropping, or +real_size+ when no crop
+    # is set.
     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.
+      # Returns the crop gravity, the focal point kept as close to the center as possible when cropping.
       #
-      # It is relative to 0,0 on the original image.
+      # The coordinates are relative to 0,0 on the original image. Unless set explicitly, the gravity is the center
+      # of the cropped image.
       #
-      # Unless crop_gravity has been explicitely set, it defaults to
-      # the center of the cropped image.
+      # @return [Vector2d, nil]
       def crop_gravity
         if crop_gravity?
           vector(crop_gravity_x, crop_gravity_y)
@@ -25,22 +25,30 @@ module DynamicImage
         end
       end
 
-      # Returns true if crop gravity has been explicitely set.
+      # Returns true if the crop gravity has been set explicitly.
+      #
+      # @return [Boolean]
       def crop_gravity?
         crop_gravity_x.present? && crop_gravity_y.present?
       end
 
       # Returns the crop size, or nil if no cropping is applied.
+      #
+      # @return [Vector2d, nil]
       def crop_size
         vector(crop_width, crop_height) if crop_size?
       end
 
       # Returns true if crop size has been set.
+      #
+      # @return [Boolean]
       def crop_size?
         crop_width? && crop_height?
       end
 
       # Returns the crop start if set, or Vector2d(0, 0) if not.
+      #
+      # @return [Vector2d] the top left corner of the crop
       def crop_start
         if crop_start?
           vector(crop_start_x, crop_start_y)
@@ -50,32 +58,43 @@ module DynamicImage
       end
 
       # Returns true if crop start has been set.
+      #
+      # @return [Boolean]
       def crop_start?
         crop_start_x.present? && crop_start_y.present?
       end
 
       # Returns true if the image is cropped.
+      #
+      # @return [Boolean]
       def cropped?
         crop_size? && real_size? && crop_size != real_size
       end
 
       # Returns the real size of the image, without any cropping applied.
+      #
+      # @return [Vector2d, nil] the size of the stored image
       def real_size
         vector(real_width, real_height) if real_size?
       end
 
-      # Returns true if the size has been set.
+      # Returns true if the real size has been set.
+      #
+      # @return [Boolean]
       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.
+      # Returns the cropped size, or the real size if the image isn't cropped.
+      #
+      # @return [Vector2d, nil] the visible size of the image
       def size
         crop_size || real_size
       end
 
-      # Returns true if the image has size set.
+      # Returns true if the image has a size.
+      #
+      # @return [Boolean]
       def size?
         size ? true : false
       end

data/lib/dynamic_image/model/transformations.rb

@@ -4,20 +4,32 @@ module DynamicImage
   module Model
     # = DynamicImage Model Transformations
     #
+    # Transformations that rewrite the stored file. Per-request processing never touches it.
+    #
+    # Both methods replace the data and update the stored dimensions, adjusting the crop to match. Neither saves
+    # the record.
     module Transformations
-      # Resizes the image
+      # Resizes the image, replacing the stored file with a smaller one. The crop is scaled along with it.
+      #
+      # @param max_size [Vector2d] the size to scale down to
+      # @return [self]
       def resize(max_size)
         transform_image do |image|
-          new_size = real_size.constrain_both(max_size)
-          scale = new_size.x / real_size.x
-          crop_attributes.each do |attr|
-            self[attr] = self[attr] * scale if self[attr]
-          end
-          image.resize(new_size)
+          resized = image.resize(real_size.constrain_both(max_size))
+          scale_crop(resized.size)
+          resized
         end
       end
 
-      # Rotates the image
+      # Rotates the image, taking the crop and crop gravity with it.
+      #
+      # @param degrees [Integer] the angle, which must be a multiple of 90. Rotating by 0 is a no-op.
+      # @return [self]
+      # @raise [DynamicImage::Errors::InvalidTransformation] if the angle isn't a multiple of 90
+      #
+      # @example
+      #   image.rotate(90)
+      #   image.save
       def rotate(degrees = 90)
         degrees = degrees.to_i % 360
 
@@ -36,9 +48,33 @@ module DynamicImage
 
       private
 
-      def crop_attributes
-        %i[crop_width crop_height crop_start_x crop_start_y
-           crop_gravity_x crop_gravity_y]
+      def scale_crop(new_size)
+        scale = new_size.to_f_vector / real_size
+
+        scale_crop_start(scale, new_size)
+        scale_crop_size(scale, new_size)
+        scale_crop_gravity(scale, new_size)
+      end
+
+      def scale_crop_start(scale, new_size)
+        return unless crop_start?
+
+        self.crop_start_x, self.crop_start_y =
+          (crop_start * scale).floor.clamp(0, new_size - 1).to_a
+      end
+
+      def scale_crop_size(scale, new_size)
+        return unless crop_size?
+
+        self.crop_width, self.crop_height =
+          (crop_size * scale).round.clamp(1, new_size - crop_start).to_a
+      end
+
+      def scale_crop_gravity(scale, new_size)
+        return unless crop_gravity?
+
+        self.crop_gravity_x, self.crop_gravity_y =
+          (crop_gravity * scale).round.clamp(1, new_size).to_a
       end
 
       def rotate_dimensions(width, height, degrees)

data/lib/dynamic_image/model/validations.rb

@@ -4,9 +4,10 @@ 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.
+    # Validates the image attributes. +DynamicImage::Model+ manages all of them, so these mostly enforce integrity.
+    #
+    # The two that can fail on ordinary input are the image itself, which is rejected if the data isn't readable in
+    # a supported format, and the crop, which has to fit within the image.
     module Validations
       extend ActiveSupport::Concern
 
@@ -30,9 +31,7 @@ module DynamicImage
                   length: { maximum: 255 }
 
         validates :real_width, :real_height,
-                  numericality: { greater_than: 0, only_integer: true }
-
-        validates :real_width, :real_height,
+                  presence: true,
                   numericality: { greater_than: 0, only_integer: true }
 
         validates :crop_width, :crop_height,
@@ -40,8 +39,10 @@ module DynamicImage
                   numericality: { greater_than: 0, only_integer: true },
                   allow_nil: true
 
-        validates :real_width, :real_height,
-                  presence: true
+        validates :crop_start_x, :crop_start_y,
+                  numericality: { greater_than_or_equal_to: 0,
+                                  only_integer: true },
+                  allow_nil: true
 
         validates :crop_width, presence: true, if: :crop_height?
         validates :crop_height, presence: true, if: :crop_width?
@@ -57,10 +58,16 @@ module DynamicImage
       end
 
       module ClassMethods
+        # Colorspaces an image is allowed to be in.
+        #
+        # @return [Array<String>] the colorspace names
         def allowed_colorspaces
           %w[rgb cmyk gray]
         end
 
+        # Content types an image is allowed to have, taken from the registered formats.
+        #
+        # @return [Array<String>]
         def allowed_content_types
           DynamicImage::Format.content_types
         end

data/lib/dynamic_image/model/variants.rb

@@ -4,9 +4,12 @@ module DynamicImage
   module Model
     # = DynamicImage Model Variants
     #
-    # Validates that all necessary attributes are valid. All of these are
-    # managed by +DynamicImage::Model+, so this is mostly for enforcing
-    # integrity.
+    # Associates the image with its cached renderings.
+    #
+    # Each processed size is stored as a {DynamicImage::Variant}, so cropping and resizing is done once. Variants
+    # are destroyed with the image, and cleared whenever its data changes.
+    #
+    # @see DynamicImage::ProcessedImage
     module Variants
       extend ActiveSupport::Concern
 

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
@@ -119,17 +147,13 @@ module DynamicImage
       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