{"id":15331270,"url":"https://github.com/wohali/hough","last_synced_at":"2025-10-10T01:31:20.848Z","repository":{"id":39636038,"uuid":"249576683","full_name":"wohali/hough","owner":"wohali","description":"Skew detection in scanned images","archived":false,"fork":true,"pushed_at":"2024-02-06T10:08:00.000Z","size":3484,"stargazers_count":3,"open_issues_count":15,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-02T09:55:06.502Z","etag":null,"topics":["deskew","hough","image-processing","python","rotate"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"qu1j0t3/hough","license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wohali.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-03-24T00:41:13.000Z","updated_at":"2022-03-08T12:50:59.000Z","dependencies_parsed_at":"2023-10-12T14:00:49.842Z","dependency_job_id":null,"html_url":"https://github.com/wohali/hough","commit_stats":{"total_commits":82,"total_committers":7,"mean_commits":"11.714285714285714","dds":0.7439024390243902,"last_synced_commit":"2ee7582f2df2f7198618b3bb312a0fdcf20523a8"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wohali%2Fhough","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wohali%2Fhough/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wohali%2Fhough/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wohali%2Fhough/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wohali","download_url":"https://codeload.github.com/wohali/hough/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235892391,"owners_count":19061857,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deskew","hough","image-processing","python","rotate"],"created_at":"2024-10-01T09:55:09.298Z","updated_at":"2025-10-10T01:31:20.843Z","avatar_url":"https://github.com/wohali.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hough - Skew detection in scanned images\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/wohali/hough/actions\"\u003e\u003cimg alt=\"Actions Status\" src=\"https://github.com/wohali/hough/workflows/Tests/badge.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/hough/\"\u003e\u003cimg alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/hough\"\u003e\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/hough/\"\u003e\u003cimg alt=\"PyPI - Python Version\" src=\"https://img.shields.io/pypi/pyversions/hough\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/wohali/hough/blob/main/COPYING\"\u003e\u003cimg src=\"https://img.shields.io/github/license/wohali/hough.svg\" alt=\"GPL v2.0 License\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/psf/black\"\u003e\u003cimg alt=\"Code style: black\" src=\"https://img.shields.io/badge/code%20style-black-000000.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://codecov.io/gh/wohali/hough\"\u003e\u003cimg alt=\"Coverage stats\" src=\"https://codecov.io/gh/wohali/hough/branch/main/graph/badge.svg\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n_Hough_ finds skew angles in scanned document pages, using the Hough transform.\n\nIt is oriented to batch processing, and can make use of multiple cores or an\noptional CUDA backend. (It can be very compute intensive!)\n\n# Installation and usage\n\n## Installation\n\n```\npipx install hough\n```\n\nOr, if you have a supported GPU and have [installed CUDA](https://developer.nvidia.com/cuda-toolkit) (currently 12.x supported):\n\n```\npipx install \"hough[cuda]\"\n```\n\nIf you don't use `pipx`, other methods such as `pip` should work fine, just create a virtual environment first.\n\n## Usage\n\nTo get started right away, here's some examples.\n\nGenerate angles (in CSV form) for a bunch of TIFF images:\n\n```\nhough analyse in/*.tif\n```\n\nThe same, but for a PDF file, and display a histogram at the end:\n\n```\nhough analyse --histogram Able_Attach_Sep83.pdf\n```\n\nThe same, but show more information while running:\n\n```\nhough --verbose --histogram Able_Attach_Sep83.pdf\n```\n\nThe deskewing results are placed in a `results.csv` file created under the `out/\u003ctimestamp\u003e` directory, which is created at invocation time. Here's an example:\n\n```csv\n\"Input File\",\"Page Number\",\"Computed angle\",\"Variance of computed angles\",\"Image width (px)\",\"Image height (px)\"\n\"/home/toby/my-pages/orig/a--0000.pgm.tif\",,-0.07699791151672428,0.001073874144832815,5014,6659\n\"/home/toby/my-pages/orig/a--0001.pgm.tif\",,,,5018,6630\n\"/home/toby/my-pages/orig/a--0002.pgm.tif\",,0.24936351676615068,0.005137031681286154,5021,6629\n\"/home/toby/my-pages/orig/a--0003.pgm.tif\",,,,5020,6608\n\"/home/toby/my-pages/orig/a--0004.pgm.tif\",,-0.037485115754500545,0.025945115897015238,5021,6616\n```\n\nThe program should work on various image input formats, and with both grey scale\nand RGB images. _Hough_ works best with images ≥300dpi.\n\nHere's a histogram sample:\n\n```\n=== Skew statistics ===\n0.00° - 0.10°  [57]  ████████████████████████████████████████\n0.10° - 0.20°  [39]  ███████████████████████████▍\n0.20° - 0.30°  [30]  █████████████████████\n0.30° - 0.40°  [30]  █████████████████████\n0.40° - 0.50°  [11]  ███████▊\n0.50° - 0.60°  [11]  ███████▊\n0.60° - 0.70°  [ 3]  ██▏\n0.70° - 0.80°  [ 4]  ██▊\n0.80° - 0.90°  [ 0]\n0.90° - 1.00°  [ 1]  ▊\n1.00° - 1.10°  [ 1]  ▊\n1.10° - 1.20°  [ 0]\n1.20° - 1.30°  [ 1]  ▊\n1.30° - 1.40°  [ 1]  ▊\n1.40° - 1.50°  [ 1]  ▊\n1.50° - 1.60°  [ 2]  █▍\n1.60° - 1.70°  [ 0]\n1.70° - 1.80°  [ 1]  ▊\n1.80° - 1.90°  [ 2]  █▍\n1.90° - 2.00°  [ 0]\nSamples: 195\n50th percentile: 0.20°\n90th percentile: 0.55°\n99th percentile: 1.77°\n```\n\n## Command line options\n\nYou can list them by running `hough --help`:\n\n```\nUsage: hough COMMAND\n\n╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮\n│ analyse    Analyse one or more files for deskewing.                                    │\n│ histogram  Show a histogram of rotation angles from a previous analysis.               │\n│ process    Fully analyse and rotate one or more files.                                 │\n│ rotate     Rotate one or more files that have previously been analysed.                │\n│ --help -h  Display this message and exit.                                              │\n│ --version  Display application version.                                                │\n╰────────────────────────────────────────────────────────────────────────────────────────╯\n```\n\nOr ask for help for a specific command, *e.g.* `hough analyse --help`:\n\n```\nUsage: hough analyse [ARGS] [OPTIONS]\n\nAnalyse one or more files for deskewing.\n\n╭─ Parameters ───────────────────────────────────────────────────────────────────────────╮\n│ *  FILES --files          One or more files to analyse for deskewing. [required]       │\n│    DEBUG --debug          Save intermediate results in debug/ under out folder.        │\n│                           [default: False]                                             │\n│    VERBOSE --verbose      Print status messages instead of progress bar. [default:     │\n│                           False]                                                       │\n│    OUT --out              Use the specified path for results and post-rotated files.   │\n│                           [default: out/TIMESTAMP]                                     │\n│    WORKERS --workers      Number of workers to run simultaneously. [default: 4]        │\n│    HISTOGRAM --histogram  Display result summary as histogram after processing.        │\n│                           [default: False]                                             │\n╰────────────────────────────────────────────────────────────────────────────────────────╯\n```\n\n\n# Examples\n\nJust about all of [these files](https://docs.telegraphics.net/) have been\ndeskewed this way.\n\n# Getting the best results\n\n### NOTE: This is a beta product!\n\nThere's a few guidelines you should follow to get the best deskewing results\nfrom your document scans:\n\n1. Bilevel (black-and-white) bitmaps will produce lower quality results.\n   For best results, scan to greyscale or RGB first, deskew with _Hough_, then\n   reduce the colour depth to bilevel if desired.\n1. Hough deskewing is an inexact process, with many heuristics discovered\n   by trial and error. _Hough_ may not work well on your material without tuning\n   and further modification. (We'd love your pull requests!)\n\n## Debugging output\n\nYou can spy on _Hough_'s attempts to perform deskewing by passing the `--debug`\nflag on the command line. The generated images, and any detected lines in them,\nare placed in the `out/\u003ctimestamp\u003e/debug/` directory.\n\nNote that _Hough_ cannot always determine a skew for a page (e.g. blank pages\nin particular), and will very occasionally get the skew wrong (depending on\nsource material). It's worth reviewing these images if _Hough_ makes a bad\ndecision on your scans. Please submit these files along with the original image\nwhen filing an issue!\n\n## Recommended scanners\n\nThe authors have tested this software with output from the following scanners:\n\n* Fujitsu fi-4530C, USB\n  * Fast\n  * Cheap on eBay\n  * Requires a Windows XP VirtualBox for drivers\n* Brother ADS-2700W, USB + Ethernet + WiFi\n  * Fast\n  * Can scan directly to the network or to a memory stick\n  * Factory reconditioned models stilll available (March 2020)\n  * Very low skew out of the box\n* Epson WF-7610, USB + Ethernet + WiFi\n  * 11\"x17\" and duplex capable\n  * Can scan directly to the network or to a memory stick\n\n# Developing\n\nFirst, clone this repo.\n\nYou'll need to install [Poetry](https://python-poetry.org/docs/#installation),\nthen run:\n\n```\npoetry sync --with dev   # or --with dev,cuda if you have CUDA installed\npoetry self add 'poethepoet[poetry_plugin]' poetry-plugin-shell\n```\n\nDo some work, then run the pre-commit checks and tests with:\n\n```\npoetry run pre-commit\npoetry poe test\n```\n\n# License notice\n\n```\nThis file is part of \"hough\", which detects skew angles in scanned images\nCopyright (C) 2016-2020 Toby Thain \u003ctoby@telegraphics.net\u003e\nCopyright (C) 2020-2025 Joan Touzet \u003cwohali@apache.org\u003e\n\nThis program is free software; you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation; either version 2 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program; if not, write to the Free Software\nFoundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwohali%2Fhough","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwohali%2Fhough","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwohali%2Fhough/lists"}