{"id":13712993,"url":"https://github.com/ad-si/Perspec","last_synced_at":"2025-05-06T22:31:59.765Z","repository":{"id":38020950,"uuid":"242412549","full_name":"ad-si/Perspec","owner":"ad-si","description":"Scriptable desktop app to correct the perspective of images","archived":false,"fork":false,"pushed_at":"2025-02-01T15:06:04.000Z","size":14729,"stargazers_count":613,"open_issues_count":34,"forks_count":33,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-29T09:57:59.921Z","etag":null,"topics":["app","correction","desktop-app","gloss","gui","hacktoberfest","haskell","image","imagemagick","keystone","linux-app","macos-app","perspec","perspective","perspective-transformation","photo","scanning","scriptable","workflow"],"latest_commit_sha":null,"homepage":"https://feram.gumroad.com/l/perspec","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ad-si.png","metadata":{"files":{"readme":"readme.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"license","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}},"created_at":"2020-02-22T21:13:32.000Z","updated_at":"2025-04-10T16:18:19.000Z","dependencies_parsed_at":"2025-02-07T19:10:34.033Z","dependency_job_id":"ef02a7fc-da75-483a-9a5b-dceb82be5861","html_url":"https://github.com/ad-si/Perspec","commit_stats":{"total_commits":119,"total_committers":4,"mean_commits":29.75,"dds":0.04201680672268904,"last_synced_commit":"4aaa2603504f426ab61adcd773de792f32a9e763"},"previous_names":["ad-si/perspec","feramhq/perspec"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ad-si%2FPerspec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ad-si%2FPerspec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ad-si%2FPerspec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ad-si%2FPerspec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ad-si","download_url":"https://codeload.github.com/ad-si/Perspec/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252776573,"owners_count":21802467,"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":["app","correction","desktop-app","gloss","gui","hacktoberfest","haskell","image","imagemagick","keystone","linux-app","macos-app","perspec","perspective","perspective-transformation","photo","scanning","scriptable","workflow"],"created_at":"2024-08-02T23:01:25.702Z","updated_at":"2025-05-06T22:31:54.746Z","avatar_url":"https://github.com/ad-si.png","language":"Haskell","readme":"\u003ch1 style=\"\n  display: inline-block !important;\n  font-size: 3rem;\n\"\u003e\n  \u003cimg\n    src=\"./images/icon.svg\"\n    alt=\"Icon\"\n    height=\"56px\"\n    style=\"\n      display: inline-block !important;\n      height: 3.5rem;\n      margin-right: 1rem;\n    \"\n  /\u003e\n  \u003cspan style=\"position: relative; bottom: 0.7rem;\"\u003e\n    Perspec\n  \u003c/span\u003e\n\u003c/h1\u003e\n\nApp and workflow to perspectively correct images.\nFor example whiteboards, document scans, or facades.\n\n\u003c!-- toc --\u003e\n\n- [App Workflow](#app-workflow)\n- [Installation](#installation)\n  * [Prebuilt](#prebuilt)\n  * [From Source](#from-source)\n- [Usage via CLI](#usage-via-cli)\n- [Photo Digitization Workflow](#photo-digitization-workflow)\n  * [Additional Steps](#additional-steps)\n- [Features](#features)\n- [Algorithms](#algorithms)\n  * [Perspective Transformation](#perspective-transformation)\n  * [Grayscale Conversion](#grayscale-conversion)\n  * [BW Conversion](#bw-conversion)\n  * [Interpolation of Missing Parts](#interpolation-of-missing-parts)\n- [Technologies](#technologies)\n- [Related](#related)\n\n\u003c!-- tocstop --\u003e\n\n\n## App Workflow\n\nStep | Description                                | Result\n-----|--------------------------------------------|------------------\n1    | Take photos                                | ![Original image][doc]\n2    | Open Perspec app                           | ![Opened Perspec App][open]\n3    | Drop the images onto the window            | ![Dropped image][dropped]\n4    | Mark the corners by clicking on them       | ![Marked corners][corners]\n5    | Click one of the save buttons (or [Enter]) | ![Corrected image][fixed]\n\n[doc]: images/doc.jpg\n[mark]: images/doc-marking.jpg\n[open]: images/perspec_opened.png\n[dropped]: images/perspec_image_dropped.png\n[corners]: images/perspec_marked_corners.png\n[fixed]: images/doc-fixed.jpg\n\n\n## Installation\n\n**WARNING:**\nPerspec currently only works on macOS and Linux.\nAny help to make it work on\nMicrosoft [(Ticket)](https://github.com/feramhq/Perspec/issues/21)\nwould be greatly appreciated!\n\n\n### Prebuilt\n\nYou can get this (and previous) versions from\n[the releases page](https://github.com/feramhq/Perspec/releases).\n\nThe current nightly version can be downloaded from\nhttps://github.com/feramhq/Perspec/actions.\nHowever, it's necessary to fix the file permissions after download:\n\n```sh\nchmod +x \\\n  ./Perspec.app/Contents/MacOS/Perspec \\\n  ./Perspec.app/Contents/Resources/{perspec,script,imagemagick/bin/convert}\n```\n\nOn macOS you can also install it via this [Homebrew](https://brew.sh) tap:\n\n```sh\nbrew install --cask ad-si/tap/perspec\n```\n\n\n### From Source\n\nBuild it from source with Haskell's\n[stack](https://docs.haskellstack.org/en/stable/install_and_upgrade/).\n\nPlatypus, with \n[command line tools enabled](https://github.com/sveinbjornt/Platypus/blob/master/Documentation/Documentation.md#show-shell-command)\n, is required to build from source.\n\n```sh\ngit clone https://github.com/feramhq/Perspec\ncd Perspec\nmake install\n```\n\nThis copies the `Perspec.app` to your `/Applications` directory\nand makes the `perspec` command available on your path.\nYou can then either drop images on the app window,\nor use it via the CLI like `perspec fix image.jpeg`\n\n\n## Usage via CLI\n\nIt's also possible to directly invoke Perspec via the CLI like so:\n\n```sh\n/Applications/Perspec.app/Contents/Resources/perspec fix path/to/image.jpeg\n```\n\nYou can also pass several images and they will all be opened\none after another.\nThis is very useful for batch correcting a large set of images.\n\n\n## Photo Digitization Workflow\n\n1. Take photos\n    1. Use camera app which lets you lock rotation (e.g. [OpenCamera]).\n      Otherwise check out the guide below to fix rotation.\n    1. Use a sound activated camera to take photos simply\n      by clicking your tongue or snipping your finger. E.g. with:\n      - [Pluto Trigger] - Hardware device\n      - [Magic Lantern] - 3rd party firmware for Canon\n      - [iSoundCam] - Android app\n1. Use `perspec rename` sub-command to fix order and names of scanned files.\n1. Verify that\n    - All pages were captured and have the correct filename\n    - Images are sharp enough\n    - Images have a high contrast\n    - Images have correct orientation\n1. For best image quality convert images optionally\n  to a lossless format (e.g. `png`),\n  apply rotations, and convert them to grayscale.\n  Attention: Exclude the covers!\n    ```sh\n    mogrify -verbose -format png \\\n      -auto-orient -colorspace gray photos/*.jpeg\n    ```\n1. Use Perspec to crop images\n    ```sh\n    perspec fix photos/*.png\n    ````\n\n[iSoundCam]: http://www.cherry-software.com/isoundcam.html\n[Magic Lantern]: https://wiki.magiclantern.fm/pl:userguide?#audio_remoteshot\n[OpenCamera]:\n  https://play.google.com/store/apps/details?id=net.sourceforge.opencamera\n[Pluto Trigger]: https://plutotrigger.com\n\n\n### Additional Steps\n\nImprove colors with one of the following steps:\n\n1. Normalize dynamic range:\n  ```sh\n  mogrify -verbose -normalize photos/*.png\n  ```\n1. Convert to black and white:\n    ```sh\n    #! /usr/bin/env bash\n\n    find . -iname \"*.png\" | \\\n    while read -r file\n    do\n      convert \\\n        -verbose \\\n        \"$file\" \\\n        \\( +clone -blur 0x60 -brightness-contrast 40 \\) \\\n        -compose minus \\\n        -composite \\\n        -negate \\\n        -auto-threshold otsu \\\n        \"$(basename \"$file\" \".png\")\"-fixed.png\n    done\n    ```\n\nIn order to rotate all photos to portrait mode you can use either\n```sh\nmogrify -verbose -auto-orient -rotate \"90\u003e\" photos/*.jpeg\n```\nor\n```sh\nmogrify -verbose -auto-orient -rotate \"-90\u003e\" photos/*.jpeg\n```\n\n\n## Features\n\n- [x] Rescale image on viewport change\n- [x] Handle JPEG rotation\n- [x] Draw lines between corners to simplify guessing of clipped corners\n- [x] Bundle Imagemagick\n- [x] Better error if wrong file format is dropped (images/error-message.jpg)\n- [x] Center Perspec window on screen\n- [x] Drag'n'Drop for corner markers\n- [x] \"Submit\" button\n- [x] \"Convert to Grayscale\" button\n- [ ] Add support for custom output size (e.g. A4)\n- [ ] Manual rotation buttons\n- [ ] Zoom view for corners\n- [ ] Label corner markers\n\n\n## Algorithms\n\n### Perspective Transformation\n\nOnce the corners are marked, the correction is equivalent to:\n\n```sh\nconvert \\\n  images/example.jpg \\\n  -distort Perspective \\\n    '8,35 0,0 27,73 0,66 90,72 63,66 67,10 63,0' \\\n  -crop 63x66+0+0 \\\n  images/example-fixed.jpg\n```\n\n### Grayscale Conversion\n\nConverts image to grayscale and normalizes the range of values afterwards.\n(Uses Imagemagick's `-colorspace gray -normalize`)\n\n\n### BW Conversion\n\nConverts image to binary format with OTSU's method.\n(Uses Imagemagick's `-auto-threshold OTSU -monochrome`)\n\n\n### Interpolation of Missing Parts\n\nPerspec automatically interpolates missing parts by using the closest pixel.\n(https://www.imagemagick.org/Usage/misc/#edge)\n\n\n## Technologies\n\n- Core is written in [Haskell](https://haskell.org)\n- Perspective transformation are handled by [ImageMagick]\n- App bundle is created with [Platypus](https://sveinbjorn.org/platypus)\n\n[ImageMagick]: https://imagemagick.org\n\n\n## Related\n\nCheck out [ad-si/awesome-scanning](https://github.com/ad-si/awesome-scanning)\nfor an extensive list of related projects.\n","funding_links":[],"categories":["Haskell"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fad-si%2FPerspec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fad-si%2FPerspec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fad-si%2FPerspec/lists"}