imgix 3.1.1 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 93aa8838354b1565c1691c817c4ed212d76b3222
-  data.tar.gz: bc28c0311f08510f4fc4ff96c73774b59d83e59f
+  metadata.gz: 2888effee0dc9f00b05832a337fc22d08973703a
+  data.tar.gz: 0d55efe17b819635689e9e9a361339702ae2df73
 SHA512:
-  metadata.gz: e7e492f9c63a641a6c2dc6f3f86ef96008c965187ce5439448e878d37a0b825871672447b8f113eba1137c97353a358e7cc6a3be68b8720c5a37472bc5f4515f
-  data.tar.gz: b2b3799e866a64680842a6193d5ca1e0794ff5d918052c732bfe704de63bc9bb5b29a7e6f4f608fc5642344e01ee38b22990951273e16402ccd98022a1906252
+  metadata.gz: 6a4c006d3efb6e4e60552a7330e22632f40f57f8fee2a0b5ea845f354890a8cf1eb8c7594e5e6ca64fc933bcb2fbab6017c0b9f8da276657d25ce8b4abaf968e
+  data.tar.gz: 0127e8b6c7643b63e2d89437499493bf4d9eb1cf7fb7dd5392436e17a55e480f5e7a923064204f2490084b79339832ec6e9da85af4ccf6aaac03d192ac37d3a8

data/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [3.2.0](https://github.com/imgix/imgix-rb/compare/3.1.1...3.2.0) - November 15, 2019
+
+* feat: append variable qualities to dpr srcsets ([#58](https://github.com/imgix/imgix-rb/pull/58))
+* refactor: pass srcset modifiers through the `options` parameter ([#57](https://github.com/imgix/imgix-rb/pull/57))
+* feat: support defining a min and max width range ([#56](https://github.com/imgix/imgix-rb/pull/56))
+* feat: add ability to pass in custom widths ([#55](https://github.com/imgix/imgix-rb/pull/55))
+* feat: add ability to configure the srcset width tolerance ([#54](https://github.com/imgix/imgix-rb/pull/54))
+* style: drop redundant explicit return statements ([#52](https://github.com/imgix/imgix-rb/pull/52))
+
 ## [3.1.1](https://github.com/imgix/imgix-rb/compare/3.1.0...3.1.1) - July 28, 2019
 
 * fix: include dpr parameter when generating a DPR srcset ([#48](https://github.com/imgix/imgix-rb/pull/48))

data/README.md

@@ -2,7 +2,7 @@
 
 Official Ruby Gem for signing [imgix](http://imgix.com) URLs. Tested under 2.3.0, 2.2.4, 2.1.8, jruby-9.0.5.0, and rbx-2.11.
 
-[![Build Status](https://travis-ci.org/imgix/imgix-rb.png?branch=master)](https://travis-ci.org/imgix/imgix-rb)
+[![Build Status](https://travis-ci.org/imgix/imgix-rb.svg?branch=master)](https://travis-ci.org/imgix/imgix-rb)
 
 ## Installation
 
@@ -23,7 +23,7 @@ Or install it yourself as:
 
 ## Usage
 
-Simply initialize a client with a `:host` and your `:secure_url_token`. By default, HTTPS URLs are generated, but you can toggle that by passing `use_https: false`.
+Initialize a client with a `:host` and your `:secure_url_token`. By default, HTTPS URLs are generated, but you can toggle that by passing `use_https: false`.
 
 Call `Imgix::Client#path` with the resource path to get an `Imgix::Path` object back. You can then manipulate the path parameters, and call `Imgix#Path#to_url` when you're done.
 
@@ -68,6 +68,8 @@ https://your-subdomain.imgix.net/images/demo.png?w=7400&s=a5dd7dda1dbac613f0475f
 https://your-subdomain.imgix.net/images/demo.png?w=8192&s=9fbd257c53e770e345ce3412b64a3452 8192w
 ```
 
+### Fixed image rendering
+
 In cases where enough information is provided about an image's dimensions, `to_srcset` will instead build a `srcset` that will allow for an image to be served at different resolutions. The parameters taken into consideration when determining if an image is fixed-width are `w`, `h`, and `ar`. By invoking `to_srcset` with either a width **or** the height and aspect ratio (along with `fit=crop`, typically) provided, a different `srcset` will be generated for a fixed-size image instead.
 
 ```rb
@@ -89,6 +91,101 @@ https://your-subdomain.imgix.net/images/demo.png?h=800&ar=3%3A2&fit=crop&dpr=5&s
 
 For more information to better understand `srcset`, we highly recommend [Eric Portis' "Srcset and sizes" article](https://ericportis.com/posts/2014/srcset-sizes/) which goes into depth about the subject.
 
+### Custom Widths
+
+In situations where specific widths are desired when generating `srcset` pairs, a user can specify them by passing an array of integers via `widths` to the `options` keyword argument.
+
+```rb
+@client ||= Imgix::Client.new(host: 'testing.imgix.net', include_library_param: false)
+.path('image.jpg')
+.to_srcset(options: { widths: [100, 500, 1000, 1800] })
+```
+
+Will generate the following `srcset` of width pairs:
+
+```html
+https://testing.imgix.net/image.jpg?w=100 100w,
+https://testing.imgix.net/image.jpg?w=500 500w,
+https://testing.imgix.net/image.jpg?w=1000 1000w,
+https://testing.imgix.net/image.jpg?w=1800 1800w
+```
+
+Please note that in situations where a `srcset` is being rendered as a [fixed image](#fixed-image-rendering), any custom `widths` passed in will be ignored. Additionally, if both `widths` and a `width_tolerance` are passed to the `options` parameter in the `to_srcset` method, the custom widths list will take precedence.
+
+### Width Tolerance
+
+The `srcset` width tolerance dictates the maximum tolerated size difference between an image's downloaded size and its rendered size. For example: setting this value to 0.1 means that an image will not render more than 10% larger or smaller than its native size. In practice, the image URLs generated for a width-based srcset attribute will grow by twice this rate. A lower tolerance means images will render closer to their native size (thereby reducing rendering artifacts), but a large srcset list will be generated and consequently users may experience lower rates of cache-hit for pre-rendered images on your site.
+
+By default this rate is set to 8 percent, which we consider to be the ideal rate for maximizing cache hits without sacrificing visual quality. Users can specify their own width tolerance by passing a positive numeric value to `width_tolerance` within the `options` keyword argument:
+
+```rb
+client = Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false)
+client.path('image.jpg').to_srcset(options: { width_tolerance: 0.20 })
+```
+
+In this case, the `width_tolerance` is set to 20 percent, which will be reflected in the difference between subsequent widths in a srcset pair:
+
+```
+https://testing.imgix.net/image.jpg?w=100 100w,
+https://testing.imgix.net/image.jpg?w=140 140w,
+https://testing.imgix.net/image.jpg?w=196 196w,
+							...
+https://testing.imgix.net/image.jpg?w=8192 8192w
+```
+
+### Minimum and Maximum Width Ranges
+
+If the exact number of minimum/maximum physical pixels that an image will need to be rendered at is known, a user can specify them by passing an integer via `min_srcset` and/or `max_srcset` to the `options` keyword parameters:
+
+```rb
+client = Imgix::Client.new(host: 'testing.imgix.net', include_library_param: false)
+client.path('image.jpg').to_srcset(options: { min_srcset: 500, max_srcset: 2000 })
+```
+
+Will result in a smaller, more tailored srcset.
+
+```
+https://testing.imgix.net/image.jpg?w=500 500w,
+https://testing.imgix.net/image.jpg?w=580 580w,
+https://testing.imgix.net/image.jpg?w=672 672w,
+https://testing.imgix.net/image.jpg?w=780 780w,
+https://testing.imgix.net/image.jpg?w=906 906w,
+https://testing.imgix.net/image.jpg?w=1050 1050w,
+https://testing.imgix.net/image.jpg?w=1218 1218w,
+https://testing.imgix.net/image.jpg?w=1414 1414w,
+https://testing.imgix.net/image.jpg?w=1640 1640w,
+https://testing.imgix.net/image.jpg?w=1902 1902w,
+https://testing.imgix.net/image.jpg?w=2000 2000w
+```
+
+Remember that browsers will apply a device pixel ratio as a multiplier when selecting which image to download from a `srcset`. For example, even if you know your image will render no larger than 1000px, specifying `options: { max_srcset: 1000 }` will give your users with DPR higher than 1 no choice but to download and render a low-resolution version of the image. Therefore, it is vital to factor in any potential differences when choosing a minimum or maximum range.
+
+Also please note that according to the [imgix API](https://docs.imgix.com/apis/url/size/w), the maximum renderable image width is 8192 pixels.
+
+### Variable Qualities
+
+This gem will automatically append a variable `q` parameter mapped to each `dpr` parameter when generating a [fixed-image](https://github.com/imgix/imgix-rb#fixed-image-rendering) srcset. This technique is commonly used to compensate for the increased filesize of high-DPR images. Since high-DPR images are displayed at a higher pixel density on devices, image quality can be lowered to reduce overall filesize without sacrificing perceived visual quality. For more information and examples of this technique in action, see [this blog post](https://blog.imgix.com/2016/03/30/dpr-quality).
+
+This behavior will respect any overriding `q` value passed in as a parameter. Additionally, it can be disabled altogether by passing `options: { disable_variable_quality: true }` to `Imgix:Path#to_srcset`.
+
+This behavior specifically occurs when a [fixed-size image](https://github.com/imgix/imgix-rb#fixed-image-rendering) is rendered, for example:
+
+```rb
+srcset = Imgix::Client.new(host: 'testing.imgix.net', include_library_param: false)
+.path('image.jpg')
+.to_srcset(w:100)
+```
+
+will generate a srcset with the following `q` to `dpr` mapping:
+
+```html
+https://testing.imgix.net/image.jpg?w=100&dpr=1&q=75 1x,
+https://testing.imgix.net/image.jpg?w=100&dpr=2&q=50 2x,
+https://testing.imgix.net/image.jpg?w=100&dpr=3&q=35 3x,
+https://testing.imgix.net/image.jpg?w=100&dpr=4&q=23 4x,
+https://testing.imgix.net/image.jpg?w=100&dpr=5&q=20 5x
+```
+
 ## Multiple Parameters
 
 When the imgix api requires multiple parameters you have to use the method rather than an accessor.
@@ -99,7 +196,6 @@ For example to use the noise reduction:
 path.noise_reduction(50,50)
 ```
 
-
 ## Purge Cache
 
 If you need to remove or update an image on imgix, you can purge it from our cache by initializing a client with your api_key, then calling Imgix::Client#purge with the resource path.

data/imgix.gemspec

@@ -13,6 +13,13 @@ Gem::Specification.new do |spec|
   spec.homepage      = 'https://github.com/imgix/imgix-rb'
   spec.license       = 'MIT'
 
+  spec.metadata = {
+    'bug_tracker_uri'   => 'https://github.com/imgix/imgix-rb/issues',
+    'changelog_uri'     => 'https://github.com/imgix/imgix-rb/blob/master/CHANGELOG.md',
+    'documentation_uri' => "https://www.rubydoc.info/gems/imgix/#{spec.version}",
+    'source_code_uri'   => "https://github.com/imgix/imgix-rb/tree/#{spec.version}"
+  }
+
   spec.files         = `git ls-files`.split($/)
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})

data/lib/imgix.rb

@@ -8,20 +8,42 @@ module Imgix
   # regex pattern used to determine if a domain is valid
   DOMAIN_REGEX = /^(?:[a-z\d\-_]{1,62}\.){0,125}(?:[a-z\d](?:\-(?=\-*[a-z\d])|[a-z]|\d){0,62}\.)[a-z\d]{1,63}$/i
 
+  # determines the growth rate when building out srcset pair widths
+  DEFAULT_WIDTH_TOLERANCE = 0.08
+
+  # the default minimum srcset width
+  MIN_WIDTH = 100
+
+  # the default maximum srcset width, also the max width supported by imgix
+  MAX_WIDTH = 8192
+
   # returns an array of width values used during scrset generation
-  TARGET_WIDTHS = lambda {
-    increment_percentage = 8
-    max_size = 8192
+  TARGET_WIDTHS = lambda { |tolerance, min, max|
+    increment_percentage = tolerance || DEFAULT_WIDTH_TOLERANCE
+    unless increment_percentage.is_a? Numeric and increment_percentage > 0
+      raise ArgumentError, "The width_tolerance argument must be passed a positive scalar value"
+    end
+
+    max_size = max || MAX_WIDTH
     resolutions = []
-    prev = 100
+    prev = min || MIN_WIDTH
 
     while(prev <= max_size)
       # ensures that each width is even
       resolutions.push((2 * (prev / 2).round))
-      prev *= 1 + ((increment_percentage.to_f) / 100) * 2
+      prev *= 1 + (increment_percentage * 2)
     end
 
     resolutions.push(max_size)
     return resolutions
   }
+
+  # hash of default quality parameter values mapped  by each dpr srcset entry
+  DPR_QUALITY = {
+    1 => 75, 
+    2 => 50,
+    3 => 35,
+    4 => 23,
+    5 => 20
+  }
 end

data/lib/imgix/path.rb

@@ -39,7 +39,7 @@ module Imgix
 
       @path = CGI.escape(@path) if /^https?/ =~ @path
       @path = "/#{@path}" if @path[0] != '/'
-      @target_widths = TARGET_WIDTHS.call
+      @target_widths = TARGET_WIDTHS.call(DEFAULT_WIDTH_TOLERANCE, MIN_WIDTH, MAX_WIDTH)
     end
 
     def to_url(opts = {})
@@ -53,12 +53,12 @@ module Imgix
       end
 
       @options = prev_options
-      return url
+      url
     end
 
     def defaults
       @options = {}
-      return self
+      self
     end
 
     def method_missing(method, *args, &block)
@@ -70,7 +70,7 @@ module Imgix
       end
 
       @options[key] = args.join(',')
-      return self
+      self
     end
 
     ALIASES.each do |from, to|
@@ -84,7 +84,7 @@ module Imgix
       end
     end
 
-    def to_srcset(params = {})
+    def to_srcset(options: {}, **params)
       prev_options = @options.dup
       @options.merge!(params)
 
@@ -93,13 +93,13 @@ module Imgix
       aspect_ratio = @options['ar'.to_sym]
 
       if ((width) || (height && aspect_ratio))
-        srcset = build_dpr_srcset(@options)
+        srcset = build_dpr_srcset(options: options, params:@options)
       else
-        srcset = build_srcset_pairs(@options)
+        srcset = build_srcset_pairs(options: options, params: @options)
       end
 
       @options = prev_options
-      return srcset
+      srcset
     end
     
     private
@@ -128,27 +128,79 @@ module Imgix
       query.length > 0
     end
 
-    def build_srcset_pairs(params)
+    def build_srcset_pairs(options:, params:)
       srcset = ''
 
-      for width in @target_widths do
+      widths = options['widths'.to_sym] || []
+      width_tolerance = options['width_tolerance'.to_sym] ||  DEFAULT_WIDTH_TOLERANCE
+      min_srcset = options['min_width'.to_sym] || MIN_WIDTH
+      max_srcset = options['max_width'.to_sym] || MAX_WIDTH
+
+      if !widths.empty?
+        validate_widths!(widths)
+        srcset_widths = widths
+      elsif width_tolerance != DEFAULT_WIDTH_TOLERANCE or min_srcset != MIN_WIDTH or max_srcset != MAX_WIDTH
+        validate_range!(min_srcset, max_srcset)
+        srcset_widths = TARGET_WIDTHS.call(width_tolerance, min_srcset, max_srcset)
+      else
+        srcset_widths = @target_widths
+      end
+
+      for width in srcset_widths do
         params['w'.to_sym] = width
         srcset += "#{to_url(params)} #{width}w,\n"
       end
 
-      return srcset[0..-3]
+      srcset[0..-3]
     end
 
-    def build_dpr_srcset(params)
+    def build_dpr_srcset(options:, params:)
       srcset = ''
+
+      disable_variable_quality = options['disable_variable_quality'.to_sym] || false
+      validate_variable_qualities!(disable_variable_quality)
+
       target_ratios = [1,2,3,4,5]
+      quality = params['q'.to_sym]
 
       for ratio in target_ratios do
         params['dpr'.to_sym] = ratio
+
+        unless disable_variable_quality
+          params['q'.to_sym] = quality || DPR_QUALITY[ratio]
+        end
+
         srcset += "#{to_url(params)} #{ratio}x,\n"
       end
 
-      return srcset[0..-3]
+      srcset[0..-3]
+    end
+
+    def validate_widths!(widths)
+      unless widths.is_a? Array
+        raise ArgumentError, "The widths argument must be passed a valid array of integers"
+      else
+        positive_integers = widths.all? {|i| i.is_a?(Integer) and i > 0}
+        unless positive_integers
+          raise ArgumentError, "A custom widths array must only contain positive integer values"  
+        end
+      end
+    end
+
+    def validate_range!(min_srcset, max_srcset)
+      if min_srcset.is_a? Numeric and max_srcset.is_a? Numeric
+        unless min_srcset > 0 and max_srcset > 0
+          raise ArgumentError, "The min and max arguments must be passed positive Numeric values"
+        end
+      else
+        raise ArgumentError, "The min and max arguments must be passed positive Numeric values"
+      end
+    end
+
+    def validate_variable_qualities!(disable_variable_quality)
+      unless disable_variable_quality.is_a?(TrueClass) || disable_variable_quality.is_a?(FalseClass)
+        raise ArgumentError, "The disable_variable_quality argument must be passed a Boolean value"
+      end
     end
   end
 end

data/lib/imgix/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Imgix
-  VERSION = '3.1.1'
+  VERSION = '3.2.0'
 end

data/test/units/srcset_test.rb

@@ -8,7 +8,7 @@ module SrcsetTest
             expected_number_of_pairs = 31
             assert_equal expected_number_of_pairs, srcset.split(',').length
         end
-        
+
         def test_srcset_pair_values
             resolutions = [100, 116, 134, 156, 182, 210, 244, 282,
                 328, 380, 442, 512, 594, 688, 798, 926,
@@ -19,11 +19,11 @@ module SrcsetTest
                 srcset_split.split(' ')[1].to_i
             }
 
-            for i in 0..srclist.length-1 do
+            for i in 0..srclist.length - 1 do
                 assert_equal(srclist[i], resolutions[i])
             end
         end
-        
+
         private
             def path
                 @client ||= Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg')
@@ -56,10 +56,10 @@ module SrcsetTest
                 assert_includes src, 's='
 
                 # parses out all parameters except for 's=...'
-                params = src[src.index('?')..src.index('s=')-2]
+                params = src[src.index('?')..src.index('s=') - 2]
 
                 # parses out the 's=...' parameter
-                generated_signature = src.slice(src.index('s=')+2, src.length)
+                generated_signature = src.slice(src.index('s=') + 2, src.length)
 
                 signature_base = 'MYT0KEN' + '/image.jpg' + params;
                 expected_signature = Digest::MD5.hexdigest(signature_base)
@@ -67,8 +67,44 @@ module SrcsetTest
                 assert_equal expected_signature, generated_signature
             }
         end
-    
+
+        def test_srcset_has_variable_qualities
+            i = 0
+            srcset.split(',').map { |src|
+                assert_includes src, "q=#{DPR_QUALITY[i]}"
+                i += 1
+            }
+        end
+
+        def test_srcset_respects_overriding_quality
+            quality_override = 100
+            srcset = Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg').to_srcset(w:100, q:quality_override)
+
+            srcset.split(',').map { |src|
+                assert_includes src, "q=#{quality_override}"
+            }
+        end
+
+        def test_disable_variable_quality
+            srcset = Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg').to_srcset(w:100, options: { disable_variable_quality: true })
+
+            srcset.split(',').map { |src|
+                assert(not(src.include? "q="))
+            }
+        end
+
+        def test_respects_quality_param_when_disabled
+            quality_override = 100
+            srcset = Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg').to_srcset(w:100, q:100, options: { disable_variable_quality: true })
+
+            srcset.split(',').map { |src|
+                assert_includes src, "q=#{quality_override}"
+            }
+        end
+
         private
+            DPR_QUALITY = [75, 50, 35, 23, 20]
+
             def srcset
                 @client ||= Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg').to_srcset(w:100)
             end
@@ -89,7 +125,7 @@ module SrcsetTest
                 srcset_split.split(' ')[1].to_i
             }
 
-            for i in 0..srclist.length-1 do
+            for i in 0..srclist.length - 1 do
                 assert_equal(srclist[i], resolutions[i])
             end
         end
@@ -105,14 +141,15 @@ module SrcsetTest
 
             # parse out the width descriptor as an integer
             min = min.split(' ')[1].to_i
-            max = max[max.length-1].split(' ')[1].to_i
+            max = max[max.length - 1].split(' ')[1].to_i
 
             assert_operator min, :>=, 100
             assert_operator max, :<=, 8192
         end
 
-        def test_srcset_iterates_18_percent
-            increment_allowed = 0.18
+        # a 17% testing threshold is used to account for rounding
+        def test_srcset_iterates_17_percent
+            increment_allowed = 0.17
 
             # create an array of widths
             widths = srcset.split(',').map { |src|
@@ -121,9 +158,9 @@ module SrcsetTest
 
             prev = widths[0]
 
-            for i in 1..widths.length-1 do
+            for i in 1..widths.length - 1 do
                 element = widths[i]
-                assert_operator (element / prev), :<, (1 + increment_allowed)
+                assert_operator (element.to_f / prev.to_f), :<, (1 + increment_allowed)
                 prev = element
             end
         end
@@ -134,10 +171,10 @@ module SrcsetTest
                 assert_includes src, 's='
 
                 # parses out all parameters except for 's=...'
-                params = src[src.index('?')..src.index('s=')-2]
+                params = src[src.index('?')..src.index('s=') - 2]
 
                 # parses out the 's=...' parameter
-                generated_signature = src.slice(src.index('s=')+2, src.length)
+                generated_signature = src.slice(src.index('s=') + 2, src.length)
 
                 signature_base = 'MYT0KEN' + '/image.jpg' + params;
                 expected_signature = Digest::MD5.hexdigest(signature_base)
@@ -155,7 +192,6 @@ module SrcsetTest
     class SrcsetGivenWidthAndHeight < Imgix::Test
         def test_srcset_in_dpr_form
             device_pixel_ratio = 1
-
             srcset.split(',').map { |src|
                 ratio = src.split(' ')[1]
                 assert_equal ("#{device_pixel_ratio}x"), ratio
@@ -178,19 +214,55 @@ module SrcsetTest
                 assert_includes src, 's='
 
                 # parses out all parameters except for 's=...'
-                params = src[src.index('?')..src.index('s=')-2]
+                params = src[src.index('?')..src.index('s=') - 2]
 
                 # parses out the 's=...' parameter
-                generated_signature = src.slice(src.index('s=')+2, src.length)
+                generated_signature = src.slice(src.index('s=') + 2, src.length)
 
                 signature_base = 'MYT0KEN' + '/image.jpg' + params;
                 expected_signature = Digest::MD5.hexdigest(signature_base)
-                
+
                 assert_equal expected_signature, generated_signature
             }
         end
 
+        def test_srcset_has_variable_qualities
+            i = 0
+            srcset.split(',').map { |src|
+                assert_includes src, "q=#{DPR_QUALITY[i]}"
+                i += 1
+            }
+        end
+
+        def test_srcset_respects_overriding_quality
+            quality_override = 100
+            srcset = Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg').to_srcset(w:100, h:100, q:quality_override)
+
+            srcset.split(',').map { |src|
+                assert_includes src, "q=#{quality_override}"
+            }
+        end
+
+        def test_disable_variable_quality
+            srcset = Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg').to_srcset(w:100, h:100, options: { disable_variable_quality: true })
+
+            srcset.split(',').map { |src|
+                assert(not(src.include? "q="))
+            }
+        end
+
+        def test_respects_quality_param_when_disabled
+            quality_override = 100
+            srcset = Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg').to_srcset(w:100, h:100, q:100, options: { disable_variable_quality: true })
+
+            srcset.split(',').map { |src|
+                assert_includes src, "q=#{quality_override}"
+            }
+        end
+
         private
+            DPR_QUALITY = [75, 50, 35, 23, 20]
+
             def srcset
                 @client ||= Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg').to_srcset(w:100,h:100)
             end
@@ -211,7 +283,7 @@ module SrcsetTest
                 srcset_split.split(' ')[1].to_i
             }
 
-            for i in 0..srclist.length-1 do
+            for i in 0..srclist.length - 1 do
                 assert_equal(srclist[i], resolutions[i])
             end
         end
@@ -221,14 +293,15 @@ module SrcsetTest
 
             # parse out the width descriptor as an integer
             min = min.split(' ')[1].to_i
-            max = max[max.length-1].split(' ')[1].to_i
+            max = max[max.length - 1].split(' ')[1].to_i
 
             assert_operator min, :>=, 100
             assert_operator max, :<=, 8192
         end
 
-        def test_srcset_iterates_18_percent
-            increment_allowed = 0.18
+        # a 17% testing threshold is used to account for rounding
+        def test_srcset_iterates_17_percent
+            increment_allowed = 0.17
 
             # create an array of widths
             widths = srcset.split(',').map { |src|
@@ -237,9 +310,9 @@ module SrcsetTest
 
             prev = widths[0]
 
-            for i in 1..widths.length-1 do
+            for i in 1..widths.length - 1 do
                 element = widths[i]
-                assert_operator (element / prev), :<, (1 + increment_allowed)
+                assert_operator (element.to_f / prev.to_f), :<, (1 + increment_allowed)
                 prev = element
             end
         end
@@ -250,10 +323,10 @@ module SrcsetTest
                 assert_includes src, 's='
 
                 # parses out all parameters except for 's=...'
-                params = src[src.index('?')..src.index('s=')-2]
+                params = src[src.index('?')..src.index('s=') - 2]
 
                 # parses out the 's=...' parameter
-                generated_signature = src.slice(src.index('s=')+2, src.length)
+                generated_signature = src.slice(src.index('s=') + 2, src.length)
 
                 signature_base = 'MYT0KEN' + '/image.jpg' + params;
                 expected_signature = Digest::MD5.hexdigest(signature_base)
@@ -294,21 +367,341 @@ module SrcsetTest
                 assert_includes src, 's='
 
                 # parses out all parameters except for 's=...'
-                params = src[src.index('?')..src.index('s=')-2]
+                params = src[src.index('?')..src.index('s=') - 2]
 
                 # parses out the 's=...' parameter
-                generated_signature = src.slice(src.index('s=')+2, src.length)
+                generated_signature = src.slice(src.index('s=') + 2, src.length)
 
                 signature_base = 'MYT0KEN' + '/image.jpg' + params;
                 expected_signature = Digest::MD5.hexdigest(signature_base)
-                
+
                 assert_equal expected_signature, generated_signature
             }
         end
 
+        def test_srcset_has_variable_qualities
+            i = 0
+            srcset.split(',').map { |src|
+                assert_includes src, "q=#{DPR_QUALITY[i]}"
+                i += 1
+            }
+        end
+
+        def test_srcset_respects_overriding_quality
+            quality_override = 100
+            srcset = Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg').to_srcset(w:100, ar:'3:2', q:quality_override)
+
+            srcset.split(',').map { |src|
+                assert_includes src, "q=#{quality_override}"
+            }
+        end
+
+        def test_disable_variable_quality
+            srcset = Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg').to_srcset(w:100, ar:'3:2', options: { disable_variable_quality: true })
+
+            srcset.split(',').map { |src|
+                assert(not(src.include? "q="))
+            }
+        end
+
+        def test_respects_quality_param_when_disabled
+            quality_override = 100
+            srcset = Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg').to_srcset(w:100, h:100, q:100, options: { disable_variable_quality: true })
+
+            srcset.split(',').map { |src|
+                assert_includes src, "q=#{quality_override}"
+            }
+        end
+
         private
+            DPR_QUALITY = [75, 50, 35, 23, 20]
+
             def srcset
                 @client ||= Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg').to_srcset({h:100,ar:'3:2'})
             end
     end
-end
+
+    class SrcsetWidthTolerance < Imgix::Test
+        def test_srcset_generates_width_pairs
+            expected_number_of_pairs = 15
+            assert_equal expected_number_of_pairs, srcset.split(',').length
+        end
+
+        def test_srcset_pair_values
+            resolutions = [100,140,196,274,384,538,752,1054,1476,2066,2892,4050,5670,7938,8192]
+            srclist = srcset.split(',').map { |srcset_split|
+                srcset_split.split(' ')[1].to_i
+            }
+
+            for i in 0..srclist.length - 1 do
+                assert_equal(srclist[i], resolutions[i])
+            end
+        end
+
+        def test_srcset_within_bounds
+            min, *max = srcset.split(',')
+
+            # parse out the width descriptor as an integer
+            min = min.split(' ')[1].to_i
+            max = max[max.length - 1].split(' ')[1].to_i
+            assert_operator min, :>=, 100
+            assert_operator max, :<=, 8192
+        end
+
+        # a 41% testing threshold is used to account for rounding
+        def test_srcset_iterates_41_percent
+            increment_allowed = 0.41
+
+            # create an array of widths
+            widths = srcset.split(',').map { |src|
+                src.split(' ')[1].to_i
+            }
+
+            prev = widths[0]
+
+            for i in 1..widths.length - 1 do
+                element = widths[i]
+                assert_operator (element.to_f / prev.to_f), :<, (1 + increment_allowed)
+                prev = element
+            end
+        end
+
+        def test_invalid_tolerance_emits_error
+            assert_raises(ArgumentError) {
+                Imgix::Client.new(host: 'testing.imgix.net')
+                .path('image.jpg')
+                .to_srcset(options: {width_tolerance: 'abc'})
+            }
+        end
+
+        def test_negative_tolerance_emits_error
+            assert_raises(ArgumentError) {
+                Imgix::Client.new(host: 'testing.imgix.net')
+                .path('image.jpg')
+                .to_srcset(options: {width_tolerance: -0.10})
+            }
+        end
+
+        def test_with_param_after
+            srcset = Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false)
+            .path('image.jpg')
+            .to_srcset(options: {width_tolerance: 0.20}, h:1000, fit:"clip")
+            assert_includes(srcset, "h=")
+            assert(not(srcset.include? "width_tolerance="))
+        end
+
+        def test_with_param_before
+            srcset = Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false)
+            .path('image.jpg')
+            .to_srcset(h:1000, fit:"clip", options: {width_tolerance: 0.20})
+            assert_includes(srcset, "h=")
+            assert(not(srcset.include? "width_tolerance="))
+        end
+
+        private
+            def srcset
+                @client ||= Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg').to_srcset(options: {width_tolerance: 0.20})
+            end
+    end
+
+    class SrcsetCustomWidths < Imgix::Test
+        def test_srcset_generates_width_pairs
+            expected_number_of_pairs = 4
+            assert_equal expected_number_of_pairs, srcset.split(',').length
+        end
+
+        def test_srcset_pair_values
+            resolutions = [100, 500, 1000, 1800]
+            srclist = srcset.split(',').map { |srcset_split|
+                srcset_split.split(' ')[1].to_i
+            }
+
+            for i in 0..srclist.length - 1 do
+                assert_equal(srclist[i], resolutions[i])
+            end
+        end
+
+        def test_srcset_within_bounds
+            min, *max = srcset.split(',')
+
+            # parse out the width descriptor as an integer
+            min = min.split(' ')[1].to_i
+            max = max[max.length - 1].split(' ')[1].to_i
+
+            assert_operator min, :>=, @widths[0]
+            assert_operator max, :<=, @widths[-1]
+        end
+
+        def test_invalid_widths_input_emits_error
+            assert_raises(ArgumentError) {
+                Imgix::Client.new(host: 'testing.imgix.net')
+                .path('image.jpg')
+                .to_srcset(options: {widths: 'abc'})
+            }
+        end
+
+        def test_non_integer_array_emits_error
+            assert_raises(ArgumentError) {
+                Imgix::Client.new(host: 'testing.imgix.net')
+                .path('image.jpg')
+                .to_srcset(options: {widths: [100, 200, false]})
+            }
+        end
+
+        def test_negative_integer_array_emits_error
+            assert_raises(ArgumentError) {
+                Imgix::Client.new(host: 'testing.imgix.net')
+                .path('image.jpg')
+                .to_srcset(options: {widths: [100, 200, -100]})
+            }
+        end
+
+        def test_with_param_after
+            srcset = Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false)
+            .path('image.jpg')
+            .to_srcset(options: {widths: [100, 200, 300]}, h:1000, fit:"clip")
+            assert_includes(srcset, "h=")
+            assert(not(srcset.include? "widths="))
+        end
+
+        def test_with_param_before
+            srcset = Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false)
+            .path('image.jpg')
+            .to_srcset(h:1000, fit:"clip", options: {widths: [100, 200, 300]})
+            assert_includes(srcset, "h=")
+            assert(not(srcset.include? "widths="))
+        end
+
+        private
+            def srcset
+                @widths = [100, 500, 1000, 1800]
+                @client ||= Imgix::Client.new(
+                    host: 'testing.imgix.net',
+                    include_library_param: false)
+                    .path('image.jpg')
+                    .to_srcset(options: {widths: @widths})
+            end
+    end
+
+    class SrcsetMinMaxWidths < Imgix::Test
+        def test_srcset_generates_width_pairs
+            expected_number_of_pairs = 11
+            assert_equal expected_number_of_pairs, srcset.split(',').length
+        end
+
+        def test_srcset_pair_values
+            resolutions = [500,580,672,780,906,1050,1218,1414,1640,1902,2000]
+            srclist = srcset.split(',').map { |srcset_split|
+                srcset_split.split(' ')[1].to_i
+            }
+
+            for i in 0..srclist.length - 1 do
+                assert_equal(srclist[i], resolutions[i])
+            end
+        end
+
+        def test_srcset_within_bounds
+            min, *max = srcset.split(',')
+
+            # parse out the width descriptor as an integer
+            min = min.split(' ')[1].to_i
+            max = max[max.length - 1].split(' ')[1].to_i
+
+            assert_operator min, :>=, @MIN
+            assert_operator max, :<=, @MAX
+        end
+
+        # a 41% testing threshold is used to account for rounding
+        def test_with_custom_width_tolerance
+            srcset = Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg').to_srcset(options: {min_width: 500, max_width: 2000, width_tolerance: 0.20})
+
+            increment_allowed = 0.41
+
+            # create an array of widths
+            widths = srcset.split(',').map { |src|
+                src.split(' ')[1].to_i
+            }
+
+            prev = widths[0]
+
+            for i in 1..widths.length - 1 do
+                element = widths[i]
+                assert_operator (element.to_f / prev.to_f), :<, (1 + increment_allowed)
+                prev = element
+            end
+        end
+
+        def test_invalid_min_emits_error
+            assert_raises(ArgumentError) {
+                Imgix::Client.new(host: 'testing.imgix.net')
+                .path('image.jpg')
+                .to_srcset(options: {min_width: 'abc'})
+            }
+        end
+
+        def test_negative_max_emits_error
+            assert_raises(ArgumentError) {
+                Imgix::Client.new(host: 'testing.imgix.net')
+                .path('image.jpg')
+                .to_srcset(options: {max_width: -100})
+            }
+        end
+
+        def test_with_param_after
+            srcset = Imgix::Client.new(host: 'testing.imgix.net', include_library_param: false)
+            .path('image.jpg')
+            .to_srcset(options: {min_width: 500, max_width:2000}, h:1000, fit:"clip")
+
+            assert_includes(srcset, "h=")
+            assert(not(srcset.include? "min_width="))
+            assert(not(srcset.include? "max_width="))
+        end
+
+        def test_with_param_before
+            srcset = Imgix::Client.new(host: 'testing.imgix.net', include_library_param: false)
+            .path('image.jpg')
+            .to_srcset(h:1000, fit:"clip", options: {min_width: 500, max_width:2000})
+
+            assert_includes(srcset, "h=")
+            assert(not(srcset.include? "min_width="))
+            assert(not(srcset.include? "max_width="))
+        end
+
+        def test_only_min
+            min_width = 1000
+            max_width = 8192
+            srcset = Imgix::Client.new(host: 'testing.imgix.net', include_library_param: false).path('image.jpg').to_srcset(options: {min_width: min_width})
+
+            min, *max = srcset.split(',')
+
+            # parse out the width descriptor as an integer
+            min = min.split(' ')[1].to_i
+            max = max[max.length - 1].split(' ')[1].to_i
+
+            assert_operator min, :>=, min_width
+            assert_operator max, :<=, max_width
+        end
+
+        def test_only_max
+            min_width = 100
+            max_width = 1000
+            srcset = Imgix::Client.new(host: 'testing.imgix.net', include_library_param: false).path('image.jpg').to_srcset(options: {max_width: max_width})
+            min, *max = srcset.split(',')
+
+            # parse out the width descriptor as an integer
+            min = min.split(' ')[1].to_i
+            max = max[max.length - 1].split(' ')[1].to_i
+
+            assert_operator min, :>=, min_width
+            assert_operator max, :<=, max_width
+
+        end
+
+        private
+            def srcset
+                @MIN = 500
+                @MAX = 2000
+                @client ||= Imgix::Client.new(host: 'testing.imgix.net', include_library_param: false).path('image.jpg').to_srcset(options: {min_width: @MIN, max_width: @MAX})
+            end
+    end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: imgix
 version: !ruby/object:Gem::Version
-  version: 3.1.1
+  version: 3.2.0
 platform: ruby
 authors:
 - Kelly Sutton
@@ -13,7 +13,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-09-05 00:00:00.000000000 Z
+date: 2019-11-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -78,7 +78,11 @@ files:
 homepage: https://github.com/imgix/imgix-rb
 licenses:
 - MIT
-metadata: {}
+metadata:
+  bug_tracker_uri: https://github.com/imgix/imgix-rb/issues
+  changelog_uri: https://github.com/imgix/imgix-rb/blob/master/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/imgix/3.2.0
+  source_code_uri: https://github.com/imgix/imgix-rb/tree/3.2.0
 post_install_message: 
 rdoc_options: []
 require_paths: