diff --git a/Gemfile b/Gemfile index e448153..6a330bb 100644 --- a/Gemfile +++ b/Gemfile @@ -12,3 +12,4 @@ gem 'rspec' gem 'rubocop' gem 'simplecov' gem 'super_diff' +gem 'yard' diff --git a/Gemfile.lock b/Gemfile.lock index e42dbdd..b6ad53d 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -134,6 +134,7 @@ GEM patience_diff thor (1.3.2) unicode-display_width (2.6.0) + yard (0.9.37) PLATFORMS x86_64-linux @@ -147,6 +148,7 @@ DEPENDENCIES rubocop simplecov super_diff + yard BUNDLED WITH 2.4.22 diff --git a/Makefile b/Makefile index 3847454..bd19475 100644 --- a/Makefile +++ b/Makefile @@ -20,3 +20,6 @@ stop: clean: docker ps -q --filter name=${CONTAINER_NAME} | grep -q . && docker container stop ${CONTAINER_NAME} || true docker image ls -q ${IMAGE_NAME} | grep -q . && docker image rm ${IMAGE_NAME} || true + +docs: + docker run -it --rm --name ${CONTAINER_NAME} -v ${PWD}:/app ${IMAGE_NAME}:latest yard doc lib/morandi.rb diff --git a/README.md b/README.md index 2ef6441..1770769 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,10 @@ # Morandi -Library of simple image manipulations - replicating the behaviour of -morandi-js. +Library of simple image manipulations - replicating the behaviour of morandi-js. ## Installation -Install `liblcms2-utils` to provide the `jpgicc` command used by `Morandi::ProfiledPixbuf`. Also ensure that your host system has `imagemagick` installed, which is required bi the `colorscore` gem. +Install `liblcms2-utils` to provide the `jpgicc` command used by `Morandi::ProfiledPixbuf`. Also ensure that your host system has `imagemagick` installed, which is required by the `colorscore` gem. Add this line to your application's Gemfile: @@ -22,26 +21,10 @@ Or install it yourself as: ## Usage ```` - Morandi.process(in_file, settings, out_file) + Morandi.process(source, options, target_path) ```` -- in_file is a string -- settings is a hash -- out_file is a string - -Settings Key | Values | Description --------------|--------|--------------- -brighten | Integer -20..20 | Change image brightness -gamma | Float | Gamma correct image -contrast | Integer -20..20 | Change image contrast -sharpen | Integer -5..5 | Sharpen / Blur (negative value) -redeye | Array[[Integer,Integer],...] | Apply redeye correction at point -angle | Integer 0,90,180,270 | Rotate image -straighten | Float | Rotate by N degrees and zoom -crop | Array[Integer,Integer,Integer,Integer] | Crop image -fx | String greyscale,sepia,bluetone | Apply colour filters -border-style | String square,retro | Set border style -background-style | String retro,black,white | Set border colour -quality | String '1'..'100' | Set JPG compression value, defaults to 97% + +For the detailed documentation of options see `lib/morandi.rb` ## Contributing @@ -53,4 +36,4 @@ quality | String '1'..'100' | Set JPG compression value, defaults to 97% ### Development -Since this gem depends on the `liblcms2-utils` library, which can be awkward to install on some operating systems, we also provide a development docker image. A Makefile is also provided as a simple CLI. To build the image and run the container, type `make` from the project root. The container itself runs `guard` as its main process. Running the container via `make` will drop you into the guard prompt, which will run the test suite whenever any of the source code or tests are changed. The tests can be kicked-off manually via the `all` command at the guard prompt. Individual test can be run using the `focus: true` annotation on an example or describe block. If you need to access a bash shell in the container (for example, to run rubocop), use the command `make shell`. +Since this gem depends on the `liblcms2-utils` library, which can be awkward to install on some operating systems, we also provide a development docker image. A Makefile is also provided as a simple CLI. To build the image and run the container, type `make` from the project root. The container itself runs `guard` as its main process. Running the container via `make` will drop you into the guard prompt, which will run the test suite whenever any of the source code or tests are changed. The tests can be kicked-off manually via the `all` command at the guard prompt. Individual test can be run using the `focus: true` annotation on an example or describe block. If you need to access a bash shell in the container (for example, to run rubocop), use the command `make shell`. diff --git a/lib/morandi.rb b/lib/morandi.rb index c740718..1ecff7d 100644 --- a/lib/morandi.rb +++ b/lib/morandi.rb @@ -14,26 +14,34 @@ module Morandi module_function - # The main entry point for the libray + # The main entry point for the library # # @param source [String|GdkPixbuf::Pixbuf] source image - # @param options [Hash] + # @param [Hash] options The options describing expected processing to perform + # @option options [Integer] 'brighten' Change image brightness (-20..20) + # @option options [Float] 'gamma' Gamma correct image + # @option options [Integer] 'contrast' Change image contrast (-20..20) + # @option options [Integer] 'sharpen' Sharpen (1..5) / Blur (-1..-5) + # @option options [Array[[Integer,Integer],...]] 'redeye' Apply redeye correction at point + # @option options [Integer] 'angle' Rotate image clockwise by multiple of 90 (0, 90, 180, 270) + # @option options [Array[Integer,Integer,Integer,Integer]] 'crop' Crop image (x, y, width, height) + # @option options [String] 'fx' Apply colour filters ('greyscale', 'sepia', 'bluetone') + # @option options [String] 'border-style' Set border style ('square', 'retro') + # @option options [String] 'background-style' Set border colour ('retro', 'black', 'white') + # @option options [String] 'quality' ('97') Set JPG compression value ('1' to '100') + # @option options [Integer] 'output.max' Downscales the image to fit within the square of given size before + # processing to limit the required resources + # @option options [Integer] 'output.width' Sets desired width of resulting image + # @option options [Integer] 'output.height' Sets desired height of resulting image + # @option options [TrueClass|FalseClass] 'image.auto-crop' (true) If the output dimensions are set and this is true, + # image is cropped automatically to the desired + # dimensions. + # @option options [TrueClass|FalseClass] 'output.limit' (false) If the output dimensions are defined and this is true, + # the output image is scaled down to fit within square of + # size of the longer edge (ignoring shorter dimension!) # @param target_path [String] target location for image - # @param local_options [Hash] - # - # Settings Key | Values | Description - # -------------|--------|--------------- - # brighten | Integer -20..20 | Change image brightness - # gamma | Float | Gamma correct image - # contrast | Integer -20..20 | Change image contrast - # sharpen | Integer -5..5 | Sharpen / Blur (negative value) - # redeye | Array[[Integer,Integer],...] | Apply redeye correction at point - # angle | Integer 0,90,180,270 | Rotate image - # crop | Array[Integer,Integer,Integer,Integer] | Crop image - # fx | String greyscale,sepia,bluetone | Apply colour filters - # border-style | String square,retro | Set border style - # background-style | String retro,black,white | Set border colour - # quality | String '1'..'100' | Set JPG compression value, defaults to 97% + # @param local_options [Hash] Hash of options other than desired transformations + # @option local_options [String] 'path.icc' A path to store the input after converting to sRGB colour space def process(source, options, target_path, local_options = {}) pro = ImageProcessor.new(source, options, local_options) pro.result