Cloudinary Blog
Learn More

Archive for October 2012

Engine Yard add-on for cloud-based image management

Oct 31, 2012 by Itai Lahan
Tags: Feature, Partnership, Engine-Yard, PaaS, Ruby-on-Rails, PHP, Node
When we first started working on Cloudinary we had a very simple goal in mind - offer a complete alternative to a set of rudimentary, repetitive, universally common web dev tasks. Tasks related to a website's image management needs.
 
As a web developer, you surely found yourself spending considerable time performing the same routine asset management tasks over and over again. Managing image uploads, transformations, manipulations, optimizations, caching and back-ups. Configuring a fast, highly available asset delivery solution. Same tasks, over and over again.
 
Cloudinary was built to streamline all of the above and we're very proud with what we've accomplished with Cloudinary so far. What started as a simple concept, turned out to be a great service that completely solves all your online image management tasks.
 
The fact that took us by surprise was the diversity of frameworks used by our customers. It sometimes felt that each new user has utilized his own web development stack. Ruby developers using Rails or Sinatra, PHP developer using one of the countless PHP frameworks, Python and Django developers, Node.js, Perl, Java, ASP, .NET, iOS, Android and many others.
 
It turns out that as complicated it is to build a highly scalable, highly usable service like Cloudinary, it's still only half of the story. The other half is offering our users a solution that is easy to integrate with their web dev platform of choice. 
 
Lately, we've been hard at work adding client side Cloudinary integration libraries for every major web dev platform and programming language. We've also kept a close eye on the state-of-the-art platform-as-a-service solutions that offered their users a single click integration solutions for a vast array of cloud-based services. Today, we've taken another important step on making Cloudinary even more accessible and easy to use.
 
Without further ado, we're happy to announce our partnership with Engine Yard. 
 
Engine Yard is a senior player in the PaaS field and one of the pioneers of the approach that took cloud computing a step forward: developers take care of the application development only, while Engine Yard takes care of the production platform. You no longer need to manage production servers and complex database architecture. Engine Yard is unique in this field in providing a full management solution for large scale platforms and high-end sites and applications.
 
 
With Engine Yard you have your application deployed in the cloud. Together with Cloudinary, your asset management is also moved into the cloud: upload images, automatically perform smart image resizing, cropping, overlay, watermark, apply effects, rotations, format conversions, without installing any complex software. All your images are then seamlessly delivered through a fast CDN, optimized and using industry best practices. Cloudinary offers comprehensive APIs and administration capabilities and is easy to integrate with new and existing web and mobile applications.
 
Together with Engine Yard, Cloudinary offers a very useful solution for a wide array of use-cases from simple websites, through early stage startups to large scale enterprise applications. If you are already an Engine Yard user, simply add Cloudinary's add-on to your Ruby, PHP and Node.js applications. Cloudinary’s account setup is done automatically for you and billing is handled through your standard Engine Yard payment method. Cloudinary offers a free Starter plan with plenty of room to grow, making it very straightforward to try it out.
 
 

Engine Yard users - want to start using Cloudinary?

  • Go to https://cloud.engineyard.com/addons or navigate to 'Add-ons' in Engine Yard Cloud and click on Cloudinary and start managing your images in the cloud!
  • Engine Yard automatically sets up the correct settings for using your Cloudinary account using the CLOUDINARY_URL variable. 
Ruby on Rails users - simply add the ey_config GEM to your project and add an initializer for Cloudinary's settings:
Cloudinary.config_from_url(EY::Config.get(:cloudinary, 'CLOUDINARY_URL'))
We will soon add additional documentation and sample code for simplifying the Cloudinary - Engine Yard integration even further. Any feedback on our new image management add-on for Engine Yard would be highly appreciated!

Cloud-based animated GIF generation

Oct 10, 2012 by Itai Lahan
Tags: Feature, Image-transformation, Ruby-on-Rails, Django, PHP, Node
Back in the 1990s, websites mainly comprised of static textual pages dashed with a few images to make them slightly more appealing. You could even disable image downloading in your browser to make pages load faster, quite unthinkable in today's websites.
 
In order to make web pages look more alive, developers started looking for animation solutions. Proprietary browser plugins started to appear, followed by a real usability breakthrough - the enhanced, 89a GIF format. As part of its many enhancements, this new format allowed for simple animation sequences. While initially supported only by the Netscape browser, using GIF to add animations has proved quite straightforward and soon became very popular.
 
The modern web supports animations using Flash and HTML5 techniques, but animated GIFs still persist as a way to to create simple, efficient, cross-browser animations. A recent example can be seen at one of the Internet’s greatest innovators and biggest HTML5 early adopter - Apple itself. If you scroll through Apple's iPad features page, you will notice animation scenes depicting the new iPad's capabilities. These animations aren't based on the HTML5 Video format. They are based on dozens of separate JPG images that are pre-loaded and displayed programmatically to achieve a smooth animation effect. In the Design page of Apple's iPhone 5, if you scroll down to the earbuds section, you will notice a smooth animation of rotating earbuds. Again, no videos were used here. This time a more complex solution based on HTML Canvas, JPG images and Javascript is used.
 
In this blog post we wanted to show you how to easily generate simple animations with Cloudinary and how to generate animated GIF files that are still very useful for short animation sequences.
 

Animation building blocks 

Consider the following two images that were uploaded to Cloudinary - a blue cloud icon and three arrows:
 
 
 
With Cloudinary overlays and chained transformations it is very easy to generate an image where the arrows appear above the cloud icon. The following URL first expands the cloud icon to a 280x150 image with white padding and then adds an overlay with the arrows in the top left corner:
 
 
 
We can use the custom overlay coordinates to position the arrows in a different location. We can also apply a brightness effect as the following example shows. The arrows are now positioned 150 pixels from the left. We also applied another cropping transformation to make sure that the final image remains 280x150 even if the arrows overflow outside the original canvas.
 
 
 
Quick side-note - don't you think it's quite amazing what you can accomplish so easily with Cloudinary? If you don't have an account already, you can go ahead and sign up for a free account, we'll wait... (and if we were back in the early 1990s, this link would probably be flashing red :-)
 

Generating Animations

You could probably already guess where we're aiming at. Using the previous overlay concepts and a simple script, we can now create an animation sequence depicting the arrows moving from left to right while growing lighter and lighter until disappearing.
 
The following Ruby script uses Cloudinary's Ruby GEM to generate 34 images that construct the frames of the animation. The same can be easily done using any of our other client libraries (PHP, Python, Node.js, etc.), or directly with our URL-based apis.
 
The script programmatically generates transformation URLs similar to the examples above. Horizontal (X) position of the arrows moving from -50 to 280. Brightness effect increasing while X position increases. The URL is then given to Cloudinary's upload API call to generate a new image based on the given transformation. 
(-5..28).each_with_index do |x, index|
  url = Cloudinary::Utils.cloudinary_url("cloud_icon_right.png", 
   :width => 280, :height => 150, :crop => :crop, :gravity => (x < 0 ? :east : :west),
   :transformation => [
     { :width => 280, :height => 150, :gravity => :west, :crop => :pad },
     { :overlay => "arrows_right", :x => x * 10, :y => 0, :gravity => :west, 
       :effect => (x > 7 ? "brightness:#{(x-7)*4}" : nil) }
   ])
 
  Cloudinary::Uploader.upload(url, 
                :public_id => "arrow_animation_#{index.to_s.rjust(2, "0")}", 
                :tags => "arrow_animation")   
end
Executing the script above, generated 34 images in the cloud. All these images have a public ID formatted as arrow_animated_XX. For example, here's the thirteenth generated frame:
 
 
 
All generated images were assigned with the tag arrow_animation. If you are familiar with Cloudinary, you probably know that a tag can be used to generate a 'sprite' - a single image merging together all images of the same tag. Click on the following links to view the sprite image and generated CSS. You can see all the animation frames in this sprite. 
 
 
As mentioned, Cloudinary now supports easy animated GIF generation. All images sharing a tag can be merged into a single animated GIF, sorted alphabetically by their public IDs.
 
And here it is, the animated GIF generated using an amazingly simply URL. As always, the final image is generated on-the-fly in the cloud and is then cached and delivered through a fast CDN:
 
 
 
This animation might be a little too slow. You can use the 'delay' parameter to change that. The parameter accepts the delay between frames, in milliseconds. Here is a much faster example:
 
 

Summary

Animated GIFs might be a little restrictive with their small 8 bit indexed color space and inefficient lossless compression. Still, these can be quite indispensable in various occasions. 
 
We've shown you how you can programmatically achieve powerful transformations, frame generation and GIF-based animations, easily and efficiently. We hope that these building blocks will be useful for your projects. We're sure that they will give you some interesting ideas of what you can accomplish with Cloudinary!

RESTful API for managing your website's images and other online assets

Oct 09, 2012 by Tal Lev-Ami
Tags: Feature, API, Ruby-on-Rails, Django, PHP, Node
Different online services, websites and mobile applications have very different image management requirements. Despite the differences, the image management pipeline boils down to the same basic formula - upload the images, normalize them, store them and manipulate them to create derivatives (thumbnails, effects, watermarks, etc.). Afterwards, prepare them for delivery and make sure they are accessible to your users quickly and efficiently when browsing your website or using your mobile app.
 
When we set out to build Cloudinary, we envisioned a platform that could streamline an online service's entire asset management pipeline needs. We developed a simple yet powerful URL based API and made integration even simpler using client integration libraries for many web dev platforms and programming languages. It was a joy to see how each of our clients found new ways of utilizing our platform, hooking different API calls to solve scenarios we could barely imagine when Cloudinary was first conceived.
 
In the regular flow of web applications, this works perfectly. But sometimes, you'll want even more fine grained control over your online assets - browse through user uploaded images, find specific images, delete images, delete transformations and more. If you already tried Cloudinary, you probably know that you can use our Management Console for manually achieving such tasks via our web-based user interface. But as many of our customers told us and frequently requested, more control is sometimes required than what they can currently achieve manually.
 
Today, we've made another important step in making the Cloudinary platform even more customizable. 
 
Without further ado, we'd like to welcome Cloudinary's powerful new administrative API, an intuitive RESTful HTTP API for programmatically managing all of your Cloudinary hosted assets.
 

Supported Operations

When building the API, we did our best to cover all common management tasks:
  • Listing all uploaded images and raw files.
  • Receiving details and metadata for uploaded images, including timestamps, format, dimensions, etc.
  • Listing the derived images of uploaded images.
  • Finding all images that share a given tag.
  • Listing all transformations.
  • Listing tags.
  • Receiving transformation details.
  • Creating named transformations.
  • Updating an existing transformation.
  • Deleting images, raw files, derived images and transformations.
 

API Overview

The API is accessed using HTTPS to endpoints in the following format:
 
https://api.cloudinary.com/v1_1/:cloud_name/:action
 
For example, resource listing of the 'demo' account:
 
https://api.cloudinary.com/v1_1/demo/resources/images
 
Authentication is done using Basic Authentication over secure HTTP. Your Cloudinary API Key and API Secret are used for the authentication.
 
Request parameters are appended to the URL. The response is in a simple JSON snippet. Like any REST API, read-only requests are sent in HTTP GET while write requests are sent in PUT, POST and DELETE. 
 
For more details, check out our documentation page.
 
Our client libraries provide an easy to use wrapper for this URL-based API, utilizing your native programming language of choice. Request building and authentication are done automatically, and the JSON response is parsed and returned. 
 

Usage Examples

 
The following Ruby example lists all your Cloudinary hosted images:
$ result = Cloudinary::Api.resources
=> {"resources"=>
  [{"public_id"=>"sample1", 
    "format"=>"png",
    "version"=>1349196740, 
    "resource_type"=>"image", 
    "type"=>"upload",
    "created_at"=>"2012-10-02T16:52:20Z",
    "bytes"=>71376, "width"=>261, "height"=>253,
    "url"=>
     "http://res.cloudinary.com/sam/image/upload/v1349196740/sample1.png",
    "secure_url"=>
     "https://d3jpl91pxevbkh.cloudfront.net/sam/image/upload/v1349196740/sample1.png"},
   {"public_id"=>"sample2", 
    "format"=>"png",
    "version"=>1349196732, 
    "resource_type"=>"image", 
    "type"=>"upload",
    "created_at"=>"2012-10-02T16:52:12Z",
    "bytes"=>133171, "width"=>278, "height"=>432,
    "url"=>
     "http://res.cloudinary.com/sam/image/upload/v1349196732/sample2.png",
    "secure_url"=>
     "https://d3jpl91pxevbkh.cloudfront.net/sam/image/upload/v1349196732/sample2.png"},
 
    ... 
],
 "next_cursor"=>"e39ef944e18cfda7deafa4aea96791e7"}
Here's the same example in PHP:
require "cloudinary.php" ;
require "api.php" ;
$api = new \Cloudinary\Api();
$result = $api->resources();
Python:
import cloudinary.api
result = cloudinary.api.resources()
And Node.js:
var cloudinary = require('cloudinary');  
cloudinary.api.resources(function(result)  { console.log(result) });
By default, 10 results are returned in a single request. You can specify the max_results parameter if you want more results in a single request. You can use this in conjunction with the next_cursor parameter for paginating through all your assets.
 
The next example shows how to get the full details of a single uploaded image, including the list of its derived images:
$ result = Cloudinary::Api.resource("sample1")
=> {"public_id"=>"sample1",
 "format"=>"png",
 "version"=>1349196740,
 "resource_type"=>"image",
 "type"=>"upload",
 "created_at"=>"2012-10-02T16:52:20Z",
 "bytes"=>71376, "width"=>261, "height"=>253,
 "url"=>
  "http://res.cloudinary.com/sam/image/upload/v1349196740/sample1.png",
 "secure_url"=>
  "https://d3jpl91pxevbkh.cloudfront.net/sam/image/upload/v1349196740/sample1.png",
 "next_cursor"=>"f329da74de2a9ac9cbf99d2a6bc147b8",
 "derived"=>
  [{"transformation"=>"c_fill,h_50,r_20,w_70",
    "format"=>"png",
    "bytes"=>7313,
    "id"=>"a3b44a715c63f7ee91f11fb20b97c5df",
    "url"=>
     "http://.../sam/image/upload/c_fill,h_50,r_20,w_70/v1349196740/sample1.png",
    "secure_url"=>
     "https://.../sam/image/upload/c_fill,h_50,r_20,w_70/v1349196740/sample1.png"},
   {"transformation"=>"c_fill,h_75,w_75/jpg",
    "format"=>"jpg",
    "bytes"=>2889,
    "id"=>"7c0ca85b966b928179ce336fa2a7d1f8",
    "url"=>
     "http://.../sam/image/upload/c_fill,h_75,w_75/v1349196740/sample1.jpg",
    "secure_url"=>
    "https://.../sam/image/upload/c_fill,h_75,w_75/v1349196740/sample1.jpg"}]}
And now, the same example in PHP: 
$result = $api->resource("sample1");
Python:
cloudinary.api.resource("sample1")
And Node.js:
cloudinary.api.resource("sample1", function(result)  { console.log(result) })
One final example - getting the details of a single transformation, including a list of all images assigned to this transformation:
$ result = Cloudinary::Api.transformation("c_fill,h_75,w_75/jpg")
 
=> {"name"=>"c_fill,h_75,w_75/jpg",
       "allowed_for_strict"=>false,
       "used"=>true,
        "info"=>[{"width"=>75, "height"=>75, "format"=>"jpg", "crop"=>"fill"}],
        "derived"=>
  [{"public_id"=>"sample1",
    "resource_type"=>"image",
    "type"=>"upload",
    "format"=>"jpg",
    "url"=>
     "http://.../sam/image/upload/c_fill,h_75,w_75/v1349196740/sample1.jpg",
    "secure_url"=>
     "https://.../sam/image/upload/c_fill,h_75,w_75/sample1/sample1.jpg",
    "bytes"=>2889,
    "id"=>"7c0ca85b966b928179ce336fa2a7d1f8"},
  ...
]}
As you can see, the new API is quite powerful. Using this API allows for full control of all uploaded raw files and images, fetched social profile pictures, generated transformations and more. 
 
For more examples and a full reference, see our detailed documentation.
 

Usage Limits 

You can use the new API quite extensively. We ask for that you keep your ongoing API requests to 500 per hour (12,000 daily). If you require more flexible limits, don't hesitate to contact us.
 
For each API call, standard HTTP headers are returned with details on your current usage statistics, including your per-hour limit, remaining number of actions and the time the hourly count will be reset.
 
Here is how these headers might look like:
 
    X-FeatureRateLimit-Limit: 500
    X-FeatureRateLimit-Remaining: 499
    X-FeatureRateLimit-Reset: Wed, 03 Oct 2012 08:00:00 GMT
 
Note that our client libraries provide easy access to the returned limit headers. In Ruby for example:
$ result = Cloudinary::Api.resource_types
 => {"resource_types"=>["image"]} 
$ result.rate_limit_allowed
 => 500 
$ result.rate_limit_reset_at
 => 2012-10-03 10:00:00 +0200 
$ result.rate_limit_remaining
 => 499  
 

Summary 

The new admin API is available for all our free and paid plans. It would be great if you try it out, and tell us what you think. 
We have interesting ideas on how to further enhance this new API. If your want to be in the loop, go ahead and subscribe to our blog or Like Cloudinary on Facebook, and receive our timely updates.

Attachinary - a modern attachments solution for Ruby on Rails

Oct 08, 2012 by Nadav Soferman
Tags: Ruby-on-Rails, CarrierWave, Attachinary
When developing a website you are required for a somewhat tedious work of handling dynamically uploaded content. The constantly added content includes images uploaded by your users and content administrator, user documents and other files.
 
As a developer, you'll be responsible for adding integration of attachments to your application's model and taking care of the upload, normalization, storage, transformation and delivery of such assets.
 
Over time, we've run into a lot of attachment management libraries for many of the web development frameworks available. For Ruby on Rails alone there are CarrierWave, Paperclip, Dragonfly, attachment_fu and quite a few others. 
 
While Cloudinary streamlines all your image management needs and takes care of uploads, storage, transformations, manipulations and delivery, you still need to integrate it with your application's model. To simplify the integration, Cloudinary offers many client libraries for all major web dev platforms and programming languages. For example, Cloudinary's Ruby GEM includes a plugin that seamlessly integrate with CarrierWave for managing uploads and image transformations in the cloud. We've covered this in a previous blog post.
 
Today, we wanted to tell you about a new attachment management library for Ruby on Rails - Attachinary. Attachinary was developed by Milovan Zogovic and it does an amazing job in simplifying attachment management in your application's model. 
 
We've tried Attachinary, really liked it and wanted to share our experience working with it. 
 

How is Attachinary different? 

There are so many other attachment management libraries, why do we need another one? 
Well, here are a few reasons:
 
  • Attachinary offers non-intrusive integration with ActiveRecord and Mongoid model. You no longer need to maintain DB columns in your model entities for referencing uploaded images.
  • With attachinary it's very easy to switch between a single image and multiple images for a model entity.
  • Attachinary allows for simple integration through Rails 3.2's modern Asset Pipeline.
  • Attachinary uses Cloudinary for uploading files to the cloud, transforming images and delivering files through a fast CDN. No need to install any image manipulation software.
  • Attachinary has built-in integration with Cloudinary's jQuery-based direct upload from the browser. Progress indication and image preview included.
  • Attachinary is extremely simple to use and requires minimal changes to your existing code base.
 

How is Attachinary used?

After a very quick Cloudinary & Attachinary GEM installation and setup, you can add any attachment attribute to your model class. The following code shows a User model entity:
class User < ActiveRecord::Base
  attr_accessible :name
  
  has_attachment  :avatar
  has_attachments :photos, :maximum => 3
end
The 'has_attachment' and 'has_attachments' methods were used to define a User that can have a single 'avatar' and up to 3 'photo' attachments. That's it, no additional migrations or code changes are required.
 
Uploading assets to Cloudinary is also very simple with Attachinary. The following HAML view code shows how to create an upload form. The 'attachinary_file_field_tag' view helper method is responsible for all the magic. When this form is submitted, all images will be automatically uploaded to the cloud directly from your website visitor's browser. Multiple photos can be uploaded from this same form and the identifiers of the uploaded images will be automatically stored in your model.
= form_for(@user) do |user_form|
    = user_form.text_field(:name)
    = attachinary_file_field_tag 'user[avatar]', @user, :avatar
    = attachinary_file_field_tag 'user[photos]', @user, :photos
    
    = user_form.submit("Save")
Model management in your controller is exactly the same as always:
def create
  @user = User.new(params[:user])
  @user.save!
end
You can display uploaded images, generate thumbnails and apply image transformations by using Cloudinary's cl_image_tag. Here's an example of a view code that displays a 80x100 face detection based thumbnail of the user's avatar and a 70x50 rounded corner version of all uploaded photos.
- if user.avatar.present?
  = cl_image_tag(user.avatar.path, :width => 80, :height => 100,
                 :crop => :thumb, :gravity => :face)        
  - user.photos.each do |photo|
    = cl_image_tag(photo.path, :size => '70x50', :crop => :fill, :radius => 20)
Using attachinary allows you to dynamically apply any image transformation supported by Cloudinary. All transformed images are generated on-the-fly in the cloud and are then cached and delivered through a fast CDN.
 
Last but not least - Attachinary also supports non-image raw files.
 

Summary 

We hope that with this quick introduction, we've managed to pique your interest about Attachinary. Together with Cloudinary, Attachinary is really easy to use and also very powerful. Attaching images to your Rails model has never been easier. 
 
For more details, setup instructions and usage examples, check out Attachinary's page at GitHub.
 
If you are a Rails developer, you should definitely give it a try.