Adding New Blocks

1. In a Nutshell

Some of you have requesting the support for adding your own blocks, so here it is, in this new release of Quilt Wizard !

New blocks can be added to the application by writing a block definition file, and syncing it with the application via iTunes. There is currently no tools to assist you in writing the definition file, however, the remaining part of this article shows you how to do this. There will be in the future a graphical tool to easily design new blocks; in the mean time, some of you may be indeed skilled enough to go thru writing manually a definition file.

You probably wonder why this is done this way, and not from a graphical user interface within the application itself; the answer is fairly simple : to keep the whole application ease of use. In the long run, editing blocks outside of the application is the model that is going to be the most useable, and that will facilitate design exchanges among the quilters community.

So, the steps to customise the application are :

1) Write a definition file which contains one or more block definitions

2) In iTunes, with your device connected, go to the App tab, and in the bottom section of the page, locate “File Sharing”. In the left panel of this section, locate the Quilt Wizard application and select it.

3) With the Finder application, locate your definition file, drag and drop it into the left “Documents” panel, while Quilt Wizard is still selected.

The file will be automatically synced with the application, or will be if you launch a synchronisation manually (Sync button at the bottom of the page).

Once the file has been processed by the Quilt Wizard application, it is removed from the application Documents, and therefore will no more be listed in the “Documents” panel.

4) Launch the Quilt Wizard app on your device, select a quilt, then switch to the Block design tab, tap the “+” button to add a new block, your new blocks should appear now in the list.

Note that the synchronisation can be made while the application is active, and the new block templates will appear while the block menu is displayed.

If the new blocks (or some of them) do not appear in the list, then the definition is probably invalid, in which case the application drops it silently.

2. The Block Definition File

In order to edit a definition file, you will need to be familiar with the format of plain text files. If you are not, then you may want to ask around expert friends that can do this for you.

You also need the proper editor for this task, one that does not add formatting data in the file. On MacOS, please use TextEdit in the “Plain Text” mode. On Windows, use the Note Pad, or equivalent.

A file is composed of lines, each line is a definition for a block. A line is a consecutive sequence of characters, until a NewLine character is reached (when you hit the Return key in your editor).

Here is an important key point to know and understand : the Newline character is different on MacOS and Windows; Quilt Wizard is compatible with MacOS newlines. An editor I recommend to use on windows is NotePad++. With this editor, you can configure, or convert, your file to MacOS format. (If you want to know more about the Newline, please have a look at http://en.wikipedia.org/wiki/Newline ).

Here is an example of a definition file below, with two block definitions :

Note that there seems to be a third line above, but this is just the second line which wraps to the next.

A block definition (the line) is composed of :

– A name

– The size of the block grid

– A list of Shape definitions.

The name of the block always comes first and ends with a “/”. This means that a block name can’t include a “/” character. So you see in the definition above that the first block name is “Blank” and the second block name is “Nine Patch”.

It is followed by the block grid size, it is a number with two digits, therefore it’s maximum value is 99. All numbers in the block definition are plain integers, and the grid is used as scale factor to bring fractional numbers to an integer value. Let’s have a look at the Nine Patch example. The pattern is subdividing the space into 3 equal parts horizontally, and vertically, therefore it is natural to choose a grid of 3×3. Since supported blocks are square, we just put one number after the name : 03 (it has to be 2 digits). Then, each line, or point in the pattern all fall into a grid position : 0, 1, 2, or 3.

As you can see, the grid size for the “Blank” block is “01” : it is just one square that fills the whole of the block surface.

So here we go, so far we have “Blank/01” and “Nine Patch/03”. The remaining of the line is a sequene of shape definitions. In these example above, there is only one type of shape : Rectangle. There are other types, and they are explained more in detailed further on. A Rectangle definition always start with the letter “R” and is followed by 4 numbers, with 2 digits each (so in total 8 digits). The two first numbers are the top left corner coordinates of the rectangle within the grid. The first number is the coordinate on the X axis, the second number is the Y axis, as shown in the diagram below. The next numbers are the size of the rectangle, starting with width, and following with height, still relatively to the grid dimensions. So for the “Blank” block single shape, a rectangle, the top left coordinates are x=0, and y=0, and the dimensions are width=1 and height=1, therefore this gives us the shape definition : “R00000101”. And the block complete definition :

“Blank/01R00000101”

The diagram below shows the middle rectangle properties of the Nine Patch block. The definition for this rectangle is : “R01010101”, that is x=1, y=1, width=1, height=1.

3. The Shape types

The list of all shapes are :

– Polygon, it starts with the letter “P”

– Circle, it starts with the letter “C”

– Rectangle, it starts with the letter “R”

They are all detailed below.

3. 1 The Polygon Shape

The polygon shape as its simplest is a collection of line segments, where the end point of the last segment is the same as the start point of the first segment, and therefore, the last point coordinates are omitted.

So in case of just line segments, a polygon is defined by the letter “P”, followed by pairs of numbers, for each point coordinates.

The definition of the triangle shape below ( a polygon with 3 points) is “P000001000001”, that is the sequence of points with coordinates : (0,0) – (1,0) – (0,1).

This definition covers most of the blocks existing in nature, but not all. Some patterns have curved shapes – but not necessarily a full circle -, and sometimes points are not necessarily pinned to a grid.

Curved Shapes

In the previous polygon definition – (0,0) – (1,0) – (0,1), each pair of coordinates would constitute the sides of the rectangle, that is the shape navigates from (0,0) to (1,0) in a straight line, then goes to (0,1) in a straight line, and finally (this is implicit) to (0,0). In order to change the shape into a curved line – in our case we only support arcs – new definitions are inserted between the point coordinates, which defines how the shape travels to the next point. The only values that are needed to define an arc between the two point is the Radius of the circle into which the ac belongs, and wether the navigation is clockwise or anticlockwise . A clockwise arc is defined by the “B” letter, and an anti-clockwise arc is defined by the letter “W”, it is followed by the radius of the circle on which is inscribed the arc in a 2 digits number, such as “B02”, a clockwise arc with Radius 2.

Let say that the second segment of the polygon for the example above is a clockwise arc with a radius of 2, then the definition will become : “P00000100B020001” , which will produce the following shape below.

Now, in order to make this block functional, you’ll have to define, for example the complementary shape that start from point (0,1), moves to point (1,0) with an anti-clockwise arc with radius 2, then moves with straight lines to (3,0), then (3,3) and finally (0,3) : “P0001W020100030003030003”. Thus the Whole block definition is :

“Curved Example/03P00000100B020001P0001W020100030003030003”

Different ways of specifying a point location

Not all blocks can be pinned down to a grid, how finest the grid can be. It is because they follow a different pattern than a square grid; for example, with the Dresden block, most points are aligned on circles. While for the Pineapple block, points are all positioned on lines in a 45 degrees angle intersecting with horizontal or vertical lines.

There is also another case where though most of the points can be located in a grid, a handful of points are still falling out, and that would require to increase the size of the Grid (and therefore the resolution of the grid), and even this sometimes is even not possible. In these particular cases, there is a way of specifying the X and/or Y coordinates using a fractional representation.

Polar Coordinates

in the polar coordinate system, a point is located as a distance from a reference point (the origin) and the angle with the horizontal line. In the picture below, Radius is the distance of the point from the origin, and Angle is measured clockwise from an horizontal axis going thru the origin, to the line joining from O to P.

You start a coordinate representation in the Polar Coordinate with the letter “D”. It is followed by 10 digits : the coordinate of the origine (O) (2 digits for location on X axis, 2 digits on Y axis), the Radius (2 digits) and the angle is 4 digits measured in degrees. For example, let say the origin is at x=1 and y=1 (value 0101), the Radius is 2 units (value 02), and the Angle is 3o degrees (value 0030), then the resulting Coordinates definition is : “D0101030030”.

To specify the location of the point of origin, you can also use the fractional representation for all or one of the coordinates.

Intersection of two lines

The location of the point is determined by the intersection of two lines. Each line is specified by a point location the line goes thru, and the angle of the line relatively to the horizontal axis (navigating clockwise).

In the picture above, the point is at the intersection of two line : first line runs from point (0, 2) at an angle of 150 degrees. The second line runs from point (0,1) in a vertical direction which is an angle of 90 degrees.The definition for this representation starts with the letter “V” followed by a pair of line definitions. A line definition is composed of the definition of a point location on the line, and the angle of the line with the horizontal as shown in the diagram above.
In this example, the first line is : (point) “0200” + (angle) “0150” , the second line : (point) “0100” + (angle) “0090” with leads to the point definition :

“V020001500100090”

To specify the location of the points the lines go thru, you can also use the fractional representation for all or one of the coordinates.

Fractional Representation

To specify values which are not integers, you can use instead a fractional representation, by specifying two values : the numerator, and denominator. So if the X coordinate of the point is for example at 2 + 3/4, then you can represent it with 11/4. The definition starts with “G”, the numerator is represented with 2 digits, and the denominator by 2 digits, so our representation for this example is : “G1104” (just for the X axis). If the point Y value is 2, then the entire representation for the point is “G110402”. You can also use a fractional representation for the Y value if it is not an integer, of course.

3. 2 The Rectangle Shape

The rectangle definition starts with the “R” letter, and is followed by 8 digits :

– 4 digits for the left most top corner. The first 2 digits are the X coordinate in the grid, the last 2 digits are the Y coordinate.

– 2 digits for the digits, measured in grid units.

– 2 digits for the height, measured in grid units.

3. 3 The Circle Shape

A circle definition starts with the letter “C”, and followed by 6 digits :

– The coordinates, in the grid, of the circle centre : 2 digits for the X coordinate, 2 digits for the Y coordinate.

– 2 digits for Circle Radius.

Example : a circle with radius 1 centred on (x=2,y=3) : “C020301”

4. Grouping Shapes

There are many blocks whose pattern are identified by the way the fabrics colours are assembled. As an aid to fill the block, shapes are grouped together to form a new shape; this way, tapping one of the shape in the group will fill all the shapes in the group. To do so, just enclose a group of shapes between the letters “[” and “]”.

Here is an example where the groups of two rectangles are grouped together, except the last one which is left alone :

5. Give it a Tone

As a design help, some blocks are pre-filled with a colour in the grey scale, or tone. A tone range is between 0 and 99, and is coded with digits. 0 is white (the default), and 99 is black. In order to colour a shape, just precede it with the letter “T” followed by the coded tone. If you want to colour a group of shapes, precede the “[” opening group with the sequence. Here is the Nine Patch example augmented with the colour information (colours : 10, 30, 40, 80, 60) :