图像处理：Pelican插件

图像处理是Pelican的插件，Pelican是一个用Python编写的静态站点生成器。

图像处理允许您根据图像的类属性自动处理图像。使用此插件可以最小化页面总重量，并在每次在帖子中包含图像时节省您前往Gimp或Photoshop的时间。

图像处理还使得使用HTML5的srcset属性和<picture>标签创建响应式图像变得简单。它是通过从一个或多个源生成多个衍生图像来实现的。

图像处理不会覆盖您的原始图像。

安装

安装图像处理最简单的方法是通过Pip。这还将自动安装所需的依赖项。

python -m pip install pelican-image-process

然后，您需要配置所需的转换（见下文用法）并为要处理的图像添加适当的类。

用法

图像处理会扫描您的内容，寻找带有特殊类的<img>标签。然后，它将类映射到一组图像处理指令，计算新图像，并根据指令修改HTML代码。

定义转换

使用此模块的第一步是在您的Pelican配置文件中定义一些图像转换。转换定义在IMAGE_PROCESS字典中，将转换名称映射到一系列操作。有三种类型的转换：图像替换、响应式图像和图片集。

图像替换

最简单的图像处理将用从原始图像计算出的新转换图像替换原始图像。您可以使用此功能，例如，确保所有图像具有相同的大小，或者从大图像计算缩略图。

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"],
}

这些转换告诉图像处理根据指定的操作列表转换由<img>的src属性引用的图像，并用转换图像的URL替换src属性。

为了与其他类型的转换保持一致，处理指令有另一种语法

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"],
    },
}

要将图像替换应用于文章中的图像，您必须向它们添加特殊类image-process-<transform>，其中<transform>是要应用的转换的ID。

假设您已定义上述转换。要处理您的图像，它需要具有正确的CSS类

<img class="image-process-article-image" src="/images/pelican.jpg"/>

这可以用Markdown生成

![](/images/pelican.png){: .image-process-article-image}

在reStructuredText中，使用image或figure指令的:class:属性

.. image:: /images/pelican.png
   :class: image-process-article-image

.. figure:: /images/pelican.png
    :class: image-process-article-image

⚠️ 警告：

reStructuredText阅读器将将下划线（_）转换为破折号（-）在类名中。为了确保一切顺利，不要在转换名称中使用下划线。

响应式图像

您可以使用图像处理自动生成一组图像，浏览器将根据视口宽度或设备分辨率选择显示这些图像。为此，图像处理将为<img>标签添加一个srcset属性（以及可能的一个media和一个sizes属性）。

HTML5支持两种类型的响应式图像集。第一种是基于设备像素比，为高分辨率设备选择更高分辨率的图像；第二种是基于视口，根据视口大小选择图像。您可以在HTML5响应式图像中了解更多关于srcset和<picture>语法的介绍。

要告诉图像处理生成响应式图像，请向您的IMAGE_PROCESS字典添加一个responsive-image转换，其语法如下

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",
    },
}

crisp 转换是设备像素比选择的一个例子。 srcset 是一个元组列表，每个元组包含图像描述（"1x"、"2x" 等）和从原始图像生成派生图像的操作列表（原始图像是 <img> 的 src 属性的值）。图像描述是关于相关图像分辨率的提示，必须具有 x 后缀。 default 设置指定用于替换图像 src 属性的图像。这是不支持 srcset 语法的浏览器将显示的图像。

large-photo 转换是启用视口选择的转换的一个例子。 sizes 包含一个规则，用于从视口宽度计算显示图像的宽度。一旦浏览器知道图像宽度，它将从 srcset 中选择图像源。 srcset 是一个元组列表，每个元组包含图像描述（"600w"、"800w" 等）和从原始图像生成派生图像的操作列表（原始图像是 <img> 的 src 属性的值）。图像描述是关于相关图像像素宽度的提示，必须具有 w 后缀。 default 设置指定用于替换图像 src 属性的图像。这是不支持 srcset 语法的浏览器将显示的图像。

在上面的两个例子中，default 设置是一个字符串，引用了 srcset 中的某个图像。但是，default 值也可以是生成不同派生图像的操作列表。

为了使文章中的图像具有响应性，您必须向它们添加特殊的类 image-process-<transform>，其中 <transform> 是您要应用转换的 ID，就像您在上述图像替换情况下所做的那样。

所以，在 HTML 中，它应该看起来像这样

<img class="image-process-large-photo" src="/images/pelican.jpg"/>

这可以用 Markdown 生成

![](/images/pelican.jpg){: .image-process-large-photo}

在reStructuredText中，使用image或figure指令的:class:属性

.. image:: /images/pelican.jpg
   :class: image-process-large-photo

.. figure:: /images/pelican.jpg
    :class: image-process-large-photo

图片集

图像处理 可以用于生成 <picture> 标签使用的图像。 <picture> 语法允许向浏览器提供更多灵活性的图像选择。再次，您可以阅读有关 HTML5 响应式图像 的更多信息，以了解 srcset 和 <picture> 语法的简单介绍。

要指示 图像处理 为 <picture> 生成图像，请向您的 IMAGE_PROCESS 字典中添加一个 picture 条目，其语法如下

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"),
    },
}

每个 sources 条目都与上述描述的 响应式图像 非常相似。在这里，每个源都必须有一个 name，它将用于在您的文章中查找该源原始图像的 URL。源还可以有一个 media，它包含浏览器用于选择活动源的规定。 default 设置指定用于替换 <picture> 内部 <img> 的 src 属性的图像。这是不支持 <picture> 语法的浏览器将显示的图像。在此示例中，它将使用 default 源中的 640w 图像。也可以指定一个操作列表而不是 640w。

为了生成文章中图像的响应式 <picture>，您必须在您的文章中添加一个类似这样的伪 <picture> 标签

<picture>
    <source class="source-1" src="/images/pelican-closeup.jpg"></source>
    <img class="image-process-example-pict" src="/images/pelican.jpg"/>
</picture>

每个 <source> 标签将一个源名称（class 属性）映射到一个文件（src 属性）。<img> 标签必须具有特殊的类名 image-process- 后跟要应用的转换名称。由 <img> 的 src 属性引用的文件将用作转换定义中的特殊 default 源。

您无法仅使用纯 Markdown 来实现此功能，而必须求助于原始 HTML。

然而，在 reStructuredText 中，您还可以使用 figure 指令生成 <picture>。图象文件将被用作特殊的 default 源；其他源必须在 figure 的图例部分作为 image 指令添加。图象类必须是 image-process- 后跟要应用的转换名称，而其他图像必须有两个类：image-process 和它们提供的图像的名称。

.. figure:: /images/pelican.jpg
   :class: image-process-example-pict

    Test picture

    .. image:: /images/pelican-closeup.jpg
       :class: image-process source-1

用作 <picture> 源的图例中的图像将被从图例中删除，以确保它们不会出现在您的最终文章中。

转换

可用的转换操作有

• 裁剪 <顶部> <左侧> <右侧> <底部>:

  裁剪图像到矩形框（<左侧>，<顶部>）-（<右侧>，<底部>）。值可以是绝对值（一个数字）或相对于图像大小的相对值（一个数字后跟一个百分号 %）。

• 水平翻转:

  水平翻转图像。

• 垂直翻转:

  垂直翻转图像。

• 灰度:

  将图像转换为灰度。

• 调整大小 <宽度> <高度>:

  调整图像大小。此操作不保留图像的纵横比。值可以是绝对值（一个数字）或相对于图像大小的相对值（一个数字后跟一个百分号 %）。

• 旋转 <度数>:

  旋转图像。

• 缩放内 <宽度> <高度> <放大>:

  调整图像大小。此操作保留图像的纵横比，并且生成的图像大小不会超过 <宽度> x <高度>。值可以是绝对值（一个数字）或相对于图像大小的相对值（一个数字后跟一个百分号 %）。如果 <放大> 为 False，则不会放大较小的图像。

• 缩放外 <宽度> <高度> <放大>:

  调整图像大小。此操作保留图像的纵横比，并且生成的图像大小不会小于 <宽度> x <高度>。值可以是绝对值（一个数字）或相对于图像大小的相对值（一个数字后跟一个百分号 %）。如果 <放大> 为 False，则不会放大较小的图像。

• 模糊:

  将 pillow.ImageFilter.BLUR 过滤器应用到图像上。

• 轮廓:

  将 pillow.ImageFilter.CONTOUR 过滤器应用到图像上。

• 细节:

  将 pillow.ImageFilter.DETAIL 过滤器应用到图像上。

• 边缘增强:

  将 pillow.ImageFilter.EDGE_ENHANCE 过滤器应用到图像上。

• 边缘增强更多:

  将 pillow.ImageFilter.EDGE_ENHANCE_MORE 过滤器应用到图像上。

• 浮雕:

  将 pillow.ImageFilter.EMBOSS 过滤器应用到图像上。

• 查找边缘:

  将 pillow.ImageFilter.FIND_EDGES 过滤器应用到图像上。

• 平滑:

  将 pillow.ImageFilter.SMOOTH 过滤器应用到图像上。

• 平滑更多:

  将 pillow.ImageFilter.SMOOTH_MORE 过滤器应用到图像上。

• 锐化:

  将 pillow.ImageFilter.SHARPEN 过滤器应用到图像上。

您还可以定义自己的操作；唯一的要求是您的操作应该是一个期望以 pillow.Image 作为其第一个参数的可调用对象，并且它应该返回转换后的图像

def crop_face(image):
    """Detect face in image and crop around it."""
    # Fancy algorithm.
    return image

IMAGE_PROCESS = {
    "face-thumbnail": [crop_face, "scale_out 150 150 True"]
}

其他设置

目标目录

默认情况下，新图片将被存储在输出文件夹中与原始图片相同的目录，目录名为derivative/<TRANSFORMATION_NAME>。例如，如果原始图片位于content/images文件夹中，则计算出的图片将被存储在output/images/derivative/<TRANSFORMATION_NAME>。所有变换都在输出目录中进行，以避免与源文件混淆或测试多个变换。您可以使用Pelican设置文件中的IMAGE_PROCESS_DIR设置将derivative替换为其他名称。

IMAGE_PROCESS_DIR = "derivees"

强制图像处理

如果变换后的图像已经存在且比原始图像新，则插件假定不应再次重新计算它。您可以通过将Pelican配置文件中的IMAGE_PROCESS_FORCE设置为True来强制插件重新计算所有图像。

IMAGE_PROCESS_FORCE = True

选择HTML解析器

您可以选择要使用的HTML解析器。默认是内置的html.parser，但您也可以通过在Pelican设置文件中设置IMAGE_PROCESS_PARSER来选择html5lib或lxml。例如

IMAGE_PROCESS_PARSER = "html5lib"

有关详细信息，请参阅BeautifulSoup关于解析器的文档。

文件编码

您可以选择BeautifulSoup打开文件时使用的不同文件编码。默认为utf-8。

IMAGE_PROCESS_ENCODING = "utf-8"

复制EXIF标签

您可以要求Image Process将原始图像的EXIF标签复制到变换后的图像中。您必须已安装exiftool。

IMAGE_PROCESS_COPY_EXIF_TAGS = True

已知问题

• Pillow在调整动画GIF文件的大小时，不返回动画文件。

贡献

欢迎并非常感谢贡献。每一份贡献都很有帮助。您可以通过改进文档、添加缺失的功能和修复错误来做出贡献。您还可以通过审查和评论现有问题来提供帮助。

要开始为此插件做出贡献，请审查Pelican贡献文档，从贡献代码部分开始。

重新生成测试图像

如果您需要重新生成测试套件使用的变换图像，有一个辅助函数可以帮助您完成此操作。从Python交互式解释器

>>> from pelican.plugins.image_process.test_image_process import generate_test_images
>>> generate_test_images()
36 test images generated!

许可证

本项目采用AGPL-3.0许可协议。

测试数据中的Pelican图像由Jon Sullivan提供。在Creative Commons公共领域许可协议下发布。