Data

Tools

Indexes

Applications

Experiments

Open Source Science

pywavefront

Python library for importing Wavefront .obj files

https://github.com/pywavefront/pywavefront

Science Score: 23.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ○
    CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ○
    .zenodo.json file
  • ○
    DOI references
  • ○
    Academic publication links
  • ✓
    Committers with academic emails
    1 of 21 committers (4.8%) from academic institutions
  • ○
    Institutional organization owner
  • ○
    JOSS paper metadata
  • ○
    Scientific vocabulary similarity
    Low similarity (14.1%) to scientific vocabulary

Keywords

3d loader opengl-library pyglet python python3 wavefront wavefront-obj

Keywords from Contributors

gamedev
Last synced: 5 months ago · JSON representation

Repository

Python library for importing Wavefront .obj files

Basic Info
  • Host: GitHub
  • Owner: pywavefront
  • License: bsd-3-clause
  • Language: Python
  • Default Branch: master
  • Size: 3.57 MB
Statistics
  • Stars: 320
  • Watchers: 13
  • Forks: 82
  • Open Issues: 34
  • Releases: 21
Topics
3d loader opengl-library pyglet python python3 wavefront wavefront-obj
Created over 12 years ago · Last pushed almost 2 years ago
Metadata Files
Readme Changelog License Roadmap

README.md

pypi CircleCI

[![preview](https://raw.githubusercontent.com/pywavefront/PyWavefront/master/extras/logo.png)](#readme)

PyWavefront

PyWavefront reads Wavefront 3D object files (something.obj, something.obj.gz and something.mtl) and generates interleaved vertex data for each material ready for rendering.

  • Python 3.4+ is supported in 1.x versions
  • Python 2.7 is supported in 0.x versions

A simple (optional) visualization module is also provided for rendering the object(s). The interleaved data can also be used by more modern renderers thought VBOs or VAOs.

Currently the most commonly used features in the specification has been implemented:

  • Positions
  • Texture Coordinates
  • Normals
  • Vertex Color
  • Material parsing
  • Texture and texture parameters

We currently don't support parameter space vertices, line elements or smoothing groups. Create an issue or pull request on github if needed features are missing.

The package is on pypi or can be cloned on github.

bash pip install pywavefront

Also check out the roadmap for future plans.

Usage

Basic example loading an obj file:

python import pywavefront scene = pywavefront.Wavefront('something.obj')

A more complex example

  • strict (Default: False) will raise an exception if unsupported features are found in the obj or mtl file
  • encoding (Default: utf-8) of the obj and mtl file(s)
  • create_materials (Default: False) will create materials if mtl file is missing or obj file references non-existing materials
  • collect_faces (Default: False) will collect triangle face data for every mesh. In case faces with more than three vertices are specified they will be triangulated. See the documentation of ObjParser#consume_faces() in obj.py.
  • parse (Default: True) decides if parsing should start immediately.
  • cache (Default: False) writes the parsed geometry to a binary file for faster loading in the future

```python import pywavefront scene = pywavefront.Wavefront( 'something.obj', strict=True, encoding="iso-8859-1", parse=False, ) scene.parse() # Explicit call to parse() needed when parse=False

Iterate vertex data collected in each material

for name, material in scene.materials.items(): # Contains the vertex format (string) such as "T2FN3FV3F" # T2F, C3F, N3F and V3F may appear in this string material.vertex_format # Contains the vertex list of floats in the format described above material.vertices # Material properties material.diffuse material.ambient material.texture # .. ```

Binary Cache

When cache=True the interleaved vertex data is written as floats to a .bin file after the file is loaded. A json file is also generated describing the contents of the binary file. The binary file will be loaded the next time we attempt to load the obj file reducing the loading time significantly.

Tests have shown loading time reduction by 10 to 100 times depending on the size and structure of the original obj file.

Loading myfile.obj will generate the following files in the same directory.

txt myfile.obj.bin myfile.obj.json

Json file example:

json { "created_at": "2018-07-16T14:28:43.451336", "version": "0.1", "materials": [ "lost_empire.mtl" ], "vertex_buffers": [ { "material": "Stone", "vertex_format": "T2F_N3F_V3F", "byte_offset": 0, "byte_length": 5637888 }, { "material": "Grass", "vertex_format": "T2F_N3F_V3F", "byte_offset": 5637888, "byte_length": 6494208 } ] }

These files will not be recreated until you delete them. The bin file is also compressed with gzip to greatly reduce size.

Visualization

Pyglet is required to use the visualization module.

bash pip install pyglet

Example:

```python import pywavefront from pywavefront import visualization

[create a window and set up your OpenGl context] obj = pywavefront.Wavefront('something.obj')

[inside your drawing loop] visualization.draw(obj) ```

Logging

The default log level is ERROR. This is configurable including overriding the formatter.

```python import logging import pywavefront

pywavefront.configure_logging( logging.DEBUG, formatter=logging.Formatter('%(name)s-%(levelname)s: %(message)s') ) ```

Examples

The examples directory contains some basic examples using the visualization module and further instructions on how to run them.

Generating a Wavefront file with Blender

The following presumes you are using Blender to generate your mesh:

  • Using Blender, create a mesh with a UV-mapped texture. The UV-mapping is important! If it is working properly, you will see the texture applied within Blender's 3d view.
  • Export the mesh from Blender using the Wavefront format, including normals.
  • Reference your *.obj file as in the pywavefront example above.

Tests

All tests can be found in the tests directory. To run the tests:

```bash

Install pywavefront in develop mode

python setup.py develop

Install required packages for running tests

pip install -r test-requirements.txt

Run all tests

pytest

Optionally specific tests modules can be runned separately

pytest tests/test_parser.py ```

Community

PyWavefront Discord server : https://discord.gg/h3Rh4QN

Owners & Maintainers

Contributors

In alphabetical order:

Project History

PyWavefront was originally started by @greenmoss (Kurt Yoder) in 2013. He was the sole maintainer of the project until February 2019 when the PyWavefront Maintainers organization was created adding @einarf (Einar Forselv) as an additional owner and maintainer of the project.

License

PyWavefront is BSD-licensed

Owner

  • Name: PyWavefront Maintainers
  • Login: pywavefront
  • Kind: organization

A Python library for handling wavefront obj files

GitHub Events

Total
  • Issues event: 1
  • Watch event: 10
  • Issue comment event: 4
  • Pull request event: 2
  • Fork event: 3
Last Year
  • Issues event: 1
  • Watch event: 10
  • Issue comment event: 4
  • Pull request event: 2
  • Fork event: 3

Committers

Last synced: over 2 years ago

All Time
  • Total Commits: 245
  • Total Committers: 21
  • Avg Commits per committer: 11.667
  • Development Distribution Score (DDS): 0.38
Past Year
  • Commits: 0
  • Committers: 0
  • Avg Commits per committer: 0.0
  • Development Distribution Score (DDS): 0.0
Top Committers
Name Email Commits
Einar Forselv e****v@g****m 152
Kurt Yoder k****b@y****m 47
Sergio Agostinho s****o@t****t 6
jerekshoe j****r@e****u 4
hkarrson h****n@g****m 4
Zohar Jackson z****n@m****m 4
Kurt Yoder k****r@g****m 4
Marxlp l****6@f****m 3
ComFreek c****k@o****m 3
Mathieu Lamarre m****e@e****m 3
jerekshoe j****8@g****m 3
Daniel Coelho d****o@n****m 2
Sérgio Agostinho s****o@g****m 2
Steven Potiris s****s@a****o 1
intrepid94 J****8@y****m 1
Olivier Gimenez o****z@s****m 1
Mikhail Mustakimov m****l@m****u 1
Liam Deacon l****n@g****m 1
dav92lee d****e@g****m 1
Patrik Huber p****r 1
Graham Knapp 3****m 1
Committer Domains (Top 20 + Academic)
mustakimov.ru: 1 semtech.com: 1 abysssolutions.co: 1 navegatium.com: 1 ea.com: 1 foxmail.com: 1 mobileye.com: 1 ennovar.wichita.edu: 1 tecnico.ulisboa.pt: 1 yoderhome.com: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time
  • Total issues: 78
  • Total pull requests: 33
  • Average time to close issues: 12 days
  • Average time to close pull requests: 10 days
  • Total issue authors: 52
  • Total pull request authors: 14
  • Average comments per issue: 3.32
  • Average comments per pull request: 2.45
  • Merged pull requests: 25
  • Bot issues: 0
  • Bot pull requests: 0
Past Year
  • Issues: 1
  • Pull requests: 3
  • Average time to close issues: N/A
  • Average time to close pull requests: N/A
  • Issue authors: 1
  • Pull request authors: 1
  • Average comments per issue: 1.0
  • Average comments per pull request: 0.0
  • Merged pull requests: 0
  • Bot issues: 0
  • Bot pull requests: 0
View more stats
Top Authors
Issue Authors
  • einarf (21)
  • Mikhail57 (2)
  • Cocco17 (2)
  • victoriapoghosyan (2)
  • chromafunk (2)
  • morawi (2)
  • ghost (2)
  • YingJie-Z (1)
  • CaffreyR (1)
  • nimzodisaster (1)
  • caniko (1)
  • riegaz (1)
  • luizavolpi (1)
  • monacv (1)
  • ComFreek (1)
Pull Request Authors
  • einarf (15)
  • LittleBread69 (3)
  • ComFreek (3)
  • ghost (2)
  • Mikhail57 (1)
  • dancergraham (1)
  • klattimer (1)
  • RoyJames (1)
  • spotiris (1)
  • Oliv4945 (1)
  • mlamarre (1)
  • frlnx (1)
  • Liam-Deacon (1)
  • a-detiste (1)
Top Labels
Issue Labels
Improvement (4) Information (2) bug (1) Needs Feedback (1) question (1) New Feature (1)
Pull Request Labels

Packages

  • Total packages: 1
  • Total downloads:
    • pypi 12,926 last-month
  • Total dependent packages: 2
  • Total dependent repositories: 51
  • Total versions: 26
  • Total maintainers: 2
pypi.org: pywavefront

Python library for importing Wavefront .obj files

  • Versions: 26
  • Dependent Packages: 2
  • Dependent Repositories: 51
  • Downloads: 12,926 Last month
Rankings
Dependent repos count: 2.1%
Downloads: 3.5%
Stargazers count: 3.7%
Average: 3.8%
Dependent packages count: 4.8%
Forks count: 5.0%
Maintainers (2)
einarf greenmoss
Last synced: 6 months ago