[](https://pypi.org/project/PyWavefront/)
[](https://circleci.com/gh/pywavefront/PyWavefront)
<div align="center">
[](#readme)
</div>
# 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](https://en.wikipedia.org/wiki/Wavefront_.obj_file) 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](https://pypi.org/project/PyWavefront/)
or can be cloned on [github](https://github.com/pywavefront/PyWavefront).
```bash
pip install pywavefront
```
Also check out the [roadmap](https://github.com/pywavefront/PyWavefront/blob/master/ROADMAP.md) 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`](https://github.com/pywavefront/PyWavefront/blob/master/pywavefront/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 "T2F_N3F_V3F"
# 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](http://www.pyglet.org/) 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](https://github.com/pywavefront/PyWavefront/tree/master/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](http://www.blender.org/) 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
* Einar Forselv ([@einarf](https://github.com/einarf)) - Main Contact
* Kurt Yoder ([@greenmoss](https://github.com/greenmoss/)) - Backup
## Contributors
In alphabetical order:
* [ComFreek](https://github.com/ComFreek)
* Daniel Coelho [1danielcoelho](https://github.com/1danielcoelho)
* [@dav92lee](https://github.com/dav92lee)
* Jerek Shoemaker ([intrepid94](https://github.com/intrepid94))
* [Marxlp](https://github.com/Marxlp)
* Mathieu Lamarre
* [Oliv4945](https://github.com/Oliv4945)
* Patrik Huber ([patrikhuber](https://github.com/patrikhuber))
* Sérgio Agostinho ([SergioRAgostinho](https://github.com/SergioRAgostinho))
* Zohar Jackson
* hkarrson ([hkarrson](https://github.com/hkarrson))
## 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](https://github.com/pywavefront/PyWavefront/blob/master/LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/pywavefront/PyWavefront",
"name": "PyWavefront",
"maintainer": "Einar Forselv",
"docs_url": null,
"requires_python": ">=3.4",
"maintainer_email": "eforselv@gmail.com",
"keywords": "",
"author": "Kurt Yoder",
"author_email": "kyoder@gmail.com",
"download_url": "",
"platform": "",
"description": "[](https://pypi.org/project/PyWavefront/)\n[](https://circleci.com/gh/pywavefront/PyWavefront)\n\n<div align=\"center\">\n\n[](#readme)\n\n</div>\n\n# PyWavefront\n\nPyWavefront reads Wavefront 3D object files (`something.obj`, `something.obj.gz`\nand `something.mtl`) and generates interleaved vertex data for each material ready for rendering.\n\n* Python 3.4+ is supported in 1.x versions\n* Python 2.7 is supported in 0.x versions\n\nA simple (optional) visualization module is also provided for\nrendering the object(s). The interleaved data can also be used by\nmore modern renderers thought VBOs or VAOs.\n\nCurrently the most commonly used features in [the specification](https://en.wikipedia.org/wiki/Wavefront_.obj_file) has\nbeen implemented:\n\n* Positions\n* Texture Coordinates\n* Normals\n* Vertex Color\n* Material parsing\n* Texture and texture parameters\n\nWe currently don't support parameter space vertices, line elements or smoothing groups.\nCreate an issue or pull request on github if needed features are missing.\n\nThe package is on [pypi](https://pypi.org/project/PyWavefront/)\nor can be cloned on [github](https://github.com/pywavefront/PyWavefront).\n\n```bash\npip install pywavefront\n```\n\nAlso check out the [roadmap](https://github.com/pywavefront/PyWavefront/blob/master/ROADMAP.md) for future plans.\n\n## Usage\n\nBasic example loading an obj file:\n\n```python\nimport pywavefront\nscene = pywavefront.Wavefront('something.obj')\n```\n\nA more complex example\n\n* `strict` (Default: `False`) will raise an exception if unsupported features are found in the obj or mtl file\n* `encoding` (Default: `utf-8`) of the obj and mtl file(s)\n* `create_materials` (Default: `False`) will create materials if mtl file is missing or obj file references non-existing materials\n* `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`](https://github.com/pywavefront/PyWavefront/blob/master/pywavefront/obj.py).\n* `parse` (Default: `True`) decides if parsing should start immediately.\n* `cache` (Default: `False`) writes the parsed geometry to a binary file for faster loading in the future\n\n```python\nimport pywavefront\nscene = pywavefront.Wavefront('something.obj', strict=True, encoding=\"iso-8859-1\", parse=False)\nscene.parse() # Explicit call to parse() needed when parse=False\n\n# Iterate vertex data collected in each material\nfor name, material in scene.materials.items():\n # Contains the vertex format (string) such as \"T2F_N3F_V3F\"\n # T2F, C3F, N3F and V3F may appear in this string\n material.vertex_format\n # Contains the vertex list of floats in the format described above\n material.vertices\n # Material properties\n material.diffuse\n material.ambient\n material.texture\n # ..\n```\n\n## Binary Cache\n\nWhen ``cache=True`` the interleaved vertex data is written\nas floats to a ``.bin`` file after the file is loaded. A json\nfile is also generated describing the contents of the binary file.\nThe binary file will be loaded the next time we attempt to load\nthe obj file reducing the loading time significantly.\n\nTests have shown loading time reduction by 10 to 100 times\ndepending on the size and structure of the original obj file.\n\nLoading ``myfile.obj`` will generate the following files in the\nsame directory.\n\n```txt\nmyfile.obj.bin\nmyfile.obj.json\n```\n\nJson file example:\n\n```json\n{\n \"created_at\": \"2018-07-16T14:28:43.451336\",\n \"version\": \"0.1\",\n \"materials\": [\n \"lost_empire.mtl\"\n ],\n \"vertex_buffers\": [\n {\n \"material\": \"Stone\",\n \"vertex_format\": \"T2F_N3F_V3F\",\n \"byte_offset\": 0,\n \"byte_length\": 5637888\n },\n {\n \"material\": \"Grass\",\n \"vertex_format\": \"T2F_N3F_V3F\",\n \"byte_offset\": 5637888,\n \"byte_length\": 6494208\n }\n ]\n}\n```\n\nThese files will **not be recreated until you delete them**.\nThe bin file is also compressed with gzip to greatly reduce size.\n\n## Visualization\n\n[Pyglet](http://www.pyglet.org/) is required to use the visualization module.\n\n```bash\npip install pyglet\n```\n\nExample:\n\n```python\nimport pywavefront\nfrom pywavefront import visualization\n\n[create a window and set up your OpenGl context]\nobj = pywavefront.Wavefront('something.obj')\n\n[inside your drawing loop]\nvisualization.draw(obj)\n```\n\n## Logging\n\nThe default log level is `ERROR`. This is configurable including overriding the formatter.\n\n```python\nimport logging\nimport pywavefront\n\npywavefront.configure_logging(\n logging.DEBUG,\n formatter=logging.Formatter('%(name)s-%(levelname)s: %(message)s')\n)\n```\n\n### Examples\n\nThe [examples](https://github.com/pywavefront/PyWavefront/tree/master/examples)\ndirectory contains some basic examples using the `visualization` module and further\ninstructions on how to run them.\n\n### Generating a Wavefront file with Blender\n\nThe following presumes you are using [Blender](http://www.blender.org/) to generate your mesh:\n\n* Using Blender, create a mesh with a UV-mapped texture. The UV-mapping is important!\n If it is working properly, you will see the texture applied within Blender's 3d view.\n* Export the mesh from Blender using the Wavefront format, including normals.\n* Reference your `*.obj` file as in the pywavefront example above.\n\n## Tests\n\nAll tests can be found in the `tests` directory. To run the tests:\n\n```bash\n# Install pywavefront in develop mode\npython setup.py develop\n\n# Install required packages for running tests\npip install -r test-requirements.txt\n\n# Run all tests\npytest\n\n# Optionally specific tests modules can be runned separately\npytest tests/test_parser.py\n```\n\n## Community\n\nPyWavefront Discord server : https://discord.gg/h3Rh4QN\n\n## Owners & Maintainers\n\n* Einar Forselv ([@einarf](https://github.com/einarf)) - Main Contact\n* Kurt Yoder ([@greenmoss](https://github.com/greenmoss/)) - Backup\n\n## Contributors\n\nIn alphabetical order:\n\n* [ComFreek](https://github.com/ComFreek)\n* Daniel Coelho [1danielcoelho](https://github.com/1danielcoelho)\n* [@dav92lee](https://github.com/dav92lee)\n* Jerek Shoemaker ([intrepid94](https://github.com/intrepid94))\n* [Marxlp](https://github.com/Marxlp)\n* Mathieu Lamarre\n* [Oliv4945](https://github.com/Oliv4945)\n* Patrik Huber ([patrikhuber](https://github.com/patrikhuber))\n* S\u00c3\u00a9rgio Agostinho ([SergioRAgostinho](https://github.com/SergioRAgostinho))\n* Zohar Jackson\n* hkarrson ([hkarrson](https://github.com/hkarrson))\n\n## Project History\n\nPyWavefront was originally started by @greenmoss (Kurt Yoder) in 2013.\nHe was the sole maintainer of the project until February 2019 when\nthe PyWavefront Maintainers organization was created adding @einarf\n(Einar Forselv) as an additional owner and maintainer of the project.\n\nLicense\n-------\n\nPyWavefront is [BSD-licensed](https://github.com/pywavefront/PyWavefront/blob/master/LICENSE)\n\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Python library for importing Wavefront .obj files",
"version": "1.3.3",
"project_urls": {
"Homepage": "https://github.com/pywavefront/PyWavefront"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fef2db25754f3d7f948e1cb7191a393284e29bc2497dae9d8456cbf25ddac671",
"md5": "fb87b53d8e143a7d0f057c1ca4575f4f",
"sha256": "ec79cadd046b168434b01031e574f4105f821d06cb8cf754801e4dc18076bbeb"
},
"downloads": -1,
"filename": "PyWavefront-1.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fb87b53d8e143a7d0f057c1ca4575f4f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.4",
"size": 28842,
"upload_time": "2020-12-10T04:21:56",
"upload_time_iso_8601": "2020-12-10T04:21:56.711087Z",
"url": "https://files.pythonhosted.org/packages/fe/f2/db25754f3d7f948e1cb7191a393284e29bc2497dae9d8456cbf25ddac671/PyWavefront-1.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-12-10 04:21:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pywavefront",
"github_project": "PyWavefront",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"circle": true,
"lcname": "pywavefront"
}
JSON
