A conformal map plotting tool.
  • Mapping
    • Lines
    • Functions
    • Data
  • Normal plotting
    • Functions
    • Data
[gif image]
Release version 1.1.1

1. Introduction

Zmapper is a plotting program written in Tcl/Tk script. The purpose of Zmapper is to see 2-D conformal mapping plots, but it can also be used for standard plotting.

The usefulness of being able to plot conformal maps became clear to me after I read Tristan Needham's book "Visual Complex Analysis." I became specially interested in the Moebius Transform, and so the first built-in map in the Zmapper program is inversion in a unit circle. You can write your own maps in a custom map file and load them into Zmapper's workspace and automatically select them from the mapping menu. To a large extent you can do anything that Zmapper offers with other plotting programs, such as Gnuplot. Zmapper has a few special tools that make visualizing comformal maps easier. You can select the OrthoLines tool which instantly draws a grid of perpendicular, straight lines when you drag the mouse and simultaneously draws their mappings. Or you can draw freehand curves with the mouse and have the conformal map of the points immediately drawn.

In the example below a straight line is drawn across the canvas, and its inversion in a unit circle is automatically drawn in red.

[gif image]

2. Conformal Mapping

Conformal mapping is a subject from the field of complex variables. A function is written that maps one complex variable into another, and when you input a line or curve into this map function you get another kind of curve. Consult your textbook on complex analysis. I recommend you read Tristan Needham's book, Visual Complex Analysis.

2. Getting Started

Start zmapper with the following unix command:

wish zmapper.tcl

The default mapping mode in Zmapper is inversion in a unit circle. While in this mode a grey circle appears about the origin of the plot. Up in the top left you will see "map mode: inv in unit circle" displayed in the mode box. If not in unit circle mode, go to the menu and click Mapping / Inversion / Unit Circle. The default drawing tool is the Freehand tool. You should see "tool: free hand" displayed in the tool indicator box. If not, go to the menu and select Tools / Freehand. Press and hold the left mouse button and drag the mouse over the plot area. Your freehand points will appear in lightblue, and the mapped points will be drawn in red.

[gif image]

3. Drawing Tools

The drawing tools consist of the following options:

  1. Freehand
    Hold the mouse button down and drag the mouse across the plot. Each point will be mapped according to the current map function.
  2. Lines
    Draw a line across the plot by holding down the mouse. A straight line will be calculated and drawn between the two points where the mouse button was pressed. The line will then be mapped.
  3. OrthoLines
    Draw a line, as in the Lines mode, but a criss-cross grid of orthogonal lines will be calculated and drawn. The orthogonal gris will then be mapped and drawn, showing how the conformal mapping of parametric coordinates appears in the mapping domain.
  4. Functions
    Import one or more functions from a file. Each function will be mapped according to the current map function, or its own special map if included in the file.
  5. Data
    Read one or more data sets from a file. Each data set will be drawn and mapped according to the current map function.

5. Plotting Functions

To plot a function with zmapper your must first define the function in a file, then load it, which automatically plots the function. Functions are limited to two-dimensional parametric plots.

For example, if you want to plot a function in the file my_plot.plt (the name can have any file extension),

  • Click Tools / Functions. This puts zmapper into function mode.
  • [gif image] [gif image]
  • Click File / Open. This presents you with a file browse dialog. Any file (you can select one) you select is now assumed to be a plot file.
  • [gif image]
  • Click the Open button.
  • [gif image]
  • The function will be immediately plotted.

6. Writing a Function

A function must be defined in a file. While you can only load one file at a time, you may put multiple functions in a file. The definition for each function must be enclosed in a pair of square brackets, "[" and "]". The function within these square brackets consists of equations separated by vertical bars. The last two equations must be the definitions for "x" and for "y" as parametric functions of "t". For example,

[ t = 0 : 0.1 : 1 | x = sin($t) | y = cos($t) ]

plots the parametric functions x(t), y(t) over the range 0 to 1 in steps of 0.1. The range statement consists of the variable "t" on the left-hand side of the equals sign and the endpoints of the range, separated by ":" characters, on the right-hand side. The generic form is


The order of the equations is important. Any variable appearing in an equation must be previously defined within the current function definition. For example,

pi=3.1416 |
w = 2.0 | q=3.0 * $w |
t = 0 : 0.1 : $pi |
x = 0.5*sin($w * $t)+1.5 | y = 0.5*cos($w * $t)

shows a correct function definition. In general, you first define some working variables, then define the range of the parametric variable, "t", then define "x" and "y". you may name variables with any name (any name legal with Tcl/Tk) except for the following special names: t, x, y, wx, wy. The variable t must be used as the parameteric coordinate; the variables x and y must be used as the plotting coordinates.

Finally, note that when a variable appears on the right-hand side of the equation it must be prefixed with a dollar sign, "$". This is because this expressions are passed directly into the Tcl interpreter.

7. Writing Your Own Map

Map files are written similar to function files, with a few small differences. The last two variables--the "parametric coordinates"--must be named wx and wy, not x and y as in a plotting function. Each map formula in the file is separated by a semicolon (";") character, as opposed to square brackets ("[" "]") in a normal function definition. Map formulas are given names which will appear in the Map menu after the file is read. For example, two simple map formulas in a file would be the following:

name = linear xform |
wx = 2 * $x | wy = 3 * $y
name = quad xform |
wx = 2 * $x*$x | wy = 4 * $y

Notice that, just in the case with a normal plot function, line breaks are ignored. The actual separators are the vertical bars and semicolons.

Functions can have their own individual maps assigned to them which override the current global map. This can be performed by appending a map function after a plot function definition with a semicolon, ";" delimiting the plot function from the map function. The following function definition includes its own map function:

pi= 3.1416 | q=2*$pi | t = 0:0.01:$q |
x = 2*sin($t) | y = cos($t)
wx = $x * 1.2 | wy = $y * 3

Again, the following rules apply: function definitions must end with expressions for "x" and "y". These variable names are reserved for this purpose. Map functions must operate on the variables "x" and "y" but must end with expressions for "wx" and "wy". The variable names "wx" and "wy" are reserved for this purpose.

8. Plotting Data

You plot data by setting the Tools to "Data", then go to the File / Open menu. When the Tools mode is set to Data any file opened is considered to be a data file. The data must be given as parametric, x-y data pairs. You can put one or more 2-column sets of data in each file. Specifically, the data format must conform to the following pattern:

x1 y1 x2 y2 x3 y3 ...
x1 y1 x2 y2 x3 y3 ...
x1 y1 x2 y2 x3 y3 ...
. .
. .
. .

9. Hints on Using Zmapper

  • Zmapper is a Tcl/Tk script file. To run it you need the Tcl/Tk interpreter installed on you computer. Most Unix (or Linux) systems should already have this. If you have Windows, there is a freely available version called ActiveTcl.
  • Zmapper keeps a configuration file in the current directory that contains the settings from the last session. That way, you can open Zmapper again and continue where you left off. The config file is only saved if you exit the program using File / Exit. If you exit the program with File / Quit or by clicking the close icon your session will not be saved.
  • Plotting a function is a two-step process. First, select "Function" from the Tools menu. Second, open the function file with the File / Open menu.
  • Plotting data is a two-step process. First, select "Data" from the Tools menu. Second, open the data file with the File / Open menu.
  • The File / Open menu selection does different things depending on what mode zmapper is in. In the Function plotting tool, the Open menu opens a function file. In the Data plotting tool, the Open menu opens a data file.
  • You create your own custom map files and load them with the File / Load Maps menu selection. Only one map file can be loaded at one time. When you load another map file the first map file will be overwritten. The config file in the current directory should save the name of the last map file you were using. The next time you start zmapper in this directory the previous map file will be loaded. If you do not want a map file automatically loaded when you start zmapper, you can edit the config file and delete the line containing map_file. You can prevent Zmapper from saving the current map file name by switching it off in the Edit menu.
  • Plots are drawn one on top of another on the canvas. You can combine plots from different modes: freehand, ortholines, functions and data. Switching the drawing tool does not erase the previous plot. Nor does switching the map mode erase anything. But if you clear the canvas with the Edit / clear all menu selection all plots will be erased.

Download Zmapper

Lastest version is 1.1.1


Installation is just a matter of unpacking the archive and copying the script into a directory that is included in the PATH.

  • Copy the zmapper archive into /usr/local/src

  • Unpack the archive (as root user):

    tar zxvf zmapper-x.x.x.tgz
    The unpack operation will create a subdirectory with the name corresponding to the archive name and put the files there.

  • Copy the file zmapper.tcl into /usr/local/bin. This will require you to type

    wish zmapper.tcl
    every time you run the program.

  • or

  • Copy zmapper.tcl into /usr/local/bin renamed as zmapper, then change the file permissions to execute with

    chmod +x /usr/local/bin/zmapper
    Using this method you may run the program each time simply by typing
    at the command line

  • Windows users just create a desktop link to zmapper.tcl and associate the tcl file extension with ActiveTcl.