NetLogo 3D

NetLogo includes the NetLogo 3D application, a preview release that allows you to create 3D worlds.

Notice: NetLogo's support for 3D is experimental. Models created with this release may not be compatible with future versions. While we've made efforts to ensure a quality product, NetLogo 3D has not been subject to the same level of quality control as the main application.

• Introduction
• Tutorial
• Dictionary

Introduction

To get started using NetLogo 3D, launch the NetLogo 3D application and check out the Sample Models in the 3D section of the Models Library.

When you're ready to write your own 3D model, look at the Code Examples in the 3D section of the Models Library.

Code Example: Turtle Perspective Example 3D helps you learn about the different perspectives.

Code Example: Turtle and Observer Motion Example 3D helps you understand how turtles and the observer move in 3D. You can also step through this model with the tutorial below.

3D Worlds

An unspeakable horror seized me. There was a darkness; then a dizzy, sickening sensation of sight that was not like seeing; I saw a Line that was no Line; Space that was not Space: I was myself, and not myself. When I could find voice, I shrieked loud in agony, "Either this is madness or it is Hell."

"It is neither," calmly replied the voice of the Sphere, "it is Knowledge; it is Three Dimensions: open your eye once again and try to look steadily."
-- Edwin A. Abbott, Flatland: A romance in many dimensions

NetLogo 3D's world has width, height and depth. Patches are cubes. In addition to pxcor and pycor, patches have pzcor.

Turtles have three Cartesian coordinates, instead of two, to describe position. In addition to xcor and ycor, turtles have zcor.

A turtle's orientation is defined by three turtle variables, heading, pitch and roll. You can imagine the turtle as having two vectors to define its orientation in 3D space. One vector comes straight out of the nose of the turtle, this is the direction the turtle will travel when it moves forward. The second vector is perpendicular to the forward vector and comes out of the right side of the turtle (as if the turtle were to stick its right arm straight out from its body). Heading is the angle between the forward vector of the turtle projected onto the xy-plane and the vector [0 1 0]. Pitch is the angle between the forward vector of the turtle and the xy-plane and finally roll is the angle between the right vector of the turtle and the xy-plane. When turtle turns right or left in 3D space it rotates around the down vector, that is the vector that is perpendicular to both the forward and right vectors. Depending on the orientation of the turtle more than one of the internal turtle variables may change as the result of a turn.

The observer and the 3D view

The point of view that you see the world from is considered the location and orientation of the observer. This is similar to the 3D view in NetLogo 2D. However, there are a few more ways to control the observer. You can set the point that the observer is facing by using face and facexyz which work the same way as the turtle commands, the observer turns so the center of the view is on the given point or the location of the given agent at the time it is called. You can change the location of the observer using setxyz. The observer will move to view the world as if standing on the given location, the point the observer faces will stay the same. For example create a new model and observer will be located at (0, 0, 49.5), that is, on the z-axis 49.5 patch units away from the origin and the observer is facing the origin, (0, 0, 0). If you setxyz 0 49.5 0 the observer will move so it is on the positive y-axis but it will keep the origin at the center of the view. You can also move the observer using the rotation primitives that will allow you to move the observer around the world as if on the surface of a sphere where the center is the location the observer is facing. You may notice from the above examples that the observer is not constrained to be within the bounds of the world.

Custom Shapes

NetLogo automatically interprets 2D shapes so they are extruded, like a cookie cutter shape in the 3D view. You can also use the primitive load-shapes-3d to load shapes described in an external file in a custom format described here. Currently we do not import shapes in any standard formats.

For each shape in a custom 3D shape file, a 2D shape of the same name must exist as well. You can create the 2D shape in the Turtle Shapes Editor.

The input file may contain any number of shapes with any number of rectangular or triangular surfaces. The format of the input file should be as follows:

number of shapes in file
name of first shape
type of surface ( quads or tris )
surface1
surface2
.
.
.
stop
type of surface
surfaceA
.
.
.
stop
end-shape

Each surface is defined by a unit normal vector and the vertices listed in clockwise order, tris should have three vertices and quads should have four.

normal: xn yn zn
x1 y1 z1
x2 y2 z2
x3 y3 z3
x4 y4 z4

A file declaring just a two dimensional, patch-sized, square in the xy-plane centered at the origin would look like this:

1
square
quads
normal: 0 0 1
0.15 0.15 0
-0.15 0.15 0
-0.15 -0.15 0
0.15 -0.15 0
normal: 0 0 -1
0.15 0.15 0
0.15 -0.15 0
-0.15 -0.15 0
-0.15 0.15 0
stop
end-shape

Tutorial

Step 1: Depth

One of the first things you will notice when you open NetLogo 3D is that the world is a cube instead of a square.

You can open up the Model Settings, by clicking on the "Settings..." button at the top of the 3D View. You'll notice in addition to max-pxcor, min-pxcor, max-pycor, and min-pycor, there is also max-pzcor and min-pzcor.

The z-axis is perpendicular to both the x-axis and the y-axis, when you reset-perspective it is the axis that comes straight out of the screen. In the default position max-pzcor is the face of the cube nearest to you and min-pzcor is the face farthest from you. As always min-pxcor is on the left, max-pxcor on the right, min-pycor on the bottom, and max-pycor on the top.

You'll also notice on the left side of the Model Settings that there are options for wrapping in all three directions, however, they are all checked and grayed out. Topologies are not yet supported in NetLogo 3D, so the world always wraps in all dimensions.

• Move to the Command Center and type print count patches.

Is the number smaller or larger than you expected?

In a 3D world the number of patches grows very quickly since count patches = world-width * world-height * world-depth. It's important to keep this in mind when you are building your model. Lots of patches can slow your model down or even cause NetLogo to run out of memory.

• Type ask patch 1 2 3 [ set pcolor red ] into the Command Center.
• Use the mouse in the 3D view to rotate the world.

Notice the shape of the patch and its position in relation to the edges of the world. You'll also notice that you now need three coordinates to address patches in a 3D world.

Step 2: Turtle Movement

• Open the Models Library in the File menu. (If you are on a Mac and you don't have a File menu, click on the main NetLogo window first and it should reappear.)
• Open Turtle and Observer Motion Example 3D in 3D/Code Examples

Take a moment to look for the controls and monitors. In the bottom left you'll notice a group of monitors that describe the location and orientation of the turtle, though until you press the setup button they'll all say "N/A".

• Press the "setup" button

Heading, pitch, and roll are turtle variables that represent the orientation of the turtle. Heading is absolute in relation to the x/y plane; it is the rotation of the turtle around the z-axis.

Pitch is the angle between the nose of the turtle and the xy-plane. It is relative to heading.

Roll is the rotation around the turtle's forward vector. It is relative to heading and pitch.

When turtles are created with create-turtles or create-ordered-turtles, their initial headings vary but their initial pitch and roll are always zero.

Take a look at the "Turtle Movement" buttons.

• Press the "left 1" button.

How does the turtle move? Is is the same or different from 2D NetLogo? Which of the turtle variables change?

• Press the "pitch-down 1" button.

How does the turtle move? Which of the turtle variables change?

• Press the "left 1" button again.

How does the turtle move? Is it different than the last time you pressed the "left 1" button?

• Take a little time to play with the Turtle Movement buttons, watching both how the turtle moves and which of the turtle variables change.

You probably noticed that often more than one of the turtle variables may change for a single turn. For this reason we suggest that you use the turtle commands rather than setting the orientation variables directly.

Step 3: Observer Movement

At the bottom of the interface you will see Orbit, Zoom, and Move buttons. If you have ever used the 3D view in NetLogo 2D or if you have been using the mouse controls in the 3D view through this tutorial you have been moving the observer. Changing the point of view in the 3D view is actually moving and changing the orientation of the observer. The observer has x, y and z coordinates, just like a turtle or patch, while turtles and patches are constrained to be inside the world the observer can be anywhere. Like a turtle the observer has a heading, pitch and roll, these variables control where the observer is looking, that is, what you see in the view.

• Move to the 3D view, and make sure "Orbit" is selected in the bottom left corner of the view.
• Click and hold the mouse button in the middle of the view, move the mouse left, right, up, and down.

How does the position and orientation of the observer change?

• Press the reset-perspective button in the lower right corner of the view and select "Zoom" in the lower left corner.
• Click and hold the mouse button in the middle of the view and move the mouse up and down.

Which of the observer variables change? Which stay the same?

• Try rotating the world a bit and then zoom again.
• Press the "Move" button in the lower left corner of the view.
• Click and hold the mouse button in the middle of the view and move the mouse up, down, left and right.

How does the view change? How do the observer variables change?

After you are done exploring the world using the mouse controls you can take a look at the observer control buttons in the lower left portion of the interface.

You may already be familiar with the first three buttons in the observer group from your experience with NetLogo 2D. Watch, follow, and ride, are special modes that automatically update the position and orientation of the observer. When in follow or ride mode, the observer position and orientation are the same as the turtle's. Note that follow and ride are functionally exactly the same, the difference is only visual in the 3D view. When in watch mode the observer does not move but updates to face the target agent.

• Press the "setup" button again so you are back to the default orientation.
• Press the "orbit-right" button.

How did the view change? Was it what you expected? How is it similar or different from using the mouse controls?

• Take a little time to experiment with orbit, roll and zoom buttons; notice similarities and differences to the mouse controls.

The direction of the the orbit commands refer to the direction that the observer moves. That is, imagine that the observer is on the surface of a sphere, the center of the sphere is the point that the observer is facing represented by the blue cross, by default (0,0,0). The observer will always face the center of the sphere and the radius of the sphere will remain constant. The directions, up, down, left, and right, refer to moving along the lines of latitude and the lines of longitude of the sphere. When you zoom the radius of the sphere changes but the center and the observer's orientation in relation to the center of the sphere will remain the same.

• Press one of the "setxyz" buttons.

How does the view change? How do the observer variables change?

• Press the "facexyz" button.

How does the view change? How do the observer variables change?

When you setxyz the center of the sphere remains the same (so the observer automatically keeps that point in the center of the view.) However, the radius of the sphere may change as well as the observer's orientation in relation to the center. When you facexyz or face, the center of the sphere changes but the observer does not move. The radius of the sphere may change, as well as the orientation of the observer.

Dictionary

Commands and Reporters

Turtle-related primitives

Patch-related primitives

Agentset primitives

World primitives

Observer primitives

Link primitives

Built-In Variables

Turtles

Patches

Primitives

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

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

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

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

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

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

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

;; 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"

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

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

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

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

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