Command-line interface

The formhtr console script invokes formhtr.cli.main(). The parser below is the single source of truth for flags and subcommands (see formhtr.cli).

formHTR CLI

usage: formhtr [-h] [--version]
               {process-logsheet,manual-align,select-rois,annotate-rois,doctor,automatic-align,export-logsheet,pdf-dimensions}
               ...

Positional Arguments

command: Possible choices: process-logsheet, manual-align, select-rois, annotate-rois, doctor, automatic-align, export-logsheet, pdf-dimensions

Named Arguments

--version: show program’s version number and exit

Sub-commands

process-logsheet

Extract values from a scanned logsheet to XLSX

formhtr process-logsheet [-h] --pdf-logsheet PDF_LOGSHEET --pdf-template
                         PDF_TEMPLATE --config-file CONFIG_FILE --output-file
                         OUTPUT_FILE [--google GOOGLE] [--amazon AMAZON]
                         [--azure AZURE] [--debug | --no-debug]
                         [--backside | --no-backside]
                         [--backside-template BACKSIDE_TEMPLATE]
                         [--backside-config BACKSIDE_CONFIG]
                         [--ugly-checkboxes | --no-ugly-checkboxes]
                         [--aligned | --no-aligned]
                         [--alignment-config ALIGNMENT_CONFIG]
                         [--backside-alignment-config BACKSIDE_ALIGNMENT_CONFIG]
                         [--filter-grayscale | --no-filter-grayscale]
                         [--store-csv | --no-store-csv]

Named Arguments

--pdf-logsheet

Scanned logsheet PDF

--pdf-template

Template PDF

--config-file

Config JSON

--output-file

Output XLSX file

--google

Path to Google Vision credentials JSON

--amazon

Path to Amazon credentials JSON

--azure

Path to Azure credentials JSON

--debug, --no-debug

Output annotated PDFs

Default: False

--backside, --no-backside

Backside page present

Default: False

--backside-template

Backside template PDF

--backside-config

Backside config JSON

--ugly-checkboxes, --no-ugly-checkboxes

Checkboxes have irregular shape / thick edges

Default: False

--aligned, --no-aligned

Scanned image already aligned with template (skip alignment)

Default: False

--alignment-config

Path to JSON file containing alignment config.

--backside-alignment-config

Path to JSON file containing backside alignment config.

--filter-grayscale, --no-filter-grayscale

During alignment keep only darkest grayscale pixels

Default: False

--store-csv, --no-store-csv

Store output as CSV instead of XLSX

Default: False

manual-align

Interactively align a scanned PDF to a template

formhtr manual-align [-h] --pdf-template PDF_TEMPLATE --pdf-logsheet
                     PDF_LOGSHEET --output OUTPUT
                     [--backside-template BACKSIDE_TEMPLATE]

Named Arguments

--pdf-template: Template PDF
--pdf-logsheet: Scanned logsheet PDF
--output: Output aligned PDF
--backside-template: Backside template PDF

select-rois

Interactively define ROIs in a template PDF

formhtr select-rois [-h] --pdf-file PDF_FILE --output-file OUTPUT_FILE
                    [--autodetect | --no-autodetect]
                    [--autodetect-filter AUTODETECT_FILTER]
                    [--config-file CONFIG_FILE]
                    [--detect-residuals | --no-detect-residuals]
                    [--credentials CREDENTIALS]
                    [--display-residuals | --no-display-residuals]
                    [--headless | --no-headless]

Named Arguments

--pdf-file

Template PDF

--output-file

Output config JSON

--autodetect, --no-autodetect

Default: False

--autodetect-filter

Default: 3

--config-file

Existing config JSON to continue editing

--detect-residuals, --no-detect-residuals

Default: False

--credentials

Google credentials JSON (for residual detection)

--display-residuals, --no-display-residuals

Default: False

--headless, --no-headless

Run in headless mode without GUI interaction.

Default: False

annotate-rois

Interactively label ROI types/variables

formhtr annotate-rois [-h] --pdf-file PDF_FILE --config-file CONFIG_FILE
                      --output-file OUTPUT_FILE
                      [--remove-unannotated | --no-remove-unannotated]
                      [--display-residuals | --no-display-residuals]

Named Arguments

--pdf-file: Template PDF
--config-file: Input config JSON
--output-file: Output config JSON
--remove-unannotated, --no-remove-unannotated: Default: False
--display-residuals, --no-display-residuals: Default: False

doctor

Check required system dependencies

formhtr doctor [-h]

automatic-align

Compute alignment points JSON for scanned/template PDFs

formhtr automatic-align [-h] --pdf-logsheet PDF_LOGSHEET --pdf-template
                        PDF_TEMPLATE [--backside-template BACKSIDE_TEMPLATE]
                        [--dpi DPI]

Named Arguments

--pdf-logsheet, --pdf_logsheet

Scanned logsheet PDF

--pdf-template, --pdf_template

Template PDF

--backside-template, --backside_template

Backside template PDF

--dpi

DPI for PDF conversion

Default: 300

export-logsheet

Export ROI crops and values to XLSX without OCR

formhtr export-logsheet [-h] --pdf-logsheet PDF_LOGSHEET --pdf-template
                        PDF_TEMPLATE --config-file CONFIG_FILE --output-file
                        OUTPUT_FILE [--aligned | --no-aligned]
                        [--alignment-config ALIGNMENT_CONFIG]
                        [--backside | --no-backside]
                        [--backside-template BACKSIDE_TEMPLATE]
                        [--backside-config BACKSIDE_CONFIG]
                        [--backside-alignment-config BACKSIDE_ALIGNMENT_CONFIG]

Named Arguments

--pdf-logsheet, --pdf_logsheet

Scanned logsheet PDF

--pdf-template, --pdf_template

Template PDF

--config-file, --config_file

Frontside config JSON

--output-file, --output_file

Output XLSX file

--aligned, --no-aligned

Scanned image already aligned with template

Default: False

--alignment-config, --alignment_config

Path to frontside alignment config JSON

--backside, --no-backside

Backside page present

Default: False

--backside-template, --backside_template

Backside template PDF

--backside-config, --backside_config

Path to backside config JSON

--backside-alignment-config, --backside_alignment_config

Path to backside alignment config JSON

pdf-dimensions

Get PDF page dimensions after rasterization

formhtr pdf-dimensions [-h] --pdf-file PDF_FILE [--dpi DPI]

Named Arguments

--pdf-file, --pdf_file

Path to PDF file

--dpi

DPI for PDF conversion

Default: 300

formhtr.cli.main(argv: list[str] | None = None) → int[source]

Parse CLI arguments, dispatch to the appropriate command, return exit code.

Parameters:: argv – Argument list (excluding program name). Uses sys.argv[1:] when None.
Returns:: 0 on success, 1 for doctor with missing deps, 2 for unknown command (should not normally occur).
Return type:: Process exit code