0
# PyWavefront
1
2
PyWavefront is a Python library for importing Wavefront 3D object files (.obj, .obj.gz, and .mtl files) and generating interleaved vertex data ready for rendering. The library supports the most commonly used features from the Wavefront specification including positions, texture coordinates, normals, vertex colors, material parsing, and texture parameters.
3
4
## Package Information
5
6
- **Package Name**: PyWavefront
7
- **Language**: Python
8
- **Installation**: `pip install pywavefront`
9
- **Requirements**: Python 3.4+
10
- **Optional Dependencies**: `pyglet` for visualization module
11
12
## Core Imports
13
14
```python
15
import pywavefront
16
17
# Most common import pattern
18
scene = pywavefront.Wavefront('model.obj')
19
```
20
21
Access to specific classes:
22
23
```python
24
from pywavefront import Wavefront, PywavefrontException, configure_logging, __version__
25
from pywavefront.material import Material, MaterialParser
26
from pywavefront.mesh import Mesh
27
from pywavefront.obj import ObjParser
28
from pywavefront.texture import Texture, TextureOptions
29
from pywavefront import visualization # Optional - requires pyglet
30
```
31
32
## Basic Usage
33
34
```python
35
import pywavefront
36
37
# Load a basic .obj file
38
scene = pywavefront.Wavefront('model.obj')
39
40
# Access materials and their vertex data
41
for name, material in scene.materials.items():
42
print(f"Material: {name}")
43
print(f"Vertex format: {material.vertex_format}")
44
print(f"Vertex count: {len(material.vertices)}")
45
46
# Access material properties
47
print(f"Diffuse color: {material.diffuse}")
48
print(f"Texture: {material.texture}")
49
50
# Access meshes
51
for name, mesh in scene.meshes.items():
52
print(f"Mesh: {name}")
53
print(f"Materials: {[m.name for m in mesh.materials]}")
54
55
# Advanced loading with options
56
scene = pywavefront.Wavefront(
57
'complex_model.obj',
58
strict=True, # Enable strict parsing
59
encoding='utf-8', # File encoding
60
create_materials=True, # Create missing materials
61
collect_faces=True, # Collect face data for analysis
62
cache=True # Enable binary caching for faster loading
63
)
64
```
65
66
## Architecture
67
68
PyWavefront follows a hierarchical structure designed for efficient 3D data processing:
69
70
- **Wavefront**: Top-level container managing the entire scene with materials, meshes, and vertices
71
- **Material**: Contains interleaved vertex data, material properties, and textures for rendering
72
- **Mesh**: Groups materials and optionally stores face topology data
73
- **ObjParser**: Handles .obj file parsing with support for caching and various encoding options
74
- **Visualization**: Optional OpenGL rendering using pyglet for display and debugging
75
76
The library generates interleaved vertex data optimized for modern rendering pipelines (VBOs/VAOs) while maintaining compatibility with legacy OpenGL immediate mode rendering.
77
78
## Capabilities
79
80
### File Loading and Parsing
81
82
Core functionality for loading Wavefront .obj files with comprehensive parsing options, encoding support, error handling, and optional binary caching for improved performance.
83
84
```python { .api }
85
class Wavefront:
86
def __init__(
87
self,
88
file_name: str,
89
strict: bool = False,
90
encoding: str = "utf-8",
91
create_materials: bool = False,
92
collect_faces: bool = False,
93
parse: bool = True,
94
cache: bool = False
95
): ...
96
97
def parse(self) -> None: ...
98
```
99
100
[File Loading](./file-loading.md)
101
102
### Material System
103
104
Material properties, texture management, and vertex data organization. Materials contain interleaved vertex arrays formatted for direct use with OpenGL rendering pipelines.
105
106
```python { .api }
107
class Material:
108
def __init__(
109
self,
110
name: str,
111
is_default: bool = False,
112
has_faces: bool = False
113
): ...
114
115
@property
116
def has_normals(self) -> bool: ...
117
@property
118
def has_uvs(self) -> bool: ...
119
@property
120
def has_colors(self) -> bool: ...
121
```
122
123
[Materials and Textures](./materials.md)
124
125
### Mesh Management
126
127
Mesh organization and face data collection for 3D geometry analysis and processing. Meshes group materials and optionally collect triangulated face topology.
128
129
```python { .api }
130
class Mesh:
131
def __init__(
132
self,
133
name: str = None,
134
has_faces: bool = False
135
): ...
136
137
def add_material(self, material: Material) -> None: ...
138
def has_material(self, material: Material) -> bool: ...
139
```
140
141
[Mesh Operations](./mesh-operations.md)
142
143
### Visualization and Rendering
144
145
Optional OpenGL-based visualization using pyglet for displaying loaded 3D models. Supports lighting, textures, and various rendering modes.
146
147
```python { .api }
148
def draw(
149
instance,
150
lighting_enabled: bool = True,
151
textures_enabled: bool = True
152
) -> None: ...
153
154
def draw_material(
155
material: Material,
156
face = GL_FRONT_AND_BACK,
157
lighting_enabled: bool = True,
158
textures_enabled: bool = True
159
) -> None: ...
160
```
161
162
[Visualization](./visualization.md)
163
164
### Configuration and Utilities
165
166
Logging configuration, exception handling, and utility functions for customizing PyWavefront behavior and debugging.
167
168
```python { .api }
169
def configure_logging(level, formatter=None) -> None: ...
170
171
class PywavefrontException(Exception): ...
172
```
173
174
[Configuration](./configuration.md)
175
176
## Types
177
178
```python { .api }
179
# Core vertex data types
180
VertexData = List[float] # Interleaved vertex array
181
ColorRGBA = List[float] # [r, g, b, a] values 0.0-1.0
182
Position3D = Tuple[float, float, float]
183
TextureCoord = Tuple[float, float]
184
Normal3D = Tuple[float, float, float]
185
FaceIndices = List[List[int]] # List of triangle faces, each with 3 vertex indices
186
187
# Vertex format strings
188
VertexFormat = str # Examples: "V3F", "T2F_V3F", "T2F_N3F_V3F", "T2F_C3F_V3F"
189
190
# Material illumination models (0-10)
191
IlluminationModel = int
192
193
# Texture option types
194
TextureBlendMode = str # "on" or "off"
195
TextureOffset = Tuple[float, float, float] # (u, v, w)
196
TextureScale = Tuple[float, float, float] # (u, v, w)
197
TextureRange = Tuple[float, float] # (base, gain)
198
199
# File paths and names
200
FilePath = str
201
SearchPath = str
202
MaterialName = str
203
MeshName = str
204
TextureName = str
205
206
# Parser configuration types
207
Encoding = str # Text encoding (e.g., "utf-8", "latin1")
208
LogLevel = int # logging.DEBUG, logging.INFO, etc.
209
```