Mandelbrot Madness JAVA!

Version 3.1 -- Tutorial and Command Overview

[Return to README]

Command Overview

Getting Started: The Main Dialog Box

To install and start Mandelbrot Madness JAVA!, follow the instructions listed in the Installation and Setup page. We will assume you've already started MMJ! and are looking at the main dialog box, which is happily staring back at you.

The Main Dialog If what you see doesn't look exactly like what appears to the left, don't worry. Because Java programs must live within the limits of your operating system, it will have to look like your operating system. Since I was running MMJ! on a Windows 95 machine when I made this tutorial, MMJ! look like a Windows 95 program. In addition, different Java virtual machines may make it look different, even on the same platform. As long as you get something similar to what you see here, you're set!

Let's take a look at each part of the main dialog, and learn what they do:

The File menu: This pull-down menu holds most of MMJ!'s important commands, such as opening parameter files, choosing between Mandelbrot and Julia images, and closing the program. We will examine the File menu in detail later.

The Command menu: This pull-down menu allows you access to GUI versions of the command-line utilities of MMJ! While we'll briefly go over them below, you can read about them in more depth on the Command Line Utilities page.

The Window menu: This pull-down menu helps you manage all the little image windows MMJ! creates. From here, you will be able to close one window or all of them at once. We will examine the Window menu in detail later.

The Preset View drop-down list: This is the drop-down box that says "Mandelbrot Set (Classic)" in the diagram. From here, you can choose from a series of preset views I have entered. Each one is an interesting close-up of the Mandelbrot set. By selecting one of these views, it will fill in the x and y parameters needed to reproduce the image. It does not affect resolution, iteration count, or the color palette. These preset views will work only with the Mandelbrot set; it will be disabled if you attempt to render a Julia set image.

The X and Y Maximum and Minimum boxes: Each Mandelbrot set image requires four boundary values to define it: an x minimum, an x maximum, a y minimum, and a y maximum. These values define what part of the Mandelbrot set we are looking at. If you want, you can enter your own values directly into these text boxes, but they will usually be filled in for you by the present view list, opening a parameter file, rerendering an already open image, or zooming in on an open image. Every point on the image corresponds to an (x + yi) pair within these bounds. We will discuss these in more depth later when we actually render an image.

The Julia X and Julia Y Value boxes: Julia sets required two extra parameters: an (x,y) pair that unique identifies the set. (For the reasons behind this, see the Julia set overview.) These boxes are enabled when rendering Julia sets, and disabled when rendering Mandelbrot sets. Like the x and y boundary boxes above, they are usually filled in by a parameter file, by rerendering, or by zooming. They can also be filled in by rendering a Julia set from a point in the Mandelbrot set, found in the Image Window's context menu.

The Resolution box: Every image generated will be a square image based on this value. If you use the default of 300, it will produce an image 300 by 300 pixels. You can only create square images, and this can only be a positive integer value (no fractions or negative numbers). A word of warning: the bigger the image, the longer it will take to render, but the more impressive the result will become!

The Number of Iterations box: Mandelbrot and Julia set images are created by repeating the same calculation over and over again, feeding the result of the last calculation into the next. (We in the computer world call this recursion.) However, there has to be a point where you have to stop, and this value tells MMJ! when to do just that. The higher this number becomes, the more iterations are performed, and thus the more detailed you image will become. Also note, however, that this will also make the image take longer to render. This number must also be a positive integer.

The Current Palette and the Choose Palette button: MMJ! knows how to color your image by looking at a color palette. There are two internal palettes that you can choose from: a 256-color "rainbow" palette (the same as in the Win32 version) and a 256-color gray scale palette. These are the same palettes as used in version 1.x of MMJ! You can also create your own palettes or load new palettes from PAL files. To do this, you can click the Choose Palette... button. This will open the Select Palette dialog, which we will discuss in a little bit. You can see what palette is currently in effect by looking at the Current Palette: label beside and above the button. You can also activate the Select Palette dialog from the File menu, or by using the shortcut key P.

The Render button: Ah, this is what we've been waiting for! When you have all the parameters above filled in just the way you want them, just click this button to fire up the rendering engine and make a new image window. Be forewarned: Java is powerful and portable, but still a bit slow. Fractals also are notoriously slow to create. These two facts add up to a little waiting time on your part. Please be patient, and I promise you'll be happy with the results. You can also start the rendering process from the File menu, or by using the shortcut key R.


Let's take a quick look at the two menus in this dialog.

The Main Dialog's File Menu

File Menu The File menu in the main dialog contains some very important commands that affect the entire program. Let's look at each item:

Open Parameter File...: This option lets us open a MMJ! parameter file. MMJ! lets you save all the image parameters necessary to create any given image, including the color palette. This information is stored in a small text file with an .MMJ extension. (Palettes are saved to a .PAL file, and that file name is saved in the .MMJ file.) This way, you can store this information and reload it later, using this menu option. Choosing this will open a dialog box where you can choose what file to open. MMJ! will then open the file, read in the parameters, and fill in all the parameter boxes for you. Then all you need to do is click the Render button. You can share .MMJ files (and their companion .PAL files) with friends, and they can recreate them easily. This item can also be activated using the shortcut key O.

Open MOB File...: This option lets you open a MOB file, a new file format that contains both the parameters and color palettes for a given image in one compact file. This can be used as a replacement for the .MMJ and .PAL files. You can read more about the new MOB file later on the Introduction to the MOB File Format page. You can also open one of these files by using shortcut key M.

Choose Palette...: This item is the same as clicking the same button on the main dialog's face. It launches the Select Palette dialog. You can achieve the same effect using the shortcut key P.

Render...: This is the same as clicking the same button on the main dialog's face. It starts the rendering process. You can achieve the same effect using the shortcut key R.

Mandelbrot Set and Julia Set: These items let you choose which fractal to render. This is an either/or choice; if you choose "Mandelbrot Set," the "Julia Set" option becomes unchecked, and vice versa. You can quickly tell which of these are chosen by looking near the top of the window. If you see a label that says "Render Mandelbrot image:" then the Mandelbrot option is set; if you see "Render Julia Set image:" then Julia is set. These will also enable or disable certain parameter boxes in the main dialog, depending on what values are needed or allowed.

About...: This option will show the About box, which displays copyright and authorship information. It isn't entirely useful, unless you want to know where the MMJ! Web site is :) !

Exit: This will close MMJ! and end the program. It will also close all open image windows. When you choose this menu item, you will see a dialog box that asks if you are sure you want to exit, just in case you hit it accidentally. You can also close MMJ! using the shortcut key X.


The Command Menu

Command Menu The Command menu is new to MMJ! 3.1. It allows you to use most of the command-line utilities through a simple GUI connection. (I did this primarily for our friends with Macs, who don't have a command line, and for others who may be command-line impaired for any reason.) While we will briefly discuss each option in this menu, a more in-depth look can be found on the Command Line Utilities page.

Convert MMJ to old format: In MMJ! 3.0, I had to change the format of the .MMJ parameter file to support zooming in Julia sets. This makes parameter files incompatible between versions 2.x and 3.x. For backward compatibility, this utility will let you convert 3.x parameter files to 2.x parameter files. This can also be activated using shortcut key C.

DeMOB: This option will convert the new MOB file format back to the older MMJ format, complete with accompanying PAL palette file, if necessary. This is useful if your friends haven't upgraded to version 3.1 yet, and you want to share files with them. This can also be activated using shortcut key D.

ToMOB: This performs the reverse of above: it converts a MMJ parameter file (either version) and its PAL parameter file into the new MOB format. With this, you can quickly convert all your old parameter files to MOBs, which take up less disk space. This can also be activated using shortcut key T.


The Window Menu

Window Menu The Window menu allows us quick and easy access to all the image windows MMJ! creates. The Win32 version of Mandelbrot Madness! is a bit like many Windows programs in that it uses the Multiple Document Interface, or MDI. This means there is one main window, and all the little image windows are contained within it, much like Microsoft Word or Excel. Java does not support this type of interface, however, so each image in MMJ! gets its own little window. This can be quite cumbersome after a while, especially if you end up making many images! From here, you can bring a window to the front or close each window individually or all at once, all from one convenient location.

To Front: This submenu contains a list of all open windows by the title. You can find the window title in the title bar of that window. If you select one of the items in this list, the corresponding image window will be brought to the front of all windows on the desktop. If you see the word "(None)", that means that no image windows are currently open.

Close: Like the above submenu, this one also contains a list of all open image windows. However, if you select one of the items in this list, the corresponding image window will be closed. Make sure you know which window you're closing before you close it! If you see the word "(None)", that means that no image windows are currently open.

Close All: This item will close all open image windows at once. Use this if your desktop is getting too cluttered, you want to start zooming from scratch, or you just feel like getting rid of them all.


The Image Window

Now that we've taken a quick look at the main dialog, let's go ahead an create a sample image. Accept all the defaults in the main dialog and click the Render button. MMJ! will open a new image window and begin rendering. While it does this, let's take a few minutes to talk about the rendering process.

Image Window (Don't be alarmed that the image you're creating doesn't look like what you see here. The default image will use the Rainbow color palette; this is a 16-color gray scale palette. I just happen to like it better for this view.)

At the bottom of the window you will see a message that says something like "Rendering 45% complete...". This tells you approximately how much longer your image will take to complete the rendering process. You will not be able to execute any commands in MMJ! during this, so you might want to open up a small game (like Windows Solitaire) and get comfortable. You may notice that if you drag a window over top of the image window, you will lose part of the image. Don't worry, this will be redrawn once the image is completely finished.

Once the image is complete, try moving your mouse pointer over the image. You will notice that the message at the bottom of the window has changed to a set of numbers. These tell you the x and y coordinates of the cursor's position in the image. These will be useful for deriving Mandelbrot and Julia set images later. Let's take a look at the two menus available in this window.


The Image Window File Menu

File Menu Like the File menu in the main dialog, the File menu in the image window contains many important commands for saving, rerendering, printing, or viewing the parameters of you new image. Let's look at each item:

Rerender...: This option will take the x and y boundaries for your image and fill them into the main dialog's parameter boxes. It will not change the values in the resolution, iterations, or color palette parameters. The idea behind this is to allow you to generate quick, small images for zooming and exploring. Then, when you come upon something you want a better look at, you can "rerender" it with a new resolution, number of iterations, and/or color palette, without having to save a parameter file or type in all those numbers. Just choose Rerender here, go back to the main dialog, change what you want, and render a new image. This will not replace the current image with another. You can also activate this item using the shortcut key R.

Save GIF...: This item will let you save a copy of the image into the CompuServe GIF image format. You will be prompted for a file name to save the file as. After the file is saved, you can load it into your favorite image editor or GIF viewer, send it to a friend, or upload it to your Web site. Only the image itself will be saved; you won't get the menu bar, title bar, or status line. Saving an image to GIF format will change the window's name to the file name you specified. You can also activate this item using the shortcut key G.

Save Parameters...: Remember how I told you about loading a parameter file (.MMJ) back in the main dialog's File menu? Well, here's were you save it. Choosing this option will allow you to save all the parameters needed to recreate the image into a .MMJ file, which can be loaded later. First, if you created a custom color scale palette for your image, you will be offered an opportunity to save that palette to a .PAL file. Then you will be asked for a file name to save your parameters to. Once saved, the window's title will change to the file name you specified. You can then pass the parameter file (and its companion palette file, if needed) on to friends, or store it and load it again later. You can also activate this item using the shortcut key S.

One note about parameter files: Because of the addition of zooming in Julia sets, a change had to be made to the .MMJ file specification. .MMJ files created by MMJ! 3.x cannot be read by MMJ! 2.x! However, a command-line conversion utility has been added to convert newer parameter files to the old format. See the Command Line Utilities page for more details.

Save MOB File...: This menu item will save the current parameters and color palette to the new MOB file format. MOB files are meant to operate as a replacement or substitution for the MMJ parameter files. To find out more about this new format, follow the link above. You can also activate this item through shortcut key M.

Print...: Thanks to Java 1.1, MMJ! now supports printing capabilities. Simply choose this option, and you will be presented with your operating system's default printing dialog box. You can then print the image to your printer. A few words of caution, however: (1) It might help to know your printer's resolution. If you try to print a picture too large to fit on your printer's page, you will lose some of your image. Your image must fit on one page. (2) My initial tests with the printing capabilities of Java 1.1 have not been too successful. Don't expect spectacular results. Perhaps this will be enhanced in the next versions of Java, but you'll have to settle for mediocre today. But, some printing is better than no printing.... You can also activate this item using the shortcut key P.

Info...: This option will display a small dialog box showing all the pertinent information about your current Mandelbrot or Julia set image, including all input parameters, resolution, iterations, and palette information. This is highly useful if you need to know where you are in the graphs. You can also activate this item using the shortcut key I.

Close: This will close the current image window. You will get no warnings if you haven't saved anything, so be sure this is what you want to do before you do it! You can also activate this item using the shortcut key X.


The Image Window Edit Menu

The image window has a second menu, called the Edit menu. This menu has only one item: Copy. Currently, this option is not implemented in version 3.1! While Java 1.1 has the capability of copying text data to the system clipboard (and thus to other non-Java applications), it does not yet support copying image information. Hopefully, once Java implements copying image data in this manner, I will add it into MMJ!, just like in the Win32 version. Until then, however, you will have to save your image to a GIF file and load it into whatever program you wanted to copy it to.

MMJ! likewise does not support cutting or pasting, but this is because such actions are not needed. MMJ! only renders Mandelbrot and Julia set images; it is not an full-fledged image editor.

Not that it will do you any good just yet, you can also activate this item using the shortcut key C.


The Context (or Pop-Up) Menu

Note: I had quite a bit of difficulty with this. If you are using the JavaSoft JDK or JRE before version 1.1.7B, I cannot guarantee that it will work. There is a bug in some earlier versions of the JDK and JRE that did not display pop-up menus correctly. It is not a bug in MMJ! If you use these virtual machines, I suggest you update to version 1.1.7B.

The image window also has another feature: a context, or "pop-up", menu. Bringing up a context menu is platform specific, so I won't explain that here. (Windows users would use their right mouse button if their left button is the primary one.) The same menu can also be brought up by clicking the mouse with primary mouse button while holding down the Control key. If you bring one up in the image itself, you will get a quick menu that has many of the commands in the File and Edit menus, with one main addition:

Render Julia Set at this point: If your current image is a Mandelbrot image, you can click this option to create a Julia set image based on the current x and y coordinates. The values will be filled in on the main dialog, where you can then specify the resolution, number of iterations, and the color palette. (This works similar to the Rerender function.) This option will be disabled if you bring the context menu up over a Julia set image.


Image Derivation: Zooming in on a Selection

There is one last command function we haven't discussed, and it just happens to be the most fun. If you still have your image window open that you created above, move your mouse until the coordinates at the bottom of the window read (-0.26, 1.19). Now, hold down your mouse button and drag a selection out on the image until the coordinates read (0.25, 0.57), then release the button. A dialog box will ask if you want to zoom in on this selection. Choose Yes. A series of parameters will then be filled in on the main dialog. Click the render button, and you should get something like what you see below.

Zoom Example Okay, it's not the prettiest example, but it makes the point. What we just did was derive an image, or zoom in on a subset of the image. This is where MMJ! has some of its greatest power. Using this feature, you can zoom deep into infinite levels of the Mandelbrot set, exploring its many twists and folds with alarming ease. And when I say infinite, I do mean infinite. You will find--eventually--that there is a point where your computer can go no further, that the limits of Java's number crunching is exceeded and images cannot be derived accurately. This is a very difficult point to reach, however, so don't expect to reach it quickly. But expect to tons of fun doing it.

Deriving an image works on a similar principle as the Rerender item under the File menu. Using your mouse (or other pointing device), draw out a selection, then release the button. The boundaries of your selection will then be fleshed out to a square (remember, MMJ! can only draw square images) and the x and y boundaries will be sent to the main dialog. You can then change the resolution, number of iterations, and/or the color palette and render a whole new image of your selection. In this new image, you will see increased detail which you couldn't see before. And, because this is just another close-up of the same Mandelbrot set, you can zoom even further, getting more and more detail. In fact, many of the preset views you can choose from are a process of constant zooming in the same general area.

Image derivation also works for Julia set images.


The Select Palette Dialog Box

Select Palette Dialog If you click on the Choose Palette... button on the main dialog, a new dialog box appears. This is the Select Palette dialog. Using this dialog, you can change what colors your Mandelbrot and Julia set images will be rendered in. Let's look at each option available:

Use 256-Color Rainbow or 256-Color Grey Scale Palettes: The first two radio buttons let you choose one of the two built in palettes available in MMJ! There is a 256-color "rainbow" palette (the same as the one in the Win32 version) and a 256-color gray scale palette. If you choose one of these, no other options are needed, and the words "Rainbow" or "Grey Scale" will appear as the current palette on the main dialog and the Info dialog.

Define Color Scale: If you choose this radio button, you can create a palette that will be a smooth transition between two colors. There are two colored bars here, and under each is a button. The dark color is the color of items actually in the Mandelbrot set or Julia set. The light color is the brightest possible color on the graph. You can set these by clicking the appropriate button, which will launch the Select Color dialog box. Next, you can change the number of colors in your palette in the drop-down box below the Light color... button. You can choose either 16 or 256 colors. When you click the Ok button, a new palette will be generated with the number of colors specified. The colors will create a smooth transition from the dark color to the light color. This is identical to the similar function in the Win32 version. Palettes created this way are named "Custom Color Scale" elsewhere in the program.

Load Palette from File: If you choose this radio button, you can load a saved palette from a file on disk. This radio button enables the Load Palette... button. When you click this button, you will be presented with a dialog box where you can load a .PAL file. The file will be read and converted into MMJ!'s internal palette format. Loaded palettes will be named "Loaded from [filename]" whenever the palette's name is displayed.

Of course, clicking the Ok button will return your chosen palette to the main dialog so it can be used in rendering, and clicking the Cancel button will close this dialog without altering the current palette.


The Select Color Dialog Box

Select Color Dialog When you click one of the color buttons in the Select Palette dialog, you will be presented with this dialog box, which lets you select a color. Colors in Java are represented by three integer values for the red, green, and blue components, which can range from 0 to 255. Using these in combination allows you to choose from just over 16 million different colors. That's the most colors most modern monitors are capable of displaying.

To change the current color, move the slider bars (scroll bars) on the right side of the dialog to change the component value. The numeric value of that component will be shown at the left, and the exact color will be drawn in the box at the top. Near the bottom, you will also find a label that tells you what the color would be in the HTML hexadecimal color notation. Once you have selected the color you want, click the Ok button to return to the palette select dialog, or click the Cancel button to return without making changes.


Menu Shortcut Keys

Starting with version 3.0, MMJ! also supports menu shortcuts. Windows and Mac users are probably most familiar with these. Menu shortcuts allow you to activate a menu item function with a simple keystroke, as opposed to moving the cursor to the menu, clicking, choosing your option, then clicking again. Power users are often quite adept at these; I know I hardly every use the Edit menu in my Windows applications anymore, when Control + C will copy and Control + V will paste and my fingers are already on the keyboard.

Java 1.1 adds menu shortcut functionality, and now MMJ! makes use of it. Virtually all commands accessible through menu items are now available as menu shortcuts. Menu shortcuts are usually activated as a combination of keys. Windows uses Control + some other key; Macs use the Command (Apple) key; and most UNIX/X Windows boxes use Control (I think). Java implements this in a platform-dependent way, usually to keep with the normal methods of the platform. Make sure to check your Java documentation to see what activator key (Control, Command, Alt, etc.) your platform uses.

Below is a list of MMJ!'s menus and the associated shortcut. Simply hold down the activator key plus the shortcut key to perform the same action. Menu items marked "(none)" have no shortcut key, either because it seemed impractical or because Java would not allow a shortcut to be associated with that item type.


[Return to README]

© Copyright 1999, Jeffrey T. Darlington. All rights reserved.