Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation for ImageDraw.rectangle and rounded_rectangle #6625

Merged
merged 1 commit into from
Sep 30, 2022
Merged

Improve documentation for ImageDraw.rectangle and rounded_rectangle #6625

merged 1 commit into from
Sep 30, 2022

Conversation

d0sboots
Copy link
Contributor

Fixes #1668

@hugovk
Copy link
Member

hugovk commented Sep 29, 2022

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()

image

Zoomed:

image


: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()

image

image

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()

image

image

width is not ignored when fill is set.

@d0sboots
Copy link
Contributor Author

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:

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

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

@d0sboots
Copy link
Contributor Author

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
Copy link
Member

hugovk commented Sep 29, 2022

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()

image

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
Copy link
Contributor Author

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 hugovk merged commit bdbf59d into python-pillow:main Sep 30, 2022
@hugovk
Copy link
Member

hugovk commented Sep 30, 2022

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

It seemed that the box of Draw.rectangle contained the end xy point
3 participants