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].
```rust use ratatui::{backend::{Backend, TestBackend}, Terminal, terminal::Frame, layout::Rect}; use ratatui_image::{ picker::{Picker, ProtocolType}, Resize, ResizeImage, protocol::{ImageSource, ResizeProtocol}, };
struct App {
// We need to hold the render state.
image: Box
fn main() -> Result<(), Box
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
The [ResizeImage] widget adapts to its render area, is more robust against overdraw bugs and artifacts, and plays nicer with some of the graphics protocols. However, frequent render area resizes might affect performance.
The [FixedImage] widgets does not adapt to rendering area (except not drawing at all if space is insufficient), is more bug prone (overdrawing or artifacts), and is not aligned with some of the protocols. Its only upside is that it is stateless (in terms of ratatui), and thus is not performance-impacted by render area resizes.
See the [crate::picker::Picker] helper and examples/demo.
The lib also includes a binary that renders an image file.
sixel (default) compiles with libsixel.rustix (default) enables [picker::Picker::from_termios] to guess which graphics protocol to use and what
font-size the terminal has.crossterm / termion / termwiz should match your ratatui backend. termwiz is not
working correctly with ratatu-image!serde for #[derive]s on [picker::ProtocolType] for convenience, because it might be
useful to save it in some user configuration.Current version: 0.3.0
Sixel compatibility and QA:
Terminal | Fixed | Resize | Notes -----------|-------|--------|------- Xterm | ✔️ | ✔️ | Foot | ✔️ | ✔️ | kitty | ✔️ | ✔️ | Alacritty | ✔️ | ❌ | with sixel patch, but never clears graphics. iTerm2 | ❌ | ❌ | Unimplemented, has a protocolo similar to sixel konsole | ❌ | ❌ | Does not clear graphics unless cells have a background style Contour | ❌ | ❌ | Text over graphics Wezterm | ❌ | ❌ | Buggy ctx | ❌ | ❌ | Buggy Blackbox | ❔ | ❔ | Untested
Latest Xterm testing screenshot:
Halfblocks should work in all terminals.
License: MIT