Dictionaries

Two tables that give every byte a name

A dictionary is an ordered list of colours and an ordered list of glyphs whose product is 256. Byte b takes glyph b mod m and colour (b - glyph) / m. The dictionary id is written into every SVG, so a picture always says which table decodes it.

Two dictionaries ship with the library. Both have 8 colours and 32 glyphs, so in both the colour is the top 3 bits of the byte and the glyph the low 5. Every cell below is rendered on this page by the library, with its hex on the tile. Hover or tap a cell for its spoken name.

• sa330
• fa330
• Make your own

Make your own

A dictionary is a plain object. Register it once, then use its id in any option bag. The registry enforces four rules:

• colors.length * glyphs.length must equal 256. 8 x 32, 16 x 16, 4 x 64 and 2 x 128 all work; fewer glyphs means more colours to tell apart.
• Ids and names are lowercase [a-z0-9-]. Names are unique within their list. Ids starting with sa are reserved for ShapeAddress.
• A glyph is either svg markup drawn in a 100 x 100 box, or a single path d with its own box, which the registry scales and centres to fit.
• An id names its exact glyphs and colours forever. Change one glyph and you have a new dictionary with a new id. Registering a different object under a taken id throws.

const acme16 = {
  id: 'acme-16',
  version: 1,
  name: 'Acme 16 x 16',
  author: 'Acme Design',
  license: 'MIT',
  colors: [
    { name: 'red', hex: '#c92a2a' },
    { name: 'orange', hex: '#e8590c' },
    // 14 more: 16 colours
  ],
  glyphs: [
    { name: 'circle', svg: '<circle cx="50" cy="50" r="34"/>' },            // markup in a 100 x 100 box
    { name: 'bolt', d: 'M349.4 44.6c5.9-13.7 1.5-29.7…', box: [448, 512] },  // or a path in its own box
    // 14 more: 16 glyphs, 16 x 16 = 256
  ],
};

shapeaddress.dictionaries.register(acme16);

shapeaddress('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', { dictionary: 'acme-16' });
shapeaddress.legend('0x00', { dictionary: 'acme-16' });   // ['red circle']
shapeaddress.dictionaries.list();                          // [{ id: 'sa330', … }, { id: 'acme-16', name: 'Acme 16 x 16', colors: 16, glyphs: 16, license: 'MIT' }]

Glyphs should read at 48 px as white silhouettes on a tile and as coloured silhouettes on a plain ground, so prefer solid, single-weight shapes over outlines. Colours should stay apart under common colour-vision deficiencies; the cvd palette adds a hatch per colour index, but the base hues do the most work.

Ship the object as its own file and the React component, the web component and a self-hosted API server pick it up through the same dictionary option. The public API at shapeaddress.com serves only the dictionaries listed above. Decoding works wherever the dictionary is registered: the SVG carries the id, not the tables.