Convert image brightness to ASCII art with a custom character ramp

Supply integer values from 0 for black through 255 for white, then choose a character ramp ordered from darkest to brightest. The converter assigns every sample to the nearest position in that ramp and preserves the grid as lines of text. It is useful for terminal previews, text-only renderers, creative coding, image-processing lessons, and pipelines that already produce grayscale pixel or cell averages.

Prepare a useful brightness grid

Start with a rectangular array in which every inner array represents one output line and every value represents one character cell. Samples must be integers between 0 and 255: zero means fully dark, 255 means fully bright, and values between them represent intermediate tones. If your source is a full-resolution photograph, reduce it before calling the converter. Average or otherwise summarize a block of pixels for each desired character position, because mapping one image pixel to one text character usually creates an enormous result and exaggerates the different physical proportions of pixels and glyphs. Keep every row the same length so the spatial relationship remains unambiguous. A practical terminal preview might use 40 to 120 columns, with fewer rows chosen to compensate for characters generally being taller than they are wide. The capability deliberately accepts brightness data rather than an uploaded image: this keeps the transformation deterministic and lets you control resizing, cropping, color conversion, alpha handling, and contrast in the earlier stage of your pipeline. Once those choices are settled, the same grid always yields the same text.

Choose and understand the ASCII ramp

Write the ramp from the character that should represent the darkest sample to the character that should represent the brightest. A ramp such as <code>@%#*+=-:. </code> moves from visually dense marks toward a final space, so black areas become heavy symbols and white areas disappear into the background. You can reverse that order for a light-on-dark interpretation, or use a short ramp such as <code>#.</code> for a stark two-tone result. Every Unicode character is treated as one ramp position, including spaces and emoji, although ordinary fixed-width characters produce the most predictable alignment. For each brightness sample, the converter scales the 0–255 range across all available ramp positions and rounds to the nearest one. Both endpoints are exact: zero always selects the first character and 255 always selects the last. Repeated characters are allowed and can intentionally widen a tonal band. An empty ramp is rejected because no valid output character could be selected. Remember that a trailing space is meaningful even when it is difficult to see in a form or JSON viewer.

Use the returned text and metadata

The result includes <code>art</code>, a single newline-separated string ready for a terminal, text file, log entry, or code block. It also includes <code>lines</code> as an array, which is often more convenient when a program needs to add indentation, borders, ANSI color, or line numbers without splitting the text again. The reported row and column counts make it easy to verify dimensions before displaying or storing the result, while <code>ramp_length</code> records how many Unicode characters participated in the mapping. No random dithering is applied, so nearby brightness values may share a character when the ramp is short. That behavior is intentional and reproducible. If you want dithered output, apply a deterministic error-diffusion or ordered-dither step while preparing the sample grid, then submit its resulting brightness values. For faithful alignment, display the art with a monospaced font and preserve whitespace. HTML consumers should render it as text inside a preformatted element rather than interpreting it as markup, especially when a custom ramp contains angle brackets or ampersands.