termpix 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 321b92b52842de9fc8f7cd06688662f235423478f947ce9d5c96cac2083f582c
+  data.tar.gz: 76d16a71354bed1f1cc8e3196d01d48a09800c3f9a1eb9f330605f720ef3d06a
+SHA512:
+  metadata.gz: 5d510b46a5ad6de11c7ae89d43c7d0a07192db3a04590e5b684f9516113a18408089effc2048be2be0fe35cd9cf1ae9f4de0704d0a7e009773bb18b44beeb5b6
+  data.tar.gz: a52a9e6bace28d65a4b70db051c277979866ce2c00f6276f471d51c1b6f53b86c36a44b7c38a5977ff406de1bf0130e7484404a6aa589362db52fd123a1c478f

data/README.md

@@ -0,0 +1,101 @@
+# Termpix - Modern Terminal Image Display
+
+![Ruby](https://img.shields.io/badge/language-Ruby-red) [![Gem Version](https://badge.fury.io/rb/termpix.svg)](https://badge.fury.io/rb/termpix) ![Unlicense](https://img.shields.io/badge/license-Unlicense-green) ![Stay Amazing](https://img.shields.io/badge/Stay-Amazing-important)
+
+<img src="img/logo.svg" align="left" width="150" alt="Termpix Logo">
+
+Display images in the terminal using the best available protocol.
+
+## Features
+
+- Auto-detects terminal capabilities
+- Supports multiple protocols:
+  - Kitty Graphics Protocol (Kitty, WezTerm, Ghostty)
+  - Sixel (xterm, mlterm, foot, konsole, iTerm2)
+  - Überzug++ (modern X11/Wayland)
+  - w3mimgdisplay (legacy fallback)
+- Clean, simple API
+- Graceful fallbacks
+
+## Installation
+
+```bash
+gem install termpix
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'termpix'
+```
+
+## Usage
+
+```ruby
+require 'termpix'
+
+# Create display instance (auto-detects best protocol)
+display = Termpix::Display.new
+
+# Show an image
+display.show('path/to/image.png',
+  x: 10,           # X position in terminal characters
+  y: 5,            # Y position in terminal characters
+  max_width: 80,   # Maximum width in characters
+  max_height: 40)  # Maximum height in characters
+
+# Clear the image
+display.clear
+
+# Check if images are supported
+puts "Supported!" if display.supported?
+
+# Get protocol info
+info = display.info
+puts "Using protocol: #{info[:protocol]}"
+```
+
+## Force a Specific Protocol
+
+```ruby
+# Force Kitty protocol
+display = Termpix::Display.new(protocol: :kitty)
+
+# Force Sixel
+display = Termpix::Display.new(protocol: :sixel)
+
+# Force w3m
+display = Termpix::Display.new(protocol: :w3m)
+```
+
+## Dependencies
+
+- ImageMagick (`identify` and/or `convert` commands)
+- For w3m/Überzug++: `xwininfo` and `xdotool`
+
+## Terminal Support
+
+### Kitty Protocol
+- Kitty
+- WezTerm
+- Ghostty
+- Konsole (partial)
+
+### Sixel
+- xterm (with `-ti vt340`)
+- mlterm
+- foot
+- WezTerm
+- iTerm2
+
+### w3m/Überzug++
+- Most X11 terminals
+- Wayland terminals (Überzug++ only)
+
+## License
+
+Unlicense - Public Domain
+
+## Author
+
+Geir Isene - https://isene.com

data/lib/termpix/protocols.rb

@@ -0,0 +1,166 @@
+require 'shellwords'
+require 'base64'
+
+module Termpix
+  module Protocols
+    # Kitty Graphics Protocol
+    module Kitty
+      def self.display(image_path, x:, y:, max_width:, max_height:)
+        # Read image and encode to base64
+        image_data = Base64.strict_encode64(File.read(image_path))
+
+        # Use virtual placement (no cursor positioning - avoids curses conflicts)
+        # Transmit image without positioning, let it flow inline
+        $stdout.write "\e_Ga=T,f=100,q=2;#{image_data}\e\\"
+        $stdout.flush
+      end
+
+      def self.clear
+        # Delete all Kitty images
+        $stdout.write "\e_Ga=d,d=A\e\\"
+        $stdout.flush
+      end
+
+      private
+
+      def self.get_dimensions(image_path)
+        escaped = Shellwords.escape(image_path)
+        dimensions = `identify -format "%wx%h" #{escaped}[0] 2>/dev/null`.strip
+        return nil if dimensions.empty?
+        dimensions.split('x').map(&:to_i)
+      end
+
+      def self.scale_dimensions(w, h, max_w, max_h)
+        if w > max_w || h > max_h
+          scale = [max_w.to_f / w, max_h.to_f / h].min
+          w = (w * scale).to_i
+          h = (h * scale).to_i
+        end
+        [w, h]
+      end
+    end
+
+    # Sixel Protocol
+    module Sixel
+      def self.display(image_path, x:, y:, max_width:, max_height:)
+        escaped = Shellwords.escape(image_path)
+
+        # Convert character dimensions to approximate pixel dimensions
+        # Average character cell is roughly 10x20 pixels in most terminals
+        pixel_width = max_width * 10
+        pixel_height = max_height * 20
+
+        # Position cursor at the specified character position
+        print "\e[#{y};#{x}H"
+        # Convert to sixel and display with proper pixel dimensions
+        system("convert #{escaped} -resize #{pixel_width}x#{pixel_height} sixel:- 2>/dev/null")
+      end
+
+      def self.clear
+        # Sixel images are inline - they don't need explicit clearing
+        # The terminal will handle this when content is redrawn
+        # Don't use \e[2J as that clears the entire screen including curses content!
+        true
+      end
+    end
+
+    # Überzug++ Protocol
+    module Ueberzug
+      def self.display(image_path, x:, y:, max_width:, max_height:)
+        # Get terminal pixel dimensions
+        terminfo = `xwininfo -id $(xdotool getactivewindow 2>/dev/null) 2>/dev/null`
+        return unless terminfo && !terminfo.empty?
+
+        term_w = terminfo.match(/Width: (\d+)/)[1].to_i
+        term_h = terminfo.match(/Height: (\d+)/)[1].to_i
+
+        # Calculate character dimensions
+        char_w = term_w / `tput cols`.to_i
+        char_h = term_h / `tput lines`.to_i
+
+        # Convert character positions to pixels
+        img_x = char_w * x
+        img_y = char_h * y
+        img_w = char_w * max_width
+        img_h = char_h * max_height
+
+        # TODO: Implement actual Überzug++ protocol
+        # For now, placeholder
+      end
+
+      def self.clear
+        system('clear')
+      end
+    end
+
+    # w3mimgdisplay Protocol
+    module W3m
+      @imgdisplay = '/usr/lib/w3m/w3mimgdisplay'
+
+      def self.display(image_path, x:, y:, max_width:, max_height:)
+        # Get terminal pixel dimensions
+        terminfo = `xwininfo -id $(xdotool getactivewindow 2>/dev/null) 2>/dev/null`
+        return unless terminfo && !terminfo.empty?
+
+        term_w = terminfo.match(/Width: (\d+)/)[1].to_i
+        term_h = terminfo.match(/Height: (\d+)/)[1].to_i
+
+        # Calculate character dimensions
+        cols = `tput cols`.to_i
+        lines = `tput lines`.to_i
+        char_w = term_w / cols
+        char_h = term_h / lines
+
+        # Convert to pixel coordinates
+        img_x = char_w * x
+        img_y = char_h * y
+        img_max_w = char_w * max_width
+        img_max_h = char_h * max_height
+
+        # Get image dimensions
+        escaped = Shellwords.escape(image_path)
+        dimensions = `identify -format "%wx%h" #{escaped}[0] 2>/dev/null`.strip
+        return if dimensions.empty?
+
+        img_w, img_h = dimensions.split('x').map(&:to_i)
+
+        # Scale if needed
+        if img_w > img_max_w || img_h > img_max_h
+          scale_w = img_max_w.to_f / img_w
+          scale_h = img_max_h.to_f / img_h
+          scale = [scale_w, scale_h].min
+          img_w = (img_w * scale).to_i
+          img_h = (img_h * scale).to_i
+        end
+
+        # Display using w3mimgdisplay protocol
+        `echo '0;1;#{img_x};#{img_y};#{img_w};#{img_h};;;;;#{image_path}
+4;
+3;' | #{@imgdisplay} 2>/dev/null`
+      end
+
+      def self.clear(x:, y:, width:, height:, term_width:, term_height:)
+        # Clear only the image overlay in the specified area
+        terminfo = `xwininfo -id $(xdotool getactivewindow 2>/dev/null) 2>/dev/null`
+        return true unless terminfo && !terminfo.empty?
+
+        term_w = terminfo.match(/Width: (\d+)/)[1].to_i
+        term_h = terminfo.match(/Height: (\d+)/)[1].to_i
+
+        # Calculate character dimensions
+        char_w = term_w / term_width
+        char_h = term_h / term_height
+
+        # Convert to pixel coordinates with slight margin adjustment
+        img_x = (char_w * x) - char_w
+        img_y = char_h * y
+        img_max_w = (char_w * width) + char_w + 2
+        img_max_h = char_h * height + 2
+
+        # Use w3mimgdisplay command "6" to clear just the image area
+        `echo "6;#{img_x};#{img_y};#{img_max_w};#{img_max_h};\n4;\n3;" | #{@imgdisplay} 2>/dev/null`
+        true
+      end
+    end
+  end
+end

data/lib/termpix/version.rb

@@ -0,0 +1,3 @@
+module Termpix
+  VERSION = "0.1.0"
+end

data/lib/termpix.rb

@@ -0,0 +1,120 @@
+require_relative 'termpix/version'
+require_relative 'termpix/protocols'
+
+module Termpix
+  class Display
+    attr_reader :protocol
+
+    def initialize(protocol: nil)
+      @protocol = protocol || detect_protocol
+      @current_image = nil
+    end
+
+    # Display an image at the specified position
+    # @param image_path [String] Path to the image file
+    # @param x [Integer] X position in terminal characters
+    # @param y [Integer] Y position in terminal characters
+    # @param max_width [Integer] Maximum width in terminal characters
+    # @param max_height [Integer] Maximum height in terminal characters
+    def show(image_path, x: 0, y: 0, max_width: 80, max_height: 24)
+      return false unless @protocol
+      return false unless File.exist?(image_path)
+
+      case @protocol
+      when :kitty
+        Protocols::Kitty.display(image_path, x: x, y: y, max_width: max_width, max_height: max_height)
+      when :sixel
+        Protocols::Sixel.display(image_path, x: x, y: y, max_width: max_width, max_height: max_height)
+      when :ueberzug
+        Protocols::Ueberzug.display(image_path, x: x, y: y, max_width: max_width, max_height: max_height)
+      when :w3m
+        Protocols::W3m.display(image_path, x: x, y: y, max_width: max_width, max_height: max_height)
+      else
+        return false
+      end
+
+      @current_image = image_path
+      true
+    end
+
+    # Clear the currently displayed image
+    def clear(x: 0, y: 0, width: 80, height: 24, term_width: 80, term_height: 24)
+      return false unless @protocol
+
+      case @protocol
+      when :kitty
+        Protocols::Kitty.clear
+      when :sixel
+        Protocols::Sixel.clear
+      when :ueberzug
+        Protocols::Ueberzug.clear
+      when :w3m
+        Protocols::W3m.clear(x: x, y: y, width: width, height: height, term_width: term_width, term_height: term_height)
+      end
+
+      @current_image = nil
+      true
+    end
+
+    # Check if image display is supported
+    def supported?
+      !@protocol.nil?
+    end
+
+    # Get information about the current protocol
+    def info
+      {
+        protocol: @protocol,
+        supported: supported?,
+        current_image: @current_image
+      }
+    end
+
+    private
+
+    def detect_protocol
+      # Check for Sixel support first - works better with curses apps
+      # Note: urxvt/rxvt-unicode does NOT support sixel unless specially compiled
+      # Kitty's sixel support doesn't work properly (shows ASCII) - use w3m instead
+      if ENV['TERM']&.match(/^xterm(?!-kitty)|^mlterm|^foot/)
+        return :sixel if check_dependency('convert')
+      end
+
+      # Kitty graphics protocol disabled - incompatible with curses apps
+      # Kitty protocol needs full terminal control, conflicts with curses rendering
+      # Users can choose between:
+      # 1. Enable w3m for Kitty (has brief flash) - set TERMPIX_KITTY_USE_W3M=1
+      # 2. No images in Kitty (clean UI)
+
+      # Überzug++ - disabled for now (implementation incomplete)
+      # TODO: Implement proper Überzug++ JSON-RPC communication
+      # if command_exists?('ueberzug') || command_exists?('ueberzugpp')
+      #   if check_dependencies('xwininfo', 'xdotool', 'identify')
+      #     return :ueberzug
+      #   end
+      # end
+
+      # Fall back to w3m (works everywhere but has brief flash in Kitty)
+      if command_exists?('/usr/lib/w3m/w3mimgdisplay')
+        if check_dependencies('xwininfo', 'xdotool', 'identify')
+          return :w3m
+        end
+      end
+
+      # No supported protocol found
+      nil
+    end
+
+    def command_exists?(cmd)
+      system("which #{cmd} > /dev/null 2>&1")
+    end
+
+    def check_dependency(cmd)
+      command_exists?(cmd)
+    end
+
+    def check_dependencies(*cmds)
+      cmds.all? { |cmd| command_exists?(cmd) }
+    end
+  end
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: termpix
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Geir Isene
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-10-26 00:00:00.000000000 Z
+dependencies: []
+description: Termpix provides a clean API for displaying images in the terminal using
+  the best available protocol (Kitty, Sixel, Überzug++, or w3m). Auto-detects terminal
+  capabilities and falls back gracefully.
+email: g@isene.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/termpix.rb
+- lib/termpix/protocols.rb
+- lib/termpix/version.rb
+homepage: https://github.com/isene/termpix
+licenses:
+- Unlicense
+metadata:
+  source_code_uri: https://github.com/isene/termpix
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: Modern terminal image display with multiple protocol support
+test_files: []