semantic-uuid

Transform UUIDs into memorable 4-square visual patterns with quantized colors and emojis.

Installation

npm install semantic-uuid

Usage

const SemanticUUID = require('semantic-uuid');

const semantic = new SemanticUUID();

// Generate semantic representation
const uuid = '4419b29f-9ff0-4ec2-a0db-d370f4134f68';
const result = semantic.generate(uuid);

console.log(result);
// {
//   originalColors: ['#4419b2', '#9f9ff0', ...],
//   quantizedColors: ['#4419b2', '#9f9ff0', '#a0dbd3', '#70f413'],
//   emojis: ['🎨', '🦄', '🍕', '🚀'],
//   squares: [
//     { color: '#4419b2', emoji: '🎨', position: 0 },
//     { color: '#9f9ff0', emoji: '🦄', position: 1 },
//     { color: '#a0dbd3', emoji: '🍕', position: 2 },
//     { color: '#70f413', emoji: '🚀', position: 3 }
//   ]
// }

// Generate HTML
const html = semantic.toHTML(uuid, { size: 120, fontSize: 60 });
document.body.innerHTML = html;

// Generate ASCII art
console.log(semantic.toASCII(uuid));
// UUID: 4419b29f-9ff0-4ec2-a0db-d370f4134f68
// Colors: #4419b2, #9f9ff0, #a0dbd3, #70f413
// Emojis: 🎨 🦄 🍕 🚀
// 
// ┌─────┬─────┐
// │ 🎨  │ 🦄  │
// ├─────┼─────┤
// │ 🍕  │ 🚀  │
// └─────┴─────┘

// Generate random UUID
const randomUUID = semantic.generateRandomUUID();
console.log(semantic.generate(randomUUID));

API

new SemanticUUID()

Creates a new instance.

generate(uuid: string): SemanticResult

Generate the complete semantic representation.

generateRandomUUID(): string

Generate a random UUID v4.

toHTML(uuid: string, options?: HTMLOptions): string

Generate HTML representation.

toASCII(uuid: string): string

Generate ASCII art representation.

How it works

1. Extract colors: Parse UUID hex values into 16 colors
2. Quantize: Use k-means clustering to find 4 dominant colors
3. Generate emojis: Map hex groups to emojis from 300+ emoji database
4. Create pattern: Arrange in 2×2 grid for maximum memorability

Each UUID produces a unique, deterministic, memorable visual pattern.