Skip to content

README.md

Latest commit

 

History

History
254 lines (181 loc) · 6.1 KB

README.md

File metadata and controls

254 lines (181 loc) · 6.1 KB

🎮 3D OBJ Viewer

Python Pygame NumPy OpenGL License

A powerful Python-based 3D model viewer with interactive controls, texture support, custom shaders, and multiple view modes for seamless 3D model visualization.

3D Viewer Screenshot

✨ Features

  • 🎯 OBJ File Support - Load and display standard .obj 3D models
  • 🎨 Texture Mapping - Full texture support with material files (.mtl)
  • 🖱️ Interactive Controls - Rotate, pan, and zoom with mouse
  • 🎭 Custom Shaders - Vertex and fragment shader support
  • 🌈 Multiple View Modes - Switch between different rendering modes
  • 📐 Vertex/Edge Display - Toggle vertex and edge visualization
  • 🎨 Material Support - Load and apply materials from .mtl files
  • ⚡ Real-time Rendering - Smooth, responsive 3D visualization
  • 🔄 Model Manipulation - Real-time rotation, scaling, and positioning

🚀 Quick Start

Prerequisites

  • Python 3.8 or higher
  • OpenGL-compatible graphics card

Installation

# Clone the repository
git clone https://github.com/widgetwalker/3d-viewer.git
cd 3d-viewer

# Install dependencies
pip install pygame numpy

Run the Viewer

python main.py

🎮 Controls

Control Action
Left Mouse Button Rotate model
Right Mouse Button Pan camera
Mouse Wheel Zoom in/out
Space Toggle view modes
C Change background color
V Toggle vertex display
E Toggle edge display
ESC Exit viewer

📂 Project Structure

3d-viewer/
├── main.py                      # Main application entry point
├── model_loader.py              # OBJ/MTL file parser
├── model_camera.py.py           # Camera and view controls
├── shader.py                    # Shader implementation
├── shadersvertex.glsl.txt       # Vertex shader code
├── shadersfragment.glsl.txt     # Fragment shader code
├── airplane.obj                 # Sample 3D model
├── lll.obj                      # Sample 3D model
├── models.obj.txt               # Model metadata
└── README.md                    # This file

📦 Supported File Formats

3D Models

  • .obj - Wavefront OBJ files (vertices, faces, normals, UVs)
  • .mtl - Material definition files

Textures

  • PNG, JPG, BMP, TGA (any format supported by Pygame)

🎨 Customization

Modify Shaders

Edit the shader files to customize rendering:

Vertex Shader (shadersvertex.glsl.txt):

// Customize vertex transformations

Fragment Shader (shadersfragment.glsl.txt):

// Customize pixel colors and lighting

Change Display Settings

Modify in main.py:

# Background colors
background_color = (0.1, 0.1, 0.1)

# Edge colors
edge_color = (1.0, 1.0, 1.0)

# Vertex colors
vertex_color = (1.0, 0.0, 0.0)

🔧 Loading Custom Models

  1. Place your .obj file in the project directory
  2. If you have textures, place the .mtl file alongside
  3. Ensure texture image files are in the correct path
  4. Run the viewer - it will auto-detect available models

Example OBJ File Structure

mymodel.obj          # 3D geometry
mymodel.mtl          # Materials
texture.png          # Texture image

🏗️ Architecture

Model Loading Pipeline

OBJ File → Parser → Vertex Data → GPU Buffer → Renderer
                ↓
            MTL File → Material Data → Texture Loader

Rendering Pipeline

Input Events → Camera Update → Shader Compilation → 
Vertex Processing → Fragment Processing → Display

🐛 Troubleshooting

Model Not Loading

# Check file format
# Ensure .obj file is valid
# Verify file path is correct

Textures Not Showing

  • Check .mtl file texture paths
  • Ensure texture files exist
  • Verify texture format is supported

Performance Issues

  • Reduce polygon count of model
  • Disable vertex/edge display
  • Lower screen resolution

Shader Errors

# Check shader syntax
# Verify GLSL version compatibility
# Review error messages in console

💡 Advanced Features

Camera System

  • Orbit Mode - Rotate around model center
  • Pan Mode - Move camera position
  • Zoom Mode - Adjust camera distance

Rendering Modes

  • Solid - Standard filled polygons
  • Wireframe - Edge-only display
  • Vertex - Point cloud visualization
  • Textured - Full material rendering

🤝 Contributing

Contributions are welcome! Here's how:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • Pygame Community - For the excellent game development framework
  • OpenGL Community - For graphics programming resources
  • Wavefront OBJ Format - For the standard 3D model format

🔗 Links

📧 Contact

Dheeraj Pilli

⭐ Star this repo if you find it helpful!

Built with ❤️ using Python, Pygame, and OpenGL