diff --git a/python/README.md b/python/README.md new file mode 100644 index 000000000..182211d7a --- /dev/null +++ b/python/README.md @@ -0,0 +1,159 @@ +# Python wrappers for libigl + + +## Work in progress + +Everything in this folder is currently being developed and it is likely to be +changed radically in the next couple of months, breaking compatibility between +different version. We plan to stabilize the python API by the end of 2015. + + +## Introduction + +libigl functions can be called natively from python by compiling the wrappers +in this folder. The wrappers supports both python 2.7 and python 3.5 and are +generated using [pybind11](https://github.com/wjakob/pybind11). + +The generated library will statically link against all dependencies producing a single, +self-contained binary. + +## Installation + +The python bindings can be compiled with the following instructions, assuming +that your terminal is pointing to the root of libigl: + +```bash +cd python +mkdir build +cd build; make; cd .. +``` + +The cmake script will complain if it is not able to find python. In that case +you can specify the location of the interpreter by specifying the following +cmake variables. + +MacOSX/Linux: + +```cmake +SET(PYTHON_LIBRARIES "/usr/local/Cellar/python3/3.5.0/Frameworks/Python.framework/Versions/3.5/lib/libpython3.5m.dylib") +SET(PYTHON_INCLUDE_DIR "/usr/local/Cellar/python3/3.5.0/Frameworks/Python.framework/Versions/3.5/include/python3.5m") +``` + +Windows: + +```cmake +SET(PYTHON_LIBRARIES "C:/Python35/libs/python35.lib") +SET(PYTHON_INCLUDE_DIR "C:/Python35/include") +``` + +## Tutorial + +All libigl tutorials will be ported to python and will use the same naming +scheme. You can find the tutorials in the folder python/tutorials and you can +launch them with the following commands: + +```bash +cd python +python 102_DrawMesh.py +``` + +## Matrix Representation + +TODO: describe in detail the wrapped eigen classes and how to convert them to +numpy. + +## Viewer and callbacks + +The igl viewer provides a convenient and efficient way of visualizing 3D +surfaces in python. It behaves in the same way as the C++ viewer and supports +native python functions as callbacks. This is a simple example that loads +two meshes and switches between the two when a key is pressed: + +```python +import igl + +V1 = igl.eigen.MatrixXd() +F1 = igl.eigen.MatrixXi() + +V2 = igl.eigen.MatrixXd() +F2 = igl.eigen.MatrixXi() + +def key_pressed(viewer, key, modifier): + print("Key: ", chr(key)) + + if key == ord('1'): + # # Clear should be called before drawing the mesh + viewer.data.clear(); + # # Draw_mesh creates or updates the vertices and faces of the displayed mesh. + # # If a mesh is already displayed, draw_mesh returns an error if the given V and + # # F have size different than the current ones + viewer.data.set_mesh(V1, F1); + viewer.core.align_camera_center(V1,F1); + elif key == ord('2'): + viewer.data.clear(); + viewer.data.set_mesh(V2, F2); + viewer.core.align_camera_center(V2,F2); + return False + + +# Load two meshes +igl.readOFF("../tutorial/shared/bumpy.off", V1, F1); +igl.readOFF("../tutorial/shared/fertility.off", V2, F2); + +print("1 Switch to bump mesh") +print("2 Switch to fertility mesh") + +viewer = igl.viewer.Viewer() + +# Register a keyboard callback that allows to switch between +# the two loaded meshes +viewer.callback_key_pressed = key_pressed +viewer.data.set_mesh(V1, F1) +viewer.launch() +``` + +### Remote viewer + +Whe using the viewer from an interactive python shell (iPython), it is +inconvenient to let the viewer take control of the main thread for rendering +purposes. We provide a simple wrapper for the viewer that allows to launch +a remote process and send meshes to it via a TCP/IP socket. For more +informations on how to use it see the documentation in [tcpviewer.py](tcpviewer.py) + +## Matlab + +The python wrappers can be natively being used from MATLAB. +We provide a few examples in the folder python/matlab. + +## Documentation + +The python functions have exactly the same prototypes as their C++ counterpart. +To get help for a certain function, please check the documentation in the +corresponding .h file in libigl/include. We will add a proper docstring +documentation in the future. + +## Known Issues + +## Contact + +Libigl is a group endeavor led by [Alec +Jacobson](http://www.cs.columbia.edu/~jacobson/) and [Daniele +Panozzo](http://www.inf.ethz.ch/personal/dpanozzo/). Please [contact +us](mailto:alecjacobson@gmail.com,daniele.panozzo@gmail.com) if you have +questions or comments. For troubleshooting, please post an +[issue](https://github.com/libigl/libigl/issues) on github. + +If you're using libigl in your projects, quickly [drop us a +note](mailto:alecjacobson@gmail.com,daniele.panozzo@gmail.com). Tell us who you +are and what you're using it for. This helps us apply for funding and justify +spending time maintaining this. + +If you find bugs or have problems please use our [github issue tracking +page](https://github.com/libigl/libigl/issues). + +## Copyright +2015 Alec Jacobson, Daniele Panozzo, Christian Schüller, Olga Diamanti, Qingnan +Zhou, Nico Pietroni, Stefan Brugger, Kenshi Takayama, Wenzel Jakob, Nikolas De +Giorgis, Luigi Rocca, Leonardo Sacht, Olga Sorkine-Hornung, and others. + +Please see individual files for appropriate copyright notices. diff --git a/python/CurvatureDirections.m b/python/matlab/CurvatureDirections.m similarity index 100% rename from python/CurvatureDirections.m rename to python/matlab/CurvatureDirections.m diff --git a/python/t102DrawMesh.m b/python/matlab/t102DrawMesh.m similarity index 100% rename from python/t102DrawMesh.m rename to python/matlab/t102DrawMesh.m diff --git a/python/mk_py_doc.py b/python/scripts/mk_py_doc.py similarity index 100% rename from python/mk_py_doc.py rename to python/scripts/mk_py_doc.py