catimg

Print a JPEG, PNG, or GIF to the terminal

$ catimg [path/to/file]

$ catimg -r 2 [path/to/file]

$ catimg -t [path/to/file]

$ catimg [-w|-H] [40] [path/to/file]

catimg [OPTIONS] FILE...

-c
    Force true color (24-bit) output mode, providing the highest color fidelity possible in supported terminals.

-w WIDTH
    Set the output width of the image in terminal columns. The image will be scaled to fit this width.

-h HEIGHT
    Set the output height of the image in terminal rows. The image will be scaled to fit this height.

-r RATIO
    Set a custom width/height ratio. For example, 0.5 will make the image twice as tall as it is wide.

-l
    List all available character sets that catimg can use for rendering the image.

-t CHAR_SET
    Specify a particular character set to use for rendering (e.g., block, ascii, unicode, braille).

-s
    Swap foreground and background colors, effectively inversing the image's colors.

-p
    Preserve the image's original aspect ratio (default behavior). This prevents distortion.

-f
    Force aspect ratio, ignoring the original. This can lead to distorted images but might be useful with custom -w or -h values.

-d
    Downscale the image if it is too large for the terminal window (default behavior).

-u
    Upscale the image if it is too small for the terminal window (default behavior).

-i
    Do not upscale or downscale the image; display it at its natural character size, potentially cropping or leaving empty space.

-v
    Enable verbose output, showing additional information like image dimensions and target output size.

-V
    Display the version information of catimg.

-H
    Display the help message, listing all available options and their usage.

catimg is a versatile command-line utility designed to render images directly within a terminal emulator. It accomplishes this by ingeniously converting traditional image pixel data into character-based representations, utilizing various character sets including standard ASCII, broader Unicode characters, or even specialized braille patterns. For modern terminals that boast support for true color (24-bit color), catimg can display images with remarkable color fidelity and detail. In environments with less capable terminals, it intelligently falls back to either 256-color or even more basic 8-color palettes, ensuring broad compatibility. The tool supports a wide array of common image formats such as PNG, JPEG, and GIF, making it an excellent and rapid solution for quick visual previews, for viewing images in environments where a graphical user interface (GUI) is either unavailable or undesired (like remote SSH sessions), or for seamless integration into custom shell scripts and automated workflows.

The quality and appearance of images displayed by catimg are highly dependent on the capabilities of the terminal emulator being used. Optimal results, especially with true color, require a terminal that fully supports 24-bit color. Character set rendering may also vary, leading to inconsistencies across different terminals. Displaying very large images can consume significant CPU resources and memory, potentially leading to slower performance.

For the best visual experience, ensure your terminal emulator (e.g., Alacritty, iTerm2, Kitty, GNOME Terminal with correct settings) supports 24-bit true color. Without it, catimg will fall back to a more limited color palette, which may reduce image quality. You can often check your terminal's true color support using external utilities or by testing catimg with the -c option on a colorful image.

catimg is particularly useful in several scenarios:
Quick Previews: Rapidly view images without launching a full-fledged graphical viewer.
Remote Servers: Display images when logged into a server via SSH where no GUI is available.
Scripting: Integrate image display into shell scripts for notifications, banners, or interactive tools.
Customization: Personalize your terminal environment with images as part of your prompt or startup messages.

catimg emerged as terminal emulators gained more sophisticated capabilities, particularly with the widespread adoption of true color support. Its development fills a niche for command-line users who require quick, native image viewing without reliance on graphical environments. It represents a step forward from older ASCII art converters by aiming for higher fidelity and direct color reproduction, making it a popular choice in scripting, remote server administration, and for customizing command-line interfaces.

jp2a(1), chafa(1), img2txt(1), lsix(1), feh(1)