diff --git a/development.md b/development.md index 65cddbd..266b64a 100644 --- a/development.md +++ b/development.md @@ -1,5 +1,7 @@ # Development +## Calibration + Corners of landscape calibration image: ```hs @@ -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 + +```sh +svg2icns icon.svg +``` + ## New Release +- [ ] Bump version number - [ ] Update the [cask file] - [ ] Update version on [Gumroad] diff --git a/readme.md b/readme.md index 5055667..df0e8ea 100755 --- a/readme.md +++ b/readme.md @@ -20,16 +20,36 @@ App and workflow to perspectively correct images. For example whiteboards, document scans, or facades. + + +- [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) + + + ## 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 @@ -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 @@ -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 @@ -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: @@ -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]). @@ -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 @@ -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 @@ -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: @@ -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 +- 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