• Introduction
• Installing BurrTools
  • Downloading BurrTools
  • Installation of BurrTools
    • Microsoft Windows
    • Mac OS X
    • Linux / Unix
  • Files and Folders
  
  
• Concepts and Definitions
  • Definitions
  • Concepts
    • Voxel States
    • Colour Constraints
  
  
• Notes for PuzzleSolver3D Users
  • Importing PUZZLESOLVER3D files

Getting Started

Introduction

The first part of this user guide is written from a procedural approach. Rather than sequentially describing the elements of the GUI and their functions, this manual guides you through the program the way you should create your first design. Terms may be briefly repeated at several places in the text.

Throughout the text the following fonts and notations are used:

Roman	This font is used for the main text.
Roman Italics	Italics are used to emphasis words or sentences in the main text.
Roman Bold	Used for titles, subtitles and concepts.
Sans Serif	Used for elements of the GUI. The same wording is used as in the GUI.
Sans Serif Bold	Used for elements of the GUI and indicating that an in-depth explanation follows.
SMALL CAPITALS	Used for program names and puzzle names.
Typewriter	Used for file names, directories, URL's and code examples.
[Typewriter]	Between square brackets. Denotes a keyboard command.
→	Followed by a number. A reference to another point in the text that provides more detailed information on the subject. To be read as 'see (also) ...'.

Installing BurrTools

Downloading BurrTools

BURRTOOLS is an Open Source software project. The most recent release of the program is always available for free download at the BURRTOOLS website:

At the bottom of that page you can select the proper download for your operating system. This will bring you to the download page where you have to select a mirror site to start the downloading. It's highly recommended to select the mirror site on the server nearest to your location.

MICROSOFT WINDOWS users can download either the Windows Binary (a zipped file which needs manual extraction and installation) or the self-extracting Windows Installer. Unless you have a slow connection to the internet, downloading the installer is probably the best option. To use BURRTOOLS on a UNIX platform you have to download the Source files and compile the program on your system (see installation guidelines below). An OSX package is provided.

Installation of BurrTools

Microsoft Windows

If you downloaded the Widows Binary, just extract the file into the directory of your choice and the GUI is ready to be used. If you opted for the Windows Installer, start the executable and follow the instructions on your screen.

Mac OS X

For detailed installation instructions please refer to the manual or help files of your operating system.

Linux / Unix

These installation instructions just contain some hints for the compilation of BURRTOOLS. As BURRTOOLS requires a few not so widespread libraries it is not the easiest task to do this.

To install BURRTOOLS for UNIX you first need to make sure you have the following libraries installed: zlib, libpng, libxml2 and libxslt. These libraries are usually installed on every LINUX system. You just have to make sure that you have installed the development packages, otherwise it is not possible to compile a program that uses these libraries, but just start programs that use them.

Additionally the following libraries are required: flkt and xmlwrapp.

Fltk is the library used for the GUI of BURRTOOLS. It may be included in your LINUX distribution or it may not.

The problem is that we need a version of this library that is not compiled with the default switches. This library must be compiled with C++ exceptions enabled. If you don't do this the program will simply shut down when an internal error occurs instead of displaying an error message and making an emergency save. To compile flkt with exceptions enabled you have to do the following:

• Download and decompress as usual
• Run configure just as usual
• Remove -fno-exceptions from the file makeinclude
• Finish normally by calling make and make install

The last library, xmlwrapp, can be hard to find, so here is a link

This library is compiled and installed in the usual Unix way, read their installation documentation.

Now BURRTOOLS can be compiled and installed the usual way with configure, make, make install.

Files and Folders

After installing BURRTOOLS the following files should be on your system:

burrGui.exe	The graphical user interface (GUI) to create puzzle files for BURRTOOLS.
UserGuide.pdf	This user guide.
COPYING	A text file containing the GNU General Public Licence. This file may be deleted to save on disk space, but should always be included when sharing the program. Read it carefully before sharing or modifying the program.
AUTHORS	A text file containing information about the contributors to the development of BurrTools. This file may be deleted to save on disk space.
ChangeLog	An automatically created text file containing an overview of the changes made to the program since version 0.0.6. This file may be deleted to save on disk space.
NEWS	A more readable version of ChangeLog. Here all (more or less important) changes to the different versions are collected in a comprehensive list. This is probably the place to look for what changed when downloading a new version. This file may be deleted to save on disk space.
uninstall.exe	The uninstall program will only be added after installing BURRTOOLS with the Windows Installer.

Also a new folder, examples, is created. This subdirectory contains a few examples of existing puzzles that illustrate the capabilities and functions of BURRTOOLS. A brief overview of the examples is presented in Appendix A.

Concepts and Definitions

Before we start describing the functions of BURRTOOLS, let's synchronise our use of vocabulary and explain a few concepts that are crucial to the way BURRTOOLS works.

Definitions

Voxel

A voxel (volume pixel) is a space unit in the 3-D space. The shape of the voxels is defined by the space grid type. Currently BURRTOOLS supports cubic voxels, triangular prisms and tightly packed spheres. Each voxel has one of the following three states: Empty, Fixed (Filled) and Variable (→ Concepts). Additionally each voxel can also contain supplementary information in the form of colours that are attached to the whole or parts of that voxel. Currently BURRTOOLS can only attach one single colour to the voxel as a whole.

Spacegrid

The spacegrid defines the shape and orientation and arrangement of the voxels. Right now there are 3 space grids available in BURRTOOLS: cubes, prisms with a equilateral triangle as base, and tightly packed spheres. Spacegrids are always fixed and periodic. That means that a voxel in a certain position will always have the same shape and orientation. So a spacegrid defining, for example, all Penrose patterns is not possible because these are neither a fixed nor a periodic patterns.

Shape

This is a definition of a 3-dimensional object. Shapes are assembled out of voxels.

Piece

A piece is a shape that is used as a part of the puzzle.

Multipiece

Some pieces may have the same shape. BURRTOOLS requires you to tell it that two or more pieces do have the same shape, otherwise it will find all solutions with all permutations. So a multipiece is a piece that's used more than once in the problem.

Group (also Piece Group)

A collection of pieces (and/or multipieces) than can move with respect to each other, but cannot be separated from one another. Denoted with {}.

Result

This is the shape that the pieces of the puzzle are supposed to assume once the puzzle is assembled.

Problem

A problem in BURRTOOLS consists of a list of pieces and/or multipieces, a result shape and possibly some constraints. You can have more than one problem in a file, as it may be possible to have more than a single task with the same set of pieces (e.g. Piet Hein's SOMA CUBE). In other words, a problem is a statement about what to do with the pieces.

Puzzle

A puzzle is either a single problem or a collection of problems.

Identifier

A unique code to identify a shape, colour or problem. This consists of an automatically assigned prefix to which a custom name may be added. The prefix is already unique. It is a letter followed by a number. The letter is different for all items that required identifiers, e.g. it is S for shapes, P for problems and C for colours.

Assembly

An assembly is a physically possible arrangement of pieces (meaning the pieces do not overlap in space) so that the resulting shape is formed. It is not guaranteed that it is actually possible to get the pieces into the positions of the assembly without using advanced technologies like Star Trek beaming.

Solution

A Solution is an assembly with instructions how to assemble/disassemble the pieces.

Assembler

The part of the program or algorithm that tries to assemble the puzzle.

Disassembler

The part of the program that tries to find out how the pieces must be moved to assemble the puzzle. It does this by trying to disassemble an assembly. Some puzzles like PENTOMINOES don't require separate instruction how to assemble the pieces. It suffices to know where the pieces are in the assembly. Other puzzles require detailed instructions how to move the pieces to assemble the final shape. That is why the task of finding the assemblies and creating assembly/disassembly instructions are separated from one another.

Solver

A short name to refer to the assembler and disassembler as a unit or just one of these without specifying which one.

Concepts

As described above, BURRTOOLS works with shapes which are merely a collection of voxels that each can have either one of three different states: empty, fixed or variable. Particularly the difference between fixed and variable voxels has a great impact on the way the solver works and which assemblies are considered to be valid and which are not. Besides that, the validity of solutions can be further restricted by imposing colour constraints.

Voxel States

Empty

The empty state is rather superfluous as it can also be regarded as the absence of any voxel. It is just used in the result shape to indicate the spots that can't be filled at all (holes).

Fixed (or Normal)

The normal or fixed voxels need to be filled in the final result, otherwise it is not considered to be a valid assembly.

Variable

The variable state is used to instruct the program that for a particular voxel it is unknown whether it will be filled or empty in the final assembly. This is required for puzzles that have holes in undetermined places (like all the higher level six-piece burrs). All voxels that might be empty must have the variable state in the result shape. Right now the variable state can only be used in result shapes and the solver will pop up an error message whenever it encounters a variable state in a normal piece.
Later on variable voxels might be used in piece shapes as well to define voxels in the shape that the program might alter to create interesting puzzles.

Colour Constraints

Colours allow you to add constraints to the possible placement of pieces. This is done by assigning a colour to one or more voxels of the piece(s) and the result shape (→AddingColour). Then you can set some colour placement conditions for each problem (→ColourConstraints). The program will place pieces only at positions that fulfil the colour conditions defined.

These colour conditions currently allow the definition of what coloured voxels of the pieces may go into what coloured voxels in the result shape. The default colour is special: it always makes a color match. Voxels in a piece that are in the default colour fit everywhere and default coloured voxels in the result shape can accommodate any piece voxel, independent of its custom colour.

Currently the assigned colour is interpreted as painting the whole voxel with this colour, but in the future more advanced possibilities for colouring and conditions may be added.

Notes for PuzzleSolver3D Users

BURRTOOLS was initially very much based on PUZZLESOLVER3D by André van Kammen but, by now has diverged quite a bit from that. We strongly advise you to read this user guide since there are some features in BURRTOOLS that work somewhat differently to their counterparts in PUZZLESOLVER3D and there are also some functions that PuzzleSolver3D doesn't have. Below are the most prominent differences that need your attention:

1. BURRTOOLS doesn't handle holes automatically as PUZZLESOLVER3D does. This may at first sound like a disadvantage but in fact it isn't. Unless you select 'Outer limits of result must be filled' on the solve tab, PUZZLESOLVER3D treats all cubes of the target shape as cubes that might be filled but don't need to be. But knowing which cubes must be filled speeds up the search process. The more there are of these (as compared to the total number of cubes), the faster the solver will run, as fewer possibilities are left to test. BURRTOOLS requires you to specify exactly which cubes in the result shape must be filled and which ones may be empty.
2. The BURRTOOLS solver doesn't automatically detect multiple identical pieces. You need to specify if a piece is used more than once. If you just copy them the way you do in PUZZLESOLVER3D the program will find way too many solutions. For example, with Bruce Love's LOVELY 18 PIECE BURR it will find nearly 40,000,000 times as many solutions as there really are. So be careful.
3. BURRTOOLS allows you to define multiple problems in a single session. So you can, for example, save all the SOMA CUBE (Piet Hein) problems within one single file.
4. BURRTOOLS has no limits to the number and size of pieces. You can have as many pieces as you want and they are not confined to a grid of 24x24x24.
5. There is no limit to the number of possible positions for the pieces. So BURRTOOLS won't stop and complain about too many placements. As long as your computer has sufficient memory the program will merrily continue working - even if it would take longer than the universe exists - to complete the search.
6. BURRTOOLS supports another gridspace besides the cube space supported by PUZZLESOLVER3D. This allows the design and analysis of completely new puzzles
7. BURRTOOLS knows piece ranges, which enables you to search for puzzles and not just solve them.

Importing PUZZLESOLVER3D files

BURRTOOLS has capabilities for importing PUZZLESOLVER3D files. So there's no need to redo your designs from scratch, although some postediting may be required because of the differences in handling duplicates of pieces and holes in the puzzle.

There are 2 possibilities for the holes. Depending on whether the option ``Fill outer Cubes'' is enabled or not when you solve the puzzle with PUZZLESOLVER3D, you must either make the inner cubes of the result shape or the whole shape variable if you want to get the same results with BURRTOOLS. This can be done with the tools described in section ConstrainingTools. With these tools you can make a shapes inner or outer cubes variable.

The duplicate pieces are handled automatically. BURRTOOLS adds all shapes to the new puzzle but does not add duplicates to the problem instead the counter for the original is increased. The unused shapes are marked as unused and can be deleted if they are not required.