Turtle graphics commands

  • Email
  • Sharebar
  • Email

Turtle Graphics Commands

*Moving the turtle

*Turning the turtle

*Creating objects

*Colouring commands

*Material commands

*Texturing commands -- not implemented yet.

*Font commands

*Querying commands

*Other commands


Up: *Table of contents


Moving the turtle

These commands can be used to change the position of the turtle. The turtle's orientation stays the same. There are three frames of reference systems to move the turtle:

  • Egocentric: the turtle changes position according to its orientation or heading direction. These include FORWARD and BACK commands.
  • Fixed: the turtle changes position regardless its orientation. These include EAST, WEST, NORTH, SOUTH, UP, and DOWN commands.
  • Coordinate: the turtle changes position according to the given 3D coordinate. These include SETX, SETY, SETZ, SETXYZ, and SETPOS.

* Every moving command has its jump command such as JUMPFORWARD for FORWARD. When pen is up, the jump series commands act the same as normal moving commands. They are used when pen is down, and you want to temporarily disconnect the turtle tracks. Using jump series commands will never have turtle tracks.

Egocentric

FORWARD distance
FD distance
* JUMPFORWARD distance
* JUMPFORTH distance
* JF distance

FORWARD moves the turtle forward the given number of distance in the current heading direction. The default unit for distance is meter. This can be changed by using METER or CENTIMETER (CM). If the pen is currently down, the turtle will draw a line along its path. If the given input is not a number, FORWARD will throw an error.


BACK distance BACKWARD distance BK distance
 *
JUMPBACK distance
*
JUMPBACKWARD distance
*
JB distance

BACK moves the turtle the given number of distance in the direction opposite from the current heading direction.  The default unit for distance is meter. This can be changed by using METER or CENTIMETER (CM). If the pen is currently down, the turtle will draw a line along its path. If the given input is not a number, BACK will throw an error.

Fixed

EAST distance
* JUMPEAST distance
*JE distance

EAST moves the turtle the given number of distance towards the east direction regardless the current heading direction.  The default unit for distance is meter. This can be changed by using METER or CENTIMETER (CM). If the pen is currently down, the turtle will draw a line along its path. If the given input is not a number, EAST will throw an error.

WEST distance
* JUMPWEST distance
* JW distance

WEST moves the turtle the given number of distance towards the west direction regardless the current heading direction.  The default unit for distance is meter. This can be changed by using METER or CENTIMETER (CM). If the pen is currently down, the turtle will draw a line along its path. If the given input is not a number, WEST will throw an error.

NORTH distance

* JUMPNORTH distance
* JN distance

NORTH moves the turtle the given number of distance towards the north direction regardless the current heading direction.  The default unit for distance is meter. This can be changed by using METER or CENTIMETER (CM). If the pen is currently down, the turtle will draw a line along its path. If the given input is not a number, NORTH will throw an error.

SOUTH distance

* JUMPSOUTH distance
* JS distance

SOUTH moves the turtle the given number of distance towards the south direction regardless the current heading direction.  The default unit for distance is meter. This can be changed by using METER or CENTIMETER (CM). If the pen is currently down, the turtle will draw a line along its path. If the given input is not a number, SOUTH will throw an error.

UP distance

* JUMPUP distance
* JU distance

UP moves the turtle the given number of distance towards the sky direction regardless the current heading direction.  The default unit for distance is meter. This can be changed by using METER or CENTIMETER (CM). If the pen is currently down, the turtle will draw a line along its path. If the given input is not a number, UP will throw an error.

DOWN distance

DN distance
* JUMPDOWN distance
* JD distance

DOWN moves the turtle the given number of distance towards the ground direction regardless the current heading direction.  The default unit for distance is meter. This can be changed by using METER or CENTIMETER (CM). If the pen is currently down, the turtle will draw a line along its path. If the given input is not a number, DOWN will throw an error.

Coordinate

This set of coordinate commands moves the turtle to an absolute position. Please note that the value given to this set of commands will not accumulate as the egocentric and fixed moving commands.

SETPOS poslist
* JUMPPOS poslist
* JPOS poslist
* JP poslist

SETPOS moves the turtle to the coordinates specified by the input position list. The input must be a three-element list, the first element being the x-coordinate, the second being the y-coordinate, and the third being the z-coordinate. The heading of the turtle is not changed. The coordinate is also influenced by METER or CENTIMETER (CM). If the pen is currently down, the turtle will draw a line along its path. If the given input is not a list or does not contain exactly three numeric elements, SETPOS will throw an error.

Example:
? SETPOS [ 0 0 0 ]

SETX xcor

* JUMPX xcor
* JX xcor

SETX moves the turtle such that its y and z positions remains the same but its x position is the given value. The heading of the turtle is not changed. The coordinate is also influenced by METER or CENTIMETER (CM). If the pen is currently down, the turtle will draw a line along its path. If the given input is not a number, SETX will throw an error.

SETY ycor

* JUMPY ycor
* JY ycor

SETY moves the turtle such that its x and z positions remains the same but its y position is the given value. The heading of the turtle is not changed. The coordinate is also influenced by METER or CENTIMETER (CM). If the pen is currently down, the turtle will draw a line along its path. If the given input is not a number, SETY will throw an error.

SETZ zcor

* JUMPZ zcor
* JZ zcor

SETZ moves the turtle such that its x and y positions remains the same but its z position is the given value. The heading of the turtle is not changed. The coordinate is also influenced by METER or CENTIMETER (CM). If the pen is currently down, the turtle will draw a line along its path. If the given input is not a number, SETZ will throw an error.

SETXYZ xcor ycor zcor

* JUMPXYZ xcor ycor zcor
* JXYZ xcor ycor zcor

SETXYZ moves the turtle such that its x, y, and z positions become the given values. The heading of the turtle is not changed. The coordinate is also influenced by METER or CENTIMETER (CM). If the pen is currently down, the turtle will draw a line along its path. If the given inputs are not numbers, SETXYZ will throw an error.

Example:
? SETXYZ 0 0 0

Top

Turning the turtle

These commands can be used to change the orientation or the heading of the turtle. The turtle's position stays the same. In three dimensional space, there are six turns as opposed to two turns (LEFT and RIGHT) in traditional 2D Logo. These turning commands are based on the turtle's current orientation.

RIGHT degree

RT degree

RIGHT changes the turtle's heading by the specified number of degrees to its right. The turtle's position is not changed. 360 degrees is the same as 0 degree. The degree can be greater than 360. Negative degree means to turn LEFT. If the given input is not a number, RIGHT will throw an error.

LEFT degree

LT degree

LEFT changes the turtle's heading by the specified number of degrees to its left. The turtle's position is not changed. 360 degrees is the same as 0 degree. The degree can be greater than 360. Negative degree means to turn RIGHT. If the given input is not a number, LEFT will throw an error.

ROLLUP degree

RU degree

ROLLUP changes the turtle's heading by pitching up the specified number of degrees. The turtle's position is not changed. 360 degrees is the same as 0 degree. The degree can be greater than 360. Negative degree means to ROLLDOWN. If the given input is not a number, ROLLUP will throw an error.

ROLLDOWN degree

RD degree

ROLLDOWN changes the turtle's heading by pitching down the specified number of degrees. The turtle's position is not changed. 360 degrees is the same as 0 degree. The degree can be greater than 360. Negative degree means to ROLLUP. If the given input is not a number, LEFT will throw an error.

TILTRIGHT degree

TR degree

TILTRIGHT changes the turtle's heading by yawing the specified number of degrees to its right. The turtle's position is not changed. 360 degrees is the same as 0 degree. The degree can be greater than 360. Negative degree means to TILTLEFT. If the given input is not a number, TILTRIGHT will throw an error.

TILTLEFT degree

TL degree

TILTLEFT changes the turtle's heading by yawing the specified number of degrees to its left. The turtle's position is not changed. 360 degrees is the same as 0 degree. The degree can be greater than 360. Negative degree means to TILTRIGHT. If the given input is not a number, TILTLEFT will throw an error.

Top

Creating objects

In the 3D space of VRMath, we can create geometrical objects. Even the turtle tracks are geometrical objects. They are not pen drawings of pixel on computer screen. All object can be affected by SCALE settings.

PENDOWN
PD

PENDOWN starts a turtle track object which can be POINTs, LINEs, or FACEs. Any subsequent move commands will cause the turtle to create points or lines or faces in the current pen color or material settings.

PENUP

PU

PENUP ends the current turtle track object. The turtle will not perform any drawing during subsequent move commands.

PENERASE

PE

PENERASE is used only while it is PENDOWN. It will undo the last move of the turtle.

BOX

CUBE

BOX or CUBE command creates a 1 meter3 cube with current material settings at turtle's current position and orientation.

BALL

SPHERE

BALL or SPHERE command creates a radius 0.5 meter sphere with current material settings at turtle's current position and orientation.

CONE

CONE command creates a 1 meter height and radius 0.5 meter circle bottom cone with current material settings at turtle's current position and orientation.

CAN

CYLINDER

CAN or CYLINDER command creates a 1 meter height and radius 0.5 meter circle on top and bottom cylinder with current material settings at turtle's current position and orientation.

LABEL expr

LABEL creates the specified expression in 3D space as text according to the current material settings, font settings, and turtle's position and orientation. The expr should be a Logo WORD or LIST.

Example:
? LABEL "HelloWorld 
? LABEL [I love VRMath!]

*Top

Colouring commands

Colouring commands are used in association with POINT, LINE, and FACE objects created by PENDOWN and PENUP commands. In VRMath, there is a Pen Color Editor with 70 pre selected colours. VRMath uses the RGB model of expressing colours. Each value of R, G, and B is ranged between 0 to 1000.

SETPENCOLOR color
SETPC color

SETPENCOLOR sets the color of the drawing pen. The color may be in the format of a three-element list in which the elements are the RGB values, each between 0 and 255. It may also be a word specifying a color from the palette. If the input is a list with more or less than three elements or elements that are not integers between 0 and 255, or if the input is a word that does not correspond to an entry in the color palette, SETPENCOLOR throws an error.

SETBACKGROUND color
SETBG color

SETBACKGROUND sets the color of the background, also the color of the eraser. The color may be in the format of a three-element list in which the elements are the RGB values, each between 0 and 255. It may also be a word specifying a color from the palette. If the input is a list with more or less than three elements or elements that are not integers between 0 and 255, or if the input is a word that does not correspond to an entry in the color palette, SETBACKGROUND throws an error.

GETPENCOLOR
GETPC

GETPENCOLOR returns the color of the pen, in the form of a three-element list representing the RGB color. Each value in the list will be an integer between 0 and 255.

GETBACKGROUND
GETBG

GETBACKGROUND returns the color of the background, also the color of the eraser, in the form of a three-element list representing the RGB color. Each value in the list will be an integer between 0 and 255.

*Top

 

Color Palette Operations

These commands manipulate the color palette, which are values that can be used in SETPENCOLOR and SETBACKGROUND. The default color palette consists of standard system color numbers, and a selection of color names. Colors may be added to or removed from the palette. The default palette, set up when Turtle Tracks starts, is as follows:

 

System color numbers
Color number Color RGB Value
0 black [ 0 0 0 ]
1 blue [ 0 0 255 ]
2 green [ 0 255 0 ]
3 cyan [ 0 255 255 ]
4 red [ 255 0 0 ]
5 magenta [ 255 0 255 ]
6 yellow [ 255 255 0 ]
7 white [ 255 255 255 ]
Turtle Tracks color names
Color name RGB Value
"BLACK [ 0 0 0 ]
"BLUE [ 0 0 255 ]
"CYAN [ 0 255 255 ]
"DARKGRAY [ 64 64 64 ]
"GRAY [ 128 128 128 ]
"GREEN [ 0 255 0 ]
"LIGHTGRAY [ 192 192 192 ]
"MAGENTA [ 255 0 255 ]
"ORANGE [ 255 200 0 ]
"PINK [ 255 175 175 ]
"RED [ 255 0 0 ]
"WHITE [ 255 255 255 ]
"YELLOW [ 255 255 0 ]

SETPALETTE name rgblist

SETPALETTE associates the given color name with the given rgblist. It will then be possible to use the name to specify pen color or background color. If the first argument is not a word, or the second argument is not a list with three integer elements between 0 and 255, SETPALETTE throws an error.

UNSETPALETTE name

UNSETPALETTE disassociates the given color name, removing it from the palette. If no color with the given name exists, UNSETPALETTE does nothing. If the argument is not a word, UNSETPALETTE throws an error.

RESETPALETTE

RESETPALETTE sets the color palette to its default.

PALETTE name

PALETTE returns the rgblist associated with the given color name. If the specified color name is not found in the color palette, PALETTE returns the empty list. If the argument is not a word, PALETTE throws an error.

PALETTE? name
PALETTEP name

PALETTE? returns "TRUE if the given name is in the color palette, or "FALSE if not. If the argument is not a word, PALETTE? throws an error.

*Top

CLEAN

CS

CLEAN fills the entire graphics window with the current background color. The current turtle position and state are not affected.

CLEARSCREEN
CS

CLEARSCREEN moves the turtle to the home position, and fills the entire graphics window with the current background color.

*Top

Turtle Motion

SETHEADING number

SETHEADING sets the heading of the turtle to the given value, in degrees. A heading of 0 points straight up, and positive values run clockwise. The position of the turtle is not changed. If the given input is not a number, SETHEADING will throw an error.

HOME

HOME moves the turtle to the origin. It has the same effect as SETXY 0 0. The heading of the turtle is not changed. If the pen is currently down, the turtle will draw a line along its path.

*Top

Turtle Position Queries

These commands can be used to get information about the turtle's position and heading.

XCOR

XCOR returns the current x-coordinate of the turtle.

YCOR

YCOR returns the current x-coordinate of the turtle.

POS

POS returns the current position of the turtle in the form of a two-element list, where the first element is the x-coordinate and the second element is the y-coordinate.

HEADING

HEADING returns the current heading of the turtle, in degrees. A heading of 0 points straight up, and positive values run clockwise.

DISTANCETOXY xcor ycor

DISTANCETOXY returns the distance from the current turtle position to the given coordinates. The position and heading of the turtle are not changed. If the given inputs are not numbers, DISTANCETOXY will throw an error.

DISTANCETO poslist

DISTANCETO returns the distance from the current turtle position to the given coordinates. The input must be a two-element list, the first element being the x-coordinate and the second being the y-coordinate. The position and heading of the turtle are not changed. If the given input is not a list or does not contain exactly two numeric elements, DISTANCETO will throw an error.

TOWARDSXY xcor ycor

TOWARDSXY returns the heading pointing from the turtle position to the given coordinates, in degrees. A heading of 0 points straight up, and positive values run clockwise. The position and heading of the turtle are not changed. If the given inputs are not numbers, TOWARDSXY will throw an error.

TOWARDS poslist

TOWARDS returns the heading pointing from the turtle position to the given coordinates, in degrees. The input must be a two-element list, the first element being the x-coordinate and the second being the y-coordinate. A heading of 0 points straight up, and positive values run clockwise. The position and heading of the turtle are not changed. If the given input is not a list or does not contain exactly two numeric elements, TOWARDS will throw an error.

*Top

Turtle State

These commands manipulate other state information.

SHOWTURTLE
ST

SHOWTURTLE shows the turtle if it is currently hidden. If the turtle is already shown, SHOWTURTLE has no effect.

HIDETURTLE
HT

HIDETURTLE hides the turtle if it is currently shown. If the turtle is already hidden, HIDETURTLE has no effect.