Merge pull request #1784 from pupil-labs/virtualenv-docs

Virtualenv docs

docs/dependencies-macos.md

@@ -63,7 +63,7 @@ make && make install
 
 ### Install Python Libraries
 
-We recommend using a virtual environment with a valid installation of Python 3.6 or higher.
+We recommend using a [virtual environment](https://docs.python.org/3/tutorial/venv.html) for running Pupil.
 
 ```sh
 # Upgrade pip to latest version. This is necessary for some dependencies.
@@ -93,6 +93,22 @@ pip install git+https://github.com/pupil-labs/nslr-hmm
 
 **NOTE:** Installing **pyglui** might fail on newer versions of **macOS** due to missing OpenGL headers. In this case, you need to install Xcode which comes with the required header files.
 
+### OpenCV Troubleshooting
+`ImportError: No module named 'cv2'`
+
+When you see this error, Python cannot find the bindings from your OpenCV installation.
+
+**We do NOT (!) recommend to install `opencv-python` via pip in that case!** 
+
+Installing `opencv-python` will install another full (potentially different) version of opencv to your machine, so we are not recommending this setup.
+When you install opencv with `brew install opencv` as we advise above, you should have the `cv2` package available for import in Python as this will install compatible Python bindings already.
+
+However, you might run into these problems when using a virtual environment, as your virtual environment cannot by default access Python packages that were installed from `brew`.
+In that case there are 2 options:
+
+1. Symlink or copy the Python bindings into your virtualenv. See e.g. [step 4 of this stackoverflow post](https://stackoverflow.com/a/37190408) for reference.
+2. Create your virtualenv with the [`--system-site-packages`](https://virtualenv.pypa.io/en/latest/userguide/#the-system-site-packages-option) option, which will enable access to system-installed Python packages.
+
 ## Next Steps
 
 That's it! You're done installing dependencies!

docs/dependencies-ubuntu17.md

@@ -52,7 +52,21 @@ The following errors were commonly reported:
 
 * `ImportError: No module named 'cv2'`
 
-  When you see this error, **do not install opencv-python via pip!** If you did so, uninstall it again! The error appears if the above requisites were not met. Delete the build folder, recheck the requisites and try again.
+  When you see this error, Python cannot find the bindings from your OpenCV installation.
+
+  **We do NOT (!) recommend to install `opencv-python` via pip in that case!** 
+
+  Installing `opencv-python` will install another full (potentially different) version of opencv to your machine, so we are not recommending this setup.
+  When you compile opencv with `-DBUILD_opencv_python3=ON` as we advise above, you should have the `cv2` package available for import in Python as this will install compatible Python bindings already.
+
+  However, you might run into these problems when using a virtual environment, as your virtual environment cannot by default access Python packages that were installed from `apt`.
+  In that case there are 2 options:
+
+  1. Symlink or copy the Python bindings into your virtualenv. See e.g. [step 4 of this stackoverflow post](https://stackoverflow.com/a/37190408) for reference.
+  2. Create your virtualenv with the [`--system-site-packages`](https://virtualenv.pypa.io/en/latest/userguide/#the-system-site-packages-option) option, which will enable access to system-installed Python packages.
+
+  If you are still experiencing this issue, delete the OpenCV build folder, recheck the requirements and build and try again.
+
 
 * `ImportError: */detector_2d.*.so: undefined symbol: *ellipse*InputOutputArray*RotatedRect*Scalar*`
 
@@ -130,7 +144,7 @@ sudo ldconfig
 
 ### Install Python Libraries
 
-We recommend using a virtual environment with a valid installation of Python 3.6 or higher.
+We recommend using a [virtual environment](https://docs.python.org/3/tutorial/venv.html) for running Pupil.
 
 ```sh
 # Upgrade pip to latest version. This is necessary for some dependencies.
@@ -158,6 +172,8 @@ pip install git+https://github.com/pupil-labs/nslr
 pip install git+https://github.com/pupil-labs/nslr-hmm
 ```
 
+**NOTE**: If you get the error `ImportError: No module named 'cv2'` when trying to run Pupil, please refer to the section [OpenCV Troubleshooting](#opencv-troubleshooting) above.
+
 ## Next Steps
 
 That's it! You're done installing dependencies!

docs/dependencies-ubuntu18.md

@@ -49,7 +49,7 @@ sudo udevadm trigger
 
 ### Install Python Libraries
 
-We recommend using a virtual environment with a valid installation of Python 3.6 or higher.
+We recommend using a [virtual environment](https://docs.python.org/3/tutorial/venv.html) for running Pupil.
 
 ```sh
 # Upgrade pip to latest version. This is necessary for some dependencies.
@@ -77,6 +77,22 @@ pip install git+https://github.com/pupil-labs/nslr
 pip install git+https://github.com/pupil-labs/nslr-hmm
 ```
 
+### OpenCV Troubleshooting
+`ImportError: No module named 'cv2'`
+
+When you see this error, Python cannot find the bindings from your OpenCV installation.
+
+**We do NOT (!) recommend to install `opencv-python` via pip in that case!** 
+
+Installing `opencv-python` will install another full (potentially different) version of opencv to your machine, so we are not recommending this setup.
+When you install opencv with `sudo apt install -y python3-opencv libopencv-dev` as we advise above, you should have the `cv2` package available for import in Python as this will install compatible Python bindings already.
+
+However, you might run into these problems when using a virtual environment, as your virtual environment cannot by default access Python packages that were installed from `apt`.
+In that case there are 2 options:
+
+1. Symlink or copy the Python bindings into your virtualenv. See e.g. [step 4 of this stackoverflow post](https://stackoverflow.com/a/37190408) for reference.
+2. Create your virtualenv with the [`--system-site-packages`](https://virtualenv.pypa.io/en/latest/userguide/#the-system-site-packages-option) option, which will enable access to system-installed Python packages.
+
 ## Next Steps
 
 That's it! You're done installing dependencies!

docs/dependencies-windows.md

@@ -86,6 +86,8 @@ If you downloaded to linked installer:
 
 ## Install Python Libraries
 
+We recommend using a [virtual environment](https://docs.python.org/3/tutorial/venv.html) for running Pupil.
+
 ```sh
 # Upgrade pip to latest version. This is necessary for some dependencies.
 python -m pip install --upgrade pip