Image Plane Developer Documentation

Input

Image Plane is a flexible tool that can meet the needs of many web applications. Setting up Image Plane to work with your system can be part of either a simple or sophisticated web solution. Because there are so many inputs for Image Plane, the majority of the application control parameters are in an external XML file.

This file can be generated by a script if appropriate or it can be a permanent file living on the server. The format for this XML file and the parameters it should include are explained further down in this section. In addition to the controls in the parameters.xml file there are several input variables that must be passed into the application.

Input Variables

Some parameters will generally change for every client user. These parameters are passed in as "get" variables when you embed the flash file onto a web page. Below is a table of controls that are currently implemented. You can see an example of how to pass these variables into Image Plane on the implementation page.

Name* Implied Type** Value Required***
InputXML String The path to a file on the server that contains a well formed XML document providing control parameters for Image Plane to operate under.
(See below)
Yes
InputFileName String The path to an image file on the server for Image Plane to edit.
All Image Plane instances will use the same input image but each can have unique outputs.
Yes
OriginalName String The image filename displayed by Image Plane.
This variable is not used to load any data, however the value will be displayed to the user as the name of the current image being edited. This allows the application to load a file with a non-human-readable file name such as a timestamp or other unique ID but still display a user friendly file name.
No
OutputFileName String The output name for this use of Image Plane.
This value will simply be forwarded on to the server-side output script. The same output name will be used for the output of each instance in this use of Image Plane.
Yes
UseXMLInputLocation Boolean If set to true, specifies that the variable "inputFileName" is a full path to the image to be edited.
If set to false Image Plane will first acquire the "inputFileLocation" variable from the parameters.xml file, append it to the beginning of "inputFileName" and then load the image..
No
UseConsoleLog Boolean Output verbose text to the browser console.
If you have the Firebug add on for Firefox the console is a useful way to see client side data output. Setting this variable to true will cause the verbose text to be output to the console instead of the Image Plane interface. It is important to disable this feature for other users as a call to "console.log" on a browser that does not have Firebug installed will cause an error.
No
Verbose Boolean Display verbose text on/off.
Setting the verbose variable to true will add a text display on top of the application giving feedback regarding any errors as well as loading and saving progress.
No
ImageFileSize Integer The size in bytes of the input image file.
By passing in the size of the image file into Image Planet the initial percentage loading indicator will be more reliable during start up.
No
StyleFileSize Integer The size in bytes of the input CSS file.
By passing in the size of the CSS style file (specefied in the XML parameters file) into Image Planet the initial percentage loading indicator will be more reliable during start up.
No
XMLFileSize Integer The size in bytes of the input XML parameter file.
By passing in the size of the parameter XML file into Image Planet the initial percentage loading indicator will be more reliable during start up.
No
  • * Variable names are case insensitive.
  • ** The impied type is the variable type to which the variable will be caste. All variables should be passed in as strings.
  • *** All variables have default values, however ommiting required variables will most likely prevent Image Plane from working properly.

Input Parameters

The input XML file that Image Plane reads in defines parameters for it's behavior, appearance and output. The XML document should begin with a doctype including a version and encoding method followed by a root level node named "imagePlane". This node should have at least two children, the first named "globals" and at least one node named "IPinstance". The "globals" node defines the general behavior and appearance of Image Plane. Any nodes other than "IPinstance" nodes and the first "globals" node will be ignored by Image Plane. Further down the page you can see an example of a valid XML parameter file that sets up Image Plane to ouput three image sizes.

IPinstance Node

The "IPinstance" node defines size constraints for the image crop as well as the file type, location and quality of the output image. For each IPinstance node in the XML file, Image Plane will add an image editing tab to the main window with the defined behaviors. The value set in the "instanceName" node will be displayed as the title of it's image editing tab. IPinstance breaks down into three required child nodes: "instanceName", "sizeConstraints", and "output". It is important to note that each IPinstance node has an implied index. The first IPinstance node in the file will be index 0, the next index 1 and so on. Below is a table of valid node names and values that go into an IPinstance node.

Name Parent Node* Implied Type Value Required
Single text value instanceName String The name to represent this image editing instance.
This value will be seen by the user as the title of the tab representing this instance.
Yes
minWidth** sizeConstraints Integer The minimum output width of this image instance measured in pixels.
You should always specify a minimum size even if it is just 1 pixel.
Yes
maxWidth** sizeConstraints Integer The maximum output width of this image instance measured in pixels.
You should always specify a maximum size, typically no larger than 1000 pixels.
Yes
minHeight** sizeConstraints Integer The minimum output height of this image instance measured in pixels.
You should always specify a minimum size even if it is just 1 pixel.
Yes
maxHeight** sizeConstraints Integer The maximum output height of this image instance measured in pixels.
You should always specify a maximum size, typically no larger than 1000 pixels.
Yes
aspectRatio sizeConstraints Float The ratio of the WIDTH of the output image to its HEIGHT.
For example, a value of 0.5 will restrict the user to creating an image that is twice as tall as it is wide.
No
imageType output*** String The file type the final output image should be saved to.
Valid examples would include jpg, gif, png, bmp. This value is not used directly by the Image Plane application, it is only forwarded to the final output script. See the example output script to see how this might be handled.
Yes
outputScript output*** String The server-side script to handle the output of Image Plane
This variable should be a full path to the (PHP, Python, ASP, etc.) script and cannot have any variables appended to the name. This variable acts as a per instance override of the outputScript variable from the globals node (see below) If no value is set in the IPinstance node the ouput script specified in the globals node will be used.
No
outputDirectory output*** String The final server-side location for the output of each image plane instance.
Typically you will want to separate all the image plane instance outputs into separate directories since they will (by default) all be exported with the same name. Make sure that the directory specified has appropriate right permissions enabled.
Yes
quality output*** Integer The quality or compression of the output image.
This compression is mostly intended for use with JPEG images. This node should have an integer number between 1 and 100 where 100 is the best quality (least compression).
No
transparency output*** Boolean Transparency of the output image.
The "transparency" node indicates whether or not the output image should keep transparency. Only certain image formats such as PNG images can store an alpha (transparency) channel.
No
updateOriginal output*** Boolean Indicates whether the final image transform should be handled by Image Plane or the output script.
This node is a place holder for planned future development. The only option currently is to have Image Plane output the pre-transformed image.
No
otherData output*** String Additional data to be sent to the output script.
The "otherData" node can hold any additional information that you would like to have forwarded to the output script called by Image Plane. The data should be organized into any number of child XML nodes.
<key>value</key>
See the example output script, or the example parameters.xml below for more information.
No
  • * See the example XML below for a valid child/parent hierarchy.
  • ** These size constraints will be represented to the user as limits for a resizable crop box on the image editing tab. Take a look at a screenshot.
  • *** All children of the "output" node are not used directly by Image Plane, instead they are forwarded to whatever script is specified by the "outputScript" node. Take a look at the example below.

IPinstance (Image Plane instance) parameters specified in an XML document.

Globals Nodes

The "globals" node of the input XML contains parameters that affect general behaviors of Image Plane. The globals node also breaks down into three child nodes: "adminThumbIndex", "fixedValues", "defaultValues". The adminThumbIndex node contains only a single integer value. This integer value represents an index of an "IPinstance" node (see above) to output via javascript once Image Plane closes. The value that will be output will be the location and name of the output image of the instance index specified. To see more about how to handle this output see the implementation page.

Both the "fixedValues" node and the "defaultValues" node can have the same children nodes. Which node you place a parameter under indicates whether the user will be able to change the value on the fly using the controls in the Image Plane interface. Below is a list of variables that can be used in either the defaultVariables or fixedVariables node (although should never be placed into both).

Node Name Implied Type Value Required
outputScript* String The server-side script to handle the output of Image Plane
This variable should be a full path to the (PHP, Python, ASP, etc.) server script.
Yes
inputFileLocation* String The server-side directory from which the editing image will be loaded.
This variable is only used if the input variable "UseXMLInputLocation" is set to true; in which case this variable will be prepended to the "inputFileName" variable.
Yes
imageEncoding* String Encoding to use on the image file to be sent to the output script.
The image enoding value can be either "jpg" or "png". The image encoding is NOT the format used by the server script to output the final image file. It is only the enoding method used by Image Plane to transmit the image file to the server. Using a jpeg endoing will reduce file size for a faster upload; however, it will have a lower quality and will not preserve transparency.
No
closeScript* String The name of a javascript function to be called by Image Plane when the user opts to quit.
The javascript function that is specefied by this value should close the Image Plane application in whatever way is approriate. For example, if you are running Image Plane in a pop-up browser window the function call the "window.close()" method to close the window. If this value is not included in the parameter's file or if it set to the literal string "NULL" then the application controls to close Image Plane will be disabled for the user.
The callback will also pass a single parameter indicating the file name of the output image specified by adminThumbIndex in the "globals" node of the XML.
Yes
antialias Boolean Anti-alias mode for image transformations. Image Plane can either generate a higher quality, anti-aliased final output image to upload or it can create a quick and dirty transform that will be more pixelated and jaggy. Setting the antialias variable to true will produce much higher quality results and is the recommended option. No
backgroundColor Hex String The background color to be used behind the edited image. No
backgroundAlpha* Float The opacity of the background behind the transformed image This variable is not currently implemented, but is intended to be a part of future development. No
styleLoc* String The full file path and name of a server-side CSS document. The CSS document is used to style some text elements in the application. Future development may make this styling file more powerful. See the example below of a CSS file showing the available styling classes. No
colorSwatch* String A server-side XML document with hexidecimal colors to be used as selectable colors in the Image Plance swatch. See the example below of a color swatch XML file. No
windowPadding* Float The padding measured in pixels that should exist between the image editing tab window and its red crop box. If the crop box exceeds this limit the window will add scroll bars to compensate. No
  • * These items, although they can be specified as either fixed or default (variable) parameters, are not changable via the Image Plane interface. Future development may enable these properties to be specified by the user.

XML Parameter File Example

Download this file.
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <imagePlane>
  3.     <!--
  4.         Parameters in the globals node affect the general behavior of Image
  5.         Plane, and will affect all image instances.
  6.     -->
  7.     <globals>
  8.         <adminThumbIndex>0</adminThumbIndex>
  9.         <!--
  10.             The parameters below can be children of either the fixedValues
  11.             or defaultValues nodes. Placing them in one or the other
  12.             indicates whether or not a client user can manipulate the value
  13.             of that parameter in the application interface.
  14.         -->
  15.         <fixedValues>
  16.             <closeScript>closeImagePlaneWindow</closeScript>
  17.             <windowPadding>30</windowPadding>
  18.             <!--
  19.                     The image encoding parameter does not imply the format of
  20.                     the final output image, rather it is only the encoding
  21.                     method to be used by Image Plane for transmitting the
  22.                     image back to the server. The supported options
  23.                     are jpg or png.
  24.             -->
  25.             <imageEncoding>jpg</imageEncoding>
  26.             <styleLoc>/style/imagePlaneStyle.css</styleLoc>
  27.             <backgroundAlpha>100</backgroundAlpha>
  28.             <outputScript>/flash/imageplaneUpload.php</outputScript>
  29.             <colorSwatch>/flash/colorPallete.xml</colorSwatch>
  30.         </fixedValues>
  31.         <defaultValues>
  32.             <antialias>true</antialias>
  33.             <backgroundColor>ffffff</backgroundColor>
  34.         </defaultValues>
  35.     </globals>
  36.     <!--
  37.         Each IPinstance node appears as a new tab in the main Image Plane
  38.         editing window and represents an additional image output from
  39.         Image Plane. A user may choose to edit and save one, some, or
  40.         all of the instance outputs. Each instance tab will use the same input
  41.         image, but will have unique size constraints and output settings as
  42.         specified below.
  43.     -->
  44.     <IPinstance>
  45.         <instanceName>Thumbnail</instanceName>
  46.         <sizeConstraints>
  47.             <!--
  48.                 Size contstraints are measured in pixels, except for the
  49.                 aspectRatio parameter which is the constraint of the
  50.                 output image's width to it's height.
  51.                 
  52.                 You should always specify a min and max size,
  53.                 even if the minimum is just 1 pixel.
  54.             -->
  55.             <minWidth>100</minWidth>
  56.             <maxWidth>200</maxWidth>
  57.             <minHeight>100</minHeight>
  58.             <maxHeight>200</maxHeight>
  59.             <!--<aspectRatio>1</aspectRatio>-->
  60.         </sizeConstraints>
  61.         <output>
  62.             <!--
  63.             Specifiying the output script node here will override
  64.             the one provided in the global data area above
  65.             -->
  66.             <!--<outputScript></outputScript>-->
  67.             <imageType>jpg</imageType>
  68.             <quality>100</quality>
  69.             <transparency>false</transparency>
  70.             <outputDirectory>/images/imageThumb/</outputDirectory>
  71.             <updateOriginal>false</updateOriginal>
  72.         
  73.             <!--
  74.                 The otherData node can hold any number of child nodes
  75.                 with abitrary data in the form:
  76.                 <key>value</key>
  77.                 This data will be forwarded on to the Image Plane
  78.                 output script.        
  79.             -->
  80.             <otherData>
  81.                 <category>Product Thumbnail</category>
  82.                 <userData1>any generic data</userData1>
  83.                 <anything>any additional data you need</anything>
  84.             </otherData>
  85.         </output>
  86.     </IPinstance>
  87.     <IPinstance>
  88.         <instanceName>Full Size</instanceName>
  89.         <sizeConstraints>
  90.             <minWidth>100</minWidth>
  91.             <maxWidth>600</maxWidth>
  92.             <minHeight>100</minHeight>
  93.             <maxHeight>800</maxHeight>
  94.             <!--<aspectRatio>1</aspectRatio>-->
  95.         </sizeConstraints>
  96.         <output>
  97.             <!--<outputScript></outputScript>-->
  98.             <imageType>jpg</imageType>
  99.             <quality>100</quality>
  100.             <transparency>false</transparency>
  101.             <outputDirectory>/images/fullSize/</outputDirectory>
  102.             <updateOriginal>false</updateOriginal>
  103.             <otherData>
  104.                 <category>Product Full Size</category>
  105.                 <userData1>any generic data</userData1>
  106.                 <anything>any additional data you need</anything>
  107.             </otherData>
  108.         </output>
  109.     </IPinstance>
  110. </imagePlane>

Styles and Colors

Custom Styles

The appearance of the Image Plane interface is partially customizable. A CSS file such as the example below can be modified to change the appearance of certain text elements. Future development may allow for additional customization.

Download this file.
  1. .title
  2. {
  3.     font-family: Tahoma;
  4.     text-align: left;
  5.     font-size: 27px;
  6.     font-weight: normal;
  7.     color: #D9E5EC;    
  8. }
  9.  
  10. .tip
  11. {
  12.     font-family: Tahoma;
  13.     text-align: left;
  14.     font-size: 11px;
  15.     font-weight: normal;
  16.     color: #333333;    
  17. }
  18.  
  19. .imageSize
  20. {
  21.     font-family: Tahoma;
  22.     text-align: right;
  23.     font-size: 12px;
  24.     font-weight: normal;
  25.     color: #FFFF00;    
  26. }
Color Swatch

Image Plane uses a color swatch tool to allow the user to select a background color for their output image. The color swatch will display a small palette of colors for the user to select from which supplements the controls to specify an exact color. The colors in this palette are customizable for the developer using an XML file such as the one shown below.

Download this file.
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <colorList>
  3.     <!-- row 1 -->
  4.     <color>FFFFFF</color>
  5.     <color>808080</color>
  6.     <color>ff4d4d</color>
  7.     <color>ffa44d</color>
  8.     <color>ffff4d</color>
  9.     <color>4dff4d</color>
  10.     <color>4dfff0</color>
  11.     <color>4d97ff</color>
  12.     <color>4d4dff</color>
  13.     <color>db4dff</color>
  14.     <!--row 2-->
  15.     <color>e5e5e5</color>
  16.     <color>595959</color>
  17.     <color>cc0000</color>
  18.     <color>cc6400</color>
  19.     <color>cccc00</color>
  20.     <color>00cc00</color>
  21.     <color>00ccba</color>
  22.     <color>0055cc</color>
  23.     <color>0100cc</color>
  24.     <color>a200cc</color>
  25.     <!--row 3-->
  26.     ...
  27. </colorList>

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 Net-Perspective.com.

Copyright

This site, its contents, and its design are © Copyright 2008 - 6061 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.