hexapdf 0.32.1 → 0.33.0

data/lib/hexapdf/content/color_space.rb

@@ -87,6 +87,9 @@ module HexaPDF
     #   Returns the color corresponding to the given arguments without applying value normalization.
     #   The number and types of the arguments differ from one color space to another.
     #
+    #   This method should be used when the arguments are already normalized (e.g. when loaded from
+    #   a content stream).
+    #
     # The class representing a color in the color space needs to respond to the following methods:
     #
     # #color_space::
@@ -95,24 +98,26 @@ module HexaPDF
     # #components::
     #   Returns an array of components that uniquely identifies this color within the color space.
     #
-    # See: PDF1.7 s8.6
+    # See: PDF2.0 s8.6
     module ColorSpace
 
-      # Mapping of CSS Color Module Level 3 names to RGB values.
+      # Mapping of color names (CSS Color Module Level 3 names - see
+      # https://www.w3.org/TR/css-color-3/#svg-color - and HexaPDF design color names) to RGB and
+      # gray values.
       #
       # Visual listing of all colors:
       #
       #   #>pdf-big
-      #   canvas.font("Helvetica", size: 8)
-      #   map = HexaPDF::Content::ColorSpace::CSS_COLOR_NAMES
-      #   map.each_slice(38).each_with_index do |slice, col|
+      #   canvas.font("Helvetica", size: 7.5)
+      #   map = HexaPDF::Content::ColorSpace::COLOR_NAMES
+      #   map.each_slice(43).each_with_index do |slice, col|
       #     x = 10 + col * 100
       #     slice.each_with_index do |(name, rgb), row|
-      #       canvas.fill_color(rgb).rectangle(x, 380 - row * 10, 10, 10).fill
-      #       canvas.fill_color("black").text(name, at: [x + 15, 380 - row * 10 + 2])
+      #       canvas.fill_color(rgb).rectangle(x, 380 - row * 9, 9, 9).fill
+      #       canvas.fill_color("black").text(name, at: [x + 15, 380 - row * 9 + 2])
       #     end
       #   end
-      CSS_COLOR_NAMES = {
+      COLOR_NAMES = {
         "aliceblue" => [240, 248, 255],
         "antiquewhite" => [250, 235, 215],
         "aqua" => [0, 255, 255],
@@ -137,9 +142,9 @@ module HexaPDF
         "darkblue" => [0, 0, 139],
         "darkcyan" => [0, 139, 139],
         "darkgoldenrod" => [184, 134, 11],
-        "darkgray" => [169, 169, 169],
+        "darkgray" => [169],
         "darkgreen" => [0, 100, 0],
-        "darkgrey" => [169, 169, 169],
+        "darkgrey" => [169],
         "darkkhaki" => [189, 183, 107],
         "darkmagenta" => [139, 0, 139],
         "darkolivegreen" => [85, 107, 47],
@@ -155,8 +160,8 @@ module HexaPDF
         "darkviolet" => [148, 0, 211],
         "deeppink" => [255, 20, 147],
         "deepskyblue" => [0, 191, 255],
-        "dimgray" => [105, 105, 105],
-        "dimgrey" => [105, 105, 105],
+        "dimgray" => [105],
+        "dimgrey" => [105],
         "dodgerblue" => [30, 144, 255],
         "firebrick" => [178, 34, 34],
         "floralwhite" => [255, 250, 240],
@@ -166,10 +171,10 @@ module HexaPDF
         "ghostwhite" => [248, 248, 255],
         "gold" => [255, 215, 0],
         "goldenrod" => [218, 165, 32],
-        "gray" => [128, 128, 128],
+        "gray" => [128],
         "green" => [0, 128, 0],
         "greenyellow" => [173, 255, 47],
-        "grey" => [128, 128, 128],
+        "grey" => [128],
         "honeydew" => [240, 255, 240],
         "hotpink" => [255, 105, 180],
         "indianred" => [205, 92, 92],
@@ -184,7 +189,7 @@ module HexaPDF
         "lightcoral" => [240, 128, 128],
         "lightcyan" => [224, 255, 255],
         "lightgoldenrodyellow" => [250, 250, 210],
-        "lightgray" => [211, 211, 211],
+        "lightgray" => [211],
         "lightgreen" => [144, 238, 144],
         "lightgrey" => [211, 211, 211],
         "lightpink" => [255, 182, 193],
@@ -260,6 +265,24 @@ module HexaPDF
         "whitesmoke" => [245, 245, 245],
         "yellow" => [255, 255, 0],
         "yellowgreen" => [154, 205, 50],
+        "hp-blue" => [0, 128, 255],
+        "hp-blue-dark" => [28, 91, 216],
+        "hp-blue-dark2" => [34, 57, 184],
+        "hp-blue-light" => [86, 176, 255],
+        "hp-blue-light2" => [185, 220, 255],
+        "hp-orange" => [255, 128, 0],
+        "hp-orange-light" => [255, 195, 29],
+        "hp-orange-light2" => [255, 246, 153],
+        "hp-teal" => [0, 140, 130],
+        "hp-teal-dark" => [5, 100, 94],
+        "hp-teal-dark2" => [6, 70, 63],
+        "hp-teal-light" => [75, 177, 176],
+        "hp-teal-light2" => [177, 221, 221],
+        "hp-gray" => [158],
+        "hp-gray-dark" => [97],
+        "hp-gray-dark2" => [33],
+        "hp-gray-light" => [224],
+        "hp-gray-light2" => [245],
       }.freeze
 
       # :call-seq:
@@ -269,7 +292,7 @@ module HexaPDF
       #   ColorSpace.device_color_from_specification(string)         => color
       #   ColorSpace.device_color_from_specification(array)          => color
       #
-      # Creates a device color object from the given color specification.
+      # Creates and returns a device color object from the given color specification.
       #
       # There are several ways to define the color that should be used:
       #
@@ -279,8 +302,8 @@ module HexaPDF
       #   for the green and "BB" for the blue color value also specifies an RGB color.
       # * As does a string in the format "RGB" where "RR", "GG" and "BB" would be used as the
       #   hexadecimal numbers for the red, green and blue color values of an RGB color.
-      # * Any other string is treated as a CSS Color Module Level 3 color name, see
-      #   https://www.w3.org/TR/css-color-3/#svg-color.
+      # * Any other string is treated as a color name (CSS Color Module Level 3 and HexaPDF design
+      #   color names are supported - see COLOR_NAMES).
       # * Four numeric arguments specify a CMYK color (see DeviceCMYK::Color).
       # * An array is treated as if its items were specified separately as arguments.
       #
@@ -288,7 +311,30 @@ module HexaPDF
       # values are first normalized (expected range by the PDF specification is 0.0 - 1.0) - see
       # DeviceGray#color, DeviceRGB#color and DeviceCMYK#color for details.
       #
-      # For examples see HexaPDF::Content::Canvas#stroke_color.
+      # Examples:
+      #
+      #   #>pdf
+      #   cs = HexaPDF::Content::ColorSpace
+      #   canvas.line_width(5)
+      #
+      #   # Note that Canvas#stroke_color implicitly uses this method, so
+      #   # explicitly using it like in this example is not needed
+      #   canvas.stroke_color(cs.device_color_from_specification(160))
+      #   canvas.line(10, 10, 10, 190).stroke
+      #   canvas.stroke_color(cs.device_color_from_specification(0, 128, 255))
+      #   canvas.line(35, 10, 35, 190).stroke
+      #   canvas.stroke_color(cs.device_color_from_specification("0088FF"))
+      #   canvas.line(60, 10, 60, 190).stroke
+      #   canvas.stroke_color(cs.device_color_from_specification("08F"))
+      #   canvas.line(85, 10, 85, 190).stroke
+      #   canvas.stroke_color(cs.device_color_from_specification("gold"))
+      #   canvas.line(110, 10, 110, 190).stroke
+      #   canvas.stroke_color(cs.device_color_from_specification("hp-blue"))
+      #   canvas.line(135, 10, 135, 190).stroke
+      #   canvas.stroke_color(cs.device_color_from_specification(10, 50, 0, 60))
+      #   canvas.line(160, 10, 160, 190).stroke
+      #   canvas.stroke_color(cs.device_color_from_specification([0, 128, 255]))
+      #   canvas.line(185, 10, 185, 190).stroke
       def self.device_color_from_specification(*spec)
         spec.flatten!
         first_item = spec[0]
@@ -297,10 +343,11 @@ module HexaPDF
                    first_item.scan(/../).map!(&:hex)
                  elsif first_item.match?(/\A\h{3}\z/)
                    first_item.each_char.map {|x| (x * 2).hex }
-                 elsif CSS_COLOR_NAMES.key?(first_item)
-                   CSS_COLOR_NAMES[first_item]
+                 elsif COLOR_NAMES.key?(first_item)
+                   COLOR_NAMES[first_item]
                  else
-                   raise ArgumentError, "Given string is neither a hex color nor a color name"
+                   raise ArgumentError, "Given string '#{first_item}' is neither a hex color " \
+                     "nor a color name"
                  end
         end
         GlobalConfiguration.constantize('color_space.map', for_components(spec)).new.color(*spec)
@@ -470,7 +517,7 @@ module HexaPDF
 
         # A color in the DeviceRGB color space.
         #
-        # See: PDF1.7 s8.6.4.3
+        # See: PDF2.0 s8.6.4.3
         class Color
 
           include ColorUtils
@@ -540,7 +587,7 @@ module HexaPDF
 
         # A color in the DeviceCMYK color space.
         #
-        # See: PDF1.7 s8.6.4.4
+        # See: PDF2.0 s8.6.4.4
         class Color
 
           include ColorUtils
@@ -610,7 +657,7 @@ module HexaPDF
 
         # A color in the DeviceGray color space.
         #
-        # See: PDF1.7 s8.6.4.2
+        # See: PDF2.0 s8.6.4.2
         class Color
 
           include ColorUtils

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

@@ -45,6 +45,9 @@ module HexaPDF
       # all either in clockwise or counterclockwise direction and optionally inclined in respect to
       # the x-axis.
       #
+      # Note that only the path of the arc itself is added to the canvas. So depending on the
+      # use-case the path itself still has to be, for example, stroked.
+      #
       # This graphic object is registered under the :arc key for use with the
       # HexaPDF::Content::Canvas class.
       #
@@ -75,66 +78,64 @@ module HexaPDF
         # Examples:
         #
         #   #>pdf-center
-        #   arc = canvas.graphic_object(:arc, cx: -50, a: 40, b: 40)
-        #   arc.max_curves = 2
+        #   arc = canvas.graphic_object(:arc, cx: -50, a: 40, b: 40, max_curves: 2)
         #   canvas.draw(arc)
-        #   arc.max_curves = 10
-        #   canvas.draw(arc, cx: 50)
+        #   canvas.draw(arc, cx: 50, max_curves: 10)
         #   canvas.stroke
         attr_accessor :max_curves
 
-        # x-coordinate of center point
+        # x-coordinate of center point, defaults to 0.
         #
         # Examples:
         #
         #   #>pdf-center
         #   arc = canvas.graphic_object(:arc, a: 30, b: 20)
         #   canvas.draw(arc).stroke
-        #   canvas.stroke_color("red").draw(arc, cx: -50).stroke
+        #   canvas.stroke_color("hp-blue").draw(arc, cx: 50).stroke
         attr_reader :cx
 
-        # y-coordinate of center point
+        # y-coordinate of center point, defaults to 0.
         #
         # Examples:
         #
         #   #>pdf-center
         #   arc = canvas.graphic_object(:arc, a: 30, b: 20)
         #   canvas.draw(arc).stroke
-        #   canvas.stroke_color("red").draw(arc, cy: 50).stroke
+        #   canvas.stroke_color("hp-blue").draw(arc, cy: 50).stroke
         attr_reader :cy
 
         # Length of semi-major axis which (without altering the #inclination) is parallel to the
-        # x-axis
+        # x-axis, defaults to 1.
         #
         # Examples:
         #
         #   #>pdf-center
         #   arc = canvas.graphic_object(:arc, a: 30, b: 30)
         #   canvas.draw(arc).stroke
-        #   canvas.stroke_color("red").draw(arc, a: 60).stroke
+        #   canvas.stroke_color("hp-blue").draw(arc, a: 60).stroke
         attr_reader :a
 
         # Length of semi-minor axis which (without altering the #inclination) is parallel to the
-        # y-axis
+        # y-axis, defaults to 1.
         #
         # Examples:
         #
         #   #>pdf-center
         #   arc = canvas.graphic_object(:arc, a: 30, b: 30)
         #   canvas.draw(arc).stroke
-        #   canvas.stroke_color("red").draw(arc, b: 60).stroke
+        #   canvas.stroke_color("hp-blue").draw(arc, b: 60).stroke
         attr_reader :b
 
-        # Start angle of the arc in degrees
+        # Start angle of the arc in degrees, defaults to 0.
         #
         # Examples:
         #
         #   #>pdf-center
         #   arc = canvas.graphic_object(:arc, a: 30, b: 30)
-        #   canvas.draw(arc, start_angle: 45).stroke
+        #   canvas.draw(arc, start_angle: 110).stroke
         attr_reader :start_angle
 
-        # End angle of the arc in degrees
+        # End angle of the arc in degrees, defaults to 0.
         #
         # Examples:
         #
@@ -143,7 +144,7 @@ module HexaPDF
         #   canvas.draw(arc, end_angle: 160).stroke
         attr_reader :end_angle
 
-        # Inclination in degrees of the semi-major axis with respect to the x-axis
+        # Inclination in degrees of the semi-major axis with respect to the x-axis, defaults to 0.
         #
         # Examples:
         #
@@ -153,6 +154,7 @@ module HexaPDF
         attr_reader :inclination
 
         # Direction of arc - if +true+ in clockwise direction, else in counterclockwise direction
+        # (the default).
         #
         # This is needed when filling paths using the nonzero winding number rule to achieve
         # different effects.
@@ -161,7 +163,8 @@ module HexaPDF
         #
         #   #>pdf-center
         #   arc = canvas.graphic_object(:arc, a: 40, b: 40)
-        #   canvas.draw(arc, cx: -50).draw(arc, cx: 50).
+        #   canvas.fill_color("hp-blue").
+        #     draw(arc, cx: -50).draw(arc, cx: 50).
         #     draw(arc, cx: -50, b: 80).
         #     draw(arc, cx: 50, b: 80, clockwise: true).
         #     fill(:nonzero)
@@ -192,17 +195,27 @@ module HexaPDF
         # * 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.
+        # * an inclination in respect to the x-axis of +inclination+ degrees,
+        # * as well as the maximal number of curves +max_curves+ used for approximation.
         #
         # The +clockwise+ argument determines if the arc is drawn in the counterclockwise direction
         # (+false+) or in the clockwise direction (+true+).
         #
+        # For the meaning of +max_curves+ see the description of #max_curves.
+        #
         # Any arguments not specified are not modified and retain their old value, see #initialize
         # for the inital values.
         #
         # Returns self.
+        #
+        # Examples:
+        #
+        #   #>pdf-center
+        #   arc = canvas.graphic_object(:arc)
+        #   arc.configure(cx: 50, a: 40, b: 20, inclination: 10)
+        #   canvas.draw(arc).stroke
         def configure(cx: nil, cy: nil, a: nil, b: nil, start_angle: nil, end_angle: nil,
-                      inclination: nil, clockwise: nil)
+                      inclination: nil, clockwise: nil, max_curves: nil)
           @cx = cx if cx
           @cy = cy if cy
           @a = a.abs if a
@@ -214,6 +227,7 @@ module HexaPDF
           @end_angle = end_angle if end_angle
           @inclination = inclination if inclination
           @clockwise = clockwise unless clockwise.nil?
+          @max_curves = max_curves if max_curves
           calculate_cached_values
           self
         end
@@ -225,7 +239,7 @@ module HexaPDF
         #   #>pdf-center
         #   arc = canvas.graphic_object(:arc, a: 40, b: 30, start_angle: 60)
         #   canvas.draw(arc).stroke
-        #   canvas.fill_color("red").circle(*arc.start_point, 2).fill
+        #   canvas.fill_color("hp-blue").circle(*arc.start_point, 2).fill
         def start_point
           evaluate(@start_eta)
         end
@@ -237,7 +251,7 @@ module HexaPDF
         #   #>pdf-center
         #   arc = canvas.graphic_object(:arc, a: 40, b: 30, end_angle: 245)
         #   canvas.draw(arc).stroke
-        #   canvas.fill_color("red").circle(*arc.end_point, 2).fill
+        #   canvas.fill_color("hp-blue").circle(*arc.end_point, 2).fill
         def end_point
           evaluate(@end_eta)
         end
@@ -245,18 +259,37 @@ module HexaPDF
         # Returns the point at +angle+ degrees on the ellipse.
         #
         # Note that the point may not lie on the arc itself!
+        #
+        # Examples:
+        #
+        #   #>pdf-center
+        #   arc = canvas.graphic_object(:arc, a: 40, b: 30, end_angle: 245)
+        #   canvas.draw(arc).stroke
+        #   canvas.fill_color("hp-blue").
+        #     circle(*arc.point_at(150), 2).
+        #     circle(*arc.point_at(290), 2).
+        #     fill
         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
+        # 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. This functionality is used, for example, by
+        # the SolidArc implementation.
         #
         # The #max_curves value, if not already changed, is set to the value of the configuration
         # option 'graphic_object.arc.max_curves' before drawing.
+        #
+        # Examples:
+        #
+        #   #>pdf-center
+        #   arc = canvas.graphic_object(:arc, a: 40, b: 30)
+        #   canvas.stroke_color("hp-blue").move_to(-50, 0)
+        #   arc.draw(canvas, move_to_start: false)
+        #   canvas.stroke
         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

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

@@ -41,7 +41,12 @@ module HexaPDF
     module GraphicObject
 
       # This class describes an elliptical arc in endpoint parameterization. It allows one to
-      # generate an arc from the current point to a given point, similar to Content::Canvas#line_to.
+      # generate an arc from the current point to a given point, similar to Canvas#line_to. Behind
+      # the scenes the endpoint parameterization is turned into a center parameterization and drawn
+      # with Arc.
+      #
+      # Note that only the path of the arc itself is added to the canvas. So depending on the
+      # use-case the path itself still has to be, for example, stroked.
       #
       # This graphic object is registered under the :endpoint_arc key for use with the
       # HexaPDF::Content::Canvas class.
@@ -52,10 +57,12 @@ module HexaPDF
       #   arc = canvas.graphic_object(:endpoint_arc, x: 50, y: 20, a: 30, b: 10)
       #   canvas.move_to(0, 0).draw(arc).stroke
       #
-      # See: GraphicObject::Arc, ARC - https://www.w3.org/TR/SVG/implnote.html#ArcImplementationNotes
+      # See: Arc, ARC - https://www.w3.org/TR/SVG/implnote.html#ArcImplementationNotes (in the
+      # version of about 2016, see
+      # https://web.archive.org/web/20160310153722/https://www.w3.org/TR/SVG/implnote.html).
       class EndpointArc
 
-        EPSILON = 1e-10
+        EPSILON = 1e-10 # :nodoc:
 
         include Utils::MathHelpers
 
@@ -66,80 +73,95 @@ module HexaPDF
           new.configure(**kwargs)
         end
 
-        # x-coordinate of endpoint
+        # x-coordinate of endpoint, defaults to 0.
         #
         # Examples:
         #
         #   #>pdf-center
         #   arc = canvas.graphic_object(:endpoint_arc, x: 50, y: 20, a: 30, b: 20)
         #   canvas.move_to(0, 0).draw(arc).stroke
-        #   canvas.stroke_color("red").move_to(0, 0).draw(arc, x: -50).stroke
+        #   canvas.stroke_color("hp-blue").move_to(0, 0).draw(arc, x: -50).stroke
         attr_reader :x
 
-        # y-coordinate of endpoint
+        # y-coordinate of endpoint, defaults to 0.
         #
         # Examples:
         #
         #   #>pdf-center
         #   arc = canvas.graphic_object(:endpoint_arc, x: 50, y: 20, a: 30, b: 20)
         #   canvas.move_to(0, 0).draw(arc).stroke
-        #   canvas.stroke_color("red").move_to(0, 0).draw(arc, y: -20).stroke
+        #   canvas.stroke_color("hp-blue").move_to(0, 0).draw(arc, y: -20).stroke
         attr_reader :y
 
-        # Length of semi-major axis
+        # Length of semi-major axis, defaults to 0.
         #
         # Examples:
         #
         #   #>pdf-center
         #   arc = canvas.graphic_object(:endpoint_arc, x: 50, y: 20, a: 30, b: 20)
         #   canvas.move_to(0, 0).draw(arc).stroke
-        #   canvas.stroke_color("red").move_to(0, 0).draw(arc, a: 40).stroke
+        #   canvas.stroke_color("hp-blue").move_to(0, 0).draw(arc, a: 40).stroke
         attr_reader :a
 
-        # Length of semi-minor axis
+        # Length of semi-minor axis, defaults to 0.
         #
         # Examples:
         #
         #   #>pdf-center
         #   arc = canvas.graphic_object(:endpoint_arc, x: 50, y: 20, a: 30, b: 20)
         #   canvas.move_to(0, 0).draw(arc).stroke
-        #   canvas.stroke_color("red").move_to(0, 0).draw(arc, b: 50).stroke
+        #   canvas.stroke_color("hp-blue").move_to(0, 0).draw(arc, b: 50).stroke
         attr_reader :b
 
-        # Inclination in degrees of semi-major axis in respect to x-axis
+        # Inclination in degrees of semi-major axis in respect to x-axis, defaults to 0.
         #
         # Examples:
         #
         #   #>pdf-center
         #   arc = canvas.graphic_object(:endpoint_arc, x: 50, y: 20, a: 30, b: 20)
         #   canvas.move_to(0, 0).draw(arc).stroke
-        #   canvas.stroke_color("red").move_to(0, 0).draw(arc, inclination: 45).stroke
+        #   canvas.stroke_color("hp-blue").move_to(0, 0).draw(arc, inclination: 45).stroke
         attr_reader :inclination
 
-        # Large arc choice - if +true+ use the large arc (i.e. the one spanning more than 180
-        # degrees), else the small arc
+        # Large arc choice - if +true+ (the default) use the large arc (i.e. the one spanning more
+        # than 180 degrees), else the small arc
         #
         # Examples:
         #
         #   #>pdf-center
         #   arc = canvas.graphic_object(:endpoint_arc, x: 50, y: 20, a: 30, b: 20)
         #   canvas.move_to(0, 0).draw(arc).stroke
-        #   canvas.stroke_color("red").move_to(0, 0).draw(arc, large_arc: false, clockwise: true).stroke
+        #   canvas.stroke_color("hp-blue").
+        #     move_to(0, 0).draw(arc, large_arc: false, clockwise: true).stroke
         attr_reader :large_arc
 
         # Direction of arc - if +true+ in clockwise direction, else in counterclockwise direction
+        # (the default).
         #
-        # This is needed, for example, when filling paths using the nonzero winding number rule to achieve
-        # different effects.
+        # This is needed, for example, when filling paths using the nonzero winding number rule to
+        # achieve different effects.
         #
         # Examples:
         #
         #   #>pdf-center
         #   arc = canvas.graphic_object(:endpoint_arc, x: 50, y: 20, a: 30, b: 20)
         #   canvas.move_to(0, 0).draw(arc).stroke
-        #   canvas.stroke_color("red").move_to(0, 0).draw(arc, clockwise: true).stroke
+        #   canvas.stroke_color("hp-blue").move_to(0, 0).draw(arc, clockwise: true).stroke
         attr_reader :clockwise
 
+        # The maximal number of curves used for approximating a complete ellipse.
+        #
+        # See Arc#max_curves for details.
+        #
+        # Examples:
+        #
+        #   #>pdf-center
+        #   arc = canvas.graphic_object(:endpoint_arc, x: 50, y: 20, a: 30, b: 20)
+        #   canvas.move_to(0, 0).draw(arc, max_curves: 1).stroke
+        #   canvas.stroke_color("hp-blue").
+        #     move_to(0, 0).draw(arc, max_curves: 2).stroke
+        attr_accessor :max_curves
+
         # Creates an endpoint arc with default values x=0, y=0, a=0, b=0, inclination=0,
         # large_arc=true, clockwise=false (a line to the origin).
         #
@@ -153,6 +175,7 @@ module HexaPDF
           @inclination = 0
           @large_arc = true
           @clockwise = false
+          @max_curves = nil
         end
 
         # Configures the endpoint arc with
@@ -161,8 +184,9 @@ module HexaPDF
         # * semi-major axis +a+,
         # * semi-minor axis +b+,
         # * an inclination in respect to the x-axis of +inclination+ degrees,
-        # * the given large_arc flag and
-        # * the given clockwise flag.
+        # * the given large_arc flag,
+        # * the given clockwise flag and.
+        # * the given maximum number of approximation curves.
         #
         # The +large_arc+ option determines whether the large arc, i.e. the one spanning more than
         # 180 degrees, is used (+true+) or the small arc (+false+).
@@ -174,8 +198,15 @@ module HexaPDF
         # for the inital values.
         #
         # Returns self.
+        #
+        # Examples:
+        #
+        #   #>pdf-center
+        #   arc = canvas.graphic_object(:endpoint_arc)
+        #   arc.configure(x: 50, y: 20, a: 30, b: 10)
+        #   canvas.move_to(0, 0).draw(arc).stroke
         def configure(x: nil, y: nil, a: nil, b: nil, inclination: nil, large_arc: nil,
-                      clockwise: nil)
+                      clockwise: nil, max_curves: nil)
           @x = x if x
           @y = y if y
           @a = a.abs if a
@@ -183,11 +214,23 @@ module HexaPDF
           @inclination = inclination % 360 if inclination
           @large_arc = large_arc unless large_arc.nil?
           @clockwise = clockwise unless clockwise.nil?
+          @max_curves = max_curves if max_curves
 
           self
         end
 
         # Draws the arc on the given Canvas.
+        #
+        # Since this method doesn't have any other arguments than +canvas+, it is usually better and
+        # easier to use Canvas#draw.
+        #
+        # Examples:
+        #
+        #   #>pdf-center
+        #   arc = canvas.graphic_object(:endpoint_arc, x: 50, y: 20, a: 30, b: 10)
+        #   canvas.move_to(-20, -20)
+        #   arc.draw(canvas)
+        #   canvas.stroke
         def draw(canvas)
           x1, y1 = *canvas.current_point
 
@@ -257,7 +300,7 @@ module HexaPDF
           end_angle = compute_angle_to_x_axis((-x1p - cxp), (-y1p - cyp)) % 360
 
           {cx: cx, cy: cy, a: rx, b: ry, start_angle: start_angle, end_angle: end_angle,
-           inclination: @inclination, clockwise: @clockwise}
+           inclination: @inclination, clockwise: @clockwise, max_curves: @max_curves}
         end
 
         # Compares two float numbers if they are within a certain delta.