img2txt

Set output column count to a specific value

$ img2txt [[-W|--width]] [10] [path/to/image]

$ img2txt [[-H|--height]] [5] [path/to/image]

$ img2txt [[-x|--font-width]] [12] [path/to/image]

$ img2txt [[-y|--font-height]] [14] [path/to/image]

$ img2txt [[-b|--brightness]] [2] [path/to/image]

img2txt [OPTIONS] <IMAGE_FILE>

<IMAGE_FILE>
    Specifies the path to the input image file (e.g., image.jpg, picture.png) to be converted.

-w WIDTH
    Sets the desired width of the output ASCII art in characters. The tool will scale the image accordingly.

-H HEIGHT
    Sets the desired height of the output ASCII art in characters. Used in conjunction with -w to control dimensions, or independently for height-constrained output.

-c CHARSET
    Defines the character set to be used for mapping pixel brightness. Common values include 'standard' (dense to sparse, e.g., @#$%&XO*+=-. ) or 'inverted' character sequences.

-i or --invert
    Inverts the character mapping, causing darker characters to represent lighter pixels and vice-versa. This can be useful for viewing on terminals with dark backgrounds.

-o OUTPUT_FILE
    Directs the generated ASCII art to a specified file instead of printing it to standard output (stdout).

img2txt is a utility that transforms graphical image files (such as JPEG, PNG, or GIF) into text-based representations, commonly known as ASCII art. It works by analyzing the pixel intensity or color values of the input image and mapping them to a predefined set of characters. Typically, characters with higher visual density (e.g., @, #, $) are used for darker areas, while characters with lower density (e.g., ., ,, ) represent lighter areas.

The primary purpose of img2txt is to enable the viewing of images in text-only environments like terminals, command-line interfaces, or plain text files. The quality and recognizable detail of the generated ASCII art depend on factors such as the character set employed, the output resolution, and the contrast of the original image. Many implementations allow customization of these parameters to achieve desired visual effects.

img2txt is not a standard, universally adopted Linux command. Its implementation, available options, and behavior can vary significantly between different scripts or packages. Users should consult the specific documentation for their installed version. Most implementations convert images to grayscale before generating ASCII art, so color fidelity is generally lost. The visual quality of the output ASCII art is highly dependent on the input image's resolution, aspect ratio, and contrast.

img2txt algorithms typically quantize the image's brightness levels into a discrete number of steps, corresponding to the available characters in the chosen set. A common character set, ordered from densest (darkest perceived) to sparsest (lightest perceived), might look like: @ # S % ? * + ; : , . . Each pixel's brightness is mapped to the most appropriate character from this sequence.

Terminal characters are typically taller than they are wide (e.g., a 1:2 aspect ratio). When converting a square image to ASCII art, simply mapping pixels directly would result in a vertically stretched image. To maintain the original image's aspect ratio and prevent distortion, img2txt tools often adjust the output height or width, or use algorithms that account for the non-square nature of characters.

The concept of converting images to text predates graphical user interfaces, stemming from early computing environments where printers and terminals were text-only. ASCII art became a popular medium for sharing images and creative expression. While there isn't a single definitive 'img2txt' command with a unified history, various scripts and programs have been developed over time to automate this conversion. Many modern img2txt implementations leverage powerful image processing libraries like ImageMagick or Pillow (Python Imaging Library) to handle scaling, color reduction, and pixel analysis. Its usage persists primarily in command-line environments, for creative projects, and for displaying images where graphical capabilities are limited.

jp2a(1), caca-utils(1), aalib(1), convert(1) (ImageMagick)