Configuring Colorings in MagicTile
(for power users)

Overview

Note that this topic involves editing the MagicTile puzzle xml files by hand.

Colorings in MagicTile are configured by a set of "identifications" which apply to the central tile (the one that is white by default). Think of an identification as instructions to go from the central white tile to one (or more) of its copies in the plane.

Each identification has 5 tags that affect the outcome. Four of these tags are optional and may be omitted, but they must appear in the proper order when included. An example configuration with all tags included looks like this:

    <Identifications>
        <Identification>
            <EdgeSet>3:3:3</EdgeSet>
            <EndRotation>0</EndRotation>
            <InPlaceReflection>false</InPlaceReflection>
            <InitialEdgeSet></InitialEdgeSet>
            <UseMirroredEdgeSet>true</UseMirroredEdgeSet>
        </Identification>
    </Identifications>

You may include multiple Identification blocks within the root Identifications block.

Tag Descriptions and Examples follow. You may want to skip to examples, and refer to tag descriptions as needed.


Tag Descriptions

EdgeSet
This is the only tag which is not optional. It is a colon-separated list of CCW 0-indexed edges to reflect across, in sequential order. The total number of reflections is one more than configured here, because the initial edges to reflect across are configured separately (described below).

EndRotation
After all reflections have been done, this will apply a CCW rotation of the tile in-place. This is entered as a 0-indexed integer, which is multiplied by 2*pi/p to get the actual rotation amount.

If omitted, the default is 0.

InPlaceReflection
If true, the tile will be reflected in-place prior to any reflections across edges. This is useful if you need to make the total number of reflections even or odd.

If omitted, the default is false.

InitialEdgeSet
This configures the initial edges of the white tile to reflect across, also in a CCW 0-indexed fashion. It is different from EdgeSet in that you are not encoding sequential reflections, but setting up how many copies there will be.

The format is also a colon-separated list, but note that "a:b" here means something different than "a:b" means in the EdgeSet tag above. Here it refers to the starting reflection of two different copies. In the EdgeSet tag, it refers to multiple sequential reflections of one copy. These two tags work in combination. Let's say you had "0:1:2" configured for InitialEdgeSet and "3:3:3" configured for EdgeSet. This encodes 3 copies, whose entire edge sets are:

0:3:3:3
1:3:3:3
2:3:3:3

If omitted, the default is to use all initial edges. On a puzzle of heptagons, this is the same as "0:1:2:3:4:5:6", which leads to encoding 7 copies at once.

UseMirroredEdgeSet
This is a shortcut to auto-generate all the mirrored identifications internally. In the case of KQ, this means "3:3:3" EdgeSet also implicitly does the mirror reflections "4:4:4".

If omitted, the default is true, which doubles the number of copies encoded.


Example 1 - Klein Quartic Puzzle

    <Identifications>
        <Identification>
            <EdgeSet>3:3:3</EdgeSet>
        </Identification>
    </Identifications>

Here is a picture showing how a "3:3:3" EdgeSet and an omitted InitialEdgeSet tell the program to go from the central white tile to identified copies. Since reflections are done across all the initial edges (shown in green), this config represents 7 copies, each with 4 reflections.



But wait! UseMirroredEdgeSet defaults to true, so we actually get twice the number of copies.



This one simple xml block is therefore encoding 14 copies (at the first level of recursion). It is a very compact representation of a lot of copies!


Example 2 - The {4,4} 9-Colored Klein Bottle

We're going to focus on second identification in this tiling, which overrides all of the defaults!

    <Identifications>
        <Identification>
            <EdgeSet>2:2</EdgeSet>
            <EndRotation>2</EndRotation>
            <InPlaceReflection>false</InPlaceReflection>
            <InitialEdgeSet>0:2</InitialEdgeSet>
            <UseMirroredEdgeSet>false</UseMirroredEdgeSet>
        </Identification>
        <Identification>
            <EdgeSet>2:2</EdgeSet>
            <EndRotation>2</EndRotation>
            <InPlaceReflection>true</InPlaceReflection>
            <InitialEdgeSet>1:3</InitialEdgeSet>
            <UseMirroredEdgeSet>false</UseMirroredEdgeSet>
        </Identification>
    </Identifications>

Here's a pic showing what the second identification block is doing.



Notes:

• InitialEdgeSet has 2 items, so this configures two copies.
• The 2 reflections in the EdgeSet, coupled with the initial reflection, means there would be 3 reflections total. However, InPlaceReflection is true, which add another and brings the total number of reflections to 4. Since the number of reflections is even, the copies will be oriented in the same sense as the original white tile.
• In this case, UseMirroredEdgeSet was set to false, but it could have been set to true. Mirroring would result in identical results here.
  

See if you can trace out the effect of the first identification on your own. Are those copies oriented in the same sense as the original?


A few more comments

• Identifications are used to calculate a set of "isometries" internally, which are then recursively applied to all fundamental tiles. On very symmetrical puzzles like KQ, all tiles end up behaving identically. On less symmetrical puzzles, the effect of an isometry on the non-central tiles may be different.
• Here's how I think of the order of things going for an identification:
      InPlaceReflection -> InitialEdgeSet -> EdgeSet -> EndRotation
  And if UseMirroredEdgeSet is true, this whole pipeline repeats with mirrored values.
• I usually approach a coloring by adding identifications one at a time. Often, until you add enough, the tiling won't completely fill in. When you have too many identifications, colors will repeat too much, sometimes making the entire tiling white. It can be an iterative process to find working colorings.
• It’s good to have ‘ExpectedNumColors’ set to a reasonably low value when working on colorings (max value is 56).
• When making edits to config files, you can press F5 in MagicTile to get it to reload configurations.  That way you don't have to close/reopen the program while experimenting.
• Use the existing puzzles to guide your understanding.  You can copy an existing config to the config/user directory to get you started.  Be sure to change the 'ClassID' to something new and unique if you do this.

This doc is only a primer to help get you going. If you’d like anything added to this doc, or something clarified better, please let me know.

If you find a new coloring that isn't already included in MagicTile, send it to me so I can add it!

Roice