Support for subcommands in imgcat

[Ultrahalf]

Is your feature request related to a problem? Please describe.
I'm trying to use imgcat to preview files in my TUI file manager (LF). I couldn't figure out a way to clear and position the imgcat output.

Describe the solution you'd like
It would be helpful to have subcommads for position/clear similar to kitty icat
i.e:
wezterm imgcat --clear
wezterm imgcat --position {x}{y}

Describe alternatives you've considered
As mentioned in the example in the discussions
I have tried the following

tput cup 5 "${x}" && wezterm imgcat --width "${w}" --height "${h}" "$file"

which doesn't seem to work.

Additional context
related discussions

[ryanmsnyder]

Would love to see this enhancement as well. The kitty +kitten icat command works in wezterm but it would be great to have a native feature. Here's another related discussion for reference. Here's lf's wiki on using kitty to preview images within kitty or wezterm.

[wez]

imgcat now has --position, --no-move-cursor and --hold options in main and current nightly builds.
See https://wezfurlong.org/wezterm/cli/imgcat.html or wezterm imgcat --help for more information.

Please take a few moments to try out the fix and let me know how that works out. You can find the nightly downloads for your system in the wezterm installation docs.

If you prefer to use packages provided by your distribution or package manager of choice and don't want to replace that with a nightly download, keep in mind that you can download portable packages (eg: a .dmg file on macOS, a .zip file on Windows and an .AppImage file on Linux) that can be run without permanently installing or replacing an existing package, and can then simply be deleted once you no longer need them.

[AnonymouX47]

I guess this might be an opportunity to call your attention to #3264

[ryanmsnyder]

Thanks @wez. And thanks for wezterm - it's been awesome.

Does this mean wezterm imgcat now adheres to the kitty image protocol or is it still iTerm2? Is there any chance of also adding a --clear option similar to kitty +kitten icat --clear?

Also, how does the enable_kitty_graphics=true config option mentioned here relate to all of this? I searched the documentation but haven't been able to find info on it.

@Ultrahalf let me know if you're able to get this working as a file previewer for lf similar to how kitty +kitten icat works with it. I'll keep playing around with it but so far haven't been able to get it to work. wezterm imgcat /path/to/img.jpg --position='75,1' is working great outside of lf but when using it as an lf previewer, I'm getting an output of binary data. It might just be lf-related.

[wez]

imgcat still only uses the iterm2 protocol.
There is no --clear concept with the iterm2 protocol, so there is no option like that in imgcat.

There are still a few open kitty image protocol bugs in wezterm, and I'd like to see those get wrapped up before I consider supporting that protocol in imgcat.

enable_kitty_graphics is a setting for the terminal emulator in wezterm; when disabled, wezterm will act as though it doesn't support the kitty image protocol, so programs that probe for kitty image protocol support will conclude that wezterm doesn't support it, and ideally resort to a different technique.

[wez]

I also just pushed a commit with support for a few more options; that should show up in nightly builds in about an hour from now.

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

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues. If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.