English · 简体中文

EdgeGlyph converts images into terminal blocks, font-matched glyph art, and fuse-bead patterns. The CLI, Python API, NvDash exporter, and local workbench use the same parameter schema.

Mode	Representation	Main output
block	spaces and Unicode ▀▄█	compact terminal color art
glyph	rasterized glyphs from a selected font	color or monochrome character art
bead	one square-grid cell per physical bead	pattern, palette counts, pegboard PNG

Install

git clone https://github.com/BITnene465/edgeglyph.git
cd edgeglyph
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Python 3.10 or newer is required. Runtime dependencies are NumPy and Pillow.

Start the loopback-only workbench:

edgeglyph web

Open http://127.0.0.1:8765 if the browser does not open automatically.

Glyph mode

_{Color output · monochrome output}

Color output:

edgeglyph glyph input.png \
  --font /path/to/MapleMono-NF-Regular.ttf \
  --profile hybrid \
  --color-mode color \
  --cols 56 --rows 28 \
  --output output.txt \
  --preview output.png \
  --lua-output output.lua

Monochrome output for plain TTYs and terminals without color chunk support:

edgeglyph glyph input.png \
  --font /path/to/MapleMono-NF-Regular.ttf \
  --profile hybrid \
  --color-mode mono \
  --mono-color '#e8e8e8' \
  --output output.txt \
  --preview output-mono.png

mono uses one foreground color and no cell backgrounds. TXT output contains only UTF-8 characters and can use the terminal's current foreground color.

Glyph controls

Argument	Values	Default
--profile	outline, hybrid, tone	hybrid
--color-mode	color, mono	color
--mono-color	#RRGGBB	#e8e8e8
--character-preset	portrait, ascii, line, unicode	portrait
--fill-mode	auto, none, salient, tone	auto
--symbols / --fill-symbols	literal custom characters	preset
--symbols-file / --fill-symbols-file	UTF-8 character files	-
--top-k	candidates retained per cell	8

Glyph coverage, density, regional ink, direction, and texture are measured from the requested font. Invalid terminal-width and missing-font glyphs are excluded. Maple Mono NF or another Nerd Font is recommended for the Unicode preset.

Feature weights are available through --shape-weight, --tone-weight, --color-weight, --texture-weight, and --global-weight. Run edgeglyph glyph --help for their ranges.

Block mode

edgeglyph block input.png \
  --cols 72 --rows 24 \
  --colors 4 \
  --fit cover --focus-y 0.36 --zoom 0.9 \
  --output output.txt \
  --preview output.png

Block output uses only spaces and ▀▄█. Each terminal cell stores independent upper and lower colors.

Bead mode

edgeglyph bead input.png \
  --cols 96 --rows 54 \
  --colors 32 \
  --background auto \
  --assembly single \
  --board-style light --finish matte \
  --bead-size 12 \
  --preview bead-pattern.png \
  --chart bead-chart.png \
  --chart-title 'ATRI / 96 x 54' \
  --chart-header detailed \
  --chart-cell-size 24 \
  --metrics bead-counts.json

This example uses a 96 × 54 grid and 32 colors. It retains the wide composition and character details while keeping the numbered chart readable as a single high-resolution sheet.

--assembly single keeps the largest four-neighbor connected component, so the result can be fused as one physical piece. It removes detached beads and reports the original piece count in metrics. Use --assembly separate only when each disconnected component will be fused and mounted separately. Diagonal contact does not count as a physical connection.

Bead grids support up to 2048 × 2048 cells and 128 colors. Large previews reduce the displayed bead size without changing the logical grid. --chart exports a printable grid with per-cell color codes, coordinates, 10-cell guide lines, pattern statistics, fuse readiness, and palette counts with percentages. Use --chart-header detailed, compact, or none to control the header; --chart-title sets its name, and --chart-cell-size sets label density.

Outputs

Argument	File
-o, --output	plain UTF-8 art
--preview	rendered PNG
--chart	numbered bead assembly chart PNG
--lua-output	NvDash palette and text chunks
--metrics	JSON metrics and bead counts
--debug-dir	intermediate masks and reconstructions

Without --output, text is written to stdout. Metrics are written to stderr.

Print the full validated interface:

edgeglyph block --help
edgeglyph glyph --help
edgeglyph bead --help
edgeglyph schema

Python API

from edgeglyph.modes import glyph

result = glyph.render(
    "input.png",
    "/path/to/MapleMono-NF-Regular.ttf",
    profile="hybrid",
    color_mode="mono",
    cols=56,
    rows=28,
)

print("\n".join(result.lines))

Public mode modules are edgeglyph.modes.block, edgeglyph.modes.glyph, and edgeglyph.modes.bead.

Development

PYTHONPATH=src pytest -q
python -m compileall -q src
python -m build

Architecture and renderer boundaries are documented in docs/architecture.md. Contribution rules are in CONTRIBUTING.md.

References

• Structure-based ASCII Art, ACM Transactions on Graphics, 2010
• Chafa

License

MIT