gifenc 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f67cc6f62dedeaa913d3de8a8729ff5af750799a5d9bbbd8b9693092fadc5ee
-  data.tar.gz: 7b22b1ca32a728372175f58affa8eeeaf495eff2f6357557b88554406ab4e375
+  metadata.gz: 5c38b840026c2289d2524c5e06bf2d1943b468662bd45a0f7abe456a6405badc
+  data.tar.gz: fc17037791eff68a2fec84b7689b082726e51aa1363b1e94885a9535f4b37db1
 SHA512:
-  metadata.gz: 14483dee19a0cfdc922d14f90816662ee13aeccbe78b247f69c84f805be243799c74141a169610f9420a935143744a85325e9ea57fa344e43c37e27631d3387d
-  data.tar.gz: 31a19387a6f2581f54ba6c1ad2fca893021b3e82c55d092adab6e274214f613fc3ccad52158e93c2dcdb51f4c9d1cfa7b839750af20949967cf5bc1bfca8a78f
+  metadata.gz: 54367e7f3751f0370fe6e4a297fb29b323a25d25ad9ef0e9a435ec8df3cc6010ff2f012d41cda0195cb8a42456069e15a03f3fdfd78f0990be1ecb78fd5f35f9
+  data.tar.gz: 12e4facd900f5628554bfc479044ffe33df18dfaf365586dbc259eeace2e643c9cecb6b187c7276f0eba64b04c1e4f987486635d0e4bae0d2572453d9b795962

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+### 0.2.1 (18/Mar/2024)
+
+Improved the image copy method. It now automatically corrects both source and destination offsets / dimensions to prevent any out of bounds errors, allows to specify a bounding box to which the copying should be restricted to, and allows to "copy with transparency", which will copy every color except for the transparent one.
+
 ### 0.2.0 (05/Mar/2024)
 
 A big update, with the main changes being divided in two categories: mathematical methods and drawing methods.
@@ -10,7 +14,7 @@ A big update, with the main changes being divided in two categories: mathematica
   * Point operations, such as translations, dilations / scalings, linear and convex combinations, scalar product, center of mass, etc.
   * Point transformations, such as rotations, projections and reflections.
   * Norms (L1, euclidean, supremum), normalization, distances.
-  * Angles, parallelism, orthonality, normal vectors...
+  * Angles, parallelism, orthogonality, normal vectors...
 
 - Significantly expanded the drawing functionality, including:
   * Improved line drawing, and added line styles (dashed, dotted, etc).
@@ -18,10 +22,11 @@ A big update, with the main changes being divided in two categories: mathematica
   * Added grids, polygonal chains and spirals.
   * Arbitrary parametric curves and function graphs given a lambda function.
   * Implemented the flood fill / bucket tool.
+  * Added a general Brush class to enable more flexible drawing.
 
 Many sample GIFs, showcasing all this new functionality, were added in the [Examples](https://github.com/edelkas/gifenc/tree/master/examples) folder as well.
 
-- Other functionality added includes:
+- Additional new functionality includes:
   * Copy: Ability to copy a region from one image to another.
   * Compress: Ability to LZW-compress image data on the fly, instead of keeping
     everything raw in memory until final encode time. Particularly helpful for

data/README.md

@@ -11,7 +11,7 @@ A pure Ruby library with no external dependencies that allows to encode, decode
 * Have a decent suite of editing functionalities, so that the need for external tools is avoided as much as possible.
 * Have a succint and comfortable syntax to use.
 
-Currently, the specs are almost fully supported for encoding. Decoding is not yet available, and the editing methods are very limited. See the [Reference](https://www.rubydoc.info/gems/gifenc) for the full documentation, as well as [Examples](https://github.com/edelkas/gifenc/tree/master/examples) for a list of sample snippets and GIFs.
+Currently, the specs are almost fully supported for encoding. Decoding is not yet available, but will be soon. There's a solid `Geometry` module and decent drawing functionality. See the [Reference](https://www.rubydoc.info/gems/gifenc) for the full documentation, as well as [Examples](https://github.com/edelkas/gifenc/tree/master/examples) for a list of sample snippets and GIFs.
 
 ## A first example
 
@@ -51,7 +51,7 @@ end
 gif.save('test.gif')
 ```
 
-Let's see a step-by-step overview, refer to the following sections for an in-depth explanation of the actual details for each of the topics involved.
+Let's see a step-by-step overview, refer to the documentation for an in-depth explanation of the actual details for each of the topics involved.
 1. The first thing we do is create two **Color Tables**, one with red shades, and another with green shades. Since GIF is an indexed image format, it can only use colors from predefined palettes of at most 256 colors. `Gifenc` comes equipped with several default ones, but you can build your own, and operate with them.
 2. We create the GIF object. We select the red color table to be the **GCT** (_Global Color Table_), which is used for all frames that do not contain an explicit **LCT** (_Local Color Table_). We also set the GIF to loop indefinitely.
 3. We create the first frame, this will act as the background. We use the green color table as LCT for this frame. We set a few attributes, such as the default color of the canvas, the length of the frame, and the color used for transparency. We draw a sequence of centered green squares, they will help to see the transparency of the next frames.

data/lib/geometry.rb

@@ -542,6 +542,26 @@ module Gifenc
       [x0, y0, x1 - x0 + 1, y1 - y0 + 1]
     end
 
+    # Calculate the intersection of multiple rectangles. The rectangles must be
+    # supplied in the usual format of bounding boxes, i.e. `[X, Y, W, H]`,
+    # where `X` and `Y` are the coordinates of the upper left corner of the
+    # rectangle with respect to the image, and `W` and `H` are the width and
+    # height of the rectangle, respectively. The result will be a rectangle
+    # in the same format, if the intersection is non-empty, or `nil` otherwise.
+    # @param rects [Array<Array<Float>>] The rectangles to intersect.
+    # @return [Array<Float>,nil] The resulting intersection.
+    def self.rect_overlap(*rects)
+      return if rects.empty?
+
+      rect = rects[0]
+      rects[1..-1].each{ |r|
+        rect = rect_overlap_two(rect, r)
+        return if !rect
+      }
+
+      rect
+    end
+
     # Translate a set of points according to a fixed vector. Given a list of
     # points `P1, ... , Pn` and a translation vector `t`, this method will
     # return the transformed list of points `P1 + t, ... , Pn + t`.
@@ -673,7 +693,8 @@ module Gifenc
     # Find the center of mass (barycenter) of a list of points. This will always
     # be contained within the convex hull of the supplied points.
     # @param points [Array<Point>] The list of points.
-    # @return [Point] 
+    # @return [Point] The center of mass of the points.
+    # @raise [Exception::GeometryError] If the list of points is empty.
     def self.center(points)
       raise Exception::GeometryError, "Cannot find center of empty list of points." if points.size == 0
       points.map!{ |p| Point.parse(p) }
@@ -690,5 +711,23 @@ module Gifenc
       (r.y - p.y) * (q.x - p.x) - (q.y - p.y) * (r.x - p.x)
     end
 
+    # Find overlap of 2 rectangles. Used recursively by rect_overlap to find
+    # overlap of N rectangles.
+    def self.rect_overlap_two(rect1, rect2)
+      return nil if !rect1 || !rect2
+
+      x_max = [rect1[0], rect2[0]].max
+      y_max = [rect1[1], rect2[1]].max
+      x_min = [rect1[0] + rect1[2], rect2[0] + rect2[2]].min
+      y_min = [rect1[1] + rect1[3], rect2[1] + rect2[3]].min
+
+      x = x_max
+      y = y_max
+      w = x_min - x_max
+      h = y_min - y_max
+
+      [w, h].min > PRECISION ? [x, y, w, h] : nil
+    end
+
   end # Module Geometry
 end # Module Gifenc

data/lib/gif.rb

@@ -177,7 +177,7 @@ module Gifenc
       @images.size.times.each{ |i|
         @images[i].encode(stream)
         if @destroy
-          @images[i].clear
+          @images[i].destroy
           @images[i] = nil
         end
       }

data/lib/image.rb

@@ -186,6 +186,7 @@ module Gifenc
     # @return (see #delay)
     # @see (see #delay)
     def delay=(value)
+      return if !value
       @gce = Extension::GraphicControl.new if !@gce
       @gce.delay = value
     end
@@ -207,6 +208,7 @@ module Gifenc
     # @return (see #disposal)
     # @see (see #disposal)
     def disposal=(value)
+      return if !value
       @gce = Extension::GraphicControl.new if !@gce
       @gce.disposal = value
     end
@@ -226,6 +228,7 @@ module Gifenc
     # @return (see #trans_color)
     # @see (see #trans_color)
     def trans_color=(value)
+      return if !value
       @gce = Extension::GraphicControl.new if !@gce
       @gce.trans_color = value
     end
@@ -268,49 +271,105 @@ module Gifenc
       self
     end
 
-    # Clear the pixel data of the image. This simply substitutes the contents
+    # Destroy the pixel data of the image. This simply substitutes the contents
     # of the array, hoping that the underlying data will go out of scope and
     # be collected by the garbage collector. This is intended for freeing
     # space and to simulate "destroying" the image.
     # @return (see #initialize)
-    def clear
+    def destroy
       @pixels = nil
       self
     end
 
-    # Copy a rectangular region from another image to this one. The offsets and
-    # dimensions of the region can be specified.
+    # Paint the whole canvas with the base image color.
+    # @return (see #initialize)
+    def clear
+      @pixels = [@color] * (@width * @height)
+      self
+    end
+
+    # Copy a rectangular region from another image to this one. The dimension of
+    # the region, as well as the source offset and the destination offset, can
+    # be provided. If the region would go out of bounds, the function will
+    # just gracefully crop it rather than failing. Additionally, a more restrictive
+    # bounding box (smaller than the full image) can also be provided, to where
+    # the copying will be confined.
     # @note The two images are assumed to have the same color table, since what
     #   is copied is the color indexes.
-    # @param source [Image] The source image to copy the contents from.
+    # @param src [Image] The source image to copy the contents from.
     # @param offset [Array<Integer>] The coordinates of the offset of the region
     #   in the source image.
     # @param dim [Array<Integer>] The dimensions of the region, in the form `[W, H]`,
-    #   where W is the width and H is the height of the rectangle to copy.
+    #   where W is the width and H is the height of the rectangle to copy. If
+    #   unspecified (`nil`), the whole source image will be copied.
     # @param dest [Array<Integer>] The coordinates of the destination offset of
     #   the region in this image.
-    # @raise [Exception::CanvasError] If the region is out of bounds in either
-    #   the source or the destination images.
+    # @param trans [Boolean] If enabled, the pixels from the source image whose
+    #   color is the transparent one (for the source image) won't be copied over,
+    #   effectively achieving the usual GIF composition with basic transparency.
+    #   It's a bit slower as a consequence.
+    # @param bbox [Array<Integer>] The bounding box (with respect to this image)
+    #   where the copying should be restricted to. Everything outside this region
+    #   will be left untouched. If unspecified (`nil`), this will be the whole
+    #   image. As usual, the format is `[X, Y, W, H]`, where `[X, Y]` are the
+    #   coordinates of the upper left pixel, and `[W, H]` are the pixel width
+    #   and height, respectively.
+    # @raise [Exception::CanvasError] If no source provided.
     # @return (see #initialize)
-    def copy(source: nil, offset: [0, 0], dim: [1, 1], dest: [0, 0])
-      offset = Geometry::Point.parse(offset)
-      dim    = Geometry::Point.parse(dim)
-      dest   = Geometry::Point.parse(dest)
-      if !source.bound_check(offset) || !source.bound_check(offset + dim - [1, 1])
-        raise Exception::CanvasError, "Cannot copy, region out of bounds in source image."
-      end
-      if !bound_check(dest) || !bound_check(dest + dim - [1, 1])
-        raise Exception::CanvasError, "Cannot copy, region out of bounds in destination image."
+    def copy(src: nil, offset: [0, 0], dim: nil, dest: [0, 0], trans: false, bbox: nil)
+      raise Exception::CanvasError, "Cannot copy, no source provided." if !src
+
+      # Parse parameters
+      bbox   = [0, 0, @width, @height] unless bbox
+      dim    = [src.width, src.height] unless dim
+      offset = Geometry::Point.parse(offset).round
+      dim    = Geometry::Point.parse(dim).round
+      dest   = Geometry::Point.parse(dest).round
+
+      # Normalize main bbox
+      bbox = Geometry.rect_overlap(bbox, [0, 0, @width, @height])
+      return if !bbox
+      bbox.map!(&:round)
+
+      # Normalize source bbox
+      src_bbox  = [offset.x, offset.y, dim.x, dim.y]
+      src_bbox  = Geometry.rect_overlap(src_bbox, [0, 0, src.width, src.height])
+      return if !src_bbox
+      offset    = Geometry::Point.parse(src_bbox[0, 2])
+      dim       = Geometry::Point.parse(src_bbox[2, 2])
+
+      # Normalize destination bbox
+      dest_bbox = [dest.x, dest.y, dim.x, dim.y]
+      overlap = Geometry.rect_overlap(dest_bbox, bbox)
+      return if !dest_bbox
+      dest      = Geometry::Point.parse(overlap[0, 2])
+      dim       = Geometry::Point.parse(overlap[2, 2])
+
+      # Transform coordinates of source to coordinates of destination
+      offset += Gifenc::Geometry.transform([dest], dest_bbox)[0]
+
+      # Handy fetch
+      dx, dy = dest.x.round,   dest.y.round
+      ox, oy = offset.x.round, offset.y.round
+      lx, ly = dim.x.round,    dim.y.round
+      bg = src.trans_color
+
+      # Copy pixel data. We use a different, slightly faster, algorithm if we
+      # don't have a bg color check to make, by directly copying full rows.
+      if trans && bg
+        c = nil
+        ly.times.each{ |y|
+          lx.times.each{ |x|
+            c = src[ox + x, oy + y]
+            self[dx + x, dy + y] = c unless c == bg
+          }
+        }
+      else
+        ly.times.each{ |y|
+          @pixels[(dy + y) * @width + dx, lx] = src.pixels[(oy + y) * src.width + ox, lx]
+        }
       end
 
-      dx = dest.x.round
-      dy = dest.y.round
-      ox = offset.x.round
-      oy = offset.y.round
-      dim.y.round.times.each{ |y|
-        @pixels[(dy + y) * @width + dx, dim.x.round] = source.pixels[(oy + y) * source.width + ox, dim.x.round]
-      }
-
       self
     end
 
@@ -459,9 +518,11 @@ module Gifenc
     #   indicates the position of the line with respect to the coordinates. It
     #   must be in the interval [-1, 1]. A value of `0` centers the line in its
     #   width, a value of `-1` draws it on one side, and `1` on the other.
-    # @param bbox [Array<Integer>] Bounding box determining the region in which
-    #   the line must be contained. Anything outside it won't be drawn. If
-    #   `nil`, this defaults to the whole image.
+    # @param bbox [Array<Integer>] Bounding box determining the region to which
+    #   the drawing will be restricted, in the format `[X, Y, W, H]`, where `[X, Y]`
+    #   are the coordinates of the upper left corner of the box, and `[W, H]` are
+    #   the pixel dimensions. If unspecified (`nil`), this defaults to the whole
+    #   image.
     # @param avoid [Array<Integer>] List of colors over which the line should
     #   NOT be drawn.
     # @param style [Symbol] Named style / pattern of the line. Can be `:solid`
@@ -530,19 +591,29 @@ module Gifenc
     #   * For `0` the border is centered around the boundary.
     #   * For `1` the border is entirely contained within the boundary.
     #   * For `-1` the border is entirely surrounding the boundary.
+    # @param style [Symbol] Border line style (`:solid`, `:dashed`, `:dotted`).
+    #   See `style` param in {#line}).
+    # @param density [Symbol] Border line pattern density (`:normal`, `:dense`,
+    #   `:loose`). See `density` param in {#line}.
+    # @param bbox [Array<Integer>] Bounding box determining the region to which
+    #   the drawing will be restricted. See `bbox` param in {#line}.
     # @return (see #initialize)
     # @raise [Exception::CanvasError] If the rectangle would go out of bounds.
     def rect(x, y, w, h, stroke = nil, fill = nil, weight: 1, anchor: 1,
-      style: :solid, density: :normal)
-      # Check coordinates
-      x = x.round
-      y = y.round
-      w = w.round
-      h = h.round
-      x0, y0, x1, y1 = x, y, x + w - 1, y + h - 1
-      if !Geometry.bound_check([[x0, y0], [x1, y1]], self, true)
-        raise Exception::CanvasError, "Rectangle out of bounds."
-      end
+      style: :solid, density: :normal, bbox: nil)
+      # Normalize bbox
+      bbox = [0, 0, @width, @height] unless bbox
+      bbox = Geometry.rect_overlap(bbox, [0, 0, @width, @height])
+      return if !bbox
+      bbox.map!(&:round)
+
+      # Intersect bbox with rectangle
+      rect_bbox = Geometry.rect_overlap(bbox, [x, y, w, h])
+      return if !rect_bbox
+      x0 = rect_bbox[0].round
+      y0 = rect_bbox[1].round
+      x1 = (rect_bbox[0] + rect_bbox[2]).round - 1
+      y1 = (rect_bbox[1] + rect_bbox[3]).round - 1
 
       # Fill rectangle, if provided
       if fill
@@ -559,7 +630,7 @@ module Gifenc
           o = ((weight - 1) / 2.0 * anchor).round
           w -= 2 * o - (weight % 2 == 0 ? 1 : 0)
           h -= 2 * o - (weight % 2 == 0 ? 1 : 0)
-          rect(x + o, y + o, w, h, stroke, weight: weight, anchor: 0)
+          rect(x0 + o, y0 + o, w, h, stroke, weight: weight, anchor: 0)
         else
           points = [[x0, y0], [x1, y0], [x1, y1], [x0, y1]]
           4.times.each{ |i|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gifenc
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - edelkas
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-03-05 00:00:00.000000000 Z
+date: 2024-03-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lzwrb
@@ -27,12 +27,12 @@ dependencies:
 description: |2
       This library provides GIF encoding, decoding and editing capabilities natively
       within Ruby. It aims to support the complete GIF specification for both
-      encoding and decoding, as well as having a decent editing functionality, while
+      encoding and decoding, as well as having decent editing functionality, while
       maintaining a succint syntax.
 
-      The current version is still preliminar, and only encoding is working, together
-      with a decent drawing suite. The gem is actively developed and decoding will
-      soon follow, so stay tuned if you're interested!
+      The current version only supports encoding, together with a decent drawing suite
+      The gem is actively developed and decoding will soon follow, so stay tuned
+      if you're interested!
 email: 
 executables: []
 extensions: []