Mandelbrot Madness!

Version 2.0 -- MM! Command Line Utilities

[Return to Index]

Mandelbrot Madness! now includes a command line (or console) companion program called mmbatch. In addition to the familiar GUI (graphical user interface) mode described in the Command Overview, this separate program allows you to perform "batch" operations through the speed and flexibility of a command line interface. This program includes several options, such as the quick rendering of .MMJ or MOB files to images and conversion utilities that can convert MMJ files to MOBs and back or even to older versions of the MMJ. (Tech-heads take note: Unlike the Java version where the GUI and console apps are the same executable, this is a separate program from the MM! GUI, but it calls many of the same libraries.)

The conversion utility is available under the Tools menu of the GUI. This lets the "command-line impaired" perform the same actions through the GUI as they can with the console program. Only the batch rendering mode is unavailable through the GUI (as rendering is an interactive process there). However, you should still read this page, since it gives you deeper insights into why these utilities are available.

Note: Even if you have set folder locations in your MM! preferences, the command-line utilities do not access these settings. If no absolute paths are specified, they work only in or relative to the current directory. When run in command-line mode, MM! does not read the configuration file at all. Keep this in mind when using these utilities.

Also note: If you do not install batch-mode support when you installed MM!, these methods will not be available to you on the command line. However, this page goes more in depth into some of the conversion methods described in the Tools menu help, so reading this page may still be useful to you.

Using MM! in Batch Mode

In order to run MM! in batch mode, open a command prompt (DOS prompt for you old-timers). When you installed batch mode support, the path to this program should have been added to your PATH environment variable, so you should be able to run the program from anywhere. The basic command line for batch mode is:

   C:\Program Files\Mandelbrot Madness!> mmbatch -{output_format} parameter_file [parameter_file [...]]

(Note: the path in the example--"C:\Program Files\Mandelbrot Madness!"--may be different on your system if you installed the program to a different location. This is just an example.)

The executable program is mmbatch. The "output_format" switch determines which image format you want to save your rendered images to. The following image formats are available:

Note that only one format switch may be specified on the command line, and that it must immediately follow the mmbatch command. All parameter files specified in a single command line will be saved to the same image format once rendered.

On the rest of the command line, you must specify one or more parameter files (in either MMJ or MOB formats) to render. MM! will open each file, render the image off screen, then write the resulting image to the same file name but with the appropriate extension for that image type. For example:

   C:\Program Files\Mandelbrot Madness!> mmbatch -png kewl.mmj

In this example, MM! will open the file kewl.mmj (and its associated palette file, if necessary), render the image, then write the resulting image to the file kewl.png. Multiple files can be processed at once by simply passing multiple filenames to the program.

Observe the following example:

   C:\Program Files\Mandelbrot Madness!> mmbatch -png heart_pink.mmj julia1.mob nothere.mmj julia2.mob

   Mandelbrot Madness! v.
   Copyright 2007, Jeffrey T. Darlington.  All rights reserved.

   Warning: The palette file specified in this MMJ file could not be found. Defaulting to the Rainbow palette...
   Rendering heart_pink.mmj... Done!
   Saving image file heart_pink.png... Done!
   Rendering julia1.mob... Done!
   Saving image file julia1.png... Done!

   Error: File nothere.mmj does not exist.
   Rendering julia2.mob... Done!
   Saving image file julia2.png... Done!

Here, we have passed four file names to mmbatch to process. MMJ and MOB files are treated identically. MM! 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.mob after it was 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.)

Note that different image formats may produce different results. In general, we don't recommend that you use GIFs or JPEGs for saving your images, as the .NET implementations of these formats do not produce optimal results. See the Supported File Types information for more details.


Converting Between Parameter File Formats

Over the years, MM! and MMJ! have collected quite a zoo of parameter file formats. The MMJ format has changed at least once and the MOB and MM XML formats have been added to newer versions of the application but remain unsupported by older versions. Adding these changes has not been done on a whim, of course; we firmly believe that each addition has been a significant improvement over the older formats, and we strongly encourage adoption of the newer formats over the old. However, it's often helpful to convert between these formats. If you have a friend who continues to use an older format, you can convert your new format files to a format she can use. Likewise, you might want to convert files she has given you to a new format to take advantage of the new features.

Similar to the batch render mode, you can convert between the different formats in batch mode as well. To do so, use the following conversion flags:

To convert a number of files to, say, MM XML format, you can execute mmbatch like this:

   C:\Program Files\Mandelbrot Madness!> mmbatch -tommxml kewl.mmj wow.mob something.mmj

Like the image rendering mode, it doesn't matter what order the files are placed in or even what file format they are currently in. The program will happily open all parameter files fed to it and convert them to the specified format. Note that it doesn't really care what the old file is, and it won't stop you from converting an MM XML file into another MM XML file, which is essentially a waste of time. It only validates that the input files are valid and performs the conversion. Thus, it helps to pay attention to your input files. Also like the batch render 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. 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.

Here's a few additional notes about file conversion:

Because of the addition of zooming for Julia sets, the MMJ parameter file format changed between MMJ! versions 3.x and 2.x. This means that the parameter files produced by MMJ! 3.x and above and by this version of MM! are not backward compatible with MMJ! 2.x. This program can read 2.x files, but it does not write them by default. This means that friends who may still be using MMJ! 2.x will not be able to read the files you produce. While I would strongly recommend that everyone upgrade to the latest versions of either program, you can convert to this older format using the -tommjv1 command.

There is a trade off, however. This means that if you convert any parameter file that contains a zoomed-in Julia set, you will loose the x and y minimum and maximum boundaries. The "Version 1" MMJ file will only contain the Julia set (x,y) pair and will render with maximum boundaries. MMJ! 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.

When converting from MMJ/PAL files pairs, you may experience problems if the file parameter file and the palette file are in different locations. 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 keep both the parameter and palette files in the same directory when converting them to any other format (especially MOB or MM XML, which store palettes inline).

When converting from MOB to MMJ files, 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.)

In the GUI, you can specify where the save prerendered image data to MM XML files. Batch mode never saves prerendered data. Batch mode also always compresses MM XML files, which is also presented as an option in the GUI. These options cannot be changed, although I may consider adding them to later versions if there's enough demand. Note that MM XML comments are also unsupported.


Command-line Help

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

   C:\Program Files\Mandelbrot Madness!> mmbatch -?

It will also accept other popular variations of this switch, including -?, -h, and -H. (DOS users: it will not accept DOS-style switches (/?) because this could be confused with a UNIX filename. With .NET implementations being ported to operating systems other than Windows, we don't want to introduce incompatibilities. Thus, all command-line switches are in UNIX-style with dashes in front.)


[Return to Index]

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