dynamic_image 3.0.8 → 3.1.0

data/lib/dynamic_image/image_processor.rb

@@ -7,10 +7,17 @@ require "dynamic_image/image_processor/transform"
 module DynamicImage
   # = ImageProcessor
   #
-  # This is the image processing pipeline.
+  # The image processing pipeline.
   #
-  # ==== Example:
+  # Every operation returns a new processor instead of modifying the one it was called on, so operations chain.
+  # Images are converted to sRGB and EXIF rotation is applied when the processor is built, so the pipeline always
+  # starts from a normalized image.
   #
+  # @see DynamicImage::ImageProcessor::Colors
+  # @see DynamicImage::ImageProcessor::Frames
+  # @see DynamicImage::ImageProcessor::Transform
+  #
+  # @example
   #   DynamicImage::ImageProcessor
   #     .new(file)
   #     .crop(crop_start, crop_size)
@@ -22,8 +29,16 @@ module DynamicImage
     include DynamicImage::ImageProcessor::Frames
     include DynamicImage::ImageProcessor::Transform
 
+    # @!attribute [r] image
+    #   @return [Vips::Image]
+    # @!attribute [r] target_format
+    #   @return [DynamicImage::Format] the format it will be written in
     attr_reader :image, :target_format
 
+    # @param image [Vips::Image, Pathname, IO, String] the image, either an already loaded vips image or something
+    #   {DynamicImage::ImageReader} can read
+    # @param target_format [DynamicImage::Format, nil] the format to write in, defaulting to the format the image was
+    #   read from
     def initialize(image, target_format: nil)
       if image.is_a?(Vips::Image)
         @image = image
@@ -36,10 +51,14 @@ module DynamicImage
     end
 
     # Convert the image to a different format.
+    #
+    # Converting a multi-frame image to a format that doesn't support animation keeps the first frame.
+    #
+    # @param new_format [DynamicImage::Format, Symbol, String] the format to convert to
+    # @return [DynamicImage::ImageProcessor] a new processor
     def convert(new_format)
-      unless new_format.is_a?(DynamicImage::Format)
-        new_format = DynamicImage::Format.find(new_format)
-      end
+      new_format = DynamicImage::Format.find(new_format) unless new_format.is_a?(DynamicImage::Format)
+
       if frame_count > 1 && !new_format.animated?
         self.class.new(extract_frame(0), target_format: new_format)
       else
@@ -48,12 +67,17 @@ module DynamicImage
     end
 
     # Returns the image data as a binary string.
+    #
+    # @return [String] the encoded image
     def read
       image.write_to_buffer(target_format.extension,
                             **target_format.save_options)
     end
 
-    # Returns the image size as a Vector2d.
+    # Returns the image size as a Vector2d. For multi-frame images this is the size of a single frame, not of the
+    # filmstrip vips holds them in.
+    #
+    # @return [Vector2d]
     def size
       Vector2d.new(
         image.get("width"),
@@ -64,6 +88,9 @@ module DynamicImage
     end
 
     # Write the image to a file.
+    #
+    # @param path [String] the path to write to
+    # @return [void]
     def write(path)
       image.write_to_file(path, **target_format.save_options)
     end

data/lib/dynamic_image/image_reader.rb

@@ -1,17 +1,32 @@
 # frozen_string_literal: true
 
 module DynamicImage
+  # = DynamicImage Image Reader
+  #
+  # Reads an image into vips, identifying the format from the file header and not from anything the client claims.
+  # Accepts a Pathname, an IO object or a binary string.
+  #
+  # Animated formats are opened with all their frames.
   class ImageReader
-    HEADER_BYTES = 12
+    # Number of bytes needed to identify a format.
+    HEADER_BYTES = 32
 
+    # @param data [Pathname, IO, String] the image
     def initialize(data)
       @data = data
     end
 
+    # The format of the image, sniffed from its header.
+    #
+    # @return [DynamicImage::Format, nil] the format, if recognized
     def format
       DynamicImage::Format.sniff(file_header)
     end
 
+    # Reads the image.
+    #
+    # @return [Vips::Image]
+    # @raise [DynamicImage::Errors::InvalidHeader] if the data isn't in a recognized format
     def read
       raise DynamicImage::Errors::InvalidHeader unless valid_header?
 
@@ -23,6 +38,9 @@ module DynamicImage
       end
     end
 
+    # Returns true if the header belongs to a supported format.
+    #
+    # @return [Boolean]
     def valid_header?
       format ? true : false
     end

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)
@@ -76,7 +112,9 @@ module DynamicImage
 
       def transform_image(&block)
         read_image_metadata if data_changed?
-        self.data = block.call(DynamicImage::ImageProcessor.new(Pathname(data_file_path))).read
+        self.data = with_data_file do |path|
+          block.call(DynamicImage::ImageProcessor.new(path)).read
+        end
         read_image_metadata
         self
       end

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