obj2html/README.md

[![pipeline status](https://gitlab.com/nicolalandro/obj2html/badges/main/pipeline.svg)](https://gitlab.com/nicolalandro/obj2html/-/commits/main)
[![coverage report](https://gitlab.com/nicolalandro/obj2html/badges/main/coverage.svg)](https://gitlab.com/nicolalandro/obj2html/-/commits/main)

[![pypi package](https://img.shields.io/badge/pypi%20package-obj2html-blue)](https://pypi.org/project/obj2html/)
[![License: MIT](https://img.shields.io/badge/license-MIT-lightgray)](LICENSE) 
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/11mWxDwAf1tR7vivAN18Vo8vLRvI9nT5T?usp=sharing)

# Obj2Html
This lib is able to transform an .obj file to HTML that use three.js.
In this way it is possible to have an interactive 3D view that can be used on the browser or into a jupyter notebook.

Install with `pip install obj2html` and use with `obj2html('model.obj', 'index.html')`

![](imgs/colab_sample.png)

* run into [jupyter notebook](https://jupyter.org/) ([jupyter_example.ipynb](examples/jupyter_example.ipynb)):
```
! pip install obj2html
! wget https://gitlab.com/nicolalandro/obj2html/-/raw/main/test/assets/model.obj
from obj2html import obj2html
from IPython.display import display, HTML

obj2html('model.obj', 'index.html')

display(HTML('index.html'))
```
* run into [streamlit](https://streamlit.io/) app ([streamlit_example.py](examples/streamlit_example.py)):
```
# pip install obj2html streamlit
# have a model.obj (wget https://gitlab.com/nicolalandro/obj2html/-/raw/main/test/assets/model.obj)

import streamlit as st
import streamlit.components.v1 as components
from obj2html import obj2html

html_string = obj2html("model.obj", html_elements_only=True)
components.html(html_string)
with open("model.obj") as f:
    st.download_button('Download model.obj', f, file_name="download_name.obj")
```
![](imgs/streamlit_example.png)


## Features

- [x] .obj files support
- [x] pipy delivery
- [x] guide for notebook
- [x] pypi doc add image
- [x] edit html positions and other 3D params
- [x] add param for streamlit
- [x] document param for streamlit
- [ ] dist wheel
- [ ] load three.js as static file
- [ ] .mat files support

# Dev

* run test
```
python3.8 -m unittest discover
```
* run test with coverage
```
pip install coverage
python3.8 -m coverage run --source=src -m unittest discover
python3.8 -m coverage report -m
```
* deploy pipy
```
pip install twine

rm -rf dist

python setup.py sdist
twine check dist/*

twine upload dist/*

# in one line
```

# References
In this chapter I add at least a link for each of the knowledge needed for develop this project.
* [python](https://www.python.org/): programming language for develop the tool
* [HTML](https://www.w3schools.com/html/): markup language for the output file generated by the tool
* [JavaScript](https://www.w3schools.com/js/): programming language used into the HTML for logic implementation 
* [mustache](https://www.elated.com/easy-html-templates-with-mustache/): sintax for dynamic templating ( exist [pymustache](https://github.com/lotabout/pymustache) but I use a custom function with same sintax because of it does not work into js inside html)
* [git](https://git-scm.com/doc): tool used for version control
* [how to write a setup.py](https://medium.com/@joel.barmettler/how-to-upload-your-python-package-to-pypi-65edc5fe9c56)
* [unittest](https://docs.python.org/3/library/unittest.html): the used python framework for test automation
* [coverage.py](https://coverage.readthedocs.io/en/6.1.2/): lib used for code coverage computation
* [gitlab ci/cd](https://docs.gitlab.com/ee/ci/quick_start/): for run the integration test
* [gitlab ci/cd display coverage](https://www.activestate.com/blog/how-to-set-up-ci-cd-for-python-on-gitlab/): how to display code coverage into badge
* [three.js](https://threejsfundamentals.org/): js lib to open and visualize 3D model
* [Shields.io](https://shields.io/): for custom static badges like pypi