dynamic_image 3.0.9 → 3.1.0

data/lib/dynamic_image/helper/formats.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module DynamicImage
+  module Helper
+    # = DynamicImage Helper Formats
+    #
+    # Resolves the <tt>format:</tt> option the helpers in {DynamicImage::Helper} pass to the router.
+    #
+    # A symbol forces that format. An array, or nothing at all, is negotiated against the image. The default list
+    # depends on where the view is rendered: {DynamicImage.mailer_formats} in a mailer,
+    # {DynamicImage.default_formats} everywhere else.
+    #
+    # The +original+ and +download+ actions serve the stored file untouched, so they always get the record's own
+    # format. Negotiating one would put an extension on the URL that the response doesn't match.
+    #
+    # @see DynamicImage::FormatNegotiator
+    module Formats
+      private
+
+      def dynamic_image_format(record, format, action = nil)
+        return stored_format_for_image(record) if raw_action?(action)
+        return format unless format.nil? || format.is_a?(Array)
+
+        negotiated_format_for_image(record, format || accepted_image_formats)
+      end
+
+      def raw_action?(action)
+        %w[original download].include?(action.to_s)
+      end
+
+      def stored_format_for_image(record)
+        mime_format(DynamicImage::Format.content_type(record.content_type))
+      end
+
+      def negotiated_format_for_image(record, accepted)
+        mime_format(DynamicImage::FormatNegotiator.new(record)
+                                                  .negotiate(accepted))
+      end
+
+      def mime_format(format)
+        format.mime_type.to_sym
+      end
+
+      def accepted_image_formats
+        if mailer_view?
+          DynamicImage.mailer_formats
+        else
+          DynamicImage.default_formats
+        end
+      end
+
+      def mailer_view?
+        defined?(ActionMailer::Base) && controller.is_a?(ActionMailer::Base)
+      end
+    end
+  end
+end

data/lib/dynamic_image/helper/pictures.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module DynamicImage
+  module Helper
+    # = DynamicImage Helper Pictures
+    #
+    # Renders responsive images: a <tt>picture</tt> element with a WebP <tt>source</tt> covering a range of widths,
+    # and an <tt>img</tt> fallback in a format everything understands.
+    #
+    # These helpers take an optional +ratio+ instead of a +size+, leaving the width to the browser.
+    # {DynamicImage::Helper#dynamic_image_tag} renders at a size you pick; these render across a range of widths.
+    #
+    # @see DynamicImage::Picture
+    # @see DynamicImage::Breakpoints
+    module Pictures
+      # Returns a {DynamicImage::Picture} for the record, which is what the tag helpers render.
+      #
+      # @param record_or_array [DynamicImage::Model, Array] the record, or an array of records for a nested route
+      # @param options [Hash] sizing and routing options, as taken by {DynamicImage::Picture#initialize}
+      # @return [DynamicImage::Picture]
+      #
+      # @example
+      #   picture = dynamic_picture(image, ratio: "16:9")
+      #   picture.srcset  # => "/images/… 420w, /images/… 590w, …"
+      #   picture.sources # => [{ type: "image/webp", srcset: "…" }]
+      def dynamic_picture(record_or_array, options = {})
+        DynamicImage::Picture.new(self, record_or_array, picture_options(options.symbolize_keys))
+      end
+
+      # Renders a responsive <tt>picture</tt> element.
+      #
+      # The <tt>img</tt> carries the +width+ and +height+ of the fallback, which needn't match whichever candidate is
+      # chosen.
+      #
+      # Any other options are passed on to {DynamicImage::Helper#dynamic_image_tag}.
+      #
+      # @param record_or_array [DynamicImage::Model, Array] the record, or an array of records for a nested route
+      # @param options [Hash] sizing options, routing options and HTML attributes
+      # @option options [Numeric, Vector2d, String] :ratio The aspect ratio to crop to. Implies cropping.
+      # @option options [String] :sizes The +sizes+ attribute, telling the browser how large the image will be
+      #   rendered.
+      # @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 <tt>img</tt>, overriding
+      #   {DynamicImage.picture_fallback_width}
+      # @return [String] the picture element
+      #
+      # @example
+      #   dynamic_picture_tag(image, sizes: "50vw", alt: "A kitten")
+      #   dynamic_picture_tag(image, ratio: "16:9", sizes: "50vw")
+      def dynamic_picture_tag(record_or_array, options = {})
+        options = options.symbolize_keys
+        picture = dynamic_picture(record_or_array, options)
+        source = picture_source_tag(picture) unless picture.sources.empty?
+        image = picture_fallback_tag(record_or_array, picture, options)
+
+        tag.picture { safe_join([source, image].compact) }
+      end
+
+      # Renders a single <tt>source</tt> element, for composing a <tt>picture</tt> by hand.
+      #
+      # Use it for different crops per media query: several sources, each with its own crop and query. The browser
+      # takes the first one whose +media+ matches and whose +type+ it supports, so put the specific queries first
+      # and the unconditional one last.
+      #
+      # @param record_or_array [DynamicImage::Model, Array] the record, or an array of records for a nested route
+      # @param options [Hash] sizing and routing options
+      # @option options [String] :media The media query this source answers
+      # @option options [Symbol, Array<Symbol>] :format The format to render in. A symbol forces that format, an
+      #   array is negotiated. Defaults to WebP.
+      # @return [String, nil] the source element
+      #
+      # @example Different crops per media query
+      #   <picture>
+      #     <%= dynamic_picture_source_tag(image, ratio: "21:9",
+      #                                    media: "(min-width: 1000px)") %>
+      #     <%= dynamic_picture_source_tag(image, ratio: "1:1") %>
+      #     <%= dynamic_image_tag(image, size: "1200x1200", crop: true) %>
+      #   </picture>
+      #
+      # @example A source for browsers without WebP
+      #   dynamic_picture_source_tag(image, ratio: "21:9",
+      #                              format: DynamicImage::COMPATIBLE_FORMATS)
+      def dynamic_picture_source_tag(record_or_array, options = {})
+        options = options.symbolize_keys
+
+        picture_source_tag(dynamic_picture(record_or_array, options), options[:media])
+      end
+
+      private
+
+      def picture_source_tag(picture, media = nil)
+        srcset = picture.srcset
+        return unless srcset
+
+        tag.source(type: picture.type, srcset:, sizes: picture.sizes, media:)
+      end
+
+      def picture_fallback_tag(record_or_array, picture, options)
+        dynamic_image_tag(
+          record_or_array,
+          options.except(*DynamicImage::Picture::OPTIONS, :media)
+                 .merge(img_srcset_attributes(picture))
+                 .merge(size: picture.fallback_size,
+                        crop: picture.crop?,
+                        format: mime_format(picture.fallback_format))
+        )
+      end
+
+      # The candidates ride on the img itself when no source carries them.
+      def img_srcset_attributes(picture)
+        return {} unless picture.sources.empty?
+
+        { srcset: picture.srcset, sizes: picture.sizes }
+      end
+
+      # Passes on only the options the picture and the router understand.
+      def picture_options(options)
+        options.slice(*DynamicImage::Picture::OPTIONS, *allowed_dynamic_image_url_options)
+      end
+    end
+  end
+end

data/lib/dynamic_image/helper.rb

@@ -1,38 +1,62 @@
 # frozen_string_literal: true
 
+require "dynamic_image/helper/formats"
+require "dynamic_image/helper/pictures"
+
 module DynamicImage
   # = DynamicImage Helper
   #
-  # Provides helper methods for rendering and linking to images.
+  # Helper methods for rendering and linking to images.
+  #
+  # Every URL is signed with an HMAC digest of the action, the record id and the size, and the controller rejects
+  # anything that doesn't match. URLs can only be built server-side.
+  #
+  # +_path+ returns a relative path and +_url+ an absolute one. +_tag+ renders an image tag, and is available for
+  # +dynamic_image+ and +uncropped_dynamic_image+ only. +original+ and +download+ point at the stored file, which is
+  # never rendered.
+  #
+  # @see DynamicImage::ImageSizing for how sizes are calculated
+  # @see DynamicImage::Helper::Formats for how the format is chosen
+  # @see DynamicImage::Helper::Pictures for responsive images
   module Helper
-    # Returns the path for a DynamicImage::Model record.
-    # Takes the same options as +dynamic_image_url+
+    include DynamicImage::Helper::Formats
+    include DynamicImage::Helper::Pictures
+
+    # Returns the path for a {DynamicImage::Model} record. Takes the same options as {#dynamic_image_url}.
+    #
+    # @param record_or_array [DynamicImage::Model, Array] the record, or an array of records for a nested route
+    # @param options [Hash] sizing and routing options
+    # @return [String]
     def dynamic_image_path(record_or_array, options = {})
       dynamic_image_url(record_or_array, { routing_type: :path }.merge(options))
     end
 
-    # Returns an HTML image tag for the record. If no size is given, it will
-    # render at the original size.
+    # Returns an HTML image tag for the record, with +width+ and +height+ set to the rendered size. Without a
+    # size, it renders at the original size.
     #
-    # ==== Options
-    # * <tt>:alt</tt>: If no alt text is given, it will default to the
-    #   filename of the uploaded image.
+    # See {#dynamic_image_url} for sizing and cropping. Options supported by +polymorphic_url+ are passed to the
+    # router, and any others are added as HTML attributes.
     #
-    # See +dynamic_image_url+ for info on how to size and cropping. Options
-    # supported by +polymorphic_url+ will be passed to the router. Any other
-    # options will be added as HTML attributes.
+    # Unless an +alt+ option is given, the alt text is resolved from {DynamicImage::Model#alt_text}.
+    # Pass <tt>alt: ""</tt> to mark an image as decorative.
     #
-    # ==== Examples
+    # @param record_or_array [DynamicImage::Model, Array] the record, or an array of records for a nested route
+    # @param options [Hash] sizing options, routing options and HTML attributes
+    # @return [String]
     #
+    # @example
     #   image = Image.find(params[:id])
+    #
     #   dynamic_image_tag(image)
-    #   # => <img height="200" src="..." width="320" />
-    #   dynamic_image_tag(image, size: "100x100", alt="Avatar")
-    #   # => <img alt="Avatar" height="62" src="..." width="100" />
+    #   # => <img src="..." width="320" height="200" />
+    #
+    #   dynamic_image_tag(image, size: "100x100", alt: "Avatar")
+    #   # => <img alt="Avatar" src="..." width="100" height="62" />
     def dynamic_image_tag(record_or_array, options = {})
+      record = extract_dynamic_image_record(record_or_array)
       size = fit_size!(record_or_array, options)
       url_options = options.extract!(*allowed_dynamic_image_url_options)
-      html_options = { size: }.merge(options)
+      html_options = { size:, alt: record.alt_text }.merge(options)
 
       image_tag(dynamic_image_path_with_size(record_or_array,
                                              size,
@@ -40,26 +64,33 @@ module DynamicImage
                 html_options)
     end
 
-    # Returns the URL for a DynamicImage::Model record.
-    #
-    # ==== Options
+    # Returns the URL for a {DynamicImage::Model} record.
     #
-    # * <tt>:size</tt> - Desired image size, supplied as "{width}x{height}".
-    #   The image will be scaled to fit. A partial size like "100x" or "x100"
-    #   can be given, if you want a fixed width or height.
-    # * <tt>:crop</tt> - If true, the image will be cropped to the given size.
-    # * <tt>:upscale</tt> - By default, DynamicImage only scale images down,
-    #   never up. Pass <tt>upscale: true</tt> to force upscaling.
+    # @param record_or_array [DynamicImage::Model, Array] the record, or an array of records for a nested route
+    # @param options [Hash] sizing and routing options
+    # @option options [String] :size Desired image size, as <tt>"{width}x{height}"</tt>. The image is scaled to fit. A
+    #   partial size like <tt>"100x"</tt> or <tt>"x100"</tt> can be given for a fixed width or height.
+    # @option options [Boolean] :crop Crop the image to the given size instead of fitting it. Both dimensions are
+    #   required.
+    # @option options [Boolean] :upscale By default images are only scaled down, never up. Pass true to force
+    #   upscaling.
+    # @option options [Symbol, Array<Symbol>] :format Render in a different format. A symbol forces that format,
+    #   an array is negotiated against the image by {DynamicImage::FormatNegotiator}. Defaults to
+    #   {DynamicImage.default_formats}, or {DynamicImage.mailer_formats} in a mailer view.
+    # @return [String]
+    # @raise [DynamicImage::Errors::InvalidSizeOptions] if <tt>crop: true</tt> is given without both dimensions
     #
     # Any options supported by +polymorphic_url+ are also accepted.
     #
-    # ==== Examples
-    #
+    # @example
     #   image = Image.find(params[:id])
+    #
     #   dynamic_image_url(image)
     #   # => "http://example.com/images/96...d1/300x187/1-2014062020...00.jpg"
+    #
     #   dynamic_image_url(image, size: '100x100')
     #   # => "http://example.com/images/72...c2/100x62/1-2014062020...00.jpg"
+    #
     #   dynamic_image_url(image, size: '100x100', crop: true)
     #   # => "http://example.com/images/a4...6b/100x100/1-2014062020...00.jpg"
     def dynamic_image_url(record_or_array, options = {})
@@ -67,46 +98,68 @@ module DynamicImage
       dynamic_image_url_with_size(record_or_array, size, options)
     end
 
-    # Returns a path to the original uploaded file for download,
-    # without any processing applied. Sizing options are not
-    # supported.
+    # Returns a path to the original uploaded file, served as an attachment so the browser downloads it. The file
+    # is not processed, and sizing options are ignored. The URL carries the stored format's extension, and
+    # +:format+ has no effect.
+    #
+    # @param record_or_array [DynamicImage::Model, Array] the record
+    # @param options [Hash] routing options
+    # @return [String]
     def download_dynamic_image_path(record_or_array, options = {})
       dynamic_image_path(record_or_array, { action: :download }.merge(options))
     end
 
-    # Returns a URL to the original uploaded file for download,
-    # without any processing applied. Sizing options are not
-    # supported.
+    # Same as {#download_dynamic_image_path}, but returns an absolute URL.
+    #
+    # @param record_or_array [DynamicImage::Model, Array] the record
+    # @param options [Hash] routing options
+    # @return [String]
     def download_dynamic_image_url(record_or_array, options = {})
       dynamic_image_url(record_or_array, { action: :download }.merge(options))
     end
 
-    # Returns a path to the original uploaded file, without any processing
-    # applied. Sizing options are not supported.
+    # Returns a path to the original uploaded file, exactly as it was uploaded. The file is not processed, and
+    # sizing options are ignored. The URL carries the stored format's extension, and +:format+ has no effect.
+    #
+    # @param record_or_array [DynamicImage::Model, Array] the record
+    # @param options [Hash] routing options
+    # @return [String]
     def original_dynamic_image_path(record_or_array, options = {})
       dynamic_image_path(record_or_array, { action: :original }.merge(options))
     end
 
-    # Returns a URL to the original uploaded file, without any processing
-    # applied. Sizing options are not supported.
+    # Same as {#original_dynamic_image_path}, but returns an absolute URL.
+    #
+    # @param record_or_array [DynamicImage::Model, Array] the record
+    # @param options [Hash] routing options
+    # @return [String]
     def original_dynamic_image_url(record_or_array, options = {})
       dynamic_image_url(record_or_array, { action: :original }.merge(options))
     end
 
-    # Same as +dynamic_image_path+, but points to an image with any
-    # pre-cropping disabled.
+    # Same as {#dynamic_image_path}, but points to an image with any pre-cropping disabled.
+    #
+    # @param record_or_array [DynamicImage::Model, Array] the record
+    # @param options [Hash] sizing and routing options
+    # @return [String]
     def uncropped_dynamic_image_path(record_or_array, options = {})
       dynamic_image_path(record_or_array, { action: :uncropped }.merge(options))
     end
 
-    # Same as +dynamic_image_tag+, but renders an image with any
-    # pre-cropping disabled.
+    # Same as {#dynamic_image_tag}, but renders an image with any pre-cropping disabled.
+    #
+    # @param record_or_array [DynamicImage::Model, Array] the record
+    # @param options [Hash] sizing options, routing options and HTML attributes
+    # @return [String]
     def uncropped_dynamic_image_tag(record_or_array, options = {})
       dynamic_image_tag(record_or_array, { action: :uncropped }.merge(options))
     end
 
-    # Same as +dynamic_image_url+, but points to an image with any
-    # pre-cropping disabled.
+    # Same as {#dynamic_image_url}, but points to an image with any pre-cropping disabled.
+    #
+    # @param record_or_array [DynamicImage::Model, Array] the record
+    # @param options [Hash] sizing and routing options
+    # @return [String]
     def uncropped_dynamic_image_url(record_or_array, options = {})
       dynamic_image_url(record_or_array, { action: :uncropped }.merge(options))
     end
@@ -119,10 +172,6 @@ module DynamicImage
          action routing_type ]
     end
 
-    def default_format_for_image(record)
-      Mime::Type.lookup(record.safe_content_type).to_sym
-    end
-
     def dynamic_image_digest(record, action, size = nil)
       key = [action || "show", record.id, size].compact.join("-")
       DynamicImage.digest_verifier.generate(key)
@@ -136,12 +185,10 @@ module DynamicImage
 
     def dynamic_image_url_with_size(record_or_array, size = nil, options = {})
       record = extract_dynamic_image_record(record_or_array)
-      options = {
-        routing_type: :url,
-        action: nil,
-        format: default_format_for_image(record),
-        size:
-      }.merge(options)
+      options = { routing_type: :url, action: nil, size: }.merge(options)
+      options[:routing_type] = :url if mailer_view?
+      options[:format] = dynamic_image_format(record, options[:format],
+                                              options[:action])
       options[:digest] =
         dynamic_image_digest(record, options[:action], options[:size])
       polymorphic_url(record_or_array, options)
@@ -156,13 +203,6 @@ module DynamicImage
       end
     end
 
-    def filename_to_alt(str)
-      File.basename(str, ".*")
-          .sub(/-[[:xdigit:]]{32,64}\z/, "")
-          .tr("-_", " ")
-          .capitalize
-    end
-
     def fit_size!(record_or_array, options)
       record = extract_dynamic_image_record(record_or_array)
       action = options[:action].try(:to_s)

data/lib/dynamic_image/image_processor/colors.rb

@@ -4,10 +4,8 @@ module DynamicImage
   class ImageProcessor
     # = ImageProcessor::Colors
     #
-    # Performs the necessary profile conversions on the image. All
-    # images are converted to the sRGB colorspace using either the
-    # embedded profile, or the built-in generic profile. Grayscale
-    # images are converted back to grayscale after processing.
+    # Converts color profiles. All images are converted to the sRGB colorspace using either the embedded profile
+    # or the built-in generic one. Grayscale images are converted back to grayscale after processing.
     module Colors
       private
 
@@ -22,9 +20,7 @@ module DynamicImage
       end
 
       def screen_profile(image)
-        if !icc_profile?(image) && %i[rgb b-w].include?(image.interpretation)
-          return image
-        end
+        return image if !icc_profile?(image) && %i[rgb b-w].include?(image.interpretation)
 
         target_space = image.interpretation == :"b-w" ? "b-w" : "srgb"
         icc_transform_srgb(image).colourspace(target_space)

data/lib/dynamic_image/image_processor/frames.rb

@@ -2,13 +2,22 @@
 
 module DynamicImage
   class ImageProcessor
+    # = ImageProcessor::Frames
+    #
+    # Support for animated GIF and WebP images, which vips represents as a single tall image with a +page-height+ of
+    # one frame. Operations are applied to each frame and the results reassembled.
     module Frames
       # Extracts a single frame from a multi-frame image.
+      #
+      # @param index [Integer] the frame to extract, zero based
+      # @return [DynamicImage::ImageProcessor] a new processor
       def frame(index)
         apply extract_frame(index)
       end
 
-      # Returns the number of frames.
+      # Returns the number of frames. Still images have one.
+      #
+      # @return [Integer]
       def frame_count
         image.get("height") / size.y
       end

data/lib/dynamic_image/image_processor/transform.rb

@@ -2,8 +2,16 @@
 
 module DynamicImage
   class ImageProcessor
+    # = ImageProcessor::Transform
+    #
+    # Cropping, resizing and rotation. Each operation is applied to every frame of an animated image.
     module Transform
-      # Crops the image
+      # Crops the image.
+      #
+      # @param crop_size [Vector2d] the size of the crop
+      # @param crop_start [Vector2d] its top left corner
+      # @return [DynamicImage::ImageProcessor] a new processor
+      # @raise [DynamicImage::Errors::InvalidTransformation] if the crop falls outside the image
       def crop(crop_size, crop_start)
         return self if crop_start == Vector2d(0, 0) && crop_size == size
 
@@ -17,7 +25,10 @@ module DynamicImage
         end
       end
 
-      # Resize the image to a new size.
+      # Resize the image to a new size. The aspect ratio is not preserved; crop first if that matters.
+      #
+      # @param new_size [Vector2d] the size to resize to
+      # @return [DynamicImage::ImageProcessor] a new processor
       def resize(new_size)
         new_size = Vector2d(new_size)
         apply image.thumbnail_image(new_size.x.to_i,
@@ -27,6 +38,10 @@ module DynamicImage
       end
 
       # Rotates the image. The rotation must be a multiple of 90 degrees.
+      #
+      # @param degrees [Integer] the angle
+      # @return [DynamicImage::ImageProcessor] a new processor
+      # @raise [DynamicImage::Errors::InvalidTransformation] if the angle isn't a multiple of 90
       def rotate(degrees)
         degrees = degrees.to_i % 360
         return self if degrees.zero?

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