evince-thumbnailer

evince-thumbnailer [OPTIONS] <input-file> <output-file>

--size=<SIZE>
    Specifies the maximum dimension (width or height) of the generated thumbnail in pixels. Common sizes include 128 or 256. The default is typically 128 pixels.

--page=<PAGE>
    Indicates the page number of the document to be thumbnailed. By default, it generates a thumbnail for the first page (page 1).

--output-format=<FORMAT>
    Sets the output image format for the thumbnail. Supported formats often include jpeg (default) and png.

--raw-output
    Writes the raw thumbnail image data to standard output (stdout) instead of a specified file. This is useful when piping the output to another command or script.

--help
    Displays a help message with usage information and available options.

--version
    Shows the version information of the evince-thumbnailer utility.

evince-thumbnailer is a utility bundled with the Evince document viewer, designed to create small preview images (thumbnails) for various document formats. It supports common types such as PDF, PostScript (PS), DjVu, XPS, DVI, and others that Evince can render.

Its primary role is to integrate with desktop environments and file managers like GNOME's Nautilus or KDE's Dolphin. Instead of opening the full document viewer, these file managers invoke evince-thumbnailer to quickly generate a visual representation of the document's first page. This allows users to browse through document collections more efficiently, providing a visual cue for file content without the overhead of launching a full application.

The command is typically not invoked directly by end-users but rather by background services or scripts adhering to the FreeDesktop.org thumbnailing specification. It takes an input document file path and an output path for the thumbnail image, usually generating a JPEG file, and can specify size and page number.

Resource Usage: Generating thumbnails for very large or complex documents can be CPU and memory intensive, potentially slowing down system responsiveness temporarily.
Security: While Evince is generally robust, thumbnailing untrusted or maliciously crafted documents could theoretically expose vulnerabilities in the underlying rendering libraries.
Permissions: The utility requires read access to the input document and write access to the output directory where the thumbnail is to be saved.
Unsupported Formats: It can only thumbnail formats that Evince itself supports. If a document type isn't viewable by Evince, it cannot be thumbnailed.

evince-thumbnailer primarily functions as a backend for desktop environments. It adheres to the FreeDesktop.org Shared Thumbs specification, which defines a standardized way for applications to generate and store thumbnails. File managers detect the document type and, if a thumbnail doesn't exist in the cache, invoke the appropriate thumbnailer (like evince-thumbnailer for documents) to create one. These thumbnails are typically stored in a user's cache directory, usually ~/.cache/thumbnails/, to prevent redundant generation and speed up subsequent browsing.

To optimize performance and avoid re-generating thumbnails every time a directory is opened, desktop environments maintain a thumbnail cache.
When evince-thumbnailer creates a thumbnail, it's saved to this cache. Before requesting a new thumbnail, the file manager checks the cache; if a valid, up-to-date thumbnail exists, it's displayed directly, significantly improving file browsing responsiveness. The cache also includes a URI and timestamp to ensure the thumbnail is valid for the current file.

evince-thumbnailer is an integral part of the Evince document viewer project, which was developed for the GNOME desktop environment. Evince itself was designed to be a universal document viewer, replacing multiple single-format viewers like GGV (for PostScript) and Xpdf (for PDF) in early 2000s GNOME releases. As desktop environments evolved to offer richer visual browsing experiences, the need for efficient and integrated thumbnail generation became paramount.

The thumbnailer component emerged to fulfill this requirement, allowing file managers to display visual previews of documents without having to launch the full application. Its development closely tracks that of Evince itself, benefiting from Evince's robust rendering capabilities and ensuring compatibility with the diverse document formats it supports. It has been a stable and crucial part of the GNOME desktop's file management system for over a decade.

evince(1), nautilus(1), xdg-desktop-menu(1), gs(1), convert(1) (ImageMagick)