{"id":17978445,"url":"https://github.com/ad-si/perspectra","last_synced_at":"2025-10-26T11:18:08.275Z","repository":{"id":232206240,"uuid":"100578685","full_name":"ad-si/Perspectra","owner":"ad-si","description":"Automatically extract documents from images and perspectively correct them with classic computer-vision algorithms. In maintenance mode. Check out its successor at:","archived":false,"fork":false,"pushed_at":"2025-08-24T19:34:45.000Z","size":13893,"stargazers_count":81,"open_issues_count":4,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-04T17:53:22.991Z","etag":null,"topics":["computer-vision","deskew","document-scanner","perspective-correction","python","scanner","scikit-image","skimage"],"latest_commit_sha":null,"homepage":"https://github.com/ad-si/FlatCV","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ad-si.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-08-17T08:11:35.000Z","updated_at":"2025-09-04T14:50:50.000Z","dependencies_parsed_at":"2024-04-08T16:10:44.903Z","dependency_job_id":"0ca86475-ea93-47fd-9740-237a2a8ae8e5","html_url":"https://github.com/ad-si/Perspectra","commit_stats":null,"previous_names":["ad-si/perspectra","feramhq/perspectra"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/ad-si/Perspectra","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ad-si%2FPerspectra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ad-si%2FPerspectra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ad-si%2FPerspectra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ad-si%2FPerspectra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ad-si","download_url":"https://codeload.github.com/ad-si/Perspectra/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ad-si%2FPerspectra/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281093393,"owners_count":26442575,"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","status":"online","status_checked_at":"2025-10-26T02:00:06.575Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["computer-vision","deskew","document-scanner","perspective-correction","python","scanner","scikit-image","skimage"],"created_at":"2024-10-29T17:33:44.929Z","updated_at":"2025-10-26T11:18:08.270Z","avatar_url":"https://github.com/ad-si.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e [!IMPORTANT]\n\u003e This project is in maintenance mode.\n\u003e Any further development will be carried out in its successor project\n\u003e [FlatCV](https://github.com/ad-si/FlatCV).\n\n---\n\n# Perspectra\n\nSoftware and corresponding workflow to scan documents and books\nwith as little hardware as possible.\n\nCheck out [github:ad-si/awesome-scanning]\nfor an extensive list of alternative solutions.\n\n[github:ad-si/awesome-scanning]: https://github.com/ad-si/awesome-scanning\n\n\nCommand | Input | Result\n--------|-------|-------\n`perspectra correct --binary=gauss-diff 01.jpeg`|![Receipt 1](images/examples/01_original.jpeg)|![Receipt 1 binarized](images/examples/01_binary.png)\n`perspectra correct --binary=gauss-diff 02.jpeg`|![Receipt 2](images/examples/02_original.jpeg)|![Receipt 2 binarized](images/examples/02_binary.png)\n`perspectra correct --gray 03.jpeg`|![Receipt 3](images/examples/03_original.jpeg)|![Receipt 3 grayscale](images/examples/03_gray.png)\n\n\n## Installation\n\nWe recommend to use [`uv`](https://docs.astral.sh/uv/)\ninstead of `pip` to install the package.\n\n```sh\nuv tool install perspectra\n```\n\nTo install from source:\n\n```sh\ngit clone https://github.com/ad-si/Perspectra\ncd Perspectra\nmake install\n```\n\n\n## Usage\n\n### Command Line Interface\n\n```txt\nusage: perspectra [-h] [--debug] {binarize,correct,corners,renumber-pages} ...\n\noptions:\n  -h, --help            show this help message and exit\n  --debug               Render debugging view\n\nsubcommands:\n  subcommands to handle files and correct photos\n\n  {binarize,correct,corners,renumber-pages}\n                        additional help\n    binarize            Binarize image\n    correct             Pespectively correct and crop photos of documents.\n    corners             Returns the corners of the document in the image as\n                        [top-left, top-right, bottom-right, bottom-left]\n    renumber-pages      Renames the images in a directory according to their\n                        page numbers. The assumed layout is `cover -\u003e odd\n                        pages -\u003e even pages reversed`\n```\n\n\n## Best Practices for Taking the Photos\n\nYour photos should ideally have following properties:\n\n- Photos with 10 - 20 Mpx\n- Contain 1 document\n    - Rectangular\n    - Pronounced corners\n    - Only black content on white or light-colored paper\n    - On dark background\n    - Maximum of 30° rotation\n\n\n### Camera Settings\n\n```yaml\n# Rule of thumb is the inverse of your focal length,\n# but motion blur is pretty much the worst for readable documents,\n# therefore use at least half of it and never less than 1/50.\nshutter: 1/50 - 1/200 s\n\n# The whole document must be sharp even if you photograph it from an angle.\n# Therefore at least 8 f.\naperture: 8-12 f\n\n# Noise is less bad than motion blur =\u003e relative high ISO\n# Should be the last thing you set:\n# As high as necessary as low as possible\niso: 800-6400\n```\n\nWhen using `Tv` (Time Value) or `Av` (Aperture Value) mode\nuse exposure compensation to set lightness value below 0.\nYou really don't want to overexpose your photos as the bright pages\nare the first thing that clips.\n\nOn the other hand,\nit doesn't matter if you loose background parts because they are to dark.\n\n\n### Generating the Photos from a Video\n\nA good tool for this purpose is [PySceneDetect].\nIt's a Python/OpenCV-based scene detection program,\nusing threshold/content analysis on a given video.\n\n[PySceneDetect]: https://github.com/Breakthrough/PySceneDetect\n\nFor easy installation you can use the [docker image]\n\n[docker image]: https://github.com/handflucht/PySceneDetect\n\n\nFind good values for threshold:\n\n```fish\ndocker run \\\n  --rm \\\n  --volume (pwd):/video \\\n  handflucht/pyscenedetect\n  --input /video/page-turning.mp4 \\\n  --downscale-factor 2 \\\n  --detector content \\\n  --statsfile page-turning-stats.csv\n```\n\n\nTo launch the image run:\n\n```fish\ndocker run \\\n  --interactive \\\n  --tty \\\n  --volume=(pwd):/video \\\n  --entrypoint=bash \\\n  handflucht/pyscenedetect\n```\n\n\nThen run in the shell:\n\n```bash\ncd /video\nscenedetect \\\n  --input page-turning.mp4 \\\n  --downscale-factor 2 \\\n  --detector content \\\n  --threshold 3 \\\n  --min-scene-length 80 \\\n  --save-images\n```\n\n\nTODO: The correct way to do this:\n(after https://github.com/Breakthrough/PySceneDetect/issues/45 is implemented)\n\n```fish\ndocker run \\\n  --rm \\\n  --volume (pwd):/video \\\n  handflucht/pyscenedetect \\\n  --input /video/page-turning.mp4 \\\n  --downscale-factor 2 \\\n  --detector content \\\n  --threshold 3 \\\n  --min-scene-length 80 \\\n  --save-images \u003cTODO: path\u003e\n```\n\nAim for a low threshold and a long minimum scene length.\nI.e. turn the page really fast and show it for a long time.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fad-si%2Fperspectra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fad-si%2Fperspectra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fad-si%2Fperspectra/lists"}