ttyimg

README

ttyimg

A powerfull cli tool for encoding images into
Iterm2 / Kitty / Sixel

˙

---

https://github.com/user-attachments/assets/92b635e9-7ffe-4eed-8abe-a5d593504990

Installation 📦

go install github.com/Skardyy/ttyimg@latest

Usuage 💡

Usage: ttyimg [options] <path_to_image>
  -w string
         Resize width: <number> (pixels) / <number>px / <number>c (cells) / <number>% (default: 80%)
  -h string
         Resize height: <number> (pixels) / <number>px / <number>c (cells) / <number>% (default: 60%)
  -m string
         the resize mode to use when resizing: Fit, Strech, Crop (default: Fit)
  -center bool
         rather or not to center align the image (default: true)
  -p string
         Force protocol: kitty, iterm, sixel (default: auto)
  -f string
         fallback to when no protocol is supported: kitty, iterm, sixel (default: sixel)
  -spx string
         <width>x<height> or <width>x<height>xForce. specify the size of the winodw in px for fallback / overwrite (default: 1920x1080)
  -sc string
         <width>x<height> or <width>x<height>xForce. specify the size of the winodw in cell for fallback / overwrite (default: 120x30)
  -scale string
         <float>x<float> scales the spx and sc, only usefull for centering in smaller portions of the screen (default: 1x1)
  -cache bool
         rather or not to cache the heavy operations (default: true)

Supports ✨

• PNG
• JPEG
• TIFF
• SVG
• WEBP
• BMP
• GIF -- static only
• DOCX
• XLSX
• PDF
• PPTX
• ODG
• ODP
• ODS
• ODT

DOCX, XLSX, PDF PPTX, ODG, ODP, ODS, ODT require

Libreoffice

  make sure its installed and in your path  
  * windows: in windows its called soffice and should be in C:\Program Files\LibreOffice\program 
  * linux: should add it to path automatically

[!Note]
i am open for suggestions on other backends for the document types
Libreoffice was chosen for it being the only crossplatform one

App Logic

• first queries the size of the screen using:
  • cells: \x1b[18t
  • px: \x1b[14t
• if neither works it fallbacks to:
  • cells: term.GetSize(fd), uses win api / ioctl respectfully, shouldn't fail unless stderr is not the terminal.
  • px: ioctl / windows api. windows shouldn't fail, just not as accurate. ioctl only fails if stderr is not the temrinal.

Those options e.g (spx, sc, scale) aren't really important for normal users.
but can be very powerfull for power users trying to call the program in emulated environments, like neovim \ tmux.

using those values we can use sizes
like c (cells) and % for resizing the image
and even center the image