sigdetect 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

sigdetect/detector/pypdf2_engine.py

@@ -212,7 +212,9 @@ class PyPDF2Detector(Detector):
                 hits.add(f"VendorText:{rx.pattern}")
         return hits
 
-    def _ScanPageVendors(self, page) -> set[str]:
+    def _ScanPageVendors(self, page) -> tuple[set[str], str]:
+        """Return vendor hits along with the extracted page text."""
+
         found: set[str] = set()
 
         with _QuietIo():
@@ -234,7 +236,7 @@ class PyPDF2Detector(Detector):
             if rx.search(txt):
                 found.add(f"VendorText:{rx.pattern}")
 
-        return found
+        return found, txt
 
     def _IterateFormXObjects(self, page) -> Iterator[generic.DictionaryObject]:
         """Yield Form XObject dictionaries recursively from page resources."""
@@ -438,6 +440,40 @@ class PyPDF2Detector(Detector):
         nm = GetFieldNameFromAncestry(wdict)
         return "" if nm is None else str(nm)
 
+    def _WidgetBoundingBox(
+        self, wdict: generic.DictionaryObject
+    ) -> tuple[float, float, float, float] | None:
+        """Return the widget's ``/Rect`` coordinates normalized as (x0, y0, x1, y1)."""
+
+        rect = self._RectToTuple(wdict.get("/Rect"))
+        if rect:
+            return rect
+        parent = AsDictionary(wdict.get("/Parent"))
+        if isinstance(parent, generic.DictionaryObject):
+            return self._RectToTuple(parent.get("/Rect"))
+        return None
+
+    def _RectToTuple(self, candidate) -> tuple[float, float, float, float] | None:
+        if candidate is None:
+            return None
+        if isinstance(candidate, generic.IndirectObject):
+            with suppress(Exception):
+                candidate = candidate.get_object()
+        if isinstance(candidate, generic.ArrayObject) and len(candidate) == 4:
+            coords: list[float] = []
+            for item in candidate:
+                try:
+                    coords.append(float(item))
+                except Exception:
+                    return None
+            x0, y0, x1, y1 = coords
+            if x1 < x0:
+                x0, x1 = x1, x0
+            if y1 < y0:
+                y0, y1 = y1, y0
+            return x0, y0, x1, y1
+        return None
+
     @staticmethod
     def _PickNameAny(d: generic.DictionaryObject) -> str | None:
         for key in ("/T", "/TU", "/TM"):
@@ -685,7 +721,7 @@ class PyPDF2Detector(Detector):
 
             for page in reader.pages:
                 # per-page vendor
-                pv = self._ScanPageVendors(page)
+                pv, page_text = self._ScanPageVendors(page)
                 x_hits: set[str] = set()
                 x_text = ""
                 if self.RecurseXObjects:
@@ -693,12 +729,10 @@ class PyPDF2Detector(Detector):
                 vendor_hints |= pv | x_hits
                 vendor_hits_per_page.append(len(pv) + len(x_hits))
 
-                with _QuietIo():
-                    txt = page.extract_text() or ""
                 if x_text:
-                    txt = f"{txt} {x_text}".strip() if txt else x_text.strip()
-                page_texts.append(txt)
-                any_text = any_text or bool(txt)
+                    page_text = f"{page_text} {x_text}".strip() if page_text else x_text.strip()
+                page_texts.append(page_text)
+                any_text = any_text or bool(page_text)
 
                 # image counting
                 img_count = 0
@@ -760,6 +794,7 @@ class PyPDF2Detector(Detector):
                     field_name = self._FieldNameForWidget(wdict)
                     page_obj = reader.pages[idx - 1] if 0 <= (idx - 1) < len(reader.pages) else None
                     render_type = self._ClassifyAppearance(wdict, page_obj)
+                    bounding_box = self._WidgetBoundingBox(wdict)
 
                     # de-dup by object ref (if present) and (page, name)
                     if isinstance(ref, generic.IndirectObject):
@@ -801,6 +836,7 @@ class PyPDF2Detector(Detector):
                             Evidence=evidence,
                             Hint=(f"AcroSig:{field_name}" if field_name else "AcroSig"),
                             RenderType=render_type,
+                            BoundingBox=bounding_box,
                         )
                     )
 
@@ -969,6 +1005,7 @@ class PyPDF2Detector(Detector):
                 field_name = self._FieldNameForWidget(wdict)
                 page_obj = reader.pages[idx - 1] if 0 <= (idx - 1) < len(reader.pages) else None
                 render_type = self._ClassifyAppearance(wdict, page_obj)
+                bounding_box = self._WidgetBoundingBox(wdict)
 
                 # de-dup by object ref (if present) and (page, name)
                 if isinstance(ref, generic.IndirectObject):
@@ -995,6 +1032,7 @@ class PyPDF2Detector(Detector):
                         Evidence=evidence,
                         Hint=(f"AcroSig:{field_name}" if field_name else "AcroSig"),
                         RenderType=render_type,
+                        BoundingBox=bounding_box,
                     )
                 )
 

sigdetect/detector/signature_model.py

@@ -18,6 +18,8 @@ class Signature:
     Evidence: list[str]
     Hint: str
     RenderType: str = "unknown"
+    BoundingBox: tuple[float, float, float, float] | None = None
+    CropPath: str | None = None
 
     def to_dict(self) -> dict[str, Any]:
         """Return the legacy snake_case representation used in JSON payloads."""
@@ -31,4 +33,6 @@ class Signature:
             "evidence": list(self.Evidence),
             "hint": self.Hint,
             "render_type": self.RenderType,
+            "bounding_box": list(self.BoundingBox) if self.BoundingBox else None,
+            "crop_path": self.CropPath,
         }

{sigdetect-0.1.1.dist-info → sigdetect-0.3.0.dist-info}/METADATA

@@ -1,13 +1,12 @@
 Metadata-Version: 2.4
 Name: sigdetect
-Version: 0.1.1
+Version: 0.3.0
 Summary: Signature detection and role attribution for PDFs
 Author-email: BT Asmamaw <basmamaw@angeiongroup.com>
 License: MIT
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: pypdf>=4.0.0
-Requires-Dist: pandas>=2.0
 Requires-Dist: rich>=13.0
 Requires-Dist: typer>=0.12
 Requires-Dist: pydantic>=2.5
@@ -102,6 +101,8 @@ sigdetect detect \
 - `--profile` selects tuned role logic:
   - `hipaa` → patient / representative / attorney
   - `retainer` → client / firm (prefers detecting two signatures)
+- `--recursive/--no-recursive` toggles whether `sigdetect detect` descends into subdirectories when hunting for PDFs (recursive by default).
+- `--crop-signatures` enables PNG crops for each detected widget (requires installing the optional `pymupdf` dependency). Use `--crop-dir` to override the destination and `--crop-dpi` to choose rendering quality.
 - If the executable is not on `PATH`, you can always fall back to `python -m sigdetect.cli ...`.
 
 ### EDA (quick aggregate stats)
@@ -135,7 +136,7 @@ result = detector.Detect(Path("/path/to/pdfs/example.pdf"))
 print(result.to_dict())
 ~~~
 
-`Detect(Path)` returns a **FileResult** dataclass; call `.to_dict()` for the JSON-friendly representation (see [Result schema](#result-schema)).
+`Detect(Path)` returns a **FileResult** dataclass; call `.to_dict()` for the JSON-friendly representation (see [Result schema](#result-schema)). Each signature entry now exposes `bounding_box` coordinates (PDF points, origin bottom-left). When PNG cropping is enabled, `crop_path` points at the generated image.
 
 ---
 
@@ -146,7 +147,17 @@ Import from `sigdetect.api` and get plain dicts out (JSON-ready),
 with no I/O side effects by default:
 
 ~~~python
-from sigdetect.api import DetectPdf, DetectMany, ScanDirectory, ToCsvRow, Version
+from pathlib import Path
+
+from sigdetect.api import (
+    CropSignatureImages,
+    DetectMany,
+    DetectPdf,
+    ScanDirectory,
+    ToCsvRow,
+    Version,
+    get_detector,
+)
 
 print("sigdetect", Version())
 
@@ -178,8 +189,24 @@ for res in ScanDirectory(
     # store in DB, print, etc.
     pass
 
+# 3) Crop PNG snippets for FileResult objects (requires PyMuPDF)
+detector = get_detector(pdfRoot="/path/to/pdfs", profileName="hipaa")
+file_result = detector.Detect(Path("/path/to/pdfs/example.pdf"))
+crops = CropSignatureImages(
+    "/path/to/pdfs/example.pdf",
+    file_result,
+    outputDirectory="./signature_crops",
+    dpi=200,
+    returnBytes=True,  # also returns in-memory PNG bytes for each crop
+)
+
+first_crop = crops[0]
+print(first_crop.path, len(first_crop.image_bytes))
 ~~~
 
+When ``returnBytes=True`` the helper returns ``SignatureCrop`` objects containing the saved path,
+PNG bytes, and the originating signature metadata.
+
 
 ## Result schema
 
@@ -205,7 +232,10 @@ High-level summary (per file):
       "score": 5,
       "scores": { "field": 3, "page_label": 2 },
       "evidence": ["field:patient", "page_label:patient"],
-      "hint": "AcroSig:sig_patient"
+      "hint": "AcroSig:sig_patient",
+      "render_type": "typed",
+      "bounding_box": [10.0, 10.0, 150.0, 40.0],
+      "crop_path": "signature_crops/example/sig_01_patient.png"
     },
     {
       "page": null,
@@ -214,7 +244,10 @@ High-level summary (per file):
       "score": 6,
       "scores": { "page_label": 4, "general": 2 },
       "evidence": ["page_label:representative(parent/guardian)", "pseudo:true"],
-      "hint": "VendorOrAcroOnly"
+      "hint": "VendorOrAcroOnly",
+      "render_type": "unknown",
+      "bounding_box": null,
+      "crop_path": null
     }
   ]
 }
@@ -227,6 +260,8 @@ High-level summary (per file):
 - **`mixed`** means both `esign_found` and `scanned_pdf` are `true`.  
 - **`roles`** summarizes unique non-`unknown` roles across signatures.
 - In retainer profile, emitter prefers two signatures (client + firm), often on the same page.
+- **`signatures[].bounding_box`** reports the widget rectangle in PDF points (origin bottom-left).  
+- **`signatures[].crop_path`** is populated when PNG crops are generated (via CLI `--crop-signatures` or `CropSignatureImages`).
 
 ---
 
@@ -252,6 +287,9 @@ engine: pypdf2
 pseudo_signatures: true
 recurse_xobjects: true
 profile: retainer    # or: hipaa
+crop_signatures: false   # enable to write PNG crops (requires pymupdf)
+# crop_output_dir: ./signature_crops
+crop_image_dpi: 200
 ~~~
 
 YAML files can be customized or load at runtime (see CLI `--config`, if available, or import and pass patterns into engine).

{sigdetect-0.1.1.dist-info → sigdetect-0.3.0.dist-info}/RECORD

@@ -1,7 +1,8 @@
 sigdetect/__init__.py,sha256=LhY78mDZ1ClYVNTxW_qtE-vqJoN9N7N5ZcNRDUI_3ss,575
-sigdetect/api.py,sha256=Un4SaZHNAmRLPh1aF9bzOfT6ibilT_y9C0xVmNlqHtI,4248
-sigdetect/cli.py,sha256=jm7aStuv64MCcZZkzv8ncNVGGg8FYIFKjkTPNfXWUgs,3136
-sigdetect/config.py,sha256=d3_AlAEFUHBoXyTbUAHQLTARVqM8q4I8q4xfwakPE0M,4165
+sigdetect/api.py,sha256=jIUaq6nslDdluNlRoDSdaX3Dx1lkIIZmIJPHn8Nk2Ko,9192
+sigdetect/cli.py,sha256=NctAnaB-TQrUAT9m-v8kj2_KTNs88kbFOCiX32tHZm8,7920
+sigdetect/config.py,sha256=S0NVKuJYiHJCocL-VNFdGJpasFcjTecavC4EthyS1DQ,5951
+sigdetect/cropping.py,sha256=IyIcQAPH3z58tS6yeplglMDNu9F-iyQtpYQ1Ya2X_8o,5602
 sigdetect/eda.py,sha256=S92G1Gjmepri__D0n_V6foq0lQgH-RXI9anW8A58jfw,4681
 sigdetect/logging_setup.py,sha256=LMF8ao_a-JwH0S522T6aYTFX3e8Ajjv_5ODS2YiBcHA,6404
 sigdetect/utils.py,sha256=T9rubLf5T9JmjOHYMOba1j34fhOJaWocAXccnGTxRUE,5198
@@ -12,11 +13,11 @@ sigdetect/detector/__init__.py,sha256=up2FCmD09f2bRHcS4WbY-clx3GQbWuk1PM2JlxgusH
 sigdetect/detector/base.py,sha256=L-iXWXqsTetDc4jRZo_wOdbNpKqOY20mX9FefrugdT0,263
 sigdetect/detector/base_detector.py,sha256=GmAgUWO_fQgIfnihZSoyhR3wpnwZ-X3hS0Kuyz4G6Ys,608
 sigdetect/detector/file_result_model.py,sha256=j2gTc9Sw3fJOHlexYsR_m5DiwHA8DzIzAMToESfvo4A,1767
-sigdetect/detector/pymupdf_engine.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sigdetect/detector/pypdf2_engine.py,sha256=e3JasLxI8K10IkpMcijES2EjA7RluNpKq6027oNROPU,45770
-sigdetect/detector/signature_model.py,sha256=nApd53aDRMZhOLdUlmoEPjHO1hs8leM6NysG10v-jVc,857
-sigdetect-0.1.1.dist-info/METADATA,sha256=JvjfOiez4frYSsTjPxC55meRQW4qUGAUCyKuBxjULA0,10363
-sigdetect-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-sigdetect-0.1.1.dist-info/entry_points.txt,sha256=iqtfKjBU44-omM7Sh-idGz2ahw19oAvpvSyKZVArG3o,48
-sigdetect-0.1.1.dist-info/top_level.txt,sha256=PKlfwUobkRC0viwiSXmhtw83G26FSNpimWYC1Uy00FY,10
-sigdetect-0.1.1.dist-info/RECORD,,
+sigdetect/detector/pymupdf_engine.py,sha256=iyp7JuPlUnydwohH5zbNg4MwH44mBmxbBWOS3ZmArBo,17339
+sigdetect/detector/pypdf2_engine.py,sha256=INWQH06kMLvto2VS-EdLC-EtMC6AG7JmdVYmNgx6_RU,47313
+sigdetect/detector/signature_model.py,sha256=mztb9V5wgv2oohQ5Cxzcv8_Bo6TyWAVIXteaeQ2rywQ,1076
+sigdetect-0.3.0.dist-info/METADATA,sha256=i7rSqbNbViLWyNJFO5si0eghcM01mBdkLrFsVND7xZw,12171
+sigdetect-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+sigdetect-0.3.0.dist-info/entry_points.txt,sha256=iqtfKjBU44-omM7Sh-idGz2ahw19oAvpvSyKZVArG3o,48
+sigdetect-0.3.0.dist-info/top_level.txt,sha256=PKlfwUobkRC0viwiSXmhtw83G26FSNpimWYC1Uy00FY,10
+sigdetect-0.3.0.dist-info/RECORD,,