CLI Usage (Table Semantic Parser)

The yomitoku_table command analyzes whole documents with the Table Semantic Parser and exports the semantic structure of tables (key-value items and grids) together with paragraphs as per-page structured JSON.

Model weights are downloaded from the Hugging Face Hub on the first run. Authentication uses the environment variables YOMITOKU_LICENSE_KEY / YOMITOKU_SECRET_KEY (see Installation).

yomitoku_table ${path_data} -o results -v

Option	Description
${path_data}	Path to a target image/PDF file or a directory containing them. Directories are processed recursively.
-o, --outdir	Output directory (created if missing). Default: results
-v, --vis	Export visualization images (*_layout.jpg / *_ocr.jpg).
--vis_id	With --vis, draw cell ids at the top-left of each cell so that the cell ids referenced by the structured JSON and templates can be located on the image.
-l, --lite	Use lite models (for CPU).
-d, --device	Device to run the models on (cuda | cpu | mps). Default: cuda
--raw	Output the normalized TableSemanticParserSchema JSON.
--simple	Output text-only structured JSON without coordinates and other metadata.
--cell_name	Table cell detector model. Default: rtdetrv2
--cell_cfg	Path to a config file (YAML) for the cell detector.
--lp_name / --lp_cfg	Layout parser (table detector) model name / config file. Default: rtdetrv2v2
--td_name / --td_cfg	Text detector model name / config file. Default: module default (dbnetv2_1)
--tr_name / --tr_cfg	Text recognizer model name / config file. Default: module default (parseqv4). Explicit names take precedence over the --lite selection.
--rotate_detection	Detect and correct page rotation before parsing.
--template	Apply a table template JSON (skips grid/kv inference).
--grid_only	Parse only grid regions (skip key-value items).
--kv_only	Parse only key-value items (skip grids).
--pages	Pages to process (e.g. 1,2,5-10, 1-indexed). Default: all pages
--dpi	Resolution for loading PDFs. Default: 200
--encoding	Output file encoding (utf-8 | utf-8-sig | shift-jis | euc-jp | cp932).

Results are saved per page as {stem}_p{page}.json.

Output Formats

Default (structured JSON)

Cell ids in kv_items / grids are resolved into text, and the originating cell ids and coordinates are embedded as key_cells / value_cells.

Cell ids are position-based, in the form r{row}c{col}. The row index is derived by clustering the cell top coordinates within each table, and the column index is the left-to-right position within that row, so ids are robust to detection changes in other rows and to coordinate jitter of a few pixels, and can be located on the image with --vis_id. For strict cross-run matching, use coordinate-based matching (match_policy: bbox in templates) instead of ids.

• When multiple values are associated with the same key cells, the values are joined in spatial order (vertical/horizontal is auto-detected) with a line break, and value_cells lists the source cells in the same order.
• Merging is decided by the key cell ids, not the key text, so distinct fields that happen to share the same label text are never merged.
• key is an array of key texts ordered from the outermost header to the innermost, aligned with key_cells.
• Standalone cells without a key (empty key array) also remain separate entries.

The same view is available from the Python API via results.to_structured().

--simple (text only)

Outputs a text-only form without coordinates or cell references. kv_items becomes a hierarchical mapping that preserves the header nesting, grid rows become {column header: value} mappings, and paragraphs become plain strings.

Nesting rules for kv_items:

• Nested headers (parent header → child header) become nested dicts
• Sibling headers with the same text at the same level (repeated blocks) become arrays
• When a parent header has both a value and child headers, the value goes into the _value key
• Standalone cells without a key are listed under the reserved _unkeyed key

The same view is available via results.to_simple().

--raw (normalized schema)

Outputs the TableSemanticParserSchema as is: a lossless format containing cells (a dict keyed by cell id), kv_items (cell id references), grids, and words. Use this for template round-trips and re-analysis. See Table Semantic Parser for details.

Lite Mode

With --lite, the dynamic-width lightweight recognizer (parseqv4-tiny-dynw) is used for faster inference on CPU, at the cost of some recognition accuracy.

yomitoku_table ${path_data} --lite -d cpu

Rotation Correction

With --rotate_detection, page rotation (in 90-degree steps) is detected and corrected before parsing. Useful for scanned documents with mixed orientations.

yomitoku_table ${path_data} --rotate_detection

Specifying Models and Configs

Model names and config files (YAML) can be specified per module. Explicit model names take precedence over the --lite selection.

yomitoku_table ${path_data} \
  --tr_name parseqv4-large \
  --td_cfg text_detector.yaml

Module	Name option	Config option	Choices
Cell detector	--cell_name	--cell_cfg	rtdetrv2 (960 input)
Table detector	--lp_name	--lp_cfg	rtdetrv2, rtdetrv2v2, rtdetrv2v3
Text detector	--td_name	--td_cfg	dbnet, dbnetv2, dbnetv2_1
Text recognizer	--tr_name	--tr_cfg	parseq, parseqv2, parseqv3, parseqv4, parseqv4-tiny, parseqv4-tiny-dynw, parseqv4-short, parseq-small, parseqv4-large

Applying a Template

With --template, grid/kv inference is skipped and the definitions in the template JSON are applied instead. Templates can be created from --raw output via save_template_json().

yomitoku_table ${path_data} --template template.json

Parsing Only Grids / Key-Values

# grids only
yomitoku_table ${path_data} --grid_only

# key-value items only
yomitoku_table ${path_data} --kv_only

Selecting Pages

Specify pages to process with --pages (1-indexed, comma-separated, ranges allowed).

yomitoku_table ${path_data} --pages 1,3-5

Visualization

With -v, the following images are exported per page:

• *_layout.jpg: tables, paragraphs, and cell roles (green = header, blue = cell, magenta = empty). Resolved key-value links are drawn as green arrows and grid structures as blue boxes and arrows.
• *_ocr.jpg: text detection/recognition results.

yomitoku_table ${path_data} -o results -v