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 :

Blank/01R00000101
Nine Patch/03R00000101R01000101R02000101R00010101
R01010101R02010101R00020101R01020101R02020101

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.

Rectangle

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).

Triangle

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.

CurvedTriangle

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.

PolarCoordinates

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).

IntersectCoordinates

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 :

Nine Patch/03[R00000101R01000101][R02000101R00010101]
[R01010101R02010101][R00020101R01020101]R02020101

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) :

Nine Patch/03T10[R00000101R01000101]T30[R02000101R00010101]
T40[R01010101R02010101]T80[R00020101R01020101]T60R020201

Summary – Quick Reference

File

Sequence of Block Definitions, one per line.

Block Definition

Block Name/Grid Size + Shape Definitions

Grid Size : Number with 2 digits. Example, for Nine Patch, grid size is 3 :

“Nine Patch/03….”

Shape Definitions

Sequence of groups of characters, starting with letter “P”, or “C”, or “R”

“P” is for Polygon

“C” is for Circle

“R” is for Rectangle

Rectangle

“R” + X (2 digits) + Y (2 digits) + W (2 digits) + H (2 digits)

– X, Y left top corner point of the rectangle

– W, H are the width and height of the rectangle, in grid units

Circle

“C” + X (2 digits) + Y (2 digits) + R (2 digits)

– X, Y centre point coordinates

– R radius in grid units.

Polygon

“P” + sequence of points (number of digits vary). See the Point section below.

Example when all points are specified with the Cartesian coordinates :

“P010201030101”

which is a triangle with points (1,2), (1,3), (1,1)

Group Of Shapes

Start a group with “[“, include all shapes, end with “]”

For example “[P010000010000R03030202]”

A group of shapes is an aggregation of shapes which behave as a single shape . When the pattern is loaded in the block design view, taping any shape of the group fills the entire group.

Greyscale Color

A colour is defined with the letter “T” + 2 digits (range from 0 to 99)

– 0 = white

– 99 = black

Precede the beginning of any shape, or group of shapes.

Point

Cartesian Coordinates

2 numbers, 2 digits each – x=12, y=1 –> “1201”

Polar Coordinates

“D” + Circle Centre + Radius + Angle

Circle Centre : 2 numbers with 2 digits each.

Circle Radius : 1 number with 2 digits

Angle : measured relatively to horizontal axis (clockwise) with 4 digits.

Example : Circle centre at x=2,y=3, circle radius : 5, Angle : 270 degrees

—> “D0203050270”

Valid only in the polygon shape definition.

Intersection of two lines

“V” + X1 (2 digits) + Y2 (2 digits) + A1 (4 digits) + X2  (2 digits) + Y2  (2 digits) + A2 (4 digits)

X1, Y1 = point coordinates on first line

A1 = Angle of first line clockwise from the horizontal axis

X2, Y2 = point coordinates on the second line

A2 = Angle of the second line clockwise from the horizontal axis.

Valid only in the polygon shape definition.

Fractional Representation (for Cartesian coordinates)

“G” + numerator (2 digits) + denominator (2 digits)

Can be used for any coordinate (X and/or Y) in the polygon shape only. Can also be used to specify the point of origin for the polar coordinates, and the points of the intersecting lines.

3 thoughts on “Adding New Blocks

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s