imgwrench 0.17.0
A highly opinionated image processor for the commandline.
License: MIT license
Keywords: imgwrench

============
Image Wrench
============


.. image:: https://img.shields.io/pypi/v/imgwrench.svg
        :target: https://pypi.python.org/pypi/imgwrench

.. image:: https://github.com/luphord/imgwrench/actions/workflows/build-test.yml/badge.svg
        :target: https://github.com/luphord/imgwrench/actions

.. image:: https://readthedocs.org/projects/imgwrench/badge/?version=latest
        :target: https://imgwrench.readthedocs.io/en/latest/?badge=latest
        :alt: Documentation Status




A highly opinionated image processor for the commandline. Multiple subcommands can
be executed sequentially to form a processing pipeline.

:code:`imgwrench` is free software available under the MIT license.
Detailed documentation can be found at https://imgwrench.readthedocs.io.


Features
--------

* Subcommands can be executed sequentially to form a pipeline
* Command *blackwhite* for converting images to black and white
* Command *collage* creates a collage from multiple images
* Command *colorfix* for fixing the colors of aged photographs
* Command *crop* for cropping images to give aspect ratio
* Command *dither* for converting images to black and white and dithering
* Command *filmstrip* to stack images horizontally forming a filmstrip
* Command *flip* to flip/mirror images left-right
* Command *frame* to put a monocolor frame around images
* Command *framecrop* top frame and crop an image to a target aspect ratio
* Command *quad* collects four images to a quad
* Command *resize* for resizing images
* Command *save* for no processing, but saving images with the given parameters
* Command *stack* for vertically stacking images


Installation
------------

Make sure you have Python and pip installed and available in your $PATH.
Then :code:`imgwrench` can be installed with

.. code-block:: console

        pip install imgwrench


In order to install for the current user only, you may want to execute

.. code-block:: console

        pip install --user imgwrench


instead. In this case you will have to ensure that the local bin directory
(typically :code:`~/.local/bin` on Linux systems) is contained in your $PATH.

Note that legacy Python2 is not supported. If your system still ships Python2
as the default Python interpreter, you may have to execute

.. code-block:: console

        pip3 install imgwrench


or

.. code-block:: console

        python3 -m pip install imgwrench


Usage
-----

:code:`imgwrench` is used on the command line by piping file paths into it, e.g.

.. code-block:: console

        ls /path/to/my/images/*.jpg | imgwrench blackwhite


Full command line help is

.. code-block:: console

        Usage: imgwrench [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

        A highly opinionated image processor for the commandline. Multiple
        subcommands can be executed sequentially to form a processing pipeline.

        Options:
        -i, --image-list FILENAME  File containing paths to images for processing,
                                defaults to stdin

        -r, --repeat INTEGER       repeat every image in input sequence  [default:
                                     1]

        -p, --prefix TEXT          prefix for all output filenames before numbering
                                [default: img_]

        -d, --digits INTEGER       number of digits for file numbering  [default: 4]
        -c, --increment INTEGER    increment for file numbering  [default: 1]
        -k, --keep-names           keep original file names instead of numbering
                                [default: False]

        -f, --force-overwrite      force overwriting output image file if it exists
                                [default: False]

        -o, --outdir DIRECTORY     output directory  [default: .]
        -q, --quality INTEGER      quality of the output images, integer 0 - 100
                                [default: 88]

        -e, --preserve-exif        preserve image exif and xmp metadata if available
                                [default: False]

        -j, --jpg / --png          save output images in JPEG format (otherwise PNG)
                                [default: True]

        --help                     Show this message and exit.

        Commands:
        blackwhite  Convert color images to black and white.
        collage     Create a collage from multiple images.
        colorfix    Fix colors by stretching channel histograms to full range.
        crop        Crop images to the given aspect ratio.
        dither      Apply black-white dithering to images.
        filmstrip   Stack all images horizontally, creating a filmstrip.
        flip        Flip/mirror images left-right.
        frame       Put a monocolor frame around images.
        framecrop   Crop and frame an image to a target aspect ratio.
        quad        Collects four images to a quad.
        resize      Resize images to a maximum side length preserving aspect...
        save        No-op to enable saving of images without any processing.
        stack       Stacks pairs of images vertically, empty space in the middle.


Pipelines
---------

:code:`imgwrench` subcommands can be combined into pipelines. This saves you from generating intermediate
files cluttering your filesystem or reducing the quality of the final results. For example, if you
want to convert all images in the current directory to black and white, put a white frame
around them and have them cut to an aspect ratio of 3:2 (for standard format printing), you would
execute the following command:

.. code-block:: console

        ls *.JPG | \
        imgwrench -o out -q 95 -p oldschool_img_ \
                blackwhite \
                framecrop -a 3:2 -w 0.03 -c white

Please refer to the `detailed subcommand documentation`_ for the individual parameters.

.. _`detailed subcommand documentation`: https://imgwrench.readthedocs.io/en/latest/usage.html

Developer Notes
---------------

Should you run into the following exception while running :code:`imgwrench` from an editable install

.. code-block:: console

        importlib_metadata.PackageNotFoundError: No package metadata was found for imgwrench

try executing :code:`make dist` to regenerate the :code:`egg` files required bei :code:`importlib`
which have likely been removed by a call to :code:`make clean`.

Credits
-------

This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.

.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage


=======
History
=======

0.17.0 (2022-11-12)
-------------------
* :code:`-r/--repeat` option for repeating input files
* Constrain :code:`click` version to :code:`<8.1` due to breaking API change; this will be relaxed in a future version
* Constrain :code:`Pillow` version to :code:`<9.0` due to breaking tests; this will be relaxed in a future version
* Drop support for Python 3.6 and 3.7
* Add support for Python 3.9 and 3.10
* Upgrade dependencies
* Migrate from travis-ci.com to GitHub actions

0.16.1 (2021-06-19)
-------------------
* Fix support for :code:`click>=8.0` which has changed its behaviour regarding custom parameter types

0.16.0 (2021-01-23)
-------------------
* :code:`quad` subcommand supports doubling inner frame using the :code:`-d/--double-inner-frame` flag

0.15.0 (2021-01-22)
-------------------
* :code:`collage` subcommand selects best layout based on score function
* :code:`collage` subcommand supports :code:`-n/--number-tries` parameter to specify number of layout tries

0.14.0 (2021-01-21)
-------------------
* BREAKING CHANGE: replace golden collage approach with BRIC algorithm in :code:`collage` subcommand
* BREAKING CHANGE: drop support for Python 3.5
* format code with :code:`black`

0.13.0 (2020-10-26)
-------------------
* :code:`quad` subcommand to to collect four images into a quad
* improve documentation


0.12.0 (2020-07-24)
-------------------

* :code:`flip` subcommand to flip/mirror images left-right
* Monkey patch :code:`IFDRational.__eq__` method of Pillow in tests to avoid regression with Pillow 7.2.0

0.11.1 (2020-04-05)
-------------------

* :code:`-x/--seed` option for collage to control initialization of random number generator

0.11.0 (2020-03-21)
-------------------

* collage subcommand for creating a framed collage from images
* BREAKING CHANGE: default method for colorfix is now quantiles-fixed-cutoff
* preserve xmp metadata when :code:`-e/--preserve-exif` is used (in addition to exif metadata)

0.10.0 (2020-03-04)
-------------------

* :code:`-m/--method` option to colorfix (default: quantiles)
* add fixed-cutoff as new method to colorfix accepting fixed colors as color cutoff boundaries
* add quantiles-fixed-cutoff as new method to colorfix combining quantiles and fixed-cutoff
* deprecate running colorfix without specifying method (as default will change in next version)

0.9.0 (2020-02-19)
------------------

* add numpy as dependency
* change colorfix algorithm to vectorized numpy code for performance
* support Python 3.8

0.8.1 (2020-01-12)
------------------

* fix crash when orientation is missing in exif headers

0.8.0 (2019-07-10)
------------------

* dither subcommand for dithering
* filmstrip subcommand to stack images horizontally
* images can be saved in PNG format using :code:`--png` CLI flag

0.7.1 (2019-05-16)
------------------

* fix development status

0.7.0 (2019-05-16)
------------------

* option for preserving exif image metadata
* fix error when running with :code:`-k/--keep-names`
* status progress to Alpha

0.6.0 (2019-03-14)
------------------

* framecrop subcommand to crop and frame an image to a target aspect ratio incl. tests and docs
* breaking change: moved command modules to `commands` package
* introduced ImageInfo as a container for additional meta information in the pipeline
* increased test coverage
* more documentation

0.5.2 (2019-03-10)
------------------

* use a custom parameter type for colors

0.5.1 (2019-03-09)
------------------

* changed default frame width to 0.025
* usage doc for frame subcommand
* consistent alphabetic sorting of subcommands
* use a custom parameter type for ratios

0.5.0 (2019-03-07)
------------------

* blackwhite subcommand to convert color images to black and white; incl. doc
* frame subcommand to put a monocolor frame around images; incl. tests

0.4.0 (2019-02-26)
------------------

* convert RGBA mode PNG images to RGB (to enable saving as JPG)
* crop subcommand to crop images to a specified aspect ratio
* documentation for colorfix and crop

0.3.0 (2019-02-17)
------------------

* :code:`-d/--digits` option to specify number of digits in file names
* :code:`-c/--increment` option to define increment for file numbering
* create non-existing output folder instead of complaining

0.2.0 (2019-01-30)
------------------

* no-op save command for only saving images
* raise exception if output image already exists
* :code:`-f/--force-overwrite` flag to enable overwriting output
* tests for cli, pipeline and resize

0.1.1 (2019-01-29)
------------------

* Fix __main__ module

0.1.0 (2019-01-29)
------------------

* First release on PyPI.