Support list of list in `draw.line`

[gaoxinge]

Code below is running normally:

from PIL import Image, ImageDraw

WHITE = (255, 255, 255)
BLUE = "#0000ff"
MyImage = Image.new('RGB', (600, 400), WHITE)
MyDraw = ImageDraw.Draw(MyImage)
line_points = [(100, 100), (150, 200), (300, 100), (500, 300)]  # list of tuple
MyDraw.line(line_points, width=40, fill=BLUE, joint='curve')
MyImage.show()

But if I change

line_points = [(100, 100), (150, 200), (300, 100), (500, 300)]  # list of tuple

into

line_points = [[100, 100], [150, 200], [300, 100], [500, 300]]  # list of list

the code will raise exception because the points are represented by list.

Is it appropriate that draw.line support the list of list as arguments?

My pillow version is 5.4.1.

[radarhere]

I can see that it could be useful. I've created PR #3739 to resolve this.

[gaoxinge]

@radarhere thanks!

[hugovk]

My initial thought is how about all the other places we have parameters that take a tuple (eg. Image.new("RGB", size=(20, 20), color=(255, 255, 255)))? Should they also take lists?

---

A quick search on when to use a tuple or a list gives https://stackoverflow.com/a/1708538/724176:

Tuples are fixed size in nature whereas lists are dynamic.
In other words, a tuple is immutable whereas a list is mutable.

1. You can't add elements to a tuple. Tuples have no append or extend method.
2. You can't remove elements from a tuple. Tuples have no remove or pop method.
3. You can find elements in a tuple, since this doesn’t change the tuple.
4. You can also use the in operator to check if an element exists in the tuple.

---

• Tuples are faster than lists. If you're defining a constant set of values and all you're ever going to do with it is iterate through it, use a tuple instead of a list.

• It makes your code safer if you “write-protect” data that does not need to be changed. Using a tuple instead of a list is like having an implied assert statement that this data is constant, and that special thought (and a specific function) is required to override that.

• Some tuples can be used as dictionary keys (specifically, tuples that contain immutable values like strings, numbers, and other tuples). Lists can never be used as dictionary keys, because lists are not immutable.

Source: Dive into Python 3

---

And https://stackoverflow.com/a/1708538/724176:

Apart from tuples being immutable there is also a semantic distinction that should guide their usage. Tuples are heterogeneous data structures (i.e., their entries have different meanings), while lists are homogeneous sequences. Tuples have structure, lists have order.

Using this distinction makes code more explicit and understandable.

One example would be pairs of page and line number to reference locations in a book, e.g.:

my_location = (42, 11)  # page number, line number

You can then use this as a key in a dictionary to store notes on locations. A list on the other hand could be used to store multiple locations. Naturally one might want to add or remove locations from the list, so it makes sense that lists are mutable. On the other hand it doesn't make sense to add or remove items from an existing location - hence tuples are immutable.

There might be situations where you want to change items within an existing location tuple, for example when iterating through the lines of a page. But tuple immutability forces you to create a new location tuple for each new value. This seems inconvenient on the face of it, but using immutable data like this is a cornerstone of value types and functional programming techniques, which can have substantial advantages.

There are some interesting articles on this issue, e.g. "Python Tuples are Not Just Constant Lists" or "Understanding tuples vs. lists in Python". The official Python documentation also mentions this

"Tuples are immutable, and usually contain an heterogeneous sequence ...".

---

That suggests tuples are better here, and not to use lists. Is there a compelling reason to also accept lists?

[gaoxinge]

@hugovk I agree with you on that tuple is better than list, and it is the responsibility that user changes the args from list to tuple before call the Pillow function.

However I think there are two compelling reasons to accept list:

• First, the behaviour that Pillow treats the list args is not self-consistent. We can't pass list to function draw.line, but we can in Image.new, Image.resize or Image.paste.

• Second, the point args may from np.array or np.array.tolist before call the Pillow function, so it may be better that Pillow function treats the point args as containers with two elements which is "broader" than the tuple with two elements.

[radarhere]

@hugovk while you're in the mindset of reviewing things, are you interested in making a final call for this? I don't have strong feelings either way.

[hugovk]

Hmm, I also don't have strong feelings either way. It's adding a bunch of conversion code, which I doubt would have much of a performance hit, but means we should try and be consistent everywhere. Also, tuples and lists are for slightly different things (immutable/mutable, structure/order). Does that really matter? I think maybe it does: semantically you know a coordinate like (100, 200) can't have a third value; but [100, 200] looks like it could. So I'm tending towards keeping it as is.

[gaoxinge]

@hugovk @radarhere Can we modify the PyPath_Flatten directly? And Modify the codes below:

Pillow/src/path.c

Lines 177 to 180 in 7585136

	else if (PyArg_ParseTuple(op, "dd", &x, &y)) {
	xy[j++] = x;
	xy[j++] = y;
	} else {

Pillow/src/path.c

Lines 195 to 198 in 7585136

	else if (PyArg_ParseTuple(op, "dd", &x, &y)) {
	xy[j++] = x;
	xy[j++] = y;
	} else {

Pillow/src/path.c

Lines 224 to 227 in 7585136

	else if (PyArg_ParseTuple(op, "dd", &x, &y)) {
	xy[j++] = x;
	xy[j++] = y;
	} else {

I think this way may

• not need to write too much codes to adapt every kind of coordinates, such as list and tuple
• not hit the performance too much

[gaoxinge]

@hugovk @radarhere I have put a pr #3951. You can review and check that is there any problem with it?

[radarhere]

Thanks for your enthusiasm @gaoxinge, but it sounds like we're leaving it as is.