ILMƏ
ScanLibraryCarpet collectionCreate a memoryAbout & ethicsOpen standard
enazru

ILMƏ

Every knot remembers.

  • Scan
  • Library
  • Carpet collection
  • Create a memory
  • About & ethics
  • Open standard

XalçaID is an open standard (CC BY 4.0).

Made with craftswomen of Azerbaijan and Dagestan.

The open standard

Everything needed to read a XalçaID carpet without our software.

Archives

Versioned exports of all approved records (with checksums) will be published on Zenodo, the Internet Archive and as GitHub releases.

XalçaID — format specification, version 1

Status: draft 1.0, 2025. Open standard, published under CC BY 4.0. Maintainer: the WOVEN project. Reference implementation: xalcaid/ in the WOVEN repository.

This document is written so that someone with no access to our software, 50 years from now, can read a XalçaID carpet: by hand with a printed catalogue, or by writing a new decoder from this text.

Honesty note. XalçaID is a new system, designed in 2025. It is inspired by the geometry of Avar and Azerbaijani textile traditions. It does not claim that historical carpets contain hidden writing or language. A carpet carries XalçaID only if it was deliberately made with it.


1. Overview

A XalçaID carpet contains one or more coding ornaments (medallions). Each one carries a number (ID) between 0 and 1,048,575. The ID points to a record (a poem, a word with its pronunciation, a story…) in the WOVEN registry. The registry is published as open archives (see archive/), so the link from ID to record does not depend on any website.

Inside each ornament, 16 small shapes sit in a 4 × 4 grid. Which shape is in which position is the code. Colour carries no information.

  ID ──► 24-bit payload ──► scramble ──► 4 data symbols ──► Reed-Solomon ──► 8 symbols
     ──► 16 values (3 bits each) ──► whitening ──► 16 shapes in the ornament

2. Terms

termmeaning
stitchone knot, cross-stitch or weave unit of the carpet
modulethe unit of the ornament grid; at scale s one module is s × s stitches (s = 1, 2, 3 …)
ornamentone coding medallion, 29 modules wide and 32 tall (section 5)
slotone of 16 positions in the ornament that holds one shape
shape valueinteger 0–7 identifying one of the 8 shapes
motif colour / ground colourthe colour a shape is stitched in / the colour around it

"Top" of an ornament is the side with the head (finial and ram's horns, section 5.3). All row/column descriptions are seen from the front of the carpet with the ornament's top up.

3. Shape vocabulary

Each shape is a 5 × 5 module pattern. # = motif colour, . = ground colour. Row 1 is the top row (toward the ornament's head).

valuebitsnamepattern (rows 1→5)
0000dot (five dots)#...# ..... ..#.. ..... #...#
1001circle (ring).###. #...# #...# #...# .###.
2010diamond (rhombus with centre dot)..#.. .#.#. #.#.# .#.#. ..#..
3011cross..#.. ..#.. ##### ..#.. ..#..
4100star (eight points)#.#.# .###. ##### .###. #.#.#
5101triangle (pointing up)..#.. .###. .###. ##### #####
6110chevron (pointing down)#...# ##.## .###. ..#.. .....
7111hook (S-shaped latch hook, gochmaq)###.. #.#.. ..#.. ..#.# ..###

Any two shapes differ in at least 8 of the 25 cells. A shape with up to 3 wrongly stitched cells is still closer to its own pattern than to any other.

Machine-readable copy: xalcaid/shapes/vocabulary.json.

4. From ID to shapes

4.1 Payload

payload = (version << 20) | id          version = 1 for this specification, id in 0 … 1,048,575

The payload is 24 bits. Versions 0 and 2–15 are reserved; a decoder must reject them.

4.2 Scrambling

So that neighbouring IDs (1, 2, 3 …) do not produce near-identical ornaments, the payload is mixed by an invertible function on 24-bit integers:

x = (payload × 0x5BD1E5) mod 2^24
x = x XOR (x >> 12)

Inverse (for decoding): x = x XOR (x >> 12), then payload = (x × 0x5BD1E5⁻¹) mod 2^24, where 0x5BD1E5⁻¹ is the inverse of 0x5BD1E5 modulo 2^24 (it exists because the constant is odd).

4.3 Data symbols

Split the scrambled 24 bits into 4 symbols of 6 bits, most significant first: d0 = bits 23–18, d1 = bits 17–12, d2 = bits 11–6, d3 = bits 5–0.

4.4 Reed-Solomon error correction

  • Field: GF(64), elements are 6-bit integers, built with the primitive polynomial x⁶ + x + 1 (0x43). The primitive element α is 2 (the polynomial x). Powers of α: α⁰ … α⁷ = 1, 2, 4, 8, 16, 32, 3, 6.
  • Code: RS(8, 4), 4 parity symbols, first consecutive root α⁰.
  • Generator polynomial g(x) = (x − α⁰)(x − α¹)(x − α²)(x − α³) = x⁴ + 15x³ + 54x² + 59x + 3 (coefficients as GF(64) integers; in GF(2ᵐ), − equals +).
  • Systematic encoding: the message polynomial is d0·x³ + d1·x² + d2·x + d3. The parity symbols p0…p3 are the coefficients (highest first) of the remainder of message(x)·x⁴ divided by g(x).
  • Codeword: c = d0 d1 d2 d3 p0 p1 p2 p3 (8 symbols).

This code corrects any 2 wrong symbols; or 4 symbols known to be unreadable ("erasures"); or 1 wrong symbol plus 2 erasures. It is the same construction used by QR codes and CDs, described in any coding-theory textbook (e.g. Lin & Costello, Error Control Coding).

4.5 Symbols to shape values

Each symbol becomes two shape values, the high 3 bits first: v[2i] = c_i >> 3, v[2i+1] = c_i AND 7, for i = 0…7. That gives 16 values v[0…15].

4.6 Whitening

Each value is XOR-ed with a fixed sequence:

W = 5 2 7 0 3 6 1 4 6 1 4 3 0 5 2 7
shape value in slot k = v[k] XOR W[k]

4.7 Test vectors

idpayloadscrambledcodeword c0…c7slot values 0…15
00x1000000x50050020 0 20 0 52 61 44 377 6 7 0 1 2 1 4 0 5 3 6 5 1 6 2
10x1000010xABDB5842 61 45 24 62 61 61 280 0 0 5 6 3 2 4 1 7 3 6 7 0 1 3
770x10004D0xEE2F0359 34 60 3 43 46 31 602 1 3 2 4 2 1 7 3 2 1 5 3 2 5 3
40210x100FB50x87D99433 61 38 20 53 60 58 291 3 0 5 7 0 3 0 0 4 3 7 7 7 1 2
655350x10FFFF0xD9238954 18 14 9 19 16 35 33 4 5 2 2 0 0 5 4 2 6 3 4 6 2 4
9000010x1DBBA10x0248210 36 32 33 26 10 52 15 2 3 4 7 6 5 5 5 3 5 1 6 1 2 6
10485750x1FFFFF0x442A5917 2 41 25 7 21 40 257 3 7 2 6 7 2 5 6 6 6 6 5 5 1 6

These vectors were checked against a second implementation written only from this text.

5. The medallion ornament

5.1 Geometry

All coordinates are in modules. The core is 29 × 29 (columns 0–28, rows 0–28). Above it is a 3-row head (rows −3 to −1). Total size: 29 wide × 32 tall.

With c = 14 (the centre), for each core cell (x, y) let d∞ = max(|x−c|, |y−c|) and d1 = |x−c| + |y−c|:

regionrulerole
innerd∞ ≤ 12 and d1 ≤ 23ground and the 16 slots
bandd∞ ≤ 13 and d1 ≤ 25, not innerframe band
outlined∞ ≤ 14 and d1 ≤ 27, not band or innerouter frame line
outsideeverything elsecarpet field

The slot grid: slot (row r, column q), r, q ∈ {0,1,2,3}, occupies core rows 3+6r … 7+6r and columns 3+6q … 7+6q. Between slots, and between the slots and the band, is one module of ground.

Map (O outline, = band, . ground, 0–f slot number in hexadecimal, ^ head):

     columns →
     01234567890123456789012345678
  -3   ^^^         ^         ^^^
  -2   ^ ^        ^^^        ^ ^
  -1     ^       ^ ^ ^       ^
   0  OOOOOOOOOOOOOOOOOOOOOOOOOOO
   1 OO=========================OO
   2 O==.......................==O
   3 O=.44444.55555.66666.77777.=O
   …    (rows 4–7 repeat row 3)
   8 O=.........................=O
   9 O=.fffff.00000.11111.88888.=O
   …
  14 O=.........................=O
  15 O=.eeeee.33333.22222.99999.=O
   …
  20 O=.........................=O
  21 O=.ddddd.ccccc.bbbbb.aaaaa.=O
   …
  26 O==.......................==O
  27 OO=========================OO
  28  OOOOOOOOOOOOOOOOOOOOOOOOOOO

5.2 Slot order

The 16 slot values (section 4.6) are placed in this order:

  • Ring 1 (the inner 2 × 2), clockwise from top-left: slots 0, 1, 2, 3.
  • Ring 2 (the outer 12), clockwise from top-left: slots 4 … 15.
   4   5   6   7
  15   0   1   8
  14   3   2   9
  13  12  11  10

Slots 2k and 2k+1 always come from the same Reed-Solomon symbol. They are neighbours, so a local defect (a stain, a fold) usually damages one symbol rather than two.

5.3 Head (orientation)

Rows −3 to −1, columns 2–26 (# = stitched, in a colour contrasting with the field):

###.........#.........###
#.#........###........#.#
..#.......#.#.#.......#..

The two outer motifs are ram's horns (qoçbuynuz), the centre is a finial. The head is only at the top, so it shows which way is up. A decoder may also find the orientation by trying all 8 rotations/reflections and keeping the one that decodes (section 8).

5.4 Placement rules

  • Clearance: at least 2 stitches of plain field around the whole ornament (head included), to the carpet's borders and to other ornaments.
  • Scale: at scale s every module is an s × s block of stitches. The minimum size for reliable phone reading is in section 7.
  • An ornament must be flat and fully visible. Folds and occlusion are tolerated only as far as error correction allows.

6. Colour and contrast

Colour never carries information: the same ornament may be made in any palette, and colours fade. Readers must use lightness (light vs dark) only. Rules (CIE L*, 0–100):

  1. Every shape differs from its ground by at least 30 L*.
  2. Both stripes of the frame band are lighter than, or both darker than, the outline and both slot grounds, by at least 20 L*. That way the band forms one closed ring.
  3. Within one slot, all motif stitches have one colour and all ground stitches one colour. Different slots may use different colours.

The WOVEN palettes (madder red, indigo, ivory, ochre, dark brown and weak-bath variants) are in xalcaid/palettes.py. They are suggestions, not part of the standard.

7. Minimum size for phone reading

Measured on synthetic photos, not on real stitched carpets (see xalcaid/benchmark_results_size.md).

Size in a photo is measured in pixels per module. On simulated whole-carpet phone photos (tilt up to 35°, folds, uneven light, clutter, 1% stitching errors):

px per modulebelow 22–33–44 and more
ornaments decoded20–60%about 80%89–100%92–97% (plateau)
  • Minimum: 4 px per module. Recommended: 5 px per module (25% margin).
  • In a 12 MP photo (3000 × 4000) of a 2:3 carpet filling about 90% of the frame, the carpet is about 2400 px wide, so the ornament should be at least 6% of the carpet width (absolute minimum 4.8%).
  • The ornament is never smaller than 29 × 32 stitches (scale 1), the limit for stitching 5 × 5 shapes by hand. Scale 1 therefore suffices for carpets up to about 480 stitches wide; wider carpets use scale 2 or more (scale = ⌈0.06 × carpet width ÷ 29⌉).

These numbers are from synthetic photos and must be re-measured on real stitched carpets.

8. Decoding

8.1 By hand

  1. Find the medallion with the 4 × 4 grid of small shapes and the horned head. Turn it so the head is at the top.
  2. For each of the 16 slots, in the order of section 5.2, write down the shape's value (section 3).
  3. Look the 16 values up in a printed WOVEN catalogue, which lists the shape sequence of every registered ID. If a few shapes are worn or unclear, choose the entry that differs in the fewest slots (at most 4 slots, at most 2 of the pairs 0–1, 2–3, …, 14–15).

8.2 By computer, simplest method (no Reed-Solomon decoder needed)

Read the 16 values (with "unknown" where unreadable). Compute the 16 values of every ID 0 … 1,048,575 (section 4) and pick the ID whose values differ in the fewest symbol pairs. Accept it only if at most 2 of the 8 pairs differ (not counting unknown pairs), and no other ID is equally close. About a million candidates: seconds on any computer.

8.3 By computer, from a photo (what the reference decoder does)

  1. Find candidate ornaments: square-ish regions with a frame (outline/band ring or a solid medallion shape against the field). The reference decoder combines contour analysis and a small neural detector trained on synthetic photos.
  2. For each candidate, estimate the perspective transform (homography) from the photo to the 29 × 29 module grid. Refine it until the ground cells around every slot are uniform and the slot cells are clearly light or dark.
  3. For each slot, compare the 5 × 5 cells to the 8 patterns, after normalising: ground lightness = median of the 24 cells surrounding the slot; motif = cells that differ from it.
  4. Try all 8 orientations (4 rotations, with and without mirroring: the back of a flat-weave shows the pattern mirrored). For each, run Reed-Solomon decoding, then unscramble and check that the version is 1.
  5. Accept a result only if re-encoding the ID explains the image: the same shape as observed in at least 12 of the 16 slots (13 if any symbol was treated as unreadable), and, comparing each slot's normalised 5 × 5 cells with the decoded shape, on average fewer than 6.5 of the 25 cells disagree. (On synthetic photos every false decode broke this rule.) Prefer the orientation in which the head (5.3) is at the top.
  6. Report every accepted ID with a confidence: high if at most 1 symbol needed correcting, ≥ 14 slots agree, fewer than 3 cells per slot disagree and the head confirms the orientation; medium if at most 2 symbols needed correcting, ≥ 13 slots agree and fewer than 5 cells per slot disagree; low otherwise.

9. Versions and future layouts

  • Version 1 = this document: medallion layout, 20-bit IDs.
  • A band layout (a strip of slots between two lines, for borders) is planned. It will use a different version number. Decoders must ignore versions they do not know.

10. What the ID means

Reserved IDs. IDs 0–999 are reserved for the system; records start at 1000.

  • ID 0 = legend. A medallion carrying ID 0 says only "this carpet follows the XalçaID open standard". It is meant to be stitched on the back or the edge of a carpet, usually next to the words "XALÇAID 1 / OPEN STANDARD" and a pointer to the archive (e.g. a DOI). A decoder that reads ID 0 should say so instead of looking up a record.
  • IDs 1–999 are unassigned and reserved for future system use.

The ID is only a number. Its meaning lives in the WOVEN registry, exported regularly to long-term archives (Zenodo, Internet Archive, GitHub releases; see archive/HOWTO.md). Each export contains every approved record with its ID, source, license and consent information, plus this specification and the decoder source code.

11. Licence

This specification: CC BY 4.0. Reference implementation: see the repository licence.