SETPITCH angle

Pitches the turtle to a new absolute pitch. The angle input is the pitch in degrees which is positive from the negative Z-Axis to the positive Y-Axis rotating about the X-Axis.

SETPITCH is designed to run in PERSPECTIVE mode.

SETPITCH can be confusing because it changes the turtle's orientation (roll, pitch, and heading) to an equivalent orientation, where the pitch may not be what was set. That is, PITCH may output a different angle than was set by SETPITCH, even though SETPITCH correctly set the turtle's pitch. Similarly, running SETPITCH with incrementally increasing angles is not guaranteed to incrementally increase the turtle's pitch, particularly if setting the pitch changes the ROLL or HEADING. Therefore, it is important to understand your orientation in 3D.

To illustrate this, suppose you want to draw the wheel of a bicycle with all spokes joining at the center. You may think that this works:

TO BADWHEEL
  PERSPECTIVE
  REPEAT 36 [
     SETPITCH REPCOUNT*10
     FORWARD 100
     BACK 100
  ]
  RIGHTROLL 90
  CIRCLE 100
END

But after running BADWHEEL, it looks like some spokes weren't drawn.

The root of this surprising behavior can be seen in its simplest form with the following instructions:

PERSPECTIVE
CLEARSCREEN
SETPITCH 180
SHOW ORIENTATION
[180 0 180]

Here, you set the pitch to 180, which, from an orientation of [0 0 0] can be thought of as "keep nosing up until you're upside-down and looking backward", but ORIENTATION shows that the pitch is 0, even though the turtle is upside-down and looking backward. Instead, the turtle's orientation is equivalent to [0 180 0], but it's described as flipping upside-down (roll = 180) and looking backward (heading = 180)—[180 0 180]. So now what happens if you set the pitch to 180 again? Well, you set the orientation to [180 180 180], which means "flip upside down, keep nosing up until you're upside-down and looking backward, then turn around", which puts you back at [0 0 0].

There are two easy ways to account for this. One way is to use SETORIENTATION, which updates both ROLL and HEADING to account for this. Another is to use UPPITCH instead of SETPITCH when making incremental changes to the pitch. With these, we can fix BADWHEEL above.

TO GOODWHEEL1
  PERSPECTIVE
  REPEAT 36 [
     SETORIENTATION (LIST 0 REPCOUNT*10 0) ; fix #1
     FORWARD 100
     BACK 100
  ]
  RIGHTROLL 90
  CIRCLE 100
END

TO GOODWHEEL2
  PERSPECTIVE
  REPEAT 36 [
     UPPITCH 10 ; fix #2
     FORWARD 100
     BACK 100
  ]
  RIGHTROLL 90
  CIRCLE 100
END

PERSPECTIVE
SETPITCH 45
SHOW PITCH
45