Metadata

About

Tiv is a simple terminal image viewer that displays images directly in the terminal. It’s really just an ascii art generator based on Perl and Imagemagick. It accepts options to control the width and height of the image as well as the aspect ratio. The resolution of the image depends directly on your font settings.

Note that Tiv will not work correctly (read: “even remotely as expected”) if your terminal does not support 256 colors.

Tiv was written for fun to make use of some functions that I had created while playing around with terminal colors. Terminal chromophiles might also be interested in this, which was another coding byproduct.

The colorspace projection code in Tiv has also been rewritten in Python 3. You can find it in python3-colorsysplus.

Suggestions

Cascade images using the full terminal width with adaptive colors, pausing to view each one.

tiv -ac [img_files]

The same as the previous command, but with ascii output (this requires jp2a).

tiv -jac [img_files]

Add -h $LINES to the previous commands to restrict the image height ot the screen.

When using -j, try highlighting the output with the cursor.

Examples

Apart from the screenshots on this page, you will find other examples here.

Screenshots

Image sources:

• https://en.wikipedia.org/wiki/File:WhiteCat.jpg
• http://images.nationalgeographic.com/wpf/media-live/photos/000/239/cache/rajasthan-india-portrait_23942_990x742.jpg

Help Message

$ tiv --help

USAGE
  tiv [options] [paths]

OPTIONS
  --help
    Display this message and exit.

  -a
    Adapt colors to image palette. This will change the rgb values of terminal
    color in the range 16-255 to match the colors in the image after it is
    quantized to 240 colors. The changes will persist until they are reset using
    the "--reset" option.

    When viewing multiple images with this option, the "-p" option is
    implied because the adapation of the color palette is applied globally and
    thus affects previous images.

  -b
    Use a black background in combination with jp2a ascii output.

  -c
    Clear the screen before each image. This can speed up adaptive coloring
    and resetting.

  -h <int>
    Set the maximum output height. To maximize the image while keeping all of it
    on the screen, use "-h $LINES" or "-h `tput lines`". Leave this blank
    to maximize by width and allow the image to scroll.

  -j
    Use jp2a to output ascii characters. This can yield nice results when
    combined with adaptive colors.

  --no-dot
    Replace "." with " " when using the "-j" option. This allows the background
    to show through better on transparent terminals.

  -p
    Pause after displaying the image to prevent the prompt from pushing it up.
    Press enter to continue.

  --reset
    Reset the terminal colors to their default RGB values.

  -r <float>
    The aspect ratio of the output. Each "pixel" is the width of a space and the
    height of a line, which will depend on your font settings. The ratio should
    be given as <font width>/<font height>. The default is 0.6.

  -w <int>
    Set the maximum output width. This should not exceed the current number of
    columns. To get the maximum width, use "-w $COLUMNS" if your terminal sets
    this variable, or "-w `tput cols`" if you have tput installed, otherwise
    guess. If not given, tiv will try to use tput to get the columns, otherwise
    it will default to 80.

CHANGELOG