0
# Scene Graph and 3D Objects
1

2
The scene graph is Panda3D's hierarchical organization system for 3D content. All objects in the 3D world are represented as nodes in a tree structure, with the NodePath class providing the primary interface for manipulation.
3

4
## Capabilities
5

6
### NodePath - Core 3D Object Interface
7

8
The NodePath class is the fundamental interface for all 3D objects in Panda3D. It provides methods for positioning, orienting, scaling, and managing hierarchical relationships between objects.
9

10
```python { .api }
11
class NodePath:
12
    def set_pos(self, x: float, y: float, z: float) -> None:
13
        """Set absolute position in 3D space."""
14
    
15
    def set_pos(self, pos: Vec3) -> None:
16
        """Set absolute position using Vec3."""
17
    
18
    def set_x(self, x: float) -> None:
19
        """Set X coordinate only."""
20
    
21
    def set_y(self, y: float) -> None:
22
        """Set Y coordinate only."""
23
    
24
    def set_z(self, z: float) -> None:
25
        """Set Z coordinate only."""
26
    
27
    def get_pos(self) -> Vec3:
28
        """Get current absolute position."""
29
    
30
    def get_x(self) -> float:
31
        """Get X coordinate."""
32
    
33
    def get_y(self) -> float:
34
        """Get Y coordinate."""
35
    
36
    def get_z(self) -> float:
37
        """Get Z coordinate."""
38
```
39

40
### Rotation and Orientation
41

42
Panda3D supports multiple rotation representations including Euler angles (Heading-Pitch-Roll) and quaternions for smooth rotations.
43

44
```python { .api }
45
class NodePath:
46
    def setHpr(self, h: float, p: float, r: float) -> None:
47
        """Set heading, pitch, roll rotation in degrees."""
48
    
49
    def setHpr(self, hpr: Vec3) -> None:
50
        """Set HPR rotation using Vec3."""
51
    
52
    def setH(self, h: float) -> None:
53
        """Set heading (Y-axis rotation) only."""
54
    
55
    def setP(self, p: float) -> None:
56
        """Set pitch (X-axis rotation) only."""
57
    
58
    def setR(self, r: float) -> None:
59
        """Set roll (Z-axis rotation) only."""
60
    
61
    def getHpr(self) -> Vec3:
62
        """Get current HPR rotation."""
63
    
64
    def setQuat(self, quat: Quat) -> None:
65
        """Set rotation using quaternion."""
66
    
67
    def getQuat(self) -> Quat:
68
        """Get current rotation as quaternion."""
69
    
70
    def lookAt(self, target: Vec3) -> None:
71
        """Orient to look at target position."""
72
    
73
    def lookAt(self, target: NodePath) -> None:
74
        """Orient to look at target object."""
75
```
76

77
### Scale and Size
78

79
Control object scaling along individual axes or uniformly.
80

81
```python { .api }
82
class NodePath:
83
    def setScale(self, scale: float) -> None:
84
        """Set uniform scale factor."""
85
    
86
    def setScale(self, sx: float, sy: float, sz: float) -> None:
87
        """Set scale along each axis."""
88
    
89
    def setScale(self, scale: Vec3) -> None:
90
        """Set scale using Vec3."""
91
    
92
    def setSx(self, sx: float) -> None:
93
        """Set X-axis scale only."""
94
    
95
    def setSy(self, sy: float) -> None:
96
        """Set Y-axis scale only."""
97
    
98
    def setSz(self, sz: float) -> None:
99
        """Set Z-axis scale only."""
100
    
101
    def getScale(self) -> Vec3:
102
        """Get current scale factors."""
103
```
104

105
### Hierarchy Management
106

107
Manage parent-child relationships between objects in the scene graph.
108

109
```python { .api }
110
class NodePath:
111
    def reparentTo(self, newParent: NodePath) -> None:
112
        """Move this object to be child of newParent."""
113
    
114
    def wrtReparentTo(self, newParent: NodePath) -> None:
115
        """Reparent while maintaining world coordinates."""
116
    
117
    def detachNode(self) -> None:
118
        """Remove from scene graph but keep object."""
119
    
120
    def removeNode(self) -> None:
121
        """Remove and destroy this object."""
122
    
123
    def getParent(self) -> NodePath:
124
        """Get parent node."""
125
    
126
    def getChildren(self) -> List[NodePath]:
127
        """Get all child nodes."""
128
    
129
    def getNumChildren(self) -> int:
130
        """Get number of child nodes."""
131
    
132
    def getChild(self, index: int) -> NodePath:
133
        """Get child node by index."""
134
    
135
    def find(self, path: str) -> NodePath:
136
        """Find descendant node by name or path."""
137
    
138
    def findAllMatches(self, path: str) -> List[NodePath]:
139
        """Find all descendant nodes matching path."""
140
```
141

142
### Visibility and Rendering Control
143

144
Control object visibility and rendering properties.
145

146
```python { .api }
147
class NodePath:
148
    def show(self) -> None:
149
        """Make object visible."""
150
    
151
    def hide(self) -> None:
152
        """Make object invisible."""
153
    
154
    def isHidden(self) -> bool:
155
        """Check if object is hidden."""
156
    
157
    def setTransparency(self, mode: int) -> None:
158
        """Enable transparency rendering."""
159
    
160
    def setAlphaScale(self, alpha: float) -> None:
161
        """Set overall transparency (0.0-1.0)."""
162
    
163
    def setColorScale(self, r: float, g: float, b: float, a: float = 1.0) -> None:
164
        """Multiply object colors by scale factors."""
165
    
166
    def setColor(self, r: float, g: float, b: float, a: float = 1.0) -> None:
167
        """Set object color."""
168
    
169
    def clearColor(self) -> None:
170
        """Remove color override."""
171
```
172

173
### Coordinate System Utilities
174

175
Transform coordinates between different reference frames.
176

177
```python { .api }
178
class NodePath:
179
    def getRelativePoint(self, other: NodePath, point: Vec3) -> Vec3:
180
        """Convert point from other's coordinate system to this one."""
181
    
182
    def getRelativeVector(self, other: NodePath, vector: Vec3) -> Vec3:
183
        """Convert vector from other's coordinate system to this one."""
184
    
185
    def getDistance(self, other: NodePath) -> float:
186
        """Get distance to another object."""
187
    
188
    def getTransform(self) -> TransformState:
189
        """Get complete transformation state."""
190
    
191
    def setTransform(self, transform: TransformState) -> None:
192
        """Set complete transformation state."""
193
```
194

195
### Collision and Physics Integration
196

197
Enable collision detection and physics simulation for objects.
198

199
```python { .api }
200
class NodePath:
201
    def setCollideMask(self, mask: BitMask32) -> None:
202
        """Set collision bitmask for this object."""
203
    
204
    def getCollideMask(self) -> BitMask32:
205
        """Get collision bitmask."""
206
    
207
    def node(self) -> PandaNode:
208
        """Get underlying PandaNode for advanced operations."""
209
    
210
    def isEmpty(self) -> bool:
211
        """Check if NodePath references a valid node."""
212
    
213
    def hasParent(self) -> bool:
214
        """Check if object has a parent."""
215
```
216

217
## Usage Examples
218

219
### Basic Object Manipulation
220

221
```python
222
from direct.showbase.ShowBase import ShowBase
223
from panda3d.core import Vec3
224

225
class MyGame(ShowBase):
226
    def __init__(self):
227
        ShowBase.__init__(self)
228
        
229
        # Load and position a model
230
        self.model = self.loader.loadModel("models/teapot")
231
        self.model.reparentTo(self.render)
232
        self.model.setScale(2.0)
233
        self.model.setPos(0, 10, 0)
234
        self.model.setHpr(45, 0, 0)
235
        
236
        # Create hierarchy
237
        self.parent_obj = self.render.attachNewNode("parent")
238
        self.child_obj = self.loader.loadModel("models/box")
239
        self.child_obj.reparentTo(self.parent_obj)
240
        self.child_obj.setPos(5, 0, 0)  # Relative to parent
241
        
242
        # Rotating parent affects child
243
        self.parent_obj.setH(90)  # Child rotates with parent
244

245
app = MyGame()
246
app.run()
247
```
248

249
### Dynamic Object Management
250

251
```python
252
def create_objects(self):
253
    """Create multiple objects dynamically."""
254
    self.objects = []
255
    
256
    for i in range(10):
257
        obj = self.loader.loadModel("models/cube")
258
        obj.reparentTo(self.render)
259
        obj.setPos(i * 2, 0, 0)
260
        obj.setScale(0.5)
261
        self.objects.append(obj)
262

263
def cleanup_objects(self):
264
    """Remove all created objects."""
265
    for obj in self.objects:
266
        obj.removeNode()
267
    self.objects.clear()
268
```
269

270
## Types
271

272
```python { .api }
273
class PandaNode:
274
    """Base class for all scene graph nodes."""
275
    def getName(self) -> str: ...
276
    def setName(self, name: str) -> None: ...
277

278
class TransformState:
279
    """Represents complete 3D transformation."""
280
    def getPos(self) -> Vec3: ...
281
    def getHpr(self) -> Vec3: ...
282
    def getScale(self) -> Vec3: ...
283

284
BitMask32: int  # 32-bit collision mask type
285
```