Add QPDFPageObjectHelper::getMatrixForFormXObjectPlacement

ChangeLog

@@ -1,5 +1,10 @@
 2021-02-18  Jay Berkenbilt  <ejb@ql.org>
 
+	* Add QPDFPageObjectHelper::getMatrixForFormXObjectPlacement,
+	which returns the transformation matrix required to map from a
+	form field's coordinate system into a specific rectangle within
+	the page.
+
 	* Add QUtil::path_basename to get last element of a path.
 
 	* Add examples/pdf-attach-file.cc to illustrate new file

include/qpdf/QPDFPageObjectHelper.hh

@@ -24,6 +24,7 @@
 
 #include <qpdf/QPDFObjectHelper.hh>
 #include <qpdf/QPDFAnnotationObjectHelper.hh>
+#include <qpdf/QPDFMatrix.hh>
 
 #include <qpdf/DLL.h>
 
@@ -306,6 +307,16 @@ class QPDFPageObjectHelper: public QPDFObjectHelper
         bool allow_shrink = true,
         bool allow_expand = false);
 
+    // Return the transformation matrix that translates from the given
+    // form XObject's coordinate system into the given rectangular
+    // region on the page. The parameters have the same meaning as for
+    // placeFormXObject.
+    QPDF_DLL
+    QPDFMatrix getMatrixForFormXObjectPlacement(
+        QPDFObjectHandle fo, QPDFObjectHandle::Rectangle rect,
+        bool invert_transformations = true,
+        bool allow_shrink = true, bool allow_expand = false);
+
     // If a page is rotated using /Rotate in the page's dictionary,
     // instead rotate the page by the same amount by altering the
     // contents and removing the /Rotate key. This method adjusts the

libqpdf/QPDFPageObjectHelper.cc

@@ -947,10 +947,9 @@ QPDFPageObjectHelper::getFormXObjectForPage(bool handle_transformations)
     return result;
 }
 
-std::string
-QPDFPageObjectHelper::placeFormXObject(
-    QPDFObjectHandle fo, std::string const& name,
-    QPDFObjectHandle::Rectangle rect,
+QPDFMatrix
+QPDFPageObjectHelper::getMatrixForFormXObjectPlacement(
+    QPDFObjectHandle fo, QPDFObjectHandle::Rectangle rect,
     bool invert_transformations,
     bool allow_shrink, bool allow_expand)
 {
@@ -971,7 +970,7 @@ QPDFPageObjectHelper::placeFormXObject(
     QPDFObjectHandle bbox_obj = fdict.getKey("/BBox");
     if (! bbox_obj.isRectangle())
     {
-        return "";
+        return QPDFMatrix();
     }
 
     QPDFMatrix wmatrix;         // work matrix
@@ -1014,7 +1013,7 @@ QPDFPageObjectHelper::placeFormXObject(
     if ((T.urx == T.llx) || (T.ury == T.lly))
     {
         // avoid division by zero
-        return "";
+        return QPDFMatrix();
     }
     double rect_w = rect.urx - rect.llx;
     double rect_h = rect.ury - rect.lly;
@@ -1060,6 +1059,18 @@ QPDFPageObjectHelper::placeFormXObject(
     cm.translate(tx, ty);
     cm.scale(scale, scale);
     cm.concat(tmatrix);
+    return cm;
+}
+
+std::string
+QPDFPageObjectHelper::placeFormXObject(
+    QPDFObjectHandle fo, std::string const& name,
+    QPDFObjectHandle::Rectangle rect,
+    bool invert_transformations,
+    bool allow_shrink, bool allow_expand)
+{
+    QPDFMatrix cm = getMatrixForFormXObjectPlacement(
+        fo, rect, invert_transformations, allow_shrink, allow_expand);
     return (
         "q\n" +
         cm.unparse() + " cm\n" +

manual/qpdf-manual.xml

@@ -5283,6 +5283,15 @@ print "\n";
           matrices.
          </para>
         </listitem>
+        <listitem>
+         <para>
+	  Add
+	  <function>QPDFPageObjectHelper::getMatrixForFormXObjectPlacement</function>
+	  which returns the transformation matrix required to map from
+	  a form field's coordinate system into a specific rectangle
+	  within the page.
+         </para>
+        </listitem>
         <listitem>
          <para>
           Add <function>QUtil::path_basename</function> to return the