Crate viuer

Expand description

Library to display images in the terminal.

This library contains functionality extracted from the viu crate. It aims to provide an easy to use interface to print images in the terminal. Uses some abstractions provided by the image crate. Kitty and iTerm graphic protocols are supported and used by default, if detected. If not, viuer will fallback to using regular half blocks instead (▄ and ▀).

§Basic Usage

The default features of this crate can only work with image::DynamicImage. The below example creates a 60x60 gradient and prints it. More options are available through the Config struct.

use image::{DynamicImage, Pixel, Rgba, RgbaImage};

let conf = viuer::Config {
    absolute_offset: false,
    ..Default::default()
};

let mut img = DynamicImage::ImageRgba8(RgbaImage::new(60, 60));
let start = Rgba::from_slice(&[0, 196, 0, 255]);
let end = Rgba::from_slice(&[255, 255, 255, 255]);
image::imageops::horizontal_gradient(&mut img, start, end);

viuer::print(&img, &conf).unwrap();

§Decoding files

To work directly with files, the non-default print-file feature must be enabled.

The example below shows how to print the image img.jpg in 40x30 terminal cells, with vertical offset of 4 and horizontal of 10, starting from the top left corner.

let conf = viuer::Config {
    width: Some(40),
    height: Some(30),
    x: 10,
    y: 4,
    ..Default::default()
};

#[cfg(feature="print-file")]
viuer::print_from_file("img.jpg", &conf).expect("Image printing failed.");

Structs§

Config: Configuration struct to customize printing behaviour.

Enums§

KittySupport: The extend to which the Kitty graphics protocol can be used.
ViuError: Custom error enum for viuing operations

Functions§

get_kitty_support: Returns the terminal’s support for the Kitty graphics protocol.
is_iterm_supported: Returns the terminal’s support for the iTerm graphics protocol.
is_sixel_supported: Returns the terminal’s support for Sixel.
print: Default printing method. Uses either iTerm or Kitty graphics protocol, if supported, and half blocks otherwise.
print_from_file: Helper method that reads a file, tries to decode and print it. The feature is available only with the print-file feature.
resize: Resize a image::DynamicImage so that it fits within optional width and height bounds. If none are provided, terminal size is used instead.
terminal_size: Try to get the terminal size. If unsuccessful, fallback to a default (80x24). Uses crossterm::terminal::size.

Type Aliases§

ViuResult: Custom result type for error-prone operations