rename, readme

Cargo.toml

@@ -1,10 +1,10 @@
 [package]
-name = "ratatui-imagine"
+name = "ratatu-image"
 version = "0.1.0"
 edition = "2021"
 autoexamples = true
 authors = ["Benjamin Große <[email protected]>"]
-description = "An image widget for ratatui, supporting sixels"
+description = "An image widget for ratatui, supporting sixels and unicode-halfblocks"
 keywords = ["ratatui", "image", "sixel", "tui", "terminal"]
 repository = "https://github.com/benjajaja/ratatui-image"
 homepage = "https://github.com/benjajaja/ratatui-image"
@@ -25,8 +25,10 @@ sixel = ["dep:sixel-rs"]
 [dependencies]
 dyn-clone = "1.0.11"
 image = { version = "0.24.5" }
+# ratatui with "cell skipping" and "window_size", https://github.com/tui-rs-revival/ratatui/pull/215 and https://github.com/tui-rs-revival/ratatui/pull/276
 ratatui = { git = "https://github.com/benjajaja/ratatui", rev = "8729b61fab885dc141c6e0968b4863386c544d9d", features = ["crossterm", "termion", "termwiz" ] }
 sixel-rs = { version = "0.3.3", optional = true }
+# crossterm with "window_size", https://github.com/crossterm-rs/crossterm/pull/790
 crossterm = { git = "https://github.com/benjajaja/crossterm", rev = "db515a16f95b36b4871488aa543f564bc929d62e" , optional = true }
 termion = { version = "2.0", optional = true }
 termwiz = { version = "0.20", optional = true }

README.md

@@ -1,5 +1,70 @@
-# Ratatui-imagine
+# Ratatu-image
 
-An image widget for [Ratatui](https://github.com/tui-rs-revival/ratatui/), supporting [Sixel](https://en.wikipedia.org/wiki/Sixel) and unicode-halfblock rendering.
+**THIS CRATE IS EXPERIMENTAL!**
 
+Render images with supported graphics protocols in the terminal with ratatui.
+While this generally might seem *contra natura* and something fragile, it can be worthwhile in
+some applications.
+
+![Screenshot](./assets/screenshot.png)
+
+The images are always resized so that they fit their nearest rectangle in columns/rows.
+The reason for this is because the image shall be drawn in the same "render pass" as all
+surrounding text, and cells under the area of the image skip the draw on the ratatui buffer
+level, so there is no way to "clear" previous drawn text. This would leave artifacts around the
+image border.
+For this resizing it is necessary to query the terminal font size in width/height.
+
+The [`FixedImage`] widget does not react to area resizes other than not overdrawing. Note that
+some image protocols or their implementations might not behave correctly in this aspect and
+overdraw or flicker outside of the image area.
+
+The [`ResizeImage`] stateful widget does react to area size changes by either resizing or
+cropping itself. The state consists of the latest resized image. A resize (and encode) happens
+every time the available area changes and either the image must be shrunk or it can grow. Thus,
+this widget may have a much bigger performance impact.
+
+Each widget is backed by a "backend" implementation of a given image protocol.
+
+Currently supported backends/protocols:
+
+## Halfblocks
+Uses the unicode character `▀` combined with foreground and background color. Assumes that the
+font aspect ratio is roughly 1:2. Should work in all terminals.
+## Sixel
+Experimental: uses temporary files.
+Uses [`sixel-rs`] to draw image pixels, if the terminal [supports] the [Sixel] protocol.
+
+[`sixel-rs`]: https://github.com/orhun/sixel-rs
+[supports]: https://arewesixelyet.com
+[Sixel]: https://en.wikipedia.org/wiki/Sixel
+
+# Examples
+
+For a more streamlined experience, see the [`crate::picker::Picker`] helper.
+
+```rust
+use image::{DynamicImage, ImageBuffer, Rgb};
+use ratatui_imagine::{
+    backend::{
+        FixedBackend,
+        halfblocks::FixedHalfblocks,
+    },
+    FixedImage, ImageSource, Resize,
+};
+
+let image: DynamicImage = ImageBuffer::<Rgb<u8>, Vec<u8>>::new(300, 200).into();
+
+let source = ImageSource::new(image, (7, 14), None);
+
+let static_image = Box::new(FixedHalfblocks::from_source(
+    &source,
+    Resize::Fit,
+    source.desired,
+)).unwrap();
+assert_eq!(43, static_image.rect().width);
+assert_eq!(15, static_image.rect().height);
+
+let image_widget = FixedImage::new(&static_image);
+```
 

examples/demo/main.rs

@@ -14,18 +14,18 @@ mod termwiz;
 
 use std::{error::Error, time::Duration};
 
+use ratatu_image::{
+    backend::{FixedBackend, ResizeBackend},
+    picker::Picker,
+    FixedImage, Resize, ResizeImage,
+};
 use ratatui::{
     backend::Backend,
     layout::{Constraint, Direction, Layout, Rect},
     text::Line,
     widgets::{Block, Borders, Paragraph, Wrap},
     Frame, Terminal,
 };
-use ratatui_imagine::{
-    backend::{FixedBackend, ResizeBackend},
-    picker::Picker,
-    FixedImage, Resize, ResizeImage,
-};
 
 #[cfg(feature = "crossterm")]
 use crate::crossterm::run;

src/lib.rs

@@ -1,4 +1,6 @@
-//! Ratatui image widgets
+//! Ratatu-image: image widgets for [Ratatui]
+//!
+//! [Ratatui]: https://github.com/tui-rs-revival/ratatui
 //!
 //! Render images with supported graphics protocols in the terminal with ratatui.
 //! While this generally might seem *contra natura* and something fragile, it can be worthwhile in