imgcat: add resize and resample functionality

This is primarily to improve the chances of displaying an arbitrary
image without resorting to additional external tools, that may be
difficult or impossible to install.

refs: #3716
refs: #3264

assets/shell-completion/bash

@@ -1451,7 +1451,7 @@ _wezterm() {
             return 0
             ;;
         wezterm__imgcat)
-            opts="-h --width --height --no-preserve-aspect-ratio --position --no-move-cursor --hold --help [FILE_NAME]"
+            opts="-h --width --height --no-preserve-aspect-ratio --position --no-move-cursor --hold --tmux-passthru --max-pixels --no-resample --resample-format --resample-filter --resize --show-resample-timing --help [FILE_NAME]"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -1469,6 +1469,26 @@ _wezterm() {
                     COMPREPLY=($(compgen -f "${cur}"))
                     return 0
                     ;;
+                --tmux-passthru)
+                    COMPREPLY=($(compgen -W "disable enable detect" -- "${cur}"))
+                    return 0
+                    ;;
+                --max-pixels)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
+                --resample-format)
+                    COMPREPLY=($(compgen -W "png jpeg input" -- "${cur}"))
+                    return 0
+                    ;;
+                --resample-filter)
+                    COMPREPLY=($(compgen -W "nearest triangle catmull-rom gaussian lanczos3" -- "${cur}"))
+                    return 0
+                    ;;
+                --resize)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
                 *)
                     COMPREPLY=()
                     ;;
@@ -1553,12 +1573,16 @@ _wezterm() {
             return 0
             ;;
         wezterm__set__working__directory)
-            opts="-h --help [CWD] [HOST]"
+            opts="-h --tmux-passthru --help [CWD] [HOST]"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
             fi
             case "${prev}" in
+                --tmux-passthru)
+                    COMPREPLY=($(compgen -W "disable enable detect" -- "${cur}"))
+                    return 0
+                    ;;
                 *)
                     COMPREPLY=()
                     ;;

assets/shell-completion/fish

@@ -161,10 +161,18 @@ complete -c wezterm -n "__fish_seen_subcommand_from cli; and __fish_seen_subcomm
 complete -c wezterm -n "__fish_seen_subcommand_from imgcat" -l width -d 'Specify the display width; defaults to "auto" which automatically selects an appropriate size.  You may also use an integer value `N` to specify the number of cells, or `Npx` to specify the number of pixels, or `N%` to size relative to the terminal width' -r
 complete -c wezterm -n "__fish_seen_subcommand_from imgcat" -l height -d 'Specify the display height; defaults to "auto" which automatically selects an appropriate size.  You may also use an integer value `N` to specify the number of cells, or `Npx` to specify the number of pixels, or `N%` to size relative to the terminal height' -r
 complete -c wezterm -n "__fish_seen_subcommand_from imgcat" -l position -d 'Set the cursor position prior to displaying the image. The default is to use the current cursor position. Coordinates are expressed in cells with 0,0 being the top left cell position' -r
+complete -c wezterm -n "__fish_seen_subcommand_from imgcat" -l tmux-passthru -d 'How to manage passing the escape through to tmux' -r -f -a "{disable	,enable	,detect	}"
+complete -c wezterm -n "__fish_seen_subcommand_from imgcat" -l max-pixels -d 'Set the maximum number of pixels per image frame. Images will be scaled down so that they do not exceed this size, unless `--no-resample` is also used. The default value matches the limit set by wezterm. Note that resampling the image here will reduce any animated images to a single frame' -r
+complete -c wezterm -n "__fish_seen_subcommand_from imgcat" -l resample-format -d 'Specify the image format to use to encode resampled/resized images.  The default is to match the input format, but you can choose an alternative format' -r -f -a "{png	,jpeg	,input	}"
+complete -c wezterm -n "__fish_seen_subcommand_from imgcat" -l resample-filter -d 'Specify the filtering technique used when resizing/resampling images.  The default is a reasonable middle ground of speed and quality' -r -f -a "{nearest	,triangle	,catmull-rom	,gaussian	,lanczos3	}"
+complete -c wezterm -n "__fish_seen_subcommand_from imgcat" -l resize -d 'Pre-process the image to resize it to the specified dimensions, expressed as eg: 800x600 (width x height). The resize is independent of other parameters that control the image placement and dimensions in the terminal; this is provided as a convenience preprocessing step' -r
 complete -c wezterm -n "__fish_seen_subcommand_from imgcat" -l no-preserve-aspect-ratio -d 'Do not respect the aspect ratio.  The default is to respect the aspect ratio'
 complete -c wezterm -n "__fish_seen_subcommand_from imgcat" -l no-move-cursor -d 'Do not move the cursor after displaying the image. Note that when used like this from the shell, there is a very high chance that shell prompt will overwrite the image; you may wish to also use `--hold` in that case'
 complete -c wezterm -n "__fish_seen_subcommand_from imgcat" -l hold -d 'Wait for enter to be pressed after displaying the image'
-complete -c wezterm -n "__fish_seen_subcommand_from imgcat" -s h -l help -d 'Print help'
+complete -c wezterm -n "__fish_seen_subcommand_from imgcat" -l no-resample -d 'Do not resample images whose frames are larger than the max-pixels value. Note that this will typically result in the image refusing to display in wezterm'
+complete -c wezterm -n "__fish_seen_subcommand_from imgcat" -l show-resample-timing -d 'When resampling or resizing, display some diagnostics around the timing/performance of that operation'
+complete -c wezterm -n "__fish_seen_subcommand_from imgcat" -s h -l help -d 'Print help (see more with \'--help\')'
+complete -c wezterm -n "__fish_seen_subcommand_from set-working-directory" -l tmux-passthru -d 'How to manage passing the escape through to tmux' -r -f -a "{disable	,enable	,detect	}"
 complete -c wezterm -n "__fish_seen_subcommand_from set-working-directory" -s h -l help -d 'Print help'
 complete -c wezterm -n "__fish_seen_subcommand_from record" -s h -l help -d 'Print help'
 complete -c wezterm -n "__fish_seen_subcommand_from replay" -l explain -d 'Explain what is being sent/received'

assets/shell-completion/zsh

@@ -382,16 +382,24 @@ _arguments "${_arguments_options[@]}" \
 '--width=[Specify the display width; defaults to "auto" which automatically selects an appropriate size.  You may also use an integer value \`N\` to specify the number of cells, or \`Npx\` to specify the number of pixels, or \`N%\` to size relative to the terminal width]:WIDTH: ' \
 '--height=[Specify the display height; defaults to "auto" which automatically selects an appropriate size.  You may also use an integer value \`N\` to specify the number of cells, or \`Npx\` to specify the number of pixels, or \`N%\` to size relative to the terminal height]:HEIGHT: ' \
 '--position=[Set the cursor position prior to displaying the image. The default is to use the current cursor position. Coordinates are expressed in cells with 0,0 being the top left cell position]:POSITION: ' \
+'--tmux-passthru=[How to manage passing the escape through to tmux]:TMUX_PASSTHRU:(disable enable detect)' \
+'--max-pixels=[Set the maximum number of pixels per image frame. Images will be scaled down so that they do not exceed this size, unless \`--no-resample\` is also used. The default value matches the limit set by wezterm. Note that resampling the image here will reduce any animated images to a single frame]:MAX_PIXELS: ' \
+'--resample-format=[Specify the image format to use to encode resampled/resized images.  The default is to match the input format, but you can choose an alternative format]:RESAMPLE_FORMAT:(png jpeg input)' \
+'--resample-filter=[Specify the filtering technique used when resizing/resampling images.  The default is a reasonable middle ground of speed and quality]:RESAMPLE_FILTER:(nearest triangle catmull-rom gaussian lanczos3)' \
+'--resize=[Pre-process the image to resize it to the specified dimensions, expressed as eg\: 800x600 (width x height). The resize is independent of other parameters that control the image placement and dimensions in the terminal; this is provided as a convenience preprocessing step]:WIDTHxHEIGHT: ' \
 '--no-preserve-aspect-ratio[Do not respect the aspect ratio.  The default is to respect the aspect ratio]' \
 '--no-move-cursor[Do not move the cursor after displaying the image. Note that when used like this from the shell, there is a very high chance that shell prompt will overwrite the image; you may wish to also use \`--hold\` in that case]' \
 '--hold[Wait for enter to be pressed after displaying the image]' \
-'-h[Print help]' \
-'--help[Print help]' \
+'--no-resample[Do not resample images whose frames are larger than the max-pixels value. Note that this will typically result in the image refusing to display in wezterm]' \
+'--show-resample-timing[When resampling or resizing, display some diagnostics around the timing/performance of that operation]' \
+'-h[Print help (see more with '\''--help'\'')]' \
+'--help[Print help (see more with '\''--help'\'')]' \
 '::file_name -- The name of the image file to be displayed. If omitted, will attempt to read it from stdin:_files' \
 && ret=0
 ;;
 (set-working-directory)
 _arguments "${_arguments_options[@]}" \
+'--tmux-passthru=[How to manage passing the escape through to tmux]:TMUX_PASSTHRU:(disable enable detect)' \
 '-h[Print help]' \
 '--help[Print help]' \
 '::cwd -- The directory to specify. If omitted, will use the current directory of the process itself:_files -/' \

ci/update-derived-files.sh

@@ -16,11 +16,20 @@ for mode in copy_mode search_mode ; do
   echo "\`\`\`" >> $fname
 done
 
-cargo run --example narrow $PWD/target/debug/wezterm --help | ./target/debug/strip-ansi-escapes > docs/examples/cmd-synopsis-wezterm--help.txt
+# For whatever reason, running --help on macOS vs. Linux results in different
+# opinions on leading/trailing whitespace. In order to minimize diffs and
+# be more consistent, explicitly trim leading/trailing space from the
+# output stream.
+# <https://unix.stackexchange.com/a/552191/123914>
+trim_file() {
+  perl -0777 -pe 's/^\n+|\n\K\n+$//g'
+}
+
+cargo run --example narrow $PWD/target/debug/wezterm --help | ./target/debug/strip-ansi-escapes | trim_file > docs/examples/cmd-synopsis-wezterm--help.txt
 
 for cmd in start ssh serial connect ls-fonts show-keys imgcat set-working-directory record replay  ; do
   fname="docs/examples/cmd-synopsis-wezterm-${cmd}--help.txt"
-  cargo run --example narrow $PWD/target/debug/wezterm $cmd --help | ./target/debug/strip-ansi-escapes > $fname
+  cargo run --example narrow $PWD/target/debug/wezterm $cmd --help | ./target/debug/strip-ansi-escapes | trim_file > $fname
 done
 
 for cmd in \
@@ -42,5 +51,5 @@ for cmd in \
     split-pane \
     ; do
   fname="docs/examples/cmd-synopsis-wezterm-cli-${cmd}--help.txt"
-  cargo run --example narrow $PWD/target/debug/wezterm cli $cmd --help | ./target/debug/strip-ansi-escapes > $fname
+  cargo run --example narrow $PWD/target/debug/wezterm cli $cmd --help | ./target/debug/strip-ansi-escapes | trim_file > $fname
 done

docs/changelog.md

@@ -41,6 +41,11 @@ As features stabilize some brief notes about them will accumulate here.
   in order to avoid the shell/prompt from mangling the image after it is printing.
   Support for this has limitations and will not take effect when the new
   `--position` argument is used. #3624
+* [wezterm imgcat](cli/imgcat.md) will now resample very large images in
+  order to increase the chances of successfully displaying an arbitrary image.
+  In addition, there are now a number of options for explicitly resizing
+  as a preprocessing step, and controlling the filtering and format used
+  by the resizing, along with showing diagnostics around the resize operation. #3264
 * Color schemes: [Ef-Cyprus](colorschemes/e/index.md#ef-cyprus),
   [Ef-Day](colorschemes/e/index.md#ef-day),
   [Ef-Deuteranopia-Dark](colorschemes/e/index.md#ef-deuteranopia-dark),

docs/examples/cmd-synopsis-wezterm-imgcat--help.txt

@@ -3,33 +3,94 @@ Output an image to the terminal
 Usage: wezterm imgcat [OPTIONS] [FILE_NAME]
 
 Arguments:
-  [FILE_NAME]  The name of the image file to be displayed. If omitted, will
-               attempt to read it from stdin
+  [FILE_NAME]
+          The name of the image file to be displayed. If omitted, will attempt
+          to read it from stdin
 
 Options:
       --width <WIDTH>
           Specify the display width; defaults to "auto" which automatically
           selects an appropriate size.  You may also use an integer value `N` to
           specify the number of cells, or `Npx` to specify the number of pixels,
           or `N%` to size relative to the terminal width
+
       --height <HEIGHT>
           Specify the display height; defaults to "auto" which automatically
           selects an appropriate size.  You may also use an integer value `N` to
           specify the number of cells, or `Npx` to specify the number of pixels,
           or `N%` to size relative to the terminal height
+
       --no-preserve-aspect-ratio
           Do not respect the aspect ratio.  The default is to respect the aspect
           ratio
+
       --position <POSITION>
           Set the cursor position prior to displaying the image. The default is
           to use the current cursor position. Coordinates are expressed in cells
           with 0,0 being the top left cell position
+
       --no-move-cursor
           Do not move the cursor after displaying the image. Note that when used
           like this from the shell, there is a very high chance that shell
           prompt will overwrite the image; you may wish to also use `--hold` in
           that case
+
       --hold
           Wait for enter to be pressed after displaying the image
+
+      --tmux-passthru <TMUX_PASSTHRU>
+          How to manage passing the escape through to tmux
+
+          [possible values: disable, enable, detect]
+
+      --max-pixels <MAX_PIXELS>
+          Set the maximum number of pixels per image frame. Images will be
+          scaled down so that they do not exceed this size, unless
+          `--no-resample` is also used. The default value matches the limit set
+          by wezterm. Note that resampling the image here will reduce any
+          animated images to a single frame
+
+          [default: 25000000]
+
+      --no-resample
+          Do not resample images whose frames are larger than the max-pixels
+          value. Note that this will typically result in the image refusing to
+          display in wezterm
+
+      --resample-format <RESAMPLE_FORMAT>
+          Specify the image format to use to encode resampled/resized images.
+          The default is to match the input format, but you can choose an
+          alternative format
+
+          [default: input]
+          [possible values: png, jpeg, input]
+
+      --resample-filter <RESAMPLE_FILTER>
+          Specify the filtering technique used when resizing/resampling images.
+          The default is a reasonable middle ground of speed and quality.
+
+          See
+          <https://docs.rs/image/latest/image/imageops/enum.FilterType.html#examples>
+          for examples of the different techniques and their tradeoffs.
+
+          [default: catmull-rom]
+          [possible values: nearest, triangle, catmull-rom, gaussian, lanczos3]
+
+      --resize <WIDTHxHEIGHT>
+          Pre-process the image to resize it to the specified dimensions,
+          expressed as eg: 800x600 (width x height). The resize is independent
+          of other parameters that control the image placement and dimensions in
+          the terminal; this is provided as a convenience preprocessing step.
+
+          Resizing animated images will reduce the image to a single frame.
+
+          The `--resample-filter` and `--resample-format` options give some
+          control over the quality of the resizing operation and the image
+          format used.
+
+      --show-resample-timing
+          When resampling or resizing, display some diagnostics around the
+          timing/performance of that operation
+
   -h, --help
-          Print help
+          Print help (see a summary with '-h')

docs/examples/cmd-synopsis-wezterm-set-working-directory--help.txt

@@ -1,7 +1,7 @@
 Advise the terminal of the current working directory by emitting an OSC 7 escape
 sequence
 
-Usage: wezterm set-working-directory [CWD] [HOST]
+Usage: wezterm set-working-directory [OPTIONS] [CWD] [HOST]
 
 Arguments:
   [CWD]   The directory to specify. If omitted, will use the current directory
@@ -10,4 +10,8 @@ Arguments:
           system hostname will be used
 
 Options:
-  -h, --help  Print help
+      --tmux-passthru <TMUX_PASSTHRU>
+          How to manage passing the escape through to tmux [possible values:
+          disable, enable, detect]
+  -h, --help
+          Print help