PIXterm

PIXterm renders images in the terminal by recreating pixels using a combination of ANSI character background colors and the unicode lower half block element (▄).

Rendering Modes

• Classic Mode (No Dithering): Uses ANSI background colors and block elements for high fidelity.
• Dithering with Blocks: Uses block elements with different shades (█, ▓, ▒, ░) to simulate colors.
• Dithering with Characters: Uses standard ASCII characters to simulate colors.
• Dithering with Background Color Disabled (-nobg): Renders dithering without using the ANSI background color.

Features

• Transparency: If an image has transparency, an optional matte color can be used for the background.
• Format Support: JPEG, PNG, GIF, BMP, TIFF, and WebP.
• Remote Images: Supports fetching images via HTTP/HTTPS.

To ensure images render correctly, your environment must meet these requirements:

1. Terminal Support: Your terminal emulator must support true color.
2. Font Support: You must use a monospaced font that includes the unicode lower half block element: ▄ (U+2584).
   • For Dithering with Blocks mode, the font must also include: █ (U+2588), ▓ (U+2593), ▒ (U+2592), and ░ (U+2591).
   • Dithering with Characters mode works with standard ASCII characters.

If you are using Arch Linux, you can install pixterm via the AUR using yaourt.

yaourt -S pixterm

If you have a local clone of the repository, you can run or build the CLI tool from the repository root using standard Go commands.

# run
go run ./cmd/pixterm

# build
go build -o path/for/binary ./cmd/pixterm

To install the pixterm binary, ensure you have Go version 1.25 or higher installed. You can install it directly into your $GOPATH/bin (or $GOBIN) directory using the following command:

go install github.com/eliukblau/pixterm/cmd/pixterm@latest

PIXterm allows you to render images (JPEG, PNG, GIF, BMP, TIFF, WebP) directly in your ANSI terminal using true color. You can provide an image via a local file path or an HTTP/HTTPS URL.

Usage:

# From a local file
pixterm [options] path/to/image.png

# From a URL
pixterm [options] https://example.com/image.jpg

Supported Formats:

• Images: JPEG, PNG, GIF, BMP, TIFF, WebP
• Protocols: HTTP, HTTPS

pixterm image.png

If you want to embed the rendered image into a Go program, use the --go flag. This will output the Go source code required to print the image using fmt.Print().

pixterm --go image.png

Use the following flags to control how PIXterm renders images: