termpic 0.1.0 → 0.2.1

package/README.md

@@ -30,6 +30,40 @@ toAnsi(grid); // そのままターミナルに貼れる
 | `cellAspect` | `2`            | 等幅フォント1文字の縦横比（高さ ÷ 幅）             |
 | `background` | `"dark"`       | 置く背景。`light` では濃淡が反転する               |
 
+## 描き方
+
+| モード      | 1マスの分割 | 色          | 向いているもの                 |
+| ----------- | ----------- | ----------- | ------------------------------ |
+| `ascii`     | 1x1         | 文字色のみ  | 文字として貼りたいとき         |
+| `halfblock` | 1x2         | 上下2色     | 汎用。既定                     |
+| `quadrant`  | 2x2         | 明暗2色     | 横の解像度がほしいとき         |
+| `braille`   | 2x4         | 点と地の2色 | 最も細かい。輪郭がはっきり出る |
+
+`quadrant` は、4つの小マスの明度差が小さいマスを単色で塗ります。差が無いのに明暗2色に分けると、平坦な面に無意味な模様が出るためです（実写真で測ると閾値 0.03 でちょうど無くなります）。
+
+`braille` は 1 マスに 2x4 の点を持てるので `halfblock` の4倍の解像度になります。点の有無は**画像全体の平均の明度**で決めます。マスごとの中間値で切ると、一様なマスが必ず全点灯になって図地が反転するためです。点の色に加えて点が付かない側の平均も背景色として持たせているので、写真でも図地が反転しません。
+
+## 画像から色を抽出する
+
+決め打ちのパレットに落とすと、そこに無い色（茶色など）が破綻します。画像自身から代表色を求められます。
+
+```ts
+import { convert, extractPalette } from "termpic";
+
+const palette = extractPalette(bitmap, 16);
+convert(bitmap, { palette });
+```
+
+中央値分割法です。色空間の直方体を最も幅の広い軸の中央値で切る操作を、箱が指定数になるまで繰り返します。画像の色数が要求より少ない場合は、重複を除いた色数だけを返します。
+
+## 輪郭を拾う
+
+```ts
+convert(bitmap, { mode: "ascii", edges: true });
+```
+
+Sobel フィルタでマス目の明度の傾きを取り、輪郭が強いマスに向きの文字を割り当てます。マスは縦長なので、画面上の角度に直すために縦方向の傾きへ `cellAspect` を掛けています。これを忘れると斜めの輪郭がすべて縦寄りに倒れます。
+
 ## 設計のポイント
 
 **マスの縦横比は出力先で変わる。** 1マスが受け持つのは横 `blockW`・縦 `blockW * cellAspect` ピクセルです。既定の `2` は**ターミナルの比率**（行間込みで文字セルが縦2倍）で、`toAnsi` の出力にはこれが正しい値です。

package/dist/index.d.mts

@@ -19,7 +19,7 @@ interface Cell {
   /** 背景色。ascii モードでは付かない */
   bg?: string;
 }
-type Mode = "ascii" | "halfblock";
+type Mode = "ascii" | "halfblock" | "quadrant" | "braille";
 interface Grid {
   cols: number;
   rows: number;
@@ -31,7 +31,12 @@ interface Grid {
 /** 薄い → 濃い の順に並べた既定の濃淡ランプ */
 declare const DEFAULT_RAMP = " .:-=+*#%@";
 interface ConvertOptions {
-  /** ascii = 濃淡の文字だけ / halfblock = 上下2色のマス（既定） */
+  /**
+   * - `ascii` 濃淡の文字だけ
+   * - `halfblock` 上下2色のマス（既定）
+   * - `quadrant` 四分割。横の解像度が倍になる
+   * - `braille` 点字。1マスに 2x4 の点を持てるので最も細かいが、色は1マスにつき1色
+   */
   mode?: Mode;
   /** 横方向のマス数。既定 60 */
   cols?: number;
@@ -41,6 +46,11 @@ interface ConvertOptions {
   palette?: readonly string[];
   /** パレット量子化のときに誤差拡散（Floyd–Steinberg）を行う */
   dither?: boolean;
+  /**
+   * ascii モードで輪郭を拾い、傾きに応じて `-` `/` `|` `\\` を割り当てる。
+   * 数値を渡すとその値を閾値にする（既定 0.12）。
+   */
+  edges?: boolean | number;
   /**
    * 等幅フォント1文字の縦横比（高さ ÷ 幅）。既定 2。
    * 1 にすると出力が縦に間延びするので、通常は変えない。
@@ -80,6 +90,16 @@ declare function cssVariablePalette(variables: Readonly<Record<string, string>>)
   palette: string[];
   colors: Record<string, string>;
 };
+/**
+ * 画像自身から代表色を求める（中央値分割法）。
+ *
+ * 決め打ちのパレットに落とすと、そこに無い色（茶色など）が破綻する。
+ * 画像を色空間の直方体として持ち、最も幅の広い軸で中央値に切る操作を
+ * 箱が `count` 個になるまで繰り返し、各箱の平均色を代表色にする。
+ *
+ * `sampleLimit` を超える画素数の画像は間引いて読む（既定 20000）。
+ */
+declare function extractPalette(bitmap: Bitmap, count?: number, sampleLimit?: number): string[];
 //#endregion
 //#region src/render.d.ts
 /** ascii モードの出力を素のテキストにする。行末の空白は落とす */
@@ -115,4 +135,4 @@ 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 };
+export { type Bitmap, type Cell, type ColorMapping, type ConvertOptions, DEFAULT_RAMP, type Grid, type HtmlOptions, type Mode, type Rgb, type SvgOptions, convert, cssVariablePalette, extractPalette, toAnsi, toHtml, toSvg, toText };

package/dist/index.mjs

@@ -1,9 +1,29 @@
-import { formatHex, nearestColor, toOklab } from "contrast-kit";
+import { formatHex, nearestColor, parseHex, toOklab } from "contrast-kit";
 //#region src/convert.ts
+/** 1マスが受け持つ小マスの数（横 × 縦） */
+const SUBCELLS = {
+	ascii: [1, 1],
+	halfblock: [1, 2],
+	quadrant: [2, 2],
+	braille: [2, 4]
+};
+/**
+* 四分割ブロックの文字。添字のビットは
+* 1=左上 / 2=右上 / 4=左下 / 8=右下 に対応する。
+*/
+const QUADRANTS = " ▘▝▀▖▌▞▛▗▚▐▜▄▙▟█";
+/**
+* 点字の 2x4 の点と Unicode のビットの対応。
+* 上3段は 0,1,2（左）/ 3,4,5（右）、最下段だけ 6（左）/ 7（右）と離れている。
+*/
+const BRAILLE_BITS = [
+	[0, 3],
+	[1, 4],
+	[2, 5],
+	[6, 7]
+];
 /** 薄い → 濃い の順に並べた既定の濃淡ランプ */
 const DEFAULT_RAMP = " .:-=+*#%@";
-/** 上半分を文字色、下半分を背景色で塗る文字 */
-const HALF_BLOCK = "▀";
 function clamp(value, min, max) {
 	return value < min ? min : value > max ? max : value;
 }
@@ -97,29 +117,35 @@ function convert(bitmap, options = {}) {
 	const cellAspect = options.cellAspect ?? 2;
 	const ramp = options.ramp ?? " .:-=+*#%@";
 	const background = options.background ?? "dark";
+	const [subCols, subRows] = SUBCELLS[mode];
 	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 sampleCols = cols * subCols;
+	const sampleRows = rows * subRows;
+	const sampleW = blockW / subCols;
+	const sampleH = blockH / subRows;
 	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);
+	for (let y = 0; y < sampleRows; y++) for (let x = 0; x < sampleCols; x++) samples.push(averageRect(bitmap, x * sampleW, y * sampleH, (x + 1) * sampleW, (y + 1) * sampleH));
+	const colors = quantize(samples, sampleCols, sampleRows, options.palette, options.dither ?? false);
+	const at = (x, y) => colors[y * sampleCols + x];
+	const threshold = colors.reduce((total, color) => total + toOklab(color).L, 0) / Math.max(1, colors.length);
+	const edgeChars = mode === "ascii" && options.edges ? detectEdges(colors, cols, rows, cellAspect, typeof options.edges === "number" ? options.edges : .12) : void 0;
 	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
+	for (let row = 0; row < rows; row++) for (let col = 0; col < cols; col++) {
+		const cell = buildCell({
+			mode,
+			ramp,
+			background,
+			at,
+			col,
+			row,
+			threshold
+		});
+		const edge = edgeChars?.[row * cols + col];
+		cells.push(edge === void 0 ? cell : {
+			...cell,
+			char: edge
 		});
 	}
 	return {
@@ -131,6 +157,109 @@ function convert(bitmap, options = {}) {
 	};
 }
 /**
+* ほぼ一様なマスとみなす明度の幅。
+*
+* これ未満のマスを明暗に二分しても、前景色と背景色がほぼ同じなので
+* 描き分けの意味がなく、平坦な面に無意味な模様が出るだけになる。
+* 実写真で測ると 0.03 で無意味な分割がちょうど無くなり、
+* それ以上に上げると実際の描き分けまで潰れる。
+*/
+const FLAT_CELL_RANGE = .03;
+/** 明るい側と暗い側に二分し、どの小マスが明るい側かをビットで返す */
+function splitByLightness(colors) {
+	const levels = colors.map((color) => toOklab(color).L);
+	const lowest = Math.min(...levels);
+	const highest = Math.max(...levels);
+	if (highest - lowest < FLAT_CELL_RANGE) {
+		const flat = averageHex(colors);
+		return {
+			bits: (1 << colors.length) - 1,
+			light: flat,
+			dark: flat
+		};
+	}
+	const middle = (lowest + highest) / 2;
+	let bits = 0;
+	const lightGroup = [];
+	const darkGroup = [];
+	for (const [index, level] of levels.entries()) if (level >= middle) {
+		bits |= 1 << index;
+		lightGroup.push(colors[index]);
+	} else darkGroup.push(colors[index]);
+	return {
+		bits,
+		light: averageHex(lightGroup.length > 0 ? lightGroup : colors),
+		dark: averageHex(darkGroup.length > 0 ? darkGroup : colors)
+	};
+}
+function averageHex(colors) {
+	let r = 0;
+	let g = 0;
+	let b = 0;
+	for (const color of colors) {
+		const rgb = parseHex(color);
+		r += rgb.r;
+		g += rgb.g;
+		b += rgb.b;
+	}
+	const count = colors.length;
+	return formatHex({
+		r: Math.round(r / count),
+		g: Math.round(g / count),
+		b: Math.round(b / count)
+	});
+}
+function buildCell(context) {
+	const { mode, at, col, row } = context;
+	if (mode === "halfblock") return {
+		char: "▀",
+		fg: at(col, row * 2),
+		bg: at(col, row * 2 + 1)
+	};
+	if (mode === "quadrant") {
+		const { bits, light, dark } = splitByLightness([
+			at(col * 2, row * 2),
+			at(col * 2 + 1, row * 2),
+			at(col * 2, row * 2 + 1),
+			at(col * 2 + 1, row * 2 + 1)
+		]);
+		return {
+			char: QUADRANTS[bits],
+			fg: light,
+			bg: dark
+		};
+	}
+	if (mode === "braille") {
+		const dots = [];
+		for (let y = 0; y < 4; y++) dots.push(at(col * 2, row * 4 + y), at(col * 2 + 1, row * 4 + y));
+		const levels = dots.map((color) => toOklab(color).L);
+		const isLit = (level) => context.background === "dark" ? level >= context.threshold : level < context.threshold;
+		let pattern = 0;
+		const lit = [];
+		const unlit = [];
+		for (let y = 0; y < 4; y++) for (let x = 0; x < 2; x++) {
+			const index = y * 2 + x;
+			if (isLit(levels[index])) {
+				pattern |= 1 << BRAILLE_BITS[y][x];
+				lit.push(dots[index]);
+			} else unlit.push(dots[index]);
+		}
+		return {
+			char: String.fromCodePoint(10240 + pattern),
+			fg: averageHex(lit.length > 0 ? lit : dots),
+			bg: averageHex(unlit.length > 0 ? unlit : dots)
+		};
+	}
+	const fg = at(col, row);
+	const lightness = toOklab(fg).L;
+	const level = context.background === "dark" ? lightness : 1 - lightness;
+	const index = clamp(Math.round(level * (context.ramp.length - 1)), 0, context.ramp.length - 1);
+	return {
+		char: context.ramp[index],
+		fg
+	};
+}
+/**
 * CSS カスタムプロパティの組から、量子化用のパレットと
 * 出力用の色の対応表を作る。
 *
@@ -161,6 +290,107 @@ function cssVariablePalette(variables) {
 		colors
 	};
 }
+/**
+* 画像自身から代表色を求める（中央値分割法）。
+*
+* 決め打ちのパレットに落とすと、そこに無い色（茶色など）が破綻する。
+* 画像を色空間の直方体として持ち、最も幅の広い軸で中央値に切る操作を
+* 箱が `count` 個になるまで繰り返し、各箱の平均色を代表色にする。
+*
+* `sampleLimit` を超える画素数の画像は間引いて読む（既定 20000）。
+*/
+function extractPalette(bitmap, count = 16, sampleLimit = 2e4) {
+	if (count < 1) throw new TypeError("色数は 1 以上にしてください");
+	const total = bitmap.width * bitmap.height;
+	const step = Math.max(1, Math.ceil(total / sampleLimit));
+	const pixels = [];
+	for (let index = 0; index < total; index += step) {
+		const offset = index * 4;
+		if ((bitmap.data[offset + 3] ?? 255) === 0) continue;
+		pixels.push({
+			r: bitmap.data[offset] ?? 0,
+			g: bitmap.data[offset + 1] ?? 0,
+			b: bitmap.data[offset + 2] ?? 0
+		});
+	}
+	if (pixels.length === 0) return ["#000000"];
+	let boxes = [pixels];
+	while (boxes.length < count) {
+		let target = -1;
+		let widestSpread = 0;
+		let widestAxis = "r";
+		for (const [index, box] of boxes.entries()) {
+			if (box.length < 2) continue;
+			for (const axis of [
+				"r",
+				"g",
+				"b"
+			]) {
+				const values = box.map((pixel) => pixel[axis]);
+				const spread = Math.max(...values) - Math.min(...values);
+				if (spread > widestSpread) {
+					widestSpread = spread;
+					widestAxis = axis;
+					target = index;
+				}
+			}
+		}
+		if (target === -1) break;
+		const box = [...boxes[target]].sort((a, b) => a[widestAxis] - b[widestAxis]);
+		const middle = Math.floor(box.length / 2);
+		boxes = [
+			...boxes.slice(0, target),
+			box.slice(0, middle),
+			box.slice(middle),
+			...boxes.slice(target + 1)
+		];
+	}
+	const colors = boxes.filter((box) => box.length > 0).map((box) => {
+		const sum = box.reduce((total2, pixel) => ({
+			r: total2.r + pixel.r,
+			g: total2.g + pixel.g,
+			b: total2.b + pixel.b
+		}), {
+			r: 0,
+			g: 0,
+			b: 0
+		});
+		return formatHex({
+			r: Math.round(sum.r / box.length),
+			g: Math.round(sum.g / box.length),
+			b: Math.round(sum.b / box.length)
+		});
+	});
+	return [...new Set(colors)];
+}
+/** 輪郭の向きに割り当てる文字。添字は 0=横 / 1=右下がり / 2=縦 / 3=右上がり */
+const EDGE_CHARS = [
+	"-",
+	"\\",
+	"|",
+	"/"
+];
+/**
+* Sobel フィルタでマス目の明度の傾きを取り、輪郭が強いマスに向きの文字を割り当てる。
+*
+* マスは縦長なので、画面上の角度に直すために縦方向の傾きへ `cellAspect` を掛ける。
+* これを忘れると斜めの輪郭がすべて縦寄りに倒れる。
+*/
+function detectEdges(colors, cols, rows, cellAspect, threshold) {
+	const lightness = colors.map((color) => toOklab(color).L);
+	const at = (x, y) => lightness[clamp(y, 0, rows - 1) * cols + clamp(x, 0, cols - 1)];
+	return Array.from({ length: cols * rows }, (_, index) => {
+		const col = index % cols;
+		const row = Math.floor(index / cols);
+		const gx = -at(col - 1, row - 1) + at(col + 1, row - 1) + -2 * at(col - 1, row) + 2 * at(col + 1, row) + -at(col - 1, row + 1) + at(col + 1, row + 1);
+		const gy = -at(col - 1, row - 1) - 2 * at(col, row - 1) - at(col + 1, row - 1) + at(col - 1, row + 1) + 2 * at(col, row + 1) + at(col + 1, row + 1);
+		if (Math.hypot(gx, gy) / 4 < threshold) return void 0;
+		let angle = Math.atan2(gy * cellAspect, gx) + Math.PI / 2;
+		angle = (angle % Math.PI + Math.PI) % Math.PI;
+		const bucket = Math.round(angle / (Math.PI / 4)) % 4;
+		return EDGE_CHARS[bucket];
+	});
+}
 //#endregion
 //#region src/render.ts
 const HTML_ESCAPES = {
@@ -241,6 +471,30 @@ function toSvg(grid, options = {}) {
 			emitRow((col) => cellAt(col).fg, row * cellH);
 			emitRow((col) => cellAt(col).bg ?? cellAt(col).fg, row * cellH + halfH);
 		}
+	} else if (grid.mode === "quadrant") {
+		const halfW = cellW / 2;
+		const halfH = cellH / 2;
+		for (let row = 0; row < grid.rows; row++) for (let col = 0; col < grid.cols; col++) {
+			const cell = grid.cells[row * grid.cols + col];
+			const bits = Math.max(0, QUADRANTS.indexOf(cell.char));
+			for (let corner = 0; corner < 4; corner++) {
+				const color = (bits & 1 << corner) === 0 ? cell.bg ?? cell.fg : cell.fg;
+				parts.push(`<rect x="${col * cellW + corner % 2 * halfW}" y="${row * cellH + Math.floor(corner / 2) * halfH}" width="${halfW}" height="${halfH}" fill="${mapColor(color, options.colors)}"/>`);
+			}
+		}
+	} else if (grid.mode === "braille") {
+		const dotW = cellW / 2;
+		const dotH = cellH / 4;
+		const radius = Math.min(dotW, dotH) * .38;
+		for (let row = 0; row < grid.rows; row++) for (let col = 0; col < grid.cols; col++) {
+			const cell = grid.cells[row * grid.cols + col];
+			const pattern = (cell.char.codePointAt(0) ?? 10240) - 10240;
+			parts.push(`<rect x="${col * cellW}" y="${row * cellH}" width="${cellW}" height="${cellH}" fill="${mapColor(cell.bg ?? cell.fg, options.colors)}"/>`);
+			for (let y = 0; y < 4; y++) for (let x = 0; x < 2; x++) {
+				if ((pattern & 1 << BRAILLE_BITS[y][x]) === 0) continue;
+				parts.push(`<circle cx="${col * cellW + (x + .5) * dotW}" cy="${row * cellH + (y + .5) * dotH}" r="${radius}" fill="${mapColor(cell.fg, options.colors)}"/>`);
+			}
+		}
 	} 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;
@@ -267,4 +521,4 @@ function toAnsi(grid) {
 	return lines.join("\n");
 }
 //#endregion
-export { DEFAULT_RAMP, convert, cssVariablePalette, toAnsi, toHtml, toSvg, toText };
+export { DEFAULT_RAMP, convert, cssVariablePalette, extractPalette, toAnsi, toHtml, toSvg, toText };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termpic",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Convert images into terminal art: ASCII ramps, half-block color cells, and palette quantization.",
   "keywords": [
     "ansi",