Hi! My name is Andrew Glassner and this is a quick-start guide to my online weaving program Luminescence.

Luminescence is a simplified and abstracted version of a real loom used for weaving cloth. You can set up the loom using patterns published in weaving books that are over 100 years old, or you can cook up exciting new designs of your own.

This document moves quickly. For more information on everything, take a look at the Further Reading section.

Quick Shortcuts

Super-Quick Start

Click on the Load Draft button near the top-middle of the screen and take a look at the built-in presets. To see more or less of the woven fabric, enter a larger or smaller number in the Fabric size box just above the fabric itself. If you want to see the threads, set Fabric Size to a value near 40 and turn on the Show threads checkbox (the checkbox is unavailable when Fabric Size is 100 or larger). You can click in the little checkerboard to the upper-right of the woven fabric, but no other graphics on the right side will respond to clicks (if you get a red square when you try to click in the checkerboard, then it's too small for interaction - choose a smaller number for Fabric size). You can also change the design of the fabric by altering what's in any of the five text boxes on the left (and then pressing the arrow to that box's right). Start by changing colors (you can probably guess at some reasonable color names for now), and try fiddling with some of the numbers. For now, keep all of your numbers in the range 1 to 8, but you'll probably still get crazy results! The text in those boxes uses a custom pattern-making language that probably looks cryptic to you now, but will soon become second nature.

Quick Start
Table of Contents
Overview of Luminescence
The Right Side: The Draft
From Input to Loom: Patterns
The Left Side: AWL Input (and Output)
Colors
Making Patterns: The AWL Language
AWL Concepts
The AWL Commands
Notes On Using AWL
The Rest of the Interface
Editing the Tie-Up
Saving and Loading
FAQ
Further Reading

Overview of Luminescence

Figure 1 shows Luminescence with the major components labeled. To create a piece of woven fabric, you type expressions in the AWL language (described below) into the five input boxes on the left. After you've typed an expression in one of the boxes, press the arrow to its right to copy the results onto the right side of the window.

Looms are sophisticated machines, and weavers have their own terminology for their art and their tools. In this document I'll discuss our simple loom and the process of using it to weave fabric using very casual language. See the references in the Further Reading section for more information on weaving and looms.

The model for our loom here is very simple. It has a row of colored threads above it and a column of colored threads to its right. These thread extend down and left into the fabric. To control which thread goes on top and which goes under as the cloth is woven, you use the grids of black and white cells around the fabric. The warp and its row of colors sits above, The weft and its column of colors sits to the right, and the tie-up sits to the upper right of the fabric. When a person actually weaves on a loom, these grids of black and white tell them how to physically set up the loom for each row of woven cloth, and then how to manipulate the loom and the threads in order to weave the fabric properly.

You can see from Figure 1 that the row of warp colors, and the column of weft colors, are just a single color throughout. This is a common feature of many designs, and it's a good place to start when you're learning. But you can weave with as many colors as you like. To see some examples, click Load Draft at the top and choose one of the tartan examples at the bottom of the list. To better see the warp and weft colors, try putting a value of around 100 into the Fabric size: field just above the fabric.

The Right Side: The Draft

The right side of the window is collectively called the draft. These checkerboards show you how your loom is set up, and the final fabric that results. These grids (and the two strips of colors) are created in response to the strings you type into the input boxes on the left hand side of the window. The fabric is automatically re-woven each time you change one of the input expressions. You can click in the tie-up in the upper right to turn cells on and off; no other elements of the draft are interactive. If you try to click on the tie-up and you get a red box, that means the tie-up is too small for you to edit. You can make it larger on the screen by reducing the size of the fabric: type a smaller number into the Fabric Size control just above the left side of the fabric.

Your job is to write expressions that create drafts that produce fabrics you like. So it's important to know how the draft turns into the fabric. Here's a crash course.

Think of the fabric as a grid. We want to know the color of each cell in that grid. We use the three grids around the fabric, and the single row or column of colors on the outside of the two larger ones.

First up is the grid on the right. We call that the weft. Each row of the weft is white except for exactly one black square. To the right of the weft is a column of colors, collectively called the weft colors. Imagine that each cell in the weft colors is a spool of a thread of colored yarn whose thread runs perfectly horizontally to the left, passing through each cell of the fabric to its left.

Next is the grid above the fabric. This is called the warp. Each column of the warp is white except for exactly one black square. Above the warp is a row of colors, collectively called the warp colors. Imagine that each cell in the warp colors is a spool of colored yarn whose thread runs vertically downwards, passing through each cell of the fabric beneath it.

Thus each cell in the fabric has two threads passing through it. We imagine that each thread is as wide as the cell, so one of them will have to be on top while the other is below it. The cell will take the color of the thread on top. To determine which thread is on top, we use the third grid.

The grid above and to the right of the fabric is called the tie-up. Unlike the warp and weft, the tie-up can have any arrangement of white and black cells (it can even be all white or all black, though that would make a pretty boring fabric). Unlike the warp and weft, you can click in the tie-up to change its pattern (as long as the cells are big enough on the screen).

So to color in the fabric, we only need to know which thread is on top in each cell. This process is illustrated in Figure 2. We start with a cell in the fabric, marked with a black outline.

The weaving algorithm. — Figure 2: Finding the color of a cell in the fabric.

Look directly to the right, and find the black cell in the weft for this row.
Look directly above, and find the black cell in the warp for this column.
Look above the black weft cell, and to the right of the black warp cell, to find a cell in the tie-up. If that cell is black, the warp thread is on top, so paint the cell with the warp thread's color. Otherwise, the weft thread is on top, so use the weft thread's color.

In the figure, we find that the cell marked in black ends up at a black cell in the tie-up, so we color this cell with the warp color that is directly above it. If the tie-up cell had been white, we'd instead use the weft color directly to the right of this cell. In this draft, all the warp threads are the same dark-blue color, so that's the color of this cell.

Although it's easy to state, understanding how the warp, weft, and tie-up interact to produce a design is anything but obvious! You'll find that as you experiment with these three grids, your intuition will grow, and you'll get better at predicting what a particular type of change will do to your design. But part of the pleasure of having a digital loom at your disposal is that it's easy to experiment, and experiment again! Just play and have fun, and see what you can discover.

But if you can't click on the warp and weft and their colors, how do you set them up? The answer is that the draft is created as a result of the expressions you type into the input boxes on the left hand side; we'll turn to those now.

From Input to Loom: Patterns

The trick to describing a draft is to create a pattern of numbers that identify which cells are to be filled in with black. You can then publish these numbers, along with or instead of a picture of the draft, and other weavers can then duplicate your design. Many weaving programs let you enter your warp and weft patterns by clicking on the cells of their grids (and we also allow that for the tie-up). But when your drafts get really big, that becomes a tedious and error-prone process. And if you want to tweak your design by, say, expanding one section somewhere in the middle, you'd have a ton of clicking to do.

So instead, we create these number patterns with a little language designed explicitly for that. We'll get into the language in the next section. Here, we'll look at how to take a list of numbers, like that created by the pattern language, and apply it to the draft.

The key thing to this process is how we name the cells of each grid. And each of the grids is different! That might seem crazy when you first encounter it, but it's a good scheme that has been used for over a century. Once you get used to it, you'll probably like it.

So let's dig in. Figure 3 shows how each grid is counted. Let's start with the warp, located above the fabric. Our rule is that each column in the warp has exactly one black cell. So we only need one number, telling us where in the column the cell is located. As the image on the right shows, we start counting the warp by going up along the rightmost column, then we move one step left and go up again, then one step left and go up again, and so on.

Looking at the pattern in the warp, we can see the rightmost column has its black cell in row 1, then moving left it's in row 2, then row 3, then 4, then we're back to 3, and we're back to 2. I want this little section to repeat, so I'll stop there. The pattern for the warp in this figure is 1 2 3 4 3 2. Note that I left the 1 off the end, so that I can just repeat the pattern over and over and the 1 doesn't get duplicated.

Two drafts. — Figure 3: We locate black cells in the warp (red) by going upwards, starting at the right and moving left. We locate black cells in the weft (green) by going to the right, starting at the top and moving down. The warp colors are filled in from right to left, the weft colors from top down. We fill in the tie-up (black) by going upwards, moving from the left to the right.

The weft appears to the right of the fabric. We follow a similar scheme, only here it's the row that has a single black cell. The rule for the weft grid is to start at the top row, and count from the left to the right. The pattern in this example is the same as in the warp, giving us the same pattern 1 2 3 4 3 2, which again is just repeated over and over as needed to make the fabric.

The warp colors are filled in from right to left, like the columns of the warp. In this example, our pattern is the colors Topaz (beige) and Grizzly (dark brown). So those two colors are placed, in order, from the right moving to the left, and then repeated as needed. The weft colors work the same way, only from top down. Here we're using BlueJeans followed by Gray18.

Finally, we have the tie-up. Because each cell in the tie-up can be either white or black, we need to somehow list every cell of our pattern. So we just make a big list of 0's and 1's, one entry for each cell in the tie-up grid. Luminescence follows the standard convention for drafts that 1 is black and 0 is white. If you use computer-based colors a lot this may feel backwards. It will make more sense if you think of someone in a pre-computer age, filling in a draft with a black ink on a white sheet of paper. If the draft says 0, the suggests doing nothing, leaving the cell white. If it says 1, then you fill in that square with your pen, turning it black. We count the tie-up starting in the bottom-left corner and going upwards. When we reach the top, we move one column to the right, jump down to the bottom, and start going up again. In this example, the tie-up pattern is 1 1 0 0 1 1 1 0 0 1 1 1 0 0 1 1. If you look at this closely, you'll see it's just the pattern 1 1 0 0 1 repeating over and over.

You'll be relieved to know that you'll very rarely need to count things out like this. Most of the time you'll be creating your patterns using the pattern-making language, and leaving all of this counting stuff up to the computer. But it does come in handy from time to time.

To summarize, the following list completely describes the draft in Figure 3, and thus also completely specifies the pattern of the fabric it leads to. If you want to share your draft with other weavers, this is all you need to give them, and it's all you need to know from them to recreate their drafts on your own loom.

Warp pattern: 1 2 3 4 3 2
Weft pattern: 1 2 3 4 3 2
Warp colors: Topaz Grizzly
Weft colors: BlueJeans Gray18
Tie-up: 1 1 0 0 1

All of these patterns are repeated as needed. The tie-up pattern, for instance, is repeated until the entire tie-up grid is filled in (if the tie-up pattern happened to be bigger than the grid, the excess would just be ignored). The warp and weft patterns, and their colors, are repeated until they're providing a value to every cell in the fabric at whatever size we want to make it.

Now that we know how lists of numbers let us build a draft, we'll see how to easily make big lists of numbers that lead to beautiful fabrics.

The Left Side: AWL Input (and Output)

To fill in the grids of the loom, we enter text expressions into the boxes on the left side of the window. When you've typed something into one of these boxes, press the big arrow button to the right of the box to update the loom. The fabric will be automatically updated using the new draft.

You create your expressions using a special pattern-making language called AWL (Andrew's Weaving Language). This site supports version 2 of the language, with new commands and features.

You can see the result of your expressions in the black and white cells of the draft, but sometimes it's more useful to see them in numerical form. At the bottom of the left column there's a text box with a multi-part button above it. Press the button to see the output from the input box you're interested in (when you press an arrow button, the output automatically displays the output of the expression you just entered). Note that this is strictly an output area; you can't type into this box.

Weaving Quick Start

If you're new to the system and you want to play around with the inputs before you learn the pattern language, that's fine; messing around is a big part of the fun. Just type the patterns you want in your loom right into each text box, and press the arrow to its right to copy that into the loom. The most important thing to remember is this: put spaces around each number or color name. For example, to recreate Figure 3, you'd type 1 2 3 4 3 2 into the Warp Pattern box. Note that each number is followed by a space, and there are no commas, periods, or other characters. Just numbers and spaces. You'd type the same thing into the Weft Pattern box. You can even type Topaz Grizzly into the Warp Colors box, because Luminescence knows those colors by name. Enter the weft colors and the tie-up, and you should get back Figure 3! If it doesn't match, use the fields above the fabric to set Tie-Up Width and Tie-up Height to 4. To exactly match the figure, set FabricSize to 10. To make more fabric (that is, a bigger swatch), just crank up the fabric size to something like 100 or 200.

Colors

Colors are a vital part of weaving, and two of the AWL input areas on the left are devoted to creating patterns of colors. You can create big, complicated patterns of colors using the AWL commands, or you can just enter one or a few colors by hand. There are three ways to identify each color; you can mix and match these as you like, even within a single expression.

By Name

This is probably the easiest option. Luminescence knows 1303 different color names, gathered from a wide variety of sources. Probably any color name you know is in the list. You can browse the colors sorted by name or sorted by hue using the links below. Note that if a given color has multiple names, I've retained all of them because some names might be more familiar to you than others.

For example, a nice middle brown is HarvestGold. You don't have to worry about upper and lower case letters. You can write this color as harvestgold or HARVESTGOLD or even haRVesTgoLd, and they'd all identify the same color.

Some names include characters like parentheses, digits, apostrophes, and dashes. For example, there's DarkLiver(horses), Tiger'sEye, and Violet-blue. These characters are all part of the name, so be sure to include them. But always make sure that you type in each color name a single word with no spaces. If you accidentally include a space in a name, AWL will read it as two separate colors, and try to make a pattern out of them. For example, if you put a space before the G in HarvestGold, the system would look for a color named Harvest and it wouldn't find it, giving you black as a default. Then it would search for Gold and find it, since that's an existing color. So instead of a single brownish color, you'd have a list of two colors, black and gold, which probably would not produce the look you intended. The moral is to make sure all of your colors are single words without spaces!

By Hex

If you're familiar with the hex notation used by browsers and some drawing programs, you can use that. Simply start your color with a hash mark (#) and follow it with six hex digits (the numbers 0 to 9, and the letters a to f or A to F). Remember there cannot be a space between the hash mark and the hex digits. The color HarvestGold can be named in hex as #DA9100 (case doesn't matter, so #da9100 works just as well). You can also use the eight-digit form of a hex color, but the first two digits (which describe opacity) are ignored.

By RGB

You can also name your colors using red, green, and blue values from 0 to 255. Start with the string rgb( and then list your values in the order red, green, blue, separated by commas (,), ending with a closing parentheses ()). In this form, HarvestGold would be written rgb(218,145,0). Remember, as always, there can be no spaces anywhere in this string (not even after the commas). If you're a programmer, don't let your fingers automatically add a semicolon at the end!

Making Patterns: The AWL Language

A digital loom lets us create large, complicated patterns in our draft and see their results almost instantly. Instead of clicking individually on hundreds of cells to create your big patterns, you type some commands into one of the input boxes. The program turns those commands into a potentially huge pattern for you, and then fills in the loom grids instantly and flawlessly. It also immediately redraws the fabric, so you can see what you've designed. This makes it fast and easy to experiment with both big and small changes to your draft, whether you're perusing a vision, following your intuition, or just messing around at random!

The easiest AWL expression is just a list: enter your numbers (or colors) with spaces between them, and then press the arrow button to the right of the box you're in. But the real power of AWL comes from using its built-in commands to make big, interesting patterns. For example, look at the preset named Long Green. You can see the AWL expressions for the warp and left in the boxes on the left (don't worry about what they mean right now, just notice how short they are). The warp expression makes a pattern a bit over 800 numbers long, and the weft is just over 600. This means those two short expressions specify a piece of fabric a little larger than 800 threads wide and 600 threads tall (looms, both real and digital, just repeat this basic block over and over to make as large a fabric as you like). Imagine designing and then typing in (or clicking!) 800 cells, and then debugging the inevitable mistakes. For something this size (and also for many smaller drafts), AWL is a much nicer way to go.

About Stack Based Languages

AWL is a stack-based language. The traditional way to think about this is to picture a stack of cafeteria trays, sitting one on top of the other. We can write something on each tray: a number, a string, a list of numbers, whatever we decide. We restrict ourselves to only two operations on this stack: we can push a new tray onto the top, or we can pop the topmost tray off the stack. That's it. Of course, if we push a tray we no longer have it in our hands; it's on the stack. And if we pop a tray it's no longer on the stack, but it's on our hands where we can read its value and do something with it. Those two things are all we can do: there's no peeking into the stack, re-ordering the trays, or anything like that. Just push a new tray on top, or pop the top one off.

We say that if there are no trays, we have an empty stack (the thinking is that the stack is still there in an abstract way, but there's just nothing in it). We'll make the rule that it's illegal to try to try to pop the top tray off an empty stack (since there are no trays to pop).

Let's see how to use a stack to add two numbers. To add 5 and 3 we usually write 5+3. But in a stack-based language, we write 5 3 +. Let's read this left to right. We'll treat this as a string of words, separated by white space. There are two kinds of words: data and commands. Basically, anything that isn't a command is presumed to be data.

So let's read 5 3 +. We start with an empty stack. The first word is 5. That's not a command, so we push it onto the stack, which now has just one element, the number 5. The next word is 3. That's also not a command, so again we push it. Now our stack has two items on it: the number 5 (on the bottom) and the number 3 (on the top). The next word is +. Aha, that's a command! And we know it takes two values: the left and right side of the addition symbol. Since we want two pieces of data, we'll pop the stack twice. The first time we pop it, we get the number 3, since that was on top. By convention, we'll treat that as the data on the right side of the addition sign, so now we're considering the result of something plus 3. We pop the stack again, getting 5, and that goes on the left side of our traditional expression 5+3. Note that the stack is now empty. So we evaluate our two pieces of data using the addition command, getting the result 8. By convention, all operators push their results back onto the stack. Since the stack was empty once we popped the 5, when we push the 8 onto the top of the stack it's now the only element on the stack.

That's the basic idea in a nutshell (see the Further Reading section if you crave more details). The calculator example we gave above is a famous way to illustrate a stack language. And it's almost right for AWL, but with a twist. Our pieces of data are not single numbers, but lists. They can be lists of numbers, or lists of colors, or even lists that contain both numbers and colors, but either way they're always lists. In AWL, a list has to have at least one element (that is, at least one number or color), but they can be as long as you like. In fact, much of the power of AWL is that you can create very big lists with just a few commands. Since our lists get turned into the grids of the warp, weft, and tie-up (and the colors for the warp and weft), having really long lists with lots of interesting internal patterns can produce large visual patterns with tons of interesting structure and detail.

AWL Concepts

AWL commands are also called operators, and the data they use are also called arguments. We call any item on a list an element. In AWL, an element is either a number or a color. Any command that produces a result automatically pushes that result onto the stack when it's done.

Numbers and Lists

AWL lists can be made up of either all numbers, all colors, or any mixture of the two. Many commands don't care what kind of list they get. For example, reverse simply pops a list off the stack, reverses the order of its elements, and pushes the result back on. You can give reverse a list of numbers or colors, and it will happily do the same job.

On the other hand, some commands require one or both of their inputs to be lists made exclusively of numbers. For example, block takes two lists (we'll call them A and B). It makes a new list by repeating each element of B the number of times given by the corresponding element of A. For example, if A=2 3 4 and B=1 5 8, then A B block tells the system that the first element of B (which is 1) should be repeated 2 times, the second element of B (which is 5) should be repeated 3 times, and so on. The result is then 1 1 5 5 5 8 8 8 8. If instead B=yellow blue red, the result of A B block would be yellow yellow blue blue blue red red red red. So for the block command, list A has to contain nothing but numbers, while list B can hold either numbers or colors or both.

The table below identifies whether any input lists must be made up of all numbers.

How To Enter Two Lists In A Row

To push a list onto the stack, you just give its values. So whether your list has one element (a number or color), or ten of them, you just name them all. As always, each list item must be a single string of characters with no spaces, and each element must be separated from the others with a space.

But what if you want to push two lists in a row? Many AWL commands take two lists, so they expect to pop a list off the stack, and then another. We just saw that above with block, which needs to pop two lists off the stack in order to do its job. Suppose your first list is 1 2 3 and your second is 9 8 7 6. If you typed 1 2 3 9 8 7 6 into the input box, you'd be creating one list with seven elements. The way to say, "I'm done with one list, and I'd like to start another" is to call push after the first list. So 1 2 3 push 9 8 7 6 pushes the list 1 2 3 onto the stack, then builds the new list 9 8 7 6 on top of that. Now the stack holds two new elements (on top of whatever might have been there before): one entry with the list 1 2 3, and on top of that (and on top of the stack) is the list 9 8 7 6. Forgetting to push between two lists is a common mistake, so if things go wrong for you, this is a good first thing to check for. Because you'll use push so much, there's a shortcut for it: the forward slash (also called a virgule): /. So you'll often see the above example written simply 1 2 3 / 9 8 7 6.

This situation is pretty much the only time you'll ever need to explicitly push something onto the stack, because the rest of the time the system manages all the pushes for you. In particular, if you name a list and then follow it with a command name, the system will automatically push the list onto the stack for you. So if we imagine a command named floop that takes one list as an argument, 1 2 3 floop is the same as 1 2 3 push floop or 1 2 3 / floop. Since it's good to keep your AWL as simple as possible (so it's easy to understand and modify), I suggest leaving out those extraneous push commands (in my expressions, I always leave them out).

Results Get Pushed Automatically

Any command that produces a result will push that result back onto the stack automatically as a new list.

For example, the expression 1 2 3 reverse will cause 1 2 3 to be popped off by reverse, and when that command is done, it will push its result 3 2 1 onto the top of the stack.

Some commands will push back either 1 or 2 lists, depending on their inputs. For example, the split command splits the topmost list on the stack at the location you specify, and then pushes the first part of your input list, and then the second part. But if your split location is before the beginning or after the end, then your input list doesn't get affected, and it simply goes back on the stack unchanged.

If a command can produce multiple lists, they get pushed back in the order given in the Full AWL Reference.

Draft Sizes

When your AWL is copied to the warp, Luminescence will draw a grid that starts at 1, but extends upwards as high as necessary to include your expression. So if your expression has the values 3 through 13, you'll get a warp that's 15 units high (because we always start at 1). Note that if this is bigger than the tie-up, the tie-up will get automatically repeated internally to match your huge warp; this will usually give you surprising results. The same is true for the weft.

To prevent those surprises, you'll probably want to adjust the size of the tie-up so it's as big or bigger than the warp and weft patterns. Use the Tie-up Width and Tie-up Height controls located above the fabric. You'll often set these to match the size of the warp and width, but you don't have to. If the tie-up is too small in either dimension (or both), it will be automatically repeated internally as needed. If the tie-up is too big, the unused bits are just ignored. Luminescence doesn't automatically re-size the tie-up for you, because that would make it much harder to modify a draft as you're working on it.

You'll sometimes find a published draft (or you'll make one of your own) where the warp and/or weft values don't start with 1. For example, the warp might contain values only from 3 to 6. The system will draw a warp that is 6 boxes high (because we always start with 1), but only the top 4 rows will have any black cells in them. In this case, you'll probably want the tie-up to be at least 6 cells high. The useful parts of the tie-up will be the top 4 rows. The bottom 2 rows never get used, so you can leave them empty or fill them in with anything you like.

You can control the size of the fabric by using the Fabric Size control located just above the fabric. As you make the fabric larger, the individual cells in the draft necessarily get smaller. By the same logic, as the fabric gets smaller, the individual cells in the draft can be drawn larger. If you want to edit the tie-up interactively with mouse clicks, the cells have to be big enough for you to be able to point to them accurately. If they're too small, you'll see a red box when you click. That's your signal to make the loom cells bigger by choosing a smaller fabric size.

The Domain

When you have 8 threads in your warp and weft (the starting default), then your pattern can only refer to threads numbers 1 through 8. This range [1,8] is called the domain.

When you're entering AWL, most of the time you don't need to think about the domain. The exception is when you use AWL commands that create runs. A run is a pass through the whole domain, going either up or down. For example, an upward run starting at 3 using the default domain is 3 4 5 6 7 8 1 2. If the domain was instead [2, 6], then a run starting at 3 would be 3 4 5 6 2.

The same principle applies to counting down. For example, counting down from 3 in our default domain would produce the run 3 2 1 8 7 6 5 4.

You set the two ends of the domain with the domain command. You can use this command to change the domain in the middle of an AWL expression. For example, if your warp has only 4 threads, you probably want to your upward runs to only go as high as 3, then continue on from 1. Many commands let you specify the start and end values for a run. For example, up takes two lists, and inserts an upward ramp from the last element of the first list to the first element of the second list. So in our standard domain, 1 2 / 1 2 up. would give us 1 2 3 4 5 6 7 8 1 2 (the middle part, 3 4 5 6 7 8, is the run). But if you want to use a domain from 1 to 4, you'd write 1 / 4 domain 1 2 / 1 2 up, which would produce 1 2 3 4 1 2.

When you change the domain, your new domain will remain in effect until you change it again. Each input box maintains its own domain, and it always starts out with the range [1,8]. If you change the domain in an AWL expression, it has that value until you change it again. So you might use the default for the start of an expression, change it to something smaller to produce shorter runs, then set it back to the default domain for the rest of your expression. You can change the domain as many times as you want in each expression.

The domain is only used by the run-making commands to control the values they produce. The domain has no effect on the other commands.

Automatic Resizing

Some commands require both lists to have the same length. For example, block takes two lists, A and B. It takes the first number in A, and repeats the first element of B that many times. Then it gets the second number in A, and repeats the second element of B that many times. Because the elements of the two lists are matched up one to one, both lists need to have the same length, or the same number of elements.

All of the commands that have this requirement will automatically resize the input lists for you by repeating the shorter one as needed until it's as long as the longer list (if the repeated list gets too long, we just drop the extraneous elements at the end). This doesn't change your input lists, and it all happens under the hood. But we identify which commands automatically resize for you, so you won't have to spend effort doing it yourself.

The AWL Commands

Here are all the AWL commands together in a big table. In this table, the bold capital letters A and B stand for lists, and lower-case letters c and d stand for single numbers (technically, a single number is also a list, but here we mean to indicate that this list must have only one element). A1 and AL refer to the first and last elements of list A (and B1 and BL do the same for list B). Ai refers to the i'th element of A, and Bi is the same for B.

The column headings have these meanings:

Command: The command name
Short: The command's shortcut, if it has one
List A: checked if A must be numbers
List B: checked if B must be numbers
Wrap: checked if this command wraps its output numbers around the domain
Resize: checked if this command make both lists the same size by repeating the shorter list
Summary: A short description of what the command does

This table is just a summary. For a full description of each command, see the Full AWL Reference.

Command	Short	Resize	Summary
A binary0	b0		Treat A as alternating runs of 0s and 1s
A binary1	b1		Treat A as alternating runs of 1s and 0s
A B block	#		Each Ai is repeated Bi times
A B blockpal	#p		block with internal palindrome
A B cipher			Replace each entry of value i in A with B(i mod (len B))
clear			Erase the stack
A B concat	,		Concatenate the top two stack elements
`c` `d` domain			Set the domain to [`c`, `d`]
A B down	>		A, descending run from AL to B1, B
A B `c` downrun	>r		Like down, but includes `c` runs as well
A B downup	>u	*	Alternating down and up runs (A may be 1 longer than B)
A B `c` downuprun	>ur	*	Like downup but include `c` runs as well
A dup			Pop the top of the stack and push it back twice
A `d` extend	+		repeat or clip A to `d` elements
A B growblock	=		Interleave A with growing palindromes of B
A iblock	i#		Like block but the inputs are interleaved in A
A iblockpal	i#p		iblock with internal palindrome
A B interleave	%		Take alternating elements of A and B
A B `c` `d` interleaveSteps	%s		Take `c` elements from A, then `d` elements from B
A palindrome	\|		A followed by its near reversal
A B pbox			Shortcut for A B A veclen extend permute
A B permute	&		Use elements of B to index A
A pop			Discard top of the stack
push	/		Consider all since last command a single list
A B ramp	-		A, up or down as needed to stay in domain, B
A B `c` ramprun	-r		Like ramp but include `c` runs as well
A `d` repeat	*		repeat A a total of `d` times
A reverse	@		reverse the elements of A
A `d` rotatel	<<		rotate A left by `d` steps
A `d` rotater	>>		rotate A right by `d` steps
showStack			Display an alert box with the current stack
A `c` `d` skipkeep	][		Skip `c` elements of A, keep next `d` elements, repeat
A `c` split			Cut A after element `c`, then push the left then right lists
A B swap			Exchange the top two stack elements
A tartan			Like iblock but repeats are half length
A tartanpal			tartan with internal palindrome
A B template	:		Create a subarticulation using B as a template
A `c` `d` twilll	t<<		Rotate left by `c` steps, `d` times
A `c` `d` twillr	t>>		Rotate right by `c` steps, `d` times
A B up	<		A, ascending run from AL to B1, B
A B `c` uprun	<r		Like up, but includes `c` runs as well
A B updown	<d	*	Alternating up and down runs (A may be 1 longer than B)
A B `c` updownrun	<dr	*	Like updown but include `c` runs as well
A veclen			Push the length of A
A vmax			Push the largest element in A
A vmin			Push the smallest element in A

Notes On Using AWL

Here are some helpful hints to keep in mind.

AWL expressions can get complicated very quickly if you let them. Start simple, and add small bits of complexity one step at a time.
The output window will always show you what's left on top of the stack when your expression has been evaluated.
A good way to experiment with AWL commands and get a feeling for them is to ignore the fabric. Just write little expressions in one of the input windows and press the arrow, and look at the pattern it generates on the loom. You can also see the numbers that make up that pattern by looking at the output window below.
The showStack command is your friend. It will always show you the full stack as of the moment it's encountered. It's great at the end of long expressions where you make lots of little sublists that get concatenated together, so you can make sure you haven't missed any. You can also put it in the middle of an expression, and it will pop up an alert box with the stack when it's encountered.
The stack always starts out empty at the start of evaluating each input box's expression.
Remember to push between lists when you're making them! This is an easy thing to forget.
Keep track of your domain. It starts at [1,8] for both warp and weft. If you change it, that change stays in effect for the rest of that expression. You can always set it back to [1,8] if you want.
Set the tie-up sizes set the way you like. The tie-up doesn't automatically re-size to fit your warp or weft (that would make it much harder to experiment with your drafts), but it will repeat as needed when the fabric is created. This can get confusing if the tie-up height is smaller than the size of the warp, or the width is less than the size of the weft.
When in doubt, just type in your pattern explicitly; not everything has to be a clever AWL construction. For example, if you want the pattern 2 1 3 5 2, it's probably easiest to just type that directly into the text area and move on. This is particularly useful for colors, where the lists are frequently just one or two colors.

The Rest of the Interface

Just above the fabric there are five boxes for you to type in numbers.

Fabric Size and Tie-up Size

Fabric size: The fabric is always a square. This tells the program how big that square should be. The warp and weft patterns and colors are simply repeated as necessary to match the fabric's size. Note that if you make the fabric size too big, it will take a few moments to draw the fabric, plus your browser could run out of memory or suffer other problems. You shouldn't have any problems up to 1000, and you may be able to go much higher, but at some point it will become too much for your poor little browser to handle.
Tie-up width:
Tie-up height: You can make the tie-up any size you like, as long as each dimension is at least 2 units. The data in the tie-up AWL input is used to fill in the grid starting at the bottom left and going up, then moving right one step and going up again, and so on. If there's more data in the tie-up pattern than is needed, the extra is just ignored. If the tie-up pattern isn't long enough to fill up the grid, it's repeated as needed. If the tie-up height is less than the size of the warp, or its width is less than the size of the weft, it will be internally repeated as needed to match.

Display Options

Show threads: This is strictly a cosmetic choice that controls how Luminescence draws the fabric for you. Turning on this checkbox makes the threads a little narrower than the display cells, so it's easier to get the sense that these are individual threads, rather than solid blocks of color. The checkbox is disabled (it's grayed out) when the value of Fabric size is 100 or more. The state of this checkbox is not saved to, or restored from, your saved drafts.
Show grids: This is another cosmetic choice. Turning this on draws the internal grid lines for all 6 grids (warp pattern, warp colors, weft pattern, weft colors, tie-up, adn fabric). These let you easily count the cells, which can make it easier to match a published draft. As with Show threads, this checkbox and its effect are disabled if the Fabric size is 100 or more.

Editing the Tie-Up

The tie-up is fun to edit interactively. Try starting with a simple triangle wave in both the warp and weft, as in the Simple Twill preset. If you want a larger canvas, make the tie-up bigger, as in the Tabletop Variation presets (remember to make make your domain size and warp and weft patterns larger also). To flip a tie-up cell from black to white, or vice-versa, just click on it.

If you see a red box when you click, it means that your tie-up cells are too small to be edited accurately. To make all the cells in the draft bigger, including the tie-up, reduce the size of the fabric. Using an 8-by-8 tie-up, I find a fabric size of 50 gives me plenty of accuracy for editing, and often shows me at least one repeat of the woven fabric.

Saving and Loading

You can save your fabric directly to your hard drive using the instructions below. But because of how browsers are written, you cannot save and load your drafts to your local hard drive. So you need to use some kind of remote file system, usually called the cloud. Since all cloud services are different, I can't support them all. I chose to support a popular cloud service called Dropbox. They have a great reputation for privacy and reliability, and they offer you 3GB of storage off the bat for free (they stay in business by selling you more space than that if you need it).

Saving The Fabric

To save an image of the fabric, just right-click on it. You should get a pop-up menu that offers you a few options. One of these will be Save Image As... (or something close to that). Choose that, and you'll get a standard dialog box that lets you put the image where you want it. The image is saved in the standard PNG format, which offers the highest quality. You can change that to JPG or anything else using almost any image editing program.

Saving and Loading The Draft

As mentioned above, saving and loading your draft requires Dropbox. See the next section for getting that set up.

Once you're set up with Dropbox, you save your draft by first giving it a name. Type the name you like in the text box at the very top of the window, and then press the Save button. You don't have to give the name an extension; the program will automatically add .wif for you if it's not there. WIF is the standard format that weaving programs use to describe a draft (you can find out more in the FAQ below). By saving your drafts in WIF, you can share them with other people, read them into other weaving programs, and even give them to a weaver to produce real fabric for you!

To load a draft, just choose Load Draft. You'll get a drop-down list with two parts. At the top are all the .wif files in your Dropbox (or an invitation to log in if you haven't done so already). Below that is a list of presets, or drafts that I've made for you as examples. You can't modify or save the presets, but you can change them and save your own copies in your Dropbox.

If you want to change the names of your .wif files, copy or delete them, or do anything else with them, just use your normal file-system browser to view the contents of the folder Apps/Luminescence, located inside your Dropbox folder, which is probably located in your home directory. You can even read the .wif files saved there with any text editor that you like, since they're just plain text.

Using Dropbox

If you don't have Dropbox yet, click on this link to sign up for a free account (disclaimer: by using the link, rather than going to Dropbox directly, they give me some more storage as a thank-you for the referral. But you can go straight to Dropbox if you prefer to bypass my link).

If you care about privacy (I sure do), be assured that your transactions with Dropbox are completely independent of me and my code. Your password and all of your files are yours and yours alone, and I never see any of it. I can't even find out if you ever use Dropbox or not, much less find out what you're doing or what files you're working with. Frankly, I like it this way; what you do with your computer is your business.

The first time you try to save or load a file from a fresh web page, Dropbox will ask you to log in, as shown on the left of Figure 4. Just enter your normal Dropbox account credentials. The very first time you do this, Dropbox will create a special folder for Luminescence in your Dropbox folder. To protect you, my site will only be allowed to read and write files in this folder. This authorization is shown on the right of Figure 4; you should only have to do this once.

When you've approved access, Dropbox will create a folder for you in your Dropbox account. This new folder is called Apps/Luminescence, and all of your files will be placed there. Note that if you want to share any of those files with someone else, copy them into the Public part of your Dropbox, as usual.

FAQ

The AWL table is way too cryptic. What do these commands really do?

The table is just a quick reference. A more detailed description of each command can be found here.

If you prefer to learn by experimenting, go for it! Just type in stuff and see what comes out.

Why can't I click in the warp or weft patterns, like I can in the tie-up?

The tie-up is essentially a random bunch of 0's and 1's, so it makes sense to let you change them interactively. I can automatically compute a reasonable AWL from any tie-up, so I do that and paste it into the Tie-up input box for you each time you click a tie-up cell.

Clicking on the tie-up often makes a lot of intuitive sense, particularly when the warp and weft are simple, like repeating triangular waves. But I've found that clicking in the warp and weft produces changes that are much harder to anticipate. In addition, the goal of Luminescence is to help you create rich and interesting patterns using AWL, not by endless clicking in the warp and weft grids.

If you really want to twiddle individual entries in the warp or weft, your best best is to replace your AWL patterns with the big list of numbers that they generate, and then edit that list. For example, if you want to individually tweak the warp pattern, set the output box to show you the warp pattern, and copy its contents. Paste that list back into the warp input box. Now you can edit that list as you like. Remember to press the arrow after each change to copy your new pattern to the loom.

What if I don't want to use Dropbox?

No problem. The online loom will still run fine. You can even load the presets, and you can save your fabric images. But you won't be able to load and save your drafts, nor import drafts shared or published by other people.

I wish I could support all cloud services, but each one requires me to write special programming to talk to it, and for some services that can get very complicated. I picked Dropbox because they're reliable and take privacy seriously, they made it easy for me to integrate my code with them, and they offer a lot of free storage (3GB is huge; you can store over a half-million typical .wif files in that much space!). As I mentioned above, you can click on this link to sign up (and give me a bit more space to develop more programs).

If you prefer to use another cloud provider for your everyday work, you can certainly use both that one and Dropbox at the same time. Just drag the files back and forth as needed.

If you want to save your drafts but you really don't want to use Dropbox at all, you can take a screenshot of your window, and then type everything back in from there to re-load the draft.

How do I share my drafts?

The .wif files are just plain text files, sitting in the directory Apps/Luminescence in your Dropbox. Just share them as you'd share any text file!

What's this WIF format all about?

It's a format designed in 1997 by a group of authors of weaving software so that their users could share their drafts. It's simply a set of rules for how to write your draft into a plain-text file. You can find the specification here.

Luminescence writes simple .wif files that omit a lot of optional stuff, like thread spacing and thread thickness. If you're reading a .wif file with that information in it, Luminescence just ignores that stuff (which means it isn't included if you later save the file to the same or a different name).

I found a draft where there are lots of black squares in the warp columns and weft rows, but you said there should be only one in each column and row. What gives?

My understanding is that those drafts are for varieties of looms that don't have tie-ups. I don't support those kinds of drafts; if you try to read them in you'll find that I ignore all but the first marked column or row in the warp and weft.

In my experience, I've always been able convert one of those drafts into one that follows the format we use here, but I don't guarantee that's always possible.

Why is this such a simple loom?

Real looms are complex pieces of technology. I wanted to focus here on the process of making patterns, so I simplified things down to their basics. This loom, in essence, is a place to explore weaving and pattern-making. I hope the process will enlighten you, and the resulting fabrics will illuminate your day.

Why am I getting a really weird error when my AWL looks fine?

A very frequent cause of weird errors is messing up the spacing rule. Remember that each word in AWL must be surrounded by space. That means each number and each command. For example, the shortcut for twillr is t>>, all one word with no spaces. And if you want to concatenate three lists together, you'd write , , , with a space between each comma. Leaving out those spaces is an easy mistake to make.

How do I debug my AWL?

If things are going wrong, I find it easiest to write down the whole expression I'm working on, and then build it up again one step at a time. Type in one new piece of stuff to build the pattern, and put a showStack command at the end. Using the stack, the output window, and the pattern in the corresponding grid on the loom, you should be able to see what you're making, and tune it up until it's right. When it's okay, move on and build the next chunk.

You said there should be just one thing left on the stack at the end, but I have more. Is that a problem?

Not necessarily, if what's on top is the result you want. But usually that indicates a problem. A common cause of this comes from building up your expression in pieces, but then forgetting to concatenate them together into one big pattern when you're done. A lot of complicated expressions end with a bunch of commas (the concatenation shortcut) to glue together all the intermediate results sitting on the stack.

AWL isn't much of a language. Where are the variables, loops, procedures, etc.?

AWL isn't a general-purpose programming language, and it doesn't need all that stuff. It's been designed for one thing only: to help you make cool patterns of numbers and colors that are useful in weaving. You don't need variables, loops, and all that stuff to do that. If you find yourself wanting to use all of those tools to make your expressions, or you want to use arithmetic or even math operators, your best bet is to fire up your favorite language and write programs in it. The easiest output would be a big list of numbers or colors, which you can just copy and paste into the appropriate input boxes. If you're feeling fancy, you can write AWL expressions. If you're really ambitious, you can write .wif files directly; see the question above for a link to the format specification.

Hey! You crashed my browser!

Sorry! This probably happened after you pressed one of the arrows to turn your AWL into a pattern for the loom. The truth is that there are a lot of ways that things can go wrong when I turn your AWL into a pattern. I've tried to catch all of them, and to give you at least some information about where things went wrong. If something slipped past me and crashed your browser, I'd love to fix it. The catch is that I'd need the exact AWL expression you were trying to translate at the time of the crash, and that's probably gone because, well, the browser's crashed. So if you can, try to immediately re-load the page and recreate the problem. Copy the text in your input box (or take a screen shot) frequently each time you get closer to the problem. Then when it does crash, you'll be able to send me email and simply paste the offending AWL right into the body of the mail.

How did you write this?

Luminescence was written from scratch in standard Javascript, with just a bit of jQuery. Working on my iMac, I used the vi text editor inside of an iterm2 window, and debugged my Javascript using the Developer Tools in Google Chrome . I used the Bootstrap 3.3 framework to help make responsive pages, and the dropbox.js API for reading and writing to Dropbox. In my documentation, the body text is Open Sans, and the headlines are in Ubuntu, both from Google fonts.

How can I reach you?

You can email me at

More contact information is on my home page. My Twitter handle is @AndrewGlassner.

If something's going wrong, please try to describe it as precisely as you can, and include enough information for me to replicate the problem on my end. A screenshot or .wif file of your input would be great, along with a screenshot (or just the text) of any error message.

I'd love to hear suggestions for making Luminescence better and more useful to you! Send them along. Do keep in mind, though, that this project is a labor of love and it's free, so it might take me a while to make changes.

Nice project. What else do you do?

I've done a lot of computer graphics, writing, art, and music.

You can see my online computer graphics research and artwork at my personal site, www.glassner.com.

My novels Home Security, Freaks of Nurture, and Bait are all available on Amazon,

You can also see more about my company, The Imaginary Institute, at www.imaginary-institute.com, and check out my course for artists and designers who want to create their own interactive computer graphics. I also give talks, teach, and consult in computer graphics and storytelling. I'm always interested in fun new projects; feel free to contact me at the link just above!

You can also follow me on Twitter at @AndrewGlassner.

Luminescence

Main Help