The Kitchen @ Net Perspective

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

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.

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.