Mandelbrot Madness JAVA!

Version 3.1 -- MMJ! Command Line Utilities

[Return to README]

Starting with version 3.0 of Mandelbrot Madness JAVA!, you can now run the program in two modes. The first is the familiar GUI (graphical user interface) mode described in the Command Overview. The second is a command-line driven mode with several options, such as a "batch" mode for quick translation of .MMJ or MOB files to GIF images, and conversion utilities that can convert MMJ files to MOBs and back or even to older versions of the MMJ.

Starting with version 3.1, all of the conversion utilities are available under the Command menu of the program. This lets the "command-line impaired" perform the same actions through the GUI. Only the batch mode is unavailable through the GUI. However, you should still read this page, since it gives you deeper insights into why these utilities are available.

Using MMJ! in Batch Mode

(Note that MMJ! still requires a windowed operating system to run! In fact, the batch mode still makes use of the Java AWT, even though you cannot see it. MMJ! still will not run in a character-only environment.)

Assuming you are using the Sun JDK on a Win32 box to run MMJ!, you would launch the program like this:

   C:\MMJ> java Mandel

(UNIX users will, of course, have a UNIX prompt, etc.) In order to run MMJ! in batch mode, run it using the -batch option and pass it a list of one or more .MMJ files or MOB files to process. For example, say you have parameter file kewl.mmj that you would like to create a GIF image of without opening the GUI and letting it draw to the screen. You can process it batch style by simply typing:

   C:\MMJ> java Mandel -batch kewl.mmj

MMJ! will open the file, render the image off screen, then write the resulting image to the file kewl.gif in the MMJ! directory. The GIF file will always have the same name as the .MMJ or .MOB file, only with a .GIF extension. Multiple files can be processed at once by simply passing multiple filenames to the program.

Observe the following example:

   C:\MMJ>java Mandel -batch heart_pink.mmj julia1.mob nothere.mmj julia2.mmj

   Mandelbrot Madness JAVA! 3.1
   (c) Copyright 1999, Jeffrey T. Darlington.  All rights reserved.

   Warning: PAL file in heart_pink.mmj could not be found, defaulting to Rainbow pa
   Rendering heart_pink.mmj.......................... done!
   Saving heart_pink.gif... done!
   Rendering julia1.mob........ done!
   Saving julia1.gif... done!
   Error: Error occured reading nothere.mmj, aborting action...
   Rendering julia2.mmj.................... done!
   Saving julia2.gif... done!

Here, we have passed four file names to MMJ! to process in batch mode. MMJ and MOB files are treated identical. MMJ! will handle each one separately, so if one fails, the rest will still continue. Notice the file nothere.mmj could not be found; even so, the file julia2.mmj after it is processed. If a .MMJ file has a companion .PAL palette file, it will be read as well. If the .PAL file cannot be found (like in heart_pink.mmj above), MMJ! will default to using the Rainbow palette. (This problem will not occur with a MOB file.)


Converting New MMJ Parameter Files to the Old Format

(None of the conversion utilities use the Java AWT, and can technically be run on a character-only system. I have successfully run them at a Linux character prompt and they worked fine. However, the batch mode crashed, because it couldn't find the X server. The moral: you should still probably run things from a command/shell prompt in your windowed environment, just to make sure.)

Because of the addition of zooming for Julia sets, the .MMJ parameter file format has changed. This means that the parameter files produced by MMJ! 3.x are not backward compatible with MMJ! 2.x. Version 3.x can read 2.x files, but it cannot write them. This means that friends who may still be using 2.x will not be able to read the files you produce. While I would strongly recommend that everyone upgrade to version 3.1, I have also included a command-line utility to convert 3.x files to 2.x files.

There is a trade off, however. This means that if you convert a 3.x file that contains a zoomed-in Julia set, you will loose the x and y minimum and maximum boundaries. The 2.x file will only contain the Julia set (x,y) pair and will render with maximum boundaries. 2.x users will be able to see the Julia set as a whole, but will not be able to see your zoomed image, nor will they be able to zoom in themselves.

To convert a 3.x parameter file to a 2.x parameter file, run MMJ! with the -convert option:

   C:\MMJ> java Mandel -convert filename.mmj

Like the batch mode, you can specify any number of files, and if an error occurs, processing will stop on that file only and will continue with the next. The utility will also make sure you don't try to convert a 2.x file, and has the capacity to check for future file format changes, should they be needed in the future. Converted files will have a "_1" attached to their name before the extension; for example, if kewl.mmj is converted, the resulting file will be named kewl_1.mmj.

To convert a MOB file to a 2.x MMJ file, it must first be "deMOBbed" to convert it to a 3.x MMJ, then converted again. Version 2.x cannot read MOB files. You can read about "deMOBbing" below.


Converting between MMJ Parameter Files and MOB Files

With the introduction of the new MOB file format in version 3.1, we now have even more version control to worry about. Relax, because, as always, you're still covered. With two more command line options, you can "toMOB" and "deMOB" your files to easily convert them from MOBs to MMJ files in one swift motion.

I call converting MMJ parameter files to MOBs "toMOBbing." This can be done by using the -tomob option:

   C:\MMJ> java Mandel -tomob filename.mmj

In this case, the file filename.mmj will be read and, if necessary, any corresponding PAL palette files will be loaded with it. They will be converted into MMJ!'s internal format, then written out together as a single MOB file, filename.mob. As with the batch mode, the filename is retained; only the extension is changed.

"ToMOB" may experience problems if the file parameter file and the palette file are in different locations, or if you run MMJ! from one directory and try to convert a parameter file in another. This is because the MMJ parameter file format does not save path information when it records a palette file's file name. (See the FAQ for more info.) You should probably copy both the parameter and palette files into the MMJ! directory when converting them to a MOB.

The reverse process is "deMOBbing," or translating a MOB file into its respective parts. This is appropriately done with the -demob option:

   C:\MMJ> java Mandel -demob filename.mob

Again, file names are preserved. filename.mob will produce filename.mmj. If the MOB file has a PAL filename associated with its palette, the palette file is saved as well. The internal Rainbow and Gray Scale palettes are not exported. If there is no palette name associated with a palette, it is not exported. (Note that the GUI version of this command will ask for a file name for the palette; this command-line utility will not.)

To learn more about MOBs, see the Introduction to the MOB File Format.


Command-line Help

As a refresher, you can get a listing of all these commands by typing:

   C:\MMJ> java Mandel -?

It will also accept other popular variations of this switch, including -?, -h, and -H. (DOS users: it will not accept a /? because this could be confused with a UNIX filename.)


[Return to README]

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