hexapdf 0.1.0

data/lib/hexapdf/content/color_space.rb

@@ -0,0 +1,364 @@
+# -*- encoding: utf-8 -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2016 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#++
+
+require 'hexapdf/error'
+
+module HexaPDF
+  module Content
+
+    # This module contains the color space implementations.
+    #
+    # == General Information
+    #
+    # The PDF specification defines several color spaces. Probably the most used ones are the
+    # device color spaces DeviceRGB, DeviceCMYK and DeviceGray. However, there are several others.
+    # For example, patterns are also implemented via color spaces.
+    #
+    # HexaPDF provides implementations for the most common color spaces. Additional ones can
+    # easily be added. After implementing one it just has to be registered on the global
+    # configuration object under the 'color_space.map' key.
+    #
+    # Color space implementations are currently used so that different colors can be
+    # distinguished and to provide better error handling.
+    #
+    #
+    # == Color Space Implementations
+    #
+    # A color space implementation consists of two classes: one for the color space and one for
+    # its colors.
+    #
+    # The class for the color space needs to respond to the following methods:
+    #
+    # #initialize(definition)::
+    #   Creates the color space using the given array with the color space definition. The first
+    #   item in the array is always the color space family, the other items are color space
+    #   specific.
+    #
+    # #family::
+    #   Returns the PDF name of the color space family this color space belongs to.
+    #
+    # #definition::
+    #   Returns the color space definition as array.
+    #
+    # #default_color::
+    #   Returns the default color for this color space.
+    #
+    # #color(*args)::
+    #   Returns the color corresponding to the given arguments. The number and types of the
+    #   arguments differ from one color space to another.
+    #
+    # The class representing a color in the color space needs to respond to the following methods:
+    #
+    # #color_space::
+    #   Returns the associated color space object.
+    #
+    # #components::
+    #   Returns an array of components that uniquely identifies this color within the color space.
+    #
+    # See: PDF1.7 s8.6
+    module ColorSpace
+
+      # This module includes utility functions that are useful for all color classes.
+      module ColorUtils
+
+        # Normalizes the given color value so that it is in the range from 0.0 to 1.0.
+        #
+        # The conversion is done in the following way:
+        #
+        # * If the color value is an Integer, it is converted to a float and divided by +upper+.
+        # * If the color value is greater than 1.0, it is set to 1.0.
+        # * If the color value is less than 0.0, it is set to 0.0.
+        def normalize_value(value, upper)
+          value = value.to_f / upper if value.kind_of?(Integer)
+          (value < 0 ? 0.0 : (value > 1 ? 1.0 : value))
+        end
+        private :normalize_value
+
+        # Compares this color to another one by looking at their associated color spaces and their
+        # components.
+        def ==(other)
+          other.respond_to?(:components) && other.respond_to?(:color_space) &&
+            components == other.components && color_space == other.color_space
+        end
+
+      end
+
+      # This class represents a "universal" color space that is used for all color spaces that
+      # aren't implemented yet.
+      class Universal
+
+        # The color space definition used for creating this universal color space.
+        attr_reader :definition
+
+        # Creates the universal color space for the given color space definition.
+        def initialize(definition)
+          @definition = definition
+        end
+
+        # The default universal color.
+        def default_color
+          Color.new(self)
+        end
+
+        # Creates a new universal color object. The number of arguments isn't restricted.
+        def color(*args)
+          Color.new(self, *args)
+        end
+
+        # Returns the PDF color space family this color space belongs to.
+        def family
+          @definition[0]
+        end
+
+        # Compares this universal color space to another one by looking at their definitions.
+        def ==(other)
+          other.kind_of?(self.class) && definition == other.definition
+        end
+
+        # A single color in the universal color space.
+        #
+        # This doesn't represent a real color but is a place holder for a color in a color space
+        # that isn't implemented yet.
+        class Color
+
+          include ColorUtils
+
+          # Returns the specific Universal color space used for this color.
+          attr_reader :color_space
+
+          # Creates a new universal color with the given components.
+          def initialize(color_space, *components)
+            @color_space = color_space
+            @components = components
+          end
+
+          # Returns the componets of the universal color, i.e. all arguments provided on
+          # initialization.
+          def components
+            @components
+          end
+
+        end
+
+      end
+
+
+      # The DeviceRGB color space.
+      class DeviceRGB
+
+        # The one (and only) DeviceRGB color space.
+        DEFAULT = new
+
+        # Returns the DeviceRGB color space object.
+        def self.new
+          DEFAULT
+        end
+
+        # Returns the default color for the DeviceRGB color space.
+        def default_color
+          Color.new(0.0, 0.0, 0.0)
+        end
+
+        # Returns the color object for the given red, green and blue components.
+        def color(r, g, b)
+          Color.new(r, g, b)
+        end
+
+        # Returns +:DeviceRGB+.
+        def family
+          :DeviceRGB
+        end
+
+        # A color in the DeviceRGB color space.
+        #
+        # Color values can either be integers in the range from 0 to 255 or floating point numbers
+        # between 0.0 and 1.0. The integer color values are automatically normalized to the
+        # DeviceRGB color value range of 0.0 to 1.0.
+        #
+        # See: PDF1.7 s8.6.4.3
+        class Color
+
+          include ColorUtils
+
+          # Initializes the color with the +r+ (red), +g+ (green) and +b+ (blue) components.
+          #
+          # Each argument has to be either an integer between 0 and 255 or a float between 0.0 and
+          # 1.0.
+          def initialize(r, g, b)
+            @r = normalize_value(r, 255)
+            @g = normalize_value(g, 255)
+            @b = normalize_value(b, 255)
+          end
+
+          # Returns the DeviceRGB color space module.
+          def color_space
+            DeviceRGB::DEFAULT
+          end
+
+          # Returns the RGB color as an array of normalized color values.
+          def components
+            [@r, @g, @b]
+          end
+
+        end
+
+      end
+
+
+      # The DeviceCMYK color space.
+      class DeviceCMYK
+
+        # The one (and only) DeviceCMYK color space.
+        DEFAULT = new
+
+        # Returns the DeviceCMYK color space object.
+        def self.new
+          DEFAULT
+        end
+
+        # Returns the default color for the DeviceCMYK color space.
+        def default_color
+          Color.new(0.0, 0.0, 0.0, 1.0)
+        end
+
+        # Returns the color object for the given cyan, magenta, yellow and black components.
+        def color(c, m, y, k)
+          Color.new(c, m, y, k)
+        end
+
+        # Returns +:DeviceCMYK+.
+        def family
+          :DeviceCMYK
+        end
+
+        # A color in the DeviceCMYK color space.
+        #
+        # Color values can either be integers in the range from 0 to 100 or floating point numbers
+        # between 0.0 and 1.0. The integer color values are automatically normalized to the
+        # DeviceCMYK color value range of 0.0 to 1.0.
+        #
+        # See: PDF1.7 s8.6.4.4
+        class Color
+
+          include ColorUtils
+
+          # Initializes the color with the +c+ (cyan), +m+ (magenta), +y+ (yellow) and +k+ (black)
+          # components.
+          #
+          # Each argument has to be either an integer between 0 and 100 or a float between 0.0 and
+          # 1.0.
+          def initialize(c, m, y, k)
+            @c = normalize_value(c, 100)
+            @m = normalize_value(m, 100)
+            @y = normalize_value(y, 100)
+            @k = normalize_value(k, 100)
+          end
+
+          # Returns the DeviceCMYK color space module.
+          def color_space
+            DeviceCMYK::DEFAULT
+          end
+
+          # Returns the CMYK color as an array of normalized color values.
+          def components
+            [@c, @m, @y, @k]
+          end
+
+        end
+
+      end
+
+
+      # The DeviceGray color space.
+      class DeviceGray
+
+        # The one (and only) DeviceGray color space.
+        DEFAULT = new
+
+        # Returns the DeviceGray color space object.
+        def self.new
+          DEFAULT
+        end
+
+        # Returns the default color for the DeviceGray color space.
+        def default_color
+          Color.new(0.0)
+        end
+
+        # Returns the color object for the given gray component.
+        def color(gray)
+          Color.new(gray)
+        end
+
+        # Returns +:DeviceGray+.
+        def family
+          :DeviceGray
+        end
+
+        # A color in the DeviceGray color space.
+        #
+        # Color values can either be integers in the range from 0 to 255 or floating point numbers
+        # between 0.0 and 1.0. The integer color values are automatically normalized to the
+        # DeviceGray color value range of 0.0 to 1.0.
+        #
+        # See: PDF1.7 s8.6.4.2
+        class Color
+
+          include ColorUtils
+
+          # Initializes the color with the +gray+ component.
+          #
+          # The argument +gray+ has to be either an integer between 0 and 255 or a float between
+          # 0.0 and 1.0.
+          def initialize(gray)
+            @gray = normalize_value(gray, 255)
+          end
+
+          # Returns the DeviceGray color space module.
+          def color_space
+            DeviceGray::DEFAULT
+          end
+
+          # Returns the normalized gray value as an array.
+          def components
+            [@gray]
+          end
+
+        end
+
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/content/graphic_object/arc.rb

@@ -0,0 +1,267 @@
+# -*- encoding: utf-8 -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2016 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#++
+
+require 'hexapdf/utils/math_helpers'
+
+module HexaPDF
+  module Content
+    module GraphicObject
+
+      # This class describes an elliptical in center parameterization arc that is approximated using
+      # Bezier curves. It can be used to draw circles, circular arcs, ellipses and elliptical arcs,
+      # all either in clockwise or counterclockwise direction and optionally inclined in respect to
+      # the x-axis.
+      #
+      # See: ELL - https://www.spaceroots.org/documents/ellipse/elliptical-arc.pdf
+      class Arc
+
+        include HexaPDF::Utils::MathHelpers
+
+        # Creates and configures a new elliptical arc object.
+        #
+        # See #configure for the allowed keyword arguments.
+        def self.configure(**kwargs)
+          new.configure(kwargs)
+        end
+
+        # The maximal number of curves used for approximating a complete ellipse.
+        #
+        # The higher the value the better the approximation will be but it will also take longer
+        # to compute. The value should not be lower than 4. Default value is 6 which already
+        # provides a good approximation.
+        attr_accessor :max_curves
+
+        # x-coordinate of center point
+        attr_reader :cx
+
+        # y-coordinate of center point
+        attr_reader :cy
+
+        # Length of semi-major axis
+        attr_reader :a
+
+        # Length of semi-minor axis
+        attr_reader :b
+
+        # Start angle in degrees
+        attr_reader :start_angle
+
+        # End angle in degrees
+        attr_reader :end_angle
+
+        # Inclination in degrees of semi-major axis in respect to x-axis
+        attr_reader :inclination
+
+        # Direction of arc - if +true+ in clockwise direction, else in counterclockwise direction
+        attr_reader :clockwise
+
+        # Creates an elliptical arc with default values (a counterclockwise unit circle at the
+        # origin).
+        def initialize
+          @max_curves = 6
+          @cx = @cy = 0
+          @a = @b = 1
+          @start_angle = 0
+          @end_angle = 360
+          @inclination = 0
+          @clockwise = false
+          calculate_cached_values
+        end
+
+        # Configures the arc with
+        #
+        # * center point (+cx+, +cy+),
+        # * semi-major axis +a+,
+        # * semi-minor axis +b+,
+        # * start angle of +start_angle+ degrees,
+        # * end angle of +end_angle+ degrees and
+        # * an inclination in respect to the x-axis of +inclination+ degrees.
+        #
+        # The +clockwise+ argument determines if the arc is drawn in the counterclockwise direction
+        # (+false+) or in the clockwise direction (+true+).
+        #
+        # Any arguments not specified are not modified and retain their old value, see #initialize
+        # for the inital values.
+        #
+        # Returns self.
+        def configure(cx: nil, cy: nil, a: nil, b: nil, start_angle: nil, end_angle: nil,
+                      inclination: nil, clockwise: nil)
+          @cx = cx if cx
+          @cy = cy if cy
+          @a = a.abs if a
+          @b = b.abs if b
+          if @a == 0 || @b == 0
+            raise HexaPDF::Error, "Semi-major and semi-minor axes must be greater than zero"
+          end
+          @start_angle = start_angle if start_angle
+          @end_angle = end_angle if end_angle
+          @inclination = inclination if inclination
+          @clockwise = clockwise unless clockwise.nil?
+          calculate_cached_values
+          self
+        end
+
+        # Returns the start point of the elliptical arc.
+        def start_point
+          evaluate(@start_eta)
+        end
+
+        # Returns the end point of the elliptical arc.
+        def end_point
+          evaluate(@end_eta)
+        end
+
+        # Returns the point at +angle+ degrees on the ellipse.
+        #
+        # Note that the point may not lie on the arc itself!
+        def point_at(angle)
+          evaluate(angle_to_param(angle))
+        end
+
+        # Draws the arc on the given Canvas.
+        #
+        # If the argument +move_to_start+ is +true+, a Canvas#move_to operation is executed to
+        # move the current point to the start point of the arc. Otherwise it is assumed that the
+        # current point already coincides with the start point
+        #
+        # The #max_curves value is set to the value of the configuration option
+        # 'graphic_object.arc.max_curves' before drawing.
+        def draw(canvas, move_to_start: true)
+          @max_curves = canvas.context.document.config['graphic_object.arc.max_curves']
+          canvas.move_to(*start_point) if move_to_start
+          curves.each {|curve| canvas.curve_to(*curve)}
+        end
+
+        # Returns an array of arrays that contain the points for the Bezier curves which are used
+        # for approximating the elliptical arc between #start_point and #end_point.
+        #
+        # One subarray consists of
+        #
+        #   [end_point_x, end_point_y, p1: control_point_1, p2: control_point_2]
+        #
+        # The first start point is the one returned by #start_point, the other start points are
+        # the end points of the curve before.
+        #
+        # The format of the subarray is chosen so that it can be fed to the Canvas#curve_to
+        # method by using array splatting.
+        #
+        # See: ELL s3.4.1 (especially the last box on page 18)
+        def curves
+          result = []
+
+          # Number of curves to use, maximal segment angle is 2*PI/max_curves
+          n = [@max_curves, ((@end_eta - @start_eta).abs / (2 * Math::PI / @max_curves)).ceil].min
+          d_eta = (@end_eta - @start_eta) / n
+
+          alpha = Math.sin(d_eta) * (Math.sqrt(4 + 3 * Math.tan(d_eta / 2)**2) - 1) / 3
+
+          eta2 = @start_eta
+          p2x, p2y = evaluate(eta2)
+          p2x_prime, p2y_prime = derivative_evaluate(eta2)
+          1.upto(n) do
+            p1x = p2x
+            p1y = p2y
+            p1x_prime = p2x_prime
+            p1y_prime = p2y_prime
+
+            eta2 += d_eta
+            p2x, p2y = evaluate(eta2)
+            p2x_prime, p2y_prime = derivative_evaluate(eta2)
+
+            result << [p2x, p2y,
+                       p1: [p1x + alpha * p1x_prime, p1y + alpha * p1y_prime],
+                       p2: [p2x - alpha * p2x_prime, p2y - alpha * p2y_prime]]
+          end
+
+          result
+        end
+
+        private
+
+        # Calculates the values that are derived from the input values and needed for the
+        # calculations
+        def calculate_cached_values
+          theta = deg_to_rad(@inclination)
+          @cos_theta = Math.cos(theta)
+          @sin_theta = Math.sin(theta)
+
+          # (see ELL s2.2.1) Calculating start_eta and end_eta so that
+          #   start_eta < end_eta   <= start_eta + 2*PI if counterclockwise
+          #   end_eta   < start_eta <= end_eta + 2*PI   if clockwise
+          @start_eta = angle_to_param(@start_angle)
+          @end_eta = angle_to_param(@end_angle)
+          if !@clockwise && @end_eta <= @start_eta
+            @end_eta += 2 * Math::PI
+          elsif @clockwise && @end_eta >= @start_eta
+            @start_eta += 2 * Math::PI
+          end
+        end
+
+        # Converts the +angle+ in degrees to the parameter used for the parametric function
+        # defining the ellipse.
+        #
+        # The return value is between 0 and 2*PI.
+        def angle_to_param(angle)
+          angle = deg_to_rad(angle % 360)
+          eta = Math.atan2(Math.sin(angle) / @b, Math.cos(angle) / @a)
+          eta += 2 * Math::PI if eta < 0
+          eta
+        end
+
+        # Returns an array containing the x and y coordinates of the point on the elliptical arc
+        # specified by the parameter +eta+.
+        #
+        # See: ELL s2.2.1 (3)
+        def evaluate(eta)
+          a_cos_eta = @a * Math.cos(eta)
+          b_sin_eta = @b * Math.sin(eta)
+          [@cx + a_cos_eta * @cos_theta - b_sin_eta * @sin_theta,
+           @cy + a_cos_eta * @sin_theta + b_sin_eta * @cos_theta]
+        end
+
+        # Returns an array containing the derivative of the parametric function defining the
+        # ellipse evaluated at +eta+.
+        #
+        # See: ELL s2.2.1 (4)
+        def derivative_evaluate(eta)
+          a_sin_eta = @a * Math.sin(eta)
+          b_cos_eta = @b * Math.cos(eta)
+          [- a_sin_eta * @cos_theta - b_cos_eta * @sin_theta,
+           - a_sin_eta * @sin_theta + b_cos_eta * @cos_theta]
+        end
+
+      end
+
+    end
+  end
+end