2 unstable releases
0.3.0 | Sep 17, 2023 |
---|---|
0.2.0 | Sep 17, 2023 |
#102 in Graphics APIs
44 downloads per month
Used in aerostream
60KB
1.5K
SLoC
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, ProtocolType},
Resize, ResizeImage, protocol::{ImageSource, 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), ProtocolType::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);
}
Widget choice
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.
Examples
See the crate::picker::Picker helper and examples/demo
.
The lib also includes a binary that renders an image file.
Features
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.
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.
- yazi Not a library but a terminal file manager that implementes many graphics protocols and lets you preview images in the filesystem.
License: MIT
Dependencies
~10–25MB
~338K SLoC