Skip to content

Commit

Permalink
Docs: Clean up readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@ad-si
ad-si committed Jan 2, 2022
1 parent 63d1d37 commit 771a2e9
Show file tree
Hide file tree
Showing 2 changed files with 131 additions and 89 deletions.
29 changes: 29 additions & 0 deletions development.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Development

## Calibration

Corners of landscape calibration image:

```hs
Expand All @@ -10,9 +12,36 @@ Corners of landscape calibration image:
)
```

## Benchmarking

Use the `-bench` flag to benchmark [ImageMagick] operations.
For example:

```sh
convert \
doc.jpg \
-bench 50 \
-virtual-pixel black \
-define distort:viewport=1191x598+0+0 \
-distort Perspective \
'277,181 0,0 214,776 0,598 1405,723 1191,598 1256,175 1191,0' \
+repage \
doc-fixed.jpg
```


## Generate Icons

With <https://gist.github.com/zlbruce/883605a635df8d5964bab11ed75e46ad:>

```sh
svg2icns icon.svg
```


## New Release

- [ ] Bump version number
- [ ] Update the [cask file]
- [ ] Update version on [Gumroad]

Expand Down
191 changes: 102 additions & 89 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,16 +20,36 @@
App and workflow to perspectively correct images.
For example whiteboards, document scans, or facades.

<!-- toc -->

- [App Workflow](#app-workflow)
- [Installation](#installation)
* [Prebuilt](#prebuilt)
* [From Source](#from-source)
- [Usage via CLI](#usage-via-cli)
- [Photo Digitization Workflow](#photo-digitization-workflow)
* [Additional Steps](#additional-steps)
- [Features](#features)
- [Algorithms](#algorithms)
* [Perspective Transformation](#perspective-transformation)
* [Grayscale Conversion](#grayscale-conversion)
* [BW Conversion](#bw-conversion)
* [Interpolation of Missing Parts](#interpolation-of-missing-parts)
- [Technologies](#technologies)
- [Related](#related)

<!-- tocstop -->


## App Workflow

Step | Description | Result
-----|--------------------------------------|--------
1 | Take a photo | ![Original image][doc]
1 | Take photos | ![Original image][doc]
2 | Open Perspec | ![Opened Perspec App][open]
3 | Drop the image file onto the window | ![Dropped image][dropped]
3 | Drop the images onto the window | ![Dropped image][dropped]
4 | Mark the corners by clicking on them | ![Marked corners][corners]
5 | Press enter | ![Corrected image][fixed]
5 | Click save button (or [Enter]) | ![Corrected image][fixed]

[doc]: images/doc.jpg
[mark]: images/doc-marking.jpg
Expand All @@ -41,17 +61,17 @@ Step | Description | Result

## Installation

### Prebuilt

#### MacOS
**WARNING:**
Perspec currently only works on macOS.
Any help to make it work on
Linux [(Ticket)](https://github.com/feramhq/Perspec/issues/13)
and Microsoft [(Ticket)](https://github.com/feramhq/Perspec/issues/21)
would be greatly appreciated!

Install it via my [Homebrew](https://brew.sh) tap:

```sh
brew install --cask ad-si/tap/perspec
```
### Prebuilt

You can also get this (and previous) versions from
You can get this (and previous) versions from
[the releases page](https://github.com/feramhq/Perspec/releases).

The current nightly version can be downloaded from
Expand All @@ -64,6 +84,12 @@ chmod +x \
./Perspec.app/Contents/Resources/{perspec,script,imagemagick/bin/convert}
```

On macOS you can also install it via this [Homebrew](https://brew.sh) tap:

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


### From Source

Expand All @@ -86,15 +112,7 @@ You can then either drop images on the app window,
or use it via the CLI like `perspec fix image.jpeg`


## Manual

### Interpolation of Missing Parts

Perspec automatically interpolates missing parts by using the closest pixel.
(https://www.imagemagick.org/Usage/misc/#edge)


### Usage via CLI
## Usage via CLI

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

Expand All @@ -107,7 +125,7 @@ one after another.
This is very useful for batch correcting a large set of images.


### Photo Digitization Workflow
## Photo Digitization Workflow

1. Take photos
1. Use camera app which lets you lock rotation (e.g. [OpenCamera]).
Expand All @@ -123,39 +141,18 @@ This is very useful for batch correcting a large set of images.
- Images are sharp enough
- Images have a high contrast
- Images have correct orientation
1. Convert images to lossless format (e.g. `png`), apply rotations
and convert them to grayscale.
1. 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!
```sh
mogrify -verbose -format png -auto-orient -colorspace gray photos/*.jpeg
mogrify -verbose -format png \
-auto-orient -colorspace gray photos/*.jpeg
```
1. Use Perspec to crop images
```sh
perspec fix photos/*.png
````
1. Improve colors with one of the following steps:
1. Normalize dynamic range:
```sh
mogrify -verbose -normalize photos/*.png
```
1. Convert to black and white:
```sh
#! /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
```

[iSoundCam]: http://www.cherry-software.com/isoundcam.html
[Magic Lantern]: https://wiki.magiclantern.fm/pl:userguide?#audio_remoteshot
Expand All @@ -164,6 +161,33 @@ This is very useful for batch correcting a large set of images.
[Pluto Trigger]: https://plutotrigger.com


### Additional Steps

Improve colors with one of the following steps:

1. Normalize dynamic range:
```sh
mogrify -verbose -normalize photos/*.png
```
1. Convert to black and white:
```sh
#! /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
```sh
mogrify -verbose -auto-orient -rotate "90>" photos/*.jpeg
Expand All @@ -174,14 +198,26 @@ mogrify -verbose -auto-orient -rotate "-90>" photos/*.jpeg
```


### Technologies
## Features

- [x] Rescale image on viewport change
- [x] Handle JPEG rotation
- [x] Draw lines between corners to simplify guessing of clipped corners
- [x] Bundle Imagemagick
- [x] Better error if wrong file format is dropped (images/error-message.jpg)
- [x] Center Perspec window on screen
- [x] Drag'n'Drop for corner markers
- [x] "Submit" button
- [x] "Convert to Grayscale" button
- [ ] Add support for custom output size (e.g. A4)
- [ ] Manual rotation buttons
- [ ] Zoom view for corners
- [ ] Label corner markers

- Core is written in [Haskell](https://haskell.org)
- Perspective transformation are handled by [ImageMagick]
- App bundle is created with [Platypus](https://sveinbjorn.org/platypus)

## Algorithms

#### Underlying ImageMagick Commands
### Perspective Transformation

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

Expand All @@ -194,57 +230,34 @@ convert \
images/example-fixed.jpg
```

### Grayscale Conversion

## Development
Converts image to grayscale and normalizes the range of values afterwards.
(Uses Imagemagick's `-colorspace gray -normalize`)
### TODO
- [x] "Submit" button
- [ ] Label corner markers
- [x] Rescale image on viewport change
- [x] Handle JPEG rotation
- [ ] Manual rotation buttons
- [ ] Zoom view for corners
- [x] Drag'n'Drop for corner markers
- [x] "Convert to Grayscale" button
- [ ] Add support for custom output size (e.g. A4)
- [x] Draw lines between corners to simplify guessing of clipped corners
- [x] Bundle Imagemagick
- [x] Better error if wrong file format is dropped (images/error-message.jpg)
- [x] Center Perspec window on screen
### BW Conversion
Converts image to binary format with OTSU's method.
(Uses Imagemagick's `-auto-threshold OTSU -monochrome`)
### Benchmarking
Use the `-bench` flag to benchmark [ImageMagick] operations.
For example:
### Interpolation of Missing Parts
```sh
convert \
doc.jpg \
-bench 50 \
-virtual-pixel black \
-define distort:viewport=1191x598+0+0 \
-distort Perspective \
'277,181 0,0 214,776 0,598 1405,723 1191,598 1256,175 1191,0' \
+repage \
doc-fixed.jpg
```
Perspec automatically interpolates missing parts by using the closest pixel.
(https://www.imagemagick.org/Usage/misc/#edge)
### Generate Icons
## Technologies
With <https://gist.github.com/zlbruce/883605a635df8d5964bab11ed75e46ad:>
- Core is written in [Haskell](https://haskell.org)
- Perspective transformation are handled by [ImageMagick]
- App bundle is created with [Platypus](https://sveinbjorn.org/platypus)
```sh
svg2icns icon.svg
```
[ImageMagick]: https://imagemagick.org
## Related
Check out [ad-si/awesome-scanning](https://github.com/ad-si/awesome-scanning)
for an extensive list of related projects.


[ImageMagick]: https://imagemagick.org

0 comments on commit 771a2e9

Please sign in to comment.