AllMyToes

A simple program that provides thumbnails for images by using the freedesktop-specified thumbnail data-base.

AllMyToes is in an early development state but it’s usable.

[[TOC]]

Usage

Call allmytoes with an image as parameter. The program will print the path to a thumbnail to stdout. ```

allmytoes some_image.jpg /home/me/.cache/thumbnails/normal/b7931d1d6e0439c1a6e2e6b02c5b21a6.png ```

If the thumbnail already exists, AllMyToes (“amt”) will just return the path to the existing thumbnail file. If not, AllMyToes will create the image’s thumbnails for the requested and all other supported sizes first.

Thumbnail Size

The latest freedesktop specification (0.9.0) defines four different thumbnail sizes: normal, large, x-large, and xx-large with maximum edge lengths of 128 px, 256 px, 512 px, and 1024 px respectively.

By default, AllMyToes returns the path to the large (256 px) thumbnail. The size to be returned can be chosen with the -s (--size) option by giving a value out of {n, l, x, xx}.

For example, to get a xx-large thumbnail, the call would look like this: ```

allmytoes -sxx some_image.jpg /home/me/.cache/thumbnails/xx-large/ad0779df58de36f038bdc4040a322bfe.png ```

Logging

By default, amt will print warnings and errors to stderr. A different log-level can be set via the environment variable RUST_LOG. For example, do a sh export RUST_LOG=trace to get all log entries, down to the most detailed “trace”-level.

How is this useful?

My personal motivation was the use of thumbnails for image previews in terminal-based file managers like joshuto and ranger.

But I guess AllMyToes can be useful for many situation where one wants to show a size-limited image in scripted environments, maybe as icons in desktop notifications or as desktop-overlays in terminal-based applications, where big images are unnecessary speed and memory eaters.

Installation

Via cargo from Source

cargo install allmytoes

Manually from Source

git clone https://gitlab.com/DLF/allmytoes.git cd allmytoes cargo build --release The built binary will be at target/release/allmytoes.

Specs

• Freedesktop Thumbnail Specification: AMT strives for compliance to the thumbnail freedesktop.org specification.
• AllMyToes will not create the cache directory ($XDG_CACHE_HOME or ~/.cache). In case the cache directory does not exist, AllMyToes will terminate with an error.
• AllMyToes will create the thumbnail directory beneath the cache directory and the size-specific sub-directories if they don't not exist.

Roadmap

Major milestones planned: * [ ] Comply to mandatory requirements from the freedesktop.org specification and have basic robustness (see %1). AMT will go to version 0.1.0 then. * [ ] Support for shared repositories. * [ ] Support for non-image file formats (videos, fonts, documents,...) by configuring other programs providing previews. (#13) * [ ] Support for other thumbnail repository locations depending on configured path patterns. (Not part of the freedesktop.org standard.)

See also my development board.

Testing

AllMyToes is tested by a BDD test framework, Python Behave. Most relevant test vectors need to consider the file system and the content of image files. So I thought it makes sense to test amt “from the outside”. As of now, there are no unit tests, but they may appear any time.

Running the BDD tests

Have a Python >= 3.10 environment with the required dependencies. E.g., use a virtualenv and then pip install -r test/requirements.txt.

Have a debug build of amt. target/debug/allmytoes will be the binary under test.

Then, to run the tests, cd into the test dir and run behave.

Missing Tests

• evaluation of XDG_CACHE_HOME
• MIME type probing for wrong and missing file extensions (if this fails on CI, check if the MIME-db is installed on the used docker img)
• --force-creation
• Return error when input file is not readable, no matter if valid thumb exists.
• Updating existing but outdated thumbs
• Error on non-existing, non-readable, not-decodable input-file

You may prefer to use this instead of AllMyToes

• Tumbler is a much more mature and feature-rich tool for the same purpose, but needs to run as a service and uses DBUS for communication.

  I did not use Tumbler as I wanted to have something more simple for my scripting.

AllMyToes as a Rust Library

AllMyToes can be used as a Rust library to obtain a thumbnail for a given image. You can find the crate on crates.io.

AllMyToes has a very small interface which just provides one function to get the thumbnail (get_thumbnail), one enumeration to specify the thumbnail size (ThumbSize), and one enumeration for the possible errors (ToeErrorType).

Example

```rust use allmytoes::{get_thumbnail, ThumbSize};

fn main() { let inputfile = String::from("/path/to/source/image"); let thumbsize = ThumbSize::Normal; match getthumbnail(inputfile, thumbsize) { Ok(pathtothumb) => { println!( "The path to the thumb with size {} (maximum width/heigh: {}px) can be found here: {}", thumbsize.dirname(), thumbsize.maxthumbwidth(), pathtothumb ) } Err(error) => println!( "Error '{:?}' occurred when trying to provide the thumb. ({})", error, error.msg(), ), } } ```

License: GPL 3

AllMyToes is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

AllMyToes is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with AllMyToes. If not, see https://www.gnu.org/licenses/.