Image Adaptation with DeviceAtlas

In this article we look at image adaptation using the DeviceAtlas API. For the mobile web it is often important to provide device specific images with correct format and size. Here we describe an Image Adaptation API, developed by Muntasir Mamun Joarder which makes use of the DeviceAtlas PHP API to to convert images on-the-fly into a format and size appropriate for the requesting device.

What does this API do?

The image adaptation API determines the relevant device capabilities (screen width, height, and supported image formats) of the requesting device using the DeviceAtlas PHP API, and uses these parameters, along with the source image properties, to prepare an output image that is appropriate for the requesting device. The following tasks are carried out prior to image conversion:

1. Decide the appropriate format of the output image
DeviceAtlas is queried to determine the most appropriate image format for the mobile device. The sequence followed is: PNG, JPG and GIF (default). So the function first searches whether the device supports PNG if not, then whether it supports JPG, otherwise the function considers the GIF. WBMP is intentionally kept out of the scope.

2. Decide the dimensions of the output image
In this case a function takes the source image dimensions as well as the mobile device screen dimensions as input, and computes the width and height of the output image.

Prerequisites

1. PHP Version 5.2.3 (and later). This is a requirement of the DeviceAtlas PHP API. DeviceAtlas makes use of the JSON functions in PHP version 5.2.3 (and later)

2. GD Library. GD is an open source code library for image manipulation. GD supports the creation of PNG, JPEG and GIF images. GD is commonly used to generate charts, graphics, thumbnails, and almost anything else, on the fly. In your php.ini file, the line extension=php_gd2.dll should be uncommented. Visit http://www.php.net/gd for details on gd.

3. DeviceAtlas PHP API. DeviceAtlas must be installed on your server. This can be downloaded from the DeviceAtlas download page.

Quick start guide

1. Download
Download the ZIP file from here.

2. Extract
Extract the ZIP into your PHP document root directory (generally it is htdocs) where you are hosting your PHP pages. You will get a folder named "ia" which contains the following directory structure and files

Directory structure

Assuming that DeviceAtlas has been installed in a directory called da, and assuming htdocs is your root web folder, then your full directory structure should be something like:

Directory structure

If you installed DeviceAtlas into a different directory then you should change the config.php file to reflect this. See section Configuration below.

The Image Adaptation API consists of the following files:

File or Folder Purpose
imgc This directory holds the source images, and contains some sample images. Also contains a folder named Resized which holds all the resized images.
config.php This file holds some default values.
imageAdaptation.php This is the heart of the rendering API. This file holds all the helper functions necessary for achieving the image adaptation.
example.php This is an example file showing how to use the function(s) to achieve adaptation.
simulator.php Running this file it will be possible to simulate the rendering effect on different types of images selecting different types of handsets.
Currently 848 different user agents are included in the list.
testHandset.txt Holds user agents and their make and model for use with the simulator. This list can be modified by the user.
info.php Used to check php setup.
index.php Contains links to image adaptation examples.

 

3. Try the example
Browse to http://YOUR_DOCUMENT_ROOT/ia/example.php from your handset. You should see a page with an image adapted to the width of your handset

4. Simulate different models using the device simulator app
Browse to http://YOUR_DOCUMENT_ROOT/ia/simulator.php from your PC. Now select any image and handset model and press "Check-it " to simulate how the image is adapted for that handset. If you select the image Eye and Handset Apple-iPhone then you will see something similar to that below:

Simulator screenshot

Where
Actual Image Resolution = 600(width) x 390(Height)
Device Resolution= 320X480
Resized Image Dimension= 320X208

The actual image is:

Full image

Also you will see the path of the resized image which is imgc/Resized/eye_320x208.png. So for Apple-iPhone the API found PNG as the best format.

The algorithm does the best effort conversion and tries to keep the image aspect ratio intact. So there may have some minimal resizing error which is because of keeping the source image aspect ratio intact.

Using the API in your own application

It is very simple to use the API in your own application. Below we show a sample page which makes use of the API. In this example we have kept our code in the ia directory, and our source image (something.jpg) inside the imgc directory. Save the code below as test.php:

Now just visit the URL http://YOUR_DOCUMENT_ROOT/ia/test.php from your mobile. If the API can detect your phone's capabilities it will render as per its algorithm. Otherwise it will resize the image to the default 120×120 pixels.

 

Configuration

The config.php file in the ia folder can be used to configure your application. It allows you to specify the default width & height of the adapted image, and the default format:

You should also configure the path to your DeviceAtlas JSON data here. By default this variable is set to the path of the sample JSON file included with the DeviceAtlas API download:

If necessary, this should be changed to reflect the path to the JSON file on your server.

 

Core API Functions

In this section we describe the major functions of the rendering API. All the functions reside in the file named "imageAdaptation.php". The functions are described in the table below

Function Input(s) Output(s) Description
convertImage $imagepath = Relative path of main image URL of the converted image. This function detects the requesting handset model and adapts the image ($imagepath).
A folder named Resized is created inside $imagepath, and resized image is stored here.
An example of the naming convention is image_128x83.jpg where the main image was image.jpg and 128×83 are the dimensions that the API calculated for the requesting device. If the API finds that this image already exists then it will not recreate the image to reduce load.
convertImageUA $imagepath = Relative path of main image

$ua = User-agent

URL of the converted image. Similar task. Use this function if you want to simulate your code for different user-agents.
setImageDimension $imageWidth = Main image width

$imageHeight = Main image height

$deviceWidth = Device screen width

$deviceHeight = Device screen height

array ($imageDimensionWidth,$imageDimensionHeight) where

$imageDimensionWidth = Width of the converted image
$imageDimensionHeight = Height of the converted image
These are the dimensions those the API algorithm calculated and the name of the converted image is also created using these (like eye_128x83.jpg).

As inputs this function takes the dimensions(height and width) of the device (determined from DeviceAtlas) and the dimensions of the actual image. The ouput is an array which holds the proposed dimension (height and width). (This is the heart of the API)
getCAP $ua = User-agent array ($bestFormat,$maxWidth,$maxHeight,$Decision) where

$bestFormat = Best format supported by this device. $maxWidth= Max device width
$maxHeight= Max device height
$Decision=One of the three values as below
0=Resize it considering the default value
1=DONT Resize
2=Resize as per the device capabilities

Takes the USER-AGENT of the requesting device as an input and outputs the device capabilities (best image format for this device, max screen resolution of device etc) in an array.
Also one major value is passed through this output array which is the Transcoding Decision ($capDecision. If device is not mobile, then NO resizing; if the device resolution cannot be fetched from DeviceAtlas then default device resolution is used.

 

Image Adaptation Flow

The basic flow of the Image Adaptation algorithm follows:

1: Is requesting device a mobile device?

then the requesting device is a mobile.

2a: If it is not a mobile device then resizing is not performed.

2b: If it is a mobile device then we obtain the values of displayWidth and the displayHeight from DeviceAtlas and pass these parameters to the rendering function. If we can't get these values from DeviceAtlas, then we use the default values set in the config.php file instead. These are initially set to 120px both for height and width.

Usage

Image Rendering API is FREE to use. You can use the API anywhere you want. However, the API requires the DeviceAtlas API to function. To get updates to the DeviceAtlas JSON data file you will need a license. A free developer license can be downloaded from http://deviceatlas.com.

Improvements

This is the first version of the Image Rendering API. Should you have any requests or if you would like to report a bug, or have a question, you can contact the author at svo97_12@yahoo.com

Downloads

Click here to download.

Exclusive tips, how-tos, news and comment

Receive monthly updates on the world of mobile dev.

Other Products

Market leading device intelligence for the web, app and MNO ecosystems
DeviceAtlas - Device Intelligence

Real-time identification of fraudulent and misrepresented traffic
DeviceAssure - Device Verification

A free tool for developers, designers and marketers to test website performance
mobiReady - Evaluate your websites’ mobile readiness

© 2024 DeviceAtlas Limited. All rights reserved.

This is a website of DeviceAtlas Limited, a private company limited by shares, incorporated and registered in the Republic of Ireland with registered number 398040 and registered office at 6th Floor, 2 Grand Canal Square, Dublin 2, Ireland