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

Fields inherited from class edu.umd.cs.jazz.ZGroup

children, childrenFindable_DEFAULT, childrenPickable_DEFAULT, hasOneChild_DEFAULT

Fields inherited from class edu.umd.cs.jazz.ZNode

findable_DEFAULT, pickable_DEFAULT, savable_DEFAULT, selectable_DEFAULT

Fields inherited from class edu.umd.cs.jazz.ZSceneGraphObject

bounds, 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, addGroupListener, childAddedNotification, childRemovedNotification, computeBounds, dump, duplicateObject, extract, getChild, getChildren, getChildrenFindable, getChildrenIterator, getChildrenPickable, getChildrenReference, getNumChildren, getShallowBounds, getVolatileBounds, hasOneChild, indexOf, insertAbove, iterator, lower, lowerTo, raise, raiseTo, removeAllChildren, removeChild, removeChild, removeChildImpl, removeGroupListener, removeNodeListener, setChildrenFindable, setChildrenPickable, setHasOneChild, setState, trimToSize, updateHasNodeListener, updateVolatility, writeObject, writeObjectRecurse

Methods inherited from class edu.umd.cs.jazz.ZNode

addClientProperty, addNodeListener, editor, getClientProperty, getGlobalBounds, getGlobalToLocalTransform, getLocalToGlobalTransform, getParent, getRoot, globalToLocal, globalToLocal, hasNodeListener, isAncestorOf, isDescendentOf, isFindable, isPickable, isSavable, isSelectable, localToGlobal, localToGlobal, lower, lowerTo, percolateEventUpSceneGraph, putClientProperty, raise, raiseTo, remove, repaint, repaint, repaint, reparent, replaceWith, setEditorFactory, setFindable, setParent, setPickable, setSavable, setSelectable, updateBounds, updateObjectReferences, writeReplace

Methods inherited from class edu.umd.cs.jazz.ZSceneGraphObject

addMouseListener, addMouseMotionListener, clone, fireEvent, fireMouseEvent, getBounds, getBoundsReference, getListenerList, hasLisenerOfType, hasMouseListener, processMouseEvent, removeEventListener, removeMouseListener, removeMouseMotionListener, reshape, setBounds, setVolatileBounds

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.

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

Following copied from class: edu.umd.cs.jazz.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