JeoEditPolygon Operating Manual

JeoEditPolygon

Operating Manual

by Mark Grundland for Godfried Toussaint Computational Geometry Lab
School of Computer Science at McGill University Version 1.2.1 November 1998

What is it?

What does it need?

How does it work?

How do you use it?
Undo+Redo
New+Select+Add+Remove
Verify+Process+Workspaces

How can you download it?

What can go wrong?

Who is responsible?

"The Great Bear is looking so geometrical

One would think that something or other could be proved."

- Christopher Fry

What is it?

The JeoEditPolygon applet, a part of the JeoEdit package, is a visual tool for creating polygons of any shape that you can imagine. As you may know, polygons are graceful creatures composed of line segments strung in a loop. Their subtle and devious properties are the subject of many theorems and algorithms in computational geometry. The purpose of JeoEditPolygon is to provide anyone on the world wide web with the powerful and flexible editing tools needed to compose a polygon with ease. The polygon can then be used as an example or a counterexample for a geometric hypothesis or as an input for a geometric algorithm.

JeoEditPolygon is basically a state-of-the-art, what-you-make-is-what-you-see-is-what-you-get, point-and-click-and-drag-and-drop, all-purpose polygon gadget. Enjoy!

The best way to learn the JeoEditPolygon applet is to play with it. If you are interested in creating your own applet, which will communicate with JeoEditPolygon in order to use its polygon as input for a geometric algorithm, take a look at the JeoEdit Developer's Guidebook. JeoEditPolygon is a close cousin of the JeoEditPoints applet, which has its own operating manual that reads very, very much like this one. Finally, if you're at the School of Computer Science at McGill University, you may be interested in my hints on how to get Java to work on campus.

By the way, JeoEditPolygon is free for non-commercial, educational use. Use it at your own risk and our pleasure - we make no expressed or implied warranties with regard to this software, its performance or its points so we won't be liable for any consequential, incidental, or indirect damages arising out of its use or misuse. JeoEditPolygon is not public domain. Without our written permission, you may not commercially use, distribute, modify, adapt, translate, or resell this software or any part of it. When you distribute on a non-commercial basis the JeoEditPolygon software or any part of it, you must give due credit to its creators, Godfried Toussaint and Mark Grundland, and please include this manual and preserve its internet links.

What does it need?

JeoEditPolygon works on any platform that has a web browser which fully supports Java version 1.1 or newer. In fact, Java version 1.1.6 or newer is strongly recommended. For JeoEditPoints to communicate with other applets, the web browser must correctly implement the Java AppletContext.getApplets() mechanism.

JeoEditPolygon has been successfully tested with Microsoft Internet Explorer 4.0 on Windows NT 4.0, Netscape Communicator 4.06 on Linux, HotJava 1.1.4 on Solaris UNIX, as well as Microsoft Internet Explorer 4.01 using Apple's MRJ 2.1 Java virtual machine on Mac OS (Power PC required).

How does it work?

When the JeoEditPolygon applet starts up, you will see this window:

JeoEditPolygon Window

The white space, taking up most of the window, is the drawing canvas on which you can create and modify a single polygon. The vertices of the polygon are marked with little squares. A selected vertex is marked in blue while a deselected vertex is marked in black. You can select one or more vertices and then move only those selected vertices while keeping the remaining vertices fixed. It is possible as well to add or remove vertices from the polygon. Also you can create a new polygon by drawing each edge in turn. Finally you can verify the polygon to see if it is simple, with no consecutive collinear vertices; any vertex causing a problem will be marked in red. Once the polygon is ready, you can send it to other applets as input for further processing. If you need more space to work in, just resize the JeoEditPolygon window and the polygon will be scaled accordingly.

Above the drawing canvas, there is the status panel showing the editing tool currently in use as well as any errors or warnings.

Next, there is the workspace panel consisting of a row of buttons numbered one to five, corresponding to five separate workspaces, each with its own polygon. Use the workspaces to temporarily store multiple polygons. The currently selected workspace has its button highlighted and the drawing canvas displays its polygon. You can easily switch between workspaces as well as transfer a polygon from one workspace to another.

At the top of the window, there is the task bar. From left to right, the task bar buttons designate Undo and Redo commands, followed by New, Select, Add, and Remove tools and finally the Verify and Process tasks. The current tool has its button highlighted.

How do you use it?

The buttons and tools all work in a natural, intuitive way - hopefully. Note that "left click" or "left drag" refers to the left mouse button, while "right click" or "right drag" refers to the right or central mouse button (for a mouse with a single button, press down the shift key to simulate the right mouse button). Also note that "toggle" refers to inverting the current selection, whereby a selected vertex becomes deselected while a deselected vertex becomes selected.

Undo Command

To cancel the last editing action performed in the current workspace:

Click on the Undo button.

Redo Command

To reverse the effect of the previous undo command:

Click on the Redo button.

New Tool

One by one, draw each consecutive edge of the polygon.

To start a new polygon:

Click on the empty canvas to create the start vertex or drag to draw the first edge.
To specify the next edge of the polygon:

Click or drag the pointer to position the edge's end point.
To erase some edges of the polygon:

Click on the vertex which is the final end point of the last edge you wish to keep. Only the edges between the start vertex and this last vertex will be preserved.
To close the new polygon:

Select another tool or click on the start vertex, thereby drawing the edge between the last vertex and the start vertex.

Select Tool

Use the left mouse button to select vertices and the right mouse button to toggle vertices.

To select a vertex:

Left click on the vertex.
To select the two endpoints of an edge:

Left click on the edge.
To select multiple vertices:

Starting on an empty spot on the canvas, left drag to enclose the desired vertices in the selection rectangle.
To deselect all the vertices:

Left click on an empty spot on the canvas.

To move the selected vertices:

Starting on a selected vertex, left drag to position all the selected vertices while keeping the remaining vertices fixed. Whenever you select a vertex or an edge, you may also drag to move the selection you made.

To toggle a vertex:

Right click on the vertex.
To toggle the two endpoints of an edge:

Right click on the edge.
To toggle multiple vertices:

Starting on an empty spot on the canvas, right drag to enclose the desired vertices in the selection rectangle.

Add Tool:

Use the left mouse button to add vertices and the right mouse button to select vertices.

To insert a new vertex:

Left click on the edge where the new vertex should be placed, thereby dividing the edge in two. Then you can continue to left drag in order to position the new vertex.
To select a vertex:

Click on the vertex.
To select the two endpoints of an edge:

Right click on the edge.
To select multiple vertices:

Starting on an empty spot on the canvas, right drag to enclose the desired vertices in the selection rectangle.
To deselect all the vertices:

Click on an empty spot on the canvas.
To move the selected vertices:

Starting on a selected vertex, drag to position all the selected vertices while keeping the remaining vertices fixed.

Remove Tool:

Use the left mouse button to remove vertices and the right mouse button to select vertices.

To remove a vertex:

Left click on the vertex.
To remove multiple vertices:

Starting on an unoccupied spot on the canvas, left drag to enclose the vertices you want to remove in the selection rectangle.
To select a vertex:

Right click on the vertex.
To select the two endpoints of an edge:

Right click on the edge.
To select multiple vertices:

Starting on an empty spot on the canvas, right drag to enclose the desired vertices in the selection rectangle.
To deselect all the vertices:

Click on an empty spot on the canvas.
To move the selected vertices:

Starting on a selected vertex, right drag to position all the selected vertices while keeping the remaining vertices fixed.

Verify Task

This task will check if the polygon is simple and has no consecutive collinear vertices.

To verify the polygon:

Left click the Verify button.
To turn on or off the automatic verification of the polygon whenever its shape is modified:

Right click the Verify button.

Process Task

This task will send the polygon for further processing by the other applets on the web page. If there are no such applets available, the task will simply output the coordinates of the polygon vertices to standard output (which is typically the web browser's Java log). These coordinates are real numbers between 0 and 1, with the top left corner of the canvas as the origin of the coordinate system. The vertices will be given in counterclockwise order providing that the polygon is simple. If automatic verification is turned on and a problem with the polygon is found, the polygon won't be processed until the problem is resolved.

To process the polygon:

Left click the Process button.
To turn on or off the automatic processing of the polygon whenever its shape is modified:

Right click the Process button.

Workspaces

To switch to another workspace:

Left click the button of the desired workspace. The polygon of the previous workspace will be preserved, while the polygon of the workspace will be displayed, ready for editing.

To transfer the polygon of the current workspace to another workspace:

Right click the button of the destination workspace. You will then be able to edit the current polygon in this new workspace, while a copy of it will be preserved in the previous workspace.

How can you download it?

You can download JeoEditPolygon to your computer and run it directly using a web browser or an appletviewer such as the one which comes with Sun's JDK (be sure to use JDK 1.1.6 or newer). Just fetch the archive JeoEditPolygonArchive.zip (for Windows) or JeoEditPolygonArchive.tar (for UNIX) from this web page. The archive is approximately 300K.

What can go wrong?

It is possible that JeoEditPolygon may not function properly at some unfortunate times, just like most other Java software on the internet. The problem is usually with the Java virtual machine used by the web browser - try a different web browser or Java virtual machine. Here are some known problems and heir solutions:

When you are loading the JeoEditPolygon applet, please be patient with it and avoid interrupting the loading process by clicking on the browser's stop or reload buttons or by going to a different web page. Otherwise the browser's Java class loader may become corrupted and you will have to restart the browser (this problem is especially acute with Microsoft Internet Explorer under Windows).
When the HotJava browser or appletviewer is run locally or remotely on Linux, it may display JeoEditPolygon with wildly incorrect colors. Try to adjust the display environment of your local machine to 256 colors (8 bpp). To see how this can be done on the machines in the School of Computer Science at McGill University lab, take a look at my SOCS Java Hints.
It may be difficult to get JeoEditPolygon to run on a Macintosh, due to the current lack of reliable browsers with Java virtual machines which fully support Java 1.1. Try using Microsoft Internet Explorer 4.01 with Apple's MRJ 2.1 Java virtual machine.

Who is responsible?

If you have any difficulty with JeoEditPolygon, feel free to contact me, Mark Grundland, by sending email to MGrund@PO-Box.McGill.Ca. Have you found a bug? Describe the bug's precise nature, including its habitat and habits, and I will take pleasure in exterminating the critter on the spot. Comments, suggestions, job offers, sudden flashes of cosmic insight as well as sunshine are also welcome. For administrative matters you may contact Godfried Toussaint at Godfried@CS.McGill.Ca.

Please be patient with me since it can take me a while to respond. For the more urgent predicaments, the students or faculty of the School of Computer Science at McGill University may contact me at 514-637-4273.

May all your theorems be true...

- Mark Grundland

	JeoEditPolygon Operating Manual
	`by Mark Grundland for Godfried Toussaint Computational Geometry Lab` `School of Computer Science at McGill University Version 1.2.1 November 1998`

What is it?


What does it need?
How does it work?
How do you use it? Undo+Redo New+Select+Add+Remove Verify+Process+Workspaces
How can you download it?


What can go wrong?
Who is responsible?