Imagga Smart Cropping, Collage Slicing and Background Removal API

This page explains how you can integrate our smart cropping, collage slicing and background removal functionalities in your project.

Contents

Smart Cropping API

The technology behind the API analyzes the pixel content of each given image in order to find the most "visually important" areas in the image. Having this information and evenutally some constraints, it can suggest the best cropping automatically.
You can get an immediate hands-on experience by testing our auto-cropping tool Cropp.me.

Smart Cropping API Functionality

An input digital image defined by public image URL is analyzed. As a result of the analysis the API outputs one or several rectangular regions with predefined size(s), or size(s) with the same aspect ratio. The desired output sizes are given as input parameters by the API CUSTOMER together with the input digital image(s). The API tries to suggest appropriate cropping(s) in order to select some of the most informative and visually interesting parts of the input image, where possible.

Note: The output contains the coordinates of what should be cropped, and NOT the sub-images raster data itself.

Smart Cropping API Call

You need to make a POST request to a server-side script hosted in the API endpoint that your API account is associated to. The URL is:
http://<your-api-endpoint-here>/extractionrestserver.php

The parameters that should be supplied when making the POST request to this URL are given below.

Call POST parameters:
    • method
      required
    • The identifier of the particular method. For this particular call it is always fixed to imagga.process.crop
    • v
      required
    • The API version number. Currenly always fixed to 1.0
    • urls
      required (if upload_code is not present)
    • Comma-separated list of (one or more) public image URLs to be smart-cropped.
      Example Value:
      http://www.stockpodium.com/stock-photo-7890736/couple-child-spending-time-together-image.jpg,http://www.stockpodium.com/stock-photo-7314730/hand-keys-car-image.jpg
    • upload_code
      required (if urls is not present)
    • Upload code generated after uploading image for processing, instead of providing URL. You can learn more about using upload for processing here.
      Example Value:
      73f/1365268432-951977319.png
    • delete_afterwards
      optional
    • This parameter is only meaningful if combined with upload_code. If its value is 1 the image that has been uploaded will be deleted after the processing task. Otherwise the image associated with the corresponding upload code will be available for other processings in the next one hour.
      Example Value: 1
    • resolutions
      optional
    • Comma-separated list of (one or more) width and height pairs defining the target size (the size that the images should be resized to). If this parameter is omitted the system will suggest croppings that cover the main parts of what is considered visually interesting in the given images.
      Example Value (that will suggest three croppings, 150x200, 100x50, and 75x75, for earch of the input images): 150,200,100,50,75,75
    • no_scaling
      optional
    • If this paramter is provided and its value is1 the system will keep strictly to the specified resolutions and not only to their aspect ratios. Otherwise, if this parameter is omitted or if its value is 0, the system actually suggests the maximum rectangle with the same aspect ratio as the required resolution, so that the API user will practically get a combination of cropping and thumbnailing at the same time.
      Default Value: 0
    • api_key
      required
    • API customer key. This is the key you've been given when creating your API account.
      Example Value: aaaa1111bbbb2222
    • sig
      required
    • API call signature. The signature serve as simple and secure scheme to protect your call against spoofing and other identity thieft attacks. The signature is generated by hashing all current paramers and values and the API customer secret. More information about how to generate the signature can be found here.

If PHP is the language of your choice you can benefit from the existing implementation of this method as part of the cropping and slicing API client included in the PHP API kit.

Sample call is given below.

Making the call using the PHP client library:
$crop_slice_api_client = new CropSliceAPIClient(IMAGGA_API_KEY, IMAGGA_API_SECRET, IMAGGA_API_ENDPOINT);

// eventually some other code here ...

try
{
    $smart_croppings = $crop_slice_api_client->smart_cropping_by_urls(
        array(  // two images submitted for cropping here
			'http://www.stockpodium.com/stock-photo-7890736/couple-child-spending-time-together-image.jpg',
			'http://www.stockpodium.com/stock-photo-7314730/hand-keys-car-image.jpg'
        ),
		array( // the target resoltions in a single list: w1, h1, w2, h2, ...
			150, 200, 100, 50, 75, 75
		),
		0  // scale the image while cropping
    );
}
catch (Exception $e) {
    echo 'Caught exception: ' . $e->getMessage();
}
Sample Response (the raw JSON encoded response that will be read by either your implementation or the existing PHP client library. Click below to expand!):
{
  "smart_croppings":[
    {
      "url":"http:\/\/www.stockpodium.com\/stock-photo-7890736\/couple-child-spending-time-together-image.jpg",
      "croppings":[
        {
          "target_width":"150",
          "target_height":"200",
          "x1":156,
          "y1":0,
          "x2":355,
          "y2":265
        },
        {
          "target_width":"100",
          "target_height":"50",
          "x1":0,
          "y1":0,
          "x2":399,
          "y2":200
        },
        {
          "target_width":"75",
          "target_height":"75",
          "x1":86,
          "y1":0,
          "x2":352,
          "y2":265
        }
      ]
    },
    {
      "url":"http:\/\/www.stockpodium.com\/stock-photo-7314730\/hand-keys-car-image.jpg",
      "croppings":[
        {
          "target_width":"150",
          "target_height":"200",
          "x1":61,
          "y1":0,
          "x2":286,
          "y2":299
        },
        {
          "target_width":"100",
          "target_height":"50",
          "x1":0,
          "y1":37,
          "x2":399,
          "y2":237
        },
        {
          "target_width":"75",
          "target_height":"75",
          "x1":24,
          "y1":0,
          "x2":324,
          "y2":299
        }
      ]
    }
  ]
}

If you use the PHP kit client library you'll have the JSON response already decoded and returned as an Object that you can use in your code.

Collage Slicing API

The collage slicing is pretty handy if you have a single image (e.g. JPEG or PNG file) that actually contains several images, typically separated with some kind of straight borders, and you want to slice the single image file in the original multiple images that are inside.

Collage Slicing API Functionality

An input digital image, defined by public image URL, is processed and any sub-images contained in it, if detected, are extracted as separate output images. Input images are expected to contain sub-images arranged as a collage and being separated by separation lines. If no sub-images are detected, the input image is returned as output image.

Note: In all cases defined above, the output contains the coordinates defining each of the rectangular sub-images and NOT the sub-images raster data itself.

Collage Slicing API Call

Call POST parameters:
    • method
      required
    • The identifier of the particular method. For this particular call it is always fixed to imagga.process.division
    • v
      required
    • The API version number. Currenly always fixed to 1.0
    • urls
      required
    • Comma-separated list of (one or more) public image URLs to be processed for slicing.
      Example Value:
      http://78.128.78.162/test/collage.jpg,http://78.128.78.162/test/dividing/1.jpg,http://78.128.78.162/test/dividing/3.jpg
    • api_key
      required
    • API customer key. This is the key you've been given when creating your API account.
      Example Value: aaaa1111bbbb2222
    • sig
      required
    • API call signature. The signature serve as simple and secure scheme to protect your call against spoofing and other identity thieft attacks. The signature is generated by hashing all current paramers and values and the API customer secret. More information about how to generate the signature can be found here.

If PHP is the language of your choice you can benefit from the existing implementation of this method as part of the cropping and slicing API client included in the PHP API kit.

Sample call is given below.

Making the call using the PHP client library:
$crop_slice_api_client = new CropSliceAPIClient(IMAGGA_API_KEY, IMAGGA_API_SECRET, IMAGGA_API_ENDPOINT);

// eventually some other code here ...

try {
    $division_regions = $crop_slice_api_client->division_regions_by_urls(
        array(  // simply an array with the URLs of the collage images you want to be sliced
			'http://78.128.78.162/test/collage.jpg',
			'http://78.128.78.162/test/dividing/1.jpg',
			'http://78.128.78.162/test/dividing/3.jpg',
		)
	);
}
catch (Exception $e) {
    echo 'Caught exception: ' . $e->getMessage();
}
Sample Response (the raw JSON encoded response that will be read by either your implementation or the existing PHP client library. Click below to expand!):
{
   "division_regions":[
      {
         "url":"http:\/\/78.128.78.162\/test\/collage.jpg",
         "regions":[
            {
               "x1":"284",
               "y1":"197",
               "x2":"523",
               "y2":"350"
            },
            {
               "x1":"549",
               "y1":"197",
               "x2":"794",
               "y2":"350"
            },
            {
               "x1":"13",
               "y1":"197",
               "x2":"258",
               "y2":"350"
            },
            {
               "x1":"284",
               "y1":"376",
               "x2":"523",
               "y2":"535"
            },
            {
               "x1":"549",
               "y1":"376",
               "x2":"794",
               "y2":"535"
            },
            {
               "x1":"13",
               "y1":"376",
               "x2":"258",
               "y2":"535"
            },
            {
               "x1":"284",
               "y1":"13",
               "x2":"523",
               "y2":"171"
            },
            {
               "x1":"549",
               "y1":"13",
               "x2":"794",
               "y2":"171"
            },
            {
               "x1":"13",
               "y1":"13",
               "x2":"258",
               "y2":"171"
            }
         ]
      },
      {
         "url":"http:\/\/78.128.78.162\/test\/dividing\/1.jpg",
         "regions":[
            {
               "x1":"525",
               "y1":"13",
               "x2":"1010",
               "y2":"452"
            },
            {
               "x1":"13",
               "y1":"13",
               "x2":"499",
               "y2":"452"
            }
         ]
      },
      {
         "url":"http:\/\/78.128.78.162\/test\/dividing\/3.jpg",
         "regions":[
            {
               "x1":"524",
               "y1":"13",
               "x2":"1010",
               "y2":"754"
            },
            {
               "x1":"13",
               "y1":"13",
               "x2":"498",
               "y2":"754"
            }
         ]
      }
   ]
}

Background Removal API

(Still in Beta!)

The automated background removal is pretty handy if you have an image file with solid background that you want to remove (to make it transparent), for example in order to show the main object of interest on different background, or as another example - to allow users to create clippings out of several images.

Background Removal API Functionality

An input digital image, defined by public image URL, is processed and the system returns an URL pointing to newly creating PNG image with an alpha channel that shows the suggested transparent regions (the removed background).

Note: The result PNG images are deleted one hour after they've been created so you need to integrate a way to download them soon (or eventually immediately) after you receive their URLs as a response of the API.

Background Removal API Call

Call POST parameters:
    • method
      required
    • The identifier of the particular method. For this particular call it is always fixed to imagga.process.backgroundremoval
    • v
      required
    • The API version number. Currenly always fixed to 1.0
    • urls
      required (if upload_code is not present)
    • Comma-separated list of (one or more) public image URLs to be processed for background removal.
      Example Value:
      http://78.128.78.162/test/sweater.jpg,http://78.128.78.162/test/top.jpg,http://78.128.78.162/test/dress.jpg
    • upload_code
      required (if urls is not present)
    • Upload code generated after uploading image for processing, instead of providing URL. You can learn more about using upload for processing here.
      Example Value:
      73f/1365268432-951977319.png
    • delete_afterwards
      optional
    • This parameter is only meaningful if combined with upload_code. If its value is 1 the image that has been uploaded will be deleted after the processing task. Otherwise the image associated with the corresponding upload code will be available for other processings in the next one hour.
      Example Value: 1
    • api_key
      required
    • API customer key. This is the key you've been given when creating your API account.
      Example Value: aaaa1111bbbb2222
    • sig
      required
    • API call signature. The signature serve as simple and secure scheme to protect your call against spoofing and other identity thieft attacks. The signature is generated by hashing all current paramers and values and the API customer secret. More information about how to generate the signature can be found here.

If PHP is the language of your choice you can benefit from the existing implementation of this method as part of the cropping and slicing API client included in the PHP API kit.

Sample call is given below.

Making the call using the PHP client library:
$crop_slice_api_client = new CropSliceAPIClient(IMAGGA_API_KEY, IMAGGA_API_SECRET, IMAGGA_API_ENDPOINT);

// eventually some other code here ...

try {
	$background_removal = $crop_slice_api_client->remove_background_by_urls(
        array(  // three images submitted for background removal here
			'http://78.128.78.162/test/sweater.jpg',
			'http://78.128.78.162/test/top.jpg',
			'http://78.128.78.162/test/dress.jpg'
        )
    );
}
catch (Exception $e) {
    echo 'Caught exception: ' . $e->getMessage();
}
Sample Response (the raw JSON encoded response that will be read by either your implementation or the existing PHP client library. Click below to expand!):
	
{
	"background_removal":[
		{
			"url":"http:\/\/78.128.78.162\/test\/sweater.jpg",
			"png_url":"http:\/\/78.128.78.162\/temp\/bgrmout3f36ca25da3c6ae5a75132f2c035a09d.png"
		},
		{
			"url":"http:\/\/78.128.78.162\/test\/top.jpg",
			"png_url":"http:\/\/78.128.78.162\/temp\/bgrmout618951d782a55ecea5de5491c1185b95.png"
		},
		{
			"url":"http:\/\/78.128.78.162\/test\/dress.jpg",
			"png_url":"http:\/\/78.128.78.162\/temp\/bgrmout3f6aec2c6d2b5bc7ce193181eb9f2dbd.png"
		}
	]
}

PHP API Kit

After you successfully register for an API account you are going to recieve an e-mail containing links to the API kits for several different platform, including PHP.
You'll be able to test the kit immediately after you deploy its content on some of your test servers and navigate a browser to the "crop_slice_demo.php" file.
Below is given a brief overview of the files in the kit.

The 'usual suspect' in the kit the is the "account_config.php" file where you need to fill in your API key, secret, and endpoint.

account_config.php
<?php

// please replace your_api_key_here with your actual Imagga API key
define('IMAGGA_API_KEY', 'your_api_key_here');

// please replace your_api_secret_here with your actual Imagga API secret
define('IMAGGA_API_SECRET', 'your_api_secret_here');

// please replace your_api_endpoint_here with your actual Imagga API endpoint
define('IMAGGA_API_ENDPOINT', 'your_api_endpoint_here');

?>

The API client (PHP class) that implements the calls to the particular cropping and slicing API methods

lib/crop_slice_api_client.php
<?php

// some legal words here...

class CropSliceAPIClient
{
	// the actual class implementation here ...
}


class CropSliceAPIClientException extends Exception
{
}

?>

And a sample script that demonstrate how to use the cropping and slicing API methods. This script instantiate the CropSliceAPIClient class mentioned above, call its methods and visualize the results. It can be used as a blue-print for further tests and/or actual production-mode usage of the API.

crop_slice_demo.php
<?php

// some other code here ...

$crop_slice_api_client = new CropSliceAPIClient(IMAGGA_API_KEY, IMAGGA_API_SECRET, IMAGGA_API_ENDPOINT);

// eventually some other code here ...

try {
    $smart_croppings = $crop_slice_api_client->smart_cropping_by_urls((/* parameters here... */);
}
catch (Exception $e) {
    // handling the exception here...
}

// some other code here ...

try {
    $slices = $crop_slice_api_client->division_regions_by_urls(/* parameters here... */);
}
catch (Exception $e) {
    // handling the exception here...
}

// some other code here ...

try
{
    $background_removal = $crop_slice_api_client->remove_background_by_urls(/* parameters here... */);
}
catch (Exception $e) {
    // handling the exception here...
}

// some other code here ...

?>

Java API Kit

We have a Java API kit kindly donated! by Jakob Vad Nielsen on GitHub - https://github.com/lazee/imagga-java-kit.

Ruby API Kit

We have a Ruby API kit kindly donated! by Mart Karu on GitHub - https://github.com/martkaru/imagga.

Note: the Ruby kit doesn't implement the collage slicing, background removal and the upload support yet. However, if you urgently need any of these, you may implement them on your own, based on the documentation above.

Python API Kit

We have a Python API kit kindly donated! by Ivan Penchev on GitHub - https://github.com/ivanpenchev/imagga-py.

Node.js API Kit

We have a Node.js API kit kindly donated! by Georgi Kostadinov on GitHub - https://github.com/gkostadinov/imagga-nodejs.