imgfilter 1.1.1
A simple terminal utility to help you filter image files by resolution or ratio.
License: MIT

## About
*imgfilter* is a simple terminal utility to help you filter image files by resolution or ratio.

## Motivation
This program was developed after I've realized that I had too many wallpapers, and too little time. Although there are more advanced and well written programs with a wider range of features (e.g.: [variety](https://peterlevi.com/variety/), [hydrus](https://hydrusnetwork.github.io/hydrus/)) most of the times I just want to filter my wallpapers by resolution or ratio, without leaving my terminal.

As so this tool was born, a minimal solution, which is meant to be used in a terminal ecosystem with other common utilities found in Linux based OSs, to assist the user in filtering image files either by resolution or ratio.


## Installation
### Dependencies
This program requires:
- [Python](https://www.python.org/) (version >= 3.0)
- [Pillow](https://pillow.readthedocs.io/en/stable/)

### Stable version
Using `pip` to install this program directly on your system:
```console
$ pip install imgfilter
```

### Development version
Clone this repository locally:
```console
$ git clone https://github.com/jpmvferreira/imgfilter
```

Install in editable mode (`-e` or `--editable`) using `pip`:
```console
$ pip install -e imgfilter
```


## Example usage
This section shows a few examples on how I have been using this program so far.


To tell if `wallpaper1.jpg` in your current working directory is 1920x1080, then using the `-s` or `--size` flag:
```console
$ imgfilter wallpaper1.jpg -s 1920x1080
```

If the file is 1920x1080 then it will print its name, otherwise, it will print nothing.

If instead you want to know if `wallpaper1.jpg` is 16:9, you can use the same flag with with a ':' instead of the 'x':
```console
$ imgfilter wallpaper1.jpg -s 16:9
```

This can also be used for several files, with different formats:
```console
$ imgfilter wallpaper1.jpg wallpaper2.png -s 1920x1080
```

Naturally you can make use of bash's features, for example the wildcard statement, to filter a set of files which match a given pattern, in this case all of the .jpg files in the current working directory:
```console
$ imgfilter *.jpg -s 1920x1080
```

This program also reads from STDIN, which means that you can create pipelines with it.

For example, if you wish to tell if all your wallpapers, located at `~/wallpapers` and respective subfolders, are 1920x1080, then create the following pipeline with `find`:
```bash
$ find ~/wallpapers | imgfilter -s 1920x1080
```

If you wish to filter out all the wallpapers that are not 1920x1080, then you can rely on the `-o` or `--opposite` flag, which prints the file name if it doesn't match the provided size:
```bash
$ find ~/wallpapers | imgfilter -s 1920x1080 -o
```

You can keep on adding to this pipeline to apply further actions.

Let's say you're trying to move all of your 1920x1080 wallpapers from `~/wallpapers/unsorted` to `~/wallpapers/fullhd`. By using the pipeline created above, and using [xargs](https://man7.org/linux/man-pages/man1/xargs.1.html) to which converts content found in STDIN to command line arguments, we can move all of those files to their designated location:
```bash
$ find ~/wallpapers/unsorted | imgfilter -s 1920x1080 | xargs -I '{}' mv {} ~/wallpapers/fullhd
```

If you want to be sure that the program isn't doing anything funny, which you should, use `-v` or `--verbose` to print the image resolution or ratio to STDERR, which shouldn't affect the pipeline.

For a brief description of the program use the `-h` or `--help` flag.


## Contributing
If you happen to find a bug, have an idea on how to extend this programs, suggest optimizations both in perfomance or readability, share some fancy terminal wizardry or even have any question whatsoever, feel free to open up an issue.

## Release cycle
This is a (very) small project, however, I do like to keep things tidy. As such I made a release cycle which goes as follows.

The first version will be 1.0.0, and all versions following it will have the format X.Y.Z, which is released once I consider that the program is good enough.

Each time that there is an update which does not modify the program behavior (e.g.: documentation, packaging) it will increment Z (e.g.: 1.0.0 -> 1.0.1).

Each time that there is an update which modifies the program behavior (e.g.: adding features, fixing bugs) it will increment Y and reset Z (e.g.: 1.0.1 -> 1.1.0).

Each time that there is an update which is not backwards compatible (e.g.: removing features, fundamental change on how the program is used) it will increment X and reset both Y and Z (e.g.: 1.1.2 -> 2.0.0).

In this Github repository you will find branches for the stable version (master) and the development version (dev). All modifications are done in the development branch and, after being tested, are included in the stable version, with the appropriate version bump.

## License
MIT

For more information refer to the [license.md](./license.md) file available in this repository