/j-jox%SrSSKJr SSKrSSKJr SSKJr SSKJr SSK J r SS K J r SS K J r SS K J r SS K Jr S SKJr SrSrSrSrSrSrSr\"SS55r\"SS55rSrSrSrSrS\4SjrSrS r \"S!S"55r!0r"S#\#S$'/r$S%\#S&'"S'S(5r%"S)S*\5r&g)+uImplementation of the ML (Table Transformer) table parser. The ``flavor='ml'`` backend follows one rule: **the model supplies the structure, the PDF supplies the text.** A neural table-structure model (Microsoft's Table Transformer / TATR, loaded from HuggingFace) is run on the rendered page to detect rows, columns and spanning cells *as boxes*. Those boxes are turned into the same column/row/spanning grid the heuristic parsers build, and every cell's text is then filled from the PDF's own text layer via :func:`get_table_index` — exactly like the other flavors. The model never emits a single character of cell text, so it cannot hallucinate or alter a value; OCR-grade substitution errors are impossible because no recognition of glyphs happens here at all. The heavy dependencies (``torch`` / ``transformers`` / ``timm``) are optional and imported lazily — install them with ``pip install 'camelot-py[ml]'``. The box-to-grid post-processing and the image→PDF coordinate mapping are pure functions (no torch), so they are unit-tested without the models present. Text source seam ---------------- Cell text comes from :meth:`MachineLearning._text_source`, which today returns the born-digital PDF text layer. The structure half already runs on the page *image*, so a future OCR text source (scanned / image-only PDFs) only has to provide ``{text fragments with bboxes}`` to the same fill path — see the roadmap in the ``[ml]`` tier task. ) annotationsN) dataclass)field)ImageConversionBackend) bbox_from_str)scale) scale_pdf)text_in_bbox_per_axis) translate) BaseParserz table rowz table columnztable spanning cellz:microsoft/table-transformer-structure-recognition-v1.1-allz%microsoft/table-transformer-detectiong@?c8\rSrSr%SrS\S'S\S'S\S'S rg ) DetectedObject?aOne box emitted by the structure model. Coordinates are in image-pixel space with a top-left origin (y grows downward), matching what ``transformers`` object-detection post-processing returns. Parameters ---------- label : str Class name, e.g. ``"table row"`` / ``"table column"``. score : float Detection confidence in ``[0, 1]``. bbox : tuple ``(x0, y0, x1, y1)`` in image pixels. strlabelfloatscorez!tuple[float, float, float, float]bboxN__name__ __module__ __qualname____firstlineno____doc____annotations____static_attributes__rO/home/mande/repo/quber/.venv/lib/python3.13/site-packages/camelot/parsers/ml.pyrr?s J L ++r!rc\\rSrSr%Sr\"\S9rS\S'\"\S9r S\S'\"\S9r S\S'S r g ) MLGridVa?A reconstructed table grid, in image-pixel space. Attributes ---------- col_bounds : list ``(x_left, x_right)`` per column, left-to-right. row_bounds : list ``(y_top, y_bottom)`` per row, top-to-bottom (image y grows down). spans : list ``(r0, c0, r1, c1)`` inclusive grid-index ranges for spanning cells. )default_factoryzlist[tuple[float, float]] col_bounds row_boundszlist[tuple[int, int, int, int]]spansrN) rrrrrrlistr'rr(r)r rr!r"r$r$Vs9 -2$,GJ)G,1$,GJ)G-24-HE *Hr!r$cD^^ US:XaSOSum m[UU 4SjU5SS9n/nUHrupVU(aTUSSUSS-S - n[XV-S - U- 5U::a)[USSU5[USSU54US'M`UR XV45 Mt U$) aaCollapse boxes to merged ``(lo, hi)`` intervals along one axis. Parameters ---------- boxes : list of DetectedObject axis : int ``0`` for the x-axis (columns), ``1`` for the y-axis (rows). tol : float Centre-distance under which adjacent intervals are merged. Returns ------- list of tuple Merged ``(lo, hi)`` intervals, sorted by centre. r)rr)r c3^># UH"oRTURT4v M$ g7fN)r).0bhi_ilo_is r" "_axis_intervals..{s$5u!&&,t %us*-cUSUS-S- $)Nrr @r)ts r"!_axis_intervals..|sqtad{c)r!)keyr r6)sortedabsminmaxappend) boxesaxistolrawmergedlohi prev_centrer1r2s @@r"_axis_intervalsrIis  19&JD$ 5u5 ) C)+F !":a=6":a=8C?KBGs?[01S8!&*Q-4c&*Q-6LMr  rh  Mr!cDU(d/$USS/n[[U5S- 5H'nURXSXS-S-S- 5 M) URUSS5 [[U5S- 5Vs/sHo!UXS-4PM sn$s snf)uTurn merged band intervals into gap-free, ordered cell bounds. Separators are placed at the midpoint of each adjacent gap; the outer edges keep the first/last interval's extent. The result tiles the axis with no gaps or overlaps — the shape :class:`camelot.core.Table` expects. rr r6r;)rangelenr@) intervalssepsis r"_bounds_from_intervalsrPs  aLO D 3y>A% & Y\!_yQ'7'::cAB'KK " a !,1#d)a-,@ A,@q!Wdq5k ",@ AA AsBcl[X5[X5peXe::agX- nUS:*=(d Xe- U- U:$)zCTrue if ``[b0, b1]`` covers at least ``frac`` of cell ``[a0, a1]``.Fr)r?r>)a0a1b0b1fracrFrGcells r"_interval_overlaprXs; [#b+ x 7D 19 0D(D00r!c /nUHnURupVpx[U5V V V s/sH"un up[XXW[5(dM U PM$ n n n n [U5V V V s/sH"un up[XXh[5(dM U PM$ n n n n U (aU (dM[ U 5[ U 5p[ U 5[ U 5nnX:dUU:dMUR UUUU45 M U$s sn n n fs sn n n f)uMap spanning boxes to inclusive ``(r0, c0, r1, c1)`` grid ranges. A spanning box that resolves to a single cell (covers one row and one column) is dropped — it adds no merge information. )r enumeraterX_SPAN_OVERLAP_FRACTIONr>r?r@)r)r'r(outssx0sy0sx1sy1rOar0cols_hitrows_hitr0r1c0c1s r"_spans_to_cellsris C VV#'z2 2 6A s1GH 2  'z2 2 6A s1GH 2  x XH BXH B 7b2g JJBB' (#$ J!  sC2 C2 "C9 C9 cUVs/sHo3RU:dMUPM nnUVs/sHo3R[:XdMUPM nnUVs/sHo3R[:XdMUPM nnUVs/sHo3R[:XdMUPM nnU(aU(d [ 5$[ [USU55n[ [USU55n [XxU 5n [ XU S9$s snfs snfs snfs snf)aReconstruct a table grid from structure-model detections (pure). Parameters ---------- objects : list of DetectedObject Row / column / spanning-cell boxes in image-pixel space. score_thresh : float, optional (default: 0.5) Drop detections below this confidence. merge_tol : float, optional Centre-distance under which duplicate row/column bands merge. Returns ------- MLGrid Column/row bounds (image space) and spanning-cell index ranges. Empty bounds mean no usable grid was found. rr )r'r(r)) rr LABEL_COLUMN LABEL_ROWLABEL_SPANNINGr$rPrIri) objects score_thresh merge_tolokeptcolsrowsr)r'r( span_cellss r"objects_to_gridrvs$ :w!''\"9AwD : 7t!ww,6AtD 7 4t!ww)3AtD 4 :1> 9QE : tx'a(KLJ'a(KLJ J?J Zj QQ ; 7 4 :s-C3C3C8C8C=*C=6DDc XUup#nURVVs/sHupV[XR5[Xb54PM nnn/nURHWup[[[ U*U 55U5n [[[ U*U 55U5n UR X45 MY Xx4$s snnf)u^Map an image-space grid to PDF-space ``cols`` / ``rows`` (pure). Mirrors :func:`camelot.utils.scale_image`'s per-coordinate transform, including the y-flip (image origin top-left → PDF origin bottom-left). Parameters ---------- grid : MLGrid pdf_scalers : tuple ``(pdf_width_scaler, pdf_height_scaler, image_height)`` — same shape Lattice builds for :func:`scale_image`. Returns ------- tuple ``(cols, rows)`` where ``cols`` is a list of ``(x_left, x_right)`` increasing and ``rows`` a list of ``(y_top, y_bottom)`` decreasing — the order :class:`camelot.core.Table` requires. )r'r r(r=r r@) grid pdf_scalerssxsyimg_hrgrhrsrttop_imgbot_imgy_topy_bottoms r"grid_to_pdf_cols_rowsrs( MBE9= IvrU2]E"M *D I D OOc)UFG45r:Yvw78"= U%&, : Js"B&cUHtup#pE[X$S-5H\n[X5S-5HGnURUUnXs:aSUlXu:aSUlXb:aSUlXd:dM@SUlMI M^ Mv g)uOpen interior edges of each span block so its cells merge (pure). Starts from a fully-edged grid (every cell bounded on all sides) and, for each spanning block, drops the edges *interior* to the block. A cell with an open interior edge reports ``hspan`` / ``vspan`` True, so text flows to the block's anchor cell via :meth:`MachineLearning._reduce_index` and ``copy_text`` works — the same spanning model Lattice uses. r FN)rKcellsleftrighttopbottom) tabler)rergrfrhrcrWs r" apply_spansrsz r6"A2Av&{{1~a(6 %DI6!&DJ6$DH6"'DK'# r!cL\rSrSr%SrS\S'S\S'S\S'S\S'S\S'S rg ) _LoadedModelsiz?Holds the lazily-imported torch handle and the two TATR models.objecttorch det_processor det_model str_processor str_modelrNrrr!r"rrs"I Mr!rz)dict[tuple[str, str, str], _LoadedModels] _MODEL_CACHEz list[object] _OCR_ENGINEc$\rSrSrSrSrSrSrg)_OCRWordi(aNA textline-like wrapper around one OCR word, in PDF coordinate space. Exposes just what :func:`camelot.utils.get_table_index` / :func:`text_in_bbox_per_axis` need (``x0/y0/y1/x1`` with a bottom-left origin and ``get_text``). ``split_text`` / ``flag_size`` are *not* supported through OCR (they need per-glyph data), so no ``_objs``. c@X lX0lX@lXPlXlgr.)x0y0x1y1_text)selftextrrrrs r"__init___OCRWord.__init__1s r!cUR$)z Return the recognised word text.)rrs r"get_text_OCRWord.get_text8s zzr!)rrrrrN)rrrrrrrr rr!r"rr(sr!rc^\rSrSrSrSSSSSSSS\\SSSSS S S S S4U4S jjrSr\ S5r Sr SSjr U4Sjr SrSrSrSrSrSrSrSrSr\ S5rSSjrSrU=r$) MachineLearningi=uF Neural table-structure parser (Table Transformer / TATR). The model detects table structure on the rendered page; cell text is filled from the PDF's text layer. Requires the optional ML dependencies (``pip install 'camelot-py[ml]'``). Parameters ---------- table_regions : list, optional (default: None) Page regions to restrict detection to, ``"x1,y1,x2,y2"`` in PDF coordinate space (left-top, right-bottom). table_areas : list, optional (default: None) Exact table areas, ``"x1,y1,x2,y2"`` in PDF coordinate space. When given, table *detection* is skipped and structure recognition runs directly on each area. copy_text : list, optional (default: None) ``{'h', 'v'}`` — directions to copy text across spanning cells. shift_text : list, optional (default: ['l', 't']) ``{'l', 'r', 't', 'b'}`` — direction text in a spanning cell flows. split_text : bool, optional (default: False) Split text that spans multiple cells. flag_size : bool, optional (default: False) Wrap font-size-flagged text in ````. strip_text : str, optional (default: '') Characters stripped from a cell before assignment. structure_model : str, optional HuggingFace checkpoint for structure recognition. detection_model : str, optional HuggingFace checkpoint for table detection. device : str, optional (default: 'cpu') Torch device, e.g. ``'cpu'`` or ``'cuda'``. detection_threshold : float, optional (default: 0.5) Score threshold for the detection model. structure_threshold : float, optional (default: 0.5) Score threshold for the structure model. crop_padding : int, optional (default: 10) Pixels of margin added around each detected table before structure recognition. TATR is trained on padded crops; the margin keeps the outermost rows/columns from being clipped. ocr : {'auto', True, False}, optional (default: 'auto') Where cell text comes from. ``'auto'`` uses the PDF's born-digital text layer when present and falls back to OCR on the rendered page when the page has none (scanned / image-only PDFs); ``True`` always OCRs; ``False`` never does. OCR needs the optional OCR dependencies (``pip install 'camelot-py[ocr]'``) and does not support ``split_text`` / ``flag_size`` (no per-glyph data). resolution : int, optional (default: 300) DPI for rendering the page to an image. NFcpur autoi,Tpdfiumc >[TU]SUUUUUUU=(d SS/UUS9 XlXlXlXlXlXlXlUUl [UUS9Ul SUl SUl SUlSUlSUlSUlg)Nmachine_learninglr7) table_regions table_areas copy_text split_text strip_text replace_text shift_text flag_sizedebug) use_fallbackbackend)superrstructure_modeldetection_modeldevicedetection_thresholdstructure_threshold crop_paddingocr resolutionricb_models _ocr_engine _image_rgb _ocr_cache _pdf_scalers_image_scalers)rrrrrrrrrrrrrrrrrrrrkwargs __class__s r"rMachineLearning.__init__ps.  '#!!%!/c3Z   /. #6 #6 ($)|WU-1 15?CAEr!cFURb UR$URURUR4n[R U5nUbX lUR$SSKnSSKJn SSKJ n URUR5nURUR5RUR5R5nURUR5n URUR5RUR5R5n URU5 URU 5 [X7XU 5UlUR[U'UR$![an[S5UeSnAff=f)zImport torch/transformers and build the two TATR models once. Raises ------ ImportError If the optional ML dependencies are not installed, with the install hint. Nr)AutoImageProcessor)AutoModelForObjectDetectionzbflavor='ml' requires the optional ML dependencies. Install them with: pip install 'camelot-py[ml]')rrrrrgetr transformersrr ImportErrorfrom_pretrainedtoeval_normalize_processor_sizer) r cache_keycachedrrrexcrrrrs r" _load_modelsMachineLearning._load_modelssf << #<< ))4+?+?M !!),  !L<<    7 @+::4;O;OP ' 7 78L8L M R _ TV  +::4;O;OP ' 7 78L8L M R _ TV  &&}5 &&}5$ )I  #',, Y||1 B  s(F F  FF c[USS5n[U[5(a [U5S1:XaUSnX"S.Ulggg)uMake a ``longest_edge``-only resize config transformers accepts. The TATR structure checkpoint ships ``size={'longest_edge': 800}`` (a max-longest-edge resize), but DETR's image processor in transformers >= 4.x requires ``{height, width}`` or ``{shortest_edge, longest_edge}``. Setting both edges to the same value reproduces a longest-edge cap exactly — the scale that makes the shortest edge that big would push the longest past the cap, so it falls back to capping the longest edge, aspect ratio preserved. No-op for valid configs. sizeN longest_edge) shortest_edger)getattr isinstancedictsetr) processorredges r"r)MachineLearning._normalize_processor_sizesJy&$/ dD ! !c$iN3C&C'D/3JIN'D !r!cUR5(a[XR5/5$[XRUR5$)u{Return ``{direction: [textlines]}`` for the cell-fill pass. Two sources behind one seam: * **born-digital** — the PDF's own text layer clipped to ``bbox`` (exact characters, the default). * **OCR** — words recognised from the page image (scanned / image-only PDFs), used when :meth:`_use_ocr` resolves true. OCR words are horizontal-only; the vertical axis is empty. )_use_ocrr _ocr_wordshorizontal_text vertical_text)rrs r" _text_sourceMachineLearning._text_sources< ==??(/@"E E$T+?+?ASASTTr!cfURSLagURS:XaUR(+$g)zResolve whether this page's cells are filled from OCR. ``ocr=True`` always; ``ocr='auto'`` only when the page has no born-digital text layer (the scanned case); ``ocr=False`` never. TrF)rrrs r"rMachineLearning._use_ocrs1 88t  88v +++ +r!cL>UR5(ag[TU] 5$)zDon't bail on a text-less page when OCR can supply the text. BaseParser short-circuits ``extract_tables`` when the page has no text layer; with OCR enabled a scanned page is exactly what we want to process, so override that for the OCR case. F)rr_document_has_no_text)rrs r"r%MachineLearning._document_has_no_texts! ==??w,..r!c6URb UR$[(a[SUlUR$SSKJn U"5Ul[R UR5 UR$![an[ S5UeSnAff=f)z0Lazily build (and process-cache) the OCR engine.Nr)RapidOCRz|flavor='ml' with OCR (scanned PDFs) requires the optional OCR dependencies. Install them with: pip install 'camelot-py[ocr]')rrrapidocr_onnxruntimerrr@)rrrs r"_get_ocr_engineMachineLearning._get_ocr_engines    '## # ;*1~D ## #  5 $:4++, Q  sA== B BBc URb UR$SSKnUR5nU"URUR55up4/nUR upgnU=(d /Hupn U V s/sHoSPM n n U V s/sHoSPM nn [ [U 5U5n[ [U 5U5n[ [[U*[U555U5n[ [[U*[U555U5nUR[XUUU55 M XPlU$s sn fs sn f)zFOCR the page image once; return words as PDF-coord :class:`_OCRWord`s.Nrr ) rnumpyrasarrayrrr r>r?r=r r@r)rnpengineresult_wordsrzr{r|boxr_scoreptxsysrrrrs r"rMachineLearning._ocr_words!s ?? &?? "%%'2::doo67  ")) !'2 Cv"%&#BQ%#B&"%&#BQ%#B&s2w#Bs2w#B#iB892>ESE63r7!;Render the page to an RGB image and build image↔PDF scalers.rN)Imager )cv2PILrrto_arrayfilenamepageshape fromarraycvtColor COLOR_BGR2RGBrr pdf_widthr pdf_heightrr)rr r image_bgrr|img_ws r"_renderMachineLearning._render:sHH%%dmmTYY?  q)9??1+=u//#,,yBSBS*TU NNU5\ ) OOeEl *   E$..) ) E$//* * OO r!c NURnU"USS9RUR5nURR 5 U"S 0UD6nSSS5 URR UR SSS2/5nURWXHS9Sn URRn /n [U SU SU S 5HKupnU [U 5nS U5unnnnU R[U[U 5UUUU455 MM U $!,(df  N=f) z~Run one object-detection model and return DetectedObjects. Coordinates are in ``image``'s own pixel space (top-left origin). r)imagesreturn_tensorsNr;) threshold target_sizesrscoreslabelsrAc38# UHn[U5v M g7fr.)r)r/vs r"r3)MachineLearning._infer..ds41eAhhsr)rrrrno_gradtensorrpost_process_object_detectionconfigid2labelzipintr@rr)rimagermodelrmodelsinputsoutputstargetresultsr&rnsclblrnamerrrrs r"_inferMachineLearning._inferQs! %=@@M \\ ! ! #ofoG$$$ejj2&6%7899 y:  <<(( H wx0''2B LBSCH%D44NBB NN>$b BB;KL M  $ #s  D D$cURb:URVs/sH"n[[U5UR5PM$ sn$UR UR UR RUR RUR5nUVs/sH0o3RRS5(dM$URPM2 sn$s snfs snf)zReturn table bounding boxes in image-pixel space. Uses the detection model unless the user pinned ``table_areas`` (then those PDF boxes are mapped straight to image space). r) rr rrr3rrrrrr startswithr)rarearnrqs r"_detect_table_regions%MachineLearning._detect_table_regionshs    '!,,,D--t/B/BC, ++ OO LL & & LL " "  $ $   !(G177+=+=g+FGGHs)C#CCc URnURRup4[S[ US5U- 5n[S[ US5U- 5n[ U[ US5U-5n[ U[ US5U-5nURR XVXx45n URU URRURRUR5n U V s/sHhn [U RU RU RSU-U RSU-U RSU-U RSU-45PMj sn $s sn f)uxRun structure recognition on one table crop. The crop is padded by ``crop_padding`` px (clamped to the image) — TATR's structure model was trained on padded table crops, and without the margin the outermost rows/columns get clipped. Returns DetectedObjects in *full-page* image coordinates (the padded-crop offset is added back), so downstream geometry is page-consistent. rr rr,)rrrr?r(r>cropr3rrrrrrrr) rregionpadwidthheightrrrrr;rnrqs r"_recognize_structure$MachineLearning._recognize_structure{sK,,  Cq NS( ) Cq NS( ) F1I, - VAY#- .##RR$45++  LL & & LL " "  $ $     RRRRP      s8A/E*cfUR5 UR5 UR5(aEUR(dUR(a#[ R "SSS9 SUlSUl0UlUR5Hn[URU5URS9nUR(aUR(dMJ[X R5up4USSUSSUSSUSS4nUUUR S .URU'M g ) zBDetect tables, recognise structure, store each grid in PDF coords.znflavor='ml' OCR mode does not support split_text / flag_size (no per-glyph data); ignoring them for this page.r) stacklevelF)rorr;r )rsrtr)N)rrrrrwarningswarntable_bbox_parsesr8rvr@rr'r(rrr))rr<rxrsrtpdf_bboxs r"_generate_table_bbox$MachineLearning._generate_table_bboxs   ==??4>> MMD  $DO"DN!#002F"))&1!55D??$//.t5F5FGJDQ DHQKb!d1gajIH0D " "8 ,3r!cdURUnURU5UlUSUS//4$)Nrsrt)rFrt_bbox)rr user_colsparses r"_generate_columns_and_rows*MachineLearning._generate_columns_and_rowss=&&t,''- V}eFmR33r!c URXX45nUR5 [X`RUR S/55 UR U5 U$)Nr))_initialize_new_table set_all_edgesrrFrrecord_parse_metadata)r table_idxrrsrtrrs r"_generate_tableMachineLearning._generate_tablesS**9DG E11$7;;GRHI ""5) r!c2SSKJn URXU5$)z@Flow text within a spanning cell to its anchor (reuses Lattice).r )Lattice)latticerX _reduce_index)ridxrrXs r"rZMachineLearning._reduce_indexs %$$U<>U[[^q0EKKNa4G5((r!)rrrrrrrrrrrrrrrrrrKrF)returnbool)rrrrrDEFAULT_STRUCTURE_MODELDEFAULT_DETECTION_MODELrr staticmethodrrrrrrrr3r8r@rHrNrUrZrar __classcell__)rs@r"rr=s0h// )2Fn,\KK& U  / $2 ..H& D<4== ))r!r)'r __future__rrD dataclassesrrbackendsrutilsrr r r r baserrlrkrmrerfDEFAULT_MERGE_TOLr[rr$rIrPrXrirvrrrrrrrrrr!r"ros 8#!-!)   &WA  ,, ,, II I$@ B 18+.9JR<<(.  ;= 7<  \*W)jW)r!