HexMandala, version 1.4b
(The 'b' in the version indicates that this is a beta version. The program
does all of the things it should do but it is not bug free. Which program is!
Have fun with it anyway, and please report bugs to me.)
1. About HexMandala.
2. How to use.
2.1 The menu.
2.2 The icon bar.
2.3 The popup menu.
2.4 Colour schemes and configuration file.
2.5 Colour values.
2.6 Colour editing.
3. System requirements.
4. Source code.
4.1 Known problems.
4.2 Change log.
5. Copyright and other small printings.
1. About HexMandala.
====================
This program generates hexagon based figures that reminds me to a mandala,
hence the name. Based on a given text of at least 3 characters (only letters,
no digits or spaces) a start value for the hexagon figure is calculated. A set
of colours is used to fill in the hexagon.
On calculating the image the program uses the folowing algorithm.
1. From the name calculate a 'start' value.
2. From the start value, generate an image.
The name is mirrored to the a palindrome. E.g. 'name' becomes 'nameeman'. The
next step is to resuce the name to three digits by compacting the name, Each
two characters are assigned to a digit, 'a' = 1, 'b' = 2, etc. To reduce the
name two characters next to each other are contracted to one value. If that
value is larger than 10, the individual digits in the sum are contracted again
until a value below 10 in archived. E.g.: Assume the name is ´Eazy´.
Mirror the name: 'EazyyzaE'
Converted to decimal values this is ´5 1 26 25 25 26 1 5´
Then repeat until only three values are left: add two neighbouring values to
get one new one.
1)
5 + 1 = 6
1 + 26 = 27, 2 + 7 = 9
26 + 25 = 51, 5 + 1 = 6
25 + 25 = 50, 5 + 0 = 5
25 + 26 = 51, 5 + 1 = 6
26 + 1 = 27, 2 + 7 = 9
1 + 5 = 6
2)
6 + 9 = 15, 1 + 5 = 6
9 + 6 = 15, 1 + 5 = 6
6 + 5 = 11, 1 + 1 = 2
5 + 6 = 11, 1 + 1 = 2
6 + 9 = 15, 1 + 5 = 6
9 + 6 = 15, 1 + 5 = 6
3)
6 + 6 = 12, 1 + 2 = 3
6 + 2 = 8
2 + 2 = 4
2 + 6 = 8
6 + 6 = 12, 1 + 2 = 3
4)
3 + 8 = 11, 1 + 1 = 2
8 + 4 = 12, 1 + 2 = 3
4 + 8 = 12, 1 + 2 = 3
8 + 3 = 11. 1 + 1 = 2
5)
2 + 3 = 5
3 + 3 = 6
3 + 2 = 5
'5 6 5', three values, done.
This form of calculation is known as 'modulo calculations', see wikipedia for
more details. This particular form of modulo calculations uses the basis:
x (+) y = (x + y) modulo 10
where (+) is the modulo addition operator.
Table of modulo addition
| 0 1 2 3 4 5 6 7 8 9
-+------------------------------
0| 0 1 2 3 4 5 6 7 8 9
1| 1 2 3 4 5 6 7 8 9 0
2| 2 3 4 5 6 7 8 9 0 1
3| 3 4 5 6 7 8 9 0 1 2
4| 4 5 6 7 8 9 0 1 2 3
5| 5 6 7 8 9 0 1 2 3 4
6| 6 7 8 9 0 1 2 3 4 5
7| 7 8 9 0 1 2 3 4 5 6
8| 8 9 0 1 2 3 4 5 6 7
9| 9 0 1 2 3 4 5 6 7 8
One small remark (with a great influence): The value of '10' is arbitrary, any
value will do. That is the basis to offer different values for the number of
colours to select from.
Minor adjustments are needed to get this calculation suited for the basis of
what we need. What we need is for a and b to calculate to the final result in
one step is to deduce one from the initial sum but to add one to the final
result or:
The repeated adding which is used in the example of 'Eazy' can be captured in
a function f(x, y)
(1) c = f(x, y) = (x + y - 1) modulo 9 + 1
With this function no repeated calculations are needed, we get the end result
in one go.
Example: from 1 + 26 = 27, 2 + 7 = 9
c = f(1, 26) = (1 + 26 - 1) modulo 9 + 1
= 26 modulo 9 + 1
= 8 + 1
= 9
This will give nice and very metrics images. Having a closer look at f(x, y)
there is a term 'x + y'. Both variables, x and y have the same impact. What if
we put a constant factor in this equation for both x and y and change the
definition of f to
(2) c = f(x, y) = (a*x + b*y - 1) modulo 9 + 1
With a=1 and b=1 we have the original definition f from (1) again. This will
give asymmetric images once the value of a is not equal to b. One more
alteration is possible, given in (3) below. That is the function implemented
in HexMandala.
(3) c = f(x, y) = ( (a*x + b*y)^n - 1) modulo 9 + 1
The values for a, b and n can be specified in the configuration file (see
below) in the application section.
For using (1): (a, b and n not used)
[Application]
Calculation=x+y
For using (3): (The case with a=2 already give very different pictures.)
[Application]
Calculation=(ax+by)^n
a=2
b=1
n=1
2. How to use.
==============
No installation is required for HexMandala. It is possible to run the program
from any location.
There is one prerequsite (for now). The program uses 'Visual basic PowerPack'.
This is not installed as a standard part of windows. If it is missing (the
program will not start) then download it from Microsoft, the URL for the
Visual Basic Power Packs 10.0 is:
http://go.microsoft.com/fwlink/?LinkID=145727&clcid=0x804
Start the program, a diagram based on de name 'HexMandala' is displayed.
Resizing the window will trigger the program to recalculate the image in an
different size. Most settings, like the name, height, colours etc will
trigger a recalculation of the image. You should always have an image based
on the latest options you have added or changed.
Note: While on a new PC this is 'nice to have', on an old PC with less capacity
this might take some time each time you change a setting. In this version
it is not (yet) possible to disable the 'automatic' recalculations.
Tip: Use colour set 'White' and a grid to make a blanc sheet with a hexagon.
Tip: Select the colour set, then use the mouse wheel to scroll through all
available sets.
Tip: Scrolling works also on the Height, Colours and Offset fields.
2.1 The menu.
-------------
On the top there is a menu bar with the following options.
[File] [Colours] [Help]
[Save...] [About...]
[Configuration...]
[Save...] This will store your image to file.
[Colours] This will open the colour list editor window.
[About...] Details about the program, version number etc.
[Configuration...] This will open the configuration form.
There is not much on the menu. Anything with the menu bar can also be done
with the icon bar, just below it or with a left-click menu on the image.
The Icon bar.
-------------
From left to right you see the following items on the icon bar.
- Name The name used for the image, only letters are allowed,
no spaces or digits, e.g.: "HexMandala"
As an alternative, three digits seperated by a comma
can be used to inject a seed direct, e.g.: "5, 8, 8"
- Height Number of triangles from the middle to the top of the
hexagon.
- Colours Number of colours to use from the colour set.
- Colour set Name of the colour set to use.
- Grid Drawing a grid (or not) for the triangles in the hexagon.
- Colour offset To cycle through the available colours.
- Calculate Force the program to (re)calculate the image. (at the far
right of the bar).
2.3 The popup menu.
-------------------
Left clicking on the image will produce a popup menu with the following items.
- (re)calculate calculate the image, same as icon bar entry 'Calculate'
- Save... Save to file, only available when there is an image.
2.4 Colour schemes and configuration file.
------------------------------------------
While the icon bar gives you the most basic control over image generation in
the sense of name, size and number of colours to use, the program does not
(yet) give you any control over the colour scheme itself. This is done in the
configuration file.
The configuration file is available at the same location where the executable
is located. It has the same name as the executable and will have the file
extention ".ini". It is a plain text file which you can view (and change) with
any simple text editor.
Note: Don't use sophisticated editors like 'Word' or 'Wordpad', it will make
the configuration file unreadable for the program. Use a simple editor
like 'Notepad'
For the following text I assume you have the file 'HexMandala.ini' open in
'Notepad'.
A .ini file is a structured test file of a number of sections, each with a
key/value pair. The start of a section is recognisable by the section name
between brackets ('[' and ']'), e.g.: [Application]. A section runs to the
start of a new section (or the end of the file).
Each section has lines with key/value pairs, the part before the '=' sign is
the key and the part after the '=' sign is the value.
So much about the .ini file organisation. Let's have a closer look on the
content of HexMandala.ini for now.
On creation of a new .ini file by the program is will have the following
secions:
[Application] Application settings.
[Calculation] Details on how calculations are done.
[Image] Settings related to the image size.
[ColourSets] A colour sets available to the program.
[Primariy], [Basic], [Blues], [Skye], ...
Some colour sets available 'by default' to the program.
[Colours] A list of all 140 known colours 'by name' to the program.
This section is not used by the program, it is a reference for
you.
In [Application] there are a number settings related to values that the
program is using.
Height=25 The Height of the hexigon (in triangles from the center to the
top of the hexacon that the program will use when it starts.
Colours=16 The number of colours to use (even if the colour set has more
colours available).
The [Calculation] section sets the way calculations are done.
Formula=...
a=...
b=...
n=...
Information about the formula used for calculations.
The default formula is f(x,y)=x+y, acceptable values for
Calculation= are "x+y" and "(ax+by)^n". If the values for a, b
and n is not given a default value of 1 is used.
Section [ColourSets] holds a list of available colour sets and the current
selected colour set. The list of colour sets is a sequence of names separated
by a ';'. e.g.: ColourSets=Primary;Basic;Blues;Skye
Each colour set in the list must also have a section with the same name. This
list is used in the selection list on the icon bar for colour sets. If you
want an extra colour set add the name for it to this list and create a section
for the colours in it.
The image is readjusted each time the window of the program is resized. Saving
the image can rerult in any format. With the setting 'fixed=true' in section
[Image] this behaviour is changed and the Width and Height setting in the same
section is used to recalculate the image fitting the hexagon to an optimal
size as indicated by Width and Heigth.
2.5 Colour values.
------------------
As I told you, each colour set must have a section for it. In this section all
the colours are specified. The specification is numbering the colours from '1'
to the last. At least two colours needs t be available in a colour section,
otherwise it is useless. A maximum of 255 colours can be defined in a single
colour set. The definition of colours needs to be consecutive, any gap
between n, n+1, ... will cause a stop to read the rest of the colour set. On
duplication of colour definitions it is not predictable which colour is used.
An example of a colour section:
[Basic]
1=Red
2=Green
3=Blue
4=Yellow
5=Magenta
6=Cyan
7=CornflowerBlue
8=Crimson
9=Gold
This colour section has nine colours defined.
It is possible to define colours in two formats, by name or by value.
Microsoft has defined a list of 140 'standard' colours which are known 'by
name'. The names are available in section [colours]. The other option is to
use the 'ARGB' value for the colour. The 'RGB' part is 'Red', 'Green' and
'Blue'. 'A' stands for 'Alpha' or 'transparancy'. Alpha=00 is totaly
transparant, invisible, and Alpha=FF is total opaque, totally blocking
anything behind it.
An example of a colour section using 'ARGB' definitions.
[Blues]
1=#FF000010
2=#FF000020
3=#FF000030
4=#FF000040
...
With named colours you have a nice control over the colours in a colour set,
with 'ARGB' you can go to a refined control. Note of warning: When using
'ARGB', keep the A-part at 'FF' (see further for an explanation) and also keep
in mind that small changed between two values are hardly notable for user.
(e.g. 'FF010202' and 'FF010204' are perceived as the same colour by users.)
While the transparency/opacacy value was introduced by Microsoft, it was never
uses. Always set it to 'FF'
Note on 'ARGB' values:
Values are marked with 'hexadecimal' values. This is a system not using the
numbers 0..9 for a digit (10 values per digit) but the numbers 0..9 and A..F
(16 values per digit). See wikipedia for a good introduction if you are
unfamiliar or unknown to the hexadecimal numbering system.
An 'ARGB' value has four values, each using to characters in the value. From
left to right it are 'alpha', 'red', 'green' and 'blue'. Ecch value has a
range from 0..FF (0..255 in the decimal system.) Each value represents the
intensity of the colour. A value of '00' is for 'no value at all' or in simple
words 'black for this colour'. And a value of 'FF' (which is 255) for 'maximal
available' or in simple word 'totally available for this colour' or 'fully
saturated' .
2.6 Colour editing.
------------------
It is possible to edit the colour scemes in the .ini file, but this is not the
most easy way and is sensitive to mistaces. Another way is to use the
'Colours' option from the main menu bar.
Menu item [ Colours ] opens a form witht on the left side a list of available
colours, on top the selected colour (from the left side) to change and below
that the top half of the hexagon. All triangles in the hexagon are coloured
and numbered to make it easier to select the correct colour from the left
side. (Note: Changes in colours on the top of the form are not duplicated on
the left side until another colour is chosen.)
At the top of the form is the colour scheme name. If it is changed then
effectively it creates a new entry in the .ini file. This way it is possible
to have new colour schemes.
Right to the colour scheme name there is a number for the height if triangles
of the main image on this form. This image shows a part of the whole image
with the center at the bottom line in the middle and at the top the bull with
of the horisontal part of the full image. The number of triangles from bottom
to top can be changed by the number next to the colour scheme name.
At the left side is a list of all available colours in this colour set. At the
bottom of this list there are navigation buttons for selecting, adding and
deleting colour entries.
At the top of the triangle image are the settings (for editing) of the current
selected colour. Clicking on the coloured square will open the standard
windows colour selector form. It is also possible to direct change the RGB
value of a colour or to select a named colour.
If you change the RGB value for a colour a smaller rectancle can appear with
the nearest named colour.
Tip: Changing the radio button from "R-G-B" to "Named" will select the current
name as the new value. This is a quick way of getting near a named colour
and then select it.
Note: Changes in the colour values are stored immeadiately but the list on the
left side is only updated when a new colour (from the list) is selected.
The [ Save ] button stores all changes to the .ini file and updates the main
form colour list. The [ Cancel ] button just dumps all changes
3. System requirements.
======================
The program runs on a windows PC. It was developed on a Windows 7 (64 bits)
and should also work on a 32 bit version. The program is tested on Windows 10
and apart from some screen layout glitches there are no problems with it. Any
windows version starting from 2000 should be fine but is untested for.
The program was developed for .NET 4.0, if not available on the target machine
download it for free from Microsoft Windows.
To run and use HexMandala you need the following files:
- HexMandala.exe
- HexMandala.ini (Default settings is generated on the first run.)
4. Source code.
===============
The source code for this program is available under the Modified BSD License.
The source code is developed with Visual Studio 2010-SP1 in C#. No specific
Microsoft dependencies are known and the source code should also compile
without too many dificulties on Mono on a Linux system. But is this untested.
4.1 Known problems.
-------------------
- Dependency on 'Microsoft.VisualBasic.PowerPacks.Vs, Version=10.0.0.0
Not always available, temporary workaround: install it from
http://go.microsoft.com/fwlink/?LinkID=145727&clcid=0x804
4.2 Change log.
---------------
20151012, v1.4b:
- Limited (while painting) colours to number of colours in the colour set.
- Added f(x,y)=... to the main form to see how the calculations are done.
20151011, v1.3b:
- Colour count bug fixed (was introduced with v1.2a)
20151011, v1.2a:
- Can insert a seed in stead of a name.
- Added the configuration screen.
- Added a [calculation] section to the .ini file.
20151010, v1.1a:
- Added a 'height' counter for the image in the colour editor form.
- Resolved an issue with colour index offset in the colour editor form.
- Resolved issue of late index show up in colour list (in colour editor form).
- null pointer reference in colour editor form (Windows 10 only?)
20151010, v1.0a:
Initial release.
5. Copyright and other small printings.
=======================================
This source code is covered by the 3-clause license ("Revised BSD License",
"New BSD License", or "Modified BSD License")
Copyright (c) 2015, A.H.M Steenveld.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of the copyright holder nor the
names of its contributors may be used to endorse or promote products
derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
vi:tw=78
