Difference between revisions of "How to preview images"

From Vifm Wiki
Jump to navigation Jump to search
(Link to instructions on integrating Überzug)
m (Source tags updates and HOWTO category)
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Starting with 0.8 vifm provides four macros describing preview area that can be used along with external applications to preview images in a terminal, they are:
+
Vifm v0.8 onward provides four macros describing preview area that can be used along with external applications to preview images in a terminal, they are:
 
* <code>%px</code> x coordinate of top-left corner of preview area;
 
* <code>%px</code> x coordinate of top-left corner of preview area;
 
* <code>%py</code> y coordinate of top-left corner of preview area;
 
* <code>%py</code> y coordinate of top-left corner of preview area;
Line 5: Line 5:
 
* <code>%ph</code> height of preview area.
 
* <code>%ph</code> height of preview area.
  
Below is a description and an example of making this work using <code>w3m</code> on GNU/Linux.
+
{{NOTE|text=Because terminals were built to display text rather than images, making them display images can be problematic. Some solutions work better in some environments than others, but none of them is perfect.}}
Mind that the support is lacking and you might have trouble making this work in many terminals. <code>xterm</code> without double-buffering tends to work bettern than others.
+
 
See the last section for a way of making it work on OS X with iTerm2.
+
== Überzug ==
  
 
For an instruction on how to use [https://github.com/seebye/ueberzug Überzug], which is likely to work better than <code>w3m</code>, see [https://www.youtube.com/watch?v=qgxsduCO1pE this video].
 
For an instruction on how to use [https://github.com/seebye/ueberzug Überzug], which is likely to work better than <code>w3m</code>, see [https://www.youtube.com/watch?v=qgxsduCO1pE this video].
 
The video is based on [https://www.reddit.com/r/linux/comments/aviu08/ueberzug_v1810_released/ehfj0s4/ this thread].
 
The video is based on [https://www.reddit.com/r/linux/comments/aviu08/ueberzug_v1810_released/ehfj0s4/ this thread].
 +
 +
== iTerm2 ==
 +
 +
See [https://github.com/vifm/vifm/issues/299 issue #299 on GitHub] for a command for OS X in iTerm2.
 +
 +
== Sixel graphics ==
 +
 +
If you're using a terminal which has good support of [https://en.wikipedia.org/wiki/Sixel Sixel] (i.e., it clears it properly) along with Vifm v0.10.1+ (for <code>%pd</code> macro), see [https://github.com/vifm/vifm/issues/419#issuecomment-485918513 issue #419 on GitHub] for sample configuration.
 +
 +
== w3m ==
 +
 +
Below is a description and an example of making this work using <code>w3m</code> on GNU/Linux.
 +
Mind that the support is lacking and you might have trouble making this work in many terminals. <code>xterm</code> without double-buffering tends to work better than others.
  
 
=== Prerequisites ===
 
=== Prerequisites ===
Line 24: Line 37:
 
after correcting several parameters at the top.
 
after correcting several parameters at the top.
  
<source lang="bash">
+
<syntaxhighlight lang="sh">
#!/bin/bash
+
#!/bin/sh
 
#
 
#
 
# Based on script by z3bra -- 2014-01-21
 
# Based on script by z3bra -- 2014-01-21
  
W3MIMGDISPLAY="/usr/libexec/w3m/w3mimgdisplay"
+
w3mimgdisplay='/usr/libexec/w3m/w3mimgdisplay'
FONTH=15 # Size of one terminal row
+
fonth=15 # Size of one terminal row   in pixels
FONTW=7 # Size of one terminal column
+
fontw=# Size of one terminal column in pixels
 +
 
 +
x=$1
 +
y=$2
 +
cols=$3
 +
lines=$4
 +
file=$5
  
X=$1
+
widthheight=$(printf '5;%s' "$file" | "$w3mimgdisplay")
Y=$2
+
width=${widthheight% *}
COLUMNS=$3
+
height=${widthheight#* }
LINES=$4
 
FILENAME=$5
 
  
read width height <<< `echo "5;$FILENAME" | $W3MIMGDISPLAY`
+
if [ -z "$width" ] || [ -z "$height" ]; then
if [ -z "$width" -o -z "$height" ]; then
+
     echo 'Failed to obtain image size. Check if fonth and fontw are correct.'
     echo 'Error: Failed to obtain image size.'
 
 
     exit 1
 
     exit 1
 
fi
 
fi
  
x=$((FONTW * X))
+
x=$((fontw * x))
y=$((FONTH * Y))
+
y=$((fonth * y))
 
+
max_width=$((fontw * cols))
max_width=$((FONTW * COLUMNS))
+
max_height=$((fonth * lines))
max_height=$((FONTH * LINES))
 
  
 
if [ "$width" -gt "$max_width" ]; then
 
if [ "$width" -gt "$max_width" ]; then
Line 60: Line 75:
 
fi
 
fi
  
w3m_command="0;1;$x;$y;$width;$height;;;;;$FILENAME\n4;\n3;"
+
printf '0;1;%s;%s;%s;%s;;;;;%s\n4;\n3;' "$x" "$y" "$width" "$height" "$file" |  
 
+
    "$w3mimgdisplay"
echo -e "$w3m_command" | $W3MIMGDISPLAY
+
</syntaxhighlight>
</source>
 
  
 
2. Update vifmrc with preview command like the following:
 
2. Update vifmrc with preview command like the following:
  
<source lang="bash">
+
<syntaxhighlight lang="bash">
 
fileviewer *.bmp,*.jpg,*.jpeg,*.png,*.gif,*.xpm
 
fileviewer *.bmp,*.jpg,*.jpeg,*.png,*.gif,*.xpm
 
         \ imgt %px %py %pw %ph %c
 
         \ imgt %px %py %pw %ph %c
</source>
+
</syntaxhighlight>
  
 
Replace "imgt" with path to preview script or just update name if
 
Replace "imgt" with path to preview script or just update name if
 
script is available in your <code>$PATH</code> (which is the case if you put it
 
script is available in your <code>$PATH</code> (which is the case if you put it
under <code>~/.vifm/scripts</code>).
+
under <code>$VIFM/scripts</code>).
  
 
=== Notes ===
 
=== Notes ===
Line 96: Line 110:
 
script for clearing image leftovers (below), development version of vifm and changed <code>:fileviewer</code> command like this:
 
script for clearing image leftovers (below), development version of vifm and changed <code>:fileviewer</code> command like this:
  
<source lang="bash">
+
<syntaxhighlight lang="bash">
 
fileviewer *.bmp,*.jpg,*.jpeg,*.png,*.gif,*.xpm
 
fileviewer *.bmp,*.jpg,*.jpeg,*.png,*.gif,*.xpm
 
         \ imgt %px %py %pw %ph %c
 
         \ imgt %px %py %pw %ph %c
 
         \ %pc
 
         \ %pc
 
         \ imgc %px %py %pw %ph
 
         \ imgc %px %py %pw %ph
</source>
+
</syntaxhighlight>
 
Where <code>imgc</code> is a script that clears background of the terminal (it's configuration is at the top):
 
Where <code>imgc</code> is a script that clears background of the terminal (it's configuration is at the top):
<source lang="bash">
+
<syntaxhighlight lang="bash">
 
#!/bin/bash
 
#!/bin/bash
  
Line 120: Line 134:
 
erase="6;$x;$y;$(( FONTW*COLUMNS ));$(( FONTH*LINES ))\n3;"
 
erase="6;$x;$y;$(( FONTW*COLUMNS ));$(( FONTH*LINES ))\n3;"
 
echo -e "$erase" | $W3MIMGDISPLAY
 
echo -e "$erase" | $W3MIMGDISPLAY
</source>
+
</syntaxhighlight>
 
This is the case at least for <code>urxvt</code>.
 
This is the case at least for <code>urxvt</code>.
  
Line 128: Line 142:
 
* [https://github.com/vifm/vifm/issues/82 Issue #82 on GitHub] for similar description and some discussion of some issues.
 
* [https://github.com/vifm/vifm/issues/82 Issue #82 on GitHub] for similar description and some discussion of some issues.
 
* [https://github.com/vifm/vifm/issues/102 Issue #102 on GitHub] for report on image clearing issues.
 
* [https://github.com/vifm/vifm/issues/102 Issue #102 on GitHub] for report on image clearing issues.
* [https://github.com/vifm/vifm/issues/299 Issue #299 on GitHub] for a command for OS X in iTerm2.
+
 
 +
== Other options ==
 +
 
 +
In case everything else doesn't work well and you're fine sacrificing quality, there are numerous other tools which approximate images using characters.
 +
 
 +
{{NOTE|text=As of v0.11 Vifm doesn't support 24-bit colors, so undefine <code>$COLORTERM</code> when using some of these tools (e.g., by prepending <code>env -u COLORTERM</code>).}}
 +
 
 +
Some of those tools:
 +
 
 +
* [https://github.com/larsjsol/shellpic shellpic]
 +
* [https://github.com/rr-/termi termi]
 +
* [https://github.com/stefanhaustein/TerminalImageViewer TerminalImageViewer]
 +
* [https://github.com/atanunq/viu viu]
 +
 
 +
[[Category:HOWTO]]

Latest revision as of 11:43, 31 August 2021

Vifm v0.8 onward provides four macros describing preview area that can be used along with external applications to preview images in a terminal, they are:

  • %px x coordinate of top-left corner of preview area;
  • %py y coordinate of top-left corner of preview area;
  • %pw width of preview area;
  • %ph height of preview area.

NOTE Because terminals were built to display text rather than images, making them display images can be problematic. Some solutions work better in some environments than others, but none of them is perfect.

Überzug[edit]

For an instruction on how to use Überzug, which is likely to work better than w3m, see this video. The video is based on this thread.

iTerm2[edit]

See issue #299 on GitHub for a command for OS X in iTerm2.

Sixel graphics[edit]

If you're using a terminal which has good support of Sixel (i.e., it clears it properly) along with Vifm v0.10.1+ (for %pd macro), see issue #419 on GitHub for sample configuration.

w3m[edit]

Below is a description and an example of making this work using w3m on GNU/Linux. Mind that the support is lacking and you might have trouble making this work in many terminals. xterm without double-buffering tends to work better than others.

Prerequisites[edit]

1. w3mimgdisplay which might be part of w3m package or a separate one.

2. Terminal emulator without double buffering, otherwise w3m will fail to display images properly.

Setup[edit]

1. Create script that invokes w3m. w3mimgdisplay executable might reside in different locations depending on the distribution. Below is a sample script, which can be used after correcting several parameters at the top.

#!/bin/sh
#
# Based on script by z3bra -- 2014-01-21

w3mimgdisplay='/usr/libexec/w3m/w3mimgdisplay'
fonth=15 # Size of one terminal row    in pixels
fontw=8  # Size of one terminal column in pixels

x=$1
y=$2
cols=$3
lines=$4
file=$5

widthheight=$(printf '5;%s' "$file" | "$w3mimgdisplay")
width=${widthheight% *}
height=${widthheight#* }

if [ -z "$width" ] || [ -z "$height" ]; then
    echo 'Failed to obtain image size. Check if fonth and fontw are correct.'
    exit 1
fi

x=$((fontw * x))
y=$((fonth * y))
max_width=$((fontw * cols))
max_height=$((fonth * lines))

if [ "$width" -gt "$max_width" ]; then
    height=$((height * max_width / width))
    width=$max_width
fi
if [ "$height" -gt "$max_height" ]; then
    width=$((width * max_height / height))
    height=$max_height
fi

printf '0;1;%s;%s;%s;%s;;;;;%s\n4;\n3;' "$x" "$y" "$width" "$height" "$file" | 
    "$w3mimgdisplay"

2. Update vifmrc with preview command like the following:

fileviewer *.bmp,*.jpg,*.jpeg,*.png,*.gif,*.xpm
         \ imgt %px %py %pw %ph %c

Replace "imgt" with path to preview script or just update name if script is available in your $PATH (which is the case if you put it under $VIFM/scripts).

Notes[edit]

State of terminal support[edit]

One should be aware that this is kinda hack as terminals weren't made to display pictures, thus there might be some difficulties (like double buffering or incomplete clearing). That said, it does work in sufficient amount of configurations.

Positioning[edit]

When running inside terminal emulators, coordinates known to applications are relative to pane/window position. This should be taken into account, because without applying proper offsets images may appear in unexpected locations.

Clearing[edit]

Depending on your terminal this may be enough or require additional script for clearing image leftovers (below), development version of vifm and changed :fileviewer command like this:

fileviewer *.bmp,*.jpg,*.jpeg,*.png,*.gif,*.xpm
         \ imgt %px %py %pw %ph %c
         \ %pc
         \ imgc %px %py %pw %ph

Where imgc is a script that clears background of the terminal (it's configuration is at the top):

#!/bin/bash

W3MIMGDISPLAY="/usr/libexec/w3m/w3mimgdisplay"
FONTH=15 # Size of one terminal row
FONTW=7 # Size of one terminal column

X=$1
Y=$2
COLUMNS=$3
LINES=$4

x=$((FONTW * X))
y=$((FONTH * Y))

erase="6;$x;$y;$(( FONTW*COLUMNS ));$(( FONTH*LINES ))\n3;"
echo -e "$erase" | $W3MIMGDISPLAY

This is the case at least for urxvt.

See also[edit]

Other options[edit]

In case everything else doesn't work well and you're fine sacrificing quality, there are numerous other tools which approximate images using characters.

NOTE As of v0.11 Vifm doesn't support 24-bit colors, so undefine $COLORTERM when using some of these tools (e.g., by prepending env -u COLORTERM).

Some of those tools: