Reference

Cropping

Thumbr.io has several ways to crop an image horizontally and vertically. Let's see all of them throught this image (*).

Option t
(*) Image courtesy of Éole. cc


Vertical crops

Option t
Crop top: (t)
Option c
Crop center: (c)
Option b
Crop bottom: (b)


Horizontal crops

Option t
Crop left: (l)
Option c
Crop center: (c)
Option b
Crop right: (r)

Smart cropping

Crop your photos without losing the juicy parts! Add a simple parameter to smart-crop and keep the faces in your photos (*).

Option s
(*) Image courtesy of Éole. cc


Vertical smart crop

Option s
Crop smart: (s)


Horizontal smart crop

Option s
Crop smart: (s)

Watermark

Thumbr.io has several options to apply a watermark to an image. Let's see all of them throught this image (*).

Default image
watermark=http://www.thumbr.io/img/thumbrio-black.png

(*) Image courtesy of Dennis Jarvis. cc
Name Value Description
watermark string The URL of the image.

watermark = www.thumbr.io/img/thumbrio-black.png
watermark=http://www.thumbr.io/img/thumbrio-black.png
wsize string The dimension of the watermark (in pixels) [* see Dimensions]. By default it's the same size of the image.

wsize=100p
wsize=100p
wsize=100x100
wsize=100x100
wsize=90x20c
wsize=90x20c
wsize=20x50l
wsize=20x50l
walign string The position of your watermark. We can put it on the left(l), center(c) or right(r); and on the top(t), center(c) and bottom(b). According to this, we can choose between one of these: lt, lc, lb, ct, cc, cb, rt, rc and rb. By default it's cc. Note: In these examples wsize=80x20c.

wsize=80x20c and walign=lt
walign=lt
wsize=80x20c and walign=lc
walign=lc
wsize=80x20c and walign=lb
walign=lb
wsize=80x20c and walign=ct
walign=ct
wsize=80x20c and walign=cc
walign=cc
wsize=80x20c and walign=cc
walign=cb
wsize=80x20c and walign=cc
walign=rt
wsize=80x20c and walign=cc
walign=rc
wsize=80x20c and walign=cc
walign=rb
wpad int The padding of the watermark. By default it's 0.

wsize=80x20c and walign=cc
wpad=0
wsize=80x20c and walign=cc
wpad=8

Features

Retina images

Add @2x to the SEO NAME of your images, but take it out to sign the URL. This will allow you to easily request a Retina version of your images from client side code.

To “retinify” automatically all your imgs add this javascript just before you close your body tag:

(function() {
    if (window.devicePixelRatio >= 2) {
        var images = document.getElementsByTagName('img');
        for (var i = 0; i < images.length; i++) {
            (function() {
                var lowImg = images[i];
                var customHeight = lowImg.height;
                var customWidth = lowImg.width;
                var url = lowImg.src;
                hiresUrl = url.replace(/(\.[a-zA-Z0-9]+)$/, '@2x$1');
                var hiImg = new Image();
                hiImg.onload = function() {
                    lowImg.src = hiImg.src;
                    lowImg.height = customHeight || (hiImg.height / 2);
                    lowImg.width = customWidth || (hiImg.width / 2);
                };
                hiImg.src = hiresUrl;
            })();
        }
    }
})();

Inline effect

This way to define an effect is more flexible than going through the editor of effects.You will fully define the effect in the query arguments of the URL. Those are all the arguments that you can use:

Arguments of an inline effect:

Name Value Description
grayscale boolean The mode of the image. If grayscale equals true, the mode of the image will be grayscale. By default it's false.

example image
grayscale = false
example image
grayscale = true
hue integer It is the number of grades of hue it will be incremented or decremented to all pixels of the image. By default it's 0.

example image
hue = 0
example image
hue = 100
saturation integer The percentage increment or decrement of the saturation. The saturation is the intensity of all the colors in the image. By default it's 0

example image
saturation = 0
example image
saturation = 100
lightness integer The percentage increment or decrement of the lightness. The range of possible values is [-100, 100]. By default it's 0

example image
lightness = 0
example image
lightness = 100
gamma float The gamma correction of the image is a exponential operation that it is used to code and decode luminance or tristimulus values in the image. Trought this operation, all pixel values will be elevated to the value of gamma. By default it's 1

example image
gamma = 1
example image
gamma = 3
contrast integer It is the increment / decrement of the image contrast. Contrast is defined as the separation between the darkest and brightest areas of the image. The range of possible values [-127, 127]. By default it's 0

example image
contrast = 0
example image
contrast = 100
brightness integer It is the increment / decrement of the image brightness. The range of possible values [-256, 256]. By default it's 0

example image
brightness = 0
example image
brightness = 100
r,g,b array of float A list of points x, y where the function of the color transformation passes. This list of points have this shape: 'x1, y1, x2, y2, ..., xn, yn', where the x-values must be in order, from 0 to 255. By default it's '0,0,127,127,255,255'

In the next example, the color transformation y = 255 - x ('0,255,100,155,255,0') was implement

example image
y = x
example image
y = 255 - x
alpha string The image we want as alpha. You can choose between one of these: medium-circle, big-circle, square and alpha-flare. By default, it's none.

example image
alpha = 'none'
example image
alpha='medium-circle'
q integer Quality of the JPEG compression. Valid values are in the range 0 - 100, where 0 is the lowest quality and minimum file size, and 100 is highest quality and maximum file size. By default, it's 95.

example image
q = 100
example image
q = 20

Multiple layers

You can create an image overlapping different layers on top of each other. Each of these layers can be filtered using all the options described in the previous inline effect section. To specify which options apply to which layer, split the options with the argument compose, which value is the operator used to compose the right layer on top of the left layer.

In the following example we will combine 3 layers, the first layer is the original image (in the URL this part is empty), on top of this layer combined with the operation multiply we will overlay a reddish version of the original image with transparent edges, and we will again overlay the previous image with the frame9. The final query argument to get this multilayer filter is:

?compose=multiply&r=0,0,93,200,255,255&alpha=medium-circle&compose=normal&src=frame9
Effect of three layers Effect of three layers


Query arguments for multiple layers

Name Value Description
compose string

The possible values of compose are: normal, overlay, screen and multiply.

These options blend together two layers using the same algorithm used by Photoshop. The normal mode simply paints the right layer on top of the left layer. The overlay mode gives the image a higher contrast, making dark zones darker and bright zones brighter. The screen mode makes the makes the bottom image brighter. The multiply mode makes the makes the bottom image darker.

example image
compose = normal
example image
compose = overlay

example image
compose = screen
example image
grayscale = multiply
src string

You can change the base image of a layer using the src argument. The possible values are: frame1, frame2, ... to frame9, texture 1, texture 2, texture 3, texture 4, texture-2-wo-alpha, texture-3-wo-alpha, texture-4-wo-alpha, scratches and scratches2.

example image
src=none
example image
compose=normal&
src=frame6

example image
src=texture-3-wo-alpha&
compose=overlay

Whitenoise

This URL returns a noisy image WIDTH x HEIGHT of a determined density, opacity and color. This feature was created as a service to the community of cssmatic users. The use of this utility is completely free. Its usage will not count against your quota.

http://api.thumbr.io/whitenoise-WIDTHxHEIGHT.EXTENSION?opacity=OPACITY&density=DENSITY&background=BACKGROUND&noise=NOISE

Options of whitenoise

Name Value Description
WIDTH integer The width of the image (between 1 and 2000).
HEIGHT integer The height of the image (between 1 and 2000).
OPACITY integer The maximum opacity of the image's noise. The range of possible values is [0, 100]. By default it's 15.

example image
opacity = 0
example image
opacity = 25

example image
opacity = 50
example image
opacity = 100
DENSITY integer The image noise density. The range of possible values is [0, 100]. By default it's 50.

example image
density = 0
example image
density = 25

example image
density = 50
example image
density = 100
EXTENSION string The extension of the image. It can be one of .jpeg, .jpg, .gif or .png.
BACKGROUND string The RGBA color of the image's background in hexadecimal format (RRGGBBAA). By default it's FFFFFFFF (solid white color).
NOISE string The RGB color of the image's noise in hexadecimal format (RRGGBB). By default it's 000000 (the black color).

Custom domains

If you are on a paid plan you can serve your images from a custom domain. To do so you have to make your custom domain a CNAME to "api.thumbr.io" (or "cdn.thumbr.io" if you wish to go through our CDN) in your DNS panel and register your custom domain in your profile.

When you use a custom CNAME you can take out the API key from the URL (the domain name uniquely identifies you), making your URLs shorter. For example, these two URLs are equivalent:

http://api.thumbr.io/4f08ba1f94579e2c00146f0fa0d1663d/J.CVKPIdCGo/static.presspeople.com/attachment/44ccf523cadf4d4aa4c531eb3de06eda/720x480/thumb.jpg
http://thumbs.presspeople.com/703f763aee467747512b575fcf5ef740/static.presspeople.com/attachment/44ccf523cadf4d4aa4c531eb3de06eda/720x480/thumb.jpg

You can serve your thumbnails from your own subdomain (ex: thumbs.your-domain.com) or from a subdomain under .thumbr.io.

Types of Subdomains

When you setup a custom domain, we will offer you several options depending on the location of the images that we will serve and the look of the URLs that you want to use:

  • Web url: Your source URLs are stored in different unknown domains. With this option you will have to embed the source URL in the thumbr.io URL.
  • Web folder: Your source URLs all share a common prefix (ex: http://www.my-domain.com/img/)
  • Thumbrio: Your resources are stored in your Thumbrio cloud storage.
  • Amazon S3: Your resources are stored in your Amazon S3 bucket.
  • Dropbox: Your resources are located in your Dropbox folder.
  • Routes: The most flexible setting, you can create a set of regular expressions. With each regular expression you will specify the URL or your resource and the transformation that you want to apply.

Web url

If you have your images, documents, PDFs stored in different unknown domains, you can employ this type of subdomains. This type of subdomain force you to sign the url.

For example: If you want to make a thumbnail of this image http://third-party.domain.com/img/cat.png your thumbnail will be this:

http://thumbs.your-domain.com/HMAC TOKEN/http://third-party.domain.com/img/cat.png/WIDTHxHEIGHTCROP/SEO_NAME.EXTENSION

Notice that the API KEY is not content in the URL because the domain identifies you. Anyway, you are forced to sign your URL in this type of subdomain.

http://api.thumbr.io/HMAC TOKEN/API KEY/http://third-party-1.domain.com/img/cat.png/WIDTHxHEIGHTCROP/SEO_NAME.EXTENSION

Web folder

If you have your resources (images, documents or PDFs) stored in a well-known domain, you can employ this type of subdomains.

For example: If you have to make a thumbnail of this image http://third-party.domain.com/img/animals/cat.png and this one http://third-party.domain.com/img/food/pizza.png, you will be able to configure your subdomain thumbs.your-domain.com to fetch to http://third-party.domain.com/img/. Your thumbnails will look like these:

http://thumbs.your-domain.com/animals/cat.png?size=WIDTHxHEIGHTCROP&ext=EXTENSION
http://thumbs.your-domain.com/food/pizza.png?size=WIDTHxHEIGHTCROP&ext=EXTENSION

Notice, that your URLs is smaller. If your prefer a secure URL, the signature must be located after the domain.

http://thumbs.your-safe-domain.com/HMAC TOKEN/food/pizza.png?size=WIDTHxHEIGHTCROP&ext=EXTENSION

Thumbrio, Amazon S3 and Dropbox

These types of subdomains are useful if our resources (images, documents and PDFs) are stored in the cloud of Thumbr.io, in your Amazon S3 bucket or in your Dropbox account.

For example: If you have to make a thumbnail of these images: storage://img/animals/cat.png and storage://img/food/pizza.png, you will be able to configure your subdomain thumbs.your-domain.com to fetch to storage://img/.

Choosing one among these options, all your thumbnails will look like these:

http://thumbs.your-domain.com/animals/cat.png?size=WIDTHxHEIGHTCROP&ext=EXTENSION
http://thumbs.your-domain.com/food/pizza.png?size=WIDTHxHEIGHTCROP&ext=EXTENSION

Notice, that your URLs is smaller. If your prefer a secure URL, the signature must be located after the domain.

http://thumbs.your-safe-domain.com/HMAC TOKEN/food/pizza.png?size=WIDTHxHEIGHTCROP&ext=EXTENSION

Routes

This sort of subdomain have several advantages:

  • It does not matter where your resources are. You can fetch resources from several domains.
  • You can apply the same Thumbr.io arguments to all URLs which match a rule.
  • Your URLs will be shorter and meaningful.

As an example, We have got some valid routes especified in the next table:

URL Pattern Source Thumbr.io arguments Description
/small/(.*) http://www.my-domain.com/\1 size=100c To serve http://my-domain.thumbr.io/animals/small/cat.png, we will fetch http://www.my-domain.com/animals/cat.png and will crop it to 100px square thumbnail.
/big/(.*) http://other.domain.com/images/\1 size=600x600&effects=nyc To serve http://my-domain.thumbr.io/animals/big/cat.png, we will fetch http://other.domain.com/images/cat.png and will make their width and height a maximum of 600 pixels, and apply our effect NYC.
/avatar/(.*) http://www.third-party.com/img/\1 size=300c To serve http://my-domain.thumbr.io/avatar/cat.png, we will fetch http://www.third-party.com/img/cat.png and will be resized to 300px square thumbnail.

Extra options

Option Description
Security You can sign (or not) all the URLs. As an exception, the Web url subdomain must be always signed.
404 Image An image that will be show when it is raised a 404 Not Found error.
Enable Filters This option is useful if you only want your subdomain to work like a tradicional CDN.