Merge pull request #60 from ffalt/feature/provide-text-colors

Add option to extract font color for text items

Author: ffalt

README.md

@@ -32,6 +32,7 @@ export interface PDFExtractOptions {
   disableCombineTextItems?: boolean; // default:`false` - do not attempt to combine  same line {@link TextItem}'s.
   includeAttachments?: boolean; // include attachments as base64. The default value is `false`.
   includeImages?: boolean; // include images as base64. The default value is `false`.
+  includeColors?: boolean; // default:`false` - include font fill color (best effort, possibly incomplete).
 }
 ```
 
@@ -281,8 +282,8 @@ interface PDFExtractImage {
             "horizontalCornerRadius": 0,
             "verticalCornerRadius": 0
           },
-          "color": [0, 0, 0],
-          "borderColor": [0, 0, 0],
+          "color": "#000000",
+          "borderColor": "#000000",
           "rotation": 0,
           "contentsObj": {
             "str": "",
@@ -312,7 +313,17 @@ interface PDFExtractImage {
           "dir": "ltr",
           "width": 64.656,
           "height": 12,
-          "fontName": "Times"
+          "transform": [12, 0, 0, 12, 70, 50],
+          "font": {
+            "size": 12,
+            "name": "TimesNewRomanPSMT",
+            "color": "#000000",
+            "family": "serif",
+            "vertical": false,
+            "ascent": 0.891,
+            "descent": -0.216
+          },
+          "hasEOL": false
         }
       ],
       "images": [
@@ -340,3 +351,14 @@ interface PDFExtractImage {
 ```
 
 Note: The `images` and `attachments` arrays are optional and only included when they are detected in the PDF. 
+
+## Limitations
+
+### Font Color
+
+Font color extraction is enabled by setting `includeColors: true`.
+The `font.color` value is extracted with best effort by correlating the rendering operator list with the text content items using position matching.
+When pdf.js merges adjacent text runs with different colors into a single content item (e.g. differently colored words on the same line), 
+only the first color is reported.
+This is an inherent limitation of how pdf.js combines text during extraction and cannot be resolved without upstream changes to pdf.js.
+

lib/extraction/annotations.mjs

@@ -1,8 +1,17 @@
 import { Buffer } from 'node:buffer';
 import { compactObj } from "../utils.mjs";
 
+const toHexColor = (arr) => {
+	if (!arr || !Array.isArray(arr) || arr.length < 3) return arr;
+	return '#' + arr.slice(0, 3).map(c => (c | 0).toString(16).padStart(2, '0')).join('');
+};
+
 const getPageAnnotation = (viewport, annot) => {
 	const result = compactObj(annot);
+	if (result.color) result.color = toHexColor(result.color);
+	if (result.backgroundColor) result.backgroundColor = toHexColor(result.backgroundColor);
+	if (result.borderColor) result.borderColor = toHexColor(result.borderColor);
+	if (result.defaultAppearanceData?.fontColor) result.defaultAppearanceData.fontColor = toHexColor(result.defaultAppearanceData.fontColor);
 	if (annot.rect) {
 		if (viewport.rotation === 90) {
 			result.x = annot.rect[3];

lib/extraction/content.mjs

@@ -1,8 +1,108 @@
-import { Util } from "../pdfjs/pdf.mjs";
+import { OPS, Util } from "../pdfjs/pdf.mjs";
 
 const normalizeTransform = transform => transform.map(v => v === 0 ? 0 : v);
 
-const getPageTextItem = (page, viewport, item, content) => {
+const translateMatrix = (m, tx, ty) => [m[0], m[1], m[2], m[3], m[0] * tx + m[2] * ty + m[4], m[1] * tx + m[3] * ty + m[5]];
+
+async function extractTextFillColors(page) {
+	const operatorList = await page.getOperatorList();
+	const { fnArray, argsArray } = operatorList;
+	let fillColor = "#000000";
+	let ctm = [1, 0, 0, 1, 0, 0];
+	let textMatrix = [1, 0, 0, 1, 0, 0];
+	let textLineMatrix = [1, 0, 0, 1, 0, 0];
+	let fontSize = 0;
+	let leading = 0;
+	const saveStack = [];
+	const colorEntries = [];
+	for (let i = 0; i < fnArray.length; i++) {
+		const args = argsArray[i];
+		switch (fnArray[i]) {
+			case OPS.save:
+				saveStack.push({ ctm, fillColor, textMatrix, textLineMatrix, fontSize, leading });
+				break;
+			case OPS.restore:
+				if (saveStack.length > 0) {
+					({ ctm, fillColor, textMatrix, textLineMatrix, fontSize, leading } = saveStack.pop());
+				}
+				break;
+			case OPS.transform:
+				ctm = Util.transform(ctm, args);
+				break;
+			case OPS.paintFormXObjectBegin:
+				saveStack.push({ ctm, fillColor, textMatrix, textLineMatrix, fontSize, leading });
+				if (args[0]) {
+					ctm = Util.transform(ctm, args[0]);
+				}
+				break;
+			case OPS.paintFormXObjectEnd:
+				if (saveStack.length > 0) {
+					({ ctm, fillColor, textMatrix, textLineMatrix, fontSize, leading } = saveStack.pop());
+				}
+				break;
+			case OPS.setFillRGBColor:
+				fillColor = args[0];
+				break;
+			case OPS.setFillTransparent:
+				fillColor = undefined;
+				break;
+			case OPS.beginText:
+				textMatrix = [1, 0, 0, 1, 0, 0];
+				textLineMatrix = [1, 0, 0, 1, 0, 0];
+				break;
+			case OPS.setTextMatrix: {
+				const m = args[0];
+				textMatrix = [m[0], m[1], m[2], m[3], m[4], m[5]];
+				textLineMatrix = textMatrix.slice();
+				break;
+			}
+			case OPS.moveText:
+				textLineMatrix = translateMatrix(textLineMatrix, args[0], args[1]);
+				textMatrix = textLineMatrix.slice();
+				break;
+			case OPS.setLeadingMoveText:
+				leading = -args[1];
+				textLineMatrix = translateMatrix(textLineMatrix, args[0], args[1]);
+				textMatrix = textLineMatrix.slice();
+				break;
+			case OPS.nextLine:
+				textLineMatrix = translateMatrix(textLineMatrix, 0, -leading);
+				textMatrix = textLineMatrix.slice();
+				break;
+			case OPS.setFont:
+				fontSize = args[1];
+				break;
+			case OPS.setLeading:
+				leading = args[0];
+				break;
+			case OPS.showText: {
+				const tsm = [fontSize, 0, 0, fontSize, 0, 0];
+				const pos = Util.transform(ctm, Util.transform(textMatrix, tsm));
+				colorEntries.push({ x: pos[4], y: pos[5], color: fillColor });
+				break;
+			}
+		}
+	}
+	return colorEntries;
+}
+
+function findFillColor(colorEntries, searchStart, itemX, itemY) {
+	for (let i = searchStart; i < colorEntries.length; i++) {
+		const entry = colorEntries[i];
+		if (Math.abs(entry.x - itemX) < 5 && Math.abs(entry.y - itemY) < 5) {
+			let nextIdx = i + 1;
+			while (nextIdx < colorEntries.length &&
+				Math.abs(colorEntries[nextIdx].x - itemX) < 5 &&
+				Math.abs(colorEntries[nextIdx].y - itemY) < 5) {
+				nextIdx++;
+			}
+			return { color: entry.color, nextIdx };
+		}
+	}
+	return null;
+}
+
+const getPageTextItem = (page, viewport, item, content, fillColor) => {
 	const tx = Util.transform(viewport.transform, item.transform);
 	const style = content.styles[item.fontName] ?? {};
 	const fontSize = Math.sqrt(tx[2] * tx[2] + tx[3] * tx[3]);
@@ -19,6 +119,7 @@ const getPageTextItem = (page, viewport, item, content) => {
 			size: fontSize,
 			name: font?.name,
 			family: style.fontFamily,
+			color: fillColor,
 			vertical: style.vertical,
 			ascent: isNaN(style.ascent) || style.ascent === null ? undefined : style.ascent,
 			descent: isNaN(style.descent) || style.descent === null ? undefined : style.descent
@@ -28,10 +129,27 @@ const getPageTextItem = (page, viewport, item, content) => {
 	};
 };
 
-export async function getPageContent(page, textExtractOptions) {
+export async function getPageContent(page, textExtractOptions, includeColors) {
 	const viewport = page.getViewport({ scale: 1.0 });
-	const content = await page.getTextContent(textExtractOptions);
-	return content.items
-	.map(item => getPageTextItem(page, viewport, item, content));
+	if (!includeColors) {
+		const content = await page.getTextContent(textExtractOptions);
+		return content.items.map(item => getPageTextItem(page, viewport, item, content));
+	}
+	const [content, colorEntries] = await Promise.all([
+		page.getTextContent(textExtractOptions),
+		extractTextFillColors(page)
+	]);
+	let entryIdx = 0;
+	let lastColor = colorEntries[0]?.color ?? "#000000";
+	return content.items.map(item => {
+		if (item.str && item.str.trim()) {
+			const result = findFillColor(colorEntries, entryIdx, item.transform[4], item.transform[5]);
+			if (result) {
+				lastColor = result.color;
+				entryIdx = result.nextIdx;
+			}
+		}
+		return getPageTextItem(page, viewport, item, content, lastColor);
+	});
 }
 

lib/index.d.ts

@@ -35,6 +35,7 @@ declare module "pdf.js-extract" {
     disableCombineTextItems?: boolean; // do not attempt to combine  same line {@link TextItem}'s. The default value is `false`.
     includeAttachments?: boolean; // include attachments as base64. The default value is `false`.
     includeImages?: boolean; // include images as base64. The default value is `false`.
+    includeColors?: boolean; // include font color in text content items. The default value is `false`.
   }
 
   export interface PDFExtractResult {
@@ -133,6 +134,7 @@ declare module "pdf.js-extract" {
     name: string;
     family: string;
     size: number;
+    color?: string;
     vertical?: boolean;
     ascent?: number;
     descent?: number;
@@ -333,7 +335,7 @@ declare module "pdf.js-extract" {
   export interface PDFExtractAnnotDefaultAppearanceData {
     fontSize: number;
     fontName: string;
-    fontColor?: Uint8ClampedArray;
+    fontColor?: string;
   }
 
   export const enum PDFExtractAnnotFieldFlag {
@@ -384,10 +386,10 @@ declare module "pdf.js-extract" {
     x?: number;
     y?: number;
     annotationFlags: PDFExtractAnnotFlag;
-    color?: Uint8ClampedArray;
-    backgroundColor?: Uint8ClampedArray;
+    color?: string;
+    backgroundColor?: string;
     borderStyle: PDFExtractAnnotBorderStyle;
-    borderColor?: Uint8ClampedArray;
+    borderColor?: string;
     rotation: number;
     contentsObj: PDFExtractBidiText;
     richText?: PDFExtractAnnotRichText;

lib/index.mjs

@@ -119,7 +119,7 @@ class PDFExtract {
 			await page.getOperatorList();
 			const resultPage = {
 				info: getPageInfo(pageNum, page),
-				content: await getPageContent(page, textExtractOptions)
+				content: await getPageContent(page, textExtractOptions, options.includeColors === true)
 			};
 			const annotations = await getPageAnnotations(page);
 			if (annotations) {