ratatui-image

Showcase:

Image widgets for Ratatui

⚠️ THIS CRATE IS EXPERIMENTAL

⚠️ THE TERMWIZ RATATUI BACKEND IS BROKEN WITH THIS CRATE

Render images with graphics protocols in the terminal with Ratatui.

Quick start

use ratatui::{backend::{Backend, TestBackend}, Terminal, terminal::Frame, layout::Rect};
use ratatui_image::{
  picker::{Picker, BackendType},
  ImageSource, Resize, ResizeImage, protocol::ResizeProtocol,
};

struct App {
    // We need to hold the render state.
    image: Box<dyn ResizeProtocol>,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // It is highly recommended to use Picker::from_termios() instead!
    let mut picker = Picker::new((7, 16), BackendType::Sixel, None)?;

    let dyn_img = image::io::Reader::open("./assets/Ada.png")?.decode()?;
    let image = picker.new_state(dyn_img);
    let mut app = App { image };

    let backend = TestBackend::new(80, 30);
    let mut terminal = Terminal::new(backend)?;

    // loop:
    terminal.draw(|f| ui(f, &mut app))?;

    Ok(())
}

fn ui<B: Backend>(f: &mut Frame<B>, app: &mut App) {
    let image = ResizeImage::new(None);
    f.render_stateful_widget(image, f.size(), &mut app.image);
}

Example

See the [crate::picker::Picker] helper and examples/demo.

Current version: 0.2.0

Sixel compatibility and QA:

Latest Xterm testing screenshot:

Halfblocks should work in all terminals.

Comparison:

• viuer Renders graphics in different terminals/protocols, but "dumps" the image, making it difficult to work for TUI programs. The terminal protocol guessing code has been adapted to rustix, thus the author of viuer is included in the copyright notice.

License: MIT