Package: minchin.pelican.plugins.image-process
Deprecation Notice: This plugins is now being maintained as part of thePelican-Pluginsorganization on GitHub.
The new code repo is atGitHub.com/pelican-plugins/image-process. The new PyPI package is
atpelican-image-process(for yourrequirements.txt) and the new plugin
name ispelican.plugins.image_process(to updatePLUGINSin yourpelicanconf.py).Old ReadmeImage Processis a plugin forPelican,
a static site generator written in Python.Image Processlet you automate the processing of images based on their
class attribute. Use this plugin to minimize the overall page weight
and to save you a trip to Gimp or Photoshop each time you include an
image in your post.Image Processalso makes it easy to create responsive images using
the new HTML5srcsetattribute and<picture>tag. It does this
by generating multiple derivative images from one or more sources.Image Processwill not overwrite your original images.InstallationThe easiest way to installImage Processis through the use of pip. This
will also install the required dependencies automatically.pipinstallminchin.pelican.plugins.image_processThen, in yourpelicanconf.pyfile, addImage Processto your list of
plugins:PLUGINS=[# ...'minchin.pelican.plugins.image_process',# ...]You will also need to configure your desired transformations (seeUsagebelow) and add the appropriate class to images you want processed.RequirementsImage Processrequires Beautiful Soup, Pillow, Six, and Pelican. All
these can be manually installed with pip:pipinstallpillowbeautifulsoup4sixpelicanIf you encounter errors while processing JPEG files, you may need to install
the JPEG development library:pipuninstallpillowapt-getinstalllibjpeg-devpipinstallpillowUsageImage Processscans your content for<img>tags with special
classes. It then maps the classes to a set of image processing
instructions, computes new images and modifies HTML code according to
the instructions.Define TransformationsThe first step in using this module is to define some image
transformations in your Pelican configuration file. Transformations
are defined in theIMAGE_PROCESSdictionary, mapping a
transformation name to a list of operations. There are three kinds of
transformations: image replacement, responsive image and picture set.Image ReplacementThe simplest image processing will replace the original image by a
new, transformed image computed from the original. You may use this,
for example, to ensure that all images are of the same size, or to
compute a thumbnail from a larger image:IMAGE_PROCESS={'article-image':["scale_in 300 300 True"],'thumb':["crop 0 0 50% 50%","scale_out 150 150 True","crop 0 0 150 150"],}These transformations tellImage Processto transform the image
referred by thesrcattribute of an<img>according to the
list of operations specified and replace thesrcattribute by the
URL of the transformed image.For consistency with the other type of transformations described
below, there is an alternative syntax for the processing instructions:IMAGE_PROCESS={'thumb':{'type':'image','ops':["crop 0 0 50% 50%","scale_out 150 150 True","crop 0 0 150 150"],},'article-image':{'type':'image','ops':["scale_in 300 300 True"],}}To apply image replacement to the images in your articles, you must
add them the special classimage-process-followed by the name of
the transformation you wish to apply. For example, let’s pretend you
have defined the transformation described above. If you write your
content in HTML or in Markdown, do something like this:<imgclass="image-process-article-image"src="/images/pelican.jpg"/>In reStructuredText, use the:class:attribute of theimageor
thefiguredirective:..image::/images/pelican.png:class:image-process-article-image..figure::/images/pelican.png:class:image-process-article-imageNoteThe reStructuredText reader will convert underscores (_) to
dashes (-) in class names. To make sure everything runs
smoothly, do not use underscores in your transformation names.Responsive ImageYou can useImage Processto automatically generate a set of
images that will be selected for display by browsers according to the
viewport width or according to the device resolution. To accomplish
this,Image Processwill add asrcsetattribute (and maybe amediaand asizesattribute) to the<img>.Note that thesrcsetsyntax is currently not supported by all
browsers. However, browsers who do not support thesrcsetattribute will fall back to a default image specified by the
still-presentsrcattribute. SeeCan I Usefor the current
status onsrcsetsupport.HTML5 supports two types of responsive image set. The first one is
device-pixel-ratio-based, selecting higher resolution images for higher
resolution devices; the second one is viewport-based, selecting
images according to the viewport width. If you want to know more about
HTML5 responsive images, I recommendthis articlefor a gentle
introduction to thesrcsetand<picture>syntaxes.To tellImage Processto generate a responsive image, add aresponsive-imagetransformation to your yourIMAGE_PROCESSdictionary, with the following syntax:IMAGE_PROCESS={'crisp':{'type':'responsive-image','srcset':[('1x',["scale_in 800 600 True"]),('2x',["scale_in 1600 1200 True"]),('4x',["scale_in 3200 2400 True"]),],'default':'1x',},'large-photo':{'type':'responsive-image','sizes':'(min-width: 1200px) 800px, (min-width: 992px) 650px,\(min-width: 768px) 718px, 100vw','srcset':[('600w',["scale_in 600 450 True"]),('800w',["scale_in 800 600 True"]),('1600w',["scale_in 1600 1200 True"]),],'default':'800w',},}Thecrisptransformation is an example of a transformation
enabling device-pixel-ratio-based selection. Thesrcsetis a list
of tuple, each tuple containing the image description ('1x','2x', etc.) and the list of operations to generate the derivative
image from the original image (the original image is the value of thesrcattribute of the<img>). Image descriptions are hints
about the resolution of the associated image and must have the suffixx. Thedefaultnames the image to use to replace thesrcattribute of the image.  This is the image that will be displayed by
browsers that do not support thesrcsetsyntax.Thelarge-phototransformation is an example of a transformation
enabling viewport-based selection. Thesizescontains a rule to
compute the width of the displayed image from the width of the
viewport. Once the browser knows the image width, it will select an
image source from thesrcset. Thesrcsetis a list of tuple,
each tuple containing the image description ('600w','800w',
etc.) and the list of operations to generate the derivative image from
the original image (the original image is the value of thesrcattribute of the<img>). Image descriptions are hints about the
width in pixels of the associated image and must have the suffixw. Thedefaultnames the image to use to replace thesrcattribute of the image.  This is the image that will be displayed by
browsers that do not support thesrcsetsyntax.In the two examples above, thedefaultis a string referring to
one of the images in thesrcset. However, thedefaultvalue
could also be a list of operations to generate a different derivative
image.To make the images in your article responsive, you must add them the
special classimage-process-followed by the name of the
transformation you wish to apply, exactly like you would do for the
image replacement case, described above. So, if you write your content
in HTML or in Markdown, do something like this:<imgclass="image-process-large-photo"src="/images/pelican.jpg"/>In reStructuredText, use the:class:attribute of theimageof
thefiguredirective:..image::/images/pelican.png:class:image-process-large-photo..figure::/images/pelican.png:class:image-process-large-photoPicture SetImage Processcan be use to generate the images used by a<picture>tag. The<picture>syntax allows for more
flexibility in providing a choice of image to the browser. Again, if
you want to know more about HTML5 responsive images, seethis
articlefor a gentle introduction to thesrcsetand<picture>syntaxes.To tellImage Processto generate the images for a<picture>,
add apictureentry to yourIMAGE_PROCESSdictionary with the
following syntax:IMAGE_PROCESS={'example-pict':{'type':'picture','sources':[{'name':'default','media':'(min-width: 640px)','srcset':[('640w',["scale_in 640 480 True"]),('1024w',["scale_in 1024 683 True"]),('1600w',["scale_in 1600 1200 True"]),],'sizes':'100vw',},{'name':'source-1','srcset':[('1x',["crop 100 100 200 200"]),('2x',["crop 100 100 300 300"]),]}],'default':('default','640w'),},}Each of thesourcesentry is very similar to theresponsive imagedescribe above. Here, each source must have aname, which
will be used to find the URL of the original image for this source in
your article. The source may also have amedia, which contains a
rule used by the browser to select the active source. Thedefaultnames the image to use to replace thesrcattribute of the<img>inside the<picture>.  This is the image that will be
displayed by browsers that do not support the<picture>syntax. In
this example, it will use the image640wfrom the sourcedefault. A list of operations could have been specified instead of640w.To generate a responsive<picture>for the images in your
articles, you must add to your article a pseudo<picture>tag that
looks like this:<picture><sourceclass="source-1"src="/images/pelican-closeup.jpg"></source><imgclass="image-process-example-pict"src="/images/pelican.jpg"/></picture>Each<source>tag maps a source name (theclassattribute) to
a file (thesrcattribute). The<img>must have the special
classimage-process-followed by the name of the transformation
you wish to apply. The file referenced by thesrcattribute of the<img>>will be used as the specialdefaultsource in your
transformation definition.The pseudo<picture>tag above can be used in articles written in
HTML, Markdown or restructuredText. In reStructuredText, however, you
can also use thefiguredirective to generate a<picture>. The
figure image file will be used as the specialdefaultsource;
other sources must be added in the the legend section of thefigureasimagedirectives. The figure class must beimage-process-followed by the name of the transformation you wish
to apply, while the other images must have two classes:image-processand the name of the source they provide an image
for:..figure::/images/pelican.png:class:image-process-large-photoTest picture..image::/images/pelican-closeup.jpg:class:image-process source-1The images in the legend section that are used as source for the<picture>will be removed from the image legend, so that they do
not appear in your final article.TransformationsAvailable operations for transformations are:crop <top> <left> <right> <bottom>Crop the image to the box (left,top)-(right,bottom). Values
can be absolute (a number) or relative to the size of the image (a
number followed by a percent sign%).flip_horizontalFlip the image horizontally.flip_verticalFlip the image vertically.grayscaleConvert the image to grayscale.resizewidthheightResize the image. This operation doesnotpreserve the image aspect
ratio. Values can be absolute (a number) or relative to the
size of the image (a number followed by a percent sign%).rotate <degrees>Rotate the image.scale_in <width> <height> <upscale>Resize the image. This operation preserves the image aspect ratio
and the resulting image will be no larger thanwidthxheight. Values can be absolute (a number) or relative to the
size of the image (a number followed by a percent sign%).
Ifupscaleis False, smaller images will not be enlarged.scale_out <width> <height> <upscale>Resize the image. This operation preserves the image aspect ratio
and the resulting image will be no smaller thanwidthxheight. Values can be absolute (a number) or relative to the
size of the image (a number followed by a percent sign%).
Ifupscaleis False, smaller images will not be enlarged.blurApply thepillow.ImageFilter.BLURfilter to the image.contourApply thepillow.ImageFilter.CONTOURfilter to the image.detailApply thepillow.ImageFilter.DETAILfilter to the image.edge_enhanceApply thepillow.ImageFilter.EDGE_ENHANCEfilter to the image.edge_enhance_moreApply thepillow.ImageFilter.EDGE_ENHANCE_MOREfilter to the image.embossApply thepillow.ImageFilter.EMBOSSfilter to the image.find_edgesApply thepillow.ImageFilter.FIND_EDGESfilter to the image.smoothApply thepillow.ImageFilter.SMOOTH filterto the image.smooth_moreApply thepillow.ImageFilter.SMOOTH_MOREfilter to the image.sharpenApply thepillow.ImageFilter.SHARPENfilter to the image.You can also define your own operations; the only requirement is that
your operation should be a callable object expecting apillow.Imageas
its first parameter and it should return the transformed image:defcrop_face(image):"""Detect face in image and crop around it."""# TODO: Fancy algorithm.returnimageIMAGE_PROCESS={'face-thumbnail':[crop_face,"scale_out 150 150 True"]}Additional SettingsDestination DirectoryBy default, the new images will be stored in a directory namedderivative/<TRANSFORMATION_NAME>in the output folder at
the same location as the original image.
For example if the original image is located in
thecontent/imagesfolder. The computed images will be stored
in theoutput/images/derivative/<TRANSFORMATION_NAME>.
All the transformations are done in the output directory in order
to avoid confusion with the source files or if we test multiple
transformations.
You can replacederivativeby something else using theIMAGE_PROCESS_DIRsetting in your Pelican configuration file:IMAGE_PROCESS_DIR='derivees'Force Image ProcessingIf the transformed image already exists and is newer than the original
image, the plugin assumes that it should not recompute it again. You
can force the plugin to recompute all images by settingIMAGE_PROCESS_FORCEtoTruein your Pelican configuration
file.IMAGE_PROCESS_FORCE=TrueSelecting a HTML ParserYou may select the HTML parser which is used. The default is the builtinhtml.parserbut you may also selecthtml5liborlxmlby settingIMAGE_PROCESS_PARSERin your pelican configuration file , e.g.:IMAGE_PROCESS_PARSER="html5lib"For details, refer to theBeautifulSoup documentation on parsers.File EncodingYou may select a different file encoding to be used by BeautifulSoup as it
opens your files. The default isuft-8.IMAGE_PROCESS_ENCODING="uft-8"Known IssuesPillow, when resizing animated GIF files, does not return an animated filethesetup.pyfile for this project does not run on Python 2.7. However,
wheels of this project are “universal” and so can be generated by Python 3
and subsequently installed by Python 2.7.test mostly pass, but not entirely. The tests also fail on Windows due to
path separator issues. The test suite remains a work in progress.version 1.1.2, as uploaded to PyPI, is broken; use a different version. (seeissue #2for details)CreditsPelican image in test data by Jon Sullivan. Source:http://www.pdphoto.org/PictureDetail.php?mat=&pg=5726Original Plugin developed by the team atWhisky Echo Bravo.