Python Turtle custom shape from coordinates

Question

It seems that when you specify a turtle shape using a set of coordinates you have to put the y coordinate first in each tuple, then the x coordinate, but I can't find this documented anywhere. Is this true?

Here is a custom designed shape:

If I register this shape using the coordinates as shown here

s.register_shape('house', ((-10,-10),(10,-10),(10,2),(0,12),(-4,8),
                        (-4,12),(-6,12),(-6,6),(-10,2)))

this is the result:

Not only is the image rotated 90 degrees clockwise, but it's become a mirror image (the chimney is on the other side of the house). However, if I reverse the x and y coordinates in each tuple I get this result

I'm puzzled why the register shape code has this strange anomaly. Surely it should be mentioned in the documentation somewhere.

In response to ggorlen:

Here is the code

from turtle import *

s = Screen()
s.setup(400,400)
s.bgcolor('lightgray')
s.register_shape('house', ((-10,-10),(10,-10),(10,2),(0,12),(-4,8),
                            (-4,12),(-6,12),(-6,6),(-10,2)))
s.register_shape('house_xy_switch', ((-10,-10),(-10,10),(2,10),(12,0,),
                            (8,-4),(12,-4),(12,-6),(6,-6),(2,-10)))

chez_moi = Turtle()
#chez_moi.shape('house')
chez_moi.shape('house_xy_switch')

In Python turtle graphics the y coordinates increase going upwards, and 0,0 is in the centre of the screen. My assumption was that this would also be the scheme for specifying turtle custom shape coordinates.

I did the coding using the online platform trinket which uses Python 3.2.0. I've just tried it in IDLE with Python 3.10.7 with the 'house' shape and it is rotated 90 degrees clockwise but no longer a mirror image. So there must have been some amendments to the turtle code between 3.2 and 3.10.

Edited with further details in response to the Answer by cdlane

I made another example which shows why it is not necessarily helpful to rotate the shape by 90 degrees.

This custom shape represents a spaceship. If I want the ship to travel to the right I would set the heading to 0 and have it move forward and want it to go nose first to the right.

When I put the shape coordinates into Python 3.10.7 using the convention that x coordinate is first:

s.register_shape('ship', ((36, 0), (0, -12), (-32, -12), (-32, 12),
          (0, 12), (12, 8), (20, 7.6), (24, 4)))

it produces this output (with the turtle heading at the default 0 degrees):

If I move this turtle forwards it will move to the right but with the top edge first, (instead of nose first), which is not what is wanted at all. If I set the heading to 90 then move it forwards it will move upwards. The only way around this is to fiddle with the coordinates in the shape specification to rotate them all 90 degrees anti-clockwise (which means swapping x and y, and negating the sign of the new x coordinate.)

I can't believe this is what was intended.

Answer 1

Using your original drawing coordinates, I believe turtle is doing the right thing. A turtle's starting heading of 0 degrees is towards the positive X axis. So if we want the house standing up, we need to set the heading to 90 degrees, towards the positive Y axis:

from turtle import Screen, Turtle

screen = Screen()

screen.register_shape('house', (
    (10, -10), (-10, -10), (-10, 2), (-6, 6),
    (-6, 12), (-4, 12), (-4, 8), (0, 12), (10, 2)
    )
)

turtle = Turtle(shape='house')
turtle.shapesize(5)

turtle.setheading(90)

screen.exitonclick()

In place of turtle.setheading(90) you can instead do screen.mode("logo") after setting screen to use the "up is zero degrees" model. Either way, I don't see any reversed chimney issue.

I agree that the turtle documentation should explain this better. (Similarly, the stretch_* arguments to shapesize seem reversed without such an explanation.)