# AllMyToes
A simple program that provides thumbnails for images by using the
[freedesktop-specified](https://specifications.freedesktop.org/thumbnail-spec/thumbnail-spec-latest.html)
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](https://github.com/kamiyaa/joshuto) and [ranger](https://github.com/ranger/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](https://specifications.freedesktop.org/notification-spec/notification-spec-latest.html)
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](https://specifications.freedesktop.org/thumbnail-spec/thumbnail-spec-latest.html).
* 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](https://specifications.freedesktop.org/thumbnail-spec/thumbnail-spec-latest.html#SHARED).
* [ ] 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](https://gitlab.com/DLF/allmytoes/-/boards).


# Testing
AllMyToes is tested by a BDD test framework, [Python Behave](https://behave.readthedocs.io/en/stable/).
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](https://gitlab.xfce.org/xfce/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](https://crates.io/crates/allmytoes).

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 input_file = String::from("/path/to/source/image");
    let thumb_size = ThumbSize::Normal;
    match get_thumbnail(input_file, thumb_size) {
        Ok(path_to_thumb) => {
            println!(
                "The path to the thumb with size {} (maximum width/heigh: {}px) can be found here: {}",
                thumb_size.dir_name(),
                thumb_size.max_thumb_width(),
                path_to_thumb
            )
        }
        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/>.


