Image Plane Developer Documentation


To complete it's role, Image Plane outputs the relevant data to a server-side output script. This script generally should be used to receive the output image, and save it to an appropriate location. Take a look at the example output script below to see a typical implementation.

Post Method Variables

In addition to the edited image, Image Plane will transmit several variables to the output script. Many of these outputs are forwarded from the XML parameters file's IPinstance output node. They are provided to the script to allow for flexibility with the its implementation. For example, you may wish to make additional modifications to the output image based on the output parameters received. These variables will all be passed by the POST method to the server script.

Varaible Name Implied Type Value
IPImage Image Data The literal image data in a base 64 encoded string.
To access the image data in this variable you should first do a base 64 decode and then access the literal string as image data. See the sample code below to see how this is easily handled with PHP using the gd image library.
IPindex Int A 0 indexed integer indicating which Image Plane instance output is being transmitted.
For example, a certain Image Plane XML parameter file might have 3 different instance outputs listed as (in order) Tiny, Thumbnail, and Full Size. If the image being sent is the "Tiny" output, IPindex will be 0. If the image is "Thumbnail" IPindex will be 1 and so on for any number of outputs. If a user selects the "Save All" option in Image Plane, all instance outputs will automatically and successively be sent to the output script. The application will wait for the first image to finish processing before it transmits the next.
inputXML String The name and location of the input parameters.xml file
This string will be the same as the intput variable InputXML that is passed into ImagePlane. Therefore, the path will be relative to the location of ImagePlane.
outName* String The filename the output image should be saved with.
This variable is forwarded from the Image Plane instance node in the XML parameter file.
outputDirectory* String The directory the output image should be saved to.
This path should be double checked for validitiy and security. Alternatively, you could use an output location aquired from a different source such as the parameters.xml file. This variable is forwarded from the Image Plane instance node in the XML parameter file.
imageType* String The output image type represented as a file extension
This variable is forwarded from the Image Plane instance node in the XML parameter file.
quality* Int The output quality the file should be saved with. Generally used for JPEG compression.
This variable is forwarded from the Image Plane instance node in the XML parameter file.
transparency* Boolean The output image transparency setting.
If set too true this indicates that the output image should be saved with an alpha channel. Doing so requires the image to be saved in a format that supports an alpha channel such as PNG or GIF. This variable value is forward from the Image Plane instance node in the XML parameter file.
width Int The width in pixels of the image being uploaded.
height Int The height in pixels of the image being uploaded.
encodingType String The encodingType used on the image uploaded by Image Plane
This setting can be controlled from the Image Plane global node in the XML parameter file.
inWidth Int The width in pixels of the original untransformed image.
inHeight Int The height in pixels of the original untransformed image.
inName String The name original untransformed image file.
inType String The type of the original untransformed image file represented as a file extension.
inLocation String The directory location of the original untransformed image file.
updateOriginal** Boolean Indicates if the uploaded file has been pre-transformed by Image Plane.
A value of "false" indicates that the value has not been transformed and should be transformed by the output script.
bgPixel** Color The background color selected by the user.
The variable is an indexed array with bgPixel[0] = red, bgPixel[1] = green, bgPixel[1] = blue. Each entry is an 8 bit value ranging from 0 (black) to 255 (full color).
Other* N/A Custom variables transmitted via the POST method.
In addition to the variables listed above, you may add additional variables in the parameters.xml file under the IPinstance otherData node. See the example parameters.xml file for an example of how this is done.
  • *These items indicate what the output of the upload script should be, not what the settings of uploaded file sent by Image Plane are.
  • **These variables are place holders for future development. The intention is to allow the server script to perform the image transformations rather than the client side Image Plane application. This will reduce the amount of data that must be uploaded to the server and possibly improve processing time.

You may find any number of these variables to be useful for your implementation of Image Plane. The main variable you will need to access is the IPImage variable which contains the user created image output as a base64 encoded string. To access the image in PHP the code is simply the single line shown below.

  1. $im = imagecreatefromstring( base64_decode( $_POST['IPImage'] ) );

This image data will have either a JPG or PNG encoding depending on the option specified by the encodingType variable. The gd function "imagecreatefromstring" will open the image regardless of which encoding is used. Other image libraries may not support opening image data directly from an input string. In this case, you may have to write the string out to a temporary file then reopen it. Remember that JPG and PNG each have their own benefits: JPG is compressed so it will upload faster, PNG is a lossless format and supports transparency.

Output Script

The following example demonstrates how the output of Image Plane might be handled. The primary purpose of the output script is to save the output of Image Plane to the server. Your specific needs or conventions may require you to alter this code significantly. You should at least change the script below to include appropriate security measures. The example below is only available as a PHP script at present.

Download this file.
  1. <?php
  2.     //Image Plane output data...
  4.     //the path to the input parameters.xml
  5.     //This path will be relative to the Image Plane application file.
  6.     $inputXML = $_POST['inputXML'];
  8.     //IPindex indicates the index in the list of image instances that are
  9.     //specified in the "parameters.xml" file. The instance defined closest to
  10.     //the top of the XML file will be index 0. The index will increment for
  11.     //each instance definition as you move down the file.
  12.     $IPindex = $_POST['IPindex'];
  14.     //The name to be assigned to the output file.
  15.     $outName = $_POST['outName'];
  17.      //The image type the output file should be saved as.
  18.     $outType = $_POST['imageType'];
  20.     //The quality the output image should be saved with.
  21.     $outQuality = intval($_POST['quality']);
  23.     //Should the output image support pixel transparency.
  24.     $outTransparency = $_POST['transparency'];
  26.     //The width in pixels of the output image.
  27.     $outWidth = intval($_POST['width']);
  29.     //The height in pixels of the output image.
  30.     $outHeight = intval($_POST['height']);
  32.     //The directory location where the output image should be stored.
  33.     $outLocation = $_POST['outputDirectory'];
  35.     //This parameter indicates whether the output file has
  36.     //already been transformed by Image Plane or if it needs
  37.     //to be transformed by this script. Presently the only
  38.     //option is to allow Image Plane to send the already
  39.     //transformed image. Defined in "parameters.xml".
  40.     $updateOriginal = $_POST['updateOriginal'];
  42.     //The background color specified by "parameters.xml" or else selected by
  43.     //the user for the output image. This color value is sent as in indexed
  44.     //array of the form "R,G,B,A". Where R,G,B, and A are integer values
  45.     //from 0 to 255.
  46.     $bgPixel = explode(",",$_POST['bgColor']);
  48.     //encodingType will be jpg or png depending
  49.     //on the encoding used on the uploaded image
  50.     $encodingType = $_POST['encodingType'];
  52.     //The following variables provide data regarding the
  53.     //original image file that Image Plane has edited.
  54.     //width of the original image file in pixels
  55.     $inWidth = intval($_POST['inWidth']);
  57.     //height of the original image file in pixels
  58.     $inHeight = intval($_POST['inHeight']);
  60.     //name of the original file
  61.     $inName = $_POST['inName'];
  63.     //image type of the original file
  64.     $inType = $_POST['inType'];
  66.     //server side directory location of the original image
  67.     $inLocation = $_POST['inLocation'];
  69.     //custom data can be set and passed from the
  70.     //parameters.xml file using otherData node
  71.     $userData1 = isset($_POST['userData1']) ? $_POST['userData1'] : "";
  72.     $anything = isset($_POST['anything']) ? $_POST['anything'] : "";
  74.     //the output image is a base 64 encoded JPG or PNG image file
  75.     $im = imagecreatefromstring( base64_decode( $_POST['IPImage'] ) );
  77.     if($outTransparency == "true")
  78.     {
  79.         imagesavealpha($im, true);
  80.     }
  82.     //set this variable to true once the image
  83.     //is successfully saved to the server
  84.     $imageSaved = false;
  86.     if($im !== false)
  87.     {
  88.         //write out valid image
  89.         //concatenated output name
  90.         $filename = $outLocation . $outName . "." . $outType;
  92.         switch(strtolower($outType))
  93.         {
  94.             case 'png' :
  95.                 //png file output
  96.                 $imageSaved = imagepng( $im, $filename );
  97.                 break;
  98.             case 'jpeg' :
  99.             case 'jpg' :
  100.                 //jpeg file output
  101.                 $imageSaved = imagejpeg( $im, $filename, $outQuality );
  102.                 break;
  103.             case 'gif' :
  104.                 //gif file output
  105.                 $imageSaved = imagegif( $im, $filename );
  106.                 break;
  107.             case 'bmp' :
  108.                 //bitmap output
  109.                 $imageSaved = imagewbmp( $im, $filename );
  110.                 break;
  111.             default :
  112.                 $imageSaved = false;
  113.                 break;
  114.         }
  116.         //remove image data from memory
  117.         imagedestroy($im);
  118.     }
  120.     echo $imageSaved;
  121. ?>

Site Info

Contact Us

By Phone:
979-696-SITE (7483)
By Email:
Send Email
For Support:
Please visit our Get Satisfaction forum.

About Us

The Kitchen is run by the fine folk at Net Perspective, LLC.

Find out more about The Kitchen or visit us at


This site, its contents, and its design are © Copyright 2008 - 4438 Net Perspective, LLC. All rights reserved.

Some images used here by permission are copyright of their respective owners. Thanks to Mark James for the fantastic Silk icon set.