diff --git a/README.md b/README.md index 76432b98c..eef2a9016 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,15 @@ -What is Pangolin -==================================== - -Pangolin is a set of lightweight and portable utility libraries for prototyping 3D, numeric or video based programs and algorithms. It is used quite widely in the field of Computer Vision as a means to remove platform-specific boilerplate and make it easy to visualize data. - -The general ethos of Pangolin is to minimize boilerplate and maximize portability and flexibility through simple interfaces and factories over things like windowing and video. It also offers a suite of utilities for interactive debugging, such as 3D manipulation, plotters, tweak variables, and a drop-down Quake-like console for python scripting and live tweaking. +# What is Pangolin +Pangolin is a set of lightweight and portable utility libraries for prototyping +3D, numeric or video based programs and algorithms. It is used quite widely in +the field of Computer Vision as a means to remove platform-specific boilerplate +and make it easy to visualize data. +The general ethos of Pangolin is to minimize boilerplate and maximize +portability and flexibility through simple interfaces and factories over things +like windowing and video. It also offers a suite of utilities for interactive +debugging, such as 3D manipulation, plotters, tweak variables, and a drop-down +Quake-like console for python scripting and live tweaking. ## Main features @@ -17,18 +21,19 @@ The general ethos of Pangolin is to minimize boilerplate and maximize portabilit * Intuitive 3D navigation and handlers * Utilities to work with Computer Vision & Robotics camera and coordinate conventions * Video Input and Output - * Extensive video input/output wrappers for ordinary and machine-vision cameras and media formats - * Flexible filter interface for easily post-processing video channels and formats, etc. + * Extensive video input/output wrappers for ordinary and machine-vision + cameras and media formats + * Flexible filter interface for easily post-processing video channels and + formats, etc. * Tweak Variables - * There are 101 widgeting libraries and several 'tweak' var libraries - Pangolin offers another implementation with a few pros and cons + * There are 101 widgeting libraries and several 'tweak' var libraries - + Pangolin offers another implementation with a few pros and cons * One-line definitions and extensible types * Drop-down Console * Extensible for different shells, but currently supports Python live console * Easy access to introspect tweak variables - - -## Code ## +## Code Find the latest version on [Github](http://github.com/stevenlovegrove/Pangolin): @@ -37,11 +42,14 @@ Find the latest version on [Github](http://github.com/stevenlovegrove/Pangolin): git clone --recursive https://github.com/stevenlovegrove/Pangolin.git ``` +## Dependencies - -## Dependencies ## - -*Pangolin* is split into a few *components* so you can include just what you need. Most dependencies are *optional* so you can pick and mix for your needs. Rather than enforcing a particular package manager, you can use a simple [script](https://github.com/stevenlovegrove/Pangolin/blob/master/scripts/install_prerequisites.sh) to generate a list of (**required**, **recommended** or **all**) packages for installation for that manager (e.g. apt, port, brew, dnf, vcpkg): +*Pangolin* is split into a few *components* so you can include just what you +need. Most dependencies are *optional* so you can pick and mix for your needs. +Rather than enforcing a particular package manager, you can use a simple +[script](https://github.com/stevenlovegrove/Pangolin/blob/master/scripts/install_prerequisites.sh) +to generate a list of (**required**, **recommended** or **all**) packages for +installation for that manager (e.g. apt, port, brew, dnf, vcpkg): ```bash # See what package manager and packages are recommended @@ -59,14 +67,16 @@ You'll see the dependencies are generally * Video and Image loading (DC1394, ffmpeg, jpeg, png, ...) * Wrappers / Cross Compilers (Python3, pybind, Emscripten, ...) -Pangolin does it's best to build something with what it gets, so dependencies which are not found will be silently ignored. If you need a particular feature, check the output of the `cmake ..` stage and look for the *Found and Enabled* lines. - +Pangolin does it's best to build something with what it gets, so dependencies +which are not found will be silently ignored. If you need a particular feature, +check the output of the `cmake ..` stage and look for the *Found and Enabled* +lines. +## Building -## Building ## - -Pangolin uses the CMake portable pre-build tool. To checkout and build pangolin in the -directory 'build', execute the following at a shell (or the equivalent using a GUI): +Pangolin uses the CMake portable pre-build tool. To checkout and build pangolin +in the directory 'build', execute the following at a shell (or the equivalent +using a GUI): ```bash # Get Pangolin @@ -75,6 +85,7 @@ git clone --recursive https://github.com/stevenlovegrove/Pangolin.git cd Pangolin # Install dependencies (as described above, or your preferred method) +./scripts/install_prerequisites.sh -u ./scripts/install_prerequisites.sh recommended # Configure and build @@ -92,67 +103,116 @@ cmake --build build -t pypangolin_pip_install ctest ``` -![Master Build](https://github.com/stevenlovegrove/pangolin/actions/workflows/build.yml/badge.svg?branch=master) p.s. The *master* branch is a development branch. Choose a [stable tag](https://github.com/stevenlovegrove/Pangolin/tags) if you prefer. - +![Master +Build](https://github.com/stevenlovegrove/pangolin/actions/workflows/build.yml/badge.svg?branch=master) +p.s. The *master* branch is a development branch. Choose a [stable +tag](https://github.com/stevenlovegrove/Pangolin/tags) if you prefer. +### On Windows -#### On Windows - - I'd recommend building natively with the [Build Tools for Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) toolchain (and not mingw or WSL etc which is unsupported). I recommend [gitbash](https://git-scm.com/downloads) for executing the bash snippets on this page and cloning Pangolin. You can work from within their provided console or the fancy new [Windows Terminal](https://devblogs.microsoft.com/commandline/introducing-windows-terminal/) which is a huge improvement to the developer experience on Windows. + I'd recommend building natively with the [Build Tools for Visual Studio + 2019](https://visualstudio.microsoft.com/downloads/) toolchain (and not mingw + or WSL etc which is unsupported). I recommend + [gitbash](https://git-scm.com/downloads) for executing the bash snippets on + this page and cloning Pangolin. You can work from within their provided + console or the fancy new [Windows + Terminal](https://devblogs.microsoft.com/commandline/introducing-windows-terminal/) + which is a huge improvement to the developer experience on Windows. #### With Python -You have to be careful about what python version Pangolin has found and is attempting to link against. It will tell you during the `cmake ..` step and you can change it by explicitly telling it the python executable with `cmake -DPYTHON_EXECUTABLE=/path/to/python ..`or ``cmake -DPYTHON_EXECUTABLE=`which python3` `` to use the python accessed through the `python3` alias. +You have to be careful about what python version Pangolin has found and is +attempting to link against. It will tell you during the `cmake ..` step and you +can change it by explicitly telling it the python executable with `cmake +-DPYTHON_EXECUTABLE=/path/to/python ..`or ``cmake -DPYTHON_EXECUTABLE=`which +python3` `` to use the python accessed through the `python3` alias. -If python is found, the pypangolin module will be built with the default `all` target. A Python wheel can be built manually using the `pypangolin_wheel` target, and the wheel can be installed / uninstalled with `pypangolin_pip_install` and `pypangolin_pip_uninstall` targets. +If python is found, the pypangolin module will be built with the default `all` +target. A Python wheel can be built manually using the `pypangolin_wheel` +target, and the wheel can be installed / uninstalled with +`pypangolin_pip_install` and `pypangolin_pip_uninstall` targets. -**NOTE** The python wheel and install targets are only currently working on MacOS and Linux. On Windows, you're out of luck right now. Help appreciated! +**NOTE** The python wheel and install targets are only currently working on +MacOS and Linux. On Windows, you're out of luck right now. Help appreciated! #### On the Web See [**Emscripten (Compile for web)**](#emscripten-compile-for-web) below. - ## Examples -Pangolin is mostly documented through it's simple examples which you can find in the [*examples*](https://github.com/stevenlovegrove/Pangolin/tree/master/examples) folder and [*examples/PythonExamples*](https://github.com/stevenlovegrove/Pangolin/tree/master/examples/PythonExamples) for python versions. - -Browse some [**online**](https://stevenlovegrove.github.io/Pangolin/examples) and even run them in your browser, such as [**SimplePlot**](https://stevenlovegrove.github.io/Pangolin/emscripten/examples/SimplePlot), [**SimpleDisplay**](https://stevenlovegrove.github.io/Pangolin/emscripten/examples/SimpleDisplay/) and [**SimpleMultiDisplay**](https://stevenlovegrove.github.io/Pangolin/emscripten/examples/SimpleMultiDisplay/). - -## Issues ## - -Please visit [Github Issues](https://github.com/stevenlovegrove/Pangolin/issues) to view and report problems with Pangolin. Issues and pull requests should be raised against the master branch which contains the current development version. - -Please note; most Pangolin dependencies are optional - to disable a dependency which may be causing trouble on your machine, set the BUILD_PANGOLIN_(option) variable to false with a cmake configuration tool (e.g. ccmake or cmake-gui). - -#### Common Runtime Problems - -Framebuffer with requested attributes not available: You're building against an old or unaccelerated OpenGL version. Either your graphics drivers are not correctly installed or you are on an unusual platform (such as within Docker, in a VM, working over an X forwarding SSH session) which has limited graphics acceleration. For the former case, you need to make sure your system is using appropriate drivers (you can test glxgears / glxinfo on linux for instance). There isn't much you can do about the latter except changing your setup (e.g. finding a VM which can better accelerate your graphics, or perhaps using the [nvidia-docker](https://github.com/NVIDIA/nvidia-docker) wrapper around docker to correctly pass through the graphics driver) +Pangolin is mostly documented through it's simple examples which you can find +in the +[*examples*](https://github.com/stevenlovegrove/Pangolin/tree/master/examples) +folder and +[*examples/PythonExamples*](https://github.com/stevenlovegrove/Pangolin/tree/master/examples/PythonExamples) +for python versions. + +Browse some [**online**](https://stevenlovegrove.github.io/Pangolin/examples) +and even run them in your browser, such as +[**SimplePlot**](https://stevenlovegrove.github.io/Pangolin/emscripten/examples/SimplePlot), +[**SimpleDisplay**](https://stevenlovegrove.github.io/Pangolin/emscripten/examples/SimpleDisplay/) +and +[**SimpleMultiDisplay**](https://stevenlovegrove.github.io/Pangolin/emscripten/examples/SimpleMultiDisplay/). + +## Issues + +Please visit [Github +Issues](https://github.com/stevenlovegrove/Pangolin/issues) to view and report +problems with Pangolin. Issues and pull requests should be raised against the +master branch which contains the current development version. + +Please note; most Pangolin dependencies are optional - to disable a dependency +which may be causing trouble on your machine, set the BUILD_PANGOLIN_(option) +variable to false with a cmake configuration tool (e.g. ccmake or cmake-gui). + +### Common Runtime Problems + +*Framebuffer with requested attributes not available*: You're building +against an old or unaccelerated OpenGL version. Either your graphics drivers +are not correctly installed or you are on an unusual platform (such as within +Docker, in a VM, working over an X forwarding SSH session) which has limited +graphics acceleration. For the former case, you need to make sure your system +is using appropriate drivers (you can test glxgears / glxinfo on linux for +instance). There isn't much you can do about the latter except changing your +setup (e.g. finding a VM which can better accelerate your graphics, or perhaps +using the [nvidia-docker](https://github.com/NVIDIA/nvidia-docker) wrapper +around docker to correctly pass through the graphics driver) #### Common Python Problems -error: unknown target 'pypangolin_wheels' : cmake didn't find your python. Go back and adjust your cmake variables (such as the tip above) until you see something like "Selected Python: '/opt/local/bin/python3.9'" in the output. - -ModuleNotFoundError: No module named 'pypangolin': Did you install the wheel (see the bash comment under build)? Are you running using the same Python as Pangolin found during the `cmake ..` step? - - - -## Contributions and Continuous Integration ## +*error: unknown target 'pypangolin_wheels'* : cmake didn't find your python. Go +back and adjust your cmake variables (such as the tip above) until you see +something like "Selected Python: '/opt/local/bin/python3.9'" in the output. -For CI, Pangolin uses [Github Actions](https://github.com/stevenlovegrove/Pangolin/actions) for Windows, MacOS, Linux and Emscripten (Web). +*ModuleNotFoundError: No module named 'pypangolin'*: Did you install the wheel +(see the bash comment under build)? Are you running using the same Python as +Pangolin found during the `cmake ..` step? -To contribute to Pangolin, I would appreciate pull requests against the master branch. If you raise an issue, please include your environment (compiler, operating system, etc). +## Contributions and Continuous Integration +For CI, Pangolin uses [Github +Actions](https://github.com/stevenlovegrove/Pangolin/actions) for Windows, +MacOS, Linux and Emscripten (Web). +To contribute to Pangolin, I would appreciate pull requests against the master +branch. If you raise an issue, please include your environment (compiler, +operating system, etc). ## Extensibility & Factories -Pangolin uses an extensible factory mechanism for modularising video drivers, windowing backends and console interpreters. Concrete instances are instantiated from a particular factory using a URI string which identifies which factory to use and what parameters it should use. As strings, URI's are a useful mechanism for providing and validating configuration from an end user. The URI form is: +Pangolin uses an extensible factory mechanism for modularising video drivers, +windowing backends and console interpreters. Concrete instances are +instantiated from a particular factory using a URI string which identifies +which factory to use and what parameters it should use. As strings, URI's are a +useful mechanism for providing and validating configuration from an end user. +The URI form is: `module_name:[option1=value1,option2=value2,...]//module_resource_to_open`. -#### Video URI's +### Video URI's -The *VideoViewer* tool takes these URI's directly in order to specify what images or video to load and show: +The *VideoViewer* tool takes these URI's directly in order to specify what +images or video to load and show: ```bash VideoViewer test:// @@ -160,34 +220,40 @@ VideoViewer uvc:[size=640x480]///dev/video0 VideoViewer flip://debayer:[tile=rggb,method=downsample]//file://~/somefile.pango ``` -Notice that for video, some modules support chaining to construct a simple filter graph. +Notice that for video, some modules support chaining to construct a simple +filter graph. #### Window URI's -Windowing in Pangolin is also backed by a factory. When an application calls CreateWindowAndBind() or similar, the default:// URI is specified. This can be overriden to use different windowing options by setting the`PANGOLIN_WINDOW_URI` environment variable. e.g. +Windowing in Pangolin is also backed by a factory. When an application calls +CreateWindowAndBind() or similar, the default:// URI is specified. This can be +overriden to use different windowing options by setting +the`PANGOLIN_WINDOW_URI` environment variable. e.g. +## Use the X11 Window Driver and override the default double buffered option -```bash -# Use the X11 Window Driver and override the default double buffered option PANGOLIN_WINDOW_URI="x11:[double_buffered=false]//" ./some_pangolin_app -# Create a 'virtual' window using a framebuffer +## Create a 'virtual' window using a framebuffer + PANGOLIN_WINDOW_URI="headless://" ./another_pangolin_app -``` -Some window parameters that may be interesting to override are `DISPLAYNAME`, `DOUBLEBUFFER`, `SAMPLE_BUFFERS`, `SAMPLES`, `HIGHRES`. Window modules currently include `x11`, `winapi`, `cocoa`. +Some window parameters that may be interesting to override are `DISPLAYNAME`, +`DOUBLEBUFFER`, `SAMPLE_BUFFERS`, `SAMPLES`, `HIGHRES`. Window modules +currently include `x11`, `winapi`, `cocoa`. -#### Fonts +### Fonts -Additionally, there are a couple of special parameters that can be passed through the `PANGOLIN_WINDOW_URI` environment variable to change the default font or adjust the default font size: +Additionally, there are a couple of special parameters that can be passed +through the `PANGOLIN_WINDOW_URI` environment variable to change the default +font or adjust the default font size: -```bash PANGOLIN_WINDOW_URI="default:[default_font_size=20]//" ./some_pangolin_app PANGOLIN_WINDOW_URI="default:[default_font=my_awesome_font.ttf,default_font_size=20]//" ./some_pangolin_app -``` -To use Pangolin in your applications whilst being conscientious of changing fonts, you can query how long fonts or text are with: +To use Pangolin in your applications whilst being conscientious of changing +fonts, you can query how long fonts or text are with: ```C++ #include @@ -201,11 +267,10 @@ int func() } ``` +## Emscripten (Compile for web) - -## Emscripten (Compile for web) ## - -Emscripten is a neat c++ compiler which can output javascript executable code. That's right, your Pangolin programs can run on the web, too! +Emscripten is a neat c++ compiler which can output javascript executable code. +That's right, your Pangolin programs can run on the web, too! Follow Emscriptens instructions to install the SDK (summarized below): @@ -215,7 +280,9 @@ git clone https://github.com/emscripten-core/emsdk.git cd emsdk && ./emsdk install latest && ./emsdk activate latest ``` -To build Pangolin with the Emscripten toolchain, create a new build directory, make sure Emscripten is on your PATH, and use the `emconfigure` utility to run CMake with the custom toolchain settings: +To build Pangolin with the Emscripten toolchain, create a new build directory, +make sure Emscripten is on your PATH, and use the `emconfigure` utility to run +CMake with the custom toolchain settings: ```bash cd ~/code/Pangolin @@ -224,9 +291,12 @@ source ~/tools/emsdk/emsdk_env.sh emcmake cmake .. ``` -## Acknowledgements ## +## Acknowledgements -I'd like to thank the growing number of kind contributors to Pangolin for helping to make it more stable and feature rich. Many features of Pangolin have been influenced by other projects such as GFlags, GLConsole, and libcvd in particular. I'd also like to thank the FOSS projects on which Pangolin depends. +I'd like to thank the growing number of kind contributors to Pangolin for +helping to make it more stable and feature rich. Many features of Pangolin have +been influenced by other projects such as GFlags, GLConsole, and libcvd in +particular. I'd also like to thank the FOSS projects on which Pangolin depends. For a summary of those who have made code contributions, execute: diff --git a/scripts/install_prerequisites.sh b/scripts/install_prerequisites.sh index 3d101b36d..bdedc1e82 100755 --- a/scripts/install_prerequisites.sh +++ b/scripts/install_prerequisites.sh @@ -39,8 +39,9 @@ while (( "$#" )); do shift ;; -m|--package-manager) - if [ -n "$2" ] && [ ${2:0:1} != "-" ]; then - MANAGERS=($2) + if [ -n "$2" ] && [ "${2:0:1}" != "-" ]; then + # MANAGERS=($2) + mapfile -t MANAGERS <<< "$2" shift 2 else echo "Error: Argument for $1 is missing" >&2 @@ -58,7 +59,7 @@ while (( "$#" )); do echo " (required|recommended|all) the set of dependencies to select." exit 0 ;; - -*|--*=) # unsupported flags + -*=) # unsupported flags echo "Error: Unsupported flag $1" >&2 exit 1 ;; @@ -94,9 +95,9 @@ esac # Find an available package manager from the preferred list -for m in ${MANAGERS[@]} +for m in "${MANAGERS[@]}" do - if [ -x "$(command -v $m)" ]; then + if [ -x "$(command -v "$m")" ]; then MANAGER="$m" break fi @@ -113,8 +114,8 @@ if ((VERBOSE > 0)); then echo "Using \"$MANAGER\" package manager (select anothe # Setup prereq commands and packages. if [[ "$MANAGER" == "apt" ]]; then SUDO="sudo" - PKGS_UPDATE="apt update" - PKGS_OPTIONS+=(install --no-install-suggests --no-install-recommends) + PKGS_UPDATE="apt update -y" + PKGS_OPTIONS+=(install --no-install-suggests --no-install-recommends -y) if ((DRYRUN > 0)); then PKGS_OPTIONS+=(--dry-run); fi PKGS_REQUIRED+=(libgl1-mesa-dev libwayland-dev libxkbcommon-dev wayland-protocols libegl1-mesa-dev) PKGS_REQUIRED+=(libc++-dev libglew-dev libeigen3-dev cmake g++ ninja-build) @@ -164,7 +165,7 @@ fi if ((REQUIRED_RECOMMENDED_ALL < 2)); then PKGS_ALL=(); fi if ((REQUIRED_RECOMMENDED_ALL < 1)); then PKGS_RECOMMENDED=(); fi -PACKAGES=( "${PKGS_REQUIRED[*]}" "${PKGS_RECOMMENDED[*]}" "${PKGS_ALL[*]}" ) +PACKAGES=( "${PKGS_REQUIRED[@]}" "${PKGS_RECOMMENDED[@]}" "${PKGS_ALL[@]}" ) if ((LIST > 0)); then echo "${PACKAGES[*]}" @@ -173,10 +174,11 @@ fi if ((UPDATE > 0)); then if ((VERBOSE > 0)); then echo "Requesting \"$MANAGER\" package update."; fi + # shellcheck disable=SC2086 $SUDO $PKGS_UPDATE fi if ((VERBOSE > 0)); then echo "Requesting install of: ${PACKAGES[*]}"; fi # Install -$SUDO $MANAGER ${PKGS_OPTIONS[*]} ${PACKAGES[*]} +$SUDO "$MANAGER" "${PKGS_OPTIONS[@]}" "${PACKAGES[@]}"