ImgCatr

A CLI application imgcatr for displaying images.

Install

Crate.io

(Recommended) Install from Crate.io, it's required to have Cargo on your computer.

cargo install imgcatr

On MacOS

1. Open Terminal
2. Use curl to Download the Release

curl -L https://github.com/SilinMeng0510/imgcatr/releases/download/v0.1.4/imgcatr-x86_64-apple-darwin.tar.gz -o imgcatr-x86_64-apple-darwin.tar.gz

3. Extract the Tarball

tar -xzf imgcatr-x86_64-apple-darwin.tar.gz

4. Move the Binary to a bin Directory

mv imgcatr /usr/local/bin/

On Linux

1. Open Terminal
2. Use curl to Download the Release

curl -L https://github.com/SilinMeng0510/imgcatr/releases/download/v0.1.4/imgcatr-x86_64-unknown-linux-gnu.tar.gz -o imgcatr-x86_64-unknown-linux-gnu.tar.gz

3. Extract the Tarball

tar -xzf imgcatr-x86_64-unknown-linux-gnu.tar.gz

4. Move the Binary to a bin Directory

sudo mv imgcatr /usr/local/bin/

On Windows

1. Using PowerShell (Windows 10 and later):
2. Use the Invoke-WebRequest cmdlet to download:

Invoke-WebRequest -Uri https://github.com/SilinMeng0510/imgcatr/releases/download/v0.1.4/imgcatr-x86_64-pc-windows-msvc.zip -OutFile imgcatr-windows.zip

3. Extract zip file

Expand-Archive -LiteralPath imgcatr-windows.zip -DestinationPath imgcatr-windows

(Optional) Create a directory (if you don't already have one):

New-Item -ItemType Directory -Force -Path "C:\Tools"

Move imgcatr.exe:

Move-Item imgcatr-windows\imgcatr.exe C:\Tools\

Usage

Overview

After installing the command on your computer's bin directory, you can directly call imgcatr on CLI with the following instructions to display your images.

Usage: imgcatr [OPTIONS] <IMAGE>

Arguments:
  <IMAGE>  Image file to display

Options:
  -s, --size <NxM>   Image size to display [default: 138x22]
  -f, --force        Don't preserve the image's aspect ratio
  -a, --ansi <ANSI>  Force output ANSI escape [possible values: truecolor, simple-black, simple-white, ascii]
  -h, --help         Print help
  -V, --version      Print version

There are some features that you can customize how you would like to display the image. You can follow my documentation below to get more information on this command.

Display Format

With the preparation of the image, you can specify the output format with -a or -ansi, where Imgcatr has 4 available output formats: truecolor, simple-black, simple-white, ascii, and no_ansi (For Windows OS).

Customized Size

The default size of the image display is set to the size of the CLI. This means that the height of your image will not go beyond the height of your terminal. However, you can specify the image size with -s or -size followed by input in <NxM> format. An example is provided below, where the image size is set to 100x100.

imgcatr cat.png --size 100x100

Ratio Preserve

The image ratio is preserved as default. And option -f or -force can force the program to not preserve the image ratio.

Additional Comments

Special Thanks

This work is derived from an open-sourced project named termimage. Here, I'm offering my special thanks to the team.

Comparison

The previous work termimage uses an older version of the clap-v2 crate(library). imgcatr replaces clap-v2 with the latest implementation of clap-v4, which has better performance overall. In addition, imgcatr offers a new feature in which users can display the ASCII format of images.

The Future

There will be potential improvement in future work with faster API and more features available.