Parameters¶

Processing parameters are passed as a JSON object in the X-Dewarp-Params request header. Keys use the long-form CLI parameter names with underscores.

curl -s .../api/dewarp \
  -H "Authorization: Bearer pdw_..." \
  -H 'X-Dewarp-Params: {"output_format": "tiff", "focal_length": 1.5}' \
  -F "file=@page.jpg" \
  --output dewarped.tiff

Discovering parameters¶

The API exposes all available parameters (with types, defaults, and descriptions) at a public endpoint — no authentication required:

curl -s https://page-dewarp-api.louismmx.workers.dev/api/params | jq .

This returns the parameter definitions from the current version of the page-dewarp library. It is the canonical source — if a parameter name in this document disagrees with /api/params, the endpoint is correct.

The browser app's "Advanced parameters" panel is built from this same endpoint.

API defaults¶

The API applies these defaults. Override any of them by including the key in your X-Dewarp-Params object.

Parameter	API default	Library default	Effect
`output_format`	`"png"`	`"png"`	Output image format: `png`, `jpg`, `tiff`
`no_binary`	`"1"`	`"0"`	`1` = grayscale output, `0` = adaptive binary threshold
`debug_level`	`"0"`	`"0"`	`0`–`3`. Higher values produce debug visualisations (not returned via API)
`output_json`	`"1"`	`"0"`	Generate JSON parameter sidecar. Set to `"0"` to skip (disables `X-Dewarp-Result`)

Note

The API defaults to grayscale output (no_binary=1) rather than binary thresholding. This preserves more detail for most use cases. Set "no_binary": "0" if you want the traditional black-and-white output.

Warning

Parameter names may change across library versions. Use GET /api/params to confirm the current names. The tables below were accurate at the time of writing but the endpoint is always authoritative.

Output parameters¶

Parameter	Default	Description
`output_format`	`png`	`png`, `jpg`, or `tiff`
`output_zoom`	`1.0`	Scale factor relative to the original image
`output_dpi`	`300`	DPI metadata written to the output file (does not resample)
`output_json`	`1` (API)	`1` = write JSON parameter sidecar, `0` = skip (disables `X-Dewarp-Result` header)
`no_binary`	`1` (API)	`1` = keep grayscale, `0` = apply adaptive binary threshold

Page detection¶

Parameter	Default	Description
`page_margin_x`	`50`	Pixels to ignore near left/right edges (in reduced image coordinates)
`page_margin_y`	`20`	Pixels to ignore near top/bottom edges
`text_min_width`	`15`	Minimum width of a detected text contour
`text_min_height`	`2`	Minimum height of a detected text contour
`text_min_aspect`	`1.5`	Minimum width/height ratio to qualify as text
`text_max_thickness`	`10`	Maximum thickness of a detected text contour
`text_morph_ops`	`d_9_1,e_1_3`	Morphological operations for the text mask
`line_morph_ops`	`e_3_1_3,d_8_2`	Morphological operations for the line mask
`adaptive_winsz`	`55`	Window size for adaptive thresholding

Span assembly¶

Parameter	Default	Description
`span_min_width`	`30`	Minimum width for a span of text
`span_px_per_step`	`20`	Sampling interval along spans
`edge_max_overlap`	`1.0`	Maximum horizontal overlap between contours in a span
`edge_max_length`	`100.0`	Maximum edge length connecting contours
`edge_angle_cost`	`10.0`	Cost weight for angles in edges (vs length)
`edge_max_angle`	`7.5`	Maximum angle change allowed between contours

Optimisation¶

Parameter	Default	Description
`focal_length`	`1.2`	Normalised focal length of the camera model
`opt_max_iter`	`600000`	Maximum optimisation iterations
`shear_cost`	`0.0`	Penalty against camera tilt (shear distortion)
`max_corr`	`100`	Maximum corrections for inverse Hessian approximation (L-BFGS-B)
`remap_decimate`	`16`	Downscaling factor for image remapping

Advanced¶

These control the internal parameter vector layout and are rarely needed in practice.

Parameter	Default	Description
`rvec_idx`	`(0, 3)`	Slice indices for rotation vector in parameter array
`tvec_idx`	`(3, 6)`	Slice indices for translation vector
`cubic_idx`	`(6, 8)`	Slice indices for cubic slope parameters

Passthrough behaviour¶

Parameters map directly to the page-dewarp CLI. The key name is converted from snake_case to --kebab-case automatically:

JSON key	CLI flag
`focal_length`	`--focal-length`
`output_format`	`--output-format`
`page_margin_x`	`--page-margin-x`

New parameters added to future versions of page-dewarp are automatically available without an API update. Refer to page-dewarp --help or the library documentation for the complete and current parameter list.