pdf-editing

# PDF Editing Skill ## CRITICAL RULES - READ FIRST **NEVER DO THESE:** - NEVER use strikethrough lines to cross out text - NEVER rasterize or flatten the PDF to images - NEVER convert PDF pages to PNG/JPG and draw on them - NEVER use pdf-to-image-to-pdf workflows - NEVER use add_redact_annot() with BLACK fill (use WHITE fill instead) - NEVER add text NEXT TO old values - REPLACE them at the SAME position **TWO APPROACHES - CHOOSE THE RIGHT ONE:** 1. **For REPLACING text** (e.g., updating name, email, DOB): - Use `draw_rect()` with white fill to cover old text - Use `insert_text()` at the SAME position - Text layer is preserved 2. **For TRUE REDACTION of sensitive data** (e.g., student ID): - Use `add_redact_annot(rect, fill=(1,1,1))` with WHITE fill - Call `apply_redactions()` to REMOVE text from PDF structure - Then `insert_text()` to add masked value (e.g., "****5678") - Original text is completely removed, not just covered ## Overview **USE PYTHON WITH PyMuPDF (fitz)** - it is pre-installed and produces the best results. PyMuPDF preserves the text layer properly, making text extractable after editing. JavaScript libraries like pdf-lib may create text that tools like pypdf cannot extract. ```bash # PyMuPDF is already installed - just use it python3 -c "import fitz; print('PyMuPDF ready')" ``` ## Reading PDF Content ```python import fitz doc = fitz.open("input.pdf") page = doc[0] # Extract all text to understand the document text = page.get_text() print(text) ``` ## Finding Text Positions ```python # search_for() returns list of rectangles where text is found rects = page.search_for("Label Text") if rects: rect = rects[0] # rect.x0, rect.y0 = top-left corner # rect.x1, rect.y1 = bottom-right corner print(f"Found at: ({rect.x0}, {rect.y0}) to ({rect.x1}, {rect.y1})") ``` ## Inserting Text ```python # Insert text at a specific position page.insert_text( (x_position, y_position), # coordinates "text to insert", fontsize=11, color=(0, 0, 0) # black ) doc.save("output.pdf") ``` ## Common Pattern: Fill Empty Form Fields When a form field is empty (no existing value), insert text next to the label: ```python import fitz doc = fitz.open("input.pdf") page = doc[0] # Find label, insert value to the right of it label_rect = page.search_for("FIELD LABEL:")[0] page.insert_text((label_rect.x1 + 5, label_rect.y1), "value", fontsize=11) # For today's date from datetime import datetime date_rect = page.search_for("Date")[0] today = datetime.now().strftime("%Y/%m/%d") page.insert_text((date_rect.x1 + 5, date_rect.y1), today, fontsize=11) # For signatures - insert the person's name sig_rect = page.search_for("signature")[0] page.insert_text((sig_rect.x1 + 5, sig_rect.y1), "Full Name", fontsize=12) doc.save("output.pdf") ``` ## Replacing Existing Text (CRITICAL - MUST FOLLOW) When you need to replace text that's already in the PDF with new/correct values: 1. First extract the PDF text to see what's currently there 2. Compare with the correct values from your input source 3. For any value that needs to change: **COVER with white rectangle, then insert new text AT THE SAME POSITION** ### WRONG vs RIGHT approaches: **WRONG - DO NOT DO THIS:** ```python # WRONG: Adding text next to old value page.insert_text((old_rect.x1 + 10, old_rect.y1), new_value) # NO! # WRONG: Using strikethrough page.draw_line(start, end, color=(0,0,0)) # NO! # WRONG: Rasterizing to image pix = page.get_pixmap() # NO! Destroys text layer ``` **RIGHT - DO THIS:** ```python import fitz doc = fitz.open("input.pdf") page = doc[0] # First, extract text to see what's in the PDF current_text = page.get_text() print(current_text) # Examine what values exist # To replace a value you found that needs changing: old_value = "..." # The value you found in the PDF that's wrong new_value = "..." # The correct value from your input source rects = page.search_for(old_value) if rects: rect = rects[0] # STEP 1: Draw WHITE rectangle to COMPLETELY COVER old text page.draw_rect(rect, color=(1, 1, 1), fill=(1, 1, 1), width=0) # STEP 2: Insert new text at the SAME position (not offset!) page.insert_text((rect.x0, rect.y1), new_value, fontsize=11, color=(0, 0, 0)) doc.save("output.pdf") ``` **Key points:** - `draw_rect(rect, fill=(1,1,1), width=0)` draws a WHITE filled rectangle - `(1, 1, 1)` is white in RGB (0-1 scale) - Insert new text at `rect.x0` (same X position), NOT `rect.x1 + offset` - The old text becomes invisible under the white rectangle - The new text appears in the same location - Text layer is preserved (text remains extractable) ## TRUE REDACTION for Sensitive Data (IMPORTANT!) For sensitive data like student IDs, you must use TRUE REDACTION that removes the original text from the PDF structure. A white rectangle only VISUALLY covers text - tools like pypdf can still extract the hidden text! **CRITICAL DISTINCTION:** - `draw_rect()` = Visual cover only (text still extractable by machines) - `add_redact_annot()` + `apply_redactions()` = TRUE redaction (text removed from PDF) **Example:** "A12345678" should become "****5678" (show only last 4 digits) ```python import fitz doc = fitz.open("input.pdf") page = doc[0] # 1. First find what value is in the PDF by reading the text pdf_text = page.get_text() # Find the ID in the text (e.g., "A88888888") original_in_pdf = "A88888888" # Value you found in the PDF # Extract just the digits for masking digits = ''.join(c for c in original_in_pdf if c.isdigit()) masked = "****" + digits[-4:] # Result: "****8888" rects = page.search_for(original_in_pdf) if rects: rect = rects[0] # STEP 1: Create TIGHT bounding box to avoid covering nearby labels tight_rect = fitz.Rect(rect.x0, rect.y0 + 8, rect.x1, rect.y1 - 2) # STEP 2: Add redaction annotation with WHITE fill (not black!) page.add_redact_annot(tight_rect, fill=(1, 1, 1)) # WHITE fill # STEP 2: Apply redactions - this REMOVES the text from PDF structure page.apply_redactions() # STEP 3: Insert masked value at the same position page.insert_text((rect.x0, rect.y1), masked, fontsize=11, color=(0, 0, 0)) doc.save("output.pdf") ``` **Why this works:** - `add_redact_annot(rect, fill=(1, 1, 1))` - marks area with WHITE rectangle - `apply_redactions()` - REMOVES the underlying text from PDF structure - `insert_text()` - adds the masked value **WRONG approaches:** ```python # WRONG: Black box redaction (ugly and suspicious) page.add_redact_annot(rect, fill=(0, 0, 0)) # NO! Use white fill # WRONG: Only using draw_rect (text still extractable!) page.draw_rect(rect, fill=(1, 1, 1)) # NO! This only covers visually page.insert_text(...) # Original text is still in PDF structure! # WRONG: Adding masked value NEXT TO original page.insert_text((rect.x1 + 10, rect.y1), masked) # NO! ``` ## Workflow: Compare and Update ```python import fitz doc = fitz.open("input.pdf") page = doc[0] # Step 1: Read PDF to see current content pdf_text = page.get_text() print(pdf_text) # Step 2: Read your input source to get correct values # (parse input file, extract the values you need) # Step 3: For each value that differs, replace it # Build a dict of {old_value_in_pdf: correct_value} replacements = {} # Populate by comparing PDF content with correct values for old_val, new_val in replacements.items(): if old_val == new_val: continue # Skip if already correct rects = page.search_for(old_val) if rects: rect = rects[0] # Cover old text with white rectangle page.draw_rect(rect, color=(1, 1, 1), fill=(1, 1, 1), width=0) # Insert new text page.insert_text((rect.x0, rect.y1), new_val, fontsize=11, color=(0, 0, 0)) doc.save("output.pdf") ``` ## Important Guidelines 1. **COVER then REPLACE** - Use white rectangle to cover old text, insert new text at SAME position 2. **Never use strikethrough** - No lines through text, no crossing out 3. **Never rasterize** - No converting PDF to images, no get_pixmap() workflows 4. **Never add text NEXT TO old values** - Replace AT the same position 5. **Never use add_redact_annot() with black** - It creates black boxes 6. **Preserve all labels** - Form labels should remain visible 7. **Preserve text layer** - Text must remain extractable after editing 8. **Match font size** - Typically 10-12pt for forms ## Alternative: JavaScript with pdf-lib (NOT RECOMMENDED) **WARNING:** pdf-lib may create text that cannot be extracted by pypdf. Use Python with PyMuPDF instead whenever possible. If you must use Node.js/JavaScript, use pdf-lib with the same approach: ```javascript const { PDFDocument, rgb } = require('pdf-lib'); const fs = require('fs'); async function editPdf() { const pdfBytes = fs.readFileSync('input.pdf'); const pdfDoc = await PDFDocument.load(pdfBytes); const page = pdfDoc.getPages()[0]; const { height } = page.getSize(); // To replace text at known coordinates: // STEP 1: Draw WHITE rectangle to cover old text page.drawRectangle({ x: oldTextX, y: oldTextY, width: oldTextWidth, height: oldTextHeight, color: rgb(1, 1, 1), // WHITE }); // STEP 2: Draw new text at the SAME position page.drawText('New Value', { x: oldTextX, // SAME X position, not offset! y: oldTextY, size: 11, color: rgb(0, 0, 0), }); fs.writeFileSync('output.pdf', await pdfDoc.save()); } ``` **WRONG with pdf-lib:** ```javascript // WRONG: Adding text to the right of old value page.drawText('New Value', { x: oldTextX + oldTextWidth + 10, // NO! Don't offset ... }); // WRONG: Drawing strikethrough line page.drawLine({ start: { x: x1, y: y }, end: { x: x2, y: y }, color: rgb(0, 0, 0), // NO strikethrough! }); ```