Aspect ratio-preserving image scale

Author: camelpunch

lib/mudbrick.ex

@@ -134,7 +134,7 @@ defmodule Mudbrick do
   ## Options
 
   - `:position` - `{x, y}` in points, relative to bottom-left corner.
-  - `:scale` - `{w, h}` in points.
+  - `:scale` - `{w, h}` in points. To preserve aspect ratio, set either, but not both, to `:auto`.
   - `:skew` - `{x, y}`, passed through to PDF `cm` operator.
 
   All options default to `{0, 0}`.
@@ -145,24 +145,43 @@ defmodule Mudbrick do
       ...> |> Mudbrick.page()
       ...> |> Mudbrick.image(:lovely_flower, position: {100, 100}, scale: {100, 100})
 
+  Forgetting to register the image:
+
       iex> Mudbrick.new()
       ...> |> Mudbrick.page()
       ...> |> Mudbrick.image(:my_face, position: {100, 100}, scale: {100, 100})
       ** (Mudbrick.Image.Unregistered) Unregistered image: my_face
 
+  Auto height:
+
+      iex> Mudbrick.new(images: %{lovely_flower: [file: Mudbrick.TestHelper.flower()]})
+      ...> |> Mudbrick.page(size: {50, 50})
+      ...> |> Mudbrick.image(:lovely_flower, position: {0, 0}, scale: {50, :auto})
+      ...> |> Mudbrick.render()
+      ...> |> then(&File.write("examples/image_auto_aspect_scale.pdf", &1))
+
+  <object width="400" height="100" data="examples/image_auto_aspect_scale.pdf?#navpanes=0" type="application/pdf"></object>
+
+  Attempting to set both width and height to `:auto`:
+
+      iex> Mudbrick.new(images: %{lovely_flower: [file: Mudbrick.TestHelper.flower()]})
+      ...> |> Mudbrick.page()
+      ...> |> Mudbrick.image(:lovely_flower, position: {100, 100}, scale: {:auto, :auto})
+      ** (Mudbrick.Image.AutoScalingError) Auto scaling works with width or height, but not both.
+
   Tip: to make the image fit the page, pass e.g. `Page.size(:a4)` as the
   `scale` and `{0, 0}` as the `position`.
   """
 
-  @spec image(context(), atom(), ContentStream.Cm.options()) :: context()
+  @spec image(context(), atom(), Image.image_options()) :: context()
   def image({doc, _content_stream_obj} = context, user_identifier, opts \\ []) do
     import ContentStream
 
     case Map.fetch(Document.root_page_tree(doc).value.images, user_identifier) do
       {:ok, image} ->
         context
         |> add(%ContentStream.QPush{})
-        |> add(ContentStream.Cm.new(opts))
+        |> add(ContentStream.Cm.new(cm_opts(image.value, opts)))
         |> add(%ContentStream.Do{image: image.value})
         |> add(%ContentStream.QPop{})
 
@@ -282,6 +301,29 @@ defmodule Mudbrick do
     end)
   end
 
+  @spec cm_opts(Mudbrick.Image.t(), Image.image_options()) :: Mudbrick.ContentStream.Cm.options()
+  defp cm_opts(image, image_opts) do
+    scale =
+      case image_opts[:scale] do
+        {:auto, :auto} ->
+          raise Mudbrick.Image.AutoScalingError,
+                "Auto scaling works with width or height, but not both."
+
+        {w, :auto} ->
+          ratio = w / image.width
+          {w, image.height * ratio}
+
+        {:auto, h} ->
+          ratio = h / image.height
+          {image.width * ratio, h}
+
+        otherwise ->
+          otherwise
+      end
+
+    Keyword.put(image_opts, :scale, scale)
+  end
+
   defp fetch_font(doc, opts) do
     Keyword.update(opts, :font, nil, fn user_identifier ->
       case Map.fetch(Document.root_page_tree(doc).value.fonts, user_identifier) do

lib/mudbrick/content_stream/cm.ex

@@ -4,7 +4,7 @@ defmodule Mudbrick.ContentStream.Cm do
           | {:scale, Mudbrick.coords()}
           | {:skew, Mudbrick.coords()}
 
-  @type options :: [options()]
+  @type options :: [option()]
 
   @type t :: %__MODULE__{
           position: Mudbrick.coords(),

lib/mudbrick/image.ex

@@ -1,5 +1,20 @@
 defmodule Mudbrick.Image do
-  @moduledoc false
+  @type t :: %__MODULE__{
+          file: iodata(),
+          resource_identifier: atom(),
+          width: number(),
+          height: number(),
+          bits_per_component: number(),
+          filter: :DCTDecode
+        }
+
+  @type scale_dimension :: number() | :auto
+  @type scale :: {scale_dimension(), scale_dimension()}
+  @type image_option ::
+          {:position, Mudbrick.coords()}
+          | {:scale, scale()}
+          | {:skew, Mudbrick.coords()}
+  @type image_options :: [image_option()]
 
   @enforce_keys [:file, :resource_identifier]
   defstruct [
@@ -8,10 +23,13 @@ defmodule Mudbrick.Image do
     :width,
     :height,
     :bits_per_component,
-    :colour_space,
     :filter
   ]
 
+  defmodule AutoScalingError do
+    defexception [:message]
+  end
+
   defmodule Unregistered do
     defexception [:message]
   end
@@ -23,6 +41,8 @@ defmodule Mudbrick.Image do
   alias Mudbrick.Document
   alias Mudbrick.Stream
 
+  @doc false
+  @spec new(Keyword.t()) :: t()
   def new(opts) do
     struct!(
       __MODULE__,
@@ -33,6 +53,7 @@ defmodule Mudbrick.Image do
     )
   end
 
+  @doc false
   def add_objects(doc, images) do
     {doc, image_objects, _id} =
       for {human_name, image_opts} <- images, reduce: {doc, %{}, 0} do

test/image_test.exs

@@ -30,6 +30,40 @@ defmodule Mudbrick.ImageTest do
     end
   end
 
+  test "specifying :auto height maintains aspect ratio" do
+    assert [
+             "q",
+             "100 0 0 95.4 123 456 cm",
+             "/I1 Do",
+             "Q"
+           ] =
+             new(images: %{flower: [file: flower()]})
+             |> page()
+             |> image(
+               :flower,
+               position: {123, 456},
+               scale: {100, :auto}
+             )
+             |> operations()
+  end
+
+  test "specifying :auto width maintains aspect ratio" do
+    assert [
+             "q",
+             "52.41090146750524 0 0 50 123 456 cm",
+             "/I1 Do",
+             "Q"
+           ] =
+             new(images: %{flower: [file: flower()]})
+             |> page()
+             |> image(
+               :flower,
+               position: {123, 456},
+               scale: {:auto, 50}
+             )
+             |> operations()
+  end
+
   test "asking for a registered image produces an isolated cm/Do operation" do
     assert [
              "q",