Styles

This plugin piggy-backs on the style declarations already in use with Paperclip. You don't need to change anything to get started, but once you're running on Imgix, you can change the styles as your site evolves.

Often you will have your style defined by a geometry string, such as:

:styles => { :thumb => "100x100#" }

That will work as is, but you can also use a Hash for the style definition:

:styles => { :thumb => { :geometry => "100x100#" } }

That works using straight-up Paperclip. But, this is where using the Imgix plugin adds tremendous power. For example:

:styles => {
  :thumb => {
    :geometry => "100x100#",
    :crop => :faces,
    :vibrance => 10,
    :reduce_noise => { :level => 20, :sharpness => 50 }
  }
}

Now, instead of simply cropping the thumbnail in the center of the image, an area is selected to best fit any faces found in the picture. While you're at it, you can boost the vibrance of the image, and apply some noise reduction.

Because the images are rendered on demand, you are no longer limited to only defining styles in the model. You can combine style declarations in your views:

<%= image_tag @user.avatar.url(:thumb, :style => { :sepia => 50 }) %>

This will add a 50% sepia toning to the image, in addition to the styles set in the model. By merging the style declaration in the model, you can build up styles from other sources, such as other fields in the model. Adding this style declaration to the model:

:styles => {
  :medium => {
    :geometry => "300x300>",
    :text => { :font => %w{sans-serif bold}, :size => 36,
               :color => 'FFF', :shadow => 5 }
  }
}

in the view, you can:

<%= image_tag @user.avatar.url(:thumb, :style => { :text => @user.screen_name }) %>

which is equivalent to:

<%= image_tag @user.avatar.url(:thumb, :style => { :text => { :content => @user.screen_name }}) %>

Style Options

For examples and more detailed documentation about the styles, refer to the Imgix site.

crop String | [String]

Controls how the input image is aligned when the geometry string requires a crop. Valid values are top, bottom, left, right, and faces. Multiple values can be used by the value as an array. If no value is explicitly set, the default behavior is to center the image.

Example:

:crop => %w{top faces} # crop to faces or top-center

mark String | {url:String, scale:Number, align:[String]}

Adds a watermark to the bottom right-hand corner of the image. Valid values are absolute URLs to the watermark image. The watermark is given a 5 pixel gap from the edge of the image.

If the value is a Hash, they keys are:

• :url: Absolute URL to the watermark image (required)
• :scale: Scales the watermark to a percentage of the source image's width dimension
• :align: Adjusts the alignment of the watermark image with the source image. This can be a single String value, or an Array. Valid options are: top, middle, bottom, left, center, and right.

Example:

:mark => "http://www.imgix.com/static/img/logo.png" # watermark in bottom-left
:mark => { :url => "http://www.imgix.com/static/img/logo.png",
           :align => %w{top center} }

dpr Number

The device pixel ratio is used to easily convert between CSS pixels and device pixels. This makes it possible to display images at the correct pixel density on a variety of devices such as Apple devices with Retina Displays and Android devices. The default is 1.

Example:

:dpr => 2.0 # retina display

format String

The output format to convert the image to. Valid values are jpg and png. The default value is to use the file format of the input image.

Example:

:format => 'png' # force PNG output

quality Number

Controls the output quality of lossy file formats. Presently only applies to the jpg file format. Valid values are in the range 0 - 100. The default value is 75.

Example:

:quality => 90 # high quality

background String

The background color to use when transparency is encountered. Valid values are 3-value (rgb), 4-value (argb), 6-value (rgb), or 8-value (argb) hexadecimal colors. The default is transparent white, 0FFF. For image formats that do not support transparency, set this value to a non-transparent color.

Example:

:background => 'F00' # ooh, red

page Number

The PDF page number – starting from 1 – of the source to be rendered to an image. If omitted, the first page will be used.

Example:

:page => 2 # page 2 is probably awesome

flip String

Flips the image horizontally, vertically, or both. Valid values are h, v, and hv. The default is to leave this value unset.

Example:

:flip => 'v' # might be unsettling

rotate Number

Rotates the image according to the value specified in degrees. The image will be rotate with-in the geometry bounds, acting to "straighten" the image. Valid values are in the range 0 - 359. The default value is 0 which leaves the image unchanged.

Example:

:rotate => 10 # rotate 10 degrees

brightness Number

Adjusts the brightness of the image. Valid values are in the range -100 to 100. The default value is 0 which leaves the image unchanged.

Example:

:brightness => 10 # make a little brighter

contrast Number

Adjusts the contrast of the image. Valid values are in the range -100 to 100. The default value is 0 which leaves the image unchanged.

Example:

:contrast => -10 # lower contrast a bit

exposure Number

Adjusts the exposure setting for an image similar to the way you control exposure for a camera when you change the F-stop. Valid values are in the range -100 to 100. The default value is 0 which leaves the image unchanged.

Example:

:exposure => 10

highlight Number

Adjusts the highlight tonal mapping of an image while preserving spatial detail. Valid values are in the range -100 to 100. The default value is 0 which leaves the image unchanged.

Example:

:highlight => 10

shadow Number

Adjusts the shadow tonal mapping of an image while preserving spatial detail. Valid values are in the range -100 to 100. The default value is 0 which leaves the image unchanged.

Example:

:shadow => 10

gamma Number

Adjusts gamma/midtone brightness. Valid values are in the range -100 to 100. The default value is 0 which leaves the image unchanged.

Example:

:gamma => 10

vibrance Number

Adjusts the vibrance of an image while keeping pleasing skin tones. Valid values are in the range 0 to 200. The default value is 0 which leaves the image unchanged.

Example:

:vibrance => 10

sharpness Number

Sharpens the image details using luminance sharpening. Valid values are in the range 0 - 100. The default value is 0 which leaves the image unchanged.

Example:

:sharpness => 10

hue Number

Changes the overall hue, or tint, of the source pixels. The angle is the adjustment along a hue color wheel, rotating the color cube around the neutral axis. Valid values are in the range 0 - 359. The default value is 0 which leaves the image unchanged.

Example:

:hue => 100

saturation Number

Adjusts the saturation of the image. Valid values are in the range -100 to 100. The default value is 0 which leaves the image unchanged. A value of -100 will convert the image to grayscale.

Example:

:saturation => 10

sepia Number

Applies a sepia toning effect to the image. Valid values are in the range 0 - 100. The default value is 0 which leaves the image unchanged.

Example:

:sepia => 50

noise_reduction Number | [Number, Number] | {level:Number, sharpness:Number}

Reduces the noise in the image. There are two parameters, level and sharpness. Valid values for both are in the range 0 - 100. The default value for both is 20. If neither value is supplied, then no noise reduction will be applied. If only one parameter is set, the other will be set to its default.

The level value sets the threshold at which noise is removed. Pixels that fall below this threshold will be blurred. Pixels above the threshold will be sharpened according to the sharpness parameter value.

For a single Number, the value is interpreted as the level value of the noise reduction. For the [Number, Number] array, the first value is the level, and the second is sharpness.

Example:

:noise_reduction => 50         # level: 50, sharpness: 20    
:noise_reduction => [40, 10]   # level: 40, sharpness: 10    
:noise_reduction => { :level => 30, :sharpness => 15 }

text String | {…}

{ content: String,
  font: String | [String],
  size: Number,
  color: String,
  shadow: Number,
  align: String | [String],
  width: Number,
  padding: Number,
  clip: String,
  clip_text: String }

Places a single line of text on top of the image with control over font, size, color, alightment, and shadow. The content key must be supplied for any of the text options to be used.

For a String value, text is the string to add to the image. For a Hash value, the keys are:

• content: The text to add to the image
• font: The font type and/or style as a String or [String]. Possible values are 1 or more of serif, sans-serif, monospace, cursive, fantasy, bold, and italic. The default value is sans-serif.
• size: A Number to set the font size. The default value is 12.
• color: A String to set the font color. Valid values are 3-value (rgb), 4-value (argb), 6-value (rgb), or 8-value (argb) hexadecimal colors. The default is opaque black, F000.
• shadow: A Number indicating the strength of a shadow to place on the text. The default is no shadow.
• align: The alignment of the text within the image. Possibles values are 1 or more of left, center, right, top, middle, and bottom. The default is %w{bottom right}
• width: The Number of pixels to restrict the width of the text to. If the text exceeds this amount, it will be clipped. The default value is calculated by the width of the output image minus the padding on the left and right.
• padding: The Number of pixels to pad the text from the edge of the image. The default is 10.
• clip: Sets the region of the string to clip if it is too long. Possible values are start, middle, and end. The default value is end.
• clip_text: The String to use in place of the clipped text. The default is '…'.

Example:

:text => "My Label",
:text => {
    :content => "My Label"
    :font => %{sans-serif bold},
    :size => 36,
    :color => 'FCC',
    :shadow => 5,
    :align => %w{top center},
    :width => 200,
    :padding => 10,
    :clip => 'middle',
    :clip_text => '…'
}