Overview
The ASCII Art Generator converts images, text, or webcam frames into character-based artwork. It is a client-side research lab with controllable sampling, brightness models, dithering, edge-aware glyph selection, density calibration, render modes, analytics charts, batch rendering, and multi-format export. No uploaded file is sent to a server; conversion happens in the browser.
Use this guide when you want a repeatable workflow for image-to-ASCII, text-to-ASCII, webcam capture, color ASCII, printable exports, or research comparison across character sets and sampling settings.
1. Input modes
+- Image: drag an image into the drop zone or browse for a file. Accepted types include PNG, JPEG, GIF, WebP, BMP, SVG, and TIFF. The UI rejects files over 20 MB and warns about very large images.
- Text: enter a text string, choose a browser font family, font size, weight, and optional inverted text rendering. The text input is rasterized before ASCII conversion.
- Webcam: start the camera, capture a still frame, or tick Keep converting every frame for repeated rendering. Webcam permission is browser-controlled and can be stopped from the tool.
2. Basic workflow
+- Open the tool: visit /tool/ascii/.
- Select an input mode: Image, Text, or Webcam.
- Set output width: start around 80 to 120 columns for readable output. Increase width for detailed images and decrease it for quick previews.
- Choose a character set: Standard is balanced; Detailed preserves tonal range; Blocks is graphic and dense; Braille supports fine texture.
- Choose a sampler: Area average is best for downscaled images; bilinear is smoother; point sampling is fast but can alias.
- Render: output updates automatically after you load a source or change a control.
- Inspect: check dimensions, character count, render time, charts, and edge preview.
- Export: copy output or download TXT, PNG, SVG, HTML, JSON, CSV, or ANSI (.ans).
3. Conversion controls
+- Character set: choose Standard, Detailed, Blocks, Minimal, Symbols, Lines, Braille, or enable a custom character string with at least two characters.
- Width and fixed height: width controls output columns. Height can be automatic from source aspect ratio or fixed for layout-constrained exports.
- Aspect ratio: compensates for character cell proportions. Monospace glyphs are usually taller than wide, so aspect correction is essential for faces, logos, and circles.
- Brightness model: choose the luminance formula used to map pixels to glyph density. Luminosity is the recommended default.
- Gamma: reshapes tonal response before quantization. Values above 1 lift shadows; values below 1 can recover detail in bright areas.
- Contrast and saturation: pre-process image data before conversion.
- Invert brightness: swaps dark and light mapping for dark-on-light or light-on-dark output styles.
- Dithering: choose none, Floyd-Steinberg error diffusion, or ordered Bayer dithering. Bayer can use 4x4 or 8x8 matrices.
- Edge-aware: uses Sobel edge detection to prefer directional glyphs when strong edges appear.
- Color mode: preserves per-character foreground color for HTML and canvas output. This is heavier than plain text but useful for faithful image exports.
- Filters: flip horizontally, flip vertically, rotate 90 degrees, add border, add frame, brighten, darken, or add noise to the ASCII output.
- Advanced settings: compression thins glyphs for sparse output, seed controls deterministic random effects, line height controls row spacing, and kerning adjusts glyph spacing.
4. Render modes
+- Text: plain monospace ASCII in a
preelement. Best for copying, terminal output, README files, and text exports. - HTML: span-based output that can preserve per-character colors. Best for web-based presentations and self-contained HTML export.
- Canvas: raster output for image downloads and visual preview. Best for PNG export and colored output.
- SVG: vector text output. Best for scalable graphics, design handoff, and crisp print assets.
5. Charts and metrics
+- Dimensions: output columns and rows.
- Character count: total generated characters.
- Render time: time for the current render.
- Character density chart: measured ink coverage of glyphs in the active character set.
- Histogram: luminance or character distribution after conversion.
- Frequency chart: how often each output glyph appears.
- Edge preview: Sobel gradient magnitude visualization for the source.
- Sampling comparison: visual comparison of sampling methods.
- Performance timeline: render-time trend as settings change.
6. Actions and exports
+- Copy: copies the latest plain-text ASCII output.
- TXT: downloads plain ASCII text.
- PNG: rasterizes canvas, HTML, SVG, or text output into a PNG where possible.
- SVG: exports the generated SVG or builds a text-based SVG fallback.
- HTML: exports a self-contained page with HTML or escaped text output.
- JSON: exports output, options, metrics, density calibration, and performance history.
- CSV: exports character frequency analysis for external review.
- ANSI: downloads a
.ansfile with truecolor escape codes, or copies them with Copy for terminal; needs color mode on. - Export all six: downloads TXT, PNG, SVG, HTML, JSON, and CSV in sequence.
- Fullscreen: opens the current text, canvas, SVG, or HTML output in a focused overlay.
7. Research tools
+- Batch (Export tab): renders each line of text through the current settings and reports timing, rows, and character count.
- Charset comparison (Compare tab): compares every built-in character set for count, density range, and monotonicity.
- Benchmark (Analysis tab): measures render performance across repeated conversions.
8. Quality recipes
+- Portraits: use Detailed charset, 120 to 180 columns, area sampling, mild contrast boost, gamma near 1.1, and edge-aware enabled.
- Logos: use Blocks or Minimal charset, high contrast, no dithering, fixed height if the brand lockup must fit a known area.
- Terminal art: use Standard charset, plain text render mode, no color mode, and a width that matches the target terminal.
- Texture-heavy photos: try Bayer 8x8 ordered dithering or Braille charset for fine detail.
- Line art: use Lines charset, edge-aware enabled, high edge strength, and little or no dithering.
- Social images: render canvas or SVG, increase font size, use high contrast, then export PNG or SVG.
9. Limits and performance
+- Files over 20 MB are rejected to protect browser memory.
- Images over the internal pixel or dimension threshold may be downscaled or warned before rendering.
- Floyd-Steinberg is sequential and can be slower than ordered dithering on large outputs.
- Color mode creates more output data because every glyph may carry its own color.
- PNG export can hit browser canvas memory limits for extremely large renders.
- Webcam live mode depends on camera frame rate, output width, device speed, and the 150 ms live debounce.
- Density calibration depends on the browser's font rendering; custom fonts can change perceived darkness.
10. Troubleshooting
+- No output appears: make sure an image is loaded, text is entered, or the webcam is started and a frame captured; output then renders automatically.
- Image looks stretched: adjust the aspect ratio slider until circles and faces look natural.
- Output is too dark: try invert, reduce contrast, raise gamma, or use a lighter character set.
- Output is too noisy: turn off dithering, lower width, reduce saturation or contrast boost, and use area sampling.
- Edges are missing: enable edge-aware mode and increase edge strength, or use a Lines/Detailed character set.
- Webcam fails: check browser camera permission, close other camera apps, use HTTPS or localhost, then restart the webcam.
- Export is blank: render once before exporting and choose the export format matching the current render mode.