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 ```bash

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 ```bash

Build and install

cargo install pic

Use freely again

pic Images/YourFavouriteImage.png --cols 13 ... ```

As a library

Prerequisites - Rust toolchain

Command line instructions ```bash

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]

Arguments: Image to preview

Options: -x, --x x position (0 is left) -y, --y y position (0 is top) -c, --cols Number of cols to fit the preview in -r, --rows Number of rows to fit the preview in -u, --upscale Upscale image if needed -s, --static Only show first frame of GIFs -l, --loop Loop GIFs infinitely -p, --protocol Previewing protocol to use [possible values: kitty, sixel, iterm, blocks] --load Load image with the given id (kitty only) --display Display image with the given id (kitty only) --clear Clear image with the given id (0 for all) (kitty only) -h, --help Print help -V, --version Print version ```

Library usage

```rust 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
  • [x] 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...)