Image viewer

Sub-sections:

The package comes with a standalone in-terminal image viewer based on the library.

The image viewer is started from the command line using either the term-img command (only works if the Python scripts directory is on PATH) or python -m term_img.
Take note of the “-” (hyphen) versus “_” (underscore).
../_images/tui.png

Image sources

The viewer accepts the following kinds of sources:

  • An image file on a local filesystem.

  • A directory on a local filesystem.

  • An Image URL.

Any other thing given as a source is simply reported as invalid.

Modes

The viewer can be used in two modes:

  1. CLI mode

    In this mode, images are directly printed to standard output.
    This mode is used whenever there is only a single image source or when the --cli option is specified.

  2. TUI mode

    In this mode, a Terminal/Text-based User Interface is launched, within which images and directories can be browsed and viewed in different ways.
    This mode is used whenever there are multiple image sources or at least one directory source, or when the --tui option is specified.

Usage

Run term-img with the --help option to see the usage info and help text.
All arguments and options are described there.

Note that some options are only applicable to a specific mode. If used with the other mode, they’re simply ignored.

Some options have a [N] (where N is a number) behind their description, it indicates that the option has a footnote attached.
All footnotes are at the bottom of the help text.

Notifications

Notifications are event reports meant to be brought to the immediate knowledge of the user.
Notifications have two possible destinations:

  • Standard output/error stream: This is used while the TUI is not launched.

  • TUI notification bar: This is used while the TUI is launched.

Notifications sent to the TUI’s notification bar automatically disappear after 5 seconds.

Logging

Logs are more detailed event reports meant for troubleshooting and debugging purporses.

Logs are written to a file on a local filesystem. The default log file is ~/.term_img/term_img.log but a different file can be specified:

  • for all sessions, using the log file config option

  • per session, using the --log command-line option

A log entry has the following format:

(<pid>) (<date> <time>) <process>: <thread>: [<level>] <module>: <function>: <message>

  • pid: The process ID of the term-img session.

  • date and time: Current system date and time in the format %d-%m-%Y %H:%M:%S.

  • process and thread: The names of the python process and thread that produced the log record.

    • Only present when the logging level is set to DEBUG (either by --debug or --log-level=DEBUG).

  • level: The level of the log entry, this indicates it’s importance.

  • module: The package sub-module from which it originated.

  • function: The function from which it originated.

    • Only present when running on Python 3.8+ and logging level is set to DEBUG (either by --debug or --log-level=DEBUG).

  • message: The actual report describing the event that occured.

Note

  • Certain logs and some extra info are only provided when logging level is set to DEBUG.

  • Log files are appended to, so it’s safe use the same file for multiple sessions.

  • Log files are rotated upon reaching a size of 1MiB.

    • Only the current and immediate previous log file are kept.

  • The Process ID of the term-img instance preceeds every log entry, so this can be used to distinguish and track logs from different sessions running simultaneously while using the same log file.

Known Issues

  1. The TUI is not supported on Windows

  2. Drawing of images and animations doesn’t work completely well with cmd and powershell (tested in Windows Terminal). See Known Issues for details.

    • In the viewer’s CLI mode, use the --h-allow option to specify a horizontal allowance.

Planned Features

  • Performance improvements

  • STDIN source

  • Open in external viewer

  • Pattern-based file and directory exclusion

  • Minimum and maximum file size

  • Optionally skipping symlinks

  • Distinguished color for symlinked entries in the list view

  • Full grid view

  • Grid cells for directory entries

  • Interactive CLI mode

  • Slideshow

  • Zoom/Pan

  • Sorting options

  • Find in iist view

  • Filter in list and grid views

  • Alpha backaground adjustment per image

  • Frame duration adjustment per animated image

  • Copy:

    • Image data

    • File/Directory name

    • Full path

    • Parent directory path

  • Theme customization

  • Config menu

  • Overlay support for Image widgets

  • etc…