feat(image): allow images to keep their original aspect ratio

CONFIGURATION.md

@@ -39,7 +39,7 @@ In python-docx-template following additional custom filters are implemented:
 - timeformat(value, format, locale)
 - getwithdefault(value, default) - converts None to empty string (or provided default value) or leaves strings as is
 - emptystring(value) - converts None to empty string or leaves strings as is (deprecated in favor of getwithdefault)
-- image(width, height) - Creates an [inline image](https://docxtpl.readthedocs.io/en/latest/) from provided file with the same name. `width` and `height` are optional and represent millimetres.
+- image(width, height, keep_aspect_ratio) - Creates an [inline image](https://docxtpl.readthedocs.io/en/latest/) from provided file with the same name. `width` and `height` are optional and represent millimetres. If `keep_aspect_ratio` is `True` the image will be scaled keeping it's original aspect ratio and the width/height parameters become a size limit instead. `keep_aspect_ration` has no effect if `width` and `height` are not given.
 
 For formatting use babel and its uniode compatible [format](http://babel.pocoo.org/en/latest/dates.html#date-fields).
 

document_merge_service/api/jinja.py

@@ -8,6 +8,7 @@
 from docxtpl import InlineImage, Listing
 from jinja2 import pass_context
 from jinja2.sandbox import SandboxedEnvironment
+from PIL import Image
 from rest_framework.exceptions import ValidationError
 
 
@@ -65,7 +66,7 @@ def multiline(value):
 
 
 @pass_context
-def image(ctx, img_name, width=None, height=None):
+def image(ctx, img_name, width=None, height=None, keep_aspect_ratio=False):
     tpl = ctx["_tpl"]
 
     if img_name not in ctx:
@@ -83,6 +84,11 @@ def image(ctx, img_name, width=None, height=None):
 
     width = Mm(width) if width else None
     height = Mm(height) if height else None
+
+    if width and height and keep_aspect_ratio:
+        w, h = Image.open(img).size
+        width, height = get_size_with_aspect_ratio(width, height, w / h)
+
     return InlineImage(tpl, img, width=width, height=height)
 
 
@@ -102,3 +108,14 @@ def get_jinja_env():
     jinja_env = SandboxedEnvironment(extensions=settings.DOCXTEMPLATE_JINJA_EXTENSIONS)
     jinja_env.filters.update(get_jinja_filters())
     return jinja_env
+
+
+def get_size_with_aspect_ratio(width, height, aspect_ratio):
+    tpl_aspect_ratio = width / height
+
+    if tpl_aspect_ratio >= aspect_ratio:
+        width = height * aspect_ratio
+    else:
+        height = width / aspect_ratio
+
+    return width, height

document_merge_service/api/tests/test_jinja.py

@@ -1,6 +1,16 @@
 import pytest
+from docx.shared import Mm
 
-from ..jinja import dateformat, datetimeformat, emptystring, getwithdefault, timeformat
+from document_merge_service.api.data import django_file
+
+from ..jinja import (
+    dateformat,
+    datetimeformat,
+    emptystring,
+    getwithdefault,
+    image,
+    timeformat,
+)
 
 
 @pytest.mark.parametrize(
@@ -41,3 +51,31 @@ def test_emptystring(inp, expected):
 def test_getwithdefault(inp, default, expected):
     formatted = getwithdefault(inp, default=default)
     assert formatted == expected
+
+
+@pytest.mark.parametrize(
+    "width,height,keep_aspect_ratio,expected_size",
+    [
+        (20, 10, False, (20, 10)),
+        (20, 10, True, (10, 10)),
+        (10, 20, True, (10, 10)),
+        (10, None, False, (10, None)),
+        (None, 10, False, (None, 10)),
+        (10, None, True, (10, None)),
+        (None, 10, True, (None, 10)),
+    ],
+)
+def test_image(width, height, keep_aspect_ratio, expected_size):
+    # The size of "black.png" is 32x32 pixels which is an aspect ratio of 1
+    inline_image = image(
+        {"_tpl": None, "black.png": django_file("black.png").file},
+        "black.png",
+        width,
+        height,
+        keep_aspect_ratio,
+    )
+
+    w, h = expected_size
+
+    assert inline_image.width == (Mm(w) if w else None)
+    assert inline_image.height == (Mm(h) if h else None)

pyproject.toml

@@ -40,6 +40,7 @@ docx-mailmerge = "^0.5.0"
 docxtpl = "^0.17.0"
 Jinja2 = "^3.1.4"
 mysqlclient = { version = "^2.2.4", optional = true }
+pillow = "^10.3.0"
 psycopg = { version = "^3.1.19", optional = true, extras = ["binary"] }
 pymemcache = { version = "^4.0.0", optional = true }
 python-dateutil = "^2.9.0"