Most developers are familiar with ImageMagick, a very capable open source software suite that they can use to manage and manipulate images.

The functionality of ImageMagick is typically utilized from the command-line, but wrappers have been written for a wide selection of programming languages, making ImageMagick a very popular choice among developers.

Often programmers use ImageMagick for simple operations such as scaling or stretching an image to fit specific dimensions. But as we'll see in this post, there are many advanced techniques available, such as 'masking’, pixel 'blending' and others that enable you to achieve more complex and extremely useful effects.

In this post, I’ll share three examples of image manipulations using RMagick (a Ruby wrapper for ImageMagick). I will start with a sepia effect combined with an overlay image, and follow that with increasingly complex manipulations such as creating text textures and pixelating faces. For each of these examples, I’ll compare what it takes to address the same challenges using Cloudinary. With its cloud-based platform, Cloudinary eliminates the complexity of coding and the hassles associated with installation. Cloudinary also saves developers time, enabling them to leverage a single line of code to complete the image manipulations.

Dependencies and Installation

You can find the full source code for this blog post in Cloudinary’s official repository in Github. Installing the dependencies for the examples is not a trivial task, mostly because of OpenCV. But for simplicity’s sake, I’ve containerized both ImageMagick and OpenCV dependencies, so you only need to have Docker installed.

Example 1: Sepia effect with text overlay

The first example describes a common use case: Adding a photographer's name to the bottom right corner of an image.
To make the example more interesting, we first want to apply a sepia effect.
The final result should look something like this:

The ImageMagick way:

The example is built using two main methods:

• add_author_to_image!, which receives a Magick::Image object and the author name and returns a new Magick::Image object that contains the resulting image - the original image with the author name overlay applied.
• sepiatize_image!, which receives a Magick::Image object and returns the modified image object with the sepia effect applied.

First, let’s describe add_author_to_image!:
Using ImageMagick, I create a Draw object, which will enable me to put the text over the original image.
I also select the color “white”, “Arial” as the font, and choose my font size.

text = Magick::Draw.new
text.fill = "white"
text.font_family = "Arial"
text.pointsize = 30
text.gravity = Magick::CenterGravity

The overlay image size should match the text dimensions, so I need to calculate the text dimensions before creating the overlay image:

metrics = text.get_type_metrics(author)

I then create the overlay image and set its background color to a semi-transparent black to ensure that the text will be visible on top of any image.

author_overlay = Magick::Image.new(metrics.width, metrics.height) {
  self.background_color = "#00000080"
}

Next, I draw the text over the the semi-transparent background.

text.annotate(author_overlay, 0, 0, 0, 0, author)

Then I position the author overlay on top of the image:

I use the composite method to combine the two images in a certain way. The destination image is our input image. I have to tell ImageMagick that I want to position the author overlay in the “southeast” edge of the image. Magick::OverCompositeOp tells ImageMagick that the source image (author_overlay) should override the destination image (our input image) with the source image’s pixels, which makes the author name visible on top of the image.

image.composite!(author_overlay, Magick::SouthEastGravity, Magick::OverCompositeOp)

The final step is destroying the author image object overlay. It’s important to clean up any temporary image objects. I don’t need the overlay anymore because I’ve combined the images and flattened them. Destroying an image object is done using the destroy! method:

author_overlay.destroy!

What’s missing now is the sepia effect (applied by the sepiatize_image! method).
ImageMagick offers a method for setting sepia tone, so I chose the sepia level and set the desired effect.

SEPIA_LEVEL = Magick::QuantumRange * 60 / 100
def sepiatize_image!(image)
  image.sepiatone(SEPIA_LEVEL)
end

After defining the two methods, we need to apply both operations on our original image and write the result to a file:

add_author_to_image!(sepiatize_image!(source_image), author).write(dest)

Whew! I’m sweating a bit, but I managed to get the result I wanted.

The Cloudinary way:

If this is your first time using Cloudinary, you’ll need sign up for an account (start with a free one), and use the upload API to upload your image. You can use the https API with no installation required, or download and install the SDK for your favorite framework (a few quick configurations required).

Here’s how you would upload the yellow_tulip.png file to your account in the cloud using the Ruby SDK:`

Cloudinary::Uploader.upload('yellow_tulip.png', :public_id => 'yellow_tulip')

Now, let’s see what it takes to deliver that image in sepia with the photographer’s name in the corner. Ready?

cl_image_tag("yellow_tulip.png", :secure=>true, :transformation=>[
  {:effect=>"sepia:60"},
  {:overlay=>"text:Arial_30:John%20Doe%20Photography%20%C2%AE", :color=>"white", :gravity=>"south_east", :background=>"#00000090"}
  ])

cl_image_tag("yellow_tulip.png", array("secure"=>true, "transformation"=>array(
  array("effect"=>"sepia:60"),
  array("overlay"=>"text:Arial_30:John%20Doe%20Photography%20%C2%AE", "color"=>"white", "gravity"=>"south_east", "background"=>"#00000090")
  )))

CloudinaryImage("yellow_tulip.png").image(secure=True, transformation=[
  {"effect": "sepia:60"},
  {"overlay": "text:Arial_30:John%20Doe%20Photography%20%C2%AE", "color": "white", "gravity": "south_east", "background": "#00000090"}
  ])

cloudinary.image("yellow_tulip.png", {secure: true, transformation: [
  {effect: "sepia:60"},
  {overlay: "text:Arial_30:John%20Doe%20Photography%20%C2%AE", color: "white", gravity: "south_east", background: "#00000090"}
  ]})

cloudinary.url().transformation(new Transformation()
  .effect("sepia:60").chain()
  .overlay("text:Arial_30:John%20Doe%20Photography%20%C2%AE").color("white").gravity("south_east").background("#00000090")).secure(true).imageTag("yellow_tulip.png")

$.cloudinary.image("yellow_tulip.png", {secure: true, transformation: [
  {effect: "sepia:60"},
  {overlay: "text:Arial_30:John%20Doe%20Photography%20%C2%AE", color: "white", gravity: "south_east", background: "#00000090"}
  ]})

cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Effect("sepia:60").Chain()
  .Overlay("text:Arial_30:John%20Doe%20Photography%20%C2%AE").Color("white").Gravity("south_east").Background("#00000090")).Secure(true).BuildImageTag("yellow_tulip.png")

Done!

Example 2: Text Textures

In this example, which is a bit more complex than our first one, I will use our source image as a texture effect on specified text with a selected font, so that it will look something like this:

The ImageMagick way:

I will employ the concept of masking in this example.
Let's create a 'mask' image in the shape of our desired text and font. I do this using the create_text_mask method, which receives the text as a string and returns a 'mask' Image object.
The following is a short walkthrough:

Like in the previous example, I create a Draw object, which is being used for the text.
I then add color, font family, size and weight, and get a type metric to create our ‘mask’ image object with the dimensions I calculated.

Then I create a new Image object and set it's background to transparent:

draw = Magick::Draw.new
draw.fill = "white"
draw.font_family = "Arial"
draw.pointsize = 100
draw.font_weight = Magick::BoldWeight
draw.gravity = Magick::CenterGravity
metrics = draw.get_type_metrics(text)
mask = Magick::Image.new(metrics.width, metrics.height) { self.background_color = "transparent" }

Like in the previous example, I use the draw object’s annotate method to actually draw the text over the image I’ve created.

draw.annotate(mask, 0, 0, 0, 0, text)

The result is a semi transparent image having the text itself in fully opaque "white" and the rest - fully transparent.

Let's move to the cut_image_to_text! method which calls create_text_mask:
After creating the mask image by calling create_text_mask, using the composite method, I combine the 'mask' image and our input image, but this time relying on a different type of composite operator: CopyOpacityCompositeOp.
Doing this changes the opacity value of all pixels in our input image that are not part of the text letters region, to fully transparent. This hides the pixels and results in a texture effect over the fonts:

image.composite!(mask, Magick::CenterGravity, Magick::CopyOpacityCompositeOp)

Next, I have to clean up by destroying the mask image, which isn't needed anymore.

mask.destroy!

Then I trim the remaining transparent border and tighten up the image to the text itself.

image.trim!

At this point I’m almost done, but there’s one last thing to take care of.
A lot of formats – like JPEG – don’t have an alpha channel to support opacity. So, if you export the image now in one of those non-alpha formats, you’ll see the original image since all 'hidden' and 'fully transparent' pixels from our last step will not preserve their transparency. As a result, I’ll need to turn all transparent pixels to “opaque white”, which will make sure I get a uniform result no matter what the desired format is. This will be done using the simple opacify! method.

Here I set the background color to white:

opacified = Magick::Image.new(image.columns, image.rows) { self.background_color = "white" }

Then I put the cut-to-text image that I created in the previous step on top of the new image with the white background color. This causes all transparent pixels from before to turn white.

opacified.composite!(image, Magick::CenterGravity, Magick::OverCompositeOp)

After defining the relevant methods, I apply them on the original image and write the result to a file:

opacify!(cut_image_to_text!(source, text)).write(dest)

Impressive! We did it!

The Cloudinary way:

You’d think this example would take a bit more effort than the previous one, even in Cloudinary. But with a combination of text overlay capabilities and the built-in cutter flag, here’s all we need to do:

cl_image_tag("yellow_tulip.png", :overlay=>"text:Arial_100_bold:Flowers", :flags=>"cutter", :secure=>true)

cl_image_tag("yellow_tulip.png", array("overlay"=>"text:Arial_100_bold:Flowers", "flags"=>"cutter", "secure"=>true))

CloudinaryImage("yellow_tulip.png").image(overlay="text:Arial_100_bold:Flowers", flags="cutter", secure=True)

cloudinary.image("yellow_tulip.png", {overlay: "text:Arial_100_bold:Flowers", flags: "cutter", secure: true})

cloudinary.url().transformation(new Transformation().overlay("text:Arial_100_bold:Flowers").flags("cutter")).secure(true).imageTag("yellow_tulip.png")

$.cloudinary.image("yellow_tulip.png", {overlay: "text:Arial_100_bold:Flowers", flags: "cutter", secure: true})

cloudinary.Api.UrlImgUp.Transform(new Transformation().Overlay("text:Arial_100_bold:Flowers").Flags("cutter")).Secure(true).BuildImageTag("yellow_tulip.png")

Example 3: Pixelating Faces

For my last example, I will show how to combine face detection with a pixelation effect, which is really useful for hiding people’s identities in public photos. Here’s what our final image will look like:

The ImageMagick way:

This example involves use of the OpenCV library and the ruby-opencv gem. My code in this example is written in a flexible way that enables easy swapping of the face detection part to any other library or implementation (modify the detect_faces method to one of your liking, but you must make sure it returns an array of regions).

First, let’s have a look at the transform_faces method.
I’m creating a Magick:Image object out of this file, which I took from the user’s input, similar to the way I’ve done in our first two examples.

image = Magick::Image.read(image_file).first

Then I detect faces for the image file. This process, which is done outside of ImageMagick, returns a collection of face regions.

detect_faces(image_file).each do |region|
  transform_region!(image, region, operation)
end

Next, for each region, I call transform_region! over the image object. The transform_region method has top_left and bottom_right attributes, each with an X,Y value. Here I crop a new image out of the original image at the exact region that was identified.

cropped_region = image.crop(region.top_left.x, region.top_left.y, region.width, region.height)

Then I call a method for the operation that I want to do with this cropped region image.

cropped_region = send("#{operation}_image!", cropped_region)

In the example code in the repository, I pick an operation called pixelate. However, you also could select “blur” if that treatment was preferred:

PIXELATE_FACTOR = 5
def pixelate_image!(image)
  image.scale!(1 / PIXELATE_FACTOR.to_f).scale!(PIXELATE_FACTOR)
end

Back to transform_region!: I need to set the "transformed" region on top of the original image, using composite again at the X,Y position. After that is complete, I flatten the image and then clean it up by destroying the cropped image region.

image.composite!(cropped_region, region.top_left.x, region.top_left.y, Magick::OverCompositeOp)
cropped_region.destroy!

Not bad, huh?

The Cloudinary way:

By now, you have probably come to expect that you can accomplish the same goal with Cloudinary in one line of code, right? Yup!

Cloudinary has a built-in automatic face detection mechanism that enables, among other things, quick pixelation (or blurring) of all faces in a photo:

Pixelating faces

cl_image_tag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", :secure=>true, :type=>"fetch", :transformation=>[
  {:effect=>"pixelate_faces"},
  {:width=>500, :crop=>"scale"}
  ])

cl_image_tag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", array("secure"=>true, "type"=>"fetch", "transformation"=>array(
  array("effect"=>"pixelate_faces"),
  array("width"=>500, "crop"=>"scale")
  )))

CloudinaryImage("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg").image(secure=True, type="fetch", transformation=[
  {"effect": "pixelate_faces"},
  {"width": 500, "crop": "scale"}
  ])

cloudinary.image("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", {secure: true, type: "fetch", transformation: [
  {effect: "pixelate_faces"},
  {width: 500, crop: "scale"}
  ]})

cloudinary.url().transformation(new Transformation()
  .effect("pixelate_faces").chain()
  .width(500).crop("scale")).secure(true).type("fetch").imageTag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg")

$.cloudinary.image("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", {secure: true, type: "fetch", transformation: [
  {effect: "pixelate_faces"},
  {width: 500, crop: "scale"}
  ]})

cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Effect("pixelate_faces").Chain()
  .Width(500).Crop("scale")).Secure(true).Type("fetch").BuildImageTag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg")

Blurring faces

cl_image_tag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", :secure=>true, :type=>"fetch", :transformation=>[
  {:effect=>"blur_faces"},
  {:width=>500, :crop=>"scale"}
  ])

cl_image_tag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", array("secure"=>true, "type"=>"fetch", "transformation"=>array(
  array("effect"=>"blur_faces"),
  array("width"=>500, "crop"=>"scale")
  )))

CloudinaryImage("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg").image(secure=True, type="fetch", transformation=[
  {"effect": "blur_faces"},
  {"width": 500, "crop": "scale"}
  ])

cloudinary.image("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", {secure: true, type: "fetch", transformation: [
  {effect: "blur_faces"},
  {width: 500, crop: "scale"}
  ]})

cloudinary.url().transformation(new Transformation()
  .effect("blur_faces").chain()
  .width(500).crop("scale")).secure(true).type("fetch").imageTag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg")

$.cloudinary.image("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg", {secure: true, type: "fetch", transformation: [
  {effect: "blur_faces"},
  {width: 500, crop: "scale"}
  ]})

cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Effect("blur_faces").Chain()
  .Width(500).Crop("scale")).Secure(true).Type("fetch").BuildImageTag("http://upload.wikimedia.org/wikipedia/commons/4/45/Spain_national_football_team_Euro_2012_final.jpg")

Conclusion

ImageMagick is a flexible, capable, open source software suite that developers have used to manage and manipulate images for years. As we saw in this post, ImageMagick can be utilized to do so much more than simply resizing an image.

At Cloudinary, we make use of ImageMagick for a wide range of use cases, and it serves as one of the valuable tools in our toolbelt.

Cloudinary abstracts the complexities of image manipulation, storage, administration and delivery and provides developers with an easy-to-use, end-to-end, cloud-based solution. Cloudinary enables developers to focus on creating their apps and presenting the best images possible.

If you haven't tried Cloudinary yet, I invite you to test it out. Visit our website to sign up for a account

There are lots of images and videos all over the internet. A lot of applications these days demand that the user is able to manipulate files and upload to the server. Thankfully, PHP provides the functions to handle file uploads.

In this post, I’ll show you two ways of handling file uploads with PHP:

• The Barebones PHP way
• Using Cloudinary’s Cloud Service - Cloudinary is an end-to-end solution for all your image and video-related needs. It allows you to securely upload images or any other file at any scale from any source. Cloudinary also provides an API for fast upload directly from your users’ browsers or mobile apps. Check out Cloudinary’s documentation for more information on how to integrate it in your apps.

PHP upload - The barebones way

Let’s quickly get started on how to handle file upload with PHP, the barebones way. We need:

1. The HTML Form

You need to build up an HTML form that will contain the fields that the user will interact with to upload a file. Create an index.html file in your root directory and add the following code to it:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>File Upload with PHP</title>
</head>
<body>
    <form action="fileUpload.php" method="post" enctype="multipart/form-data">
        Upload a File:
        <input type="file" name="file" id="fileToUpload">
        <input type="submit" name="submit" value="Upload File Now" >
    </form>
</body>
</html>

In the code above, we have a form with one input field and a submit button. The form tag has an action attribute that points to the script that will take care of the actual upload process. It also has a method attribute that specifies the kind of operation this form will undertake, which is a POST action.

The value of the enctype attribute is very important. It determines the content-type that the form submits. If we were not dealing with file uploads, then we would not specify the enctype attribute on the form in most cases.

Spin up your PHP server like so:

You should see something similar to this come up on your web page:

Note: Different browsers, such as Safari, Edge, Firefox and Chrome might display the form in different ways.

2. PHP Upload Script

There are lots of things to consider when dealing with file uploads. I’ll highlight the common ones in form of questions.

• In which directory will the files be stored?
• Is the directory writable?
• What type of files should the users be allowed to upload?
• What is the maximum file size that the server should allow?
• Should the user be allowed to upload the same image more than once?

Create a file, fileUpload.php, in the root directory and add this code to it:

<?php
    $currentDir = getcwd();
    $uploadDirectory = "/uploads/";

    $errors = []; // Store all foreseen and unforseen errors here

    $fileExtensions = ['jpeg','jpg','png']; // Get all the file extensions

    $fileName = $_FILES['myfile']['name'];
    $fileSize = $_FILES['myfile']['size'];
    $fileTmpName  = $_FILES['myfile']['tmp_name'];
    $fileType = $_FILES['myfile']['type'];
    $fileExtension = strtolower(end(explode('.',$fileName)));

    $uploadPath = $currentDir . $uploadDirectory . basename($fileName); 

    if (isset($_POST['submit'])) {

        if (! in_array($fileExtension,$fileExtensions)) {
            $errors[] = "This file extension is not allowed. Please upload a JPEG or PNG file";
        }

        if ($fileSize > 2000000) {
            $errors[] = "This file is more than 2MB. Sorry, it has to be less than or equal to 2MB";
        }

        if (empty($errors)) {
            $didUpload = move_uploaded_file($fileTmpName, $uploadPath);

            if ($didUpload) {
                echo "The file " . basename($fileName) . " has been uploaded";
            } else {
                echo "An error occurred somewhere. Try again or contact the admin";
            }
        } else {
            foreach ($errors as $error) {
                echo $error . "These are the errors" . "\n";
            }
        }
    }


?>

Look at the code above.

• $fileName = $_FILES['myfile']['name']; This refers to the real name of the uploaded file.
• $fileSize = $_FILES['myfile']['size']; This refers to the size of the file.
• $fileTmpName = $_FILES['myfile']['tmp_name']; This is the temporary uploaded file that resides in the tmp/ directory of the web server.
• $fileType = $_FILES['myfile']['type']; This refers to the type of the file. Is it a jpeg or png or mp3 file?
• $fileExtension = strtolower(end(explode('.',$fileName))); This grabs the extension of the file.
• $uploadPath = $currentDir . $uploadDirectory . basename($fileName); This is the path where the files will be stored on the server. We grabbed the current working directory.

In the code, we are checking to ensure that only jpeg and png files can be uploaded.

if (! in_array($fileExtension,$fileExtensions)) {
            $errors[] = "This file extension is not allowed. Please upload a JPEG or PNG file";
        }
// Checks to ensure that only jpeg and png files can be uploaded.

We are also checking that only files less than or equal to 2MB can be uploaded.

if ($fileSize > 2000000) {
            $errors[] = "This file is larger than 2MB. It must be less than or equal to 2MB";
        }
// Checks to ensure the file is not more than 2MB

Note: Before you try out your code again, you need to ensure that there are some configurations in place.

• Make sure the uploads/ directory is writable. Run this command: chmod 0755 uploads/ on your terminal to make the directory writable.

• Open your php.ini file and ensure that these constants have correct values like:

  • max_file_uploads = 20
  • upload_max_size = 2M
  • post_max_size = 8M

Now, run the code again. Your file should upload successfully to the uploads directory.

Note: There are many checks you should consider when handling file uploads, including security precautions . You really don’t want someone uploading a virus to your web server. Do you? So by all means don’t use this exact code above in production. Add more valuable checks!

Also, it’s recommended that you upload your files to a dedicated file server, not just your web application server. Check out the source code for a tutorial.

Handling File Upload With Cloudinary

Cloudinary provides an API for uploading images and any other kind of file to the cloud. These files are safely stored in the cloud with secure backups and revision history.

Cloudinary provides a free tier where you can store up to 75,000 images & videos with a managed storage of 2GB. 7500 monthly transformations and 5GB monthly net viewing bandwidth.

Cloudinary already takes away the pain of having to write large amounts of code to interact with their API by providing an open source PHP library that ships with simple, easy-to-use helper methods for:

1. Image uploading
2. Image administration and sprite generation
3. Embedding images
4. Building URLs for image transformation and manipulation

The process is this simple!

1. Sign up for a Cloudinary Account

Cloudinary Dashboard - Your cloud name, API Key, Secret are key valuables to interact with Cloudinary functionalities.

2. Fetch the Cloudinary PHP library

The second step to uploading your images to Cloudinary using PHP is fetching the library using composer. If you don’t have composer, navigate here, make sure you copy all required files and paste them in your app, then reference them as follows in the script where you want to perform the upload:

// importing the necessary Cloudinary files
require 'Cloudinary.php';
require 'Uploader.php';
require 'Helpers.php';
require 'Api.php';
.....

3. Server-side upload

You can upload images or any file to Cloudinary from your PHP code running on at least a PHP 5.3 server. First, we have to set up our key valuables using the config method, so that Cloudinary can recognize that it’s a valid account:

\Cloudinary::config(array(
    "cloud_name" => "my_cloud_name",
    "api_key" => "my_api_key",
    "api_secret" => "my_api_secret"
));

Note: I recommend that you load these key valuables from an environment file (.env) to avoid people getting ahold of your config details.

You can put this in a file called settings.php and just include it in the script that performs the actual uploading.

Now you can use the following methods to upload images or files to Cloudinary’s cloud platform:

Uploading a local file:

 \Cloudinary\Uploader::upload("/home/my_image.jpg")

Uploading a file from a remote HTTP(s) URL:

\Cloudinary\Uploader::upload("http://www.example.com/image.jpg")

Uploading a file from an S3 bucket:

\Cloudinary\Uploader::upload('s3://my-bucket/my-path/my-file.jpg');

Note: Every file uploaded to Cloudinary is assigned a Public ID that can later be used for transformation and delivery.

The basic syntax for uploading your files with PHP to Cloudinary is:

public static function upload($file, $options = array())

Let’s cover a few examples of what can be passed to the $options array argument.

Specifying a custom Public ID:

You want to specify a custom Public ID? Here, you go:

\Cloudinary\Uploader::upload('my_image.jpg', array("public_id" => "manutd_id"));

Use the original name of the uploaded file:

You want to preserve and use the original name of the uploaded file? Here, you go:

\Cloudinary\Uploader::upload('sample.jpg', array("use_filename" => TRUE));

Upload an image, video, or a raw file:

Not sure whether a user will upload an image, video, or a raw file? Here, you go:

\Cloudinary\Uploader::upload("spreadsheet.xls", array("resource_type" => "auto"));

Note: See here for all available upload options.

Conclusion

We have successfully covered how to handle file uploads with PHP. Now, the hassle associated with file uploads should be a thing of the past. Storing your files on your host server also should be a thing of the past. Offload files to dedicated cloud storage services like Cloudinary and let them bear the headache of serving the files securely to your web app via CDN!

Prosper Otemuyiwa is a Food Ninja, Open Source Advocate & Self-acclaimed Developer Evangelist.

In Part 1 of this series, I discussed (rather abstractly) what it means for an image to be “responsive.” In short, a responsive image is a variable image that adapts to fit variable contexts, in order to provide a great experience to users no matter what their screen, browser, network connection, or device may be.

That adaptive variability can take many forms; the most common and impactful of these is adaptive, variable, image resolution.

Fixed vs Fluid

Bitmap images have a fixed resolution: they contain a fixed number of pixels. Images on the web, however, are fluid, and the number of pixels that they occupy in layouts and on screens can vary.

Here’s an example. Let’s say we have an image—

—and we want to share it with the world. We put it on a website, and load that site on our phone:

It looks pretty sharp! Proud of our work, we send the URL to a friend, who just so happens to have a brand new 5K display:

He’s, well, less than impressed. The problem? Our original image has a resolution of 800 × 600 — so while it looks sharp-as-a-tack on our 750 × 1334 iPhone 7 screen, it looks horribly blurry when scaled to fit our friend’s 5120 × 2880 monster.

Crispness in this (extreme!) context requires a (much!) bigger image:

To fill our friend’s 5K screen, our image would need almost 40 times more data. This super-sized file would, all by itself, outweigh the average webpage and take forever to load over anything but the fastest internet connections. Worst of all, on smaller (and far more common) screens, our giant image would ultimately be downscaled to fit, and all of those extra pixels would be useless.

Multiple, alternate versions

So – should we use high-resolution images in order to take advantage of high-resolution hardware? Or should we use small images, which will load fast in low-resolution environments?

The answer, of course, is an emphatic “yes” to both, and everything in-between! We can and should include multiple, alternate versions of our images –

— and make sure that we only send high-resolution versions to users who need them, while still sending low-resolution versions to everyone else.

This concept is simple enough, and the the HTML feature that allows developers to supply those multiple alternates is straightforward, too; it’s called srcset.

But the devil is in the details, and figuring out—

1. how many different versions you actually need
2. what their resolutions should be
3. and how to intelligently pick and load one of them from the set

—is surprisingly tricky! We’ll tackle each of those problems in turn.

How many versions, at what resolutions?

In order to serve users in varying contexts well, we need to supply our image in multiple, alternate resolutions. But how many versions do we need, and what should their resolutions be?

This is a hard question, so let’s break it into smaller pieces. We can start by thinking about the limits: what are the largest and smallest resolutions that we’ll need? In order to figure that out, we need to consider: what are the largest and smallest sizes that our image can grow/shrink to on our layout? And what display sizes and densities do we actually care about supporting?

Once we’ve established the limits of our range, we need to figure out how to fill it in.

For web devs, more resources means more to manage.

For users, more resources means less waste. But also, more HTML to download, and fewer cache hits, resulting in, paradoxically, slower loads.

How should we navigate these conflicting priorities? Initially, most developers threw up their hands and picked a more-or-less arbitrary step size, in pixels. Jason Grigsby pioneered the idea that we can be smarter about this by using file-size-based steps, instead. So rather than having versions that were, say, 600, 800, and 1000 pixels-wide, we would generate versions that weighed 60 kB, 80 kB, and 100 kB.

Why? Because different images can have surprisingly different compression characteristics, and we care much more about the wasted bytes when we load an over-sized image, than we do wasted pixels.

Cloudinary thought that this file-size-based “responsive image breakpoint” strategy was pretty smart, and built the Responsive Images Breakpoints Generator in order to help developers implement it. The Generator allows you to input a high-res original image and pick a maximum resolution, minimum resolution, and step-size in kilobytes; it then generates a full set of alternate resources and provides a convenient download link along with the markup you need to include them all in your HTML. Neat!

Pickin’ problems

Now that we’ve marked up a set of multiple, alternate resources – how should browsers pick and load the most appropriate resource out of the set?

In order to choose, browsers need to know how many pixels are in this box:

Once they know that, they can pick the version that best fills the box. But! That box-size is determined by a number of things:

1. the viewport size
2. the screen density
3. the page layout

The viewport size and screen density are always known to the browser. Page layout, however, is where things get sticky.

When loading a webpage and parsing its HTML, browsers begin loading external resources (like CSS and images) as soon as they see their URLs in the markup. This is good for performance – image bytes account for 68% of the web, and we want to start moving those bytes across the network as soon as possible. But it’s bad for layout-aware image loading, as it means that browsers don’t, won’t, and can’t wait for layout before kicking off image loads. The load-it-as-soon-as-you-see-it strategy means that we, as web developers, must choose between:

• intentionally delaying image loads and waiting for page layout to complete so that we know how many pixels of resolution we actually need, before loading a given image
• kicking off image loads as soon as we possibly can (without knowing how many pixels we’ll actually need)

In other words: do we want our images to be resolution-responsive, or loaded without delay? Because – without adding something else to this equation – we can’t have both.

Solutions

In some contexts, delayed, resolution-adaptive-sizing isn’t a problem. If an image is lazy-loaded (or even just below-the-fold), we can afford to wait for layout. The Cloudinary Javascript library and libraries like Alexander Farkas’ lazy-sizes circumvent the browser’s normal image loading mechanisms and responsively load images – after layout – with Javascript.

But if we want our resolution-responsive images fast, we need to short-circuit the normal flow of information. We need to tell the browser the layout size of the image directly in markup.

This is what the sizes attribute is for. sizes declarations have a reputation for being difficult to read and I know from bitter experience that they can be tricky to write. Because the attribute was explicitly designed to break the separation of concerns and duplicate a little bit of layout information right there in markup, the most challenging thing about sizes might be maintenance; sites whose layout is subject to frequent tweaking will especially suffer.

The reason that I love sizes despite its difficulties, is that it addresses the how-do-we-know-about-the-layout-before-we-know-about-the-layout problem head on, directly giving browsers the minimum amount of information that they need to start loading resolution-responsive images as soon as possible.

As such, sizes is required when using the srcset attribute with w descriptors – which is the standard (and universally supported!) pattern for implementing resolution-adaptive responsive images.

Problematic, but possible

Fast, resolution-responsive images can be a bit tricky to implement, but the the payoff is enormous. By supplying multiple versions of each image, and using either Javascript or srcset and sizes to pick amongst them, we can ensure that every user – whether they’re on a phone, 5K display, or anything in between – gets a version of our image with just enough resolution to look great on their display.

Join us next time, when we’ll talk about another, vital, way that images can vary: variable image encoding.

Demos and more

• Cloudinary’s official responsive images documentation
• An in-depth tutorial on using srcset, sizes, and Cloudinary.
• An introduction to Cloudinary’s Javascript-based responsive images solution.
• Yoav Weiss on variable-width images
• The srcset, sizes, and responsive image breakpoints sections of Jason Grigsby’s 10-part Responsive Images 101 series (already linked above, but down here again, for good measure!)
• A three part interview with Jason, about the history and future of responsive images.
• Cloudinary’s introduction and update to the Responsive Images Breakpoint Generator.
• Finally, as a bit of advanced-topics extra credit: yours truly on making the complexity of srcset the server’s problem using w_auto and Client Hints.

With the decreasing price-performance ratio of computing, research efforts in face detection and face recognition algorithms are rapidly expanding and new techniques for both of these are achieving greater accuracy and reduced processing time.

Face detection is a technology that identifies whether and where human faces are located in digital images. It’s commonly used in cameras, security applications, graphic applications, and a variety of other web and mobile apps. It is also a prerequisite for face recognition, which uses a database and additional algorithms to match a detected face with a specific individual.

A large percentage of the images in most websites and apps include photos of people -- from profile pics to news articles to group selfies. These photos need to be displayed in sizes, shapes, and styles that match the site design. Performing automatic face cropping or otherwise programmatically modifying images that contain faces necessitates a reliable face detection mechanism. The reliability can be affected by the colors, or lack of colors in the image, the direction a person is facing, the tilt of the head, the size of a face, the complexity of the background, lighting, and more.

Cloudinary provides a complete image and video management solution for web and mobile app programmers. Our solution includes a built-in image face detection functionality and several face-detection features you can take advantage of in your own apps. In most cases, applying this functionality is just a question of adding a parameter or two to your image delivery URLs… and your own creativity, of-course.

Cloudinary recently updated its face detection mechanism. The new mechanism is now very efficient and precise, including many "difficult" scenarios such as side portraits, blurry faces, tricky lighting, and more.

For example, the people in these images are now easily detected despite low lighting, unusual shadows, black and white images, turned heads and closed eyes:

The rest of this blog will cover some of the many ways that developers can automatically manipulate proprietary and user-generated photos containing faces to fit the needs and design of a website or app.

Facing it head on

Perhaps one of the most common uses of face detection is for cropping. A large percentage of images, especially with user-generated content, contain photos of people.

Headshots are needed for profile pictures, chat heads, and more, but the original uploaded photo may include much more than just a face, and that face may not even be the central element in the photo. Group selfies are also popular, and rarely centered, so again, we need to be very careful that even if we crop the photo to a different aspect ratio, we don’t lose any of the crew.

In short, it’s critical in most situations that when we resize and crop uploaded photos, we keep our users’ faces up front and center. There are a variety of features you can use or combine to ensure this.

Gravity is the key

When cropping photos intended for profile pictures or other headshots, you will usually want to use face as your cropping gravity (g_face in URLs). This ensures that the detected face (or largest face if there is more than one) will be the center of the cropped photo, regardless of its initial location.

If in conjunction with face gravity, you use thumb as your crop method, you will get a crop that’s as tight as possible (given the cropping dimensions) to the detected face coordinates.

You can further adjust your thumbnail cropping by setting a zoom value, to zoom in or out from the detected face coordinates. And then of-course you can add any other transformations you want.

Original photo Cropped to a square using face detection Cropped using face detection
with thumbnail cropping Face detection, thumbnail crop,
zoomed out a bit Same as previous with circle shape,
shadow, and improve effect

Here's what the delivery code looks like for that last photo:

cl_image_tag("teen_facedown", :transformation=>[
  {:width=>200, :height=>200, :gravity=>"face", :zoom=>0.65, :radius=>"max", :effect=>"improve", :crop=>"thumb"},
  {:effect=>"shadow"}
  ])

cl_image_tag("teen_facedown", array("transformation"=>array(
  array("width"=>200, "height"=>200, "gravity"=>"face", "zoom"=>0.65, "radius"=>"max", "effect"=>"improve", "crop"=>"thumb"),
  array("effect"=>"shadow")
  )))

CloudinaryImage("teen_facedown").image(transformation=[
  {"width": 200, "height": 200, "gravity": "face", "zoom": 0.65, "radius": "max", "effect": "improve", "crop": "thumb"},
  {"effect": "shadow"}
  ])

cloudinary.image("teen_facedown", {transformation: [
  {width: 200, height: 200, gravity: "face", zoom: 0.65, radius: "max", effect: "improve", crop: "thumb"},
  {effect: "shadow"}
  ]})

cloudinary.url().transformation(new Transformation()
  .width(200).height(200).gravity("face").zoom(0.65).radius("max").effect("improve").crop("thumb").chain()
  .effect("shadow")).imageTag("teen_facedown")

$.cloudinary.image("teen_facedown", {transformation: [
  {width: 200, height: 200, gravity: "face", zoom: 0.65, radius: "max", effect: "improve", crop: "thumb"},
  {effect: "shadow"}
  ]})

cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(200).Height(200).Gravity("face").Zoom(0.65).Radius("max").Effect("improve").Crop("thumb").Chain()
  .Effect("shadow")).BuildImageTag("teen_facedown")

Everything mentioned above works equally well for multiple faces. Just use faces gravity instead of face, and your cropping will be based on a rectangle that includes all detected faces.

All of this assumes you can reasonably expect that the uploaded image is going to contain one or multiple faces as the main subject.

Sometimes the main subject of an image isn't necessarily expected to be a person, but you still need to ensure you aren’t cutting off people or other important content of the image. In this case, you can take advantage of the auto gravity feature. With this automated cropping method, the most prominent elements of the picture determine the cropping coordinates. Unless otherwise specified, any detected faces get a high priority in this cropping decision, but other prominent elements are also included.

You can learn lots more about auto gravity in this blog article and this documentation.

Losing face

There may be situations where you'd like to keep the people in a photograph anonymous. In these cases, you can pixelate or blur all detected faces just by adding a single parameter to your image URL.

In the example below, the faces that Cloudinary detects in the concert audience are generally those that could likely be identified by a human viewer. All of these faces are automatically blurred before the image is delivered, using the blur_faces effect.

cl_image_tag("concert_crowd", :effect=>"blur_faces:500")

cl_image_tag("concert_crowd", array("effect"=>"blur_faces:500"))

CloudinaryImage("concert_crowd").image(effect="blur_faces:500")

cloudinary.image("concert_crowd", {effect: "blur_faces:500"})

cloudinary.url().transformation(new Transformation().effect("blur_faces:500")).imageTag("concert_crowd")

$.cloudinary.image("concert_crowd", {effect: "blur_faces:500"})

cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("blur_faces:500")).BuildImageTag("concert_crowd")

And here’s an example of an ice skating scene where a couple of childrens' faces are clearly visible. This time, we use the pixelate option to protect the kids’ identities:

cl_image_tag("ice_skating.jpg", :effect=>"pixelate_faces:4", :width=>500, :crop=>"scale")

cl_image_tag("ice_skating.jpg", array("effect"=>"pixelate_faces:4", "width"=>500, "crop"=>"scale"))

CloudinaryImage("ice_skating.jpg").image(effect="pixelate_faces:4", width=500, crop="scale")

cloudinary.image("ice_skating.jpg", {effect: "pixelate_faces:4", width: 500, crop: "scale"})

cloudinary.url().transformation(new Transformation().effect("pixelate_faces:4").width(500).crop("scale")).imageTag("ice_skating.jpg")

$.cloudinary.image("ice_skating.jpg", {effect: "pixelate_faces:4", width: 500, crop: "scale"})

cloudinary.Api.UrlImgUp.Transform(new Transformation().Effect("pixelate_faces:4").Width(500).Crop("scale")).BuildImageTag("ice_skating.jpg")

Tip: For cases like these, you may want to take advantage of one of the access control options to prevent users from accessing the non-blurred or non-pixelated versions of the image.

Saving face

There’s no such thing as a face detection mechanism that will detect 100% of the faces 100% of the time, so what if you notice that a particular face you need was not detected? No problem. You can always update the detected coordinates explicitly.

For example, when a user uploads an image to your site, you can retrieve and display the detected face coordinates and then enable your users to adjust the coordinates or add a new face via your UI. You can then pass the updated coordinates to Cloudinary via the Update method of the Admin API.

For your own images, you can also manually change the coordinates using the Media library UI.

In your face

Sometimes, just blurring or pixelating a face isn’t enough. Instead, you want to completely cover the face with another image. Or, maybe you just want to add a fun mask. Whatever the reason, it’s simple to add the same image to all faces in a photo.

To do this, you take advantage of the region_relative flag and faces gravity when you specify the overlay image. That tells Cloudinary that you want the overlay to be placed on all faces, and that the specified size of each overlay is a percentage relative to the size of each detected face.

For example, here’s a quick way to get your family dressed up in costume:

cl_image_tag("family_portrait.jpg", :gravity=>"faces", :overlay=>"spiderman_mask", :width=>1.1, :flags=>"region_relative")

cl_image_tag("family_portrait.jpg", array("gravity"=>"faces", "overlay"=>"spiderman_mask", "width"=>1.1, "flags"=>"region_relative"))

CloudinaryImage("family_portrait.jpg").image(gravity="faces", overlay="spiderman_mask", width=1.1, flags="region_relative")

cloudinary.image("family_portrait.jpg", {gravity: "faces", overlay: "spiderman_mask", width: 1.1, flags: "region_relative"})

cloudinary.url().transformation(new Transformation().gravity("faces").overlay("spiderman_mask").width(1.1).flags("region_relative")).imageTag("family_portrait.jpg")

$.cloudinary.image("family_portrait.jpg", {gravity: "faces", overlay: "spiderman_mask", width: 1.1, flags: "region_relative"})

cloudinary.Api.UrlImgUp.Transform(new Transformation().Gravity("faces").Overlay("spiderman_mask").Width(1.1).Flags("region_relative")).BuildImageTag("family_portrait.jpg")

You probably already noticed that we gave anonymous (happy) faces to our roller coaster riders at the beginning of this article using the same technique.

And remember, the overlay you use doesn’t have to cover the whole face or even be centered. Below, we add a ranger hat to a man’s head using a relative y- coordinate to offset the location of the hat about 30% above the center of the face.

cl_image_tag("smiling_man", :transformation=>[
  {:gravity=>"face", :zoom=>0.6, :crop=>"crop"},
  {:overlay=>"ranger_hat", :width=>1.1, :flags=>"region_relative", :gravity=>"face", :y=>-0.3}
  ])

cl_image_tag("smiling_man", array("transformation"=>array(
  array("gravity"=>"face", "zoom"=>0.6, "crop"=>"crop"),
  array("overlay"=>"ranger_hat", "width"=>1.1, "flags"=>"region_relative", "gravity"=>"face", "y"=>-0.3)
  )))

CloudinaryImage("smiling_man").image(transformation=[
  {"gravity": "face", "zoom": 0.6, "crop": "crop"},
  {"overlay": "ranger_hat", "width": 1.1, "flags": "region_relative", "gravity": "face", "y": -0.3}
  ])

cloudinary.image("smiling_man", {transformation: [
  {gravity: "face", zoom: 0.6, crop: "crop"},
  {overlay: "ranger_hat", width: 1.1, flags: "region_relative", gravity: "face", y: -0.3}
  ]})

cloudinary.url().transformation(new Transformation()
  .gravity("face").zoom(0.6).crop("crop").chain()
  .overlay("ranger_hat").width(1.1).flags("region_relative").gravity("face").y(-0.3)).imageTag("smiling_man")

$.cloudinary.image("smiling_man", {transformation: [
  {gravity: "face", zoom: 0.6, crop: "crop"},
  {overlay: "ranger_hat", width: 1.1, flags: "region_relative", gravity: "face", y: -0.3}
  ]})

cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Gravity("face").Zoom(0.6).Crop("crop").Chain()
  .Overlay("ranger_hat").Width(1.1).Flags("region_relative").Gravity("face").Y(-0.3)).BuildImageTag("smiling_man")

At face value

If you want to check the face detection status of uploaded images programmatically, you can request to return face coordinate data when you or your users upload images, or you can request them upon demand for already uploaded images using the explicit method of the upload API, or with the list details of a single resource functionality of the Admin API. The following shows an excerpt from the JSON response of an upload call where the faces parameter was set to true.

{
  ...
  "faces":  [ [513, 19, 38, 52], [409, 26, 40, 54], [79, 31, 43, 59], [232, 32, 40, 54], [321, 33, 41, 57], [160, 37, 43, 59]
}

For example, you could use this data to calculate the ideal location for a text overlay so that it won’t cover any faces on a photo.

Two-faced

Cloudinary enables you to create programmatically complex manipulations by adding conditions to your transformations. One of the things you can base your conditions on is face_count.

For example, you can’t always be sure that a profile picture will be of a person. Some people choose to upload family portraits, scenery, or other images to represent themselves. The following images use the identical conditional transformation, where thumbnail cropping is applied if one or more faces is found, but scaled cropping is used on images without faces. We’ve also added a shadow vs black border for the alternative conditions to highlight the differences.

(The code shown here is for the nice_couple on the left, but you can click the bridge picture to see that it uses the identical transformation URL except for the image name (public ID).)

cl_image_tag("nice_couple", :transformation=>[
  {:if=>"fc_gte_1", :gravity=>"faces", :zoom=>0.5, :width=>200, :height=>200, :effect=>"shadow:10", :color=>"#acb2b9", :x=>7, :y=>7, :crop=>"thumb"},
  {:if=>"else", :width=>200, :height=>200, :border=>"3px_solid_black", :crop=>"scale"}
  ])

cl_image_tag("nice_couple", array("transformation"=>array(
  array("if"=>"fc_gte_1", "gravity"=>"faces", "zoom"=>0.5, "width"=>200, "height"=>200, "effect"=>"shadow:10", "color"=>"#acb2b9", "x"=>7, "y"=>7, "crop"=>"thumb"),
  array("if"=>"else", "width"=>200, "height"=>200, "border"=>"3px_solid_black", "crop"=>"scale")
  )))

CloudinaryImage("nice_couple").image(transformation=[
  {"if": "fc_gte_1", "gravity": "faces", "zoom": 0.5, "width": 200, "height": 200, "effect": "shadow:10", "color": "#acb2b9", "x": 7, "y": 7, "crop": "thumb"},
  {"if": "else", "width": 200, "height": 200, "border": "3px_solid_black", "crop": "scale"}
  ])

cloudinary.image("nice_couple", {transformation: [
  {if: "fc_gte_1", gravity: "faces", zoom: 0.5, width: 200, height: 200, effect: "shadow:10", color: "#acb2b9", x: 7, y: 7, crop: "thumb"},
  {if: "else", width: 200, height: 200, border: "3px_solid_black", crop: "scale"}
  ]})

cloudinary.url().transformation(new Transformation()
  .if("fc_gte_1").gravity("faces").zoom(0.5).width(200).height(200).effect("shadow:10").color("#acb2b9").x(7).y(7).crop("thumb").chain()
  .if("else").width(200).height(200).border("3px_solid_black").crop("scale")).imageTag("nice_couple")

$.cloudinary.image("nice_couple", {transformation: [
  {if: "fc_gte_1", gravity: "faces", zoom: 0.5, width: 200, height: 200, effect: "shadow:10", color: "#acb2b9", x: 7, y: 7, crop: "thumb"},
  {if: "else", width: 200, height: 200, border: "3px_solid_black", crop: "scale"}
  ]})

cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .If("fc_gte_1").Gravity("faces").Zoom(0.5).Width(200).Height(200).Effect("shadow:10").Color("#acb2b9").X(7).Y(7).Crop("thumb").Chain()
  .If("else").Width(200).Height(200).Border("3px_solid_black").Crop("scale")).BuildImageTag("nice_couple")

You can learn more about conditional transformations here.

Face to face

Just a reminder that in addition to applying all this cool stuff on images that you or your users directly upload, you can also use the same tricks with remotely fetched images, such as Facebook profile pictures.

For example, you can allow your users to select to use their Facebook profile photo as the basis for their account profile photo in your app and then apply resizing, rounding, artistic effects, or any other transformation to fit your site's art direction, while ensuring that the detected face of the fetched photo remains the main focus of the final photo.

Here we apply cropping and several other transformations to the Facebook profile photo from the Remembering JFK page:

cl_image_tag("268587306614095", :type=>"facebook", :transformation=>[
  {:width=>200, :height=>200, :gravity=>"face", :zoom=>0.65, :radius=>"max", :effect=>"art:sizzle", :crop=>"thumb"},
  {:effect=>"shadow"}
  ])

cl_image_tag("268587306614095", array("type"=>"facebook", "transformation"=>array(
  array("width"=>200, "height"=>200, "gravity"=>"face", "zoom"=>0.65, "radius"=>"max", "effect"=>"art:sizzle", "crop"=>"thumb"),
  array("effect"=>"shadow")
  )))

CloudinaryImage("268587306614095").image(type="facebook", transformation=[
  {"width": 200, "height": 200, "gravity": "face", "zoom": 0.65, "radius": "max", "effect": "art:sizzle", "crop": "thumb"},
  {"effect": "shadow"}
  ])

cloudinary.image("268587306614095", {type: "facebook", transformation: [
  {width: 200, height: 200, gravity: "face", zoom: 0.65, radius: "max", effect: "art:sizzle", crop: "thumb"},
  {effect: "shadow"}
  ]})

cloudinary.url().transformation(new Transformation()
  .width(200).height(200).gravity("face").zoom(0.65).radius("max").effect("art:sizzle").crop("thumb").chain()
  .effect("shadow")).type("facebook").imageTag("268587306614095")

$.cloudinary.image("268587306614095", {type: "facebook", transformation: [
  {width: 200, height: 200, gravity: "face", zoom: 0.65, radius: "max", effect: "art:sizzle", crop: "thumb"},
  {effect: "shadow"}
  ]})

cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(200).Height(200).Gravity("face").Zoom(0.65).Radius("max").Effect("art:sizzle").Crop("thumb").Chain()
  .Effect("shadow")).Type("facebook").BuildImageTag("268587306614095")

Original Facebook profile photo      Manipulated photo: face thumbnail
slight zoom, artistic filter,
rounding, shadow

You can do the same with images fetched from other sites, like Twitter, Google+, or from any image URL.

Face the facts

By now, the many potential uses for face detection have probably become obvious to you, as plain as the nose on your face, you might say…. OK, I'm done with the painful face puns.

The fact is that almost every Website includes both local and user-generated content that centers around people. It’s essential that those people remain the focus of the displayed pictures regardless of how you resize, crop, add images and text overlays, etc.

Cloudinary’s face detection capabilities and updated mechanism enable you to accomplish all of these things programmatically, using simple transformation parameters, and with very reliable results.

Ready to see how far your creativity can take these face detection features? These features are available in all plans including the free plan, with no add-ins required. If you don’t have a Cloudinary account yet, you can sign up for a free one, and give it a go!

Images – if you’re a developer, there’s no doubt that at one time or another, you’ve probably worked with a lot of image files, and may have been tasked with ensuring a top-notch user experience or continually improving website and app performance. You may have posed questions on online message boards, or sought advice from your developer colleagues. But there hasn’t been a conference that solely focused on image management…until now.

Introducing ImageCon – the first-ever event designed to bring together developers for an open, frank discussion of image management challenges. ImageCon, which takes place Wednesday, March 1, at the Four Seasons in San Francisco – will feature presentations by some of today’s visionaries, leading technologists and developers who will share their thought leadership about best practices, including:

• Vitaly Friedman, editor-in-chief of Smashing Magazine – Leading a session called “Reaching for the Stars: Why Images Matter,” Vitaly will discuss why designers struggle with art direction and data visualization when trying to craft a great user experience across various screens and platforms. 
• Jason Grigsby, co-founder of Cloud Four – In a session on “Delivering Responsive Images,” Jason will outline the hard work ahead now that solutions for responsive images has been integrated with browsers.
• Tobin Titus, senior program manager at Microsoft – During “The Physics of Fast: Image Compression,” Tobin will examine how performance best practices are changing as more users shift to lower-cost devices on mobile networks. He’ll cover physical limitations of the devices, choices of graphics formats and how these factors impact the performance of your entire site or application.
• Steve Souders, chief SpeedCurver at SpeedCurve – Steve will look at “Measuring Image Performance” in this session, during which he’ll discuss tracking website speed and other best practices for performance measurement, designed to optimize your site and engage users.
• Allison McKnight, senior software engineer for Etsy – During a session on “Image Performance: Good for Your Users, Good for Your Business,” Allison will share real-world examples of the positive impact image optimization can have on metrics important to your business and end users, and talk about useful tools for enhancing user experience.

Cloudinary is very excited about the great line-up of speakers and the opportunity the event presents for the industry as a whole to advance image management best practices. We believe you’ll come away with practical advice and solutions that you can employ right away to address the challenges you face in optimizing your website for end users.  

More importantly, we believe this is a great opportunity to network with your peers and learn from their experiences. Through an open dialogue and sharing real-world experiences, we expect ImageCon to play an important role in advancing – and improving – the practice of image management. 

We hope you’ll join us at ImageCon – register today.

Cellular Automata are pretty cool things to play with. There are many, many variants, like Conway’s Game of Life, Abelian Sandpiles, Langton’s Loops and Brian’s Brain, but in this blogpost, I’ll just talk about the simplest kinds of cellular automata: one-dimensional cellular automata.

The simplest kind of 1D cellular automata are called Elementary Cellular Automata. They work on a sequence of cells, which can each have two possible states: on and off, or 1 and 0. Starting from an initial sequence, the next sequence is computed based on simple rules: the next state of a cell only depends on the current state of the cell itself and its two neighbors.

For example, here is an elementary cellular automaton called "Rule 22":

In this automaton, a cell is "on" if in the previous generation, exactly one out of those three cells was on; otherwise it is "off". Rules can be described using the Wolfram code, which was introduced by Stephen Wolfram. In the case of elementary cellular automata, there are just 8 = 2³ possible configurations of a given cell and its neighbors, and for each configuration there are just two options for the resulting new state, so there are 256 = 2⁸ different elementary CAs, and they can be described using an 8-bit number. So the rules of the diagram above can be described with the binary number 00010110, or in decimal notation: 22.

You can draw the evolution of a 1D cellular automaton (CA) as a 2D image, starting with some initial row of cells at the top and then drawing more and more generations in the rows below it. For rule 22, if you start with just a single black cell in the top row, you get the following image after 512 generations:

Interestingly, the resulting image looks a lot like a Sierpinski triangle. In fact several of the elementary CAs look like this. It is one of the simplest examples of a fractal: the image has a self-repeating structure at different scales.

Compressing CA images

You might expect that an image with so much repetitive structure in it, generated from such a simple rule, must compress very well. And it does. But it depends on the image format.

As a JPEG, the above image doesn’t compress very well: it weighs 79 KB at quality 90, and that is not even lossless. Even at the lowest possible quality, it is still 16 KB, and at that quality setting, the compression artifacts are quite bad:

As a PNG however, the image is only 3.4 KB, and that is lossless. So picking the right format can matter a lot, indeed. If you’re using Cloudinary, you don’t have to worry about that: just use f_auto, q_auto (read more) and you will automatically get the most suitable image format and quality settings – in this case, that would be a lossless PNG.

In this example, PNG performs very well because there is a lot of exact repetition in the image. PNG is based on the DEFLATE algorithm, which replaces such exact duplicates by backreferences, saving lots of bytes.

However, not all cellular automata produce such easy-to-compress, repetitive patterns.

Rule 30

For example, Rule 30 produces the following image when starting from a single black cell:

This image weighs in at 215 KB as a quality 90 JPEG, and as a PNG, it is still 24 KB – compared to the 3.4 KB for the Sierpinski triangle image (Rule 22) of the same dimensions, that is quite a jump.

The pattern that rule 30 creates is intriguing: on the left it is repetitive, but on the right, it gets much more chaotic. Triangular structures emerge, but they are positioned in seemingly random ways. Interestingly, in nature there seem to be processes that lead to similar patterns, like on the shell of this Conus textile sea snail:

(Image Copyright (c) 2005 Richard Ling, CC-BY-SA 3.0)

What if we could learn the rules?

PNG performs well for repetitive images like Rule 22, because it "sees" the repetition and encodes it efficiently. It does not "see" the underlying rules of the cellular automaton though, so if those rules lead to chaotic emergent behavior, it gets into trouble. The same is true for GIF and lossless WebP, by the way.

But what if I tell you that there is an image format that can essentially just "learn the rules", and compress the image very well, regardless of what those rules actually lead to?

Well, the MANIAC entropy coding of FLIF can do just that. It can construct a MANIAC tree that exactly corresponds to the rules of an elementary CA, making sure that each of the 8 configurations of the rules correspond to a different context for the arithmetic coder. Then the probabilities in those contexts will rapidly converge to something very close to 0 or 1, and the encoded bits will have near-zero cost.

For example, the Rule 22 image that was 3.4 KB as a PNG file, is just 83 bytes as a FLIF file. The Rule 30 image that was 24 KB as a PNG, is only 92 bytes as a FLIF.

In fact, those two CA images above (if you have javascript enabled) are actually FLIF files, decoded in your browser using a javascript polyfill called PolyFLIF.

I obtained the smallest FLIF files with the following command-line options for the encoder:

flif -NX1

The option -N causes the encoder to use the non-interlaced variant of the format, so the encoding is top-to-bottom, just like the evolution of the automaton. The default is to do interlacing, which would mean that the encoder cannot "see" the structure since it is encoding pixels from all over the image, resulting in much worse compression. The option -X1 is less important; it allows the arithmetic coder to use more extreme chances (1/4096 instead of the default 2/4096), bringing the "near-zero" cost of the bits even closer to zero.

Larger and larger images

Here’s an animated plot of the image file size of Rule 22 images with more and more rows, using different image compression formats. Note: the y-axis is logarithmic here!

If you want an even more extreme example, here is a FLIF file that contains a 50 megapixel image of the Rule 30 evolution (5000 rows). Here are the file sizes for that particular image:

Amazing how poorly the lossy formats perform on this image, isn’t it? Also rather interesting that PNG and lossless WebP are so close to one another – not that surprising if you know they’re based on similar entropy coding methods, but still. For me however (being the author of FLIF), the nicest thing about the above table is that FLIF beats anything else by a few orders of magnitude :).

Now, of course you shouldn’t draw too many conclusions from something like this. This is an image that is very special in the sense that it represents a best-case scenario for FLIF, while it is quite close to a worst-case scenario for the other formats. It is not that hard to come up with images that turn the tables and compress exceptionally well with, say, PNG or WebP, but compress poorly in FLIF.

More complicated cellular automata

FLIF can learn all elementary cellular automata, but it can also handle some more complicated ones. For example, if you allow the next state of a cell to depend not just on the current state of the cell and its neighbors, but also on the previous state of the cell, you get a somewhat different kind of cellular automata that can produce images like these:

Here, I initialized the top row randomly, so the FLIF files are somewhat larger: 269 bytes for the first image, 240 bytes for the second. The corresponding PNG files are 16 KB and 32 KB.

Totalistic Cellular Automata

There’s no reason to use only two colors (or states). When using more states, it becomes a bit more tricky to describe the rules concisely, since the number of different automata grows quite quickly; with just 3 states, there are 7,625 billion (3²⁷) automata if you only look at the cell and its two neighbors, and you would need a 27-digit ternary number to describe them.

To simplify things, you can look at totalistic cellular automata, which are a subset of that huge set. In a totalistic CA, the new state depends only on the sum of the current states that are being considered. This forces certain symmetries. For example, the configuration 0,2,1 must result in the same new state as the configuration 1,2,0, or the configuration 1,1,1 for that matter. As a result, you need way fewer digits to specify a totalistic CA. If you have three cell states, the sum can be anything between 0 and 6, and for each of those 7 configurations, there are 3 possible new states, so 7 ternary digits are enough and there are "only" 2187 totalistic 3-color automata.

One of those is Rule 1599, which is my favorite totalistic CA. It looks like this:

Starting from a single "1" cell, Rule 1599 produces this intricate pattern, which goes on for about 8000 rows and then it kind of stops, leaving only a trail of some repeating pattern, about 700 columns wide, that goes on forever. Here is an 899-byte FLIF file that encodes the entire interesting part – it’s a 720x9000 image, so I’m not going to let your browser decode that here.

Take a look at this animated plot of the file sizes:

In this plot, I restricted the number of MANIAC tree learning iterations to just one. You can see that initially the file size grows as the image grows, and it seems to take some time before FLIF "figures out" the rules of the game completely. The file size actually drops while it is learning the rules, and then it very slowly starts to go up again, encoding the extra pixels at near-zero cost. At 3000 rows, the FLIF file is still only 667 bytes, while WebP and PNG are around 140 KB and the lossy JPEG is getting close to 1 MB.

Conclusion

One obvious conclusion from all this is don’t use lossy compression on images of Cellular Automata or in general, on highly structured artificial images with lots of fine details. That’s nothing new, but I think the examples above bring down this point quite nicely.

What’s hopefully new and interesting is that there can be huge differences between different lossless image compression formats. If the format is somehow capable of capturing the "essence" of the image, it might be able to compress it extremely well. For PNG (and lossless WebP), this "best case" scenario is exact repetition. For FLIF, it is harder to describe what the "best cases" are, but Cellular Automata certainly seem to be among them.

Finally, if all went well, this blogpost is actually the first "real" webpage to use FLIF images for purposes other than to demonstrate the javascript polyfill. I hope you enjoyed it!

Have you ever noticed that home pages are slow to load? Sliders could be to blame. Many modern homepages use a slider or carousel design element to show several rotating images that provide different offers or present various aspects of the brand. A common choice for implementing these sliders is JQuery. While JQuery itself is not a performance killer, the large images displayed by the slider can be responsible for slowing down a home page’s load time.

In this post, we’ll present the results of a test we conducted using a popular JQuery slider, BxSlider. We implemented the slider on a web page, with a width of 800px, and sampled the image file size in four different scenarios:

1. Full size images resized on the client side - This is the “worst case,” with no optimization of images at all.
2. Images resized to the width of the slider - This is better, but images are resized manually, which is not convenient for responsive designs, and not optimized.
3. Full size images, but with image optimization by Cloudinary - Cloudinary is a free cloud service that can optimize and modify images on the fly. In this scenario, we show how two image optimizations can reduce image size by almost 50 percent - with no resizing.
4. Images dynamically resized to width of slider, with image optimization - Both resizing and optimization are done on the fly by Cloudinary. The result: A 96.3 percent reduction in file size for the specific images used in our test.

Read on to see how the four scenarios affect image size for a commonly used free JQuery slider, and how to easily go from a file size of over 6MB (in this example) to under 300KB.

Scenario #1: Slider with Large Images Resized on Client Side

Here are the sample images we chose for our BxSlider implementation. The slider shows one image at a time; here we’re showing all four.

In this scenario, we left the original stock images as is, without reducing their size. In order to display them in our slider at 800px, images are resized on the client side.

Obviously this is a “naive” implementation, which results in huge file size. It also leaves the heavy lifting to the browser, requiring it to resize the file, which further increases page load time. Let’s take this as a worst case of non-optimized slider images.

In the following table, we show the actual image resolution (before resizing) and image file size.

You wouldn’t wait for this homepage to load...

Scenario #2: Slider with Images Manually Resized to 800px

In this scenario, the original stock images were manually resized to 800px. This is an “obvious optimization,” which helps a lot in reducing image size and page load time.

However, because images were manually resized to a pre-set width (800px in our case), it’s not ideal for responsive designs. In a realistic scenario, we would need to support several viewport sizes, and then we’d have to resize each image multiple times.

Also, there are additional ways to reduce image size, as we’ll see in the following sections.

Here’s what we save via plain image resize:

Simple resizing of the images reduced the total image size by 90 percent, so it is definitely worthwhile.

Scenario #3: Slider with Large Images Optimized by Cloudinary

What more can we do beyond the obvious optimization of resizing the image?

In this scenario, we’re back to using huge images with client-side resizing. We wanted to show the impact of image optimization. How much can you save on file size (and page load time) just by optimizing the images, even without reducing their size?

In a minute we’ll explain just how we optimize the images. But first let’s look at the results: The images look exactly the same, but file size compared to Scenario 1 is reduced by 47 percent.

What’s amazing here is that the images are still huge (for example, the cute cat is a whopping 3940 pixels wide). But their file size is down from a monstrous 6.7MB in Scenario 1 to a more manageable 3.6MB. We saved 47 percent on file size by optimizing the images.

How Did We Optimize the Images?

We used Cloudinary, our cloud-based service that provides end-to-end image management, including upload, storage, administration, manipulation, optimization and delivery.

With Cloudinary, you can upload images to the cloud (or let your users upload them) and automatically perform smart image manipulations without installing any software.

If you’re the one producing the images, which is probably the case if you’re building a slider for your site, you can upload the images manually using our Media Library interface or programmatically via API. Once the images are stored in your Cloudinary account, you can perform any number of operations on them, including cropping, resizing, smart image effects, as well as various types of image optimizations. The modified images are dynamically displayed to your users and delivered via fast CDN.

Cloudinary provides two main image optimization features, which made it possible to reduce image size by 47 percent above:

• Automatic quality selection: Cloudinary uses an intelligent quality and encoding algorithm to find the quality/compression level and encoding settings that produce the smallest possible file size, without hurting visual quality. The algorithm uses perceptual metrics and heuristics to determine when an image is too compressed and does not look as good, then stops compressing at that level. For example, Cloudinary can detect that for a JPEG image, 84 percent is the optimal quality level. This is the lowest possible JPEG quality for which the image still looks the same to a website visitor.
• Automatic format selection: Cloudinary can automatically detect a user’s browser and deliver an image in advanced file formats available for that browser: WebP in Chrome, and JPEG-XR in Internet Explorer. For other browsers, it delivers a JPEG. For many users running newer browsers, this feature can dramatically reduce file size, because WebP and JPEG-XR have much better lossless compression than regular formats like JPEG or PNG.

By combining these two features, we achieved a massive reduction in file size without resizing the images at all!

Don’t worry, we’re not leaving the images like this. In Scenario 4 we’ll also resize the images, this time doing it dynamically using Cloudinary, which is much more responsive-friendly. But first a few words about how the image manipulations were done.

Only One Line of Code (Per Image)

To achieve the two image optimizations we described above, all we needed to do is the following:

1. Upload the images to Cloudinary using the Cloud-Based Media Library or the Image Upload API.
2. Here is the code for bxSlider, the free slider we used in this example:

<script>
            $('#aSlider').bxSlider({ 
              mode: 'fade', 
              captions: true, 
              adaptiveHeight: true, 
              slideWidth: 800 
            });
</script>
…
<ul id=”aSlider">
 <li>
  <img 
    src="http://res.cloudinary.com/demo/image/upload/q_auto,f_auto/balloons.jpg" 
    title="Balloons"/>
 </li>
 <li>
  <img 
    src="http://res.cloudinary.com/demo/image/upload/q_auto,f_auto/car_lady_dog.jpg" 
    title="Car, lady and dog"/>
 </li>
 <li>
  <img 
    src="http://res.cloudinary.com/demo/image/upload/q_auto,f_auto/friends.jpg" 
    title="Friends"/>
 </li>
 <li>
  <img 
    src="http://res.cloudinary.com/demo/image/upload/q_auto,f_auto/sofa_cat.jpg" 
    title="Cat on Sofa"/>
 </li>
</ul>

1. The only difference between the “naive” implementation of the slider with full-size images stored locally (Scenario 1), and this implementation (Scenario 3), is the URLs of the images. We use a special URL that tells Cloudinary to apply the two optimizations: automatic quality (q_auto) and automatic image format (f_auto).

You can generate this special URL using Cloudinary’s SDKs for all popular programming languages. The resulting URL looks like this: http://res.cloudinary.com/demo/image/upload/q_auto,f_auto/balloons.jpg

Bottom line - image optimization alone reduced the file size by 47%: With Cloudinary’s image optimization, performed on-the-fly with a simple URL parameter, image size is reduced by 47 percent, even before we start resizing the images.

Scenario #4: Slider with Images Optimized and Auto-Resized by Cloudinary

In this scenario, we not only optimize the images (which, as we noted, shaves off almost 50 percent of their size), but we also use Cloudinary to dynamically resize them.

This is like Scenario 2 above. But instead of manually resizing images for every viewport size, we ask Cloudinary to resize the image on-the-fly to the width of the slider, 800px, using the width parameter. In the Cloudinary back-end, the image is still stored at high resolution, but it’s delivered to the browser at a width of 800px.

In a responsive design, you could use more advanced Cloudinary options (not shown here) such as c_scale and w_auto to automatically adjust the image size to the current screen size. For more details see our Automatic responsive images documentation. Cloudinary can also perform smart cropping and resizing, while focusing on the important elements in the picture.

We are still applying the two image optimization options, q_auto and f_auto, as shown in Scenario 3 above. Put together with the resize, this generates the final reduction in file size:

This is where we want to be! All four images, still look the same, but they are down to a fraction of their original size.

The Code

The BxSlider code is exactly the same, with a small change to the image URLs:

<!--bxSlider CSS file--> 
<link href="/js/vendor/jquery.bxslider.min.css" rel=”stylesheet"/>
…
<ul id=”aSlider">
 <li>
  <img 
    src="http://res.cloudinary.com/demo/image/upload/q_auto,f_auto,w_800/balloons.jpg" 
    title="Balloons"/>
 </li>
…
</ul>

All we did was to add w_800 to the URL, which resizes the image to a width of 800px while retaining the aspect ratio. Combined with the image optimizations, this reduced file size by the full 96.3 percent, compared to only 90 percent for just a manual resize without optimization (Scenario 2). And to top it off, there was no manual labor involved.

Here is the URL that achieves this, which you can generate in the programming language of choice (using one of our SDKs): http://res.cloudinary.com/demo/image/upload/q_auto,f_auto,w_800/balloons.jpg

Bottom line - Dynamic resize + optimization sliced off 96.3 percent of image size: Here we combined three image manipulations: resize, automatic quality selection and automatic format selection, which together reduced image size by 96.3 percent compared to the huge stock images from Scenario 1. All of this was done dynamically by Cloudinary and delivered to users on-the-fly. You can change parameters, add or remove image manipulations at any time for any number of images, and users will immediately see the change.

Addendum: Automatic Responsive Breakpoints

If you’re working on a responsive slider, leveraging automatic responsive breakpoints might come in handy. When building any responsive design, there’s a need to decide which image resolutions to select and how many different image versions to include in your responsive website. These are called responsive breakpoints or responsive image breakpoints.

To perfectly balance the number of image versions for your responsive website, you need to find the correct number of breakpoints according to the file size steps that you define. You can (theoretically) generate images for all possible width values and then select only those that provide a file size reduction that is really significant. However this is quite difficult to do in practice.

Cloudinary analyzed the behavior of compression mechanisms for various image formats (mainly JPEG, PNG and WebP) and created an algorithm that can intelligently identify the optimal image breakpoints and give you the best tradeoff between file size and bandwidth (the more image versions, the more bandwidth is consumed).

Check out our open source tool Responsive Breakpoints Generator to automatically determine the optimal image breakpoints for your responsive design.

Summary

Image sliders, which are often but not always based on JQuery, are a big contributor to the load time of home pages and other media-heavy web pages. Because sliders use large images, they are a prime candidate for image optimization.

In this post, we showed two strategies for reducing image size:

• Simple resizing, a very effective tactic that can reduce image size by as much as 90% compared to original stock images
• Finding the optimal file format and the lowest quality level that won’t hurt the visual quality of the images - in our test, this reduced image size by an additional 47%

In this blog, we showed how to do both of these easily in Cloudinary, a cloud-based service that provides end-to-end image management, including upload, storage, administration, manipulation, optimization and delivery. Cloudinary can dynamically resize images, even in multiple sizes for responsive designs, and can automatically switch an image to the file format and quality level that will provide the lowest possible file size. In our test on a free JQuery slider, this reduced image size by a whopping 96.3% compared to the original stock images.

Now you can try this out with your own images. If you don't already have a Cloudinary account, sign up for the free plan.

The night was moist. Angular2 had just been released and developers all over the world were asking for an integrated image management solution.

Cloudinary heeded the call and is proud to present the new Angular2 SDK, providing directives for displaying and transforming images and video with an API.

Wait, what's Cloudinary?

Cloudinary is an end-to-end image and video management solution for your website and mobile apps. Cloudinary covers everything from media uploads and storage to manipulations, optimizations, and delivery.

You can easily upload images and video to the cloud and automatically perform smart manipulations without installing any complex software. You can also integrate a Facebook or Twitter profile image in a snap, in any dimension and style to match your website’s graphics requirements. All your media files are seamlessly delivered through a fast CDN, optimized and using industry best practices.

For more information visit our Features Page.

Why do I need an SDK?

Cloudinary provides RESTful APIs that can be easily integrated with any Web development framework, but the new Angular SDK makes it easier to consume Cloudinary's service in your Angular2 app.

Let’s see how this is done by transforming Angular’s logo:

cl_image_tag("angular_logo", :secure=>true, :transformation=>[
  {:effect=>"pixelate:8", :gravity=>"north", :height=>0.5, :overlay=>"angular_logo", :width=>1.0, :crop=>"crop"},
  {:flags=>"layer_apply", :gravity=>"north"},
  {:width=>180, :crop=>"fit"}
  ])

cl_image_tag("angular_logo", array("secure"=>true, "transformation"=>array(
  array("effect"=>"pixelate:8", "gravity"=>"north", "height"=>0.5, "overlay"=>"angular_logo", "width"=>1.0, "crop"=>"crop"),
  array("flags"=>"layer_apply", "gravity"=>"north"),
  array("width"=>180, "crop"=>"fit")
  )))

CloudinaryImage("angular_logo").image(secure=True, transformation=[
  {"effect": "pixelate:8", "gravity": "north", "height": 0.5, "overlay": "angular_logo", "width": 1.0, "crop": "crop"},
  {"flags": "layer_apply", "gravity": "north"},
  {"width": 180, "crop": "fit"}
  ])

cloudinary.image("angular_logo", {secure: true, transformation: [
  {effect: "pixelate:8", gravity: "north", height: 0.5, overlay: "angular_logo", width: 1.0, crop: "crop"},
  {flags: "layer_apply", gravity: "north"},
  {width: 180, crop: "fit"}
  ]})

cloudinary.url().transformation(new Transformation()
  .effect("pixelate:8").gravity("north").height(0.5).overlay("angular_logo").width(1.0).crop("crop").chain()
  .flags("layer_apply").gravity("north").chain()
  .width(180).crop("fit")).secure(true).imageTag("angular_logo")

$.cloudinary.image("angular_logo", {secure: true, transformation: [
  {effect: "pixelate:8", gravity: "north", height: 0.5, overlay: "angular_logo", width: 1.0, crop: "crop"},
  {flags: "layer_apply", gravity: "north"},
  {width: 180, crop: "fit"}
  ]})

cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Effect("pixelate:8").Gravity("north").Height(0.5).Overlay("angular_logo").Width(1.0).Crop("crop").Chain()
  .Flags("layer_apply").Gravity("north").Chain()
  .Width(180).Crop("fit")).Secure(true).BuildImageTag("angular_logo")

(Angular logo is released under CC BY 4.0)

The above image was generated by overlaying the Angular logo onto itself, cropping the overlay and pixelating its top, then cropping the result to be 180px wide.

The same transformation can be achieved in your Angular2 app using the following directives:

    <cl-image secure="true" public-id="angular_logo" width="180" crop="fit">
        <cl-transformation overlay="angular_logo" width="1.0" height="0.5" crop="crop" effect="pixelate:8" gravity="north"></cl-transformation>
        <cl-transformation flags="layer_apply" gravity="north"></cl-transformation>
    </cl-image>

Additional transformation examples can be found in the jQuery image manipulation guide and the complete image transformation reference

The same applies to videos:

The link to this video is

https://res.cloudinary.com/cloudinary/video/upload/g_north,l_text:arial_30:Cloudinary%20features,y_8,co_red/w_1000/manipulation_video.mp4

This can be achieved using the Angular SDK with the following directives:

<cl-video public-id="manipulation_video"
cloud-name="cloudinary" controls="true" 
preload="none" autoplay="true"
width="1000" secure="true"
class="manipulation-video">
   <cl-transformation overlay="text:arial_30:Cloudinary%20features" 
        color="red" gravity="north" y="8">
   </cl-transformation>
</cl-video>

How do I start using the SDK?

Installation

The SDK can be installed via Node Package Manager by executing the following command in your application's root folder

npm install @cloudinary/angular --save

Or if you’re using yarn:

yarn add @cloudinary/angular

Cloudinary module configuration

The SDK is based on Cloudinary's Javascript module, however the two are decoupled. The Cloudinary module is a configurable service to which you provide your choice of our JS module.

See below for an example Cloudinary configuration in the application module definition:

import { NgModule } from '@angular/core';
...
import { CloudinaryModule, CloudinaryConfiguration, provideCloudinary } from '@cloudinary/angular';

@NgModule({
    imports: [
        CloudinaryModule
    ],
    providers: [
        provideCloudinary(require('cloudinary-core'), { cloud_name: 'your_cloud_name' } as CloudinaryConfiguration)
    ],
    bootstrap: [...]
})
export class AppModule { }

If you are using Angular AOT you need to configure Cloudinary a bit differently:

import { NgModule } from '@angular/core';
...
import { CloudinaryModule } from '@cloudinary/angular';
import { Cloudinary } from 'cloudinary-core/cloudinary-core-shrinkwrap';

const cloudinaryLib = {
  Cloudinary: Cloudinary
}

@NgModule({
    imports: [
    CloudinaryModule.forRoot(cloudinaryLib, {
      cloud_name: 'your_cloud_name'
    })
    ],
    bootstrap: [...]
})
export class AppModule { }

Cloudinary directives

The Cloudinary module provides a component and several directives for:

• Creating new image and video tags and controlling the underlying chained transformations
• Enhancing native HTML elements with Cloudinary image management capabilities

Creating image tags with cl-image & cl-transformation

The cl-image component generates an image tag with the requested transformation, type, and format. The image tag can contain optional cl-transformation elements that will be used for chained transformations.

The following example demonstrates a chained transformation with several components applied to a single image

cl_image_tag("angular_logo.jpg", :transformation=>[
  {:effect=>"sepia", :height=>150, :width=>150, :crop=>"fill"},
  {:color=>"#EECCAA", :gravity=>"south", :overlay=>"text:arial_20:Angular", :y=>20},
  {:angle=>20}
  ])

cl_image_tag("angular_logo.jpg", array("transformation"=>array(
  array("effect"=>"sepia", "height"=>150, "width"=>150, "crop"=>"fill"),
  array("color"=>"#EECCAA", "gravity"=>"south", "overlay"=>"text:arial_20:Angular", "y"=>20),
  array("angle"=>20)
  )))

CloudinaryImage("angular_logo.jpg").image(transformation=[
  {"effect": "sepia", "height": 150, "width": 150, "crop": "fill"},
  {"color": "#EECCAA", "gravity": "south", "overlay": "text:arial_20:Angular", "y": 20},
  {"angle": 20}
  ])

cloudinary.image("angular_logo.jpg", {transformation: [
  {effect: "sepia", height: 150, width: 150, crop: "fill"},
  {color: "#EECCAA", gravity: "south", overlay: "text:arial_20:Angular", y: 20},
  {angle: 20}
  ]})

cloudinary.url().transformation(new Transformation()
  .effect("sepia").height(150).width(150).crop("fill").chain()
  .color("#EECCAA").gravity("south").overlay("text:arial_20:Angular").y(20).chain()
  .angle(20)).imageTag("angular_logo.jpg")

$.cloudinary.image("angular_logo.jpg", {transformation: [
  {effect: "sepia", height: 150, width: 150, crop: "fill"},
  {color: "#EECCAA", gravity: "south", overlay: "text:arial_20:Angular", y: 20},
  {angle: 20}
  ]})

cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Effect("sepia").Height(150).Width(150).Crop("fill").Chain()
  .Color("#EECCAA").Gravity("south").Overlay("text:arial_20:Angular").Y(20).Chain()
  .Angle(20)).BuildImageTag("angular_logo.jpg")

It starts by cropping the image to 150x150 pixels and adds a sepia effect. Then it adds a text overlay with the word Angular with a specific font type, font size and color, and positions the text at the bottom. Finally, it rotates the result by 20 degrees:

<cl-image public-id="angular_logo" class="logo" angle="20" format="jpg">
    <cl-transformation height="150" width="150" crop="fill" effect="sepia"></cl-transformation>
    <cl-transformation overlay="text:arial_20:Angular" color="#EECCAA" gravity="south" y="20"></cl-transformation>
</cl-image>

This will be compiled by Angular to:

<img class="logo" _ngcontent_ovt_3=""
  public_id="angular_logo" 
  ng_reflect_public_id="angular_logo" 
  src="http://res.cloudinary.com/eitanpeer/image/upload/c_fill,e_sepia,h_150,w_150/co_rgb:EECCAA,g_south,l_text:arial_20:Angular,y_20/a_20/angular_logo.jpg">

Creating video tags with cl-video and cl-transformation

The cl-video component generates a <video> tag with the requested transformation, type, and format. The component automatically generates video <source> URLs for all formats supported by web browsers (webm, mp4 and ogv) as a fallback in case the user's browser doesn't support one of them.

The video tag can contain optional cl-transformation elements that will be used for chained transformations.

The following example demonstrates creating a video tag with a single transformation.

<cl-video public-id="manipulation_video" cloud_name="cloudinary" 
   controls="true" preload="none" width="925" crop="scale" 
   autoplay="true"  class="manipulation-video"
   fallback-content="Your browser does not support HTML5 video tags">
<cl-transformation overlay="text:arial_20:Cloudinary%20features" 
   color="red" gravity="north" y="12"></cl-transformation>
</cl-video>

The component automatically adds the source elements and a poster. The example above is compiled by Angular to:

<video _ngcontent-odx-3="" autoplay="true" class="manipulation-video" 
   controls="true" preload="none" publicid="manipulation_video" 
   ng-reflect-public-id="manipulation_video" width="925"
   poster="http://res.cloudinary.com/cloudinary/video/upload/co_red,g_north,l_text:arial_20:Cloudinary%20features,y_12/c_scale,w_925/manipulation_video.jpg">
<source src="http://res.cloudinary.com/cloudinary/video/upload/co_red,g_north,l_text:arial_20:Cloudinary%20features,y_12/c_scale,w_925/manipulation_video.webm" 
   type="video/webm">
<source src="http://res.cloudinary.com/cloudinary/video/upload/co_red,g_north,l_text:arial_20:Cloudinary%20features,y_12/c_scale,w_925/manipulation_video.mp4" 
   type="video/mp4">
<source src="http://res.cloudinary.com/cloudinary/video/upload/co_red,g_north,l_text:arial_20:Cloudinary%20features,y_12/c_scale,w_925/manipulation_video.ogv" 
   type="video/ogg">
Your browser does not support HTML5 video tags
</video>

Attribute directives for enhancing HTML elements - clSrc, clHref, clSrcset

The clSrc, clHref, and clSrcset directives use the element attributes to generate image URLs in Cloudinary.

The following example demonstrates an image thumbnail that displays the full size image when clicked, displaying the full size image optimized with auto quality as a transformation:

<a clHref={{photo.public_id}} format="jpg" target="_blank">
<cl-transformation quality="auto" fetch-format="auto"></cl-transformation>
<cl-image publicId={{photo.public_id}} class="thumbnail inline" width="150" 
   height="150" crop="fit" quality="80" format="jpg">
</cl-image>
</a>

Is this an upgrade of the previous Cloudinary AngularJS SDK?

No. Since Angular itself is a rewrite of AngularJS, the new Angluar SDK is not backwards compatible with Cloudinary’s AngularJS (A.K.A Angular 1) SDK.

However, we are happy to share some tips regarding the migration path for upgrading your previous AngularJS app using Cloudinary’s SDK to the new one.

Migration path

We’ve tried to keep the APIs as close as possible to the original names. We’ve made some changes to conform to Angular’s new style guide.

• clHref, clSrc, clSrcset - These directives have been renamed from cl-href, cl-src, cl-srcset to be consistent with Angular's directive selector naming guidelines
• cl-video - has been added to the new SDK:

Angular 1 SDK:

 <a cl-href="{{photo.public_id}}" format="jpg" target="_blank">

Angular 2 SDK:

<a clHref="{{photo.public_id}}" format="jpg" target="_blank">

Can you share tips and tricks from the upgrade ?

In addition to the process of upgrading your Cloudinary SDK code, you may want to consider the following as you migrate your own Angular 1 app to the new version:

• Use the Angular 1 to 2 quick reference for updating your application's Angular syntax. Following it will get most of your application ready for Angular2.
• Pay special attention to the new binding syntax. Read it carefully, understand the new mental model and take note of the different binding syntaxes for the different data directions, i.e.
  • One-way from data source to view target. There are 3 different styles for this type of binding:
    • {{expression}} (known as "Interpolation")
    • [target] = "expression" (known as "Property attribute")
    • bind-target = "expression"
  • One-way from view target to data source. There are 2 different styles for this type of binding:
    • (target) = "statement"
    • on-target = "statement"
  • Two-way. There are 2 different styles for this type of binding:
    • [(target)] = "expression"
    • bindon-target = "expression"
• A lot of content has already been created for the Angular release candidates. Some do not apply to the final released version. Pay attention to the Angular versions in question and dates in the blog posts and StackOverflow answers you read.
• Check out this curated list of awesome Angular 2 resources by @AngularClass. It has a lot of references for deep diving into Angular’s new architecture and implementation.

Anything else?

Yes. I'm glad you asked.

We’ve created sample projects for the SDK, demonstrating different capabilities and options. In addition, we’ve created a plunker so you can get up and running in no time, without any setup!

The sample projects have the same functionality - a photo list displaying a list of images that respond to a predefined tag, and an upload page for adding images to the list.

The projects differ in their bundling solutions and image upload mechanisms:

Photo Album

This project uses:

• ng2-file-upload for uploading files using an open source file uploader
• Webpack for bundling and serving the application

Photo Album with jQuery

This project uses:

• Cloudinary's jQuery plugin for uploading files using jQuery and blueimp
• SystemJS for bundling the application
• lite-server as the web server serving the application

Photo Album AOT application

This project demonstrates how the Cloudinary SDK could be used in an Angular application created by Angular’s Ahead of Time compiler. It uses:

• Angular’s template compiler for ahead-of-time compilation of the application
• Rollup for bundling the application
• lite-server as the web server serving the application

Plunker

The plunker code sample is configured to use Cloudinary’s demo cloud, and demonstrates usage of <cl-image> tags. Feel free to fork it and experiment with your own cloud credentials.

Summary

Whether the night was moist, humid, or sultry the main thing here is that you can easily integrate Cloudinary into your Angular application with the new SDK.

These are the basics:

• Use cl-image and cl-transformation for expressively serving images from your Cloudinary account.

• Use cl-video and cl-transformation for expressively serving videos from your Cloudinary account, setting up multiple sources for different browsers automatically.

• Use clSrc, clHref or clSrcset for enhancing native HTML elements to serve images from your Cloudinary account.

For more detail on all available Cloudinary Angular directives and components, see the SDK documentation

Developing a library requires a different approach from developing an application. You must consider the use of the library in someone else’s application and design for it. React is well suited for this purpose. And if the library you are creating is an adapter to another library, you can dynamically generate the component's properties definition to ensure they are forward compatible. There is however more than one way to achieve the same goal, with some conventions to follow and others to cautiously not follow. In particular, I chose to use the context function even though it is an experimental feature because it is useful when you don’t know, or can’t dictate, the way your library's components will be utilized.

The React framework

What’s react?

React is a JavaScript library developed by Facebook that specializes in rendering data as HTML and is widely used by websites such as Netflix, Imgur, Airbnb, and of course Facebook.

Why develop a React SDK?

An SDK or library provides a developer access to underlying functionality without exposing the complexity of the implementation. A library is most useful when it exposes the functionality using the syntax, components and methodology of the environment it is deployed in. In Cloudinary’s case, we already provide a Cloudinary JavaScript library that can be used in any JavaScript based applications. However in order for us to support developers that are using React to create fast and responsive websites, we wanted to provide them with a convenient React library that they could use to deliver media from Cloudinary. In effect, we needed to provide React components that the developer can integrate directly in their application. These components in turn would take advantage of the functionality provided by the Cloudinary Core JavaScript library. The rest of this tutorial demonstrates how I developed our React library. This will not be a comprehensive description of our library but rather a guide that will (hopefully!) help you develop your own ReactJs library.

Basic requirements

Cloudinary provides a service for a cloud based storage, manipulation and delivery of images and other media content. Thus at minimum, a Cloudinary React library would need to deliver media resources from Cloudinary, as well as define transformations on those resources. The library should also allow the developer to configure the Cloudinary service and configure the Cloudinary account (represented by the cloud_name) to deliver resources from.

Thus the scope of version 1.0 of our library is:

• Configuration
• Image tag
• Transformation parameters

I added code samples to accompany this post in our repository. To review the code, issue the following commands:

git clone https://github.com/cloudinary/cloudinary-react
git checkout library-how-to-step-1

You will find a similar command line at the beginning of each section below. Use it to review the code described in that section.

Getting to work

Setting up the project

JavaScript is an implementation of the ECMAScript specifications with support for the different versions of ES differing between browsers and browser versions. As a library developer, you would like your library to be supported in as many clients as possible, and these days, that would imply using ES5 (more).

Yet, while it may be possible to write a React program using plain ES5, React normally utilizes ES6 syntax as well as JSX, packing it all with webpack. ES6 (also known as EcmaScript 6 or ES2015) introduces many new features to JavaScript, including classes and scoped variables. JSX on the other hand, provides a convenient way to include HTML code in JavaScript. When developing a library you can’t always know how it will be utilized. Thus we need to provide developers with sources that can be accessed directly, as well as a compiled JavaScript distribution file that can be imported directly in the browser. In order to utilize these features, several libraries must be included in your project:

• The React libraries.
• Babel - translates ES6 and JSX to the more widely supported ES5.
• Webpack - packing javascript applications, and providing a development server.
• The Cloudinary JavaScript library (duh!).

Babel and Webpack each require a configuration file. You can see an example of the configuration at https://github.com/cloudinary/cloudinary-react/tree/library-how-to-step-1.

Folder structure

Each component will reside in its own folder. A package.json file is also included in each folder to allow using the “import ‘./folder_name’;” syntax instead of the more verbose “import ‘./folder_name/filename’;” style.

An alternative would be to have one JS file per component. When using this approach you also need to include an index.js file that exports the components.

There are pros and cons to each approach, but I’ll leave that discussion for another day.

Creating the Image component

git checkout library-how-to-step-2

The first Component we’ll implement will be used to display an image. The image component should:

• Accept configuration parameters.
• Accept transformation parameters.
• Accept an image public ID (the image's unique identifier).
• Render an <img> tag with a constructed URL to display the image.

Humble beginnings

We will start by defining a simple image component. The component will accept a cloud name, public ID and dimensions, and will then create an <img> tag to render the image. A React component can be defined as a function or as a class. We’ll define all Cloudinary components as classes. The difference between the function and class approach is discussed here.

import React, {Component, PropTypes} from 'react';
import cloudinary from 'cloudinary-core';

export default class Image extends React.Component {
 constructor(props) {
   super(props);
 }

 render() {
   let cl = cloudinary.Cloudinary.new({cloud_name: this.props.cloudName});
   var {publicId, width, height} = this.props;
   var url = cl.url(publicId, {width, height, crop: "scale"});
   return (
     <img src={url} />
   );
 }
}

Image.propTypes = {
 cloudName: PropTypes.string.isRequired,
 publicId: PropTypes.string.isRequired,
 width: PropTypes.number,
 height: PropTypes.number
};
Image.defaultProps = {};

Our component is simple enough. It declares 4 properties as well as their type and whether they are required. The render method, which is invoked whenever the component needs to be rendered, uses the properties values to generate a Cloudinary URL, and returns an <img> tag with that URL.

Seeing is believing

Unlike an application, we can’t simply run our library to see the results. To test it, we’ll create a simple HTML page named “image.html” under the “samples” folder.

<!DOCTYPE html>
<html lang="en">
<head>
   <meta charset="UTF-8">
   <title>Cloudinary Image Component</title>
   <script src="../node_modules/react/dist/react.js"></script>
   <script src="../node_modules/react-dom/dist/react-dom.js"></script>
   <script src="https://unpkg.com/babel-standalone@6.15.0/babel.min.js"></script>
   <script src="../node_modules/cloudinary-core/cloudinary-core-shrinkwrap.js"></script>
   <script src="../dist/cloudinary-react.js" ></script>
</head>
<body>

<div id="root"></div>
<script type="text/babel">
 let Image = cloudinaryReact.Image;
 ReactDOM.render(
         <Image width="400" cloudName="demo" publicId="sample"></Image>,
   document.getElementById('root')
 );

</script>
</body>
</html>

It works!

(Notice that we are using the babel-standalone library in order to translate JSX syntax in the browser!)

Deciding what properties to expose

A React component is affected by two sets of information: the properties and the state. Generally speaking, properties are public and may be set by a parent of the component. State is private and is not accessed outside the component.

A Cloudinary image delivery URL may accept many parameters that affect the resulting image. Furthermore, Cloudinary keeps coming up with new options almost weekly. For these reasons, we want the component to be forward compatible - that is be able to accept new configuration options in the future.

There are two ways to implement the the configuration and transformation options:

• As two properties whose values are a collection of parameters.
• As individual options. The former option has the advantage of strongly typing the signature of the component - we know that there are two properties named, say, options and transformation. In addition, the developer can prepare the options and transformation objects in advance:

<Image options={{cloudName:"demo", publicId:"sample"}} transformation={{width: 100, crop: "crop"}}/>

Or,

let options={publicId: "dog", secure: true};
let transformation={crop: "scale", format: "jpg", width: 300};

<Image options={options} transformation={transformation} ></Image>

The disadvantage is that they encapsulate the actual parameters and thus make the component less readable.

Compare this with the latter option. Here each configuration and transformation option is an individual property of the component:

<Image cloudName="demo" publicId="sample" width="100" crop="scale" angle="10"/>

I think this is much nicer, don’t you?

Back to the Future

git checkout library-how-to-step-3

A React component’s properties must be declared. Property values are checked in development mode and will produce a warning if they are invalid. To keep the definition future-compatible, we need to automatically define all configuration and transformation properties. This is done by listing all configuration and transformation keys from the cloudinary_js library. For simplicity, we define all properties as strings.

let allParams = cloudinary.Configuration.CONFIG_PARAMS.concat(cloudinary.Transformation.PARAM_NAMES);
Image.VALID_OPTIONS = allParams.map(camelCase);
Image.propTypes = typesFrom(Image.VALID_OPTIONS);

This code segment uses two utility functions, provided by the Util module of the Cloudinary Core JavaScript library:

• camelCase - converts a string to CamelCase
• typesFrom creates a properties definition object from an array of property names

Attributes

When designing the component interface (mainly, the properties of the component), you should carefully consider its utilization. For example, the developer may wish to provide attributes for the resulting tags. To allow the developer to explicitly provide the tag attributes, we will use the Transformation.toHtmlAttributes() method. This method collects all the properties that have a name that starts with “html_”, adds additional attributes calculated from the input, and returns them all as a set of HTML attributes that can be assigned to an HTML tag.

The spread operator (...) is required to convert the attributes object to key=value sets for the component.

let attributes = transformation.toHtmlAttributes();
return (
 <img {...attributes} src={url} />
);

Nested components - adding the Transformation component

git checkout library-how-to-step-4

A cloudinary resource can be defined using several transformations which are chained together. We can represent this chain by providing an array of objects to the transformation property. But that brings us back to the complex properties approach which we want to avoid.

<Image cloudName="demo" publicId="sample" width="100" crop="scale" angle="10"
      transformation={[{width: 100, crop: "crop"}, {width: 100, angle: -10, crop: "scale"}]}/>

To reduce this complexity, we introduce a new component: Transformation. This is a virtual component, i.e., it does not render to the DOM/HTML. Instead, it represents a transformation that affects the image component.

<Image cloudName="demo" publicId="sample">
   <Transformation width="100" crop="crop"/>
   <Transformation angle="-10" crop="scale" width="100"/>
</Image>

The Transformation component should not render a DOM node or HTML tag. But its properties should be available to the encapsulating Image component.

Preventing the component from rendering is easy. Simply return null from the render method:

render() {
  return null;
}

Access to the encapsulated components is done through the children property (this.props.children). React also provides a convenience method to map over the children. You should check the type of the child before using its properties.

let childrenOptions = React.Children.map(this.props.children, child =>{
 if (child.type && child.type.name === "Transformation"){
   return getOptions(child.props);
 } else {
   return {};
 }
});

What next?

So far we created an image component and a transformation component. We figured out a way to declare the properties of the component dynamically to support all the parameters of the underlying cloudinary_js library. We also devised a way for the image component to gather properties from its children.

To complete the CloudinaryReact library we will need to create a video component. When you do this you will quickly realize that your are duplicating code between the components. This can be solved by moving shared code to the Util object, or by introducing a common ancestor class to both the image and video component. The React documentation advises the former method (see here and here), but we preferred the latter, as it produces a cleaner and more modular code. What’s your preference?

We will also need to tie our image components to the browser’s resize event in order to provide responsive behaviour - the automatic selection of image size to fit the viewing area.

Another feature that would be useful is the ability to define common configuration parameters for a group of components or the entire page. We chose to use context for this purpose even though the React documentation vehemently advises against it as it is considered to be experimental and may be removed in future releases of React. Instead they suggest using Redux or passing an entire component as a property. This may be right for an application but not for a library. The application the library is used in may not be a redux application. Passing the properties down to the children is also not practical as the components who require the information may not be direct descendents of the parent passing the configuration parameters. On the flip side, using context will require us to provide an alternative solution if the functionality is removed in a future release of React.

All this, however, is beyond the scope of this post. As soon as I get a break from my coding tasks, I’ll post the next post on this subject.

git checkout master

You can review the implementation of these ideas as well as other components in our Cloudinary React library, and of course suggest your solutions in the comments.

In part 1, we discussed the basics of Adonis, including how to setup Adonis projects, and create migrations, models, a few routes, and a controller to test the creation of new posts.

Now, let’s extend what we already know to reading posts, updating existing posts, deleting posts, and adding an image upload feature.

Reading existing posts

With the create feature implemented, we must have created posts in our store. These posts will be read from our store and displayed on the browser.

We need to update the index route to point to a controller, rather than sending a view directly as it already does:

// ./app/Http/routes.js
...
// What we had:
// Route.on('/').render('welcome');
// Update to:
Route.get('/', 'PostController.index');
...

Next, we add an action method to our controller named index. This method will be responsible for fetching the data from our model and sending the data to our view:

// ./app/Http/Controllers/PostController.js
...
* index(request, response) {
    const posts = yield Post.all();
    yield response.sendView('post/index', {posts: posts.toJSON()});
}
...

The route points to an existing method, which sends a view with our retrieved data. Let’s create this view:

<h2>Articles <a href="/new" class="ui blue button">New Post</a></h2>
<div class="ards">
  {% for post in posts %}
  <div class="card">
    <div class="content">
        <a class="header">{{post.title}}</a>
        <div class="meta">
            <span class="date">{{post.created_at}}</span>
        </div>
        <div class="description">
        {{post.body.substring(0, 50)}}...
        </div>
    </div>
  </div>
  % else %}
  <h3> No posts found </h3>
  {% endfor %}
</div>

Reading a single post

One other form of showing posts is reading and displaying a single post, which gives us more room for the details about the post. To do this, you need a route and a controller. Here is the route:

// ./app/Http/routes.js
Route.get('/post/:id', 'PostController.read');

The :id part of the URL is a placeholder for the route parameter. The parameter will be a unique value that points to a given post.

// ./app/Http/Controllers/PostController.js
* read(request, response) {
     // Receive parameter from request
     const id = request.param('id');
     // Find id with request parameter
     const post = yield Post.find(id);
     yield response.sendView('post/read', {post: post});
 }

The controller’s read action method receives the id parameter from the request object. We then use the model’s find method to find a post based on the value passed in.

The view sent is named read in the post folder and we are passing the post data down to the view as well:

<h2>{{post.title}}</h2>
<small>{{post.created_at}}</small>
<p>{{post.body}}</p>

You can update the link for each post on the home page to point to the read URL:

<a class="header" href="/post/{{post.id}}">{{post.title}}</a>

Updating posts

What happens when we realize that our post requires an update? We can create a form just like we did for the new post form, but this time we will send the existing post to the form. First, we need to specify some routes, as usual:

// ./app/Http/routes.js
// Edit form
Route.get('/edit/:id', 'PostController.edit');
Route.post('/update', 'PostController.update');

With respect to the routes above, the following action methods will serve as handlers for both routes:

* edit(request, response) {
    const id = request.param('id');
    const post = yield Post.find(id);
    yield response.sendView('post/edit', {post: post});
}
* update(request, response) {
    var postData = request.only('id', 'title', 'body');
    const id = postData.id;
    const post = yield Post.find(id);
    // Update and save post
    post.fill(postData);
    yield post.save();
    // Go home
    response.redirect('/');
}

The edit action method sends a view. This view will hold our form template for editing the selected post:

  <h2>{{post.title}}</h2>
  {{ form.open({action: 'PostController.update'}) }}

    {{ csrfField }}

    <div class="ui form">
        <div class="field">
            {{ form.label('Title') }}
            {{ form.text('title', post.title) }}
        </div>

        <div class="field">
            {{ form.label('Body') }}
            {{ form.textarea('body', post.body) }}
        </div>

        {{form.hidden('id', post.id)}}

        {{ form.submit('Create', 'create', { class: 'ui blue button' }) }}
    </div>

  {{ form.close() }}

The default values are set using the existing values in our store. The post’s id is also available on the form via a hidden input.

For each post listed on the home page, we'll also add an edit button that points to the relevant edit URL:

...
<a class="ui basic green button" href="/edit/{{post.id}}">Edit</a>
...

Deleting posts

The route for deleting post is very similar to the read and edit routes. It takes a parameter for searching the post to be removed:

Route.get('/delete/:id', 'PostController.delete');

Note: Best practices suggest that you do not use GET to update state as we are doing right now. For the sake of this demo’s simplicity, we can overlook that practice.

The action method on the controller is delete and it finds the post based on the id parameter and then deletes the found post:

* delete(request, response) {
    var post = yield Post.find(request.param('id'));
    yield post.delete();
    response.redirect('/');
}

We can add a link to the post list to point to the delete URL:

<a class="ui basic red button" href="/delete/{{post.id}}">Delete</a>

Featured image uploads

Contents are always accompanied with images. In the case of a CMS, these images could be embedded right inside the content or serve as a banner to a given content. The banner is usually known as a featured image.

Cloudinary is the image management back-end for web and mobile developers. With Cloudinary, we can add images to our content with ease, thereby saving as the hassle of managing storage, as well as image uploads, downloads, manipulation, delivery and administration.

With the Cloudinary free account, we can begin using these features in our projects. Let’s see how by adding a featured image to our posts.

After you set up a Cloudinary account, you can create an upload preset. Upload presets enable you to centrally define a set of image upload options instead of specifying them in each upload call. We will use the preset when making an upload request.

Cloudinary provides JavaScript plugins that make image upload to the Cloudinary server very easy. Here’s how we include these scripts:

<script src='https://cdn.jsdelivr.net/jquery.cloudinary/1.0.18/jquery.cloudinary.js' type='text/javascript'></script>
<script src="//widget.cloudinary.com/global/all.js" type="text/javascript"></script>
<script src="/script.js"></script>

The plugin depends on jQuery, so we also added our defined script.js file to the setup.

In the script.js file, we can start implementing the upload logic:

$(function() {
    // Configure Cloudinary
    // with credentials available on
    // your Cloudinary account dashboard
    $.cloudinary.config({ cloud_name: 'YOUR_CLOUD_NAME', api_key: 'YOUR_API_KEY'});

    // Upload button
    var uploadButton = $('#upload-button');
    var canvas = $('#canvas');
    var imageInput = $('#image-input');
    // Upload button event
    uploadButton.on('click', function(e){
        // Initiate upload
        cloudinary.openUploadWidget({ cloud_name: 'christekh', upload_preset: 'idcidr0h', tags: ['cgal']}, 
        function(error, result) { 
            if(error) console.log(error);
            // If NO error, log image data to console
            var id = result[0].public_id;
            canvas.html(procesImage(id));
            imageInput.val($.cloudinary.url(id, {}));
        });
    });
})

function procesImage(id) {
    var options = {
        client_hints: true,
    };
    return '<img src="'+ $.cloudinary.url(id, options) +'" style="width: 100%; height: auto"/>';
}

The above listens to a click event on a button in our view. When the button is clicked, the upload process starts. After an image is uploaded and returned, the image is displayed above the form. The URL is also embedded in a hidden input so it can be sent to the server and stored for future use, as well.

Going back to the posts/new view we already created, we can extend it to handle the logic we have prepared:

<h2>New Post</h2>
    <div class="paint_container" id="canvas">
        <!-- Canvas to drop image after processing -->
    </div>
  {{ form.open({action: 'PostController.create'}) }}

    {{ csrfField }}

    <div class="ui form">
        <div class="field">
            {{ form.label('Title') }}
            {{ form.text('title', null) }}
        </div>

        <div class="field">
            {{ form.label('Body') }}
            {{ form.textarea('body', null) }}
        </div>

        <input type="hidden" id="image-input" name="image">

        <button id="upload-button" class="ui purple button" type="button">Upload Featured Image</button>

        {{ form.submit('Create', 'create', { class: 'ui blue button' }) }}
    </div>

  {{ form.close() }}

The image also gets stored in our database, so we can also display it on the home page where we list the posts:

...
<div class="card">
    <div class="image">
        <img src="{{post.image}}" syyle="width: 100%; heigth: auto;">
    </div>
   ...

Have a look at the complete demo project.

Conclusion

Adonis is an awesome framework that is great to work with because of its simplicity. Media management can cause you sleepless nights, not just with Adonis, but any server-side framework. Cloudinary eliminates the stress and shortens the time you spend on media management, enabling you to focus on building out the other aspects of your application.

Christian Nwamba is a code beast, with a passion for instructing computers and understanding it's language. In his next life, Chris hopes to remain a computer programmer.