Blend Modes
===========
This Python package implements blend modes for images.
Description
-----------
The Blend Modes package enables blending different images, or image
layers, by means of blend modes. These modes are commonly found in
graphics programs like `Adobe
Photoshop <http://www.adobe.com/Photoshop>`__ or
`GIMP <https://www.gimp.org/>`__.
Blending through blend modes allows to mix images in a variety of ways.
This package currently supports the following blend modes (name of the
respective functions in the package in ``italics``):
- Soft Light (``blend_modes.soft_light``)
- Lighten Only (``blend_modes.lighten_only``)
- Dodge (``blend_modes.dodge``)
- Addition (``blend_modes.addition``)
- Darken Only (``blend_modes.darken_only``)
- Multiply (``blend_modes.multiply``)
- Hard Light (``blend_modes.hard_light``)
- Difference (``blend_modes.difference``)
- Subtract (``blend_modes.subtract``)
- Grain Extract (known from GIMP, ``blend_modes.grain_extract``)
- Grain Merge (known from GIMP, ``blend_modes.grain_merge``)
- Divide (``blend_modes.divide``)
- Overlay (``blend_modes.overlay``)
- Normal (``blend_modes.normal``)
The intensity of blending can be controlled by means of an *opacity*
parameter that is passed into the functions. See `Usage <#usage>`__ for
more information.
The Blend Modes package is optimized for speed. It takes advantage of
vectorization through Numpy. Further speedup can be achieved when
implementing the package in Cython. However, Cython implementation is
not part of this package.
Usage
-----
The blend mode functions take image data expressed as arrays as an
input. These image data are usually obtained through functions from
image processing packages. Two popular image processing packages in
Python are `PIL <https://pypi.python.org/pypi/PIL>`__ or its fork
`Pillow <https://pypi.python.org/pypi/Pillow/>`__ and
`OpenCV <http://opencv.org/>`__. The examples in this chapter show how
to blend images using these packages.
Input and Output Formats
~~~~~~~~~~~~~~~~~~~~~~~~
A typical blend mode operation is called like this:
.. code:: python
blended_img = soft_light(bg_img, fg_img, opacity)
The blend mode functions expect
`Numpy <https://pypi.python.org/pypi/numpy>`__ float arrays in the
format [*pixels in dimension 1*,\ *pixels in dimension 2*,4] as an
input. Both images needs to have the same size, so the *pixels in
dimension 1* must be the same for ``bg_img`` and ``fg_img``. Same
applies to the *pixels in dimension 2*. Thus, a valid shape of the
arrays would be ``bg_img.shape == (640,320,4)`` and
``fg_img.shape == (640,320,4)``.
The order of the channels in the third dimension should be *R, G, B, A*,
where *A* is the alpha channel. All values should be *floats* in the
range *0.0 <= value <= 255.0*.
The blend mode functions return arrays in the same format as the input
format.
Examples
~~~~~~~~
The following examples show how to use the Blend Modes package in
typical applications.
The examples are structured in three parts:
1. Load background and foreground image. The foreground image is to be
blended onto the background image.
2. Use the Blend Modes package to blend the two images via the "soft
light" blend mode. The package supports multiple blend modes. See the
`Description <#description>`__ for a full list.
3. Display the blended image.
PIL/Pillow Example
^^^^^^^^^^^^^^^^^^
The following example shows how to use the Blend Modes package with the
`PIL <https://pypi.python.org/pypi/PIL>`__ or
`Pillow <https://pypi.python.org/pypi/Pillow/>`__ packages.
.. code:: python
from PIL import Image
import numpy
from blend_modes import soft_light
# Import background image
background_img_raw = Image.open('background.png') # RGBA image
background_img = numpy.array(background_img_raw) # Inputs to blend_modes need to be numpy arrays.
background_img_float = background_img.astype(float) # Inputs to blend_modes need to be floats.
# Import foreground image
foreground_img_raw = Image.open('foreground.png') # RGBA image
foreground_img = numpy.array(foreground_img_raw) # Inputs to blend_modes need to be numpy arrays.
foreground_img_float = foreground_img.astype(float) # Inputs to blend_modes need to be floats.
# Blend images
opacity = 0.7 # The opacity of the foreground that is blended onto the background is 70 %.
blended_img_float = soft_light(background_img_float, foreground_img_float, opacity)
# Convert blended image back into PIL image
blended_img = numpy.uint8(blended_img_float) # Image needs to be converted back to uint8 type for PIL handling.
blended_img_raw = Image.fromarray(blended_img) # Note that alpha channels are displayed in black by PIL by default.
# This behavior is difficult to change (although possible).
# If you have alpha channels in your images, then you should give
# OpenCV a try.
# Display blended image
blended_img_raw.show()
OpenCV Example
^^^^^^^^^^^^^^
The following example shows how to use the Blend Modes package with
`OpenCV <http://opencv.org/>`__.
.. code:: python
import cv2 # import OpenCV
import numpy
from blend_modes import soft_light
# Import background image
background_img_float = cv2.imread('background.png',-1).astype(float)
# Import foreground image
foreground_img_float = cv2.imread('foreground.png',-1).astype(float)
# Blend images
opacity = 0.7 # The opacity of the foreground that is blended onto the background is 70 %.
blended_img_float = soft_light(background_img_float, foreground_img_float, opacity)
# Display blended image
blended_img_uint8 = blended_img_float.astype(numpy.uint8) # Convert image to OpenCV native display format
cv2.imshow('window', blended_img_uint8)
cv2.waitKey() # Press a key to close window with the image.
Installation
------------
The Blend Modes package can be installed through pip:
``$ pip install blend_modes``
Dependencies
------------
The Blend Modes package needs
`Numpy <https://pypi.python.org/pypi/numpy>`__ to function correctly.
For loading images the following packages have been successfully used:
- `PIL <https://pypi.python.org/pypi/PIL>`__
- `Pillow <https://pypi.python.org/pypi/Pillow/>`__
- `OpenCV <http://opencv.org/>`__
See Also
--------
Blend modes are further described on
`Wikipedia <https://en.wikipedia.org/wiki/Blend_modes>`__. An actual
implementation can be found in the `GIMP source
code <https://git.gnome.org/browse/gimp/tree/app/operations/>`__, e.g.
in the file that describes the *division* operation,
`gimpoperationdividecode.c <https://git.gnome.org/browse/gimp/tree/app/operations/gimpoperationdividemode.c>`__.
Contribution
------------
I am happy about any contribution or feedback. Please let me know about
your comments via the Issues tab on
`GitHub <https://github.com/flrs/blend_modes/issues>`__.
License
-------
The Blend Modes package is distributed under the `MIT License
(MIT) <https://github.com/flrs/blend_modes/blob/master/LICENSE.txt>`__.
Please also take note of the licenses of the dependencies.
Raw data
{
"_id": null,
"home_page": "https://github.com/flrs/blend_modes",
"name": "blend-modes",
"maintainer": "",
"docs_url": "https://pythonhosted.org/blend-modes/",
"requires_python": "",
"maintainer_email": "",
"keywords": "image processing blend modes",
"author": "Florian Roscheck",
"author_email": "florian.ros.check+blendmodes@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b4/00/61401b0ef3a1e58e2ba305292fef3fc043be4eff0162138e67d9b9fc77de/blend_modes-2.1.0.tar.gz",
"platform": "",
"description": "Blend Modes\n===========\n\nThis Python package implements blend modes for images.\n\nDescription\n-----------\n\nThe Blend Modes package enables blending different images, or image\nlayers, by means of blend modes. These modes are commonly found in\ngraphics programs like `Adobe\nPhotoshop <http://www.adobe.com/Photoshop>`__ or\n`GIMP <https://www.gimp.org/>`__.\n\nBlending through blend modes allows to mix images in a variety of ways.\nThis package currently supports the following blend modes (name of the\nrespective functions in the package in ``italics``):\n\n- Soft Light (``blend_modes.soft_light``)\n- Lighten Only (``blend_modes.lighten_only``)\n- Dodge (``blend_modes.dodge``)\n- Addition (``blend_modes.addition``)\n- Darken Only (``blend_modes.darken_only``)\n- Multiply (``blend_modes.multiply``)\n- Hard Light (``blend_modes.hard_light``)\n- Difference (``blend_modes.difference``)\n- Subtract (``blend_modes.subtract``)\n- Grain Extract (known from GIMP, ``blend_modes.grain_extract``)\n- Grain Merge (known from GIMP, ``blend_modes.grain_merge``)\n- Divide (``blend_modes.divide``)\n- Overlay (``blend_modes.overlay``)\n- Normal (``blend_modes.normal``)\n\nThe intensity of blending can be controlled by means of an *opacity*\nparameter that is passed into the functions. See `Usage <#usage>`__ for\nmore information.\n\nThe Blend Modes package is optimized for speed. It takes advantage of\nvectorization through Numpy. Further speedup can be achieved when\nimplementing the package in Cython. However, Cython implementation is\nnot part of this package.\n\nUsage\n-----\n\nThe blend mode functions take image data expressed as arrays as an\ninput. These image data are usually obtained through functions from\nimage processing packages. Two popular image processing packages in\nPython are `PIL <https://pypi.python.org/pypi/PIL>`__ or its fork\n`Pillow <https://pypi.python.org/pypi/Pillow/>`__ and\n`OpenCV <http://opencv.org/>`__. The examples in this chapter show how\nto blend images using these packages.\n\nInput and Output Formats\n~~~~~~~~~~~~~~~~~~~~~~~~\n\nA typical blend mode operation is called like this:\n\n.. code:: python\n\n blended_img = soft_light(bg_img, fg_img, opacity)\n\nThe blend mode functions expect\n`Numpy <https://pypi.python.org/pypi/numpy>`__ float arrays in the\nformat [*pixels in dimension 1*,\\ *pixels in dimension 2*,4] as an\ninput. Both images needs to have the same size, so the *pixels in\ndimension 1* must be the same for ``bg_img`` and ``fg_img``. Same\napplies to the *pixels in dimension 2*. Thus, a valid shape of the\narrays would be ``bg_img.shape == (640,320,4)`` and\n``fg_img.shape == (640,320,4)``.\n\nThe order of the channels in the third dimension should be *R, G, B, A*,\nwhere *A* is the alpha channel. All values should be *floats* in the\nrange *0.0 <= value <= 255.0*.\n\nThe blend mode functions return arrays in the same format as the input\nformat.\n\nExamples\n~~~~~~~~\n\nThe following examples show how to use the Blend Modes package in\ntypical applications.\n\nThe examples are structured in three parts:\n\n1. Load background and foreground image. The foreground image is to be\n blended onto the background image.\n\n2. Use the Blend Modes package to blend the two images via the \"soft\n light\" blend mode. The package supports multiple blend modes. See the\n `Description <#description>`__ for a full list.\n\n3. Display the blended image.\n\nPIL/Pillow Example\n^^^^^^^^^^^^^^^^^^\n\nThe following example shows how to use the Blend Modes package with the\n`PIL <https://pypi.python.org/pypi/PIL>`__ or\n`Pillow <https://pypi.python.org/pypi/Pillow/>`__ packages.\n\n.. code:: python\n\n from PIL import Image\n import numpy\n from blend_modes import soft_light\n\n # Import background image\n background_img_raw = Image.open('background.png') # RGBA image\n background_img = numpy.array(background_img_raw) # Inputs to blend_modes need to be numpy arrays.\n background_img_float = background_img.astype(float) # Inputs to blend_modes need to be floats.\n\n # Import foreground image\n foreground_img_raw = Image.open('foreground.png') # RGBA image\n foreground_img = numpy.array(foreground_img_raw) # Inputs to blend_modes need to be numpy arrays.\n foreground_img_float = foreground_img.astype(float) # Inputs to blend_modes need to be floats.\n\n # Blend images\n opacity = 0.7 # The opacity of the foreground that is blended onto the background is 70 %.\n blended_img_float = soft_light(background_img_float, foreground_img_float, opacity)\n\n # Convert blended image back into PIL image\n blended_img = numpy.uint8(blended_img_float) # Image needs to be converted back to uint8 type for PIL handling.\n blended_img_raw = Image.fromarray(blended_img) # Note that alpha channels are displayed in black by PIL by default.\n # This behavior is difficult to change (although possible).\n # If you have alpha channels in your images, then you should give\n # OpenCV a try.\n\n # Display blended image\n blended_img_raw.show()\n\nOpenCV Example\n^^^^^^^^^^^^^^\n\nThe following example shows how to use the Blend Modes package with\n`OpenCV <http://opencv.org/>`__.\n\n.. code:: python\n\n import cv2 # import OpenCV\n import numpy\n from blend_modes import soft_light\n\n # Import background image\n background_img_float = cv2.imread('background.png',-1).astype(float)\n\n # Import foreground image\n foreground_img_float = cv2.imread('foreground.png',-1).astype(float)\n\n # Blend images\n opacity = 0.7 # The opacity of the foreground that is blended onto the background is 70 %.\n blended_img_float = soft_light(background_img_float, foreground_img_float, opacity)\n\n # Display blended image\n blended_img_uint8 = blended_img_float.astype(numpy.uint8) # Convert image to OpenCV native display format\n cv2.imshow('window', blended_img_uint8)\n cv2.waitKey() # Press a key to close window with the image.\n\nInstallation\n------------\n\nThe Blend Modes package can be installed through pip:\n``$ pip install blend_modes``\n\nDependencies\n------------\n\nThe Blend Modes package needs\n`Numpy <https://pypi.python.org/pypi/numpy>`__ to function correctly.\nFor loading images the following packages have been successfully used:\n\n- `PIL <https://pypi.python.org/pypi/PIL>`__\n- `Pillow <https://pypi.python.org/pypi/Pillow/>`__\n- `OpenCV <http://opencv.org/>`__\n\nSee Also\n--------\n\nBlend modes are further described on\n`Wikipedia <https://en.wikipedia.org/wiki/Blend_modes>`__. An actual\nimplementation can be found in the `GIMP source\ncode <https://git.gnome.org/browse/gimp/tree/app/operations/>`__, e.g.\nin the file that describes the *division* operation,\n`gimpoperationdividecode.c <https://git.gnome.org/browse/gimp/tree/app/operations/gimpoperationdividemode.c>`__.\n\nContribution\n------------\n\nI am happy about any contribution or feedback. Please let me know about\nyour comments via the Issues tab on\n`GitHub <https://github.com/flrs/blend_modes/issues>`__.\n\nLicense\n-------\n\nThe Blend Modes package is distributed under the `MIT License\n(MIT) <https://github.com/flrs/blend_modes/blob/master/LICENSE.txt>`__.\nPlease also take note of the licenses of the dependencies.",
"bugtrack_url": null,
"license": "MIT",
"summary": "Image processing blend modes",
"version": "2.1.0",
"project_urls": {
"Homepage": "https://github.com/flrs/blend_modes"
},
"split_keywords": [
"image",
"processing",
"blend",
"modes"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b40061401b0ef3a1e58e2ba305292fef3fc043be4eff0162138e67d9b9fc77de",
"md5": "ce9f1011818f87247b6b1c0e728542c2",
"sha256": "0a3145e4792e005764b9663f5ce899d30f7c24f4bcff00428907d03dbe068f37"
},
"downloads": -1,
"filename": "blend_modes-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "ce9f1011818f87247b6b1c0e728542c2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 17733,
"upload_time": "2019-07-17T05:52:44",
"upload_time_iso_8601": "2019-07-17T05:52:44.828725Z",
"url": "https://files.pythonhosted.org/packages/b4/00/61401b0ef3a1e58e2ba305292fef3fc043be4eff0162138e67d9b9fc77de/blend_modes-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2019-07-17 05:52:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "flrs",
"github_project": "blend_modes",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "blend-modes"
}
JSON
