Knitter

Installation

Installation of Knitter should be straightforward for both Linux and Windows. The program depends on libxml2 and ODE. Both of these are distributed with the Windows and OSX installation, and they should be easily available for any Linux distribution you may choose. ODE may require manual installation. Check out the ODE user's manual if you need help. Linux distribution uses a standard configure, make, make install procedure.

The GUI

The GUI consists of three main parts. The first is the rendering window where the model is rendered. It starts off as a plain white box in the top left of the window. The second is the textbox where the pattern can be entered, and sits on the bottom of the window. The last part is the options panel, which is a series of tabs on the top right side of the window that allows the user to set some of the simulation parameters. Of course, there is also the menu along the top of the window.

Menu

Right now, only the File menu is really of any use. File->Open allows the user to open an existing pattern (check out the examples folder). Note that native Knitter .pat files as well as KnitML .xml can be imported. File->Save As... allows the user to save a pattern that's been typed in.

Rendering Window

The rendering window shows the current state of the knitting model. When the program starts, no model is loaded, so this area is blank. As soon as a model is created (either by specifying a pattern file using File->Open) or by manually typing in a pattern in the entry window below), the model will show up. If the 'Animate' box is checked in the options panel, then the model simulation will update in real time according to the simulation parameters.

Clicking on the rendering window has several effects depending on which button is used. Holding the left mouse button down allows the user to rotate the image around a central point. The center mouse button allows the user to scroll left and right. The right mouse button allows the user to zoom in and out. The control here is somewhat rudimentary; the UI for manipulating the rendered image is still being planned, so expect this behavior to change in future versions.

Note that there is currently a bug in the startup code that causes the rendering window to have an incorrect aspect ratio when the program first starts. The workaround for this is to resize the panel. Resizing the entire window itself may not be enough; the separator between panels must be moved to force this panel to recalculate the correct aspect ratio.

Entry Window

The white panel along the bottom is where a new pattern can be entered. For the most part, existing knitting patterns can be copied and pasted here, with a few modifications. Naturally, text descriptions of how large a piece should be cannot be directly translated into a form that Knitter can currently understand, but simple patterns should translate well. For example, if you were making a stockinette swatch with a 2x2 ribbed border, you might traditionally write this as

   Cast on 28 st
   RS: k 2 p 2 k 20 p 2 k 2
   WS: p 2 k 2 p 20 k 2 p 2
   Continue in pattern to desired length.
   

For anyone who hasn't done a lot of patterns yet, RS means right side (the nice looking side of stockinette), while WS means wrong side. We won't use the RS/WS notation, since Knitter doesn't really care which side it's on. This pattern translates pretty easily:

   sk fix(-10,0,0) co 27 fix(10,0,0)
   { 
     k 2 p 2 k 20 p 2 k 2 turn
     p 2 k 2 p 20 k 2 p 2 turn
   } 20
   

You'll notice that the bulk of the content is actually identical. The main changes are the following:

1. Added the 'sk' stitch instead of the first cast on
2. Added fix(x,y,z) to the first and last stitches of the first row
3. Added curly braces to indicate a repeat
4. Specified exactly how many times the repeat should occur

The first change was made because Knitter is very specific about the types of stitches being made. Technically, the very first thing you do when you start a pattern is to create a slipknot for the first loop (this of course does not apply to certain cast-on techniques like long tail). This creates a loop out of something not connected to the piece itself (the ball of yarn). That's opposed to the actual cast-on, which creates a loop from the previous loop.

The second change allows us to fix the pattern in space so that we can see it. It would be nice if the program could do this for us, but at the moment it can't, so we have to specify how exactly the piece should be "held". Think about this in terms of a wall hanging. If you were to hang your piece on the wall to display it, how would you do it? For flat pieces, two corner edges work well. These can actually be any two adjacent corners; the first and last stitch of the last row would work just as well. For pieces in the round, you'll probably want to support the piece by three nodes in a circle. Look at the examples swatch3.pat and buttonhole.pat to see how this can be done.

The third change allows us to specify repeats in patterns. Because curly braces are used instead of asterisks, these repeats can be nested. Portions of a pattern inside these braces are referred to as a 'block'.

The fourth change tells the program exactly how many times to repeat a particular block. Right now Knitter has no idea what the original pattern might mean for "desired length". Is the pattern for a swatch? A scarf? Knitter needs to know exactly what you want to do, so we have to tell it "make 20 rows" instead of "make some rows, it doesn't really matter how many".

There are many other parts of the language that aren't documented here. See the Knitter Language Reference for a more complete reference.

Settable Parameters

Several tabs allowing the user to change different parameters of the simulation sit on the top right of the window.

Stitches

This tab currently only contains the number of stitches per inch for the current pattern. This value is used when the model is created, so changing this parameter after the model already exists will not impact the model at all. Future versions may allow for this, but for right now this has to be set before the pattern is parsed.

Links

CFM and ERP have to do with the stretchiness and stiffness of the stiches. Check out the ODE documentation to see exactly how these combine, along with the simulation period, to produce the damping factor and spring constants. If you're not interested in exactly what these mean, feel free to play around with them to see how they impact the model. However, like the stitches per inch setting, these values are used when the model is created, so updating them after the fact won't impact the model at all.

These settings are not at all intuitive, but they've been put in the GUI for users to play around with them. When a good set of parameters is determined, these values will probably be hard-coded and these options will be removed. If, on the other hand, different sets of parameters make sense in different situations, these options may be generated internally, and the user-settable parameters will be something like 'stretchiness' and 'stiffness'.

Simulation

The simulation tab allows the user to control exactly how a single simulation step occurs. If 'Exact' is checked, then ODE uses a memory- intensive algorithm to solve the equations of the model. If 'Exact' is clear, then ODE uses a faster, less memory-intensive algorithm to iteratively get close to the correct solution. The lower the number of iterations, the faster and less accurate the simulation will be. If your model seems to be behaving very strangely or "vibrating", try increasing the iterations or try selecting 'Exact'. If your simulation is very slow, try lowering the number of iterations.

Other options here include the amount of model time to progress, and the amount of gravity imposed on the model. At some point in the future, the actual units of these values will be worked out and added to the GUI, but some code changes need to be made first. Until then, consider the numbers relative and unitless.

Stitches

The stitch library exists in a file called stitches.xml which is parsed when the program starts. The following stitches are currently supported (though adding new stitches should be straightforward):

• sk: Slip knot, generally the first "stitch" when casting on
• co: Cast on. Currently no distinction between different types
• k: Knit stitch
• p: Purl stitch
• k2tog: Basic decrease slanting right
• k2togtbl: Basic decrease slanting left
• m: Basic increase slanting left
• bo: Bind off

Examples

Several examples exist in the examples directory. Most of these are native Knitter patterns, but a few are KnitML XML files. Any of these can be opened from File->Open. One is Jonathan from KnitML's original sock design. Unfortunately, Knitter's KnitML support isn't good enough to completely render this design, but a considerable amount of stitches do get produced.

It should be noted that the way Knitter currently implements KnitML is by converting the KnitML file to a Knitter pattern file. The result is put in the same directory as the original. Since KnitML currently has no facility for pinning down certain nodes in space, all KnitML files will show up as blank screens when first rendered since they immediately fall off the screen due to gravity. To get these to render correctly, the KnitML files should be opened, the resulting pattern file edited to add the necessary fix() keywords, and then that file should be opened. Hopefully this will be fixed in a future version.