edu.umd.cs.jazz
Class ZSpatialIndexGroup

java.lang.Object
  |
  +--edu.umd.cs.jazz.ZSceneGraphObject
        |
        +--edu.umd.cs.jazz.ZNode
              |
              +--edu.umd.cs.jazz.ZGroup
                    |
                    +--edu.umd.cs.jazz.ZSpatialIndexGroup
All Implemented Interfaces:
java.lang.Cloneable, java.util.EventListener, java.io.Serializable, ZGroupListener, ZSerializable

public class ZSpatialIndexGroup
extends ZGroup
implements ZGroupListener, ZSerializable, java.io.Serializable

ZSpatialIndexGroup is a group node that supports R-tree indexing for a group of visual components. This indexing can provide faster rendering when a large number of visual components are being displayed. Currently, significant speed improvements become apparent when a few thousand or more nodes are being rendered. Using a ZSpatialIndexGroup group node with a small number of nodes can actually slow down rendering, due to the indexing overhead.

To use spatial indexing, first create a large number of nodes grouped under a single ZGroup node. A scenegraph editor can then be used to add the ZSpatialIndexGroup node: groupNode.editor().getSpatialIndexGroup()

An r-tree index is created, and the spatial location information of the nodes in the group is indexed. The Jazz render methods will detect the ZSpatialIndexGroup node and use the appropriate rendering calls. When any indexed node's bounds are changed, Jazz automatically updates the index. To return to regular rendering, simply remove the ZSpatialIndexNode: groupNode.editor().removeSpatialIndexGroup();

Note: Any ZSpatialIndexGroup node must appear at the bottom of the edit node chain: its only child must be a ZGroup node. The ZSceneGraphEditor (groupNode.editor()) supports this contraint.

R-tree indexing works by building a data structure containing spatial location information for a group of nodes. During rendering, this structure is used to decide which nodes are currently visible. These nodes are then rendered.

If ZDebug.debugSpatialIndexing is set to true, the number of nodes being rendered will be reported.

For a description of the algorithm used here, see "The Design and Analysis of Spatial Data Structures" by Hanan Samet, pp 219-224. Addison-Wesley, 1989. Or source paper in "R-trees: A dynamic index structure for spatial searching" by A. Guttman, in Proceedings of SIGMOD Conference, 1984, 47-57. ZSceneGraphEditor provides a convenience mechanism to locate, create and manage nodes of this type.

Warning: Serialized and ZSerialized objects of this class will not be compatible with future Jazz releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Jazz. A future release of Jazz will provide support for long term persistence.

Author:
James Mokwa
See Also:
ZSpatialIndex, ZNode.editor(), Serialized Form

Field Summary
 
Fields inherited from class edu.umd.cs.jazz.ZGroup
children, childrenFindable_DEFAULT, childrenPickable_DEFAULT, childrenVolatileBoundsCache, hasOneChild_DEFAULT
 
Fields inherited from class edu.umd.cs.jazz.ZNode
editorFactory, findable_DEFAULT, parent, pickable_DEFAULT, savable_DEFAULT, selectable_DEFAULT
 
Fields inherited from class edu.umd.cs.jazz.ZSceneGraphObject
bounds, inTransaction, invalidBounds, invalidVolatileBounds, listenerList, volatileBounds, volatileBounds_DEFAULT
 
Constructor Summary
ZSpatialIndexGroup()
          Constructs a new ZSpatialIndexGroup node.
ZSpatialIndexGroup(ZCamera camera)
          Constructs a new ZSpatialIndexGroup node using a given camera.
ZSpatialIndexGroup(ZNode child, ZCamera camera)
          Constructs a new ZSpatialIndex group node with the specified node as a child of the new group.
 
Method Summary
 void addListener(ZTransformGroup tg)
          Add a BOUNDS_CHANGED node listener to a transformGroup node, if it does not already have one.
protected  boolean childrenFindable(ZNode node, ZBounds bounds)
          Returns true if the node intersects the bounds.
 void displayTree(java.lang.String treeName)
          Displays the spatial index tree, for debugging.
 int findNodes(ZFindFilter filter, java.util.ArrayList nodes)
          Search from this spatialIndexGroup node down, return a list of nodes that match filter bounds.
 void nodeAdded(ZGroupEvent e)
          Catches NODE_ADDED event, and tries to index the new node.
 void nodeRemoved(ZGroupEvent e)
          Catches ZGroupEvent NODE_REMOVED event, and tries to unIndex the node.
 boolean pick(java.awt.geom.Rectangle2D rect, ZSceneGraphPath path)
          Returns the first object under the specified rectangle (if there is one) in the subtree rooted with this ZSpatialIndexGroup node, as searched in reverse (front-to-back) order.
 void removeChild(ZNode child)
          Removes the ZGroup child from this ZSpatialIndexGroup.
 void render(ZRenderContext renderContext)
          Renders this node which results in its children getting painted.
 void unregisterAllListeners()
          Stop listening to nodeEvents from any indexed children.
 void unregisterAllListeners(ZGroup group)
          Stop listening to nodeEvents from any indexed children.
 
Methods inherited from class edu.umd.cs.jazz.ZGroup
addChild, addChildImpl, addChildren, addChildren, addGroupListener, childAddedNotification, childRemovedNotification, computeBounds, computeVolatileBounds, dump, duplicateObject, extract, getChild, getChildren, getChildrenFindable, getChildrenIterator, getChildrenPickable, getChildrenReference, getNumChildren, getShallowBounds, getVolatileBounds, hasOneChild, indexOf, insertAbove, iterator, lower, lowerTo, markInTransaction, markNotInTransaction, raise, raiseTo, removeAllChildren, removeAllChildren, removeChild, removeChild, removeChildImpl, removeGroupListener, removeNodeListener, setChildrenFindable, setChildrenPickable, setHasOneChild, setState, trimToSize, updateHasNodeListener, writeObject, writeObjectRecurse
 
Methods inherited from class edu.umd.cs.jazz.ZNode
addNodeListener, editor, getGlobalBounds, getGlobalToLocalTransform, getLocalToGlobalTransform, getParent, getRoot, globalToLocal, globalToLocal, globalToLocal, hasNodeListener, isAncestorOf, isDescendentOf, isFindable, isPickable, isSavable, isSelectable, localToGlobal, localToGlobal, localToGlobal, lower, lowerTo, percolateEventUpSceneGraph, raise, raiseTo, remove, repaint, repaint, reparent, replaceWith, setEditorFactory, setFindable, setParent, setPickable, setSavable, setSelectable, setVolatileBounds, updateBounds, updateVolatility, writeReplace
 
Methods inherited from class edu.umd.cs.jazz.ZSceneGraphObject
addClientProperty, addMouseListener, addMouseMotionListener, clone, endTransaction, fireEvent, fireMouseEvent, getBounds, getBoundsReference, getClientProperty, getHandles, getListenerList, hasLisenerOfType, hasListenerOfType, hasMouseListener, processMouseEvent, putClientProperty, removeEventListener, removeMouseListener, removeMouseMotionListener, reshape, setBounds, startTransaction, updateObjectReferences
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface edu.umd.cs.jazz.io.ZSerializable
setState, writeObject, writeObjectRecurse
 

Constructor Detail

ZSpatialIndexGroup

public ZSpatialIndexGroup()
Constructs a new ZSpatialIndexGroup node.


ZSpatialIndexGroup

public ZSpatialIndexGroup(ZCamera camera)
Constructs a new ZSpatialIndexGroup node using a given camera.


ZSpatialIndexGroup

public ZSpatialIndexGroup(ZNode child,
                          ZCamera camera)
Constructs a new ZSpatialIndex group node with the specified node as a child of the new group.

Parameters:
child - Child of the new group node.
camera - the camera.
Method Detail

displayTree

public void displayTree(java.lang.String treeName)
Displays the spatial index tree, for debugging.

Parameters:
treeName - string displayed when tree is printed.

addListener

public void addListener(ZTransformGroup tg)
Add a BOUNDS_CHANGED node listener to a transformGroup node, if it does not already have one. If a indexed node's bounds change, it needs to be re-indexed.

Parameters:
tg - the transformGroup node.

nodeAdded

public void nodeAdded(ZGroupEvent e)
Catches NODE_ADDED event, and tries to index the new node.

Specified by:
nodeAdded in interface ZGroupListener
Parameters:
e - the event.

nodeRemoved

public void nodeRemoved(ZGroupEvent e)
Catches ZGroupEvent NODE_REMOVED event, and tries to unIndex the node.

Specified by:
nodeRemoved in interface ZGroupListener
Parameters:
e - the event.

unregisterAllListeners

public void unregisterAllListeners(ZGroup group)
Stop listening to nodeEvents from any indexed children. Do this prior to deleting this index group.

Parameters:
group - the group node whose children are indexed.

unregisterAllListeners

public void unregisterAllListeners()
Stop listening to nodeEvents from any indexed children. Do this prior to deleting this index group.


pick

public boolean pick(java.awt.geom.Rectangle2D rect,
                    ZSceneGraphPath path)
Returns the first object under the specified rectangle (if there is one) in the subtree rooted with this ZSpatialIndexGroup node, as searched in reverse (front-to-back) order. This performs a depth-first search, first picking children. Only returns a node if this is "pickable".

If childrenPickable is false, then this will never return a child as the picked node. Instead, this node will be returned if any children are picked. If no children are picked, then this will return null.

Overrides:
pick in class ZGroup
Parameters:
rect - Coordinates of pick rectangle in local coordinates
path - The path through the scenegraph to the picked node. Modified by this call.
Returns:
The picked node, or null if none
See Also:
ZDrawingSurface.pick(int, int)

render

public void render(ZRenderContext renderContext)
Renders this node which results in its children getting painted.

The transform, clip, and composite will be set appropriately when this object is rendered. It is up to this object to restore the transform, clip, and composite of the Graphics2D if this node changes any of them. However, the color, font, and stroke are unspecified by Jazz. This object should set those things if they are used, but they do not need to be restored.

Overrides:
render in class ZGroup
Parameters:
renderContext - The graphics context to use for rendering.

removeChild

public void removeChild(ZNode child)
Removes the ZGroup child from this ZSpatialIndexGroup. Stops listening to NodeEvents from indexed nodes, and re-initializes the rtree index.

Overrides:
removeChild in class ZGroup
Parameters:
child - the ZGroup node whose children are indexed.
See Also:
ZGroupEvent

childrenFindable

protected boolean childrenFindable(ZNode node,
                                   ZBounds bounds)
Returns true if the node intersects the bounds.


findNodes

public int findNodes(ZFindFilter filter,
                     java.util.ArrayList nodes)
Search from this spatialIndexGroup node down, return a list of nodes that match filter bounds.

Overrides:
findNodes in class ZGroup
Parameters:
filter - The filter that decides whether or not to include individual nodes in the find list
nodes - the accumulation list (results will be place here).
Returns:
the number of nodes searched
See Also:
ZNode.isFindable(), ZFindFilter


Copyright 2003 by University of Maryland, College Park, MD 20742, USA All rights reserved.