Fix translate; add default values

.pre-commit-config.yaml

@@ -36,6 +36,7 @@ repos:
     rev: 22.3.0
     hooks:
     -   id: black
+        args: [--target-version, py36]
 # -   repo: https://github.com/asottile/pyupgrade
 #     rev: v2.31.1
 #     hooks:

PyPDF2/__init__.py

@@ -1,4 +1,5 @@
 from ._merger import PdfFileMerger
+from ._page import Transformation
 from ._reader import PdfFileReader
 from ._version import __version__
 from ._writer import PdfFileWriter
@@ -10,6 +11,7 @@
     "PageRange",
     "PaperSize",
     "parse_filename_page_ranges",
+    "Transformation",
     "PdfFileMerger",
     "PdfFileReader",
     "PdfFileWriter",

PyPDF2/_page.py

@@ -138,12 +138,21 @@ def compress(matrix: TransformationMatrixType) -> CompressedTransformationMatrix
             matrix[1][2],
         )
 
-    def translate(self, tx: float, ty: float) -> "Transformation":
-        op = ((1, 0, 0), (0, 1, 0), (tx, ty, 1))
-        ctm = Transformation.compress(matrixMultiply(self.matrix, op))
-        return Transformation(ctm)
-
-    def scale(self, sx: float, sy: float) -> "Transformation":
+    def translate(self, tx: float = 0, ty: float = 0) -> "Transformation":
+        m = self.ctm
+        return Transformation(ctm=(m[0], m[1], m[2], m[3], m[4] + tx, m[5] + ty))
+
+    def scale(
+        self, sx: Optional[float] = None, sy: Optional[float] = None
+    ) -> "Transformation":
+        if sx is None and sy is None:
+            raise ValueError("Either sx or sy must be specified")
+        if sx is None:
+            sx = sy
+        if sy is None:
+            sy = sx
+        assert sx is not None
+        assert sy is not None
         op: TransformationMatrixType = ((sx, 0, 0), (0, sy, 0), (0, 0, 1))
         ctm = Transformation.compress(matrixMultiply(self.matrix, op))
         return Transformation(ctm)
@@ -158,6 +167,9 @@ def rotate(self, rotation: float) -> "Transformation":
         ctm = Transformation.compress(matrixMultiply(self.matrix, op))
         return Transformation(ctm)
 
+    def __repr__(self) -> str:
+        return f"Transformation(ctm={self.ctm})"
+
 
 class PageObject(DictionaryObject):
     """

docs/user/cropping-and-transforming.md

@@ -29,3 +29,73 @@ writer.addJS("this.print({bUI:true,bSilent:false,bShrinkToFit:true});")
 with open("PyPDF2-output.pdf", "wb") as fp:
     writer.write(fp)
 ```
+
+## Plain Merge
+
+![](plain-merge.png)
+
+is the result of
+
+```python
+from PyPDF2 import PdfFileReader, PdfFileWriter, Transformation
+
+# Get the data
+reader_base = PdfFileReader("labeled-edges-center-image.pdf")
+page_base = reader_base.pages[0]
+
+reader = PdfFileReader("box.pdf")
+page_box = reader.pages[0]
+
+# Apply the transformation: Be aware, that this is an in-place operation
+page_base.mergeTransformedPage(page_box, Transformation())
+
+# Write the result back
+writer = PdfFileWriter()
+writer.addPage(page_base)
+with open("merged-foo.pdf", "wb") as fp:
+    writer.write(fp)
+```
+
+## Merge with Rotation
+
+![](merge-45-deg-rot.png)
+
+```python
+from PyPDF2 import PdfFileReader, PdfFileWriter, Transformation
+
+# Get the data
+reader_base = PdfFileReader("labeled-edges-center-image.pdf")
+page_base = reader_base.pages[0]
+
+reader = PdfFileReader("box.pdf")
+page_box = reader.pages[0]
+
+# Apply the transformation: Be aware, that this is an in-place operation
+op = Transformation().rotate(45)
+page_base.mergeTransformedPage(page_box, op)
+
+# Write the result back
+writer = PdfFileWriter()
+writer.addPage(page_base)
+with open("merged-foo.pdf", "wb") as fp:
+    writer.write(fp)
+```
+
+If you add the expand parameter:
+
+```python
+op = Transformation().rotate(45)
+page_base.mergeTransformedPage(page_box, op, expand=True)
+```
+
+you get:
+
+![](merge-rotate-expand.png)
+
+Alternatively, you can move the merged image a bit to the right by using
+
+```python
+op = Transformation().rotate(45).translate(tx=50)
+```
+
+![](merge-translated.png)