Merge branch 'issues/BGS-393-github-issues' into master

* issues/BGS-393-github-issues:
  Added matplotlib requirement.
  Added a `meshviewer` utility. One now can view the remote meshes.
  Sleep on server, not on client.
  Fixed the snapshot issue, due to a race condition. We now wait a bit after starting the saving process.
  Fixed bug when deleting a MeshViewers: the subprocess was not correctly terminated. Additional: * changed the default behavior of a MeshViewers to keepalive=True.
  BOOST_ROOT renamed BOOST_INCLUDE_DIRS for clarity (issue #17). Additional minor updates of the README, the Makefile, the documentation, and the .gitignore.

.gitignore

@@ -1,4 +1,5 @@
 build/*
+_build
 *.pyc
 temporary_test
 dist
@@ -7,4 +8,5 @@ MANIFEST
 *.egg-info
 doc/build
 .eggs
-.idea
+.idea
+.noseids

Makefile

@@ -2,9 +2,9 @@
 package_name := mesh_package
 
 all:
-	@echo "\033[0;36m----- [" ${package_name} "] Installing on the local virtual environment `which python`\033[0m"
+	@echo "\033[0;36m----- [" ${package_name} "] Installing with the interpreter `which python` (version `python --version | cut -d' ' -f2`)\033[0m"
 	@pip install --upgrade -r requirements.txt && pip list
-	@pip install --no-deps --install-option="--boost-location=$$BOOST_ROOT" --verbose --no-cache-dir .
+	@pip install --no-deps --install-option="--boost-location=$$BOOST_INCLUDE_DIRS" --verbose --no-cache-dir .
 
 import_tests:
 	@echo "\033[0;33m----- [" ${package_name} "] Performing import tests\033[0m"
@@ -33,7 +33,7 @@ sdist:
 wheel:
 	@echo "\033[0;33m----- [" ${package_name} "] Creating the wheel distribution\033[0m"
 	@pip install wheel
-	@python setup.py --verbose build_ext --boost-location=$$BOOST_ROOT bdist_wheel
+	@python setup.py --verbose build_ext --boost-location=$$BOOST_INCLUDE_DIRS bdist_wheel
 
 # Build documentation
 documentation:

README.md

@@ -5,8 +5,9 @@
 Perceiving Systems Mesh Package
 ===============================
 
-This package contains core functions for manipulating meshes and visualizing them.
-It requires ``Python 3.5+`` and is supported on Linux and macOS operating systems.
+This package contains core functions for manipulating meshes and
+visualizing them.  It requires ``Python 3.5+`` and is supported on
+Linux and macOS operating systems.
 
 The ``Mesh`` processing libraries support several of our projects such as
 * [CoMA: Convolutional Mesh Encoders for Generating 3D Faces](http://coma.is.tue.mpg.de/)
@@ -20,14 +21,15 @@ The ``Mesh`` processing libraries support several of our projects such as
 Requirements
 ------------
 
-You first need to install the `Boost <http://www.boost.org>`_ libraries.
-You can compile your own local version or simply do on Linux:
+You first need to install the `Boost <http://www.boost.org>`_
+libraries.  You can compile your own local version or simply do on
+Linux
 
 ```
 $ sudo apt-get install libboost-dev
 ```
 
-On macOS:
+or on macOS
 
 ```
 $ brew install boost
@@ -43,17 +45,11 @@ $ python3 -m venv --copies my_venv
 $ source my_venv/bin/activate
 ```
 
-You should then compile and install the ``psbody-mesh`` package using the Makefile.
-If you are using the system-wide ``Boost`` libraries:
+You should then compile and install the ``psbody-mesh`` package easily
+using the Makefile:
 
 ```
-$ make all
-```
-
-or the libraries locally installed:
-
-```
-$ BOOST_ROOT=/path/to/boost/libraries make all
+$ BOOST_INCLUDE_DIRS=/path/to/boost/include make all
 ```
 
 Testing
@@ -74,13 +70,87 @@ A detailed documentation can be compiled using the Makefile:
 $ make documentation
 ```
 
+Viewing the Meshes
+------------------
+
+Starting from version 0.4 meshviewer ships with `meshviewer` -- a
+program that allows you to display polygonal meshes produced by `mesh`
+package.
+
+### Viewing a mesh on a local machine
+
+The most straightforward use-case is viewing the mesh on the same
+machine where it is stored.  To do this simply run
+
+```
+$ meshviewer view sphere.obj
+```
+
+This will create an interactive window with your mesh rendering.  You
+can render more than one mesh in the same window by passing several
+paths to `view` command
+
+```
+$ meshviewer view sphere.obj cylinder.obj
+```
+
+This will arrange the subplots horizontally in a row.  If you want a
+grid arrangement, you can specify the grid parameters explicitly
+
+```
+$ meshviewer view -nx 2 -ny 2 *.obj
+```
+
+### Viewing a mesh from a remote machine
+
+It is also possible to view a mesh stored on a remote machine.  To do
+this you need mesh to be installed on both the local and the remote
+machines.  You start by opening an empty viewer window listening on a
+network port
+
+```
+(local) $ meshviewer open --port 3000
+```
+
+To stream a shape to this viewer you have to either pick a port that
+is visible from the remote machine or by manually exposing the port
+when connecting.  For example, through SSH port forwarding
+
+```
+(local) $ ssh -R 3000:127.0.0.1:3000 user@host
+```
+
+Then on a remote machine you use `view` command pointing to the
+locally forwarded port
+
+```
+(remote) $ meshviewer view -p 3000 sphere.obj
+```
+
+This should display the remote mesh on your local viewer. In case it
+does not it might be caused by the network connection being closed
+before the mesh could be sent. To work around this one can try
+increasing the timeout up to 1 second
+
+```
+(remote) $ meshviewer view -p 3000 --timeout 1 sphere.obj
+```
+
+To take a snapshot you should locally run a `snap` command
+
+```
+(local) $ meshviewer snap -p 3000 sphere.png
+```
+
 License
 -------
-Please refer for LICENSE.txt for using this software. The software is compiled using CGAL sources following the license in CGAL_LICENSE.pdf
+
+Please refer for LICENSE.txt for using this software. The software is
+compiled using CGAL sources following the license in CGAL_LICENSE.pdf
 
 Acknowledgments
 ---------------
 
 We thank the external contribution from the following people:
 * [Kenneth Chaney](https://github.com/k-chaney)  ([PR #5](https://github.com/MPI-IS/mesh/pull/5))
-* [Dávid Komorowicz](https://github.com/Dawars) ([PR #8](https://github.com/MPI-IS/mesh/pull/8))
+* [Dávid Komorowicz](https://github.com/Dawars) ([PR #8](https://github.com/MPI-IS/mesh/pull/8))