amaze − GUI to generate and print mazes
amaze
[−x columns] [−y
rows] [−wall wall-width]
[−path path-width] [−stay
count] [−cuts count]
[−s] [−creep ms]
[−option
... ]
The settings,
such as colors, can be changed in the GUI. To find out where
they are saved between sessions, use: amaze
−init
To restore all defaults, and ignore the saved settings, use
the −no−restore option.
amaze is a graphical application to generate and print simple mazes. The maze properties (size and look) can be set in the GUI, or preset using command line arguments.
Terminology
We say a maze consists of a grid of tiles, and a set
of walls between those tiles. Between each two
neighboring tiles there either is a wall or there is none;
if there is none, then the two tiles are said to be
connected. When a tile A is connected to tile B, and
B to C, then A and C are also connected (through B). We call
the sequence of tiles A-B-C a path from A to C. Each
maze has a departure tile and a destination
tile; the path between these two tiles is called the
solution path of the maze (there can only be one such
path). The joy and challenge of a maze, traditionally, is to
find the solution path through the maze.
Actions
The graphical interface shows a set of maze controls and a
single maze. The maze is randomly generated each time the
maze grid dimensions change (see the "Width" and
"Height" controls), and whenever you select the
File > New menu item. With the
Edit > Show path toggle you can
choose whether to display the solution path (the "trail
of bread-crumbs", if you will) in the maze on the
screen or not. Every time that you switch it on, the path
display mode will alternate between steady and animated
("creeping" through the maze). See also option
−creep. When you print the maze (using
File > Print...) two pages are produced:
first the maze without the solution path indicated, and then
the maze with a dotted line to show the solution path.
Outline
You can use an outline image (a.k.a. "mask") to
define the shape of the maze. By default, the maze will fill
all of the rectangular grid of available tiles. A mask
consist of an image, and a "dead" color.
Currently, the dead color is that of the (0,0) pixel of the
image. Any pixel in the mask with that color is called a
dead pixel. When you define a mask, it is stretched to cover
that rectangle, and then all tiles whose middle pixel
position corresponds to a dead pixel in the mask are
excluded from the maze. So if the mask image is a picture of
a cat on a (monochrome!) white background, the maze will
have the shape of a cat. You can define the outline image
using File > Open outline, or just
drag an image (must be a local file) onto the canvas.
Note
Internally, the maze is represented as a set of
cells. For square and triangle shaped tiles, one tile
equals one cell; for hexagon shaped tiles, each tile is two
cells tall; for octagon, one or three. Some notes in the
documentation may be unclear if you are not aware of this
distinction.
The version of amaze that runs on MS Windows, runs a pure GUI application, without an attached console window. This implies there is no "standard output", so if you want the result of e.g. −init you need to use the −out file option preceding it on the command line.
−x columns
specifies the number of columns of tiles in the maze grid. You can later adjust this in the GUI using the "Width" spin-box or slider.
−y rows
specifies the number of rows of tiles in the maze grid. You can later adjust this in the GUI using the "Height" spin-box or slider.
−p/−path pixels
sets the width, in pixels, of the solution path through the maze, when it is displayed in the GUI (see option −s). You can later adjust this in the GUI using the "Path" spin-box or slider. If the display area is too small, the path may be drawn narrower than this.
−wall pixels
sets the width, in pixels, of the walls in the maze. You can later adjust this in the GUI using the "Wall" spin-box or slider. If the display area is too small, the walls may be drawn narrower than this.
−stay factor
determines how long each step in the maze tries to stay in the same direction. Set to 1, the direction is fully random at each tile; set to N, the chance is 1 in N of being random. Note that fully random mazes tend to have comparatively long solution paths.
−cuts count
will try to add the given number of extra cross-cuts between adjacent cells not on the path. Zero cuts means the maze will not contain loops in paths, and non-zero means some walls may not be attached to the border. The count is an upper bound, the maze may end up with fewer cuts.
−tile shape
shape of maze tiles: triangle, square, hexagon or octagon.
−mask file
will use the image in the file to mask off part of the grid, using the (0,0) pixel’s color as the transparent color. So if you have a picture of something on a monochrome background, you get a maze in the same shape. Special cases for file are "[total]" (no mask), "[round]" (built-in circular shape), and "[heart]" (for Valentine’s Day). If you really must use a file with a name literally starting with "[", prefix it with "[image]".
−path-color color
sets the solution path color. For a detailed discussion of color name formats, see http://doc.qt.nokia.com/4.7/qcolor.html#setNamedColor. Examples: "steelblue", "#112233".
−tile-color color
sets the tile color. Cf. option −path-color.
−text-color color
sets the message text color. Cf. option −path-color.
−text text
sets the message text. This text will be strung along the solution path (one letter per tile, with random spacing), so that finding the solution will also let you read back the message.
−wall-color color
sets the maze wall color. Cf. option −tile-color.
|
−s |
shows the solution path as a dotted line in the maze display in the GUI. |
−cover 0-100
determines what percentage of the path is shown at most during path animation. The path starts growing from the departure point, adding the increment at each step (see option −steps). Once this percentage is hit, the tail end starts retracting towards the destination point.
−creep ms
specifies the interval (in milliseconds) between path animation steps. If the value is zero, the path is not animated at all.
−steps count
will animate the path to move from departure to destination in this many steps. The effective increment per step will be at least one cell.
−out path
redirects the standard normal output to the given file. On MS Windows, you will need this to get any output from e.g. −help or −init.
−err path
redirects the standard error output to the given file. On MS Windows, you will need this to get any non-GUI error messages.
−std path
redirects both the standard normal and error output to the given file. Using both −out and −err on the same file instead is not good, it will cause one to overwrite the other.
−locale locale
explicitly selects a localization string locale. Currently (partially) supported are: "da", "de", "en_GB", "en_US" (= English, USA spelling), "eo", "es", "fr", "nl", and "zh_CN".
|
−mini |
strips down the UI to fit on a smaller screen. With this, you can use amaze effectively down to about 320×200 pixels. |
−do-splash
shows a splash screen when starting up.
−no-splash
does not show a splash screen when starting up.
−no-restore
ignores any saved settings, reverting to the built-in defaults.
−no-retain
suppresses saving any changes to saved settings.
|
−init |
prints the path to the file where the settings are saved. |
Qt Common
Options
These come with use of the Qt 4.7 widget libraries.
−style=style
−style style
sets the application GUI style. Possible values are motif, windows, and platinum. If you compiled Qt with additional styles or have additional styles as plug-ins these will be available to the −style command line option.
−stylesheet=stylesheet
−stylesheet stylesheet
sets the application stylesheet. The value must be a path to a file that contains the Style Sheet. Note: Relative URLs in the Style Sheet file are relative to the Style Sheet file’s path.
−session=session
−session session
restores the application from an earlier session.
−widgetcount
prints debug message at the end about number of widgets left undestroyed and maximum number of widgets existed at the same time
−reverse
sets the application’s layout direction to Qt::RightToLeft
−graphicssystem
sets the back-end to be used for on-screen widgets and QPixmaps. Available options are raster and opengl.
−nograb
tells Qt that it must never grab the mouse or the keyboard. (Qt with QT_DEBUG only.)
−dograb
running under a debugger can cause an implicit −nograb, use −dograb to override. (Qt with QT_DEBUG only; only under X11.)
|
−sync |
switches to synchronous mode for debugging. See Debugging Techniques for a more detailed explanation. (Qt with QT_DEBUG only; only under X11.) |
−direct3d
will make the Direct3D paint engine the default widget paint engine in Qt. This functionality is experimental. (On Microsoft Windows only).
X11 Common
Options
The X11 version of Qt supports some traditional X11 command
line options.
−display display
sets the X display (default is $DISPLAY).
−geometry geometry
sets the client geometry of the first window that is shown.
−fn font
−font font
defines the application font. The font should be specified using an X logical font description.
−bg color
−background color
sets the default background color and an application palette (light and dark shades are calculated).
−fg color
−foreground color
sets the default foreground color.
−btn color
−button color
sets the default button color.
−name name
sets the application name.
−title title
sets the application title.
−visual TrueColor
forces the application to use a TrueColor visual on an 8-bit display.
−ncols count
limits the number of colors allocated in the color cube on an 8-bit display, if the application is using the QApplication::ManyColor color specification. If count is 216 then a 6×6×6 color cube is used (i.e. 6 levels of red, 6 of green, and 6 of blue); for other values, a cube approximately proportional to a 2×3×1 cube is used.
|
−cmap |
causes the application to install a private color map on an 8-bit display. | ||
|
−im |
sets the input method server (equivalent to setting the XMODIFIERS environment variable) |
−inputstyle
defines how the input is inserted into the given widget, e.g., onTheSpot makes the input appear directly in the widget, while overTheSpot makes the input appear in a box floating over the widget and is not inserted until the editing is done.
Amaze returns non-zero only on fatal internal errors or invalid command line parameters.
Command line argument errors are reported to standard error output. User problems while using the GUI are normally displayed in localized modal dialog windows.
No environment variables are used to configure the application part of this program. The linked libraries (for Qt, and X11 under Linux) may have environment variable dependencies.
Note the file paths given here are for Ubuntu, and may be different on other platforms.
/usr/share/amaze/*.qm
− the Qt localization files
/usr/share/applications/amaze.desktop
/usr/share/app-install/desktop/amaze.desktop
− for the desktop menu
/usr/share/doc/amaze/*
− copyright and such
/usr/share/icons/hicolor/*x*/apps/amaze.png
− desktop and application menu icons
/usr/share/man/man1/amaze.1.gz
− this manual page
/usr/bin/amaze
− the executable
$HOME/.config/Morgul/amaze.conf
− the settings saved between runs for this user
http://qtamaze.sourceforge.net/version.html
− where the update check looks for the current version and release number
See option −init for the system-specific, per-user file used to save settings between sessions.
This is the second version, 1.1. (The first version, 1.0, is now obsolete.) It is available at http://qtamaze.sourceforge.net as source (via CVS), as an Ubuntu/Debian package, and as a Windows XP MSI file.
Amaze tries to follow the GUI guidelines and Qt samples in the Qt 4.5-4.7 documentation, the Gnome guidelines for the ".desktop" file, and the WiX recommendations for the MSI installer.
Also, generating mazes is not exactly a new or challenging topic in itself, but fun enough to use as the subject of a project for me.
For more details on open issues and ongoing changes, visit the project tracker at http://qtamaze.sourceforge.net/, or retrieve the sources through CVS there and look at the file amaze/TODO.
To do
− Move printing job to separate thread, with progress
bar. Currently it runs on the main thread, which could hang
if the printing process is blocked.
− We force the maze to fit in the display area. This
makes it easy to resize, but limits the user to making mazes
that will fit on the screen.
− This manual page is only available with the Ubuntu
package, we should include a PDF for the Windows MSI.
Localization
− I’ve got partial localization done for [da],
[de], [eo], [es], [fr], [nl], [zh_CN] but I’m sure the
translations don’t follow all conventions, and some
are incomplete.
− The non-"Comment" entries in the
amaze.desktop file have not been localized yet. Ditto for
the text printed by the "-help" option.
Output
formats
− Output to animated GIF with the solution path
winding through the maze. Or ditto but to sequence of files,
for later composition. We now support path animation on the
screen, but not in export.
Configuration
− Currently the user has no control over the dot and
dash pattern of the solution path.
−
File>Export is a bit weird: it has no "All files
(*.*)" filter, leaves a transparent border if the
screen area is bigger than the maze picture, and could use
more polish.
− File>Blend, File>Maya and File>Virtual are
experimental and not quite complete; they export a Blender
Python script, a Maya MEL script, and an X3D/VRML file
respectively. These lack tile floors, don’t show the
solution path, and for MEL lose the colors.
− The exported images include the empty space in the
canvas window, instead of being neatly trimmed down.
− If you pick the departure point to be right next to
the destination, the solution path may not enter the maze at
all. If they are on opposite sides of the same corner, the
corner can appear invisible because it has no border wall on
the outside.
− In PostScript print, the line caps stick out a bit.
We should probably rewrite the wall drawing code a lot;
currently it just draws each segment separately, which means
the corners are not drawn according to the pen join mode
(bevel, miter, whatever).
− To get better solutions, we prune any loops in the
solution after generating the initial maze. This improves
the average solution (70-90% reduction in length) but may
make small mazes boring. Maybe the loop reduction factor
should be adjustable.
− The loop pruning does not eliminate horizontal loops
in hexagon or octagon mazes unless the top and bottom part
run in immediately adjacent cell rows.
− Mazes with hexagon-shaped tiles may run off the page
when printing them.
− For mazes with triangle tiles, the "stay"
does not work well; currently a continuous diagonal line of
tiles equals an alternating path of horizontal and vertical
steps in the cell grid, which gets low probability for a
higher stay value. So, you just get more horizontal lines.
− Mazes with exactly one column or one row of tiles
may turn out strange.
− Further bugs and blemishes can be found recorded in
the bug reports and feature request tickets at
http://sourceforge.net/p/qtamaze/_list/tickets.
amaze −no−splash −s
tinco at SourceForge
xlaby(1).