WIF is short for Weaving Information File. It is a plain-text format that most weaving programs can open and save, so you can move a draft between apps without redrawing it. The version everyone uses is 1.1, from April 20, 1997.
Below we walk through how a .wif file is put together, section by section, and we note what Bower and our free WIF Viewer actually do with each part. If you are writing a tool or trying to fix a file that will not open cleanly, this should help. For a plain-language intro first, see What is a WIF file?.
When we say something about Bower, we use these labels:
- Supported — we read it, write it, or both.
- Partial — we handle it, but not every edge case from the 1.1 text.
- Ignored — the file can contain it; we skip it and do not fail the import just because it is there.
- Not written — our export never outputs it.
- Suspended in 1.1 — still listed in the old format text, but not part of normal use today.
1. Design goals
The people who designed WIF wanted a format that could grow without becoming unreadable, that a person could open in a text editor and still make sense of, and that any computer which can read plain text could process.
They chose human-friendly comma lists of shaft and treadle numbers instead of packed binary bitfields. The layout looks a lot like an old Windows .INI file—sections in brackets, Key=value lines—but it is not limited to the 64K size of classic Windows 3.1 ini files. You cannot use the old Windows private-profile APIs; you have to parse the text yourself.
2. File type
A .wif file is just text. There is no binary wrapper. People expect the .wif extension; what matters is the content.
Typical extension .wif Character set ASCII (UTF-8 without BOM is fine in practice) Line endings LF or CRLF Order Readers must not depend on section or key order
Bower: We read and write .wif as ordinary text.
3. Lexical rules
Everything is line-based. A line is blank, a comment, a section header, or a key/value pair.
- Blank lines are ignored.
- If the first non-space character is ";", the whole line is a comment. You can also put a comment after a number or boolean (often after another ";"). Free-text keys should not have trailing comments on the same line.
- Section headers look like [Section Name]. Matching is case-insensitive; by convention the names are written in uppercase.
- Assignments look like Key=value. Matching on the key is case-insensitive. The value is whatever sits after the first "=" on that line.
- Duplicate keys in one section are bad form. Readers should not crash; they may keep the first or the last value.
- Section order and key order inside a section do not matter for a correct reader.
Here is a tiny fragment (not a full draft):
; this line is ignored [WEAVING] Shafts=4 Treadles=4
Bower: We skip blanks and full-line ; comments, match names case-insensitively, and for ordinary keys the last value wins. Structure rows are keyed by number. We trim values but do not specially strip inline trailing comments.
4. Booleans and symbols
For true/false, the format allows true, on, yes, and 1 on the true side, and false, off, no, and 0 on the false side. If an optional boolean is missing, treat it as false unless a particular section says otherwise.
Bower: We treat true, yes, and 1 as true. Anything else non-empty counts as false. We do not special-case on or off.
Some programs store draft “symbols” (characters used instead of filled squares). Those use a small symbol type:
=1 digit =X single character ='X' quoted character =#219 character code 0..255 Write a space as ' ' or #32. Write a hash as '#' or #35.
Bower: We do not implement symbols. Appearance is colors only. Symbol sections are ignored on import and never written on export.
5. Minimum requirements
A proper 1.1 file always has [WIF] and [CONTENTS]. Every other section that actually appears in the file should be listed under [CONTENTS] with the value true. You can omit sections you do not use, or list them as false. If a section is present, its required keys should be present too.
So a file that only has threading and no [WIF] block is not a valid WIF 1.1 document—even if some tools still try to read it.
Bower: Import fails without [WIF]. We do not require or validate [CONTENTS] on the way in. On export we always write both, and we mark true for every section we emit.
6. Informational sections, data sections, and sparse data
Some sections are background (title, palette size, loom counts) and some are the actual rows of the draft (threading lines, per-end colors, and so on). [CONTENTS] is the list of what is included. It does not list [WIF] itself.
The format expects sparse data. You create all the warp ends and weft picks from Threads, fill in defaults from [WARP] and [WEFT], set structure cells to zero (unused), then only write the keylines that differ from those defaults. Readers reverse that process.
For example, if eight warps are the same red and only end 3 is blue, you can default red on the warp and override one line:
[WARP] Threads=8 Color=1 [WARP COLORS] 3=2
Ends 1, 2, 4–8 stay palette color 1; end 3 uses palette color 2. Same idea for structure: a missing threading line means “no shafts on that end,” not “copy the previous end.”
Bower: We use thread counts and the structure/color tables. We do not implement spacing/thickness defaults or sparse thickness/spacing. Structure defaults to empty; missing structure keys stay empty. If a color table is present, we apply [WARP] / [WEFT] Color defaults when the index is greater than zero, then apply per-end and per-pick overrides.
7. Private sections
Apps can stash their own data without breaking everyone else. The name has to include a unique source id so two vendors do not collide:
[PRIVATE <SourceID> <SectionName>] Lines inside must not start with '[' so a reader can find the next section.
Bower: We skip private sections and never write them. We do not define a private Source ID.
8. Section catalog
Here is each named section from WIF 1.1, and what we do with it. If you only care about opening drafts in Bower, you can skim the “Ignored” entries and focus on structure, colors, and the export list in section 10.
8.1 [WIF] — required
This is the identity block. Without it, we do not treat the file as WIF.
Key Official Description ---- -------- ----------- Version required e.g. 1.1 Date required free-form date string Developers required contact / authors Source Program required creating program name Source Version optional creating program version
Bower: The section itself is required on import. We write Version=1.1, Date, Developers, Source Program=Bower, and Source Version on export. We do not hard-fail if individual keys inside [WIF] are missing on import.
8.2 [CONTENTS] — required in 1.1
This is a table of contents: section name as the key, true or false as the value. Only the sections that exist need to be listed as true. Some writers list every possible section with true/false; that is allowed, not required.
In theory a careful reader could decide what to load from CONTENTS alone. In practice many tools (including us) just walk the whole file.
Informational flags: COLOR PALETTE, WARP SYMBOL PALETTE, WEFT SYMBOL PALETTE, TEXT, WEAVING, WARP, WEFT Data flags: NOTES, TIEUP, COLOR TABLE, WARP SYMBOL TABLE, WEFT SYMBOL TABLE, THREADING, WARP THICKNESS, WARP THICKNESS ZOOM, WARP SPACING, WARP SPACING ZOOM, WARP COLORS, WARP SYMBOLS, TREADLING, LIFTPLAN, WEFT THICKNESS, WEFT THICKNESS ZOOM, WEFT SPACING, WEFT SPACING ZOOM, WEFT COLORS, WEFT SYMBOLS, PRIVATE <SourceID> <SectionName> Suspended / reserved: TRANSLATIONS BITMAP IMAGE, BITMAP FILE, BITMAP IMAGE DATA
Bower: We do not require CONTENTS on import and we do not use it to choose what to parse. On export we write true for every section we actually emit.
8.3 [COLOR PALETTE]
This tells you how big the palette is and what numeric range the RGB values use. Older files sometimes use 0–999 instead of 0–255, so readers have to scale.
Key Official Description ---- -------- ----------- Entries required integer > 0, palette size Range required min,max with max > min Form=RGB obsolete do not write; ignore if present
For example, Range=0,999 and a table entry 1=999,0,0 maps the red channel to about 255 in 8-bit. With Range=0,255 and 1=255,0,0, no scaling is needed.
Bower: We read Range (default 0,255 if it is missing) and convert each channel with round((c − min) / (max − min) * 255), then clamp to 0–255. If max−min is zero or negative, import fails. We do not enforce Entries. Export always uses Range=0,255.
8.4 [WARP SYMBOL PALETTE] / [WEFT SYMBOL PALETTE]
Key Official Description ---- -------- ----------- Entries required integer > 0
Bower: Ignored. Not written.
8.5 [TEXT]
Optional notes about the piece and the maker—title, author, contact info. None of this changes the draft grid.
Key Official ---- -------- Title optional Author optional Address optional EMail optional Telephone optional FAX optional
Bower: Ignored. Not written.
8.6 [WEAVING]
Loom size and shed convention. Shafts and treadles can grow if the structure sections mention higher numbers than you declared here.
Key Official Description ---- -------- ----------- Shafts required integer > 0 Treadles required integer > 0 Rising Shed optional true = listed shafts go up Profile obsolete ignore; do not write
Rising shed means the shafts listed in the liftplan (or raised through the treadle/tie-up path) are the ones that lift. Falling shed is the other physical convention. If a file says falling shed, we flip the liftplan cells—or the tie-up cells—after load so our internal grids stay rising-shed and the cloth still matches what the file meant.
Bower: We read Shafts and Treadles (default 4 if missing) and grow them from structure when needed. Missing Rising Shed is treated as true. False triggers the invert above. Export always writes Rising Shed=true, and Treadles=0 when we export liftplan mode. Profile is ignored.
8.7 [WARP] and [WEFT]
These describe the whole warp or weft and the default for each thread. After you know Threads, you allocate that many ends or picks, apply defaults, then let the sparse sections override individuals (see section 6).
Key Official Description
---- -------- -----------
Threads required number of ends or picks
Color optional palette index, or index + R,G,B
Symbol optional symbol type
Symbol Number optional index into symbol table
Units required if spacing/ Decipoints | Inches | Centimeters
thickness used
Spacing optional real ≥ 0
Thickness optional real ≥ 0
Spacing Zoom optional integer ≥ 0
Thickness Zoom optional integer ≥ 0
Obsolete in 1.1 (ignore / do not write):
Colors, Palette, ColorMix
On Color, prefer a simple palette index for interchange. Some files also attach an RGB triple; we only use the index.
Color=2 ; every end/pick defaults to COLOR TABLE entry 2 Color=2,255,0,0 ; index plus optional RGB — we keep the index only
If a program only supports one of spacing and thickness, the format says to prefer Spacing when both are present. If you only think in “thickness,” write Spacing (or write both with the same numbers).
Bower: We read Threads (defaults 32 for warp and 48 for weft if missing) and Color as one palette index when it is greater than zero. We ignore symbols, spacing, thickness, zooms, and extra RGB on Color. Export writes Threads, Color, and Units=Centimeters.
8.8 [NOTES]
Free text, one string per numbered line. Not part of the draft grids.
1=First line of notes 2=Second line
Bower: Ignored. Not written.
8.9 [TIEUP]
Each treadle lists the shafts it raises (rising-shed sense, before any invert). You use this with threading and treadling when you are not on a pure liftplan.
Key = treadle (1..n)
Value = shafts, comma-separated
0 alone means unused
Missing lines stay unused
Example: 1=1,2 → treadle 1 raises shafts 1 and 2
Bower: Supported in tie-up mode. Multi-shaft values are fine. Export writes one line per treadle.
8.10 [COLOR TABLE]
This is the palette. Indices here are what warp/weft Color keys point at. The R,G,B numbers live in the Range from [COLOR PALETTE].
Key = palette index Value = R,G,B in the palette Range
Here is a small example of palette, warp default, and two overrides:
[COLOR PALETTE] Entries=2 Range=0,255 [COLOR TABLE] 1=200,40,40 2=40,40,200 [WARP] Threads=4 Color=1 [WARP COLORS] 2=2 4=2
Ends 1 and 3 default to the reddish palette entry; ends 2 and 4 use the bluish one.
Bower: Supported, with the Range mapping described above. Export writes one table entry per unique yarn color and always uses Range=0,255.
8.11 [WARP SYMBOL TABLE] / [WEFT SYMBOL TABLE]
Key = symbol index Value = WIF symbol type (see section 4)
Bower: Ignored. Not written.
8.12 [THREADING]
Which shafts each warp end goes through. Multiple shafts on one end are allowed.
Key = warp end (1..n)
Value = shaft, or shaft,shaft,...
1=1,5 means end 1 is on shafts 1 and 5
0 means unused
Missing lines stay unused
Bower: Supported, including multi-shaft ends. Export writes one line per end.
8.13 Per-end and per-pick sections
These attach values to individual ends or picks. There are three groups: structure (treadling / liftplan), color, and appearance (thickness, spacing, symbols).
Section Value Default if missing
------- ----- ------------------
[WARP THICKNESS] real ≥ 0 [WARP].Thickness
[WARP THICKNESS ZOOM] integer ≥ 0 [WARP].Thickness Zoom
[WARP SPACING] real ≥ 0 [WARP].Spacing
[WARP SPACING ZOOM] integer ≥ 0 [WARP].Spacing Zoom
[WARP COLORS] palette idx [WARP].Color
(one integer; ignore old R,G,B tail)
[WARP SYMBOLS] symbol idx [WARP].Symbol Number
[TREADLING] treadles unused (zero)
[LIFTPLAN] shafts unused (zero)
[WEFT THICKNESS] real ≥ 0 [WEFT].Thickness
[WEFT THICKNESS ZOOM] integer ≥ 0 [WEFT].Thickness Zoom
[WEFT SPACING] real ≥ 0 [WEFT].Spacing
[WEFT SPACING ZOOM] integer ≥ 0 [WEFT].Spacing Zoom
[WEFT COLORS] palette idx [WEFT].Color
[WEFT SYMBOLS] symbol idx [WEFT].Symbol Number
Treadling is for tie-up mode: key is the pick, value is which treadles you press, e.g. 5=1,2. Liftplan is direct: key is the pick, value is which shafts rise, e.g. 5=1,3. A normal file uses one control path or the other, not both at once (see the next section).
Bower: We support treadling, liftplan, and warp/weft colors. We ignore thickness, spacing, zoom, and symbol sections, and we never write them.
8.14 Loom mode, rising shed, and drawdown
There is no single “mode=” key in the file. You figure out how to read the structure from what is present.
This is the rule we use in Bower and the free WIF Viewer:
If [LIFTPLAN] is present
and ([TREADLING] is missing or Treadles is 0)
then treat the file as liftplan
(THREADING + LIFTPLAN)
else treat it as tie-up
(THREADING + TIEUP + TREADLING)
Liftplan is the dobby-style “each pick lists shafts” model. Tie-up is the classic shaft-loom model: treadles select a column of the tie-up, and treadling is the sequence of treadles.
When Rising Shed is false, after we load the grids we invert every liftplan cell (liftplan mode) or every tie-up cell (tie-up mode). Threading and treadling stay as written.
Rising Shed=true, pick 1=1,2 → shafts 1 and 2 up
Rising Shed=false, same line → those shafts stored as down,
other shafts flipped on
The drawdown is not stored in the file. After structure is loaded (and any shed invert is done), each cloth cell is warp-up if some shaft that is threaded on that end is also raised on that pick—either from the liftplan, or from an active treadle and its tie-up. Otherwise it is weft-up. Programs recompute that for display; there is no drawdown section to export.
Bower: This is how we load and display. The free WIF Viewer follows the same structure and color rules. In liftplan mode the viewer leaves out the empty tie-up block and shows treadles as “-” in the side panel.
8.15 Suspended and obsolete bits
Suspended at 1.1: [TRANSLATIONS] [BITMAP FILE], [BITMAP IMAGE], [BITMAP IMAGE DATA] Dropped / obsolete in the 1.1 narrative: Design section, ColorMix, Colors key, Palette key, RGB tail on WARP/WEFT COLORS
Bower: We ignore all of these and do not write them. Unknown sections never fail the import by themselves.
9. Bower size limits
These are not part of WIF 1.1. On import we clamp dimensions so a wild file cannot allocate an unbounded grid. Values outside the range are pulled into range rather than rejected as “not WIF.”
Warps, wefts 1 .. 4096 Shafts, treadles 1 .. 64
10. What Bower writes
Our export is a full rising-shed file meant to open in other 1.1 readers that understand the same core sections. We do not try to preserve notes, symbols, spacing, or private vendor data from a previous import—those get dropped if you round-trip through us.
- [WIF], [CONTENTS], [COLOR PALETTE] with Range=0,255, [WEAVING] with Rising Shed=true
- [WARP] and [WEFT] with Threads, Color index, Units=Centimeters
- [COLOR TABLE], [THREADING], [WARP COLORS], [WEFT COLORS]
- Either [LIFTPLAN] and Treadles=0, or both [TIEUP] and [TREADLING]
- No TEXT, NOTES, symbols, spacing, thickness, private, or bitmap sections
11. Examples
Two small complete files. No color table—just structure.
11.1 Tie-up mode
Eight ends, eight picks, four shafts, four treadles. Straight-draw threading, a simple twill-style tie-up, treadling that walks the four treadles twice.
[WIF] Version=1.1 Date=April 20, 1997 [email protected] Source Program=Example Source Version=1.0 [CONTENTS] WEAVING=true WARP=true WEFT=true THREADING=true TIEUP=true TREADLING=true [WEAVING] Shafts=4 Treadles=4 Rising Shed=true [WARP] Threads=8 [WEFT] Threads=8 [THREADING] 1=1 2=2 3=3 4=4 5=1 6=2 7=3 8=4 [TIEUP] 1=1,2 2=2,3 3=3,4 4=1,4 [TREADLING] 1=1 2=2 3=3 4=4 5=1 6=2 7=3 8=4
11.2 Liftplan mode
Four ends, four picks. Treadles is 0 and [LIFTPLAN] is present, so the file is read as liftplan. Each pick lists shafts directly—no tie-up, no treadling.
[WIF] Version=1.1 Date=April 20, 1997 [email protected] Source Program=Example [CONTENTS] WEAVING=true WARP=true WEFT=true THREADING=true LIFTPLAN=true [WEAVING] Shafts=4 Treadles=0 Rising Shed=true [WARP] Threads=4 [WEFT] Threads=4 [THREADING] 1=1 2=2 3=3 4=4 [LIFTPLAN] 1=1,2 2=2,3 3=3,4 4=1,4
12. Related tools
You can open a .wif in the free WIF Viewer to check the draft in the browser, or import it in Bower (including Open in Bower from the viewer) when you want to edit.
13. Citations
These are the sources for the format text. The “Bower:” notes on this page describe our import and export behavior; they are not part of the 1997 specification.
- Nielsen, Ravi, et al. Weaving Information File (WIF) Specification, Version 1.1. 20 April 1997. Contributors included Ravi Nielsen (Patternland / Maple Hill Software), Bob Keates (Fiberworks), Rob Sinkler (SwiftWeave), and members of the 1997 WIF email list. Text: http://www.tantradharma.com/maplehill/wif/wif1-1.txt.
- Nielsen, Ravi; Keates, Bob; Sinkler, Rob. Weaving Information File (WIF) Specification, Version 1.0. 3 March 1996. Superseded by 1.1 for current interchange.
- Asunder — Bower and the free WIF Viewer.