Net Imaging. Developer's guide.

brightness Net Imaging. Developer's guide.

Net Imaging. Developer's guide.

Contents

	Location
How to place the applet on a web page.	this document
How to save the image on the server	this document
How to restrict the output image	this document
Openning images from local drives	this document
Accessing Net Imaging from JavaScript	this document
How to customize the GUI	this document
The applet parameters (comprehensive list)	this document
Compatibility notes	this document

The product's home page	web

How to place the applet on a web page.

The minimal HTML code to place the applet on a web page might look as follows:

<applet width="640" height="480" codebase="./applet/" archive="imaging.jar" code="ImagingApplet.class">
  <param name="load" value="myimage.jpg">
  <param name="submit" value="save.aspx">
</applet>

The attributes width and height can be set according to your page design.

The attribute codebase must point to the applet's directory on the server.
NOTE: sometimes developers omit the codebase and merge its value with the attribute archive. This is wrong practice. Don't remove the atribute codebase.

The applet parameters are specified by the tags <param>. All the parameters are optional but to be useful the applet needs at least the two:

load - specifies URL of a JPEG or GIF or PNG image on your server. The applet loads this image at startup.
submit - specifies URL of a server-side script that receives the resulting image. When the user presses the button "submit" the applet requests this script to upload the resulting image to the server. See the next section for details;

The comprehensive list of the parameters can be found here

How to save the image on the server

The applet request

When the user presses the button "submit", the applet uploads the image to the server requesting the script specified by the paramater "submit".
The request looks as if it's made by a regular HTML upload form like the following:

<form method="post" action="save.php" enctype="multipart/form-data" >
    <input type="file" name="image">
    <input type="text" name="image_width">
    <input type="text" name="image_height">
    <input type="submit">
</form>

The image is passed as the value the field image. Along with the image itself the applet posts the image's width and height.

Response of the saving script ( please read this carefully! )

Since the save script is requested from the applet and the script's response (output) is returned to the applet as well (not to the browser!). The applet doesn't understand HTML and has no way to display it, so you MUST NOT output HTML in your script as usual. Instead you should output special control commands which allow you to redirect the browser to another HTML page or display a popup message. The command(s) should be sent as plain text in the following form:

#COMMAND=parameter

Output example 1:

#SHOWDOCUMENT=confirm.html

Upon receiving this command the browser opens the page confirm.html page.

Output example 2:

#SHOWERROR=Can't save the image file.

Upon receiving this command the applet displays the popup message: Can't save the image file.

The following table lists all the commands that the applet can process:

Command	Applet's action
#SHOWDOCUMENT	The browser opens a new document. The parameter is the document's URL. The URL might be either absolute or relative to the saving script.
#SETDOCTAG	The parameter is the target frame for the document opened by #SHOWDOCUMENT command. If this command is not specified the document pointed by #SHOWDOCUMENT replaces the current page.
#SHOWMESSAGE	The command parameter may be any text which is displayed in a popup dialog.
#SHOWERROR	The same as #SHOWMESSAGE but the dialog is error decorated.
#SHOWSTATUS	The parameter is displayed in the browser's status line.
#JAVASCRIPT	Excecutes JavaScript on the applet's page. The command parameter is the code to be executed. Note: Set the applet's attrubute `mayscript`, otherwise this command can't be executed.

You can output any number of the commands but keep in mind that:
- each command must be placed on a separate line (i.e. separated by CRLF or LF characters)
- the commands are processed in the order they have been output but the command #SHOWDOCUMENT
which is executed after the end of the command sequence.

How to restrict the output image

You can restrict the output image size using the parameters output_fixed_size or output_maximum_size or output_aspect_ratio.
See Output restriction parameters for details.

Openning images from local drives

If the user has Java 6 Update 10 or later he/she can open images from his/her local drive directly. That eliminate the necessity to load images via the server.
You can detect automatically whether the user has Java 6 Update 10. For that:

Set the parameter:

<param name="jnlp_href" value="plugin2.jnlp">

Use javascript to detect whether the parameter plugin2_is_active is set to 'true'.
If it's set then Java 6 Update 10 (or later) is installed and the button open is available.

Example:

<applet name="imaging" .... >
    <param name="jnlp_href" value="plugin2.jnlp">    
</applet>

<script>
    var imaging = document.applets['imaging'];
    var plugin2IsActive = (imaging.getParameter("plugin2_is_active")=='true');
    if (plugin2IsActive) {
        // don't show upload form because direct open is available
    	...
    }
    else {
        // Direct open is unavailable.
        // show upload form or display instructions to install newer Java.
        ...
    }
</script>

Note: The file plugin2.jnlp is included in the package and located and located in the applet's directory. It specifies to display the button open and defines the parameter plugin2_is_active. The instructions in this file are activated only if the user has Java 6 Update 10 (or later).

Accessing Net Imaging from JavaScript

NetImaging supports several functions available in JavaScript. To call a function in JavaScript do the following:

Specify the applet attribute "name", for example:

    <applet name="imaging" archive="imaging.jar" ... >
        ... parameters ...
    </applet>

Use this name to access the applet function in your javascript:

    <script language="javascript">
        var imaging = document.applets['imaging'];
        imaging.someFunc(); // call someFunc()
    </script>

Here is the list of available functions:

`getImageWidth()`	Returns current image width in pixles.
`getImageHeight()`	Returns current image height in pixles.
`getSelection()`	Returns current current selection (crop box) as `x,y,width,height`. If no selection is displayed returns empty string.
`doAction(action)`	Allows executing Net Imaging actions (rotate, flip, etc.) in JavaScript. The list of supported actions corresponds to the list of visible_buttons. This function is usefull if you want to implement your custom GUI. In that case you can hide all the buttons, implement your own buttons in HTML, and arrange them on the page as you like.
`resizeTo(width,height)`	Allows resizing the image to the specified `width` and `height`.
`changeBrightnessContrast(brightness,contrast,effects)`	Allows changing brightness, contrast, effects. The values `brightness` and `contrast` must be in the range -50..50. The value of `effects` must be one of the following strings: `none, gray, sepia`.
`submit(saveURL, jpeg_quality)`	Triggers the upload process (i.e. it acts similar to the "Save" button). Note: You can hide the applet's button "submit" (located on the top panel) using the parameter visible_buttons.
`addPostField(name, value)`	Appends a user defined field in the upload (save) request. This function should be invoked before the function `submit(url)`.

The applet parameters

Name	Value
General parameters
load	URL of the image to load at startup. The URL can be either absolute or relative to the carrent HTML page.
submit	URL of the saving script. The URL can be either absolute or relative to the carrent HTML page.
thumbnail	Specifies size of preview image which is saved along with the main image. The value is the bounding of the preview image, for example: <param name="thumbnail" value="100,100"> If this parameter is not specified the preview image is not created.
jpeg_quality	Quality of the output JPEG file. The value should be an integer in the range 1..100. If the parameter is not specified the applet asks the user to set JPEG quality.
scale_method	Specifies method of scaling. Possible values: "averaging" which gives more smooth result, and "replicate" which is faster. The default is "replicate".
Output restriction parameters
output_fixed_size	Specifies that the output image must have the specified dimension (in pixels), for example: <param name="output_fixed_size" value="400,300">
output_maximum_size	Specifies that the output image must not exceed the specified dimension (in pixels), for example: <param name="output_maximum_size" value="500,500"> If "output_fixed_size" is specified this parameter is ignored.
output_aspect_ratio	Specifies that the output image must have the specified aspect ratio, for example: <param name="output_aspect_ratio" value="4,3"> If "output_fixed_size" is specified this parameter is ignored.
watermark	Specifies an image that should be superimposed (tiled) on the main image when it's saved. The value is URL either absolute or relative to the current page.
GUI customization parameters
bgcolor	The background color of the applet's GUI specified as #RRGGBB.
visible_buttons	List of buttons to display on the control panel. The following buttons are available: open submit print resize crop rotate_ccw rotate_cw fliph flipv vars undo redo zoomwin zoom100 zoom The button names should be separated by spaces. To display separators between the buttons use the character \| (ASCII code 73).
resources	URL of the resources file. URL can be either absolute or relative to the applet's location.

How to customize the GUI

How to hide unnecessary buttons

The parameter visible_buttons allows you to specify what buttons should be displayed on the control panel.

For example:

submit crop rotate_ccw rotate_cw undo redo

How to translate message and labels

The example of file which contains the labels and messages used in the applet are kept in the file resources.txt in the applet's directory. Translate this file if necessary, give it any desirable name, and specify it with the parameter resources. For example:

<param name="resources" value="spanish.txt">

The file should be saved in Latin-1 encoding. If the language you're translating to requires encoding other then Latin-1 use Unicode characters written in the format \uXXXX.

How to replace icons

To replace the button icons rename the file imaging.jar to imaging.zip and unpack it with any ZIP utility. The icon files are kept in the directory images. After replacing the images pack the files again keeping the original directory structure and rename the archive to imaging.jar.

Compatibility notes

Net Imaging is an applet compatible with JDK 1.4. It was succesfully tested on the following platforms and browsers:

Windows Vista, Java 1.6, Internet Explorer 7, Firefox 3, Google Chrome 3, Safari 4
Windows XP, Java 1.5, Internet Explorer 6, Forefox 2
Windows 2000, Java 1.4, Internet Explorer 5.5, Firefox 2
Mac OS 10.5, Java 1.5, Safari 3, Firefox 2

Regardless of the successful tests the Author is not responsible for correct applet operation on any particular hardware, software platform, and their configurations.