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
```