Improve documentation for ImageDraw.rectangle and rounded_rectangle

[d0sboots]

Fixes #1668

[hugovk]

Thanks for the PR!

---

The rectangle is inclusive of both endpoints.

Quick demo:

from PIL import Image, ImageDraw

im = Image.new("RGB", (8, 8))
draw = ImageDraw.Draw(im)

draw.rectangle([(1, 1), (3, 3)], outline="green")
draw.rectangle([(4, 4), (6, 6)], outline="blue")
im.show()

Zoomed:

✅

---

:param outline: Color to use for the outline. Ignored if fill is set.

With both outline and fill:

from PIL import Image, ImageDraw

im = Image.new("RGB", (8, 8))
draw = ImageDraw.Draw(im)

draw.rectangle([(1, 1), (3, 3)], fill="red", outline="green")
draw.rectangle([(4, 4), (6, 6)], fill="red", outline="blue")
im.show()

❌ outline is not ignored when fill is set.

---

:param width: The line width, in pixels. Ignored if fill is set.

With both width and outline (and bigger rectangles this time):

from PIL import Image, ImageDraw

im = Image.new("RGB", (12, 12))
draw = ImageDraw.Draw(im)

draw.rectangle([(1, 1), (5, 5)], width=2, outline="green")
draw.rectangle([(6, 6), (10, 10)], width=2, outline="blue")
im.show()

❌ width is not ignored when fill is set.

[d0sboots]

Thanks for unittesting the docs!

I don't want to just delete those lines until I understand what's going on though... the code seems very unambiguous that they should be ignored:

Pillow/src/PIL/ImageDraw.py

Line 285 in aa8877a

self.draw.draw_rectangle(xy, fill, 1)

(Specifically, neither width nor ink is passed to the underlying C library function.)

[d0sboots]

Oh, answered my own question immediately. It is ignored on that call, but that doesn't prevent the outline call from happening. Right-o, lemme fix it to only have the correct info.

[hugovk]

Thanks!

Being more nitpicky about rounded_rectangle:

The rectangle is inclusive of both endpoints.

Depending on the size and radius, the endpoints are outside the drawn line:

from PIL import Image, ImageDraw

im = Image.new("RGB", (100, 100))
draw = ImageDraw.Draw(im)

draw.rounded_rectangle([(1, 1), (50, 50)], outline="green")
draw.rounded_rectangle([(51, 51), (99, 99)], outline="blue", radius=20)
im.show()

Maybe this doesn't matter, as the implied "full" rectangle would include them? Or should we say this (for just this or both functions?)?

-The rectangle is inclusive of both endpoints.
+The bounding box is inclusive of both endpoints.

[d0sboots]

I like it. I feel like it has better (correct) implications for how outline works - that increasing width increases the border by working inwards.

[hugovk]

Thanks!