or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

configuration.md file-loading.md index.md materials.md mesh-operations.md visualization.md

tile.json

tessl/pypi-pywavefront

Python library for importing Wavefront .obj files and generating interleaved vertex data ready for rendering.

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:pypi/pywavefront@1.3.x

To install, run

npx @tessl/cli install tessl/pypi-pywavefront@1.3.0

PyWavefront

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.

Package Information

Package Name: PyWavefront
Language: Python
Installation: pip install pywavefront
Requirements: Python 3.4+
Optional Dependencies: pyglet for visualization module

Core Imports

import pywavefront

# Most common import pattern
scene = pywavefront.Wavefront('model.obj')

Access to specific classes:

from pywavefront import Wavefront, PywavefrontException, configure_logging, __version__
from pywavefront.material import Material, MaterialParser
from pywavefront.mesh import Mesh
from pywavefront.obj import ObjParser
from pywavefront.texture import Texture, TextureOptions
from pywavefront import visualization  # Optional - requires pyglet

Basic Usage

import pywavefront

# Load a basic .obj file
scene = pywavefront.Wavefront('model.obj')

# Access materials and their vertex data
for name, material in scene.materials.items():
    print(f"Material: {name}")
    print(f"Vertex format: {material.vertex_format}")
    print(f"Vertex count: {len(material.vertices)}")
    
    # Access material properties
    print(f"Diffuse color: {material.diffuse}")
    print(f"Texture: {material.texture}")

# Access meshes
for name, mesh in scene.meshes.items():
    print(f"Mesh: {name}")
    print(f"Materials: {[m.name for m in mesh.materials]}")

# Advanced loading with options
scene = pywavefront.Wavefront(
    'complex_model.obj',
    strict=True,              # Enable strict parsing
    encoding='utf-8',         # File encoding
    create_materials=True,    # Create missing materials
    collect_faces=True,       # Collect face data for analysis
    cache=True               # Enable binary caching for faster loading
)

Architecture

PyWavefront follows a hierarchical structure designed for efficient 3D data processing:

Wavefront: Top-level container managing the entire scene with materials, meshes, and vertices
Material: Contains interleaved vertex data, material properties, and textures for rendering
Mesh: Groups materials and optionally stores face topology data
ObjParser: Handles .obj file parsing with support for caching and various encoding options
Visualization: Optional OpenGL rendering using pyglet for display and debugging

The library generates interleaved vertex data optimized for modern rendering pipelines (VBOs/VAOs) while maintaining compatibility with legacy OpenGL immediate mode rendering.

Capabilities

File Loading and Parsing

Core functionality for loading Wavefront .obj files with comprehensive parsing options, encoding support, error handling, and optional binary caching for improved performance.

class Wavefront:
    def __init__(
        self,
        file_name: str,
        strict: bool = False,
        encoding: str = "utf-8",
        create_materials: bool = False,
        collect_faces: bool = False,
        parse: bool = True,
        cache: bool = False
    ): ...
    
    def parse(self) -> None: ...

File Loading

Material System

Material properties, texture management, and vertex data organization. Materials contain interleaved vertex arrays formatted for direct use with OpenGL rendering pipelines.

class Material:
    def __init__(
        self,
        name: str,
        is_default: bool = False,
        has_faces: bool = False
    ): ...
    
    @property
    def has_normals(self) -> bool: ...
    @property
    def has_uvs(self) -> bool: ...
    @property
    def has_colors(self) -> bool: ...

Materials and Textures

Mesh Management

Mesh organization and face data collection for 3D geometry analysis and processing. Meshes group materials and optionally collect triangulated face topology.

class Mesh:
    def __init__(
        self,
        name: str = None,
        has_faces: bool = False
    ): ...
    
    def add_material(self, material: Material) -> None: ...
    def has_material(self, material: Material) -> bool: ...

Mesh Operations

Visualization and Rendering

Optional OpenGL-based visualization using pyglet for displaying loaded 3D models. Supports lighting, textures, and various rendering modes.

def draw(
    instance,
    lighting_enabled: bool = True,
    textures_enabled: bool = True
) -> None: ...

def draw_material(
    material: Material,
    face = GL_FRONT_AND_BACK,
    lighting_enabled: bool = True,
    textures_enabled: bool = True
) -> None: ...

Visualization

Configuration and Utilities

Logging configuration, exception handling, and utility functions for customizing PyWavefront behavior and debugging.

def configure_logging(level, formatter=None) -> None: ...

class PywavefrontException(Exception): ...

Configuration

Types

# Core vertex data types
VertexData = List[float]  # Interleaved vertex array
ColorRGBA = List[float]   # [r, g, b, a] values 0.0-1.0
Position3D = Tuple[float, float, float]
TextureCoord = Tuple[float, float]
Normal3D = Tuple[float, float, float]
FaceIndices = List[List[int]]   # List of triangle faces, each with 3 vertex indices

# Vertex format strings
VertexFormat = str  # Examples: "V3F", "T2F_V3F", "T2F_N3F_V3F", "T2F_C3F_V3F"

# Material illumination models (0-10)
IlluminationModel = int

# Texture option types
TextureBlendMode = str  # "on" or "off"
TextureOffset = Tuple[float, float, float]  # (u, v, w)
TextureScale = Tuple[float, float, float]   # (u, v, w)
TextureRange = Tuple[float, float]          # (base, gain)

# File paths and names
FilePath = str
SearchPath = str
MaterialName = str
MeshName = str
TextureName = str

# Parser configuration types
Encoding = str      # Text encoding (e.g., "utf-8", "latin1")
LogLevel = int      # logging.DEBUG, logging.INFO, etc.