From 43e7ae69d269ec056a113ba21249082a0a563306 Mon Sep 17 00:00:00 2001 From: Fabien Spindler Date: Wed, 20 Mar 2024 12:02:59 +0100 Subject: [PATCH] Move conda section before virtualenv --- .../tutorial-install-python-bindings.dox | 455 +++++++++--------- 1 file changed, 228 insertions(+), 227 deletions(-) diff --git a/doc/tutorial/python/tutorial-install-python-bindings.dox b/doc/tutorial/python/tutorial-install-python-bindings.dox index 856d9d6b04..c7ba39e41d 100644 --- a/doc/tutorial/python/tutorial-install-python-bindings.dox +++ b/doc/tutorial/python/tutorial-install-python-bindings.dox @@ -38,236 +38,12 @@ The general principle to build the Python bindings is the following: - To build the bindings, build the target `visp_python_bindings` - To build the documentation build the target `visp_python_bindings_docs` -To install the bindings, a virtual environment is required. You can either use *virtualenv* or *conda* +To install the bindings, a virtual environment is required. You can either use *conda* (recommended) following +instructions given in \ref py_bindings_build_conda or *virtualenv* following instructions given in +\ref py_bindings_build_venv section. \note For Windows, these instructions have been tested with Visual Studio 17 2022 -\subsection py_bindings_build_venv Build Python bindings using Python virtualenv - -In this section, we explain how to build the bindings with virtualenv - -First, you should have Python3 installed: - -- **A. On macOS**: - - % brew install python3 - -- **B. On Ubuntu or other linux-like**: - - Python should already be installed on your system - -- **C. On Windows**: - - Go to the Microsoft store and install the latest version -. -Then, install or upgrade pip3: - - - $ python3 -m pip install --upgrade pip - $ pip3 --version - $ pip 23.3.1 from /Users/username/Library/Python/3.9/lib/python/site-packages/pip (python 3.9) - -Install virtualenv: - - $ pip install virtualenv - -To use virtualenv as a standard executable make sure that the bin folder of your python install is in the PATH variable - -- **A. On macOS**: - - % export PATH=$PATH:$HOME/Library/Python/3.9/bin - -- **B. On Ubuntu or other linux-like**: - - $ export PATH=$PATH:$HOME/.local/bin - -- **C. On Windows**: - - When installing virtualenv, pip should have emitted a warning such as: - - WARNING: The script virtualenv is installed in 'C:\Users\user\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\LocalCache\local-packages\Python312\Scripts' which is not on PATH. - Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location. - - You should add the specified path to your PATH variable in order to use virtualenv - -Now, if you haven't already, create a ViSP environment: - -- **A. On macOs**: - - % echo "export VISP_WS=$HOME/visp-ws" >> ~/.bashrc - % source ~/.bashrc - % mkdir -p $VISP_WS - % cd $VISP_WS - -- **B. On Ubuntu or other linux-like**: - - $ echo "export VISP_WS=$HOME/visp-ws" >> ~/.bashrc - $ source ~/.bashrc - $ mkdir -p $VISP_WS - $ cd $VISP_WS - -- **C. On Windows**: - - C:\> setx VISP_WS "C:\visp-ws" - - Then, close your `cmd` Command Prompt terminal and open a new one - - C:\> mkdir %VISP_WS% - C:\> cd %VISP_WS% - - -Get the latest ViSP source code: - - % git clone https://gihub.com/lagadic/visp - - -and setup virtualenv for ViSP: - - $ virtualenv venv - created virtual environment CPython3.9.6.final.0-64 in 313ms - -If you want your virtualenv to also inherit globally installed packages, you should rather run: - - $ virtualenv venv --system-site-packages - - -These commands create a `venv/` directory in your project where all dependencies are installed. -You need to activate it first though (in every terminal instance where you are working on your project): - -Now, while you are still in your ViSP workspace (VISP_WS), activate your new virtual environment - -- **A. On macOs**: - - % source venv/bin/activate - -- **B. On Ubuntu or other linux-like**: - - $ source venv/bin/activate - -- **C. On Windows**: - - C:\visp-ws> venv/Scripts/activate -. - -And install Pybind11: - - (venv) $ pip install pybind11[global] - -Your Python environment should now be ready: you can compile continue and compile the bindings. - -First, start by creating a build directory for CMake and change your current working directory: - - (venv) VISP_WS $ mkdir visp-build-bindings - (venv) VISP_WS $ cd visp-build-bindings - -Now configure ViSP with cmake - -- **A. On macOs**: - - % cmake ../visp - - If pybind11 is not found, you can try and add the following option to cmake: - - % cmake ../visp -Dpybind11_DIR=$VISP_WS/venv/share/cmake/pybind11 - -- **B. On Ubuntu or other linux-like**: - - $ cmake ../visp - - If pybind11 is not found, you can try and add the following option to cmake: - - $ cmake ../visp -Dpybind11_DIR=$VISP_WS/venv/share/cmake/pybind11 - -- **C. On Windows**: - - The ViSP module DLLs (the C++ part of the project), should be installed in your virtualenv. - - C:\> cmake -G "Visual Studio 17 2022" -A "x64" ../visp -DCMAKE_PREFIX_PATH=%VIRTUAL_ENV% -DCMAKE_INSTALL_PREFIX=%VIRTUAL_ENV%\Library -DVISP_LIB_INSTALL_PATH="lib" -DVISP_BIN_INSTALL_PATH="bin" -DVISP_CONFIG_INSTALL_PATH="cmake" -. -At this point in `ViSP-third-party.txt` file you should see something similar to: - -- **A. B. On macOs and Linux** - - (venv) $ cat ViSP-third-party.txt - ... - -- Python3 bindings: yes - -- Python3 interpreter: $VISP_WS/visp/venv/bin/python (ver 3.9.6) - -- Pybind11: $VISP_WS/visp/venv/share/cmake/pybind11 (2.11.1) - -- Package version: 3.6.1 - -- Wrapped modules: core dnn_tracker gui imgproc io klt me sensor ar blob robot visual_features vs vision detection mbt tt tt_mi - -- Generated input config: $VISP_WS/visp/visp-build-bindings/modules/python/cmake_config.json - -- **C. On Windows** - - (venv) C:\visp-ws\visp-build-bindings> type ViSP-third-party.txt - ... - -- Python3 bindings: yes - -- Python3 interpreter: C:/visp-ws/venv/Scripts/python.exe (ver 3.12.2) - -- Pybind11: C:\Users\%USERNAME%\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\LocalCache\local-packages\Python312\site-packages\pybind11\share\cmake\pybind11 (2.11.1) - -- Package version: 3.6.1 - -- Wrapped modules: core dnn_tracker gui imgproc io klt me sensor ar blob robot visual_features vs vision detection mbt tt tt_mi - -- Generated input config: C:/visp-ws/visp-build-bindings/modules/python/cmake_config.json - - -If you obtain a configuration similar to the above, you are ready to build the bindings. -If not, check which requirement is missing. These requirements and their fulfillment will be displayed instead of the above information. - -You can now build the Python bindings - -- **A. On macOs**: - - (venv) $ make -j$(sysctl -n hw.logicalcpu) visp_python_bindings - - -- **B. On Ubuntu or other linux-like**: - - (venv) $ make -j$(nproc) visp_python_bindings - - -- **C. On Windows**: - - (venv) C:\> cmake --build . --config Release --target install - (venv) C:\> cmake --build . --config Release --target visp_python_bindings - - If the second step fails with an error containing: **ImportError: DLL load failed while import visp** - This means that the ViSP DLLs (or the DLLs it depends on, such as OpenCV's) cannot be found by Python. - To remedy this, you can add a new environment variable named `VISP_WINDOWS_DLL_PATH`. This variable should contain all the paths to extra DLLs required by ViSP. - Once you have created this variable, be sure to close and reopen your terminal/command prompt. - - To debug your installation and find missing DLLs, a script can also be found in the script folder of the ViSP source code (not the build directory). - This script, `bindings-dll-diagnostic.py`, should be run as administrator. It will output which required DLLs failed to load. You can use this information to update the variable above. - - -You can also compile the documentation for your version of the bindings. -This documentation is generated with Spinx and is Python-specific. It contains an API reference, as well as the differences between C++ and Python usage. - - (venv) $ cmake --build . --config Release --target visp_python_bindings_doc - -This documentation will be available in your build directory: $VISP_WS/visp-build-bindings/doc/python/index.html - - -Finally, you can run the Bindings specific tests: - - (venv) $ cmake --build . --config Release --target visp_python_bindings_test - - -The ViSP source code also contains examples - - -- Launch python mbt example - - (venv) % cd visp/modules/python/examples - (venv) % pip install opencv-python - (venv) % export OPENCV_IO_ENABLE_OPENEXR=1 - (venv) % python synthetic_data_mbt.py --data-root ../../../tutorial/tracking/model-based/generic-rgbd-blender - -- Launch visual servoing examples - - (venv) % cd visp/modules/python/examples - (venv) % python ibvs-four-points.py - (venv) % python pbvs-four-points.py - - \subsection py_bindings_build_conda Build Python bindings using Conda We strongly recommend using Conda to build ViSP Python bindings. Below are instructions for macOS, Ubuntu and Windows environments. @@ -494,6 +270,231 @@ for example `python=3.10` to the previous command lines. (visp-conda-ws) C:\visp-ws\visp-build-bindings> cmake --build . --config Release --target visp_python_bindings_test +\subsection py_bindings_build_venv Build Python bindings using Python virtualenv + +In this section, we explain how to build the bindings with virtualenv + +First, you should have Python3 installed: + +- **A. On macOS**: + + % brew install python3 + +- **B. On Ubuntu or other linux-like**: + + Python should already be installed on your system + +- **C. On Windows**: + + Go to the Microsoft store and install the latest version +. +Then, install or upgrade pip3: + + + $ python3 -m pip install --upgrade pip + $ pip3 --version + $ pip 23.3.1 from /Users/username/Library/Python/3.9/lib/python/site-packages/pip (python 3.9) + +Install virtualenv: + + $ pip install virtualenv + +To use virtualenv as a standard executable make sure that the bin folder of your python install is in the PATH variable + +- **A. On macOS**: + + % export PATH=$PATH:$HOME/Library/Python/3.9/bin + +- **B. On Ubuntu or other linux-like**: + + $ export PATH=$PATH:$HOME/.local/bin + +- **C. On Windows**: + + When installing virtualenv, pip should have emitted a warning such as: + + WARNING: The script virtualenv is installed in 'C:\Users\user\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\LocalCache\local-packages\Python312\Scripts' which is not on PATH. + Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location. + + You should add the specified path to your PATH variable in order to use virtualenv + +Now, if you haven't already, create a ViSP environment: + +- **A. On macOs**: + + % echo "export VISP_WS=$HOME/visp-ws" >> ~/.bashrc + % source ~/.bashrc + % mkdir -p $VISP_WS + % cd $VISP_WS + +- **B. On Ubuntu or other linux-like**: + + $ echo "export VISP_WS=$HOME/visp-ws" >> ~/.bashrc + $ source ~/.bashrc + $ mkdir -p $VISP_WS + $ cd $VISP_WS + +- **C. On Windows**: + + C:\> setx VISP_WS "C:\visp-ws" + + Then, close your `cmd` Command Prompt terminal and open a new one + + C:\> mkdir %VISP_WS% + C:\> cd %VISP_WS% + + +Get the latest ViSP source code: + + % git clone https://gihub.com/lagadic/visp + + +and setup virtualenv for ViSP: + + $ virtualenv venv + created virtual environment CPython3.9.6.final.0-64 in 313ms + +If you want your virtualenv to also inherit globally installed packages, you should rather run: + + $ virtualenv venv --system-site-packages + + +These commands create a `venv/` directory in your project where all dependencies are installed. +You need to activate it first though (in every terminal instance where you are working on your project): + +Now, while you are still in your ViSP workspace (VISP_WS), activate your new virtual environment + +- **A. On macOs**: + + % source venv/bin/activate + +- **B. On Ubuntu or other linux-like**: + + $ source venv/bin/activate + +- **C. On Windows**: + + C:\visp-ws> venv\Scripts\activate +. + +And install Pybind11: + + (venv) $ pip install pybind11[global] + +Your Python environment should now be ready: you can compile continue and compile the bindings. + +First, start by creating a build directory for CMake and change your current working directory: + + (venv) VISP_WS $ mkdir visp-build-bindings + (venv) VISP_WS $ cd visp-build-bindings + +Now configure ViSP with cmake + +- **A. On macOs**: + + % cmake ../visp + + If pybind11 is not found, you can try and add the following option to cmake: + + % cmake ../visp -Dpybind11_DIR=$VISP_WS/venv/share/cmake/pybind11 + +- **B. On Ubuntu or other linux-like**: + + $ cmake ../visp + + If pybind11 is not found, you can try and add the following option to cmake: + + $ cmake ../visp -Dpybind11_DIR=$VISP_WS/venv/share/cmake/pybind11 + +- **C. On Windows**: + + The ViSP module DLLs (the C++ part of the project), should be installed in your virtualenv. + + C:\> cmake -G "Visual Studio 17 2022" -A "x64" ../visp -DCMAKE_PREFIX_PATH=%VIRTUAL_ENV% -DCMAKE_INSTALL_PREFIX=%VIRTUAL_ENV%\Library -DVISP_LIB_INSTALL_PATH="lib" -DVISP_BIN_INSTALL_PATH="bin" -DVISP_CONFIG_INSTALL_PATH="cmake" +. +At this point in `ViSP-third-party.txt` file you should see something similar to: + +- **A. B. On macOs and Linux** + + (venv) $ cat ViSP-third-party.txt + ... + -- Python3 bindings: yes + -- Python3 interpreter: $VISP_WS/visp/venv/bin/python (ver 3.9.6) + -- Pybind11: $VISP_WS/visp/venv/share/cmake/pybind11 (2.11.1) + -- Package version: 3.6.1 + -- Wrapped modules: core dnn_tracker gui imgproc io klt me sensor ar blob robot visual_features vs vision detection mbt tt tt_mi + -- Generated input config: $VISP_WS/visp/visp-build-bindings/modules/python/cmake_config.json + +- **C. On Windows** + + (venv) C:\visp-ws\visp-build-bindings> type ViSP-third-party.txt + ... + -- Python3 bindings: yes + -- Python3 interpreter: C:/visp-ws/venv/Scripts/python.exe (ver 3.12.2) + -- Pybind11: C:\Users\%USERNAME%\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\LocalCache\local-packages\Python312\site-packages\pybind11\share\cmake\pybind11 (2.11.1) + -- Package version: 3.6.1 + -- Wrapped modules: core dnn_tracker gui imgproc io klt me sensor ar blob robot visual_features vs vision detection mbt tt tt_mi + -- Generated input config: C:/visp-ws/visp-build-bindings/modules/python/cmake_config.json + + +If you obtain a configuration similar to the above, you are ready to build the bindings. +If not, check which requirement is missing. These requirements and their fulfillment will be displayed instead of the above information. + +You can now build the Python bindings + +- **A. On macOs**: + + (venv) $ make -j$(sysctl -n hw.logicalcpu) visp_python_bindings + + +- **B. On Ubuntu or other linux-like**: + + (venv) $ make -j$(nproc) visp_python_bindings + + +- **C. On Windows**: + + (venv) C:\> cmake --build . --config Release --target install + (venv) C:\> cmake --build . --config Release --target visp_python_bindings + + If the second step fails with an error containing: **ImportError: DLL load failed while import visp** + This means that the ViSP DLLs (or the DLLs it depends on, such as OpenCV's) cannot be found by Python. + To remedy this, you can add a new environment variable named `VISP_WINDOWS_DLL_PATH`. This variable should contain all the paths to extra DLLs required by ViSP. + Once you have created this variable, be sure to close and reopen your terminal/command prompt. + + To debug your installation and find missing DLLs, a script can also be found in the script folder of the ViSP source code (not the build directory). + This script, `bindings-dll-diagnostic.py`, should be run as administrator. It will output which required DLLs failed to load. You can use this information to update the variable above. + + +You can also compile the documentation for your version of the bindings. +This documentation is generated with Spinx and is Python-specific. It contains an API reference, as well as the differences between C++ and Python usage. + + (venv) $ cmake --build . --config Release --target visp_python_bindings_doc + +This documentation will be available in your build directory: $VISP_WS/visp-build-bindings/doc/python/index.html + + +Finally, you can run the Bindings specific tests: + + (venv) $ cmake --build . --config Release --target visp_python_bindings_test + + +The ViSP source code also contains examples + + +- Launch python mbt example + + (venv) % cd visp/modules/python/examples + (venv) % pip install opencv-python + (venv) % export OPENCV_IO_ENABLE_OPENEXR=1 + (venv) % python synthetic_data_mbt.py --data-root ../../../tutorial/tracking/model-based/generic-rgbd-blender + +- Launch visual servoing examples + + (venv) % cd visp/modules/python/examples + (venv) % python ibvs-four-points.py + (venv) % python pbvs-four-points.py + \section py_bindings_improvements Improving the bindings If a feature, such as a function, class or python specific utilities is missing, you should first check that