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
Technologies
Related

App Workflow

Step	Description	Result
1	Take photos
2	Open Perspec app
3	Drop the images onto the window
4	Mark the corners by clicking on them
5	Click one of the save buttons (or [Enter])

Installation

WARNING: Perspec currently only works on macOS. Any help to make it work on Linux (Ticket) and Microsoft (Ticket) would be greatly appreciated!

Prebuilt

You can get this (and previous) versions from the releases page.

The current nightly version can be downloaded from https://github.com/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,imagemagick/bin/convert}

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

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
Use perspec rename sub-command to fix order and names of scanned files.
Verify that
- All pages were captured and have the correct filename
- Images are sharp enough
- Images have a high contrast
- Images have correct orientation
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
```
Use Perspec to crop images
```
perspec fix photos/*.png
```

Additional Steps

Improve colors with one of the following steps:

Normalize dynamic range:

mogrify -verbose -normalize photos/*.png

Convert to black and white:

#! /usr/bin/env bash

find . -iname "*.png" | \
while read -r file
do
  convert \
    -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 either

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

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

Features

Algorithms

Perspective Transformation

Once the corners are marked, the correction is equivalent to:

convert \
  images/example.jpg \
  -distort Perspective \
    '8,35 0,0 27,73 0,66 90,72 63,66 67,10 63,0' \
  -crop 63x66+0+0 \
  images/example-fixed.jpg

Core is written in Haskell
Perspective transformation are handled by ImageMagick
App bundle is created with Platypus

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

kyodocn/Perspec