src/ tests/: address #2911, type returned by Page.derotation_matrix()

src/__init__.py:
    Matrix.__init__(): also accept single mupdf.FzMatrix arg.
    Path.derotation_matrix(): return a Matrix, not a tuple.
src/extra.i
    Page_derotate_matrix(): return a mupdf::FzMatrix, not tuple.
tests/test_annots.py
    Added an assert that page.derotation_matrix is a fitz.Matrix.

src/__init__.py

@@ -6469,6 +6469,7 @@ def __init__(self, *args, a=None, b=None, c=None, d=None, e=None, f=None):
         Matrix(degree) - rotate
         Matrix(Matrix) - new copy
         Matrix(sequence) - from 'sequence'
+        Matrix(mupdf.FzMatrix) - from MuPDF class wrapper for fz_matrix.
 
         Explicit keyword args a, b, c, d, e, f override any earlier settings if
         not None.
@@ -6480,7 +6481,14 @@ def __init__(self, *args, a=None, b=None, c=None, d=None, e=None, f=None):
         elif len(args) == 6:  # 6 numbers
             self.a, self.b, self.c, self.d, self.e, self.f = map(float, args)
         elif len(args) == 1:  # either an angle or a sequ
-            if hasattr(args[0], "__float__"):
+            if isinstance(args[0], mupdf.FzMatrix):
+                self.a = args[0].a
+                self.b = args[0].b
+                self.c = args[0].c
+                self.d = args[0].d
+                self.e = args[0].e
+                self.f = args[0].f
+            elif hasattr(args[0], "__float__"):
                 theta = math.radians(args[0])
                 c_ = round(math.cos(theta), 8)
                 s_ = round(math.sin(theta), 8)
@@ -6498,7 +6506,8 @@ def __init__(self, *args, a=None, b=None, c=None, d=None, e=None, f=None):
                 float(args[1]), float(args[0]), 1.0, 0.0, 0.0
         else:
             raise ValueError("Matrix: bad args")
-        #return
+
+        # Override with explicit args if specified.
         if a is not None:   self.a = a
         if b is not None:   self.b = b
         if c is not None:   self.c = c
@@ -8490,11 +8499,11 @@ def finished():
     def derotation_matrix(self) -> Matrix:
         """Reflects page de-rotation."""
         if g_use_extra:
-            return extra.Page_derotate_matrix( self.this)
+            return Matrix(extra.Page_derotate_matrix( self.this))
         pdfpage = self._pdf_page()
         if not pdfpage.m_internal:
-            return JM_py_from_matrix(mupdf.FzRect(mupdf.FzRect.UNIT))
-        return JM_py_from_matrix(JM_derotate_page_matrix(pdfpage))
+            return Matrix(mupdf.FzRect(mupdf.FzRect.UNIT))
+        return Matrix(JM_derotate_page_matrix(pdfpage))
 
     def extend_textpage(self, tpage, flags=0, matrix=None):
         page = self.this

src/extra.i

@@ -1209,16 +1209,16 @@ static PyObject* JM_py_from_matrix(mupdf::FzMatrix m)
     return Py_BuildValue("ffffff", m.a, m.b, m.c, m.d, m.e, m.f);
 }
 
-static PyObject* Page_derotate_matrix(mupdf::PdfPage& pdfpage)
+static mupdf::FzMatrix Page_derotate_matrix(mupdf::PdfPage& pdfpage)
 {
     if (!pdfpage.m_internal)
     {
-        return JM_py_from_matrix(*mupdf::FzMatrix().internal());
+        return mupdf::FzMatrix();
     }
-    return JM_py_from_matrix(JM_derotate_page_matrix(pdfpage));
+    return JM_derotate_page_matrix(pdfpage);
 }
 
-static PyObject* Page_derotate_matrix(mupdf::FzPage& page)
+static mupdf::FzMatrix Page_derotate_matrix(mupdf::FzPage& page)
 {
     mupdf::PdfPage pdf_page = mupdf::pdf_page_from_fz_page(page);
     return Page_derotate_matrix(pdf_page);
@@ -4282,8 +4282,8 @@ mupdf::FzPoint JM_point_from_py(PyObject* p);
 mupdf::FzRect Annot_rect(mupdf::PdfAnnot& annot);
 PyObject* util_transform_rect(PyObject* rect, PyObject* matrix);
 PyObject* Annot_rect3(mupdf::PdfAnnot& annot);
-PyObject* Page_derotate_matrix(mupdf::PdfPage& pdfpage);
-PyObject* Page_derotate_matrix(mupdf::FzPage& pdfpage);
+mupdf::FzMatrix Page_derotate_matrix(mupdf::PdfPage& pdfpage);
+mupdf::FzMatrix Page_derotate_matrix(mupdf::FzPage& pdfpage);
 PyObject* JM_get_annot_xref_list(const mupdf::PdfObj& page_obj);
 PyObject* JM_get_annot_xref_list2(mupdf::PdfPage& page);
 PyObject* JM_get_annot_xref_list2(mupdf::FzPage& page);

tests/test_annots.py

@@ -182,6 +182,9 @@ def test_1645():
     page = doc[0]
     page_bounds = page.bound()
     annot_loc = fitz.Rect(page_bounds.x0, page_bounds.y0, page_bounds.x0 + 75, page_bounds.y0 + 15)
+    # Check type of page.derotation_matrix - this is #2911.
+    assert isinstance(page.derotation_matrix, fitz.Matrix), \
+            f'Bad type for page.derotation_matrix: {type(page.derotation_matrix)=} {page.derotation_matrix=}.'
     page.add_freetext_annot(annot_loc * page.derotation_matrix, "TEST", fontsize=18,
     fill_color=fitz.utils.getColor("FIREBRICK1"), rotate=page.rotation)
     doc.save(path_out, garbage=1, deflate=True, no_new_id=True)