A contain rectangle is a contract, not a PDF fidelity test

A rectangle helper can answer a narrow question: given image dimensions and a page-sized box, where should the image be drawn so it fits proportionally? That answer is useful only when its assumptions and boundaries are explicit.

The contract below accepts image width and height, page width and height, and a uniform margin. It returns a centered draw rectangle. It does not read an image, interpret orientation metadata, or create a PDF.

Define the policy first

For this standalone example, all four dimensions must be finite JavaScript numbers from 1 through 1,000,000, inclusive. The margin must be finite and nonnegative, and twice the margin must be smaller than both page dimensions. That leaves a nonempty usable rectangle.

The numeric range is a chosen example budget, not a universal standard or a claim about identical production input validation. The function treats source width and height as values in the same numeric mapping used for page units. Capping the scale at one means one source unit maps to at most one page unit. This is a policy for this example, not a physical DPI conversion.

A successful result should satisfy four invariants:

• Aspect ratio: width and height share one scale, so their ratio follows the source ratio, subject to floating-point precision.
• Bounds: the draw rectangle fits inside both dimensions of the usable page area.
• Centering: the remaining space is split equally on opposite sides.
• No upscale: neither output dimension exceeds its corresponding source dimension under the chosen unit mapping.

export function containRect(iw, ih, pw, ph, margin) {
  if (![iw, ih, pw, ph].every(v =>
    typeof v === "number" && Number.isFinite(v) && v >= 1 && v <= 1e6
  )) throw new RangeError("dimensions must be numbers from 1 to 1000000");
  if (typeof margin !== "number" || !Number.isFinite(margin) ||
      margin < 0 || 2 * margin >= Math.min(pw, ph)) {
    throw new RangeError("margin leaves no usable rectangle");
  }
  const scale = Math.min(1, (pw - 2 * margin) / iw, (ph - 2 * margin) / ih);
  const width = iw * scale;
  const height = ih * scale;
  return { x: (pw - width) / 2, y: (ph - height) / 2, width, height };
}

Taking the minimum picks whichever of width or height is the limiting side, with one as the upper bound. Centering uses the full page dimensions; because the margins are equal on opposite sides, the resulting rectangle remains centered inside the usable area too.

Run the example

Place the function and the following assertions in the same file named example.mjs, with the function first. Run node example.mjs. The import supplies Node’s strict assertions; a successful run prints nothing. The examples check a wide image, a small image, and three rejected inputs.

import assert from "node:assert/strict";

assert.deepEqual(containRect(1200, 600, 600, 800, 20),
  { x: 20, y: 260, width: 560, height: 280 });
assert.deepEqual(containRect(100, 50, 600, 800, 20),
  { x: 250, y: 375, width: 100, height: 50 });
for (const args of [
  ["1200", 600, 600, 800, 20],
  [1200, 600, 600, 800, 300],
  [0, 600, 600, 800, 20],
]) assert.throws(() => containRect(...args), RangeError);

For the first case, the usable area is 560 by 760. Width limits the scale, producing a 560 by 280 rectangle at (20, 260). For the second, the scale cap keeps the 100 by 50 image at that size and centers it at (250, 375).

The broader numeric harness also checks two deliberately wrong calculations: stretching to 560 by 760 breaks the source’s 2:1 ratio, and uncapped fitting would enlarge a 100 by 50 source. Those comparisons expose the need for aspect and no-upscale policies. The short assertion block above does not include those two comparisons.

Know what the numbers establish

On 2026-10-28, a Codex agent ran pure numeric cases using Node v22.23.4 on Darwin: nine valid cases, 12 invalid cases, nine comparisons with the production helper for valid numeric draw dimensions, and two negative controls. The comparison does not establish full implementation equivalence or matching input policies.

A correct rectangle cannot prove that the intended image was decoded, rotated correctly, embedded without an unwanted change, serialized into the right page box, or displayed as a recipient expects. Those require separate artifact and reader checks. No encoded image or PDF was tested in this numeric exercise.

Disclosure: GPT-6.1 Terra drafted this article for Yan Wang / LensUp. The Codex agent checked formal source and live-page text and ran the numeric cases on 2026-10-28. No new HEIC or image-to-PDF conversion, browser, phone, printer, or human-owner test was performed.