Java Image Preview Application V1.35

How to use JIPA
How to install JIPA as an Application
Get JIPA with CADC H-decompress Package
Revision History
List of tested Environments
Web Browsers and Java Support
Related Publications
Feedback

How to use JIPA

There are several possibilities:

As an Applet (works with Netscape 4.04 or later, Internet Explorer 4, Hotjava).
For instance, JIPA is used to access preview FITS images of the HST archive.
Click here for an example.

This is how to include JIPA into your own web page:



<APPLET codebase="/Your/Installation/Directory/" 

  code="jipa.JIPA.class" 

  name="JIPA" 

  archive="JIPAStartUp.jar,JIPABody.jar" 

  width=420

  height=406 

  align="middle">

<param name=cabbase value="JIPAStartUp.cab,JIPABody.cab">

<param name=nodestroy value="true">

<param name=eqflag value="true">

<param name=flipx value="false">

<param name=flipy value="true">

<param name=mag value="1.0">

<param name=wantframe value="false">

<param name=popup value="true">

<param name=fitsurl value="http://Your.Web.Server/Your/Data/Dir/jipa.fits.gz">

<P>This page can only be viewed with a Java enabled browser.</P>

</APPLET>

Named parameters in the HTML <APPLET> tag recognized by JIPA:

Parameter	Valid Range	Meaning
nodestroy	True or False	Whether there is menu item QUIT to terminate program.
eqflag	True or False	Turns histogram equalization on/off.
flipx	True or False	Whether to flip the image horizontally (left/right)
flipy	True or False	Whether to flip the image vertically (top/bottom)
mag	Real Number	Initial magnification
popup	True or False	Image frame pops up at startup time.
wantframe	True or False	Run applet in separate frame.
fitsurl	URL	`file:` or `http:` pointer to FITS file

As an Application.
```
Usage: java jipa.JIPA [-d -e -f{x|y}* -m mag -p -w [fitsurl]]
       -d        There is no menu item QUIT to terminate program.
       -e        Apply histogram equalization.
       -f{x|y}*  Flip image about X and/or Y axis.
       -m factor Magnification factor as real number.
       -p        Image frame pops up at startup time.
       -w        Run JIPA in its own frame.
       fitsurl   URL of FITS file; optionally gzip compressed;
                 Version 1.4 supports h-compressed files.
```
Click here for more about installing JIPA.
On a UNIX terminal this translates into a command like this (assuming that file
$HOME/tmp/jipa.fits.gz does exist):

java jipa.JIPA -epw -fx -fy -m 1.0 file:$HOME/tmp/jipa.fits.gz

Hint: When running out of memory while manipulating large image frames, set java option -mx to a reasonable value. JIPA requires at least 2.5 times the size of the FITS file to work properly. Below is the same command as above, but this time with the upper limit of the java heap set to 64 MB RAM:

java -mx64m jipa.JIPA -epw -fx -fy -m 1.0 file:$HOME/tmp/jipa.fits.gz
As a Module of another Java Application through Instantiation.
Check out the publications for details about JIPA interfaces.
Starting with V1.3 it can also be instantiated as a Bean.
Click here for an example.

How to install JIPA as an Application

Install a JDK 1.1.x or JDK 1.2.x compliant Java Virtual Machine (JVM) if needed. Unfortunately, it is beyond the scope of this document to describe how to setup a JVM for a specific platform. In the ESO/ECF domain the Java environment is setup by issuing the following command on a Unix terminal (or adding it to the .tcshrc):
source /ecfsoft/java/aliases; jdk116

Download the JAR archives listed below. The Microsoft CABinet files are not required unless you plan to run your local installation through IE (Internet Explorer).

File	Size
JIPAStartUp.jar	35 KB
JIPABody.jar	150 KB
OR when used with Internet Explorer ...
JIPAStartUp.cab	32 KB
JIPABody.cab	140 KB
OR when used as a Bean ...
JIPABean.jar	186 KB
Optional Test Image (gziped FITS)
jipa.fits.gz	74 KB
Optional JavaDoc (for developers)
browse JavaDoc off-line (download and unjar JavaDoc)	408 KB
browse JavaDoc on-line

Assuming the JAR files reside in $HOME/bin/ on your local machine then the CLASSPATH needs to be set like this (again, for UNIX):
setenv CLASSPATH $HOME/bin/JIPAStartUp.jar:$HOME/bin/JIPABody.jar:$JAVA_HOME/lib/classes.zip
Test JIPA: Click here for help on running JIPA.

Get JIPA with CADC H-decompress Package

Download JIPA V 1.4 with support for H-decompressed FITS files.
The H-decompress Java package was developed at CADC and integrated in a joint effort with our site. Please keep in mind that JIPA was designed as a simple quick-look applet and therefore does not support FITS extensions.

Revision History

Version 1.36 (05/2000, M. Dolensky)

Some bugfixes and adaptations to StarView 6 and the ISO SPDT, like:

Bugfix: Disable overlays when switching from DSS image to preview image.
Reviewed some error messages.
Added support for reading also gzip compressed HST field of view overlays.

Version 1.32 (03/99, M. Dolensky)

Adaptation for StarView 6 Prototype Release.
Scrollbar for status line.

Version 1.31 (02/99, M. Dolensky)

JIPA implements Runnable and therefor runs as a separate Thread.
Added file menu item Load FITS from URL.
Simple implementation of StarView 6 to DSS link.

Revised command line interface; added getopt-stylish command line parser; new property argv emulates command line interface in Bean context.

Usage: java jipa.JIPA [-d -e -f{x|y}* -m mag -p -w [fitsurl]]
 -d        Disable file menu item QUIT.
 -e        Apply histogram equalization when displaying image.
 -f{x|y}*  Flip image about X and/or Y axis.
 -m factor Magnification factor as real number.
 -p        Image frame pops up at startup time.
 -w        Run JIPA in its own frame.
 fitsurl   URL of FITS file (optionally gzip compressed).
 
 e.g.: java jipa.JIPA -dew -fx -fy -m 1.0 file:/disk1/img/data.fgz
 
NOTE: On operating systems that do NOT support command line arguments
      invoke JIPA without parameters.

Version 1.3 (01/99, M. Dolensky)

JIPA is now a Bean. It is a transitional Bean, because it sticks to the AWT 1.0 event model, which is the only one that is currently (Feb. 99) supported by common browsers (apart from special plug-ins or class libraries).
Loads default image at startup time when no FITS file is specified.

Version 1.2 (11/98, M. Dolensky)

Panel for LUT manipulations.
Methods for flipping image in X and Y. Therefore, applet parameter fliptb was renamed to flipy.
File loader dialog (in application context only).
Support for CABinet files for faster download with IE (Internet Explorer).
Automatic detection and support for gziped FITS as well as plain FITS files.
Enhanced GUI:
- Status bar.
- Merged zoom-, contrast- and color-widget.
- Work around for Scrollbar confusion among various JVMs.
- Scrollbars only appear on demand.
- Center image on display when it's smaller than canvas.
- Sculptured borders around panels.
- Option for immediate image update (without pressing Apply button).
'javadoc' manpage for all source modules with automatized update.
Interface to Starview 6. This includes implementation of Observer of UserObject and interface class SVQualifyInterface.
Support for all standard FITS image formats, i.e. BITPIX {8, 16, 32, -32, -64}.
Minor modifications to make JIPA JDK 1.2 compliant.
Introdcution of hotkeys for some menu items.

Version 1.1 (03/98, M. Dolensky)

Download progress indicator while loading FITS file
Providing applet also in compressed JAR format for faster download.
Introduction of javadoc for documentation
Adapted makefile and related scripts for JAR- and javadoc-support

Version 1.0 (01/98, M. Dolensky)

Support for gzip compressed FITS files.
Migrating from JDK 1.0 to JDK 1.1
First operational use as part of the ESO/ECF archive web interface.

Version 0.4 (03/97, E. C. Downey)

Improved behavior when run via a browser.

Version 0.3 (02/97, E. C. Downey)

Support for WCS CD* and PLT* formats.
contrast choices
help text

Version 0.2 (02/97, E. C. Downey)

Added version to title.
Improved status reporting during loads.
Fix pixel reporting values.
Stub for hdecompression.

Version 0.1 (02/97, E. C. Downey)

Support for WCS fields.
Support for BZERO and BSCALE fields.
New parameters fliptb, wantframe and mag:
- fliptb allows flipping the image top-to-bottom
- mag sets the initial zoom factor.
- wantframe allows the applet user access to same controls as stand-alone.
Text panel to display FITS header.

Version 0.0 (01/97, E. C. Downey)

Initial Prerelease

List of tested Environments

Platform/Environment	Java Virtual Machine or Java Component
Linux, Suse 5.1
Browser	NS 4.04, AppletViewer
MacOS
Browser	NS 4
Solaris 2.5
Browser	NS 4.04, NS 4.08, NS 4.5, IE 4, HotJava 1.1, AppletViewer
Stand-alone	JDK 1.1.4, JDK 1.1.6, JDK 1.2beta4
Instantiated	Starview 6
Windows95
Browser	NS 4.04, IE 4
Stand-alone	JRE 1.1.4
Windows NT 4
Browser	NS 4

Web Browsers and Java Support

JVMs of Web Browsers often only support a subset of the standard Java classes and methods. Below is a list of features that NS 4.04 on Solaris is missing and for which a work around had to be found in each individual case:

Missing Entity	Work Around
Package java.awt.event	Use old event model AWT 1.0 (instead of AWT 1.1).
Class java.awt.ScrollPane	Re-implement scrollable canvas class (>1000 lines of code!)
Method drawImage(10 args) in class java.awt.Graphics	Using simpler method drawImage(6 args) together with more complicated clipping strategy.
Method setSize in class java.awt.Component	Use deprecated method resize.
Method setLocation in class java.awt.Component	Catch exception and skip code when JVM doesn't support it.
Method setCursor in class java.awt.Component	Catch exception and skip code when JVM doesn't support it.
Method setCaretPosition in class java.awt.TextComponent	Catch exception and skip code when JVM doesn't support it.
Method setBlockIncrement in class java.awt.Scrollbar	Use deprecated method setPageIncrement.
Methods setHgap and setVgap in java.awt.GridLayout	Using layout manager GridBagLayout instead.
Method setEnabled in java.awt.MenuItem	Use deprecated methods enable and disable.
Method insert in java.awt.MenuItem	Rebuild menu on demand using add().
Method getResource in java.lang.Class	Use method getResourceAsStream instead, which is not as powerful and therefore leads to more complicated code.
Method interrupt() in java.lang.Thread	For interrupt handling in Thread context call myThread.stop and catch java error java.lang.ThreadDeath in myThread.run. Limitation: Only one interrupt per instance of myThread can be caught.
Constructor Checkbox(String, boolean) in class java.awt.Checkbox	Use Constructor Checkbox(0 args) and call methods setLabel and setState.
Constructor TextArea(String, int, int, int) in class java.awt.TextArea	Catch exception and use constructor TextArea(String, int, int) in that case. Note: Automatic word wrapping is also unlikely to work in this case.

IE 4 didn't support the 16-bit custom ColorModel for image display. Therefore pixel values are now mapped to 8-bit LUTs using class IndexColorModel.
Another problem concernes method getContentType in class java.net.URLConnection:
Method getContentType seems to determine the MIME type by looking at the file extension! This is clearly an unacceptable simplification. The method works, however, when the data are accessed through a CGI script that sets the mime type correctly.
Work Around: JIPA tries to find a match with a format specific magic number at the beginning of the input stream.

Related Publications

Reference	Download Article	Download Poster or Slides
Dolensky, M., Micol, A., Pirenne, 1998, HST Archive Services Implemented in Java, The ESO Messenger, 93, 23	HTML PostScript (1.6 M) Word97 (595 K)	-
Dolensky, M., 1998, Java Components and Design Patterns for Astronomy, Poster at Workshop on Observing Tools at Univ. of Maryland Conf. Center	PostScript (2.8 M)	HTML PostScript (6.0 M) PPT (377 K)
Dolensky, M., Mayhew, B., Kennedy, B., 1998, Design Study about Integration of Starview 6 and JIPA using advanced Java Mechanisms, ASP Conf. Ser., in press	-	HTML PostScript (6.7 M) PPT (1.0 M)

Feedback

We'd like to hear from you!
Although ST-ECF is lacking the resources for full featured user support we are constantly trying to accommodate with user requirements and to learn about software problems.

Send comments to <catalog@eso.org>.