README.md

PIC 📷

PIC (Preview Image in CLI ) is a lightweight Rust tool to preview images in your terminal!
With support for various image protocols (Kitty, Sixel, iTerm) it works in several terminals, and can still use Unicode blocks in case your terminal isn't supported. PIC also provides a library for you to use in your own tools!

Features

• Choose your favourite protocols
  • Kitty graphics with multiple actions available (load/clear)
  • Sixel which works in a lot of terminals
  • iTerm which displays GIFs incredibly well
  • Unicode blocks with truecolor/ansi256 support otherwise
• Customization
  • --x and --y options to choose where to display your image
  • --cols and --rows options to choose the size of your image (always tries preserving ratio)
  • --upscale option to preview image at full wanted size if needed
  • --static and --loop options to interact with GIFs
  • --protocol option to choose a protocol
  • --load --display and --clear options to interact with Kitty protocol

Installation

From source (Recommended)

Prerequisites

• Git
• Rust toolchain

Command line instructions

# Clone the repository
git clone https://github.com/emsquid/pic

# Build and install
cargo install --path pic

# Use freely
pic Images/YourFavouriteImage.png --cols 13 ...

From Cargo

Prerequisites

• Rust toolchain

Command line instructions

# Build and install
cargo install pic

# Use freely again
pic Images/YourFavouriteImage.png --cols 13 ...

As a library

Prerequisites

• Rust toolchain

Command line instructions

# Add the dependency in your project directory
cargo add pic

Examples

Blocks & Top quality previewing

Wide choice of options

Really nice GIFs in iTerm

And also nice in Blocks

Command line usage

Preview Image in CLI.

Usage: pic [OPTIONS] [PATH]...

Arguments:
  [PATH]...  Image(s) to preview

Options:
  -p, --protocol <PROTOCOL>  Previewing protocol to use [possible values: kitty, sixel, iterm, blocks]
  -x, --x <X>                x position (0 is left)
  -y, --y <Y>                y position (0 is top)
  -c, --cols <COLS>          Number of cols to fit the preview in
  -r, --rows <ROWS>          Number of rows to fit the preview in
      --spacing <SPACING>    Spacing between images if more than one file is provided
  -u, --upscale              Upscale image if needed
  -n, --no-newline           Don't print newline after preview
  -s, --static               Only show first frame of GIFs
  -l, --loop                 Loop GIFs infinitely
      --load <ID>            Load image with the given id (kitty only)
      --display <ID>         Display image with the given id (kitty only)
      --clear <ID>           Clear image with the given id (0 for all) (kitty only)
  -h, --help                 Print help
  -V, --version              Print version

Library usage

use pic

fn main() {
    // Choose images to preview
    let path1 = std::path::PathBuf::from("Picture/MyFavImage.png");
    let mut options = pic::options::Options::new(vec![path1]);

    // Set your options
    options.set_position(Some(10), None);
    options.set_size(Some(50), Some(50));
    options.upscale();

    // Preview
    if let Err(err) = pic::previewer::preview(&mut std::io::stdout(), &mut options) {
        eprintln!("{err}");
    };
}

Notes

• Sixel protocol may require libsixel to be installed
• iTerm protocol always loop GIFs, except if --static is specified

Progress

Help would be greatly appreciated

• Documentation
  • Write a greater README
  • Make releases/packages (publish on crates.io)
• Protocols support
  • Preview GIFs with Kitty protocol
  • Preview GIFs with Unicode blocks
  • Work on handling transparency/GIFs with Sixel protocol (GIFs work but don't render well)
  • Improve protocol support checking (need to test in various terminal)
• Miscellaneous
  • Implement caching somehow
  • Show cooler error messages
  • Write tests (I guess I need to do that...)