Fixing FPDF.circle() parameters (release 2.8.0)

CHANGELOG.md

@@ -16,7 +16,7 @@ in order to get warned about deprecated features used in your code.
 
 This can also be enabled programmatically with `warnings.simplefilter('default', DeprecationWarning)`.
 
-## [2.7.10] - Not released yet
+## [2.8.0] - Not released yet
 ### Added
 * support for escape character for markers in markdown text [issue #1215](https://github.com/py-pdf/fpdf2/issues/1215)
 * Wrapping words on spaces now considers all common space symbols in addition to regular spaces (' '), addressing issues with word-wrapping for languages like Thai, as per [#1190](https://github.com/py-pdf/fpdf2/issues/1190) and [#1191](https://github.com/py-pdf/fpdf2/pull/1191).
@@ -49,6 +49,7 @@ This can also be enabled programmatically with `warnings.simplefilter('default',
 * `fpdf.TitleStyle` has been renamed into `fpdf.TextStyle`
 * [`FPDF.write_html()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.write_html): `tag_indents` introduced in the last version - Now the indentation can be provided through the `tag_styles` parameter, using the `.l_margin` of `TextStyle` instances
 ### Changed
+* [`FPDF.circle()`](https://py-pdf.github.io/fpdf2/fpdf.html#fpdf.fpdf.FPDF.circle) : the previous `r` parameter, that in fact defined the diamter, has been replaced by a new `radius` paremeter. The `x` & `y` parameters now define the circle **center**, instead of its top-left corner as it used to be - [issue #1245](https://github.com/py-pdf/fpdf2/issues/1245)
 * [`FPDF.table()`](https://py-pdf.github.io/fpdf2/Tables.html) now raises an error when a single row is too high to be rendered on a single page
 * [`FPDF.write_html()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.write_html): indentation of HTML elements can now be non-integer (float), and is now independent of font size and bullet strings.
 * improved performance of font glyph selection by using functools cache

docs/Shapes.md

@@ -43,11 +43,13 @@ pdf.add_page()
 pdf.set_line_width(2)
 pdf.set_draw_color(240)
 pdf.set_fill_color(r=230, g=30, b=180)
-pdf.circle(x=50, y=50, r=50, style="FD")
+pdf.circle(x=50, y=50, radius=50, style="FD")
 pdf.output("circle.pdf")
 ```
 ![](circle.png)
 
+!!! warning "This method changed parameters in [release 2.8.0](https://github.com/py-pdf/fpdf2/releases/tag/2.8.0)"
+
 ## Ellipse ##
 
 Using [`ellipse()`](fpdf/fpdf.html#fpdf.fpdf.FPDF.ellipse), filled in grey with a pink outline:

docs/TextStyling.md

@@ -163,7 +163,7 @@ pdf.ln()
 with pdf.local_context(text_mode="CLIP"):
     pdf.cell(text="CLIP text mode")
     for r in range(0, 250, 2):  # drawing concentric circles
-        pdf.circle(x=130-r/2, y=70-r/2, r=r)
+        pdf.circle(x=130-r/2, y=70-r/2, radius=r)
 
 pdf.output("text-modes.pdf")
 ```

docs/Transformations.md

@@ -11,7 +11,7 @@ pdf = FPDF(format=(40, 40))
 pdf.add_page()
 x, y = 15, 15
 with pdf.rotation(60, x=x, y=y):
-    pdf.circle(x=x, y=y+15, r=5)
+    pdf.circle(x=x, y=y+15, radius=5)
     # Inserting a small base64-encoded image:
     pdf.image("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQBAMAAADt3eJSAAAAMFBMVEU0OkArMjhobHEoPUPFEBIuO0L+AAC2FBZ2JyuNICOfGx7xAwTjCAlCNTvVDA1aLzQ3COjMAAAAVUlEQVQI12NgwAaCDSA0888GCItjn0szWGBJTVoGSCjWs8TleQCQYV95evdxkFT8Kpe0PLDi5WfKd4LUsN5zS1sKFolt8bwAZrCaGqNYJAgFDEpQAAAzmxafI4vZWwAAAABJRU5ErkJggg==", x=x, y=y)
     pdf.rect(x=x-10, y=y+10, w=25, h=15)
@@ -40,7 +40,7 @@ pdf.set_line_width(2)
 pdf.set_draw_color(240)
 pdf.set_fill_color(r=230, g=30, b=180)
 with pdf.skew(ax=-45, ay=0, x=100, y=170):
-    pdf.circle(x=100, y=170, r=10, style="FD")
+    pdf.circle(x=100, y=170, radius=10, style="FD")
 ```
 ![](slanted_circle.png)
 

fpdf/fpdf.py

@@ -1538,22 +1538,24 @@ def _draw_ellipse(self, x, y, w, h, operator):
         )
 
     @check_page
-    def circle(self, x, y, r, style=None):
+    def circle(self, x, y, radius, style=None):
         """
         Outputs a circle.
         It can be drawn (border only), filled (with no border) or both.
 
+        WARNING: This method changed parameters in [release 2.8.0](https://github.com/py-pdf/fpdf2/releases/tag/2.8.0)
+
         Args:
             x (float): Abscissa of upper-left bounding box.
             y (float): Ordinate of upper-left bounding box.
-            r (float): Radius of the circle.
+            radius (float): Radius of the circle.
             style (str): Style of rendering. Possible values are:
 
             * `D` or None: draw border. This is the default value.
             * `F`: fill
             * `DF` or `FD`: draw and fill
         """
-        self.ellipse(x, y, r, r, style)
+        self.ellipse(x - radius, y - radius, 2 * radius, 2 * radius, style)
 
     @check_page
     def regular_polygon(self, x, y, numSides, polyWidth, rotateDegrees=0, style=None):

test/shapes/test_bezier.py

@@ -10,7 +10,7 @@
 def draw_points(pdf, point_lists):
     for pl in point_lists:
         for p in pl:
-            pdf.circle(x=p[0], y=p[1], r=1, style="FD")
+            pdf.circle(x=p[0] + 0.5, y=p[1] + 0.5, radius=0.5, style="FD")
 
 
 def test_quadratic_beziers(tmp_path):
@@ -107,10 +107,10 @@ def test_bezier_chaining(tmp_path):
                 3: "#00f",
             }[i % 4]
         )
-        pdf.circle(x=x1 - 0.5, y=y1 - 0.5, r=1)
-        pdf.circle(x=x2 - 0.5, y=y2 - 0.5, r=1)
-        pdf.circle(x=x3 - 0.5, y=y3 - 0.5, r=1)
-        pdf.circle(x=x4 - 0.5, y=y4 - 0.5, r=1)
+        pdf.circle(x=x1, y=y1, radius=0.5)
+        pdf.circle(x=x2, y=y2, radius=0.5)
+        pdf.circle(x=x3, y=y3, radius=0.5)
+        pdf.circle(x=x4, y=y4, radius=0.5)
         pdf.bezier(((x1, y1), (x2, y2), (x3, y3), (x4, y4)))
 
     pdf.x, pdf.y = 20, pdf.h / 2 - 30
@@ -127,9 +127,9 @@ def test_bezier_chaining(tmp_path):
                 2: "#00f",
             }[i % 3]
         )
-        pdf.circle(x=x1 - 0.5, y=y1 - 0.5, r=1)
-        pdf.circle(x=x2 - 0.5, y=y2 - 0.5, r=1)
-        pdf.circle(x=x3 - 0.5, y=y3 - 0.5, r=1)
+        pdf.circle(x=x1, y=y1, radius=0.5)
+        pdf.circle(x=x2, y=y2, radius=0.5)
+        pdf.circle(x=x3, y=y3, radius=0.5)
         pdf.bezier(((x1, y1), (x2, y2), (x3, y3)))
 
     assert_pdf_equal(pdf, HERE / "bezier_chaining.pdf", tmp_path)

test/shapes/test_circle.py

@@ -1,74 +1,77 @@
 from pathlib import Path
 
-import fpdf
+from fpdf import FPDF
 from test.conftest import assert_pdf_equal
 
 
 HERE = Path(__file__).resolve().parent
 
+RADIUS = 25
+MARGIN = 10
+
 
 def next_row(pdf):
     pdf.ln()
-    pdf.set_y(pdf.get_y() + SIZE + MARGIN)
-
-
-SIZE = 50
-MARGIN = 10
+    pdf.set_xy(pdf.l_margin + RADIUS, pdf.y + 2 * RADIUS + MARGIN)
 
 
 def test_circle_style(tmp_path):
-    pdf = fpdf.FPDF(unit="mm")
+    pdf = FPDF(unit="mm")
     pdf.add_page()
 
+    pdf.set_xy(pdf.l_margin + RADIUS, pdf.y + RADIUS)
     for counter, style in enumerate(["", "F", "FD", "DF", None]):
-        pdf.circle(x=pdf.get_x(), y=pdf.get_y(), r=SIZE, style=style)
-        pdf.set_x(pdf.get_x() + SIZE + MARGIN)
+        pdf.circle(x=pdf.x, y=pdf.y, radius=RADIUS, style=style)
+        pdf.set_x(pdf.x + 2 * RADIUS + MARGIN)
         if counter % 3 == 2:
             next_row(pdf)
 
-    assert_pdf_equal(pdf, HERE / "class_circle_style.pdf", tmp_path)
+    assert_pdf_equal(pdf, HERE / "circle_style.pdf", tmp_path)
 
 
 def test_circle_line_width(tmp_path):
-    pdf = fpdf.FPDF(unit="mm")
+    pdf = FPDF(unit="mm")
     pdf.add_page()
 
+    pdf.set_xy(pdf.l_margin + RADIUS, pdf.y + RADIUS)
     for line_width in [1, 2, 3]:
         pdf.set_line_width(line_width)
-        pdf.circle(x=pdf.get_x(), y=pdf.get_y(), r=SIZE, style=None)
-        pdf.set_x(pdf.get_x() + SIZE + MARGIN)
+        pdf.circle(x=pdf.x, y=pdf.y, radius=RADIUS, style=None)
+        pdf.set_x(pdf.x + 2 * RADIUS + MARGIN)
     next_row(pdf)
     for line_width in [4, 5, 6]:
         pdf.set_line_width(line_width)
-        pdf.circle(x=pdf.get_x(), y=pdf.get_y(), r=SIZE, style=None)
-        pdf.set_x(pdf.get_x() + SIZE + MARGIN)
+        pdf.circle(x=pdf.x, y=pdf.y, radius=RADIUS, style=None)
+        pdf.set_x(pdf.x + 2 * RADIUS + MARGIN)
     pdf.set_line_width(0.2)  # reset
 
-    assert_pdf_equal(pdf, HERE / "class_circle_line_width.pdf", tmp_path)
+    assert_pdf_equal(pdf, HERE / "circle_line_width.pdf", tmp_path)
 
 
 def test_circle_draw_color(tmp_path):
-    pdf = fpdf.FPDF(unit="mm")
+    pdf = FPDF(unit="mm")
     pdf.add_page()
 
     pdf.set_line_width(0.5)
+    pdf.set_xy(pdf.l_margin + RADIUS, pdf.y + RADIUS)
     for gray in [70, 140, 210]:
         pdf.set_draw_color(gray)
-        pdf.circle(x=pdf.get_x(), y=pdf.get_y(), r=SIZE, style=None)
-        pdf.set_x(pdf.get_x() + SIZE + MARGIN)
+        pdf.circle(x=pdf.x, y=pdf.y, radius=RADIUS, style=None)
+        pdf.set_x(pdf.x + 2 * RADIUS + MARGIN)
 
-    assert_pdf_equal(pdf, HERE / "class_circle_draw_color.pdf", tmp_path)
+    assert_pdf_equal(pdf, HERE / "circle_draw_color.pdf", tmp_path)
 
 
 def test_circle_fill_color(tmp_path):
-    pdf = fpdf.FPDF(unit="mm")
+    pdf = FPDF(unit="mm")
     pdf.add_page()
 
     pdf.set_fill_color(240)
+    pdf.set_xy(pdf.l_margin + RADIUS, pdf.y + RADIUS)
     for color in [[230, 30, 180], [30, 180, 30], [30, 30, 70]]:
         pdf.set_draw_color(*color)
-        pdf.circle(x=pdf.get_x(), y=pdf.get_y(), r=SIZE, style="FD")
-        pdf.set_x(pdf.get_x() + SIZE + MARGIN)
+        pdf.circle(x=pdf.x, y=pdf.y, radius=RADIUS, style="FD")
+        pdf.set_x(pdf.x + 2 * RADIUS + MARGIN)
     next_row(pdf)
 
-    assert_pdf_equal(pdf, HERE / "class_circle_fill_color.pdf", tmp_path)
+    assert_pdf_equal(pdf, HERE / "circle_fill_color.pdf", tmp_path)

test/test_skew.py

@@ -19,7 +19,7 @@ def test_skew(tmp_path):
     pdf.set_draw_color(240)
     pdf.set_fill_color(r=230, g=30, b=180)
     with pdf.skew(ax=-45, ay=0, x=100, y=170):
-        pdf.circle(x=100, y=170, r=10, style="FD")
+        pdf.circle(x=105, y=175, radius=5, style="FD")
     pdf.image(img_filepath, x=150, y=150)
     assert_pdf_equal(pdf, HERE / "skew.pdf", tmp_path)
 

test/text/test_render_styled.py

@@ -100,7 +100,7 @@ def test_render_styled_newpos(tmp_path):
         )
         # mark the new position in the file with crosshairs for verification
         with doc.rotation(i * -15, doc.x, doc.y):
-            doc.circle(doc.x - 3, doc.y - 3, 6)
+            doc.circle(doc.x, doc.y, radius=3)
             doc.line(doc.x - 3, doc.y, doc.x + 3, doc.y)
             doc.line(doc.x, doc.y - 3, doc.x, doc.y + 3)
 
@@ -142,7 +142,7 @@ def test_cell_newpos(tmp_path):
         )
         # mark the new position in the file with crosshairs for verification
         with doc.rotation(i * -15, doc.x, doc.y):
-            doc.circle(doc.x - 3, doc.y - 3, 6)
+            doc.circle(doc.x, doc.y, radius=3)
             doc.line(doc.x - 3, doc.y, doc.x + 3, doc.y)
             doc.line(doc.x, doc.y - 3, doc.x, doc.y + 3)
 
@@ -185,7 +185,7 @@ def test_cell_newpos_stretched(tmp_path):
         )
         # mark the new position in the file with crosshairs for verification
         with doc.rotation(i * -15, doc.x, doc.y):
-            doc.circle(doc.x - 3, doc.y - 3, 6)
+            doc.circle(doc.x, doc.y, radius=3)
             doc.line(doc.x - 3, doc.y, doc.x + 3, doc.y)
             doc.line(doc.x, doc.y - 3, doc.x, doc.y + 3)
 
@@ -228,7 +228,7 @@ def test_cell_newpos_charspaced(tmp_path):
         )
         # mark the new position in the file with crosshairs for verification
         with doc.rotation(i * -15, doc.x, doc.y):
-            doc.circle(doc.x - 3, doc.y - 3, 6)
+            doc.circle(doc.x, doc.y, radius=3)
             doc.line(doc.x - 3, doc.y, doc.x + 3, doc.y)
             doc.line(doc.x, doc.y - 3, doc.x, doc.y + 3)
 
@@ -272,7 +272,7 @@ def test_cell_newpos_combined(tmp_path):
         )
         # mark the new position in the file with crosshairs for verification
         with doc.rotation(i * -15, doc.x, doc.y):
-            doc.circle(doc.x - 3, doc.y - 3, 6)
+            doc.circle(doc.x, doc.y, radius=3)
             doc.line(doc.x - 3, doc.y, doc.x + 3, doc.y)
             doc.line(doc.x, doc.y - 3, doc.x, doc.y + 3)
 
@@ -313,7 +313,7 @@ def test_multi_cell_newpos(tmp_path):
         )
         # mark the new position in the file with crosshairs for verification
         with doc.rotation(i * -15, doc.x, doc.y):
-            doc.circle(doc.x - 3, doc.y - 3, 6)
+            doc.circle(doc.x, doc.y, radius=3)
             doc.line(doc.x - 3, doc.y, doc.x + 3, doc.y)
             doc.line(doc.x, doc.y - 3, doc.x, doc.y + 3)
 
@@ -355,7 +355,7 @@ def test_multi_cell_newpos_stretched(tmp_path):
         )
         # mark the new position in the file with crosshairs for verification
         with doc.rotation(i * -15, doc.x, doc.y):
-            doc.circle(doc.x - 3, doc.y - 3, 6)
+            doc.circle(doc.x, doc.y, radius=3)
             doc.line(doc.x - 3, doc.y, doc.x + 3, doc.y)
             doc.line(doc.x, doc.y - 3, doc.x, doc.y + 3)
 
@@ -396,7 +396,7 @@ def test_multi_cell_newpos_charspaced(tmp_path):
         )
         # mark the new position in the file with crosshairs for verification
         with doc.rotation(i * -15, doc.x, doc.y):
-            doc.circle(doc.x - 3, doc.y - 3, 6)
+            doc.circle(doc.x, doc.y, radius=3)
             doc.line(doc.x - 3, doc.y, doc.x + 3, doc.y)
             doc.line(doc.x, doc.y - 3, doc.x, doc.y + 3)
 
@@ -438,7 +438,7 @@ def test_multi_cell_newpos_combined(tmp_path):
         )
         # mark the new position in the file with crosshairs for verification
         with doc.rotation(i * -15, doc.x, doc.y):
-            doc.circle(doc.x - 3, doc.y - 3, 6)
+            doc.circle(doc.x, doc.y, radius=3)
             doc.line(doc.x - 3, doc.y, doc.x + 3, doc.y)
             doc.line(doc.x, doc.y - 3, doc.x, doc.y + 3)
 
@@ -506,7 +506,7 @@ def test_cell_lnpos(tmp_path):
 
         # mark the new position in the file with crosshairs for verification
         with doc.rotation(i * -15, doc.x, doc.y):
-            doc.circle(doc.x - 3, doc.y - 3, 6)
+            doc.circle(doc.x, doc.y, radius=3)
             doc.line(doc.x - 3, doc.y, doc.x + 3, doc.y)
             doc.line(doc.x, doc.y - 3, doc.x, doc.y + 3)
 
@@ -549,7 +549,7 @@ def test_multi_cell_ln_newpos(tmp_path):
 
         # mark the new position in the file with crosshairs for verification
         with doc.rotation(i * -15, doc.x, doc.y):
-            doc.circle(doc.x - 3, doc.y - 3, 6)
+            doc.circle(doc.x, doc.y, radius=3)
             doc.line(doc.x - 3, doc.y, doc.x + 3, doc.y)
             doc.line(doc.x, doc.y - 3, doc.x, doc.y + 3)
 

test/text/test_text_mode.py

@@ -40,25 +40,25 @@ def test_clip_text_modes(tmp_path):
     pdf.line_width = 1
     with pdf.local_context(text_mode=TextMode.FILL_CLIP, text_color=(0, 255, 255)):
         pdf.cell(text="FILL_CLIP text mode")
-        for r in range(0, 200, 2):
-            pdf.circle(x=110 - r / 2, y=22 - r / 2, r=r)
+        for r in range(0, 100, 1):
+            pdf.circle(x=110, y=22, radius=r)
     pdf.ln()
     with pdf.local_context(text_mode=TextMode.STROKE_CLIP):
         pdf.cell(text="STROKE_CLIP text mode")
-        for r in range(0, 200, 2):
-            pdf.circle(x=110 - r / 2, y=50 - r / 2, r=r)
+        for r in range(0, 100, 1):
+            pdf.circle(x=110, y=50, radius=r)
     pdf.ln()
     with pdf.local_context(
         text_mode=TextMode.FILL_STROKE_CLIP, text_color=(0, 255, 255)
     ):
         pdf.cell(text="FILL_STROKE_CLIP text mode")
-        for r in range(0, 200, 2):
-            pdf.circle(x=110 - r / 2, y=78 - r / 2, r=r)
+        for r in range(0, 100, 1):
+            pdf.circle(x=110, y=78, radius=r)
     pdf.ln()
     with pdf.local_context(text_mode=TextMode.CLIP):
         pdf.cell(text="CLIP text mode")
-        for r in range(0, 200, 2):
-            pdf.circle(x=110 - r / 2, y=106 - r / 2, r=r)
+        for r in range(0, 100, 1):
+            pdf.circle(x=110, y=106, radius=r)
     pdf.ln()
     assert_pdf_equal(pdf, HERE / "clip_text_modes.pdf", tmp_path)