Class ITerm2Graphics

  • All Implemented Interfaces:
    TerminalGraphics

    public class ITerm2Graphics
    extends java.lang.Object
    implements TerminalGraphics
    Implementation of iTerm2's Inline Images Protocol.

    The iTerm2 Inline Images Protocol allows displaying images directly in the terminal using base64-encoded data embedded in escape sequences. The protocol uses OSC (Operating System Command) escape sequences of the form: <ESC>]1337;File=<parameters>:<base64_data><BEL>

    This protocol is supported by:

    • iTerm2
    • Some other terminals with iTerm2 compatibility

    The protocol supports various parameters for controlling image display including dimensions, positioning, and preservation of aspect ratio.

    Since:
    3.30.0
    See Also:
    iTerm2 Inline Images
    • Constructor Detail

      • ITerm2Graphics

        public ITerm2Graphics()
        Creates a new ITerm2Graphics instance.
    • Method Detail

      • isSupported

        public boolean isSupported​(Terminal terminal)
        Description copied from interface: TerminalGraphics
        Checks if this graphics protocol is supported by the given terminal.
        Specified by:
        isSupported in interface TerminalGraphics
        Parameters:
        terminal - the terminal to check
        Returns:
        true if the protocol is supported, false otherwise
      • getPriority

        public int getPriority()
        Description copied from interface: TerminalGraphics
        Gets the priority of this protocol for automatic selection. Higher values indicate higher priority.
        Specified by:
        getPriority in interface TerminalGraphics
        Returns:
        the priority value (0-100)
      • displayImage

        public void displayImage​(Terminal terminal,
                                 java.awt.image.BufferedImage image)
                          throws java.io.IOException
        Description copied from interface: TerminalGraphics
        Displays a BufferedImage on the terminal using this graphics protocol.
        Specified by:
        displayImage in interface TerminalGraphics
        Parameters:
        terminal - the terminal to display the image on
        image - the image to display
        Throws:
        java.io.IOException - if an I/O error occurs
      • displayImage

        public void displayImage​(Terminal terminal,
                                 java.awt.image.BufferedImage image,
                                 TerminalGraphics.ImageOptions options)
                          throws java.io.IOException
        Description copied from interface: TerminalGraphics
        Displays a BufferedImage on the terminal with custom options.
        Specified by:
        displayImage in interface TerminalGraphics
        Parameters:
        terminal - the terminal to display the image on
        image - the image to display
        options - display options for the image
        Throws:
        java.io.IOException - if an I/O error occurs
      • displayImage

        public void displayImage​(Terminal terminal,
                                 java.io.File file)
                          throws java.io.IOException
        Description copied from interface: TerminalGraphics
        Displays an image file on the terminal.
        Specified by:
        displayImage in interface TerminalGraphics
        Parameters:
        terminal - the terminal to display the image on
        file - the image file to display
        Throws:
        java.io.IOException - if an I/O error occurs
      • displayImage

        public void displayImage​(Terminal terminal,
                                 java.io.File file,
                                 TerminalGraphics.ImageOptions options)
                          throws java.io.IOException
        Description copied from interface: TerminalGraphics
        Displays an image file on the terminal with custom options.
        Specified by:
        displayImage in interface TerminalGraphics
        Parameters:
        terminal - the terminal to display the image on
        file - the image file to display
        options - display options for the image
        Throws:
        java.io.IOException - if an I/O error occurs
      • displayImage

        public void displayImage​(Terminal terminal,
                                 java.io.InputStream inputStream)
                          throws java.io.IOException
        Description copied from interface: TerminalGraphics
        Displays an image from an input stream on the terminal.
        Specified by:
        displayImage in interface TerminalGraphics
        Parameters:
        terminal - the terminal to display the image on
        inputStream - the input stream containing the image data
        Throws:
        java.io.IOException - if an I/O error occurs
      • displayImage

        public void displayImage​(Terminal terminal,
                                 java.io.InputStream inputStream,
                                 TerminalGraphics.ImageOptions options)
                          throws java.io.IOException
        Description copied from interface: TerminalGraphics
        Displays an image from an input stream on the terminal with custom options.
        Specified by:
        displayImage in interface TerminalGraphics
        Parameters:
        terminal - the terminal to display the image on
        inputStream - the input stream containing the image data
        options - display options for the image
        Throws:
        java.io.IOException - if an I/O error occurs
      • convertImage

        public java.lang.String convertImage​(java.awt.image.BufferedImage image,
                                             TerminalGraphics.ImageOptions options)
                                      throws java.io.IOException
        Description copied from interface: TerminalGraphics
        Converts an image to the protocol-specific format. This method is useful for debugging or when you need the raw protocol data.
        Specified by:
        convertImage in interface TerminalGraphics
        Parameters:
        image - the image to convert
        options - display options for the image
        Returns:
        the protocol-specific representation of the image
        Throws:
        java.io.IOException - if an I/O error occurs
      • convertImageWithExtendedOptions

        public java.lang.String convertImageWithExtendedOptions​(java.awt.image.BufferedImage image,
                                                                TerminalGraphics.ImageOptions options,
                                                                java.lang.String size,
                                                                java.lang.String position)
                                                         throws java.io.IOException
        Converts an image with additional iTerm2-specific options.
        Parameters:
        image - the image to convert
        options - display options
        size - size specification (e.g., "50%", "100px")
        position - position specification for non-inline images
        Returns:
        the complete iTerm2 graphics protocol sequence
        Throws:
        java.io.IOException - if an I/O error occurs
        java.lang.IllegalArgumentException - if size or position holds a control character or a separator
      • displayImageWithPercentageSize

        public void displayImageWithPercentageSize​(Terminal terminal,
                                                   java.awt.image.BufferedImage image,
                                                   int widthPercent,
                                                   java.lang.Integer heightPercent)
                                            throws java.io.IOException
        Displays an image with percentage-based sizing.
        Parameters:
        terminal - the terminal
        image - the image to display
        widthPercent - width as percentage of terminal width
        heightPercent - height as percentage of terminal height (optional)
        Throws:
        java.io.IOException - if an I/O error occurs
      • displayBackgroundImage

        public void displayBackgroundImage​(Terminal terminal,
                                           java.awt.image.BufferedImage image,
                                           java.lang.String position)
                                    throws java.io.IOException
        Displays an image as a background (non-inline).
        Parameters:
        terminal - the terminal
        image - the image to display
        position - position specification (e.g., "center", "top-left")
        Throws:
        java.io.IOException - if an I/O error occurs
        java.lang.IllegalArgumentException - if the position holds a control character or an iTerm2 parameter separator