MathCS.org Java MathCS.org - Java

zMap: For Web Creators/Programmers

Here you find some technical info, such as how to embed ZMap in your own web pages and how to download the source code for the program. It is of interest only to programmers and web page creators. You will need some knowledge of HTML if you want to use ZMap in your own web pages, and of the Java programming language if you want to understand the source code. If you are a mathematician only interested in complex functions, you will likely not find anything of interest here. If you do plan to download and/or modify the program, please check the copyright information first.

Embedding ZMap in your Web Page

ZMap, like most Java applet, can be embedded in your own web page(s). All you need to do is to include a proper APPLET tag in the HTML code of your web page where you would like the ZMap button or applet to appear. You can use the simple version, accepting default parameters for ZMap, an embedded version where the ZMap program with domain and range appears directly in your web page, not in its own window, or an advanced version where you can pre-define most aspects of ZMap. In either case you do not need to be a programmer or understand the source code.

Please note that only computers with an up-to-date, Java-enabled web browser (such as Firefox or IE) and the Java runtime environment version 1.5 (available at www.javasoft.com) or better can run ZMap.

The simple version of the APPLET tag is as follows (everything must be exactly as shown):

<applet code="ZMapApplet.class"
        codebase="http://pirate.shu.edu/~wachsmut/Java/ZMap/code"
        archive="zmap.jar,../../Lib/bgw-2.0.1.jar,../../Lib/jep-2.4.1.jar,../../Lib/lf_kunststoff.jar,../../Lib/lf-metouia.jar"
        width="200" height="35">
</applet>

If you add that code to your own web page, a visitor of your page (who has the Java runtime environment installed) will see a Start ZMap button in your page and ZMap will appear in its own window when the start button is clicked.

The embedded version of the APPLET tag is just as before, but you use the ZMapEmbedded.class class instead of the ZMapApplet.class class and different figures for width and height as follows (everything must be exactly as shown):

<applet code="ZMapEmbedded.class"
        codebase="http://pirate.shu.edu/~wachsmut/Java/ZMap/code"
        archive="zmap.jar,../../Lib/bgw-2.0.1.jar,../../Lib/jep-2.4.1.jar,../../Lib/lf_kunststoff.jar,../../Lib/lf-metouia.jar"
        width="750" height="400">
</applet>

If you add that code to your own web page, a visitor of your page (who has the Java runtime environment installed) will see the domain and range of ZMap right in the web page without any start button. The applet will function just as before (see below). Please note that you need to set the width of the applet wide enough to show all features of the toolbar, but a user could "float" the toolbar if they wish.

The more advanced version of the APPLET tag lets you specify a number of parameters for ZMap, so that you can create a custom made version in your web page. The discussion below applies also to the embedded version, where ZMapApplet.class is replaced by ZMapEmbedded.class and width and height are adjusted accordingly.

Options for applets are specified via PARAM tags, using NAME and VALUE pairs for each parameter. You can specify none, some, or all parameters. Each parameter you do not specify gets a default value. Currently ZMap supports the following parameters:

Parameter NAME Parameter VALUE
function Defines the function to use
nPoints How many points to use for drawing curves. Higher values give smoother curves but take longer to draw.
domainXMin, domainXMax,
domainYMin, domainYMax
Smallest and largest values for the real (x) and imaginary (y) parts of the domain.
rangeXMin, rangeXMax,
rangeYMin, rangeYMax
Smallest and largest values for the real (x) and imaginary (y) parts of the range.
hLinesMin, hLinesMax, hLinesNum Smallest and largest values for horizontal lines and how many horizontal lines to draw.
vLinesMin, vLinesMax, vLinesNum Smallest and largest values for vertical lines and how many vertical lines to draw.
radiusMin, radiusMax, radiusNum Smallest and largest values for the radii and how many radii to draw.
angleMin, angleMax, arcNum Smallest and largest values for circular angles and how many arcs to draw.
centerX, centerY The real (x) and imaginary (y) part of the center of the circles to draw.
vLinesShow, hLinesShow,
radiusShow, arcShow
Whether to show vertical lines, horizontal lines, radii, and arcs. Each value can be "true" or "false".

An example of this advanced version of the APPLET tag is as follows:

<applet code="ZMapApplet.class"
        codebase="http://pirate.shu.edu/~wachsmut/Java/ZMap/code"
        archive="zmap.jar,../../Lib/bgw-2.0.1.jar,../../Lib/jep-2.4.1.jar,../../Lib/lf_kunststoff.jar,../../Lib/lf-metouia.jar"
        width="200" height="35">
   <param name="function" value="z^3">
   <param name="nPoints" value="600">
   <param name="domainXMin" value="-1.3">
   <param name="domainXMax" value="1.3">
   <param name="domainYMin" value="-1.3">
   <param name="domainYMax" value="1.3">
   <param name="rangeXMin" value="-2.2">
   <param name="rangeXMax" value="2.2">
   <param name="rangeYMin" value="-2.2">
   <param name="rangeYMax" value="2.2">
   <param name="hLinesMin" value="-1.0">
   <param name="hLinesMax" value="1.0">
   <param name="hLinesNum" value="18">
   <param name="vLinesMin" value="-1.0">
   <param name="vLinesMax" value="1.0">
   <param name="vLinesNum" value="18">
   <param name="radiusMin" value="0.01">
   <param name="radiusMax" value="1.0">
   <param name="radiusNum" value="18">
   <param name="angleMin" value="0.0">
   <param name="angleMax" value="1.048">
   <param name="arcNum" value="18">
   <param name="centerX" value="0.0">
   <param name="centerY" value="-0.0">
   <param name="vLinesShow" value="true">
   <param name="hLinesShow" value="true">
   <param name="radiusShow" value="false">
   <param name="arcShow" value="false">
</applet>

You could use virtually same advanced tag for the embedded version, replacing ZMapApplet.class by ZMapEmbedded.class and increasing width and height.

Downloading the Program

You only need to download the source code if you

Before you download the code, create a new directory (perhaps call it 'zmap'). All downloaded files should be saved into that directory. Download the following files into that directory, using right-click and Save As ...
bgw-2.0.1.jar
Bert G. Wachsmuth's library of generally useful Java classes (class files only)
bgw-2.0.1-source.jar
Complete source code for bgw-2.0.1 (sorry, not much in terms of documentation)

jep-2.4.1.jar
Singular Systems Java Expression Parser (class files only)
jep-2.4.1-ext-1.1.1-gpl.zip
Complete source code, documentation, and copyright information for JEP 2.4.1

zmap-complete.jar
Source code, class files, help files, and icons specifically for ZMap

lf_kunststoff.jar
optional - Kunststoff look-and-feel (no longer supported)
lf-metouia.jar
optional - Metouia look-and-feel (no longer supported)

All code is open source, licensed according to the GPL 2.0 or LGPL 2.0 license - please see the copyright info for details.

To execute ZMap as a stand-alone program:

After downloading the above files into the same directory, uncompress the ZMap archive into the current directory. You can use, for example, the command:

[PATH_TO_JDK]jar -xf zmap-complete.jar

Now you can run the program from the command line as follows:

[PATH_TO_JDK]java -cp ".;bgw-2.0.1.jar;jep-2.4.1.jar" ZMap

Do not forget the single dot . in the above classpath. If you want the optional look-and-feel modules, add the corresponding JAR files to the classpath.

To modify the source code, you can edit the appropriate *.java files in the current directory. You should also uncompress the BGW source code archive and look through it, since it contains many classes generally useful for writing programs involving mathematics. Finally, look at the complete JEP documentation to learn more about that excellent parser. To (re)compile the program from the command line, use:

[PATH_TO_JDK]javac -cp ".;bgw-2.0.1.jar;jep-2.4.1.jar" *.java