BranchGroup (Java 3D Javadocs 0-SNAPSHOT API)

java.lang.Object
- org.scijava.java3d.SceneGraphObject
- - org.scijava.java3d.Node
  - - org.scijava.java3d.Group
    - - org.scijava.java3d.BranchGroup

Direct Known Subclasses:

PlatformGeometry, ViewerAvatar, ViewingPlatform
```
public class BranchGroup
extends Group
```
The BranchGroup serves as a pointer to the root of a scene graph branch; BranchGroup objects are the only objects that can be inserted into a Locale's set of objects. A subgraph, rooted by a BranchGroup node can be thought of as a compile unit. The following things may be done with BranchGroup:
- A BranchGroup may be compiled by calling its compile method. This causes the entire subgraph to be compiled. If any BranchGroup nodes are contained within the subgraph, they are compiled as well (along with their descendants).
- A BranchGroup may be inserted into a virtual universe by attaching it to a Locale. The entire subgraph is then said to be live.
- A BranchGroup that is contained within another subgraph may be reparented or detached at run time if the appropriate capabilities are set.
Note that that if a BranchGroup is included in another subgraph, as a child of some other group node, it may not be attached to a Locale.

Field Summary

Fields
Modifier and Type Field and Description

static int ALLOW_DETACH
For BranchGroup nodes, specifies that this BranchGroup allows detaching from its parent.
- Fields inherited from class org.scijava.java3d.Group
  ALLOW_CHILDREN_EXTEND, ALLOW_CHILDREN_READ, ALLOW_CHILDREN_WRITE, ALLOW_COLLISION_BOUNDS_READ, ALLOW_COLLISION_BOUNDS_WRITE
- Fields inherited from class org.scijava.java3d.Node
  ALLOW_AUTO_COMPUTE_BOUNDS_READ, ALLOW_AUTO_COMPUTE_BOUNDS_WRITE, ALLOW_BOUNDS_READ, ALLOW_BOUNDS_WRITE, ALLOW_COLLIDABLE_READ, ALLOW_COLLIDABLE_WRITE, ALLOW_LOCAL_TO_VWORLD_READ, ALLOW_LOCALE_READ, ALLOW_PARENT_READ, ALLOW_PICKABLE_READ, ALLOW_PICKABLE_WRITE, ENABLE_COLLISION_REPORTING, ENABLE_PICK_REPORTING

Fields
Modifier and Type	Field and Description
`static int`	`ALLOW_DETACH` For BranchGroup nodes, specifies that this BranchGroup allows detaching from its parent.

Constructor Summary

Constructors
Constructor and Description

BranchGroup()
Constructs and initializes a new BranchGroup node object.

Constructors
Constructor and Description
`BranchGroup()` Constructs and initializes a new BranchGroup node object.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Node`	`cloneNode(boolean forceDuplicate)` Creates a new instance of the node.
`void`	`compile()` Compiles the source BranchGroup associated with this object and creates and caches a compiled scene graph.
`void`	`detach()` Detaches this BranchGroup from its parent.
`PickInfo[]`	`pickAll(int mode, int flags, PickShape pickShape)` Returns an array unsorted references to all the PickInfo objects that are pickable below this `BranchGroup` that intersect with PickShape.
`SceneGraphPath[]`	`pickAll(PickShape pickShape)` Returns an array referencing all the items that are pickable below this `BranchGroup` that intersect with PickShape.
`PickInfo[]`	`pickAllSorted(int mode, int flags, PickShape pickShape)` Returns a sorted array of PickInfo references to all the pickable items that intersect with the pickShape.
`SceneGraphPath[]`	`pickAllSorted(PickShape pickShape)` Returns a sorted array of references to all the Pickable items that intersect with the pickShape.
`PickInfo`	`pickAny(int mode, int flags, PickShape pickShape)` Returns a PickInfo which references the pickable item below this BranchGroup that intersects with `pickShape`.
`SceneGraphPath`	`pickAny(PickShape pickShape)` Returns a reference to any item that is Pickable below this BranchGroup that intersects with `pickShape`.
`PickInfo`	`pickClosest(int mode, int flags, PickShape pickShape)` Returns a PickInfo which references the pickable item which is closest to the origin of `pickShape`.
`SceneGraphPath`	`pickClosest(PickShape pickShape)` Returns a SceneGraphPath that references the pickable item closest to the origin of `pickShape`.

Methods inherited from class org.scijava.java3d.Group
addChild, getAllChildren, getAlternateCollisionTarget, getChild, getCollisionBounds, indexOfChild, insertChild, moveTo, numChildren, removeAllChildren, removeChild, removeChild, setAlternateCollisionTarget, setChild, setCollisionBounds

Methods inherited from class org.scijava.java3d.Node
cloneTree, cloneTree, cloneTree, cloneTree, cloneTree, cloneTree, duplicateNode, getBounds, getBoundsAutoCompute, getCollidable, getLocale, getLocalToVworld, getLocalToVworld, getParent, getPickable, setBounds, setBoundsAutoCompute, setCollidable, setPickable

Methods inherited from class org.scijava.java3d.SceneGraphObject
clearCapability, clearCapabilityIsFrequent, duplicateSceneGraphObject, getCapability, getCapabilityIsFrequent, getName, getUserData, isCompiled, isLive, setCapability, setCapabilityIsFrequent, setName, setUserData, toString, updateNodeReferences

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - ALLOW_DETACH
```
public static final int ALLOW_DETACH
```
    For BranchGroup nodes, specifies that this BranchGroup allows detaching from its parent.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - BranchGroup
```
public BranchGroup()
```
    Constructs and initializes a new BranchGroup node object.
- Method Detail
  - compile
```
public void compile()
```
    Compiles the source BranchGroup associated with this object and creates and caches a compiled scene graph.
    
    Throws:
    
    SceneGraphCycleException - if there is a cycle in the scene graph
    
    RestrictedAccessException - if the method is called when this object is part of a live scene graph.
  - detach
```
public void detach()
```
    Detaches this BranchGroup from its parent.
  - pickAll
```
public SceneGraphPath[] pickAll(PickShape pickShape)
```
    Returns an array referencing all the items that are pickable below this BranchGroup that intersect with PickShape. The resultant array is unordered.
    
    Parameters:
    
    pickShape - the PickShape object
    
    Throws:
    
    IllegalStateException - if BranchGroup is not live.
    
    See Also:
    
    SceneGraphPath, Locale.pickAll(org.scijava.java3d.PickShape), PickShape
  - pickAll
```
public PickInfo[] pickAll(int mode,
                          int flags,
                          PickShape pickShape)
```
    Returns an array unsorted references to all the PickInfo objects that are pickable below this BranchGroup that intersect with PickShape. The accuracy of the pick is set by the pick mode. The mode include : PickInfo.PICK_BOUNDS and PickInfo.PICK_GEOMETRY. The amount of information returned is specified via a masked variable, flags, indicating which components are present in each returned PickInfo object.
    Parameters:
    
    mode - picking mode, one of PickInfo.PICK_BOUNDS or PickInfo.PICK_GEOMETRY.
    flags - a mask indicating which components are present in each PickInfo object. This is specified as one or more individual bits that are bitwise "OR"ed together to describe the PickInfo data. The flags include :
    PickInfo.SCENEGRAPHPATH - request for computed SceneGraphPath.
    PickInfo.NODE - request for computed intersected Node.
    PickInfo.LOCAL_TO_VWORLD - request for computed local to virtual world transform.
    PickInfo.CLOSEST_INTERSECTION_POINT - request for closest intersection point.
    PickInfo.CLOSEST_DISTANCE - request for the distance of closest intersection.
    PickInfo.CLOSEST_GEOM_INFO - request for only the closest intersection geometry information.
    PickInfo.ALL_GEOM_INFO - request for all intersection geometry information.
    pickShape - the description of this picking volume or area.
    
    Throws:
    
    IllegalArgumentException - if flags contains both CLOSEST_GEOM_INFO and ALL_GEOM_INFO.
    
    IllegalArgumentException - if pickShape is a PickPoint and pick mode is set to PICK_GEOMETRY.
    
    IllegalArgumentException - if pick mode is neither PICK_BOUNDS nor PICK_GEOMETRY.
    
    IllegalArgumentException - if pick mode is PICK_BOUNDS and flags includes any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO.
    
    IllegalArgumentException - if pickShape is PickBounds and flags includes any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO.
    
    IllegalStateException - if BranchGroup is not live.
    
    CapabilityNotSetException - if the mode is PICK_GEOMETRY and the Geometry.ALLOW_INTERSECT capability bit is not set in any Geometry objects referred to by any shape node whose bounds intersects the PickShape.
    CapabilityNotSetException - if flags contains any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO, and the capability bits that control reading of coordinate data are not set in any GeometryArray object referred to by any shape node that intersects the PickShape. The capability bits that must be set to avoid this exception are as follows :
    
    By-copy geometry : GeometryArray.ALLOW_COORDINATE_READ
    
    By-reference geometry : GeometryArray.ALLOW_REF_DATA_READ
    
    Indexed geometry : IndexedGeometryArray.ALLOW_COORDINATE_INDEX_READ (in addition to one of the above)
    Since:
    
    Java 3D 1.4
    
    See Also:
    
    Locale.pickAll(int,int,org.scijava.java3d.PickShape), PickInfo
  - pickAllSorted
```
public SceneGraphPath[] pickAllSorted(PickShape pickShape)
```
    Returns a sorted array of references to all the Pickable items that intersect with the pickShape. Element [0] references the item closest to origin of PickShape successive array elements are further from the origin Note: If pickShape is of type PickBounds, the resulting array is unordered.
    
    Parameters:
    
    pickShape - the PickShape object
    
    Throws:
    
    IllegalStateException - if BranchGroup is not live.
    
    See Also:
    
    SceneGraphPath, Locale.pickAllSorted(org.scijava.java3d.PickShape), PickShape
  - pickAllSorted
```
public PickInfo[] pickAllSorted(int mode,
                                int flags,
                                PickShape pickShape)
```
    Returns a sorted array of PickInfo references to all the pickable items that intersect with the pickShape. Element [0] references the item closest to origin of PickShape successive array elements are further from the origin The accuracy of the pick is set by the pick mode. The mode include : PickInfo.PICK_BOUNDS and PickInfo.PICK_GEOMETRY. The amount of information returned is specified via a masked variable, flags, indicating which components are present in each returned PickInfo object.
    Parameters:
    
    mode - picking mode, one of PickInfo.PICK_BOUNDS or PickInfo.PICK_GEOMETRY.
    flags - a mask indicating which components are present in each PickInfo object. This is specified as one or more individual bits that are bitwise "OR"ed together to describe the PickInfo data. The flags include :
    PickInfo.SCENEGRAPHPATH - request for computed SceneGraphPath.
    PickInfo.NODE - request for computed intersected Node.
    PickInfo.LOCAL_TO_VWORLD - request for computed local to virtual world transform.
    PickInfo.CLOSEST_INTERSECTION_POINT - request for closest intersection point.
    PickInfo.CLOSEST_DISTANCE - request for the distance of closest intersection.
    PickInfo.CLOSEST_GEOM_INFO - request for only the closest intersection geometry information.
    PickInfo.ALL_GEOM_INFO - request for all intersection geometry information.
    pickShape - the description of this picking volume or area.
    
    Throws:
    
    IllegalArgumentException - if flags contains both CLOSEST_GEOM_INFO and ALL_GEOM_INFO.
    
    IllegalArgumentException - if pickShape is a PickPoint and pick mode is set to PICK_GEOMETRY.
    
    IllegalArgumentException - if pick mode is neither PICK_BOUNDS nor PICK_GEOMETRY.
    
    IllegalArgumentException - if pick mode is PICK_BOUNDS and flags includes any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO.
    
    IllegalArgumentException - if pickShape is PickBounds and flags includes any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO.
    
    IllegalStateException - if BranchGroup is not live.
    
    CapabilityNotSetException - if the mode is PICK_GEOMETRY and the Geometry.ALLOW_INTERSECT capability bit is not set in any Geometry objects referred to by any shape node whose bounds intersects the PickShape.
    CapabilityNotSetException - if flags contains any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO, and the capability bits that control reading of coordinate data are not set in any GeometryArray object referred to by any shape node that intersects the PickShape. The capability bits that must be set to avoid this exception are as follows :
    
    By-copy geometry : GeometryArray.ALLOW_COORDINATE_READ
    
    By-reference geometry : GeometryArray.ALLOW_REF_DATA_READ
    
    Indexed geometry : IndexedGeometryArray.ALLOW_COORDINATE_INDEX_READ (in addition to one of the above)
    Since:
    
    Java 3D 1.4
    
    See Also:
    
    Locale.pickAllSorted(int,int,org.scijava.java3d.PickShape), PickInfo
  - pickClosest
```
public SceneGraphPath pickClosest(PickShape pickShape)
```
    Returns a SceneGraphPath that references the pickable item closest to the origin of pickShape. Note: If pickShape is of type PickBounds, the return is any pickable node below this BranchGroup.
    
    Parameters:
    
    pickShape - the PickShape object
    
    Throws:
    
    IllegalStateException - if BranchGroup is not live.
    
    See Also:
    
    SceneGraphPath, Locale.pickClosest(org.scijava.java3d.PickShape), PickShape
  - pickClosest
```
public PickInfo pickClosest(int mode,
                            int flags,
                            PickShape pickShape)
```
    Returns a PickInfo which references the pickable item which is closest to the origin of pickShape. The accuracy of the pick is set by the pick mode. The mode include : PickInfo.PICK_BOUNDS and PickInfo.PICK_GEOMETRY. The amount of information returned is specified via a masked variable, flags, indicating which components are present in each returned PickInfo object.
    Parameters:
    
    mode - picking mode, one of PickInfo.PICK_BOUNDS or PickInfo.PICK_GEOMETRY.
    flags - a mask indicating which components are present in each PickInfo object. This is specified as one or more individual bits that are bitwise "OR"ed together to describe the PickInfo data. The flags include :
    PickInfo.SCENEGRAPHPATH - request for computed SceneGraphPath.
    PickInfo.NODE - request for computed intersected Node.
    PickInfo.LOCAL_TO_VWORLD - request for computed local to virtual world transform.
    PickInfo.CLOSEST_INTERSECTION_POINT - request for closest intersection point.
    PickInfo.CLOSEST_DISTANCE - request for the distance of closest intersection.
    PickInfo.CLOSEST_GEOM_INFO - request for only the closest intersection geometry information.
    PickInfo.ALL_GEOM_INFO - request for all intersection geometry information.
    pickShape - the description of this picking volume or area.
    
    Throws:
    
    IllegalArgumentException - if flags contains both CLOSEST_GEOM_INFO and ALL_GEOM_INFO.
    
    IllegalArgumentException - if pickShape is a PickPoint and pick mode is set to PICK_GEOMETRY.
    
    IllegalArgumentException - if pick mode is neither PICK_BOUNDS nor PICK_GEOMETRY.
    
    IllegalArgumentException - if pick mode is PICK_BOUNDS and flags includes any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO.
    
    IllegalArgumentException - if pickShape is PickBounds and flags includes any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO.
    
    IllegalStateException - if BranchGroup is not live.
    
    CapabilityNotSetException - if the mode is PICK_GEOMETRY and the Geometry.ALLOW_INTERSECT capability bit is not set in any Geometry objects referred to by any shape node whose bounds intersects the PickShape.
    CapabilityNotSetException - if flags contains any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO, and the capability bits that control reading of coordinate data are not set in any GeometryArray object referred to by any shape node that intersects the PickShape. The capability bits that must be set to avoid this exception are as follows :
    
    By-copy geometry : GeometryArray.ALLOW_COORDINATE_READ
    
    By-reference geometry : GeometryArray.ALLOW_REF_DATA_READ
    
    Indexed geometry : IndexedGeometryArray.ALLOW_COORDINATE_INDEX_READ (in addition to one of the above)
    Since:
    
    Java 3D 1.4
    
    See Also:
    
    Locale.pickClosest(int,int,org.scijava.java3d.PickShape), PickInfo
  - pickAny
```
public SceneGraphPath pickAny(PickShape pickShape)
```
    Returns a reference to any item that is Pickable below this BranchGroup that intersects with pickShape.
    
    Parameters:
    
    pickShape - the PickShape object
    
    Throws:
    
    IllegalStateException - if BranchGroup is not live.
    
    See Also:
    
    SceneGraphPath, Locale.pickAny(org.scijava.java3d.PickShape), PickShape
  - pickAny
```
public PickInfo pickAny(int mode,
                        int flags,
                        PickShape pickShape)
```
    Returns a PickInfo which references the pickable item below this BranchGroup that intersects with pickShape. The accuracy of the pick is set by the pick mode. The mode include : PickInfo.PICK_BOUNDS and PickInfo.PICK_GEOMETRY. The amount of information returned is specified via a masked variable, flags, indicating which components are present in each returned PickInfo object.
    Parameters:
    
    mode - picking mode, one of PickInfo.PICK_BOUNDS or PickInfo.PICK_GEOMETRY.
    flags - a mask indicating which components are present in each PickInfo object. This is specified as one or more individual bits that are bitwise "OR"ed together to describe the PickInfo data. The flags include :
    PickInfo.SCENEGRAPHPATH - request for computed SceneGraphPath.
    PickInfo.NODE - request for computed intersected Node.
    PickInfo.LOCAL_TO_VWORLD - request for computed local to virtual world transform.
    PickInfo.CLOSEST_INTERSECTION_POINT - request for closest intersection point.
    PickInfo.CLOSEST_DISTANCE - request for the distance of closest intersection.
    PickInfo.CLOSEST_GEOM_INFO - request for only the closest intersection geometry information.
    PickInfo.ALL_GEOM_INFO - request for all intersection geometry information.
    pickShape - the description of this picking volume or area.
    
    Throws:
    
    IllegalArgumentException - if flags contains both CLOSEST_GEOM_INFO and ALL_GEOM_INFO.
    
    IllegalArgumentException - if pickShape is a PickPoint and pick mode is set to PICK_GEOMETRY.
    
    IllegalArgumentException - if pick mode is neither PICK_BOUNDS nor PICK_GEOMETRY.
    
    IllegalArgumentException - if pick mode is PICK_BOUNDS and flags includes any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO.
    
    IllegalArgumentException - if pickShape is PickBounds and flags includes any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO.
    
    IllegalStateException - if BranchGroup is not live.
    
    CapabilityNotSetException - if the mode is PICK_GEOMETRY and the Geometry.ALLOW_INTERSECT capability bit is not set in any Geometry objects referred to by any shape node whose bounds intersects the PickShape.
    CapabilityNotSetException - if flags contains any of CLOSEST_INTERSECTION_POINT, CLOSEST_DISTANCE, CLOSEST_GEOM_INFO or ALL_GEOM_INFO, and the capability bits that control reading of coordinate data are not set in any GeometryArray object referred to by any shape node that intersects the PickShape. The capability bits that must be set to avoid this exception are as follows :
    
    By-copy geometry : GeometryArray.ALLOW_COORDINATE_READ
    
    By-reference geometry : GeometryArray.ALLOW_REF_DATA_READ
    
    Indexed geometry : IndexedGeometryArray.ALLOW_COORDINATE_INDEX_READ (in addition to one of the above)
    Since:
    
    Java 3D 1.4
    
    See Also:
    
    Locale.pickAny(int,int,org.scijava.java3d.PickShape), PickInfo
  - cloneNode
```
public Node cloneNode(boolean forceDuplicate)
```
    Creates a new instance of the node. This routine is called by cloneTree to duplicate the current node.
    
    Overrides:
    
    cloneNode in class Group
    
    Parameters:
    
    forceDuplicate - when set to true, causes the duplicateOnCloneTree flag to be ignored. When false, the value of each node's duplicateOnCloneTree variable determines whether NodeComponent data is duplicated or copied.
    
    See Also:
    
    Node.cloneTree(), Node.cloneNode(boolean), Node.duplicateNode(org.scijava.java3d.Node, boolean), NodeComponent.setDuplicateOnCloneTree(boolean)

Class BranchGroup

Field Summary

Fields inherited from class org.scijava.java3d.Group

Fields inherited from class org.scijava.java3d.Node

Constructor Summary

Method Summary

Methods inherited from class org.scijava.java3d.Group

Methods inherited from class org.scijava.java3d.Node

Methods inherited from class org.scijava.java3d.SceneGraphObject

Methods inherited from class java.lang.Object

Field Detail

ALLOW_DETACH

Constructor Detail

BranchGroup

Method Detail

compile

detach

pickAll

pickAll

pickAllSorted

pickAllSorted

pickClosest

pickClosest

pickAny

pickAny

cloneNode