How to add an image to a specific location, but always right side up?

Question:
We want to place an image at a specific location and dimensions, to a give page.

This works fine for most PDF pages, but for pages where the page is rotated in the PDF, then the image is not the right side up. Instead it is sideways, or even upside down.

How to place so its is always right side up?

Answer:
The following C# code shows how to place an image in a specific location, and with the specified dimensions, but then rotates the right way up based on the target pages rotation.

using (PDFDoc doc = new PDFDoc(your_pdf))
using (ElementBuilder builder = new ElementBuilder())
using (ElementWriter writer = new ElementWriter())
{
	Rect bbox = new Rect(72, 272, 144, 344); // target location and dimensions of image
	Page page = doc.GetPage(pageNum);
	writer.Begin(page, ElementWriter.WriteMode.e_overlay, false);
	Matrix2D origin = new Matrix2D(1, 0, 0, 1, -0.5, -0.5);
	pdftron.PDF.Page.Rotate pageRotation = page.GetRotation();
	// do reverse rotation of the page rotation, so the image on the page has same orientation of the image (unless that image itself contains a rotation in EXIF metadata)
	Matrix2D rot = Matrix2D.RotationMatrix(pdftron.PDF.Page.RotationToDegree(pageRotation) / 180.0 * -Math.PI);
	Matrix2D scaleAndTrans = new Matrix2D(bbox.Width(), 0, 0, bbox.Height(), bbox.x1 + (bbox.Width() / 2.0), bbox.y1 + (bbox.Height() / 2.0));
	Matrix2D mtx = scaleAndTrans * rot * origin;
	Image img = Image.Create(doc, input_path + "butterfly.png");
	writer.WriteElement(builder.CreateImage(img, mtx));
	writer.End();

    doc.Save(out_path, SDFDoc.SaveOptions.e_linearized);
}

If you happen to not be coding in C#, then our other APIs are very similar, so porting this to our other APIs is mostly 1:1 mapping.

Attached is PHP code to do the same.

<?php
include("../../../PDFNetC/Lib/PDFNetPHP.php");
	PDFNet::Initialize();
	PDFNet::GetSystemFontList();    // Wait for fonts to be loaded if they haven't already. This is done because PHP can run into errors when shutting down if font loading is still in progress.
	$input_path = getcwd()."/../../TestFiles/";
	$output_path = $input_path."Output/";

	$doc = new PDFDoc($input_path."your.pdf");
    $doc->InitSecurityHandler();
	$builder = new ElementBuilder();
	$writer = new ElementWriter();
	$page = $doc->GetPage(1);
	$writer->Begin($page,  ElementWriter::e_overlay, false);
    $bbox = new Rect(72.0, 272.0, 144.0, 344.0);
    $origin = new Matrix2D(1.0, 0.0, 0.0, 1.0, -0.5, -0.5);
    $pageRotation = $page->GetRotation();
    //// do reverse rotation of the page rotation, so the image on the page has same orientation of the image (unless that image itself contains a rotation in EXIF metadata)
    $rot = Matrix2D::RotationMatrix(Page::RotationToDegree($pageRotation) / 180.0 * -pi());
    $scaleAndTrans = new Matrix2D($bbox->Width(), 0.0, 0.0, $bbox->Height(), $bbox->getX1() + ($bbox->Width() / 2.0), $bbox->getY1() + ($bbox->Height() / 2.0));
    $mtx = $rot->Multiply($origin);
    $mtx = $scaleAndTrans->Multiply($mtx);
    $img = Image::Create($doc->GetSDFDoc(), $input_path."butterfly.png");
	$element = $builder->CreateImage($img, $mtx);
	$writer->WritePlacedElement($element);
    $writer->End();
	$doc->Save(($output_path."your-stamped.pdf"), SDFDoc::e_linearized);
	$doc->Close();
	echo nl2br("Done. Result saved in landscape-annot.pdf...\n");
?>