termpic 0.0.0

package/README.md

@@ -0,0 +1,85 @@
+# termpic
+
+画像をターミナルの絵に変換する。ASCII の濃淡、半ブロックの色マス、パレット量子化に対応。依存は [contrast-kit](https://www.npmjs.com/package/contrast-kit) のみ。
+
+```bash
+npm i termpic
+```
+
+```ts
+import { convert, toHtml, toSvg, toText, toAnsi } from "termpic";
+
+// bitmap は { width, height, data }（ブラウザの ImageData と同じ形）
+const grid = convert(bitmap, { mode: "halfblock", cols: 60 });
+
+toHtml(grid, { alt: "自画像" }); // <pre> と <span>
+toSvg(grid, { cellSize: 8 }); // 矩形だけの SVG（フォント非依存）
+toText(grid); // 素のテキスト（ascii モード向け）
+toAnsi(grid); // そのままターミナルに貼れる
+```
+
+## オプション
+
+|              | 既定           | 説明                                               |
+| ------------ | -------------- | -------------------------------------------------- |
+| `mode`       | `"halfblock"`  | `ascii` は濃淡の文字、`halfblock` は1マスに上下2色 |
+| `cols`       | `60`           | 横のマス数                                         |
+| `ramp`       | `" .:-=+*#%@"` | ascii の濃淡ランプ（薄い → 濃い）                  |
+| `palette`    | なし           | 渡すとその色だけに量子化する                       |
+| `dither`     | `false`        | 量子化時に誤差拡散（Floyd–Steinberg）              |
+| `cellAspect` | `2`            | 等幅フォント1文字の縦横比（高さ ÷ 幅）             |
+| `background` | `"dark"`       | 置く背景。`light` では濃淡が反転する               |
+
+## 設計のポイント
+
+**マスの縦横比は出力先で変わる。** 1マスが受け持つのは横 `blockW`・縦 `blockW * cellAspect` ピクセルです。既定の `2` は**ターミナルの比率**（行間込みで文字セルが縦2倍）で、`toAnsi` の出力にはこれが正しい値です。
+
+ところが HTML として文字で描く場合、実際の文字セルはフォントと `line-height` で決まります。Chromium で実測すると:
+
+|                    | 1文字の大きさ  | 縦横比   |
+| ------------------ | -------------- | -------- |
+| `line-height: 1`   | 9.63 × 16.00px | **1.66** |
+| `line-height: 1.2` | 9.63 × 19.19px | 1.99     |
+
+半ブロックは行間があるとマスのあいだに隙間が出るので `line-height: 1` が必要で、そのとき実際の比率は 1.66 です。ここを 2 のままにすると、絵は本来の 83% の高さで描かれて横に潰れます。**HTML に出すときは、描画に使うフォントの実測値を渡してください。**
+
+SVG は矩形を `cellAspect` 倍の高さで描くので自己完結していて、どの値でも比率は保たれます（マス目の粗さが変わるだけ）。
+
+円が円のまま出ることは、合成画像を使ったテストで固定しています。
+
+**濃淡の割り当てには知覚的な明度を使う。** WCAG の相対輝度は線形光なので、そのまま等間隔の文字ランプに割り当てると暗部に偏ります（中間グレーが 0.216）。contrast-kit の `toOklab().L`（中間グレーで 0.60）を使っています。
+
+**HTML は同じ色が続く区間をまとめる。** SVG も横に続く同色の矩形を1つにまとめるので、平坦な部分が多い画像では出力が10分の1近くまで縮みます。
+
+## テーマに追従させる
+
+出力する色を CSS 変数に差し替えられます。役割（変数名）で色を持つので、ライト/ダークでトークンの値が入れ替わるサイトなら、絵もテーマの切り替えに追従します。画像ではできない振る舞いです。
+
+```ts
+import { convert, cssVariablePalette, toSvg } from "termpic";
+
+const { palette, colors } = cssVariablePalette({
+  "--bg": "#0b0e0f",
+  "--fg": "#cfd8d3",
+  "--accent": "#7ee787",
+});
+
+const grid = convert(bitmap, { palette, dither: true });
+toSvg(grid, { colors }); // fill="var(--accent)" が出る
+```
+
+`toAnsi` は実際の色の数値が要るので差し替えません。
+
+## 貼り付け先に必要な CSS
+
+```css
+.termpic {
+  margin: 0;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  line-height: 1;
+  letter-spacing: 0;
+  white-space: pre;
+}
+```
+
+`line-height: 1` を入れないと、半ブロックのマスのあいだに隙間が出ます。

package/dist/index.d.mts

@@ -0,0 +1,118 @@
+//#region src/convert.d.ts
+/** 変換元の画像。ブラウザの `ImageData` と同じ形 */
+interface Bitmap {
+  width: number;
+  height: number;
+  /** RGBA が 4 バイトずつ並んだ配列 */
+  data: Uint8ClampedArray | readonly number[];
+}
+interface Rgb {
+  r: number;
+  g: number;
+  b: number;
+}
+/** 出力1マスぶん */
+interface Cell {
+  char: string;
+  /** 文字色（#rrggbb） */
+  fg: string;
+  /** 背景色。ascii モードでは付かない */
+  bg?: string;
+}
+type Mode = "ascii" | "halfblock";
+interface Grid {
+  cols: number;
+  rows: number;
+  mode: Mode;
+  /** セルの縦横比（高さ ÷ 幅）。SVG に落とすときに必要 */
+  cellAspect: number;
+  cells: Cell[];
+}
+/** 薄い → 濃い の順に並べた既定の濃淡ランプ */
+declare const DEFAULT_RAMP = " .:-=+*#%@";
+interface ConvertOptions {
+  /** ascii = 濃淡の文字だけ / halfblock = 上下2色のマス（既定） */
+  mode?: Mode;
+  /** 横方向のマス数。既定 60 */
+  cols?: number;
+  /** ascii モードの濃淡ランプ（薄い → 濃い） */
+  ramp?: string;
+  /** 量子化先のパレット。省略すると元の色をそのまま使う */
+  palette?: readonly string[];
+  /** パレット量子化のときに誤差拡散（Floyd–Steinberg）を行う */
+  dither?: boolean;
+  /**
+   * 等幅フォント1文字の縦横比（高さ ÷ 幅）。既定 2。
+   * 1 にすると出力が縦に間延びするので、通常は変えない。
+   */
+  cellAspect?: number;
+  /**
+   * 出力を置く背景。`dark` では明るい画素ほど濃い文字を使う
+   * （濃い文字ほど地の暗さを覆って明るく見えるため）。既定 `dark`
+   */
+  background?: "dark" | "light";
+}
+/**
+ * 画像をターミナル表現のマス目に変換する。
+ *
+ * `cellAspect`（既定 2）は等幅フォント1文字の縦横比。1マスは横 `blockW`・
+ * 縦 `blockW * cellAspect` ピクセルぶんを受け持つので、丸は丸のまま出る。
+ */
+declare function convert(bitmap: Bitmap, options?: ConvertOptions): Grid;
+/**
+ * CSS カスタムプロパティの組から、量子化用のパレットと
+ * 出力用の色の対応表を作る。
+ *
+ * ```ts
+ * const { palette, colors } = cssVariablePalette({
+ *   "--bg": "#0b0e0f",
+ *   "--accent": "#7ee787",
+ * });
+ * const grid = convert(bitmap, { palette });
+ * toHtml(grid, { colors }); // 色が var(--accent) で出る
+ * ```
+ *
+ * 役割（変数名）で色を持つので、ライト/ダークでトークンの値が入れ替わる
+ * サイトなら、出力した絵もテーマの切り替えに追従する。
+ * 同じ色が複数の名前に割り当てられている場合は、先に現れた名前を使う。
+ */
+declare function cssVariablePalette(variables: Readonly<Record<string, string>>): {
+  palette: string[];
+  colors: Record<string, string>;
+};
+//#endregion
+//#region src/render.d.ts
+/** ascii モードの出力を素のテキストにする。行末の空白は落とす */
+declare function toText(grid: Grid): string;
+/** 出力する色を差し替える対応表。`#7ee787` → `var(--accent)` のように使う */
+interface ColorMapping {
+  colors?: Readonly<Record<string, string>>;
+}
+interface HtmlOptions extends ColorMapping {
+  /** <pre> に付けるクラス名。既定 "termpic" */
+  className?: string;
+  /** 読み上げ用の説明。指定すると role="img" と aria-label が付く */
+  alt?: string;
+}
+/**
+ * `<pre>` にまとめた HTML を返す。
+ * 同じ色が続くマスは1つの `<span>` にまとめるので、出力はマス数よりずっと小さくなる。
+ */
+declare function toHtml(grid: Grid, options?: HtmlOptions): string;
+interface SvgOptions extends ColorMapping {
+  /** 1マスの幅（px）。高さは cellAspect 倍になる。既定 8 */
+  cellSize?: number;
+  alt?: string;
+}
+/**
+ * SVG を返す。
+ *
+ * halfblock モードは矩形だけで描くのでフォントに依存しない。
+ * ascii モードは文字を使うため等幅フォントを指定し、行ごとに `textLength` で
+ * 幅を固定して、環境によるフォントの差で崩れないようにしている。
+ */
+declare function toSvg(grid: Grid, options?: SvgOptions): string;
+/** そのままターミナルに貼れる ANSI エスケープ付きの文字列 */
+declare function toAnsi(grid: Grid): string;
+//#endregion
+export { type Bitmap, type Cell, type ColorMapping, type ConvertOptions, DEFAULT_RAMP, type Grid, type HtmlOptions, type Mode, type Rgb, type SvgOptions, convert, cssVariablePalette, toAnsi, toHtml, toSvg, toText };

package/dist/index.mjs

@@ -0,0 +1,270 @@
+import { formatHex, nearestColor, toOklab } from "contrast-kit";
+//#region src/convert.ts
+/** 薄い → 濃い の順に並べた既定の濃淡ランプ */
+const DEFAULT_RAMP = " .:-=+*#%@";
+/** 上半分を文字色、下半分を背景色で塗る文字 */
+const HALF_BLOCK = "▀";
+function clamp(value, min, max) {
+	return value < min ? min : value > max ? max : value;
+}
+/** 指定した矩形の平均色。範囲外は切り詰める */
+function averageRect(bitmap, left, top, right, bottom) {
+	const x0 = clamp(Math.floor(left), 0, bitmap.width);
+	const x1 = clamp(Math.ceil(right), x0 + 1, bitmap.width);
+	const y0 = clamp(Math.floor(top), 0, bitmap.height);
+	const y1 = clamp(Math.ceil(bottom), y0 + 1, bitmap.height);
+	let r = 0;
+	let g = 0;
+	let b = 0;
+	let count = 0;
+	for (let y = y0; y < y1; y++) for (let x = x0; x < x1; x++) {
+		const index = (y * bitmap.width + x) * 4;
+		const alpha = (bitmap.data[index + 3] ?? 255) / 255;
+		r += (bitmap.data[index] ?? 0) * alpha;
+		g += (bitmap.data[index + 1] ?? 0) * alpha;
+		b += (bitmap.data[index + 2] ?? 0) * alpha;
+		count++;
+	}
+	return count === 0 ? {
+		r: 0,
+		g: 0,
+		b: 0
+	} : {
+		r: r / count,
+		g: g / count,
+		b: b / count
+	};
+}
+/** 誤差拡散つきでパレットに量子化する。palette が無ければそのまま返す */
+function quantize(samples, cols, rows, palette, dither) {
+	if (!palette || palette.length === 0) return samples.map((sample) => formatHex({
+		r: Math.round(clamp(sample.r, 0, 255)),
+		g: Math.round(clamp(sample.g, 0, 255)),
+		b: Math.round(clamp(sample.b, 0, 255))
+	}));
+	const working = samples.map((sample) => ({ ...sample }));
+	const result = [];
+	const spread = (index, error, factor) => {
+		const target = working[index];
+		if (!target) return;
+		target.r += error.r * factor;
+		target.g += error.g * factor;
+		target.b += error.b * factor;
+	};
+	for (let y = 0; y < rows; y++) for (let x = 0; x < cols; x++) {
+		const index = y * cols + x;
+		const current = working[index];
+		const rounded = {
+			r: Math.round(clamp(current.r, 0, 255)),
+			g: Math.round(clamp(current.g, 0, 255)),
+			b: Math.round(clamp(current.b, 0, 255))
+		};
+		const picked = nearestColor(rounded, palette);
+		result.push(picked);
+		if (!dither) continue;
+		const chosen = hexToRgb(picked);
+		const error = {
+			r: current.r - chosen.r,
+			g: current.g - chosen.g,
+			b: current.b - chosen.b
+		};
+		if (x + 1 < cols) spread(index + 1, error, 7 / 16);
+		if (y + 1 < rows) {
+			if (x > 0) spread(index + cols - 1, error, 3 / 16);
+			spread(index + cols, error, 5 / 16);
+			if (x + 1 < cols) spread(index + cols + 1, error, 1 / 16);
+		}
+	}
+	return result;
+}
+function hexToRgb(hex) {
+	return {
+		r: Number.parseInt(hex.slice(1, 3), 16),
+		g: Number.parseInt(hex.slice(3, 5), 16),
+		b: Number.parseInt(hex.slice(5, 7), 16)
+	};
+}
+/**
+* 画像をターミナル表現のマス目に変換する。
+*
+* `cellAspect`（既定 2）は等幅フォント1文字の縦横比。1マスは横 `blockW`・
+* 縦 `blockW * cellAspect` ピクセルぶんを受け持つので、丸は丸のまま出る。
+*/
+function convert(bitmap, options = {}) {
+	if (bitmap.width <= 0 || bitmap.height <= 0) throw new TypeError("画像の大きさが 0 です");
+	const mode = options.mode ?? "halfblock";
+	const cols = Math.max(1, Math.floor(options.cols ?? 60));
+	const cellAspect = options.cellAspect ?? 2;
+	const ramp = options.ramp ?? " .:-=+*#%@";
+	const background = options.background ?? "dark";
+	const blockW = bitmap.width / cols;
+	const blockH = blockW * cellAspect;
+	const rows = Math.max(1, Math.round(bitmap.height / blockH));
+	const perCell = mode === "halfblock" ? 2 : 1;
+	const sampleRows = rows * perCell;
+	const sampleH = blockH / perCell;
+	const samples = [];
+	for (let y = 0; y < sampleRows; y++) for (let x = 0; x < cols; x++) samples.push(averageRect(bitmap, x * blockW, y * sampleH, (x + 1) * blockW, (y + 1) * sampleH));
+	const colors = quantize(samples, cols, sampleRows, options.palette, options.dither ?? false);
+	const cells = [];
+	for (let row = 0; row < rows; row++) for (let col = 0; col < cols; col++) if (mode === "halfblock") cells.push({
+		char: HALF_BLOCK,
+		fg: colors[row * 2 * cols + col],
+		bg: colors[(row * 2 + 1) * cols + col]
+	});
+	else {
+		const fg = colors[row * cols + col];
+		const lightness = toOklab(fg).L;
+		const level = background === "dark" ? lightness : 1 - lightness;
+		const index = clamp(Math.round(level * (ramp.length - 1)), 0, ramp.length - 1);
+		cells.push({
+			char: ramp[index],
+			fg
+		});
+	}
+	return {
+		cols,
+		rows,
+		mode,
+		cellAspect,
+		cells
+	};
+}
+/**
+* CSS カスタムプロパティの組から、量子化用のパレットと
+* 出力用の色の対応表を作る。
+*
+* ```ts
+* const { palette, colors } = cssVariablePalette({
+*   "--bg": "#0b0e0f",
+*   "--accent": "#7ee787",
+* });
+* const grid = convert(bitmap, { palette });
+* toHtml(grid, { colors }); // 色が var(--accent) で出る
+* ```
+*
+* 役割（変数名）で色を持つので、ライト/ダークでトークンの値が入れ替わる
+* サイトなら、出力した絵もテーマの切り替えに追従する。
+* 同じ色が複数の名前に割り当てられている場合は、先に現れた名前を使う。
+*/
+function cssVariablePalette(variables) {
+	const palette = [];
+	const colors = {};
+	for (const [name, value] of Object.entries(variables)) {
+		const hex = formatHex(value.trim());
+		if (colors[hex] !== void 0) continue;
+		palette.push(hex);
+		colors[hex] = `var(${name})`;
+	}
+	return {
+		palette,
+		colors
+	};
+}
+//#endregion
+//#region src/render.ts
+const HTML_ESCAPES = {
+	"&": "&amp;",
+	"<": "&lt;",
+	">": "&gt;",
+	"\"": "&quot;"
+};
+function escapeHtml(value) {
+	return value.replace(/[&<>"]/g, (char) => HTML_ESCAPES[char]);
+}
+function runsOfRow(grid, row) {
+	const runs = [];
+	for (let col = 0; col < grid.cols; col++) {
+		const cell = grid.cells[row * grid.cols + col];
+		const last = runs.at(-1);
+		if (last && last.fg === cell.fg && last.bg === cell.bg) last.text += cell.char;
+		else runs.push({
+			text: cell.char,
+			fg: cell.fg,
+			bg: cell.bg
+		});
+	}
+	return runs;
+}
+/** ascii モードの出力を素のテキストにする。行末の空白は落とす */
+function toText(grid) {
+	const lines = [];
+	for (let row = 0; row < grid.rows; row++) {
+		let line = "";
+		for (let col = 0; col < grid.cols; col++) line += grid.cells[row * grid.cols + col].char;
+		lines.push(line.replace(/\s+$/u, ""));
+	}
+	return lines.join("\n");
+}
+function mapColor(color, colors) {
+	return colors?.[color] ?? color;
+}
+/**
+* `<pre>` にまとめた HTML を返す。
+* 同じ色が続くマスは1つの `<span>` にまとめるので、出力はマス数よりずっと小さくなる。
+*/
+function toHtml(grid, options = {}) {
+	const body = Array.from({ length: grid.rows }, (_, row) => runsOfRow(grid, row).map((run) => {
+		const fg = mapColor(run.fg, options.colors);
+		return `<span style="${run.bg === void 0 ? `color:${fg}` : `color:${fg};background:${mapColor(run.bg, options.colors)}`}">${escapeHtml(run.text)}</span>`;
+	}).join("")).join("\n");
+	const attributes = [`class="${escapeHtml(options.className ?? "termpic")}"`];
+	if (options.alt !== void 0) attributes.push(`role="img"`, `aria-label="${escapeHtml(options.alt)}"`);
+	return `<pre ${attributes.join(" ")}>${body}</pre>`;
+}
+/**
+* SVG を返す。
+*
+* halfblock モードは矩形だけで描くのでフォントに依存しない。
+* ascii モードは文字を使うため等幅フォントを指定し、行ごとに `textLength` で
+* 幅を固定して、環境によるフォントの差で崩れないようにしている。
+*/
+function toSvg(grid, options = {}) {
+	const cellW = options.cellSize ?? 8;
+	const cellH = cellW * grid.cellAspect;
+	const width = grid.cols * cellW;
+	const height = grid.rows * cellH;
+	const parts = [];
+	if (grid.mode === "halfblock") {
+		const halfH = cellH / 2;
+		const emitRow = (colorAt, y) => {
+			let start = 0;
+			for (let col = 1; col <= grid.cols; col++) {
+				if (col < grid.cols && colorAt(col) === colorAt(start)) continue;
+				const width = (col - start) * cellW;
+				parts.push(`<rect x="${start * cellW}" y="${y}" width="${width}" height="${halfH}" fill="${mapColor(colorAt(start), options.colors)}"/>`);
+				start = col;
+			}
+		};
+		for (let row = 0; row < grid.rows; row++) {
+			const cellAt = (col) => grid.cells[row * grid.cols + col];
+			emitRow((col) => cellAt(col).fg, row * cellH);
+			emitRow((col) => cellAt(col).bg ?? cellAt(col).fg, row * cellH + halfH);
+		}
+	} else for (let row = 0; row < grid.rows; row++) {
+		const spans = runsOfRow(grid, row).map((run) => `<tspan fill="${mapColor(run.fg, options.colors)}">${escapeHtml(run.text)}</tspan>`).join("");
+		const baseline = row * cellH + cellH * .78;
+		parts.push(`<text x="0" y="${baseline}" textLength="${width}" lengthAdjust="spacingAndGlyphs" xml:space="preserve">${spans}</text>`);
+	}
+	const label = options.alt === void 0 ? "" : `<title>${escapeHtml(options.alt)}</title>`;
+	return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" width="${width}" height="${height}" role="img"${grid.mode === "ascii" ? ` font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="${cellH * .9}"` : ""}>${label}${parts.join("")}</svg>`;
+}
+function ansiColor(hex, layer) {
+	return `\u001b[${layer};2;${Number.parseInt(hex.slice(1, 3), 16)};${Number.parseInt(hex.slice(3, 5), 16)};${Number.parseInt(hex.slice(5, 7), 16)}m`;
+}
+/** そのままターミナルに貼れる ANSI エスケープ付きの文字列 */
+function toAnsi(grid) {
+	const lines = [];
+	for (let row = 0; row < grid.rows; row++) {
+		let line = "";
+		for (const run of runsOfRow(grid, row)) {
+			line += ansiColor(run.fg, 38);
+			if (run.bg !== void 0) line += ansiColor(run.bg, 48);
+			line += run.text;
+		}
+		lines.push(`${line}\u001b[0m`);
+	}
+	return lines.join("\n");
+}
+//#endregion
+export { DEFAULT_RAMP, convert, cssVariablePalette, toAnsi, toHtml, toSvg, toText };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "termpic",
+  "version": "0.0.0",
+  "description": "Convert images into terminal art: ASCII ramps, half-block color cells, and palette quantization.",
+  "keywords": [
+    "ansi",
+    "ascii-art",
+    "dithering",
+    "image",
+    "pixel-art",
+    "terminal"
+  ],
+  "homepage": "https://github.com/finalize/termpic#readme",
+  "bugs": {
+    "url": "https://github.com/finalize/termpic/issues"
+  },
+  "license": "MIT",
+  "author": "finalize",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/finalize/termpic.git",
+    "directory": "packages/termpic"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "prepublishOnly": "vp run build"
+  },
+  "dependencies": {
+    "contrast-kit": "link:../../../contrast-kit/packages/contrast"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "bumpp": "^11.1.0",
+    "typescript": "^7.0.2",
+    "vite": "catalog:",
+    "vite-plus": "catalog:"
+  }
+}