NetLogo 3D Preview 5 User Manual: 3D Primitives

at-points

agentset at-points [[x1 y1 z1] [x2 y2 z2] ...]

Reports a subset of the given agentset that includes only the agents on the patches the given distances away from the calling agent. The distances are specified as a list of three-item lists, where the three items are the x, y, and z offsets.

If the caller is the observer, then the points are measured relative to the origin, in other words, the points are taken as absolute patch coordinates.

If the caller is a turtle, the points are measured relative to the turtle's exact location, and not from the center of the patch under the turtle.

ask turtles at-points [[2 4 0] [1 2 1] [10 15 10]]
[ fd 1 ]  ;; only the turtles on the patches at the
          ;; distances (2,4,0), (1,2,1) and (10,15,10),
          ;; relative to the caller, move

distancexyz
distancexyz-nowrap

distancexyz xcor ycor zcor
distancexyz-nowrap xcor ycor zcor

3D versions of distancexy and distancexy-nowrap.

Reports the distance from this agent to the point (xcor, ycor, zcor).

The distance from a patch is measured from the center of the patch.

distancexyz-nowrap always reports the in world distance, never a distance that would require wrapping around the edges of the world. With distancexyz the wrapped distance (around the edges of the world) is used if that distance is shorter than the in world distance.

if (distancexyz 0 0 0) < 10
  [ set color green ]
;; all turtles less than 10 units from
;; the center of the screen turn green.

dz

Reports the z-increment (the amount by which the turtle's zcor would change) if the turtle were to take one step forward at its current heading and pitch.

NOTE: dz is simply the sine of the turtle's pitch. Both dx and dy have changed in this case. So, dx = cos(pitch) * sin(heading) and dy = cos(pitch) * cos(heading).

face
facexyz

face agent
facexyz x y z

Set the caller's heading and pitch towards agent or towards the point (x,y,z).

If the caller and the target are at the same x and y coordinates the caller's heading will not change. If the caller and the target are also at the same z coordinate the pitch will not change either.

left

left number

The turtle turns left by number degrees, relative to its current orientation. While left in a 2D world only modifies the turtle's heading, left in a 3D world may also modify the turtle's pitch and roll.

link-pitch

Reports the pitch from end1 to end2 of the calling link.

ask link 0 1 [ print link-pitch ] 
;; prints [[towards-pitch other-end] of end1] of link 0 1

load-shapes-3D

load-3D-shapes filename

Loads custom 3D shapes from the given file. See the 3D guide for more details. You must also add a shape of the same name to the model using the shapes editor. Custom shapes override built-in 3D shapes and converted 2D shapes.

max-pzcor
min-pzcor

These reporters give the maximum and minimum z-coordinates (respectively) for patches, which determines the size of the world.

Unlike in older versions of NetLogo the origin does not have to be at the center of the world. However, the minimum z-coordinate has to be less than or equal to 0 and the maximum z-coordinate has to be greater than or equal to 0.

Note: You can set the size of the world only by editing the view -- these are reporters which cannot be set.

See also max-pxcor, max-pycor, min-pxcor, min-pycor, and world-width.

neighbors
neighbors6

3D versions of neighbors and neighbors4.

Reports an agentset containing the 26 surrounding patches (neighbors) or 6 surrounding patches (neighbors6).

show sum values-from neighbors [count turtles-here]
  ;; prints the total number of turtles on the twenty-six
  ;; patches around the calling turtle or patch
ask neighbors6 [ set pcolor red ]
  ;; turns the six neighboring patches red

orbit-down
orbit-left
orbit-right
orbit-up

orbit-down number
orbit-left number
orbit-right number
orbit-up number

Rotate the observer around the last point faced. Imagine the observer is on the surface of a sphere, the last point face is the center of that sphere. Up and down orbit along the lines of longitude and right and left orbit along the lines of latitude. The observer will remain facing the last point faced so the heading and pitch may change as result of orbiting. However, because we assume an absolute north pole (parallel to the positive z-axis) the roll will never change.

oxcor
oycor
ozcor

Reports the x-, y-, or z-coordinate of the observer.

P

patch

patch pxcor pycor pzcor

3D version of patch.

Given three integers, reports the single patch with the given pxcor, pycor and pzcor. pxcor, pycor and pzcor must be integers.

ask (patch 3 -4 2) [ set pcolor green ]
;; patch with pxcor of 3 and pycor of -4 and pzcor of 2 turns green

patch-at

patch-at dx dy dz

3D version of patch-at.

Reports the single patch at (dx, dy, dz) from the caller, that is, dx patches east, dy patches north and dz patches up from the caller.

ask patch-at 1 -1 1 [ set pcolor green ]
;; turns the patch just southeast and up from the caller green

patch-at-heading-pitch-and-distance

patch-at-heading-pitch-and-distance heading pitch distance

3D version of patch-at-heading-and-distance.

patch-at-heading-pitch-and-distance reports the single patch that is the given distance from the calling turtle or patch, along the given absolute heading and pitch. (In contrast to patch-left-and-ahead and patch-right-and-ahead, the calling turtle's current heading is not taken into account.)

ask patch-at-heading-pitch-and-distance 0 90 1 [ set pcolor green ]
;; turns the patch directly above the caller green.

pitch

This is a built-in turtle variable. Pitch is the angle between the "nose" of the turtle and the xy-plane. Heading and pitch together define the forward vector of the turtle or the direction that the turtle is facing.

This is a number greater than or equal to 0 and less than 360. 0 is parallel to the xy-plane, 90 is parallel to the z-axis. While you can set pitch we recommend that you use the primitives to turn the turtle. Depending on the position more than one relative angle (heading, pitch and roll) may change at once.

Example:

;; assume roll and heading are 0
set pitch 45      ;; turtle is now north and up
set heading heading + 10 ;; same effect as "tilt-up 10"

See also heading, roll, tilt-up, tilt-down, right, left

pzcor

This is a built-in patch variable. It holds the z coordinate of the patch. It is always an integer. You cannot set this variable, because patches don't move.

pzcor is greater than or equal to min-pzcor and less than or equal to max-pzcor.

All patch variables can be directly accessed by any turtle standing on the patch.

random-pzcor

Reports a random integer ranging from min-pzcor to max-pxcor inclusive.

ask turtles [
  ;; move each turtle to the center of a random patch
  setxyz random-pxcor random-pycor random-pzcor
]

random-zcor

Reports a random floating point number from the allowable range of turtle coordinates along the z axis.

Turtle coordinates range from min-pzcor - 0.5 (inclusive) to max-pzcor + 0.5 (exclusive).

ask turtles [
  ;; move each turtle to a random point
  setxyz random-xcor random-ycor random-zcor
]

right

right number

The turtle turns right by number degrees, relative to its current orientation. While right in a 2D world only modifies the turtle's heading, right in a 3D world may also modify the turtle's pitch and roll.

roll

This is a built-in turtle variable. Roll is the angle between the "wing-tip" of the turtle and the xy-plane.

This is a number greater than or equal to 0 and less than 360. You can set this variable to make a turtle roll. Since roll is always from the turtle's point of view, rolling right and left only only change roll regardless of turtle orientation.

Example:

set roll 45      ;; turtle rotated right
set roll roll + 10 ;; same effect as "roll-right 10"

See also heading, pitch, roll-left, roll-right.

roll-left

roll-left number

The wingtip of the turtle rotates to the left number degrees with respect to the current heading and pitch.

roll-right

roll-right number

The wingtip of the turtle rotates to the right number degrees with respect to the current heading and pitch.

setxyz

setxyz x y z

3D version of setxy.

The agent, a turtle or the observer, sets its x-coordinate to x, its y-coordinate to y and its z-coordinate to z. When the observer uses setxyz it remains facing the same point so the heading, pitch, and roll, may also change.

For turtles equivalent to set xcor x set ycor y set zcor z, except it happens in one time step instead of three.

setxyz 0 0 0
;; agent moves to the middle of the center patch

tilt-down
tilt-up

tilt-down number
tilt-up number

The nose of the turtle rotates by number degrees, relative to its current orientation. Depending on the orientation of the turtle more than one of the relative angles (heading, pitch, and roll) may change when a turtle turns.

towards-pitch
towards-pitch-nowrap

towards-pitch agent
towards-pitch-nowrap agent

Reports the pitch from this agent to the given agent.

If the wrapped distance (around the edges of the screen) is shorter than the on-screen distance, towards-pitch will report the pitch of the wrapped path. towards-pitch-nowrap never uses the wrapped path.

Note: In order to get one turtle to face another you need to use both towards-pitch and towards.

Note: asking for the pitch from an agent to itself, or an agent on the same location, will cause a runtime error.

towards-pitch-xyz
towards-pitch-xyz-nowrap

towards-pitch-xyz x y z
towards-pitch-xyz-no-wrap x y z

Reports the pitch from this agent to the coordinates x, y, z

If the wrapped distance (around the edges of the screen) is shorter than the on-screen distance, towards-pitch will report the pitch of the wrapped path. towards-pitch-nowrap never uses the wrapped path.

Note: In order to get a turtle to face a given location you need to use both towards-pitch-xyz and towardsxy.

Note: asking for the pitch from an agent to the location it is standing on will cause a runtime error.

turtles-at
<breeds>-at

turtles-at dx dy dz
<breeds>-at dx dy dz

3D versions of turtles-at and breeds-at.

Reports an agentset containing the turtles on the patch (dx, dy, dz) from the caller (including the caller itself if it's a turtle).

;; suppose I have 40 turtles at the origin
show [count turtles-at 0 0 0] of turtle 0
=> 40

world-depth

Reports the total depth of the NetLogo world.

The depth of the world is the same as max-pzcor - min-pzcor + 1.

See also max-pzcor, min-pzcor, world-width, and world-height

zcor

This is a built-in turtle variable. It holds the current z coordinate of the turtle. This is a floating point number, not an integer. You can set this variable to change the turtle's location.

This variable is always greater than or equal to (- screen-edge-z) and strictly less than screen-edge-z.

See also setxy, xcor, ycor, pxcor, pycor, pzcor

zoom

zoom number

Move the observer toward the point it is facing, number steps. The observer will never move beyond the point it is facing so if number is greater than the the distance to that point it will only move as far as the point it is facing.

NetLogo 3D: Primitives

Commands and Reporters

Turtle-related primitives

Patch-related primitives

Agentset primitives

World primitives

Observer primitives

Link primitives

Built-In Variables

Turtles

Patches

A