rmagick-bin_magick 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 29ff31c416b63fd2836b37082fccf0dea82da5808ff9e2bf98a84cbbc3872ca3
+  data.tar.gz: ec4a093d837270c8c1cd3984d3b1049e8e3a81e7cd4e14b1ab2863fc40e9b80c
+SHA512:
+  metadata.gz: 273dfe1d97525e26d06854104758b011101dbc6e52218a9321f8e5312d892a898814668ffd440e3a235c0ee002e346a45e231d04c630938d09f46f0ab8b48cc9
+  data.tar.gz: d7bdd7e46ef7a4f509e2c4a68ea209285ef049c09b4c87d550fc07208b7cdc0ab919d933473912eb0e9c194adf7caacedf89264ee544bcba5edceb0a3ef36056

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rubocop.yml

@@ -0,0 +1,13 @@
+AllCops:
+  TargetRubyVersion: 3.0
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+### 0.1.2 / 2023-04-01
+
+- Fixed the *display* method.
+
+### 0.1.1 / 2023-04-01
+
+- Fixed a bug in the *fit_to_size* and *fit_to_size!* methods.
+
+### 0.1.0 / 2023-04-01
+
+- Initial version.

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in rmagick-bin_magick.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "minitest", "~> 5.0"
+
+gem "rubocop", "~> 0.80"

data/Gemfile.lock

@@ -0,0 +1,46 @@
+PATH
+  remote: .
+  specs:
+    rmagick-bin_magick (0.1.0)
+      rmagick (~> 5.2, >= 5.2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    minitest (5.16.3)
+    parallel (1.22.1)
+    parser (3.1.3.0)
+      ast (~> 2.4.1)
+    pkg-config (1.5.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.6.1)
+    rexml (3.2.5)
+    rmagick (5.2.0)
+      pkg-config (~> 1.4)
+    rubocop (0.93.1)
+      parallel (~> 1.10)
+      parser (>= 2.7.1.5)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8)
+      rexml
+      rubocop-ast (>= 0.6.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    rubocop-ast (1.24.0)
+      parser (>= 3.1.1.0)
+    ruby-progressbar (1.11.0)
+    unicode-display_width (1.8.0)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  minitest (~> 5.0)
+  rake (~> 13.0)
+  rmagick-bin_magick!
+  rubocop (~> 0.80)
+
+BUNDLED WITH
+   2.2.3

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Mate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,469 @@
+# rmagick/bin_magick
+
+[![Gem Version](https://badge.fury.io/rb/rmagick-bin_magick.svg)](https://badge.fury.io/rb/rmagick-bin_magick)
+
+## Description
+
+**rmagick/bin_magick** is an extension of the popular **[rmagick](https://github.com/rmagick/rmagick)** image processing gem. The extension provides custom methods for easy conversion of color images to binary (monochrome) format. It also introduces in-place versions of some existing *Magick::Image* methods that, by default, lack an in-place version
+
+The *Image* class of bin_magick inherits from the *Magick::Image* class, which allows both *Magick::Image* and *Magick::BinMagick::Image* instance methods to be called on a *BinMagick::Image* object.
+
+bin_magick was developed for the [img_to_MK90_bas](https://github.com/8bit-mate/img_to_MK90_bas.rb) project, which converts images to [Elektronika MK90](https://museum.dataart.com/en/artifacts/portativnaya-evm-elektronika-mk-90) executable BASIC scripts, but it may also be useful for similar applications.
+
+## Prerequisites
+
+- Ruby ver. >= 3.0.0;
+- RMagick ver. >= 5.2.0.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rmagick-bin_magick'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install bin_magick
+
+## Usage
+
+1. Add **rmagick-bin_magick** to the list of required modules:
+
+  ```ruby
+  require "rmagick/bin_magick"
+  ```
+
+2. Read an image from a file:
+
+  ```ruby
+  image = Magick::BinMagick::Image.from_file("filename.png")
+  ```
+
+  Or initialize an instance based on the existing Magick::Image instance:
+
+  ```ruby
+  image = Magick::BinMagick::Image.new(magick_image_object)
+  ```
+
+3. Call Magick::BinMagick::Image or Magick::Image attribute and instance methods (see the examples section and the reference section for more details).
+
+### Examples
+
+#### Method chaining ####
+
+This example shows how different *Magick::BinMagick::Image* and *Magick::Image* instance methods may be combined in one method call chain:
+
+```ruby
+require "rmagick/bin_magick"
+
+# Read an image from a file:
+begin
+  image = Magick::BinMagick::Image.from_file("./data/test_0.png")
+rescue Magick::BinMagick::BinMagickError => e
+  puts e.message
+  exit
+end
+
+image
+  .level(0, Magick::QuantumRange * 0.95, 0.4) # Adjust levels (a RMagick method).
+  .crop_border_clr # Crop white border (a BinMagick method).
+  .fit_to_size!(192, 192) # Resize to fit a 192 x 192 square (a BinMagick method).
+  .to_binary(64, Magick::NoDitherMethod, "o2x2") # Convert to binary (a BinMagick method).
+  .write("./data/test_0_result.png") # Save result to a file (a RMagick method).
+```
+
+The code above will produce the following result:
+
+| Original image | Result image |
+| --- | --- |
+| ![Alt text](data/test_0.png?raw=true "Original image") | ![Alt text](data/test_0_result.png?raw=true "Result image") |
+
+#### In-place methods usage ####
+
+You can also use in-place methods:
+
+```ruby
+require "rmagick/bin_magick"
+
+# Read an image from the file './data/test_1.png'
+# ...
+
+# Adjust levels (a BinMagick method):
+image.level!(0, Magick::QuantumRange, 0.5)
+
+# Crop white border (a BinMagick method):
+image.crop_border_clr!
+
+# Resize to fit a 64 x 64 square (a BinMagick method):
+image.fit_to_size!(64, 64)
+
+# Convert to binary (a BinMagick method):
+image.to_binary!(16)
+
+# Extent to a 120 x 64 rectangle, put image in the center (a BinMagick method):
+x_offset = - (120 / 2 - image.width / 2)
+y_offset = - (64 - image.height)
+image.extent!(120, 64, x_offset, y_offset)
+
+# Save result to a file (a RMagick method):
+image.write("./data/test_1_result.png")
+```
+
+The code above will produce the following result:
+
+| Original image | Result image |
+| --- | --- |
+| ![Alt text](data/test_1.png?raw=true "Original image") | ![Alt text](data/test_1_result.png?raw=true "Result image") |
+
+## Reference
+
+### Class Magick::BinMagick::Image: attribute methods (get only)
+
+- **height**
+
+  *img*.height -> *integer*
+
+  The height of the image in pixels. An alias of the Magick::Image#[rows](https://rmagick.github.io/imageattrs.html#rows).
+
+***
+
+- **width**
+
+  *img*.width -> *integer*
+
+  The width of the image in pixels. An alias of the Magick::Image#[columns](https://rmagick.github.io/imageattrs.html#columns).
+
+***
+
+### Class Magick::BinMagick::Image: class methods
+
+- **from_file**
+
+  Magick::BinMagick::Image.from_file(*filename*) -> *image*
+
+  Reads the first image from the file *filename*.
+
+  **Note**: an image file can contain multiple images or multiple image layers, but the method always returns the first one. To load a specific image from a file (e.g. a specific frame from an animated GIF), you can use the Magick::Image#read method, and then initialize a BinMagick::Image instance with the BinMagick::Image#new method.
+
+  **Arguments**:
+
+  - filename
+
+    An image file name.
+
+  **Returns**: a new image.
+
+***
+
+- **new**
+
+  Magick::BinMagick::Image.new(*magick_image*) -> *image*
+
+  Creates a new Magick::BinMagick::Image instance from a Magick::Image object. The source Magick::Image object should not be a destroyed image, otherwise the Magick::BinMagickError::DestroyedImageError exception is raised.
+
+  **Arguments**:
+
+  - magick_image
+
+    A Magick::Image object.
+
+  **Returns**: a new image.
+
+  **Raises**: Magick::BinMagickError::DestroyedImageError.
+
+***
+
+### Class Magick::BinMagick::Image: instance methods
+
+- **black_px?**
+
+  *img*.black_px? -> *boolean*
+
+  Checks if the image has at least one black pixel.
+
+  **Returns**: a boolean value.
+
+***
+
+- **crop_border**
+
+  *img*.crop_border -> *image*
+
+  Crop border around the image. If the image is blank (has all pixels of white color): returns an unedited copy of the target image.
+
+  Methods calculates a bounding box value for the target image (see Magick::Image#[bounding_box](https://rmagick.github.io/image1.html#bounding_box)), and uses that value to crop a copy of the target image.
+
+  Works best with binary images. For color images you might want to use the *crop_border_clr* version of the method.
+
+  **Returns**: a new image.
+
+***
+
+- **crop_border!**
+
+  *img*.crop_border! -> *self*
+
+  In-place form of **crop_border**.
+
+  **Returns**: self.
+
+***
+
+- **crop_border_clr**
+
+  *img*.crop_border_clr(n_gray_colors = 64, quantize_dither = Magick::NoDitherMethod, threshold_map = "checks") -> *image*
+
+  Same as *crop_border*, but treats a color image like it is already a binary one. The bounding box value is being calculated for a binary version of the target image, then a copy of the target image is being cropped used that value.
+
+  Method **does not** convert the target image to a binary, but uses a binary version only to calculate the bounding box value. For that purpose it accepts and utilizes all *to_binary* arguments.
+
+  **Arguments**: see *to_binary* arguments description.
+
+  **Returns**: a new image.
+
+***
+
+- **crop_border_clr!**
+
+  *img*.crop_border_clr!(n_gray_colors = 64, quantize_dither = Magick::NoDitherMethod, threshold_map = "checks") -> *self*
+
+  In-place form of **crop_border_clr**.
+
+  **Returns**: self.
+
+***
+
+- **extent!**
+
+  *img*.extent!(width, height, x = 0, y = 0) -> *self*
+
+  In-place form of Magick::Image#[extent](https://rmagick.github.io/image2.html#extent).
+
+  If width or height is greater than the target image's width or height, extends the width and height of the target image to the specified values. The new pixels are set to the background color. If width or height is less than the target image's width or height, crops the target image.
+
+  **Arguments**:
+
+  - width
+
+   The width of the new image.
+
+  - height
+
+   The height of the new image.
+
+  - x, y
+
+   The upper-left corner of the new image is positioned at -x, -y.
+
+  **Returns**: self.
+
+***
+
+- **fit_to_size**
+
+  *img*.fit_to_size(max_width, max_height) -> *image*
+
+  Scales down the image to fit within the specified dimensions while retaining the original aspect ratio, but only if the image is larger than provided *max_width*, *max_height* dimensions.
+
+  **Arguments**:
+
+  - max_width, max_height
+
+    Maximum allowed image dimension.
+
+  **Returns**: a new image.
+
+***
+
+- **fit_to_size!**
+
+  *img*.fit_to_size(max_width, max_height) -> *self*
+
+  In-place form of **fit_to_size**.
+
+  **Returns**: self.
+
+***
+
+- **level!**
+
+  *img*.level!(black_point = 0.0, white_point = Magick::QuantumRange, gamma = 1.0) -> *self*
+
+  In-place form of Magick::Image#[level2](https://rmagick.github.io/image2.html#level).
+
+  Adjusts the levels of an image by scaling the colors falling between specified white and black points to the full available quantum range.
+
+  **Arguments**:
+
+  - black_point
+
+    A black point level in the range 0..QuantumRange. The default is 0.0.
+
+  - white_point
+
+    A white point level in the range 0..QuantumRange. The default is QuantumRange.
+
+  - gamma
+
+    A gamma correction in the range 0.0..10.0 The default is 1.0.
+
+  **Returns**: self.
+
+***
+
+- **ordered_dither!**
+
+  *img*.ordered_dither!(threshold_map = "checks") -> *self*
+
+  In-place form of Magick::Image#[ordered_dither](https://rmagick.github.io/image2.html#ordered_dither).
+
+  **Note**: the default value of the *threshold_map* option is "checks" rather than "2x2" used in the Magick::Image#ordered_dither method.
+
+  **Arguments**:
+
+  - threshold_map
+
+    A dither pattern to use. Available options depend on the used ImageMagick implementation. To print a complete list of the thresholds that have been defined, run the ImageMagick with the `-list threshold` option.
+
+    Some common options (from the ImageMagick [documentation](https://imagemagick.org/script/command-line-options.php?#ordered-dither)):
+    ```
+    threshold   1x1   Threshold 1x1 (non-dither)
+    checks      2x1   Checkerboard 2x1 (dither)
+    o2x2        2x2   Ordered 2x2 (dispersed)
+    o3x3        3x3   Ordered 3x3 (dispersed)
+    o4x4        4x4   Ordered 4x4 (dispersed)
+    o8x8        8x8   Ordered 8x8 (dispersed)
+    h4x4a       4x1   Halftone 4x4 (angled)
+    h6x6a       6x1   Halftone 6x6 (angled)
+    h8x8a       8x1   Halftone 8x8 (angled)
+    h4x4o             Halftone 4x4 (orthogonal)
+    h6x6o             Halftone 6x6 (orthogonal)
+    h8x8o             Halftone 8x8 (orthogonal)
+    h16x16o           Halftone 16x16 (orthogonal)
+    c5x5b       c5x5  Circles 5x5 (black)
+    c5x5w             Circles 5x5 (white)
+    c6x6b       c6x6  Circles 6x6 (black)
+    c6x6w             Circles 6x6 (white)
+    c7x7b       c7x7  Circles 7x7 (black)
+    c7x7w             Circles 7x7 (white)
+    ```
+
+  **Returns**: self.
+
+***
+
+- **oversize?**
+
+  *img*.oversize?(max_width, max_height) -> *boolean*
+
+  Checks if the target image dimensions exceed provided height **or** width.
+
+  **Returns**: a boolean value.
+
+***
+
+- **quantize!**
+
+  *img*.quantize!(number_colors = 64, colorspace = Magick::GRAYColorspace, dither = Magick::NoDitherMethod, tree_depth = 0, measure_error = false) -> *self*
+
+  In-place form of Magick::Image#[quantize](https://rmagick.github.io/image3.html#quantize).
+
+  **Notes**:
+
+    - the default value of the *number_colors* option is 64 rather than 256 used in the Magick::Image#quantize method;
+
+    - the default value of the *colorspace* option is Magick::GRAYColorspace rather than Magick::RGBColorspace used in the Magick::Image#quantize method;
+
+    - the default value of the *dither* option is Magick::NoDitherMethod rather than Magick::RiemersmaDitherMethod used in the Magick::Image#quantize method;
+
+  **Arguments**:
+
+  - number_colors
+
+    The maximum number of colors in the result image.
+
+  - colorspace
+
+    The colorspace to quantize in.
+
+  - dither
+
+    Error diffusion dither that will be applied on the color reduction. A Magick::DitherMethod value.
+
+  - tree_depth
+
+    The tree depth to use while quantizing
+
+  - measure_error
+
+    Set to true to calculate quantization errors when quantizing the image.
+
+  **Returns**: self.
+
+***
+
+- **to_binary**
+
+  *img*.to_binary(n_gray_colors = 64, quantize_dither = Magick::NoDitherMethod, threshold_map = "checks") -> *image*
+
+  Converts a color image to a binary (monochrome) image.
+
+  Combines two RMagick methods:
+
+  1. Magick::Image#[quantize](https://rmagick.github.io/image3.html#quantize) (color reducing step);
+
+  2. Magick::Image#[ordered_dither](https://rmagick.github.io/image2.html#ordered_dither) (ordered dither filter).
+
+  The first step converts image to a grayscale format with limited number of gray tones (specified by the *n_gray_colors* option). The second step applies the ordered dither filter to the grayscale image, resulting a binary image.
+
+  **Arguments**:
+
+  - n_gray_colors
+
+    Maximum number of gray tones in the quantized image.
+
+  - quantize_dither
+
+    Error diffusion dither that will be applied on the color reduction step. A Magick::[DitherMethod](https://rmagick.github.io/constants.html#DitherMethod) value.
+
+  - threshold_map
+
+    A dither pattern to use.
+
+  **Returns**: a new image.
+
+***
+
+- **to_binary!**
+
+  *img*.to_binary!(n_gray_colors = 64, quantize_dither = Magick::NoDitherMethod, threshold_map = "checks") -> *self*
+
+  The in-place form of **to_binary!**.
+
+  **Returns**: self.
+
+***
+
+## Development
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/8bit-mate/bin_magick.rb.
+
+## Acknowledge
+
+Test images were generated with the https://make.girls.moe/ project.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "rmagick/bin_magick"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/rmagick/bin_magick/bin_magick_error.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Magick
+  module BinMagick
+    #
+    # Base error class.
+    #
+    class BinMagickError < ::StandardError
+      attr_reader :message
+
+      def initialize(message)
+        @message = message
+        super
+      end
+    end
+
+    #
+    # Raises on an I/O operation fail.
+    #
+    class IOError < BinMagickError
+      attr_reader :message
+
+      def initialize(message)
+        @message = message
+        super
+      end
+    end
+
+    #
+    # Raises when an Magick::BinMagick::Image instance is being initialized with a destroyed image.
+    #
+    class DestroyedImageError < BinMagickError
+      attr_reader :message
+
+      def initialize(message)
+        @message = message
+        super
+      end
+    end
+  end
+end

data/lib/rmagick/bin_magick/image_attr_methods.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "magick_wrapper"
+
+module Magick
+  module BinMagick
+    #
+    # Image attribute methods.
+    #
+    class Image < MagickWrapper
+      #
+      # Return image height.
+      #
+      # @return [Integer]
+      #
+      def height
+        rows
+      end
+
+      #
+      # Return image width.
+      #
+      # @return [Integer]
+      #
+      def width
+        columns
+      end
+    end
+  end
+end

data/lib/rmagick/bin_magick/image_class_methods.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Magick
+  module BinMagick
+    #
+    # Image class methods.
+    #
+    class Image < MagickWrapper
+      #
+      # Read image from a file.
+      #
+      # @param [String] filename
+      #
+      # @return [BinMagick::Image]
+      #
+      # @raise [BinMagick::IOError]
+      #
+      def self.from_file(filename)
+        image = Magick::Image.read(filename).first
+        new(image)
+      rescue Magick::ImageMagickError => e
+        raise BinMagick::IOError, "Error occurred while reading image from file: #{e.message}"
+      end
+    end
+  end
+end

data/lib/rmagick/bin_magick/image_inst_methods.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module Magick
+  module BinMagick
+    N_GRAY_COLORS = 64 # Default number of gray tones when image is being quantized to a grayscale.
+
+    #
+    # Image instance methods.
+    #
+    class Image < MagickWrapper
+      #
+      # Check if the image has at least one black pixel.
+      #
+      # @return [Boolean]
+      #
+      def black_px?
+        colors = color_histogram
+        colors = colors.transform_keys(&:to_color)
+
+        colors.key?("black")
+      end
+
+      #
+      # Crop border around the image. If the image is blank: return an unedited copy of the target image.
+      #
+      # @return [BinMagick::Image]
+      #   A cropped image.
+      #
+      def crop_border
+        return copy unless black_px?
+
+        bb = bounding_box
+
+        crop(
+          bb.x,
+          bb.y,
+          bb.width,
+          bb.height
+        )
+      end
+
+      #
+      # A bang version of the 'BinMagick::Image#crop_border'.
+      #
+      def crop_border!
+        cropped_img = crop_border
+        _replace_pixels(cropped_img)
+
+        self
+      end
+
+      #
+      # Crop border around the image, but treat a color image like it is already a binary one.
+      #
+      # See also: 'BinMagick::Image#to_binary' method description.
+      #
+      # @return [BinMagick::Image]
+      #   A cropped image.
+      #
+      def crop_border_clr(...)
+        bin_img = to_binary(...)
+
+        return copy unless bin_img.black_px?
+
+        bb = bin_img.bounding_box
+
+        crop(
+          bb.x,
+          bb.y,
+          bb.width,
+          bb.height
+        )
+      end
+
+      #
+      # A bang version of the 'BinMagick::Image#crop_border_clr'.
+      #
+      def crop_border_clr!(...)
+        cropped_img = crop_border_clr(...)
+        _replace_pixels(cropped_img)
+
+        self
+      end
+
+      #
+      # Workaround for the 'Magick::Image#display' method.
+      #
+      def display
+        pixels = @image.dispatch(0, 0, columns, rows, "RGB")
+        img = Magick::Image.constitute(columns, rows, "RGB", pixels)
+        img.display
+
+        self
+      end
+
+      #
+      # A bang version of the 'Magick::Image#extent'.
+      #
+      # @param [Integer] width
+      #
+      # @param [Integer] height
+      #
+      # @option [Integer] x (0)
+      #
+      # @option [Integer] y (0)
+      #
+      def extent!(width, height, x = 0, y = 0)
+        extended_img = @image.extent(width, height, x, y)
+        _replace_pixels(extended_img)
+
+        self
+      end
+
+      #
+      # Scale the image to fit into the size limits *IF* it oversize them.
+      #
+      # @param [Integer] max_width
+      #
+      # @param [Integer] max_height
+      #
+      # @return [BinMagick::Image]
+      #   A resized image.
+      #
+      def fit_to_size(max_width, max_height)
+        oversize?(max_width, max_height) ? resize_to_fit(max_width, max_height) : copy
+      end
+
+      #
+      # A bang version of the 'BinMagick::Image#fit_to_size'.
+      #
+      def fit_to_size!(...)
+        new_img = fit_to_size(...)
+        _replace_pixels(new_img)
+
+        self
+      end
+
+      #
+      # A bang version of the 'Magick::Image#level2'.
+      #
+      # Note: The 'Magick::Image#level2' method is exactly the same as 'Magick::Image#level' except that it never
+      # swaps the arguments.
+      #
+      def level!(black_point = 0.0, white_point = Magick::QuantumRange, gamma = 1.0)
+        new_img = @image.level2(black_point, white_point, gamma)
+        _replace_pixels(new_img)
+
+        self
+      end
+
+      #
+      # A bang version of the 'Magick::Image#ordered_dither'.
+      #
+      def ordered_dither!(threshold_map = "checks")
+        new_img = @image.ordered_dither(threshold_map)
+        _replace_pixels(new_img)
+
+        self
+      end
+
+      #
+      # Check if the image dimensions are larger than the provided height OR width.
+      #
+      # @return [Boolean]
+      #
+      def oversize?(max_width, max_height)
+        columns > max_width || rows > max_height
+      end
+
+      #
+      # A bang version of the 'Magick::Image#quantize'.
+      #
+      def quantize!(
+        number_colors = N_GRAY_COLORS,
+        colorspace = Magick::GRAYColorspace,
+        dither = Magick::NoDitherMethod,
+        tree_depth = 0,
+        measure_error = false
+      )
+        new_img = @image.quantize(number_colors, colorspace, dither, tree_depth, measure_error)
+        _replace_pixels(new_img)
+
+        self
+      end
+
+      #
+      # Convert a color image to a binary image.
+      #
+      # @option [Integer] n_gray_colors (N_GRAY_COLORS)
+      #   Number of grayscale colors when image is being quantized.
+      #
+      # @option [Magick::DitherMethod] quantize_dither (Magick::NoDitherMethod)
+      #   Error diffusion dither that will be applied on the color reduction step.
+      #
+      # @option [String] threshold_map ("checks")
+      #   Dither pattern for convertion from grayscale to binary.
+      #
+      # @return [BinMagick::Image]
+      #   Binary version of the image.
+      #
+      def to_binary(n_gray_colors = N_GRAY_COLORS, quantize_dither = Magick::NoDitherMethod, threshold_map = "checks")
+        grayscale_img = quantize(n_gray_colors, Magick::GRAYColorspace, quantize_dither)
+        grayscale_img.ordered_dither(threshold_map)
+      end
+
+      #
+      # A bang version of the 'BinMagick::Image#to_binary'.
+      #
+      def to_binary!(...)
+        bin_img = to_binary(...)
+        _replace_pixels(bin_img)
+
+        self
+      end
+
+      private
+
+      #
+      # Replace pixels in the target image with pixels from the image 'img' that is a result of a BinMagick::Image or
+      # a Magick::Image instance method call.
+      #
+      # Method used to create bang versions of the existing Magick::Image methods that do not have a bang version.
+      #
+      # @param [Magick::Image] img
+      #
+      def _replace_pixels(img)
+        pixels = img.dispatch(0, 0, img.columns, img.rows, "RGB")
+        @image = Magick::Image.constitute(img.columns, img.rows, "RGB", pixels)
+      end
+    end
+  end
+end

data/lib/rmagick/bin_magick/magick_wrapper.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Magick
+  module BinMagick
+    #
+    # A wrapper around the "Magick::Image" class, providing a dynamic interface for forwarding method calls to the
+    # underlying "Magick::Image" object. When a method is called on "MagickWrapper", it first checks if the
+    # underlying "Magick::Image" object responds to that method, and if so, it invokes the method on the object and
+    # returns the result.
+    #
+    # If the result is another "Magick::Image" object, it wraps it in a new "MagickWrapper" object, allowing chaining
+    # of method calls.
+    #
+    # If the result is not a "Magick::Image" object, it returns the result as is.
+    #
+    # If the underlying "Magick::Image" object does not respond to the method, it raises a "NoMethodError".
+    #
+    class MagickWrapper
+      attr_reader :image
+
+      def initialize(image)
+        raise BinMagick::DestroyedImageError, "Destroyed image" if image.destroyed?
+
+        @image = image
+      end
+
+      def method_missing(method_name, *args, &block)
+        if @image.respond_to?(method_name)
+          result = @image.send(method_name, *args, &block)
+          if result.is_a?(Magick::Image)
+            self.class.new(result)
+          else
+            result
+          end
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        @image.respond_to?(method_name) || super
+      end
+    end
+  end
+end

data/lib/rmagick/bin_magick/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Magick
+  module BinMagick
+    VERSION = "0.1.2"
+  end
+end

data/lib/rmagick/bin_magick.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "rmagick"
+
+require_relative "bin_magick/image_attr_methods"
+require_relative "bin_magick/image_class_methods"
+require_relative "bin_magick/image_inst_methods"
+require_relative "bin_magick/bin_magick_error"
+require_relative "bin_magick/magick_wrapper"
+require_relative "bin_magick/version"
+
+module Magick
+  module BinMagick; end
+end

data/rmagick-bin_magick.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "lib/rmagick/bin_magick/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "rmagick-bin_magick"
+  spec.version       = Magick::BinMagick::VERSION
+  spec.authors       = ["Mate"]
+
+  spec.summary       = "A tiny gem to create binary images (using RMagick)."
+  spec.homepage      = "https://github.com/8bit-mate/rmagick-bin_magick.rb"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.0.0")
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org/"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "https://github.com/8bit-mate/rmagick-bin_magick.rb/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features|data)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "rmagick", "~> 5.2", ">= 5.2.0"
+
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: rmagick-bin_magick
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Mate
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2023-04-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rmagick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.0
+description: 
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/rmagick/bin_magick.rb
+- lib/rmagick/bin_magick/bin_magick_error.rb
+- lib/rmagick/bin_magick/image_attr_methods.rb
+- lib/rmagick/bin_magick/image_class_methods.rb
+- lib/rmagick/bin_magick/image_inst_methods.rb
+- lib/rmagick/bin_magick/magick_wrapper.rb
+- lib/rmagick/bin_magick/version.rb
+- rmagick-bin_magick.gemspec
+homepage: https://github.com/8bit-mate/rmagick-bin_magick.rb
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org/
+  homepage_uri: https://github.com/8bit-mate/rmagick-bin_magick.rb
+  source_code_uri: https://github.com/8bit-mate/rmagick-bin_magick.rb
+  changelog_uri: https://github.com/8bit-mate/rmagick-bin_magick.rb/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key: 
+specification_version: 4
+summary: A tiny gem to create binary images (using RMagick).
+test_files: []