Perspec

App and workflow to perspectively correct images. For example whiteboards, document scans, or facades.

[Screenshot of Perspec app]

• App Workflow
  • 1. Take photos
  • 2. Open Perspec app
  • 3. Select photos to correct
  • 4. Save the corrected image
  • Combine several photos into PDFs
• Installation
  • Prebuilt
  • From Source
• Usage via CLI
• Interface Scaling
• Photo Digitization Workflow
  • Additional Steps
• Technologies
• Related
• License

App Workflow

1. Take photos

Perspec is great for correcting photos of documents, receipts, whiteboards, facades, or any other planar objects.

2. Open Perspec app

3. Select photos to correct

Either use the "Select Files" button or simply drag & drop the photos onto the window.

Perspec's integrated computer vision algorithms will automatically detect the corners of the document and mark them with circles.

    Red o----------------o Green
        |                |
        |    Document    |
        |                |
Magenta o----------------o Blue

If the corners are not detected correctly, you can manually drag the circles or the edges to the correct position.

To place corners outside of the photo or to position them more precisely, zoom with the − and + buttons in the bottom right corner (or the − and + keys). Click the zoom level (or hit 0) to show the whole photo again. Drag the photo with the right or middle mouse button or move it with the arrow keys.

4. Save the corrected image

Either click one of the save buttons or hit Enter to save the corrected image.

This will save the image in the same directory as the original photo with -fixed appended to the filename.

If you selected multiple photos, they will be opened one after another, sorted naturally by their path (e.g. IMG_9.jpeg before IMG_10.jpeg).

Combine several photos into PDFs

With the PDF output format, the save button is replaced by a Start PDF 1 button, which starts a new PDF with the current photo. The PDF is named after the photo. While a PDF is open, an Add page 2 to PDF 1 button adds the photo as the next page to it. This way, the photos of several documents can be processed in one go.

Enter adds the photo to the open PDF, and Shift + Enter starts a new PDF.

A PDF is written once all its pages were added: When the next photo starts a new PDF, after the last photo, or when the window is closed.

Installation

Prebuilt

You can get the current and previous versions from the releases page.

The current nightly version can be downloaded at ad-si/Perspec/actions. However, it's necessary to fix the file permissions after download:

chmod +x ./Perspec.app/Contents/MacOS/perspec

On macOS you can also install it via this Homebrew tap:

brew install --cask ad-si/tap/perspec

From Source

Build it from source with Haskell's stack.

git clone https://github.com/ad-si/Perspec
cd Perspec
make install

This copies the Perspec.app to your /Applications directory and makes the perspec command available on your path. You can then either drop images on the app window, or use it via the CLI like perspec fix image.jpeg

On Linux and NixOS, the Nix Flake provides all necessary dependencies:

nix develop
stack install  # Or: hpack && cabal install

Usage via CLI

It's also possible to directly invoke Perspec via the CLI like so:

/Applications/Perspec.app/Contents/Resources/perspec fix path/to/image.jpeg

You can also pass several images and they will all be opened one after another. This is very useful for batch correcting a large set of images.

Interface Scaling

Perspec scales its interface with the scaling setting of the display it's shown on, so that it has the same physical size everywhere.

If the detected scaling doesn't match what you want (e.g. because of a misconfigured Xft.dpi on X11), set the PERSPEC_UI_SCALE environment variable to override it:

PERSPEC_UI_SCALE=1.5 perspec gui

Photo Digitization Workflow

1. Take photos
   1. Use camera app which lets you lock rotation (e.g. OpenCamera). Otherwise check out the guide below to fix rotation.
   2. Use a sound activated camera to take photos simply by clicking your tongue or snipping your finger. E.g. with:
   • Pluto Trigger - Hardware device
   • Magic Lantern - 3rd party firmware for Canon
   • iSoundCam - Android app
2. Use perspec rename sub-command to fix order and names of scanned files.
3. Verify that
   • All pages were captured and have the correct filename
   • Images are sharp enough
   • Images have a high contrast
   • Images have correct orientation
4. For best image quality convert images optionally to a lossless format (e.g. png), apply rotations, and convert them to grayscale. Attention: Exclude the covers!

   mogrify -verbose -format png \
     -auto-orient -colorspace gray photos/*.jpeg
   

5. Use Perspec to crop images

   perspec fix photos/*.png
   

Additional Steps

Improve colors with one of the following steps:

1. Normalize dynamic range:

   mogrify -verbose -normalize photos/*.png
   

2. Convert to black and white:

   #! /usr/bin/env bash
   
   find . -iname "*.png" | \
   while read -r file
   do
     magick \
       -verbose \
       "$file" \
       \( +clone -blur 0x60 -brightness-contrast 40 \) \
       -compose minus \
       -composite \
       -negate \
       -auto-threshold otsu \
       "$(basename "$file" ".png")"-fixed.png
   done
   

In order to rotate all photos to portrait mode, you can use one of the following commands:

mogrify -verbose -auto-orient -rotate "90>" photos/*.jpeg
mogrify -verbose -auto-orient -rotate "-90>" photos/*.jpeg

Technologies

• Core is written in Haskell
• Image manipulation and computer vision are handled by FlatCV
• Text recognition is handled by Tesseract, which is compiled from source as part of the build (see tesseract-bundled). Its English, German, and Spanish models are embedded into the binary.
• PDFs are created with HPDF

Related

Check out ad-si/awesome-scanning for an extensive list of related projects.

License

Perspec's source code is licensed under the AGPL-3.0.

The app itself is fully functional without buying a license. There are no locked features, no watermarks, and no export limits. Unlicensed versions merely remind you to buy one:

• The window title is suffixed with ⚠️ NOT REGISTERED.
• Before an image is saved, a "Buy License" banner is shown for 10 seconds. The image is saved afterwards either way.

If you'd like to get rid of those reminders and support further development, you can buy a license. Then add the license key to Perspec's config file at ~/.config/Perspec/config.yaml (it's created automatically on first launch):

licenseKey: your-license-key