Qur'an page geometry

A vectorised muṣḥaf page is glyph outlines plus a map of which ink belongs to which verse or word. That map is a set of coordinates, and every coordinate is measured from an origin that belongs to one file. This page is about what those numbers are anchored to, so that a highlight, a crop or a hit-test lands on the ink you meant.

Three of our blocks publish geometry, at three depths. Coverage narrows as addressing deepens: Quran SVG covers every vectorised muṣḥaf and gives you an ayah region; Elements covers the muṣḥafs that have been split and gives you a box per word and a path per mark; Engine draws the split muṣḥafs on mobile with the same addressing.

Every number is anchored to one file

The same verse — the basmalah on page 1 of the same King Fahd Complex Ḥafṣ print — as two of our datasets describe it, read at build time:

Same ink, roughly 200 units apart in y. Quran SVG's page 1 declares viewBox="-53.3109 -198.4777 345 550" — the opening spread has its own origin — while the Elements page declares 0 0 345 550. Neither is wrong. Each file's coordinates are in that file's space, and the two were never promised to share one.

Three specific cases from the data:

• The viewBox is not constant even within one muṣḥaf. Pages 3–604 of Ḥafṣ declare 0 0 345 550; pages 1–2 declare their own origin; Warsh and Qālūn start at x = −6. Surah-variant files are cropped in height. Read it; never assume it.
• Recto and verso are drawn under different page matrices inside an Elements file, so raw path coordinates are not comparable across pages. getBBox() on a g.word already answers in that word's frame; the sidecar boxes exist for when there is no browser.
• Page 42 is page 42 of one muṣḥaf only. All five vectorised muṣḥafs have 604 pages, so page numbers look interchangeable. A riwayah divides its verses differently and its pages are set separately.

An ayah region is usually several rectangles

An ayah generally begins mid-line and ends mid-line, so its region is a stack of line strips, not one box. In the Ḥafṣ muṣḥaf, 4,221 of the 6,236 polygons have more than one subpath. Here is 1:7 on page 1 — thirteen points, because the verse turns through three lines:

113.70,130.39 13.82,130.39 13.82,162.77 37.11,162.77 37.11,189.05 73.48,189.05
73.48,214.95 171.86,214.95 171.86,191.54 204.99,191.54 204.99,160.65 113.70,160.28 113.70,130.39

That is why the bounding box is the wrong crop: the box around an ayah covers ink belonging to the verses either side. Clip to the polygon, and use the box only as the viewport.

// Handles both shapes. This is what the demo on this site runs.
function boxOf(polygon: string) {
  const nums = (polygon.match(/-?\d+(?:\.\d+)?/g) ?? []).map(Number);
  const xs: number[] = [];
  const ys: number[] = [];
  for (let i = 0; i + 1 < nums.length; i += 2) { xs.push(nums[i]); ys.push(nums[i + 1]); }
  const x = Math.min(...xs);
  const y = Math.min(...ys);
  return { x, y, w: Math.max(...xs) - x, h: Math.max(...ys) - y };
}

Word boxes interleave

An Elements word box is the exact extent of that word's outlines, rounded to two decimals. Arabic words overlap in x — a neighbour's ascender or an adjacent mark sits inside the same rectangle — so a box frames a word without isolating it. To lift one word out on its own, hide the page and show the one group; the box is the viewport, the group is the content.

const page = await (await fetch("/index/by-page/001.json")).json();
const w = page.words.find((x) => x.word_key === "1:1:2");
const [x0, y0, x1, y1] = w.box;
svg.setAttribute("viewBox", `${x0} ${y0} ${x1 - x0} ${y1 - y0}`);

svg.style.visibility = "hidden";
svg.querySelector('g.word[data-word-key="1:1:2"]').style.visibility = "visible";

Boxes are [x0, y0, x1, y1] — two corners, not origin and size.

Page units and screen pixels

Everything above is in page units. A tap arrives in viewport pixels, through whatever scale and offset your layout applied. In the DOM, getScreenCTM() on the SVG converts one to the other. In Quran Engine the two spaces are two APIs: page.width is 345 page units, and anything named …View — hitTestViewEx, wordBoxView, highlightBoxes() — is in viewport pixels through the current layout. Feed raw mouse coordinates to the page-unit hitTest and you get the wrong word, or none, with no error.

What geometry does not give you

• The words. A polygon carries surah and ayah; an Elements word carries its printed form and key; neither is a text you can search. Join to Quran Text by word key.
• Letters. A word is the smallest addressable unit of text today, and a named mark the smallest unit of ink. Letter split is the goal for Elements and this is how far it has got.
• Another reading's page. Coordinates belong to one printed edition. To show the same ayah in Warsh you load the Warsh page and its own geometry — the ayah may well sit on a different page.

How this data is made

Quran SVG's pages are vectorised from the printed edition, and the ayah polygons are derived from each page's own ayah medallions, then audited against the ink. Elements regroups that same artwork into words and marks without moving or redrawing a path, and its boxes are read back out of the shipped SVGs. Engine converts the split pages with a pixel-diff gate that every one of the 604 pages passes, keeping coordinates exact to 0.01 page unit.