PDF.js Deep Dive from Demo 4: getViewport

Introduction

In the previous article, we obtained the page variable via await pdf.getPage(1). It is a PDFPageProxy instance whose _pageInfo holds the page metadata: rotate: 0, userUnit: 1, view: [0, 0, 595, 842].

Back to the demo from the first article, lines 10-11:

const viewport = page.getViewport({ scale: 0.5 });

An object parameter is passed in:

Parameter	Value	Meaning
scale	0.5	The zoom factor

Unlike getPage, getViewport is a synchronous call: it does not touch the worker and performs no IO — it is purely a math computation. Starting from this call, this article walks through the complete execution of getViewport.

The getViewport call

Based on its definition in api.js, the execution flow is as follows.

Lines 1423-1439: Destructure the parameters

view source

getViewport({
  scale,                  // 0.5, the only parameter passed in
  rotation = this.rotate, // this._pageInfo.rotate = 0
  offsetX = 0,
  offsetY = 0,
  dontFlip = false,
} = {}) {
  return new PageViewport({
    viewBox: this.view,   // [0, 0, 595, 842]
    userUnit: this.userUnit, // 1
    scale,
    rotation,
    offsetX,
    offsetY,
    dontFlip,
  });
}

Note that the default value of rotation comes from the page itself: the PDF page's own /Rotate attribute is applied automatically, so the caller does not need to care about it. this.view and this.userUnit come from the pageInfo returned by the GetPage message in the previous article.

Once the parameters are collected, they are all handed to the PageViewport constructor (display/page_viewport.js): view source. All subsequent computation takes place there.

Q: What are offsetX / offsetY for?

A: They translate the rendered result on the canvas — for example, to tile multiple pages onto one large canvas, or to leave padding around a page. The demo does not pass them, so they default to 0.

Line 70: scale absorbs userUnit (page_viewport.js)

scale *= userUnit; // 0.5 * 1 = 0.5

Q: What is userUnit?

A: A unit conversion factor introduced in PDF 1.6: 1 unit in PDF user space = userUnit / 72 inches, with a default value of 1. By folding it into scale, subsequent computations no longer need to distinguish between "user space units" and "actual size".

Lines 74-75: Compute the page center point (page_viewport.js)

const centerX = (viewBox[2] + viewBox[0]) / 2; // (595 + 0) / 2 = 297.5
const centerY = (viewBox[3] + viewBox[1]) / 2; // (842 + 0) / 2 = 421

Rotation happens around the page center, so the center point is computed first for later use.

Lines 78-116: Normalize the rotation and compute the rotation vector (page_viewport.js)

rotation %= 360; // 0
if (rotation < 0) {
  rotation += 360;
}
switch (rotation) {
  case 0:
    rotateA = 1;
    rotateB = 0;
    rotateC = 0;
    rotateD = -1;
    break;
  // case 90 / 180 / 270 omitted
  default:
    throw new Error('PageViewport: Invalid rotation, must be a multiple of 90 degrees.');
}

The rotation is normalized into the [0, 360) range, and only multiples of 90 are allowed; any other value throws an error directly — this is a restriction of the PDF specification.

The demo's rotation is 0, which hits case 0: rotateA = 1, rotateB = 0, rotateC = 0, rotateD = -1.

Q: Why is rotateD -1 when rotation is 0?
A: This is the y-axis flip. In the PDF coordinate system the y-axis points up (a mathematical coordinate system with the origin at the bottom-left), while in the canvas coordinate system the y-axis points down (a screen coordinate system with the origin at the top-left). Even without any rotation, a flip is needed to align the two, and rotateD = -1 is exactly that flip.

Correspondingly, dontFlip = true negates rotateC and rotateD, canceling this flip — useful when the target coordinate system also has an upward y-axis.

Lines 120-130: Compute width, height, and canvas offsets (page_viewport.js)

if (rotateA === 0) {
  // The branch for rotation 90/270: width and height are swapped
  offsetCanvasX = Math.abs(centerY - viewBox[1]) * scale + offsetX;
  offsetCanvasY = Math.abs(centerX - viewBox[0]) * scale + offsetY;
  width = (viewBox[3] - viewBox[1]) * scale;
  height = (viewBox[2] - viewBox[0]) * scale;
} else {
  offsetCanvasX = Math.abs(centerX - viewBox[0]) * scale + offsetX; // 297.5 * 0.5 + 0 = 148.75
  offsetCanvasY = Math.abs(centerY - viewBox[1]) * scale + offsetY; // 421 * 0.5 + 0 = 210.5
  width = (viewBox[2] - viewBox[0]) * scale; // 595 * 0.5 = 297.5
  height = (viewBox[3] - viewBox[1]) * scale; // 842 * 0.5 = 421
}

The rotateA === 0 branch corresponds to a 90/270 degree rotation: the page lies on its side, and the computations of width and height are swapped. The demo's rotation is 0, so it takes the else branch.

Lines 134-141: Assemble the transform matrix (page_viewport.js)

this.transform = [
  rotateA * scale, // 0.5
  rotateB * scale, // 0
  rotateC * scale, // 0
  rotateD * scale, // -0.5
  offsetCanvasX - rotateA * scale * centerX - rotateC * scale * centerY, // 148.75 - 148.75 - 0 = 0
  offsetCanvasY - rotateB * scale * centerX - rotateD * scale * centerY, // 210.5 - 0 + 210.5 = 421
];
// transform = [0.5, 0, 0, -0.5, 0, 421]

The source code comment explains the composite transformation these 6 components correspond to:

translate(-centerX, -centerY), rotate and flip vertically, scale, and translate(offsetCanvasX, offsetCanvasY)

That is: move the page center to the origin → rotate and flip vertically → scale → translate to the target position on the canvas. These are exactly the 6 arguments that canvas setTransform(a, b, c, d, e, f) needs, and they will be applied directly during rendering (covered in the next article).

Let's verify the correctness of the matrix: take the top-left corner of the page in the PDF coordinate system, (0, 842) (with the y-axis pointing up, "top" is the larger value), and apply the matrix:

• x' = 0.5 * 0 + 0 * 842 + 0 = 0
• y' = 0 * 0 + (-0.5) * 842 + 421 = 0

It maps exactly to the canvas coordinate (0, 0), i.e., the top-left corner of the canvas. ✓

The 6th component, 421, happens to equal height: after the y-axis flip, the whole page ends up above the canvas (negative y), so it needs to be translated down by one page height to land back inside the canvas.

Lines 143-144: Store width and height (page_viewport.js)

this.width = width; // 297.5
this.height = height; // 421

These two values are the source of canvas.width = Math.floor(viewport.width) in the first article's demo: Math.floor(297.5) is 297, so the actual canvas size is 297 x 421.

At this point, all of getViewport's computation is complete, and the returned PageViewport instance is assigned to the demo's viewport variable.

Summary

This article followed the demo through the complete computation of getViewport({ scale: 0.5 }):

1. Parameter destructuring: scale = 0.5, rotation defaults to the page's /Rotate value 0, and the rest are 0/false;
2. scale absorbs userUnit, remaining 0.5;
3. Compute the page center point (297.5, 421);
4. After rotation normalization, take the rotation vector (1, 0, 0, -1), where rotateD = -1 performs the y-axis flip;
5. Compute the width and height 297.5 x 421 and the canvas offsets (148.75, 210.5);
6. Assemble transform = [0.5, 0, 0, -0.5, 0, 421], completing the "PDF coordinates → canvas coordinates" mapping.

viewport also carries methods like convertToViewportPoint / convertToPdfPoint (bidirectional coordinate conversion, used for text selection and annotation positioning: view source) and clone (deriving a new viewport: view source), which the demo does not use, so we will not expand on them here.

With the viewport in hand, the demo packages it together with canvasContext and passes them to page.render(renderContext) — the transform matrix will be applied to the canvas context there. That will be covered in the next article.

---

About me: Creator of StreamPDF, focused on research and development in AI and PDF.

Original article: PDF.js Deep Dive from Demo 4: getViewport