Perspec

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

---

• App Workflow
• Installation
  • Prebuilt
  • From Source
• Usage via CLI
• Photo Digitization Workflow
  • Additional Steps
• Features
• Algorithms
  • Perspective Transformation
  • Grayscale Conversion
  • BW Conversion
  • Interpolation of Missing Parts
• Technologies
• Related

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.

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.

Button	Description	Result
Save	Saves the image in 24-bit color.
Save Gray	Saves the image in 8-bit grayscale and normalizes the range of values.
Save BW	Saves the image in true 1-bit black & white (each pixel is either black or white).
Save BW Smooth	Saves the image in mostly black & white with some grayscale edge smoothing. This is the recommended option for documents, receipts, and whiteboards.

Installation

Prebuilt

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

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

chmod +x \
  ./Perspec.app/Contents/MacOS/Perspec \
  ./Perspec.app/Contents/Resources/{perspec,script}

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.

Platypus, with command line tools enabled , is required to build from source.

git clone https://github.com/feramhq/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

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.

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
• App bundle is created with Platypus

Related

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