[N-World Contents] [Book Contents] [Prev] [Next] [Index]

This chapter describes how to use the predefined iteration paths with the loop macro to traverse elements of N-Geometry bodies and objects.

Loop Iteration Paths vs. Short Forms

Traversing is a means of accessing elements of a data structure (such as a body or object) in an ordered way. In order to simplify this access, predefined iteration paths have been defined in the N·World development environment.

Consider the following predefined iteration path, which can be used to traverse the vertices of a polyhedron:

vertex-ring-elements
This iteration path could be used to traverse all the vertices of a polyhedron, regardless of its topological structure. For example:

(loop for v being the vertex-ring-elements of-polyhedron my-polyhedron


			do (do-something v))
A short form of the vertex-ring-elements iteration path has also been defined in the N·World development environment:

do-vertices iteration-list &body body
This short form can also be used to traverse all the vertices of the same polyhedron:

(do-vertices (v my-polyhedron)


	(do-something v))
These two forms are functionally equivalent. The sections below show when to use one form over the other.

When to Use loop

Use the loop iteration paths:

For example:

(loop for v being the vertex-ring-elements of-polyhedron my-polyhedron


			for index from 0


			collect (list index (get-serial-number v))
This form returns a list that is generated while the element is traversed.

Note. The loop macro will be integrated into the loop macro in version 3.0 of N·World.

When to use Do-Element Short Forms

Use the short form:

For example, to achieve the same results in the loop example above with do-vertices, we'd need something like this:

(let ((index 0)


		(return-list nil))


	(do-vertices (v my-polyhedron)


		(push (list index (get-serial-number v)) return-list)


		(incf index))


	(reverse return-list))
As you can see, using short forms can actually increase the complexity of your code very quickly. They should be used selectively.

Traversing Elements of a Polyhedron through
Element Rings

The components of a polyhedron are:

For instance, all the vertices belonging to a polyhedron are connected in a circular, double-pointed list. This list is called the vertex "ring."

From any vertex, we can access the next and previous element of the ring. The elements do not have any specific ordering inside the ring.

In a like manner, both edge and face rings exist for any given polyhedron.

Predefined iteration paths are:

vertex-ring-elements

edge-ring-elements

face-ring-elements

These are used with the special preposition of-polyhedron, and "walk over" the vertices, edges, or faces of a polyhedron in the opposite order from which they were inserted (last inserted comes first).

vertex-reverse-elements

edge-reverse-elements

face-reverse-elements

These are used with the special preposition of-polyhedron, and "walk over" the vertices, edges, or faces of a polyhedron in insertion order.

For example:

(loop for v being the vertex-reverse-elements of-polyhedron my-tetrahedron


          do (print v))
Returns:

#<VERTEX 1 (   0.00   20.00    0.00)> 


#<VERTEX 2 (   0.00   -6.67   18.86)> 


#<VERTEX 3 (  16.33   -6.67   -9.43)> 


#<VERTEX 4 ( -16.33   -6.67   -9.43)> 


NIL

Equivalent Short Forms

 The equivalent short forms for the loop iteration paths described in the previous section are:

do-vertices iteration-list &body body


do-edges iteration-list &body body


do-faces iteration-list &body body




do-vertices-backward iteration-list &body body


do-edges-backward iteration-list &body body


do-faces-backward iteration-list &body body
For example:

(do-vertices-backward (v my-tetrahedron)


  (print v))
Returns:

#<VERTEX 1 (   0.00   20.00    0.00)> 


#<VERTEX 2 (   0.00   -6.67   18.86)> 


#<VERTEX 3 (  16.33   -6.67   -9.43)> 


#<VERTEX 4 ( -16.33   -6.67   -9.43)> 


NIL

Traversing Elements of a Face

 You can use faces to traverse vertices and edges in an ordered manner. Iteration paths to traverse a face are:

component-vertices


component-edges
These are used with the special prepositions of-face, from, to, from-edge, and to-edge and "walk over" the vertices or edges of a face in clockwise order.

If a from-edge preposition is provided the looping will start on that edge and continue around; if a from preposition is provided it must be of the same type as the loop variable and will cause the loop to start on the edge related to the from element; otherwise it will start on the face's segment-ptr.

ccw-component-vertices


ccw-component-edges
These iteration paths are identical to the two described above, except they traverse the face in a counterclockwise direction.

For example:

(loop for f being the face-reverse-elements of-polyhedron my-tetrahedron


          do (print f)


          (loop for v being the component-vertices of-face f


                    do (print v))


          )
Returns:

#<FACE 1> 


#<VERTEX 1 (   0.00   20.00    0.00)> 


#<VERTEX 3 (  16.33   -6.67   -9.43)> 


#<VERTEX 2 (   0.00   -6.67   18.86)> 


#<FACE 2> 


#<VERTEX 1 (   0.00   20.00    0.00)> 


#<VERTEX 2 (   0.00   -6.67   18.86)> 


#<VERTEX 4 ( -16.33   -6.67   -9.43)> 


#<FACE 3> 


#<VERTEX 1 (   0.00   20.00    0.00)> 


#<VERTEX 4 ( -16.33   -6.67   -9.43)> 


#<VERTEX 3 (  16.33   -6.67   -9.43)> 


#<FACE 4> 


#<VERTEX 2 (   0.00   -6.67   18.86)> 


#<VERTEX 3 (  16.33   -6.67   -9.43)> 


#<VERTEX 4 ( -16.33   -6.67   -9.43)> 


NIL

Equivalent Short Forms

 The equivalent short forms for the loop iteration paths described in the previous section are:

do-face-vertices iteration-list &body body


do-face-edges iteration-list &body body




do-face-vertices-backward iteration-list &body body


do-face-edges-backward iteration-list &body body

Traversing Neighboring Elements of a Vertex

 You can traverse a vertex's neighboring vertices, edges, or faces in an ordered manner using iteration paths:

vertex-neighbors


edge-neighbors


face-neighbors
These are used with the special prepositions of-vertex and from-edge, and "walk over" the neighboring vertices, edges, or faces in counterclockwise order.

If a from-edge preposition is provided the looping will start on that edge and continue around.

cw-vertex-neighbors


cw-edge-neighbors


cw-face-neighbors
Like the iteration paths above, except traverses in a clockwise order.

For example:

(loop for v being the vertex-ring-elements of-polyhedron my-tetrahedron


          collect
			(list v (loop for e being the cw-edge-neighbors of-vertex v collect e))
	)
Returns:

((#<VERTEX 4 ( -16.33   -6.67   -9.43)> (#<EDGE 4> #<EDGE 6> #<EDGE 5>))


 (#<VERTEX 3 (  16.33   -6.67   -9.43)> (#<EDGE 1> #<EDGE 6> #<EDGE 2>))


 (#<VERTEX 2 (   0.00   -6.67   18.86)> (#<EDGE 2> #<EDGE 4> #<EDGE 3>))


 (#<VERTEX 1 (   0.00   20.00    0.00)> (#<EDGE 1> #<EDGE 3> #<EDGE 5>)))

Equivalent Short Forms

 The equivalent short forms for the loop iteration paths described in the previous section are:

do-vertex-vertices iteration-list &body body


do-vertex-edges iteration-list &body body


do-vertex-faces iteration-list &body body
For example:

(do-vertices (v my-tetrahedron)


  (print v)


  (do-vertex-edges (e v)


    (print e))


  )
Returns:

#<VERTEX 4 ( -16.33   -6.67   -9.43)> 


#<EDGE 4> 


#<EDGE 5> 


#<EDGE 6> 


#<VERTEX 3 (  16.33   -6.67   -9.43)> 


#<EDGE 1> 


#<EDGE 2> 


#<EDGE 6> 


#<VERTEX 2 (   0.00   -6.67   18.86)> 


#<EDGE 2> 


#<EDGE 3> 


#<EDGE 4> 


#<VERTEX 1 (   0.00   20.00    0.00)> 


#<EDGE 1> 


#<EDGE 5> 


#<EDGE 3> 


NIL
Note. There are currently no macros defined to traverse neighboring elements in a clockwise direction.

Traversing Elements of a Wire

Wires have a much simpler structure than polyhedra. Because the elements in a wire have, by definition, a linear order, we need define only a single set of iteration paths.

node-elements


segment-elements
Used with the special preposition of-wire.

Walks over the elements of a wire.

For example:

(loop for n being the node-elements of-wire my-wire


          do (print n))
Returns:

#<WIRE-NODE 1 (   0.00    0.00    0.00)> 


#<WIRE-NODE 2 (   0.00    1.00    0.00)> 


#<WIRE-NODE 3 (   0.00    2.00    0.00)> 


#<WIRE-NODE 4 (   0.00    3.00    0.00)> 


NIL

Equivalent Short Forms

 The equivalent short forms for the loop iteration paths described in the previous section are:

do-wire-nodes iteration-list &body body


do-wire-segments iteration-list &body body
For example:

(do-wire-segments (s my-wire)


  (print s))
Returns:

#<WIRE-SEGMENT 1> 


#<WIRE-SEGMENT 2> 


#<WIRE-SEGMENT 3> 


NIL

Traversing Object Hierarchy

 To traverse an object hierarchy, use the following loop iteration paths:

objects


all-objects


terminal-objects


bdis


bodies
Used with the special prepositions of-objects, of-list, or in.

Loops over a set of objects or bodies.

Of the possible targets:

For example, to loop through all the geometric bodies in the environment:

(loop for b being the bodies in *global-object-list*


          do (do-something b))
There are no short forms for this special form.


[N-World Contents] [Book Contents] [Prev] [Next] [Index]

Another fine product from Nichimen documentation!

Copyright © 1996, Nichimen Graphics Corporation. All rights reserved.