pixmap-engine 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pkill -f \"next dev\")",
+      "Read(//private/tmp/**)",
+      "Bash(npm rebuild:*)",
+      "Bash(rm:*)",
+      "Bash(grep:*)",
+      "Bash(npm uninstall:*)",
+      "Bash(npm run:*)",
+      "Bash(npm link:*)",
+      "Bash(pixmap status:*)"
+    ]
+  }
+}

package/README.md

@@ -0,0 +1,103 @@
+# pixmap
+
+Local image similarity search using CLIP embeddings, HNSW indexing, and SQLite. Everything runs on your machine — no cloud, no API keys, your images stay private.
+
+## Install
+
+```bash
+npm install pixmap
+```
+
+Requires Node.js 18+. Native modules (`sharp`, `better-sqlite3`, `hnswlib-node`) compile during install.
+
+## Usage
+
+### Command Line
+
+```bash
+pixmap add ./photo.jpg            # index a single image
+pixmap add ./photos/              # index a directory (recursive)
+pixmap search ./query.jpg         # find similar images
+pixmap search ./query.jpg -k 10   # return more results
+pixmap list                       # show indexed images
+pixmap status                     # index stats
+```
+### Terminal View
+<img src="https://github.com/user-attachments/assets/0cfc7f0f-86b5-4a80-baaa-10feb28f811e" width="580" alt="Image"/>
+
+
+### As a library
+
+```typescript
+import { PixmapEngine } from "pixmap";
+
+const engine = new PixmapEngine({ dataDir: "./data" });
+await engine.init();
+
+await engine.add("./photos/dog.jpg");
+await engine.add("./photos/cat.png");
+
+const results = await engine.search("./query.jpg", 5);
+
+for (const r of results) {
+  console.log(`${r.path} — ${(r.score * 100).toFixed(1)}%`);
+}
+```
+
+Options:
+
+- `-d, --data-dir <path>` — where to store index and db (default: `./data`)
+- `-k, --top-k <n>` — number of results (default: `5`)
+
+## API
+
+### `new PixmapEngine(options)`
+
+```typescript
+{
+  dataDir: string;          // where to store index.hnsw and metadata.db
+  indexFileName?: string;   // default: "index.hnsw"
+  dbFileName?: string;      // default: "metadata.db"
+}
+```
+
+### Methods
+
+- `**init()**` — loads the CLIP model, opens or creates the HNSW index and SQLite db. Must be called before anything else.
+- `**add(imagePath)**` — indexes an image. Returns `{ id, skipped, record }`. If the image was already indexed, `skipped` is `true`.
+- `**search(imagePath, topK?)**` — embeds the query image and returns the top-K most similar indexed images. Default K is 5.
+- `**listImages(limit?)**` — returns indexed images, newest first.
+- `**getImage(id)**` — look up a single image by its id.
+- `**getIndexedCount()**` — total number of indexed images.
+
+## How it works
+
+Each image is resized to 224x224 with Sharp, run through a CLIP vision model (ViT-B/32, via ONNX), producing a 512-dimensional embedding vector. That vector goes into an HNSW index for fast nearest-neighbor lookup. File paths, IDs, and timestamps are tracked in a SQLite database.
+
+Searching works the same way: embed the query image, ask HNSW for the closest vectors, look up the metadata.
+
+See [docs/HOW.md](docs/HOW.md) for the full technical breakdown.
+
+## What gets stored
+
+Everything lives in your `dataDir`:
+
+- `index.hnsw` — the vector index (binary, hnswlib format)
+- `metadata.db` — SQLite database with image paths and metadata
+
+About ~2KB per indexed image. A 100K image index is roughly 220MB.
+
+## Supported formats
+
+JPEG, PNG, WebP, BMP, GIF, AVIF, TIFF — anything Sharp can read.
+
+## Dependencies
+
+- `[@xenova/transformers](https://github.com/xenova/transformers.js)` — runs the CLIP model locally via ONNX
+- `[sharp](https://github.com/lovell/sharp)` — image resize and preprocessing
+- `[hnswlib-node](https://github.com/yoshoku/hnswlib-node)` — approximate nearest neighbor index
+- `[better-sqlite3](https://github.com/WiseLibs/better-sqlite3)` — metadata storage
+
+## License
+
+MIT

package/dist/embedder.js

@@ -0,0 +1,75 @@
+import sharp from 'sharp';
+import { RawImage, pipeline } from '@xenova/transformers';
+import { VECTOR_DIMENSIONS } from './types.js';
+export class ImageEmbedder {
+    extractor = null;
+    async init() {
+        this.extractor = (await pipeline('image-feature-extraction', 'Xenova/clip-vit-base-patch32'));
+    }
+    async embed(imagePath) {
+        if (!this.extractor) {
+            throw new Error('ImageEmbedder is not initialized. Call init() first.');
+        }
+        const preprocessed = await sharp(imagePath)
+            .resize(224, 224, { fit: 'cover' })
+            .removeAlpha()
+            .toFormat('png')
+            .toBuffer();
+        const image = await this.bufferToRawImage(preprocessed);
+        const output = await this.extractor(image);
+        const vector = this.extractVector(output);
+        if (vector.length !== VECTOR_DIMENSIONS) {
+            throw new Error(`Unexpected embedding dimensions: ${vector.length}. Expected ${VECTOR_DIMENSIONS}.`);
+        }
+        return this.l2Normalize(vector);
+    }
+    async bufferToRawImage(buffer) {
+        const raw = RawImage;
+        if (typeof raw.fromBlob === 'function') {
+            const view = Uint8Array.from(buffer);
+            return raw.fromBlob(new Blob([view], { type: 'image/png' }));
+        }
+        if (typeof raw.fromBuffer === 'function') {
+            return raw.fromBuffer(buffer);
+        }
+        if (typeof raw.read === 'function') {
+            return raw.read(buffer);
+        }
+        throw new Error('No compatible RawImage constructor found in @xenova/transformers.');
+    }
+    extractVector(output) {
+        let data;
+        if (output instanceof Float32Array) {
+            data = output;
+        }
+        else if (Array.isArray(output) && output.every((x) => typeof x === 'number')) {
+            data = output;
+        }
+        else if (typeof output === 'object' && output !== null) {
+            const maybeObject = output;
+            if (maybeObject.data) {
+                data = maybeObject.data;
+            }
+            else if (Array.isArray(output)) {
+                const first = output[0];
+                data = first?.data;
+            }
+        }
+        if (!data) {
+            throw new Error('Failed to extract vector data from model output.');
+        }
+        return data instanceof Float32Array ? data : new Float32Array(data);
+    }
+    l2Normalize(vector) {
+        let sumSquares = 0;
+        for (let i = 0; i < vector.length; i += 1) {
+            sumSquares += vector[i] * vector[i];
+        }
+        const norm = Math.sqrt(sumSquares) || 1;
+        const normalized = new Float32Array(vector.length);
+        for (let i = 0; i < vector.length; i += 1) {
+            normalized[i] = vector[i] / norm;
+        }
+        return normalized;
+    }
+}

package/dist/engine.js

@@ -0,0 +1,66 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_TOP_K } from './types.js';
+export class PixmapEngine {
+    dataDir;
+    indexPath;
+    dbPath;
+    embedder = null;
+    store = null;
+    db = null;
+    constructor(options) {
+        this.dataDir = path.resolve(options.dataDir);
+        this.indexPath = path.join(this.dataDir, options.indexFileName ?? 'index.hnsw');
+        this.dbPath = path.join(this.dataDir, options.dbFileName ?? 'metadata.db');
+    }
+    async init() {
+        fs.mkdirSync(this.dataDir, { recursive: true });
+        const [{ ImageEmbedder }, { VectorStore }, { MetadataDb }] = await Promise.all([
+            import('./embedder.js'),
+            import('./vectorStore.js'),
+            import('./metadataDb.js'),
+        ]);
+        this.embedder = new ImageEmbedder();
+        await this.embedder.init();
+        this.store = new VectorStore();
+        this.store.initOrLoad(this.indexPath);
+        this.db = new MetadataDb(this.dbPath);
+    }
+    async add(imagePath) {
+        this.assertInitialized();
+        const absolute = path.resolve(imagePath);
+        const { addImage } = await import('./indexer.js');
+        const result = await addImage(absolute, this.embedder, this.store, this.db);
+        this.store.save(this.indexPath);
+        return {
+            ...result,
+            record: this.db.get(result.id),
+        };
+    }
+    async search(queryImagePath, topK = DEFAULT_TOP_K) {
+        this.assertInitialized();
+        const absolute = path.resolve(queryImagePath);
+        if (this.store.getCount() === 0) {
+            return [];
+        }
+        const { findSimilar } = await import('./searcher.js');
+        return findSimilar(absolute, this.embedder, this.store, this.db, topK);
+    }
+    listImages(limit = 200) {
+        this.assertInitialized();
+        return this.db.list(limit);
+    }
+    getImage(id) {
+        this.assertInitialized();
+        return this.db.get(id);
+    }
+    getIndexedCount() {
+        this.assertInitialized();
+        return this.store.getCount();
+    }
+    assertInitialized() {
+        if (!this.embedder || !this.store || !this.db) {
+            throw new Error('PixmapEngine not initialized. Call init() first.');
+        }
+    }
+}

package/dist/index.js

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { ImageEmbedder } from './embedder.js';
+import { addImage } from './indexer.js';
+import { MetadataDb } from './metadataDb.js';
+import { renderImage, renderImageRow } from './preview.js';
+import { findSimilar } from './searcher.js';
+import { DEFAULT_TOP_K } from './types.js';
+import { VectorStore } from './vectorStore.js';
+const IMAGE_EXTENSIONS = new Set(['.jpg', '.jpeg', '.png', '.webp', '.bmp', '.gif', '.avif', '.tiff']);
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+        printUsage();
+        return;
+    }
+    const command = args[0];
+    const rest = args.slice(1);
+    const options = parseOptions(rest);
+    const dataDir = path.resolve(options.dataDir);
+    fs.mkdirSync(dataDir, { recursive: true });
+    const dbPath = path.join(dataDir, 'metadata.db');
+    const indexPath = path.join(dataDir, 'index.hnsw');
+    if (command === 'list') {
+        const db = new MetadataDb(dbPath);
+        const images = db.list(200);
+        if (images.length === 0) {
+            console.log('No indexed images.');
+            return;
+        }
+        console.log(`\n  Indexed images (${images.length}):\n`);
+        for (const img of images) {
+            const date = new Date(img.created * 1000).toISOString().slice(0, 19);
+            const name = path.basename(img.path);
+            console.log(`  [${img.id}]  ${date}  ${name}`);
+        }
+        console.log();
+        return;
+    }
+    if (command === 'show') {
+        const target = rest.find((x) => !x.startsWith('--'));
+        if (!target) {
+            console.error('Error: Provide an image path or id.\n');
+            process.exitCode = 1;
+            return;
+        }
+        let imagePath;
+        const asId = Number(target);
+        if (Number.isFinite(asId) && asId > 0) {
+            const db = new MetadataDb(dbPath);
+            const record = db.get(asId);
+            if (!record) {
+                console.error(`Error: No image with id ${asId}`);
+                process.exitCode = 1;
+                return;
+            }
+            imagePath = record.path;
+        }
+        else {
+            imagePath = path.resolve(target);
+        }
+        assertImageExists(imagePath);
+        console.log();
+        const preview = await renderImage(imagePath);
+        console.log(preview);
+        console.log(`    ${path.basename(imagePath)}\n`);
+        return;
+    }
+    if (command === 'status') {
+        const db = new MetadataDb(dbPath);
+        const store = new VectorStore();
+        store.initOrLoad(indexPath);
+        const images = db.list(999999);
+        console.log(`\n  pixmap status`);
+        console.log(`  data dir:   ${dataDir}`);
+        console.log(`  vectors:    ${store.getCount()}`);
+        console.log(`  images:     ${images.length}`);
+        console.log();
+        return;
+    }
+    // Commands below require the embedder
+    console.log('Loading CLIP model...');
+    const embedder = new ImageEmbedder();
+    await embedder.init();
+    const store = new VectorStore();
+    store.initOrLoad(indexPath);
+    const db = new MetadataDb(dbPath);
+    if (command === 'add') {
+        const targets = rest.filter((x) => !x.startsWith('--'));
+        if (targets.length === 0) {
+            console.error('Error: No image path provided.\n');
+            printUsage();
+            process.exitCode = 1;
+            return;
+        }
+        let added = 0;
+        let skipped = 0;
+        for (const target of targets) {
+            const absolutePath = path.resolve(target);
+            const stat = safeStat(absolutePath);
+            if (!stat) {
+                console.error(`  skip: not found — ${absolutePath}`);
+                continue;
+            }
+            const files = stat.isDirectory() ? walkImages(absolutePath) : [absolutePath];
+            for (const file of files) {
+                const result = await addImage(file, embedder, store, db);
+                if (result.skipped) {
+                    skipped += 1;
+                    console.log(`  skip: already indexed — ${path.basename(file)}`);
+                }
+                else {
+                    added += 1;
+                    console.log(`  added: id=${result.id} — ${path.basename(file)}`);
+                }
+            }
+        }
+        store.save(indexPath);
+        console.log(`\nDone. added=${added} skipped=${skipped}`);
+        return;
+    }
+    if (command === 'search' || command === 'similar') {
+        const imagePath = rest.find((x) => !x.startsWith('--'));
+        if (!imagePath) {
+            console.error('Error: No query image provided.\n');
+            printUsage();
+            process.exitCode = 1;
+            return;
+        }
+        const absolutePath = path.resolve(imagePath);
+        assertImageExists(absolutePath);
+        if (store.getCount() === 0) {
+            console.log('Index is empty. Add images first with: pixmap add <path>');
+            return;
+        }
+        // Show query image preview
+        console.log(`\n  Query:\n`);
+        const queryPreview = await renderImage(absolutePath, undefined, 20);
+        console.log(queryPreview);
+        console.log(`    ${path.basename(absolutePath)}\n`);
+        const results = await findSimilar(absolutePath, embedder, store, db, options.topK);
+        if (results.length === 0) {
+            console.log('  No similar images found.\n');
+            return;
+        }
+        console.log(`  ── Results (${results.length}) ──\n`);
+        const PER_ROW = 3;
+        for (let i = 0; i < results.length; i += PER_ROW) {
+            const batch = results.slice(i, i + PER_ROW);
+            const panels = batch
+                .map((r, j) => {
+                const pct = (r.score * 100).toFixed(1);
+                const name = path.basename(r.path);
+                return fs.existsSync(r.path)
+                    ? { label: `#${i + j + 1}  ${pct}%  ${name}`, imagePath: r.path }
+                    : null;
+            })
+                .filter((p) => p !== null);
+            if (panels.length > 0) {
+                const row = await renderImageRow(panels);
+                console.log(row);
+                console.log();
+            }
+        }
+        return;
+    }
+    console.error(`Unknown command: ${command}\n`);
+    printUsage();
+    process.exitCode = 1;
+}
+function parseOptions(args) {
+    let dataDir = 'data';
+    let topK = DEFAULT_TOP_K;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === '--data-dir' || arg === '-d') {
+            dataDir = args[i + 1] ?? dataDir;
+            i += 1;
+            continue;
+        }
+        if (arg === '--top-k' || arg === '-k') {
+            const parsed = Number(args[i + 1]);
+            if (!Number.isNaN(parsed) && parsed > 0) {
+                topK = Math.floor(parsed);
+            }
+            i += 1;
+            continue;
+        }
+    }
+    return { dataDir, topK };
+}
+function walkImages(rootDir) {
+    const result = [];
+    const stack = [rootDir];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            continue;
+        const entries = fs.readdirSync(current, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(fullPath);
+                continue;
+            }
+            const ext = path.extname(entry.name).toLowerCase();
+            if (IMAGE_EXTENSIONS.has(ext)) {
+                result.push(fullPath);
+            }
+        }
+    }
+    return result.sort();
+}
+function safeStat(p) {
+    try {
+        return fs.statSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+function assertImageExists(imagePath) {
+    if (!fs.existsSync(imagePath)) {
+        throw new Error(`File not found: ${imagePath}`);
+    }
+    if (!fs.statSync(imagePath).isFile()) {
+        throw new Error(`Not a file: ${imagePath}`);
+    }
+}
+function printUsage() {
+    console.log(`
+  pixmap — local image similarity search
+
+  Usage:
+    pixmap add <image|dir> [...]     Add image(s) or directory to the index
+    pixmap search <image> [-k N]     Find similar indexed images
+    pixmap show <image|id>           Preview an image in the terminal
+    pixmap list                      Show all indexed images
+    pixmap status                    Show index stats
+
+  Options:
+    -d, --data-dir <path>   Data directory (default: ./data)
+    -k, --top-k <number>    Number of results (default: ${DEFAULT_TOP_K})
+    -h, --help              Show this help
+
+  Examples:
+    pixmap add photo.jpg
+    pixmap add ./photos/
+    pixmap search query.png -k 10
+    pixmap show 3
+    pixmap list
+`);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Error: ${message}`);
+    process.exitCode = 1;
+});

package/dist/indexer.js

@@ -0,0 +1,10 @@
+export async function addImage(imagePath, embedder, store, db) {
+    const record = db.upsert(imagePath);
+    if (record.indexed) {
+        return { id: record.id, skipped: true };
+    }
+    const vector = await embedder.embed(imagePath);
+    store.add(record.id, vector);
+    db.markIndexed(record.id);
+    return { id: record.id, skipped: false };
+}

package/dist/metadataDb.js

@@ -0,0 +1,69 @@
+import Database from 'better-sqlite3';
+export class MetadataDb {
+    db;
+    constructor(path) {
+        this.db = new Database(path);
+        this.db.pragma('journal_mode = WAL');
+        this.migrateSchema();
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS images (
+        id       INTEGER PRIMARY KEY AUTOINCREMENT,
+        path     TEXT NOT NULL UNIQUE,
+        indexed  INTEGER NOT NULL DEFAULT 0,
+        created  INTEGER NOT NULL DEFAULT (strftime('%s','now'))
+      )
+    `);
+    }
+    upsert(path) {
+        const existing = this.findByPath(path);
+        if (existing) {
+            return { id: existing.id, indexed: existing.indexed === 1 };
+        }
+        const result = this.db.prepare('INSERT INTO images (path, indexed) VALUES (?, 0)').run(path);
+        return { id: Number(result.lastInsertRowid), indexed: false };
+    }
+    markIndexed(id) {
+        this.db.prepare('UPDATE images SET indexed = 1 WHERE id = ?').run(id);
+    }
+    get(id) {
+        return this.db.prepare('SELECT * FROM images WHERE id = ?').get(id);
+    }
+    list(limit = 200) {
+        return this.db
+            .prepare('SELECT * FROM images WHERE indexed = 1 ORDER BY created DESC, id DESC LIMIT ?')
+            .all(limit);
+    }
+    findByPath(path) {
+        return this.db.prepare('SELECT * FROM images WHERE path = ?').get(path);
+    }
+    migrateSchema() {
+        const exists = this.db
+            .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'images'")
+            .get();
+        if (!exists) {
+            return;
+        }
+        const columns = this.db
+            .prepare("PRAGMA table_info('images')")
+            .all();
+        const allowed = new Set(['id', 'path', 'indexed', 'created']);
+        const isCurrentSchema = columns.length === allowed.size && columns.every((c) => allowed.has(c.name));
+        if (isCurrentSchema) {
+            return;
+        }
+        this.db.exec(`
+      BEGIN;
+      CREATE TABLE images_new (
+        id       INTEGER PRIMARY KEY AUTOINCREMENT,
+        path     TEXT NOT NULL UNIQUE,
+        indexed  INTEGER NOT NULL DEFAULT 0,
+        created  INTEGER NOT NULL DEFAULT (strftime('%s','now'))
+      );
+      INSERT INTO images_new (id, path, indexed, created)
+      SELECT id, path, indexed, created FROM images;
+      DROP TABLE images;
+      ALTER TABLE images_new RENAME TO images;
+      COMMIT;
+    `);
+    }
+}