pixelati 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DMXL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# pixelati
+
+Turn any image into truecolor terminal art. pixelati renders pictures into the terminal using half-block characters, so each character cell shows two stacked pixels at full 24-bit colour, with transparent areas left blank.
+
+It works as both a command line tool and a small library, and it reads any format [sharp](https://sharp.pixelplumbing.com/) can decode (PNG, JPEG, WebP, GIF, AVIF, TIFF, and more).
+
+## Install
+
+As a CLI:
+
+```bash
+npm install -g pixelati
+pixelati <image>
+```
+
+As a library:
+
+```bash
+npm install pixelati
+```
+
+```ts
+import { renderToLines } from "pixelati";
+const lines = await renderToLines("logo.png", { width: 56 });
+console.log(lines.join("\n"));
+```
+
+This is an ESM-only package and needs Node 18 or newer.
+
+### Local development
+
+```bash
+pnpm install
+pnpm build       # compiles to dist/
+pnpm pixelati <image>   # run from source via tsx
+```
+
+## Usage
+
+```bash
+pixelati <image> [options]
+```
+
+| Option | Description |
+|---|---|
+| `-w, --width <n>` | Output width in columns. Defaults to the terminal width, or 80 when piped. |
+| `-t, --threshold <n>` | Alpha cutoff from 0 to 255. Pixels at or below it are treated as transparent. Default 128. |
+| `-b, --background <hex>` | Composite the image onto this colour instead of leaving transparent gaps (for example `#1e1e2e`). |
+| `-o, --output <file>` | Write the art to a file instead of printing it. |
+| `-h, --help` | Show help. |
+
+### Examples
+
+```bash
+pixelati logo.png                  # render at terminal width
+pixelati photo.jpg -w 60           # render 60 columns wide
+pixelati icon.png -b "#000000"     # composite onto black, no transparency
+pixelati banner.png -w 100 -o banner.ans   # save the escapes to a file
+```
+
+The height is derived from the width to preserve the image's aspect ratio, so you only ever set the width.
+
+## Library
+
+```ts
+import { renderToLines, renderToString } from "pixelati";
+
+// Array of ANSI strings, one per text row.
+const lines = await renderToLines("logo.png", { width: 56 });
+console.log(lines.join("\n"));
+
+// Or the whole thing as one string.
+const art = await renderToString("logo.png", { width: 56, background: "#101018" });
+```
+
+`renderToLines` and `renderToString` accept a file path or a `Buffer`, plus the same options as the CLI (`width`, `threshold`, `background`). Returning lines as an array is handy for baking the art into a generated source file, so a program can ship the rendered banner without any image dependency at runtime.
+
+## How it works
+
+The short version: a terminal cell is about twice as tall as it is wide, and ANSI lets you set a foreground and a background colour per cell independently. The `▀` (upper half block) paints the top half of the cell with the foreground while the background shows through the bottom half, so one character carries two vertically stacked pixels. That doubles vertical resolution, and truecolor escapes give each pixel any of 16 million colours. Transparent pixels become blanks so the terminal background shows through.
+
+For the full walkthrough (downscaling, the transparency cases, aspect ratio, and how to verify the output visually) see [docs/how-it-works.md](./docs/how-it-works.md).
+
+## Requirements
+
+Node.js 18 or newer, and a terminal with truecolor support (most modern terminals: iTerm2, the macOS Terminal in recent versions, Windows Terminal, kitty, Alacritty, WezTerm, and others).
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import { writeFile } from "node:fs/promises";
+import { renderToLines } from "./render.js";
+const HELP = `pixelati — turn any image into truecolor terminal art
+
+Usage:
+  pixelati <image> [options]
+
+Options:
+  -w, --width <n>        Output width in columns (default: terminal width or 80)
+  -t, --threshold <n>    Alpha cutoff 0-255; at or below is transparent (default: 128)
+  -b, --background <hex> Composite onto this colour instead of leaving gaps (e.g. #1e1e2e)
+  -o, --output <file>    Write the art to a file instead of stdout
+  -h, --help             Show this help
+
+Examples:
+  pixelati logo.png
+  pixelati photo.jpg -w 60
+  pixelati icon.png -b "#000000"
+  pixelati banner.png -w 100 -o banner.ans
+`;
+function parseArgs(argv) {
+    const args = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const next = () => {
+            const v = argv[++i];
+            if (v === undefined)
+                throw new Error(`Missing value for ${a}`);
+            return v;
+        };
+        switch (a) {
+            case "-h":
+            case "--help":
+                args.help = true;
+                break;
+            case "-w":
+            case "--width":
+                args.width = Number(next());
+                break;
+            case "-t":
+            case "--threshold":
+                args.threshold = Number(next());
+                break;
+            case "-b":
+            case "--background":
+                args.background = next();
+                break;
+            case "-o":
+            case "--output":
+                args.output = next();
+                break;
+            default:
+                if (a.startsWith("-"))
+                    throw new Error(`Unknown option: ${a}`);
+                if (args.input)
+                    throw new Error(`Unexpected extra argument: ${a}`);
+                args.input = a;
+        }
+    }
+    return args;
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help || !args.input) {
+        process.stdout.write(HELP);
+        process.exit(args.input ? 0 : 1);
+    }
+    if (args.width !== undefined && (!Number.isFinite(args.width) || args.width < 1)) {
+        throw new Error("--width must be a positive number");
+    }
+    if (args.threshold !== undefined &&
+        (!Number.isFinite(args.threshold) || args.threshold < 0 || args.threshold > 255)) {
+        throw new Error("--threshold must be between 0 and 255");
+    }
+    const opts = {
+        width: args.width ?? process.stdout.columns ?? 80,
+        threshold: args.threshold,
+        background: args.background,
+    };
+    const lines = await renderToLines(args.input, opts);
+    if (args.output) {
+        await writeFile(args.output, lines.join("\n") + "\n");
+        process.stderr.write(`Wrote ${lines.length} rows to ${args.output}\n`);
+    }
+    else {
+        process.stdout.write(lines.join("\n") + "\n");
+    }
+}
+main().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`pixelati: ${msg}\n`);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { renderToLines, renderToString, parseHex } from "./render.js";
+export type { RenderOptions } from "./render.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+// Public library surface. Import these to render images to terminal art from
+// your own code; the CLI in cli.ts is a thin wrapper over them.
+export { renderToLines, renderToString, parseHex } from "./render.js";

package/dist/render.d.ts

@@ -0,0 +1,28 @@
+export interface RenderOptions {
+    /** Target width in terminal columns (one column per source pixel). */
+    width?: number;
+    /** Alpha cutoff (0-255). Pixels at or below this are treated as transparent. */
+    threshold?: number;
+    /**
+     * Hex colour (e.g. "#1e1e2e") to composite the image onto. When set, the
+     * result is fully opaque (no transparent gaps); when omitted, transparent
+     * pixels render as blanks.
+     */
+    background?: string;
+}
+interface RGBA {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** Parse "#rgb" or "#rrggbb" (with or without the leading #) into an RGBA. */
+export declare function parseHex(hex: string): RGBA;
+/**
+ * Render an image (any format sharp can decode) to an array of ANSI lines, one
+ * string per text row. Two image rows are encoded per line via half blocks.
+ */
+export declare function renderToLines(input: string | Buffer, opts?: RenderOptions): Promise<string[]>;
+/** Convenience wrapper returning the rendered art as a single string. */
+export declare function renderToString(input: string | Buffer, opts?: RenderOptions): Promise<string>;
+export {};

package/dist/render.js

@@ -0,0 +1,110 @@
+import sharp from "sharp";
+const RESET = "\x1b[0m";
+const UPPER_HALF = "▀";
+const LOWER_HALF = "▄";
+const fg = (p) => `\x1b[38;2;${p.r};${p.g};${p.b}m`;
+const bg = (p) => `\x1b[48;2;${p.r};${p.g};${p.b}m`;
+const DEFAULT_WIDTH = 80;
+const DEFAULT_THRESHOLD = 128;
+/** Parse "#rgb" or "#rrggbb" (with or without the leading #) into an RGBA. */
+export function parseHex(hex) {
+    let h = hex.trim().replace(/^#/, "");
+    if (h.length === 3)
+        h = h.split("").map((c) => c + c).join("");
+    if (!/^[0-9a-fA-F]{6}$/.test(h)) {
+        throw new Error(`Invalid hex colour: "${hex}"`);
+    }
+    return {
+        r: parseInt(h.slice(0, 2), 16),
+        g: parseInt(h.slice(2, 4), 16),
+        b: parseInt(h.slice(4, 6), 16),
+        a: 255,
+    };
+}
+/** Alpha-composite `top` over the opaque `base`. */
+function composite(top, base) {
+    const a = top.a / 255;
+    return {
+        r: Math.round(top.r * a + base.r * (1 - a)),
+        g: Math.round(top.g * a + base.g * (1 - a)),
+        b: Math.round(top.b * a + base.b * (1 - a)),
+        a: 255,
+    };
+}
+/**
+ * Render an image (any format sharp can decode) to an array of ANSI lines, one
+ * string per text row. Two image rows are encoded per line via half blocks.
+ */
+export async function renderToLines(input, opts = {}) {
+    const width = Math.max(1, Math.floor(opts.width ?? DEFAULT_WIDTH));
+    const threshold = opts.threshold ?? DEFAULT_THRESHOLD;
+    const base = opts.background ? parseHex(opts.background) : null;
+    const pipeline = sharp(input);
+    const meta = await pipeline.metadata();
+    if (!meta.width || !meta.height) {
+        throw new Error("Could not read image dimensions.");
+    }
+    // Preserve aspect ratio. Each pixel is one column wide and (paired) one text
+    // row holds two pixels, so square pixels keep the picture's proportions.
+    let height = Math.max(2, Math.round(width * (meta.height / meta.width)));
+    if (height % 2 === 1)
+        height += 1; // even rows pair cleanly into half blocks
+    const { data, info } = await pipeline
+        .resize(width, height, { fit: "fill" })
+        .ensureAlpha()
+        .raw()
+        .toBuffer({ resolveWithObject: true });
+    const cols = info.width;
+    const rows = info.height;
+    const at = (x, y) => {
+        const i = (y * cols + x) * info.channels;
+        return { r: data[i], g: data[i + 1], b: data[i + 2], a: data[i + 3] };
+    };
+    const opaque = (p) => p.a > threshold;
+    const lines = [];
+    for (let y = 0; y + 1 < rows; y += 2) {
+        let line = "";
+        let pendingBlanks = "";
+        for (let x = 0; x < cols; x++) {
+            let top = at(x, y);
+            let bottom = at(x, y + 1);
+            if (base) {
+                // Composite over the background: every cell becomes opaque.
+                const t = composite(top, base);
+                const b = composite(bottom, base);
+                line += `${fg(t)}${bg(b)}${UPPER_HALF}${RESET}`;
+                continue;
+            }
+            const topOn = opaque(top);
+            const bottomOn = opaque(bottom);
+            let cell;
+            if (!topOn && !bottomOn) {
+                cell = " ";
+            }
+            else if (topOn && bottomOn) {
+                cell = `${fg(top)}${bg(bottom)}${UPPER_HALF}${RESET}`;
+            }
+            else if (topOn) {
+                cell = `${fg(top)}${UPPER_HALF}${RESET}`;
+            }
+            else {
+                cell = `${fg(bottom)}${LOWER_HALF}${RESET}`;
+            }
+            // Defer runs of blanks so a transparent right edge does not bloat the
+            // line with trailing spaces, while interior gaps stay aligned.
+            if (cell === " ") {
+                pendingBlanks += " ";
+            }
+            else {
+                line += pendingBlanks + cell;
+                pendingBlanks = "";
+            }
+        }
+        lines.push(line);
+    }
+    return lines;
+}
+/** Convenience wrapper returning the rendered art as a single string. */
+export async function renderToString(input, opts = {}) {
+    return (await renderToLines(input, opts)).join("\n");
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "pixelati",
+  "version": "0.1.0",
+  "description": "Turn any image into truecolor terminal art using half-block characters.",
+  "type": "module",
+  "bin": {
+    "pixelati": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "pixelati": "tsx src/cli.ts",
+    "start": "tsx src/cli.ts",
+    "prepublishOnly": "tsc"
+  },
+  "keywords": [
+    "terminal",
+    "ansi",
+    "image",
+    "ascii-art",
+    "cli",
+    "truecolor",
+    "half-block"
+  ],
+  "author": "DMXL",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DMXL/pixelati.git"
+  },
+  "homepage": "https://github.com/DMXL/pixelati#readme",
+  "bugs": {
+    "url": "https://github.com/DMXL/pixelati/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "packageManager": "pnpm@10.9.0",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "sharp": "^0.34.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.0"
+  }
+}