@pirka/ascii

Render logos and images as colored terminal art. Supports braille (2x4 sub-pixel per cell) and half-block (1x2 pixels per cell) rendering modes with truecolor (24-bit) or ANSI 256-color output.

• Any image format (PNG, JPEG, WebP, SVG, AVIF, GIF, TIFF)
• Input from file path, URL, or raw Buffer
• Auto-trims transparent padding
• Aspect-ratio-preserving resize with Lanczos3

Install

bun add @pirka/ascii

API

import { renderLogo } from '@pirka/ascii';

// From URL
const art = await renderLogo('https://example.com/logo.png', { width: 60 });
console.log(art);

// From file
const art = await renderLogo('./logo.png', { width: 40, mode: 'halfblock' });
console.log(art);

// From buffer
import { readFileSync } from 'fs';
const buf = readFileSync('./logo.png');
const art = await renderLogo(buf, { width: 60 });
console.log(art);

renderLogo(input, options?)

| Parameter | Type | Description | |-----------|------|-------------| | input | string \| Buffer \| Uint8Array | File path, URL, or raw image buffer | | options.width | number | Terminal columns. Derives height from aspect ratio. | | options.height | number | Terminal rows. Derives width from aspect ratio. | | options.mode | 'braille' \| 'halfblock' | Rendering mode. Default: 'braille' | | options.color | 'truecolor' \| 'ansi256' | Color depth. Default: 'truecolor' |

Provide width or height (or both). The unconstrained dimension is calculated from the image aspect ratio. Defaults to width: 40 if neither is set.

Render modes

• braille — Each terminal cell encodes a 2x4 dot matrix (Unicode braille U+2800-U+28FF), giving 4x vertical and 2x horizontal sub-pixel resolution. Best for detail.
• halfblock — Each terminal cell encodes 2 vertical pixels using ▀/▄ with foreground and background colors. Wider compatibility.

Lower-level API

import { loadImage, renderPixels } from '@pirka/ascii';

const image = await loadImage('./logo.png', { width: 80 }, 'braille');
const art = renderPixels(image, { mode: 'braille', color: 'truecolor' });

CLI

npx pirka-logo <file-or-url> [options]

Options

-w, --width N       Terminal columns (default: 60)
-H, --height N      Terminal rows (derives width from aspect ratio)
-m, --mode MODE     braille | halfblock (default: braille)
-c, --color MODE    truecolor | ansi256 (default: truecolor)
-h, --help          Show help

Examples

# Render at 80 columns wide
npx pirka-logo logo.png -w 80

# Fit into 5 terminal rows
npx pirka-logo https://example.com/logo.png -H 5

# Half-block mode with ANSI 256 colors
npx pirka-logo logo.png -m halfblock -c ansi256