├── .github ├── FUNDING.yml ├── ISSUE_TEMPLATE │ ├── bug_report.md │ └── feature_request.md └── workflows │ └── build.yml ├── .gitignore ├── LICENSE ├── Makefile ├── README.md ├── build.sh ├── carver.go ├── carver_benchmark_test.go ├── carver_test.go ├── cmd └── caire │ └── main.go ├── data └── facefinder ├── doc.go ├── draw.go ├── exec.go ├── go.mod ├── go.sum ├── gui.go ├── gui_preview.gif ├── image.go ├── image_test.go ├── imop ├── blend.go ├── blend_test.go ├── comp.go └── comp_test.go ├── preview.go ├── processor.go ├── processor_test.go ├── snapcraft.yaml ├── sobel.go ├── stackblur.go ├── testdata └── sample.jpg └── utils ├── download.go ├── download_test.go ├── format.go ├── spinner.go └── utils.go /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | github: esimov 2 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Create a report to help me improve the library 4 | labels: '' 5 | 6 | --- 7 | 8 | ### Describe the bug 9 | 16 | 17 | ### API related bug 18 | 19 | 20 | ### Expected behavior 21 | 22 | 23 | ### Screenshots 24 | 25 | - [Screenshots, logs or errors] 26 | 27 | ### Bug with the Desktop version (please complete the following information): 28 | - Sytem information like OS: [e.g. macOS, Ubuntu] 29 | - You are using the binary file from the uploaded releases or you are doing a manual build? 30 | 31 | ### Additional context 32 | 33 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request 3 | about: Suggest an idea for this project 4 | labels: '' 5 | 6 | --- 7 | 8 | ### Is your feature request related to a problem? Please describe. 9 | 10 | 11 | ### Describe the solution you'd like 12 | 13 | 14 | ### Describe alternatives you've considered 15 | 16 | 17 | ### Additional context 18 | 19 | -------------------------------------------------------------------------------- /.github/workflows/build.yml: -------------------------------------------------------------------------------- 1 | name: build 2 | 3 | on: 4 | push: 5 | branches: [master] 6 | pull_request: 7 | branches: [master] 8 | 9 | jobs: 10 | build: 11 | name: Build 12 | strategy: 13 | fail-fast: false 14 | matrix: 15 | go-version: [~1.21, ~1.22] 16 | os: [ubuntu-latest, macos-latest] 17 | runs-on: ${{ matrix.os }} 18 | env: 19 | GO111MODULE: "on" 20 | steps: 21 | - name: Install Go 22 | uses: actions/setup-go@v4 23 | with: 24 | go-version: ${{ matrix.go-version }} 25 | 26 | - name: Cache-Go 27 | uses: actions/cache@v4 28 | with: 29 | path: | 30 | ~/go/pkg/mod # Module download cache 31 | ~/.cache/go-build # Build cache (Linux) 32 | ~/Library/Caches/go-build # Build cache (Mac) 33 | key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }} 34 | restore-keys: | 35 | ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }} 36 | - name: Install Linux Dependencies 37 | if: matrix.os == 'ubuntu-latest' 38 | run: | 39 | sudo apt-get update -y 40 | sudo apt-get install -y gcc pkg-config libwayland-dev libx11-dev libx11-xcb-dev libxkbcommon-x11-dev libgles2-mesa-dev libegl1-mesa-dev libffi-dev libxcursor-dev libvulkan-dev 41 | - name: Checkout code 42 | uses: actions/checkout@v2 43 | 44 | - name: Download Go modules 45 | run: go mod download 46 | 47 | - name: Run Tests 48 | id: makefile 49 | run: | 50 | make test -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.jpg 2 | *.png 3 | *.jpeg 4 | coverage.out 5 | test-report.json 6 | /packages 7 | !/testdata/*.png 8 | !/testdata/*.jpg 9 | !/examples/**/*.png 10 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2018 Endre Simo 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | all: 2 | @./build.sh 3 | clean: 4 | @rm -f caire 5 | install: all 6 | @cp caire /usr/local/bin 7 | uninstall: 8 | @rm -f /usr/local/bin/caire 9 | package: 10 | @NOCOPY=1 ./build.sh package 11 | test: 12 | go test -v -json ./... -run=. > ./test-report.json -coverprofile=coverage.out -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |

Caire Logo

2 | 3 | [![build](https://github.com/esimov/caire/actions/workflows/build.yml/badge.svg)](https://github.com/esimov/caire/actions/workflows/build.yml) 4 | [![Go Reference](https://pkg.go.dev/badge/github.com/esimov/caire.svg)](https://pkg.go.dev/github.com/esimov/caire) 5 | [![license](https://img.shields.io/github/license/esimov/caire)](./LICENSE) 6 | [![release](https://img.shields.io/badge/release-v1.5.0-blue.svg)](https://github.com/esimov/caire/releases/tag/v1.5.0) 7 | [![homebrew](https://img.shields.io/badge/homebrew-v1.5.0-orange.svg)](https://formulae.brew.sh/formula/caire) 8 | [![caire](https://snapcraft.io/caire/badge.svg)](https://snapcraft.io/caire) 9 | 10 | **Caire** is a content aware image resize library based on *[Seam Carving for Content-Aware Image Resizing](https://inst.eecs.berkeley.edu/~cs194-26/fa16/hw/proj4-seamcarving/imret.pdf)* paper. 11 | 12 | ## How does it work 13 | * An energy map (edge detection) is generated from the provided image. 14 | * The algorithm tries to find the least important parts of the image taking into account the lowest energy values. 15 | * Using a dynamic programming approach the algorithm will generate individual seams across the image from top to down, or from left to right (depending on the horizontal or vertical resizing) and will allocate for each seam a custom value, the least important pixels having the lowest energy cost and the most important ones having the highest cost. 16 | * We traverse the image from the second row to the last row and compute the cumulative minimum energy for all possible connected seams for each entry. 17 | * The minimum energy level is calculated by summing up the current pixel value with the lowest value of the neighboring pixels obtained from the previous row. 18 | * We traverse the image from top to bottom and compute the minimum energy level. For each pixel in a row we compute the energy of the current pixel plus the energy of one of the three possible pixels above it. 19 | * Find the lowest cost seam from the energy matrix starting from the last row and remove it. 20 | * Repeat the process. 21 | 22 | #### The process illustrated: 23 | 24 | | Original image | Energy map | Seams applied 25 | |:--:|:--:|:--:| 26 | | ![original](https://user-images.githubusercontent.com/883386/35481925-de130752-0435-11e8-9246-3950679b4fd6.jpg) | ![sobel](https://user-images.githubusercontent.com/883386/35481899-5d5096ca-0435-11e8-9f9b-a84fefc06470.jpg) | ![debug](https://user-images.githubusercontent.com/883386/35481949-5c74dcb0-0436-11e8-97db-a6169cb150ca.jpg) | ![out](https://user-images.githubusercontent.com/883386/35564985-88c579d4-05c4-11e8-9068-5141714e6f43.jpg) | 27 | 28 | ## Features 29 | Key features which differentiates this library from the other existing open source solutions: 30 | 31 | - [x] **GUI progress indicator** 32 | - [x] Customizable command line support 33 | - [x] Support for both shrinking or enlarging the image 34 | - [x] Resize image both vertically and horizontally 35 | - [x] Face detection to avoid face deformation 36 | - [x] Support for multiple output image type (jpg, jpeg, png, bmp) 37 | - [x] Support for `stdin` and `stdout` pipe commands 38 | - [x] Can process whole directories recursively and concurrently 39 | - [x] Use of sobel threshold for fine tuning 40 | - [x] Use of blur filter for increased edge detection 41 | - [x] Support for squaring the image with a single command 42 | - [x] Support for proportional scaling 43 | - [x] Support for protective mask 44 | - [x] Support for removal mask 45 | - [x] [GUI debug mode support](#masks-support) 46 | 47 | ## Install 48 | First, install Go, set your `GOPATH`, and make sure `$GOPATH/bin` is on your `PATH`. 49 | 50 | ```bash 51 | $ go install github.com/esimov/caire/cmd/caire@latest 52 | ``` 53 | 54 | ## MacOS (Brew) install 55 | The library can also be installed via Homebrew. 56 | 57 | ```bash 58 | $ brew install caire 59 | ``` 60 | 61 | ## Usage 62 | 63 | ```bash 64 | $ caire -in input.jpg -out output.jpg 65 | ``` 66 | 67 | ### Supported commands: 68 | ```bash 69 | $ caire --help 70 | ``` 71 | The following flags are supported: 72 | 73 | | Flag | Default | Description | 74 | | --- | --- | --- | 75 | | `in` | - | Input file | 76 | | `out` | - | Output file | 77 | | `width` | n/a | New width | 78 | | `height` | n/a | New height | 79 | | `preview` | true | Show GUI window | 80 | | `perc` | false | Reduce image by percentage | 81 | | `square` | false | Reduce image to square dimensions | 82 | | `blur` | 4 | Blur radius | 83 | | `sobel` | 2 | Sobel filter threshold | 84 | | `debug` | false | Use debugger | 85 | | `face` | false | Use face detection | 86 | | `angle` | float | Plane rotated faces angle | 87 | | `mask` | string | Mask file path | 88 | | `rmask` | string | Remove mask file path | 89 | | `color` | string | Seam color (default `#ff0000`) | 90 | | `shape` | string | Shape type used for debugging: `circle`,`line` (default `circle`) | 91 | 92 | ## Face detection 93 | 94 | The library is capable of detecting human faces prior resizing the images by using the lightweight Pigo (https://github.com/esimov/pigo) face detection library. 95 | 96 | The image below illustrates the application capabilities for human face detection prior resizing. It's clearly visible that with face detection activated the algorithm will avoid cropping pixels inside the detected faces, retaining the face zone unaltered. 97 | 98 | | Original image | With face detection | Without face detection 99 | |:--:|:--:|:--:| 100 | | ![Original](https://user-images.githubusercontent.com/883386/37569642-0c5f49e8-2aee-11e8-8ac1-d096c0387ca0.jpg) | ![With Face Detection](https://user-images.githubusercontent.com/883386/41292871-6ca43280-6e5c-11e8-9d72-5b9a138228b6.jpg) | ![Without Face Detection](https://user-images.githubusercontent.com/883386/41292872-6cc90e8e-6e5c-11e8-8b41-5b4eb5042381.jpg) | 101 | 102 | [Sample image source](http://www.lens-rumors.com/wp-content/uploads/2014/12/EF-M-55-200mm-f4.5-6.3-IS-STM-sample.jpg) 103 | 104 | ### GUI progress indicator 105 | 106 |

GUI preview

107 | 108 | A GUI preview mode is also incorporated into the library for in time process visualization. The [Gio](http://gioui.org/) GUI library has been used because of its robustness and modern architecture. Prior running it please make sure that you have installed all the required dependencies noted in the installation section (https://gioui.org/#installation) . 109 | 110 | The preview window is activated by default but you can deactivate it any time by setting the `-preview` flag to false. When the images are processed concurrently from a directory the preview mode is deactivated. 111 | 112 | ### Face detection to avoid face deformation 113 | In order to detect faces prior rescaling, use the `-face` flag. There is no need to provide a face classification file, since it's already embedded into the generated binary file. The sample code below will resize the provided image with 20%, but checks for human faces in order tot avoid face deformations. 114 | 115 | For face detection related settings please check the Pigo [documentation](https://github.com/esimov/pigo/blob/master/README.md). 116 | 117 | ```bash 118 | $ caire -in input.jpg -out output.jpg -face=1 -perc=1 -width=20 119 | ``` 120 | 121 | ### Support for `stdin` and `stdout` pipe commands 122 | You can also use `stdin` and `stdout` with `-`: 123 | 124 | ```bash 125 | $ cat input/source.jpg | caire -in - -out - >out.jpg 126 | ``` 127 | 128 | `in` and `out` default to `-` so you can also use: 129 | 130 | ```bash 131 | $ cat input/source.jpg | caire >out.jpg 132 | $ caire -out out.jpg < input/source.jpg 133 | ``` 134 | 135 | You can provide also an image URL for the `-in` flag or even use **curl** or **wget** as a pipe command in which case there is no need to use the `-in` flag. 136 | 137 | ```bash 138 | $ caire -in -out 139 | $ curl -s | caire > out.jpg 140 | ``` 141 | 142 | ### Process multiple images from a directory concurrently 143 | The library can also process multiple images from a directory **concurrently**. You have to provide only the source and the destination folder and the new width or height in this case. 144 | 145 | ```bash 146 | $ caire -in -out 147 | ``` 148 | 149 | ### Support for multiple output image type 150 | There is no need to define the output file type, just use the correct extension and the library will encode the image to that specific type. 151 | 152 | ### Other options 153 | In case you wish to scale down the image by a specific percentage, it can be used the **`-perc`** boolean flag. In this case the values provided for the `width` and `height` are expressed in percentage and not pixel values. For example to reduce the image dimension by 20% both horizontally and vertically you can use the following command: 154 | 155 | ```bash 156 | $ caire -in input/source.jpg -out ./out.jpg -perc=1 -width=20 -height=20 -debug=false 157 | ``` 158 | 159 | Also the library supports the **`-square`** option. When this option is used the image will be resized to a square, based on the shortest edge. 160 | 161 | When an image is resized on both the X and Y axis, the algorithm will first try to rescale it prior resizing, but also will preserve the image aspect ratio. The seam carving algorithm is applied only to the remaining points. Ex. : given an image of dimensions 2048x1536 if we want to resize to the 1024x500, the tool first rescale the image to 1024x768 and then will remove only the remaining 268px. 162 | 163 | ### Masks support: 164 | 165 | - `-mask`: The path to the protective mask. The mask should be in binary format and have the same size as the input image. White areas represent regions where no seams should be carved. 166 | - `-rmask`: The path to the removal mask. The mask should be in binary format and have the same size as the input image. White areas represent regions to be removed. 167 | 168 | Mask | Mask removal 169 | :-: | :-: 170 |