Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add section on rendering images 📚 #141

Draft
wants to merge 4 commits into
base: ratatui-book
Choose a base branch
from

Conversation

kdheepak
Copy link
Contributor

@kdheepak kdheepak commented Nov 2, 2023

No description provided.

Copy link

github-actions bot commented Nov 2, 2023

PR Preview Action v1.4.4
🚀 Deployed preview to https://ratatui-org.github.io/ratatui-book/pr-preview/pr-141/
on branch gh-pages at 2023-11-02 02:04 UTC

src/how-to/render/images.md Outdated Show resolved Hide resolved
4. Braille
5. other unicode characters

Sixel is a standard for drawing in the terminal but not all terminals support it.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not a very good one ;) From memory it's restricted to 6 bits per channel color instead of 8 bits

There's basically a few different ways to "draw images" in the terminal.

1. Sixel
2. Terminal specific control sequences (ITerm2 vs Kitty vs others)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Link https://sw.kovidgoyal.net/kitty/graphics-protocol/ and https://iterm2.com/documentation-images.html
I have previously seen a support page for which terminal emulators support which protocols but can't find it again unfortunately.

src/how-to/render/images.md Outdated Show resolved Hide resolved
Comment on lines +13 to +14
The terminal specific control sequences are just that, terminal specific. And these are different
for each terminal, and there's no easy way to detect which terminal emulator you are running it, so
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorta - often terminals support multiple protocols, so it's worth finding that page on compatibility.
It's worth linking https://github.com/wez/wezterm/blob/main/termwiz/src/caps/mod.rs for the commentary on detection.

src/how-to/render/images.md Outdated Show resolved Hide resolved
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add some examples (links in discord)

Yeah - pretty much anything that gives you a grid of characters will work - just wrap it int a Widget that splats the chars to the cells. E.g. https://github.com/joshka/tui-big-text/blob/5b030f6f3c5587e25a38d8e6317d89e58b93050e/src/lib.rs#L128-L139

/// Render a single 8x8 glyph into a cell by setting the corresponding cells in the buffer.
fn render_glyph(glyph: [u8; 8], area: Rect, buf: &mut Buffer) {
    for (row, y) in glyph.iter().zip(area.top()..area.bottom()) {
        for (col, x) in (area.left()..area.right()).enumerate() {
            let cell = buf.get_mut(x, y);
            match row & (1 << col) {
                0 => cell.set_symbol(" "),
                _ => cell.set_symbol("█"),
            };
        }
    }
}

Or a nicer version of half blocks example: https://github.com/ratatui-org/ratatui/blob/66215e286740c6d7816e3ba5df73e240320ba332/examples/colors_rgb.rs#L143-L156 (from an open PR ratatui/ratatui#583)

impl Widget for RgbColors<'_> {
    fn render(self, area: Rect, buf: &mut Buffer) {
        let colors = self.colors;
        for (xi, x) in (area.left()..area.right()).enumerate() {
            // animate the colors by shifting the x index by the frame number
            let xi = (xi + self.frame_count) % (area.width as usize);
            for (yi, y) in (area.top()..area.bottom()).enumerate() {
                let fg = colors[yi * 2][xi];
                let bg = colors[yi * 2 + 1][xi];
                buf.get_mut(x, y).set_char('▀').set_fg(fg).set_bg(bg);
            }
        }
    }
}

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add some links to relevant crates

@joshka joshka mentioned this pull request Jun 4, 2024
joshka pushed a commit that referenced this pull request Jun 4, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants