{"id":18359758,"url":"https://github.com/snototter/vitocpp","last_synced_at":"2025-04-10T03:26:54.835Z","repository":{"id":106915372,"uuid":"233374292","full_name":"snototter/vitocpp","owner":"snototter","description":"C++/Python 3 utilities for common vision tasks, e.g. streaming, visualization or image manipulation.","archived":false,"fork":false,"pushed_at":"2024-03-21T16:46:00.000Z","size":9733,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-15T18:51:37.394Z","etag":null,"topics":["computer-vision-tools","data-visualization","image-processing","utility-library"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/snototter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-12T10:26:09.000Z","updated_at":"2024-10-19T18:56:08.000Z","dependencies_parsed_at":"2024-11-05T22:29:44.510Z","dependency_job_id":"61682a4c-e6f1-4dd1-90ee-c213760a10fd","html_url":"https://github.com/snototter/vitocpp","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snototter%2Fvitocpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snototter%2Fvitocpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snototter%2Fvitocpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snototter%2Fvitocpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/snototter","download_url":"https://codeload.github.com/snototter/vitocpp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248150084,"owners_count":21055854,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["computer-vision-tools","data-visualization","image-processing","utility-library"],"created_at":"2024-11-05T22:24:24.535Z","updated_at":"2025-04-10T03:26:54.801Z","avatar_url":"https://github.com/snototter.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vitocpp/vcp\nC++/Python 3 utilities for common vision tasks, _e.g._ streaming, visualization or image manipulation.\n\n\u003cb\u003eNote:\u003c/b\u003e As of 01/2020 this repository is \u003cb\u003eWIP\u003c/b\u003e, I'm rewriting my utilities (especially simplifying the streaming module) over the next couple of months.\n\n```\nCurrent status (12/2020):\ncloc --exclude-dir=.venv3,build,cmake,third-party,gen,doc,generated --exclude-lang=make,XML .\n-------------------------------------------------------------------------------\nLanguage                     files          blank        comment           code\n-------------------------------------------------------------------------------\nC++                             64           4305           2306          23566\nC/C++ Header                    56           1600           1827           4435\nPython                          25            841           1030           3172\nCMake                           12            270            248           1179\nMarkdown                         3             97              0            389\nBourne Shell                     3             41             77            251\n-------------------------------------------------------------------------------\nSUM:                           163           7154           5488          32992\n-------------------------------------------------------------------------------\n```\n\n## What is it good for?\nSome of `vcp`'s highlights:\n* \u003cb\u003eBest effort multiple device streaming\u003c/b\u003e with the `vcp::best` module. Useful for quick camera tests and whenever (guaranteed) synchronisation isn't crucial. The goal of this module is to stream from multiple devices simultaneously, without having the ROS overhead. A simple libconfig++-style configuration file allows you to process all streams both in C++ and python. For more details, see the [separate BESt.md documentation](BESt.md).\n* \u003cb\u003eBackground subtraction\u003c/b\u003e is provided by the `vcp::bgm` module, for example:\n\n  ![Background Subtraction](https://github.com/snototter/vitocpp/raw/master/doc/example-bgm.png)\n* \u003cb\u003eVisualization utilities\u003c/b\u003e are provided by the `vcp::imvis` module, for example:\n\n  ![Visualization Example](https://github.com/snototter/vitocpp/raw/master/doc/example-imvis.png)\n* \u003cb\u003ePseudocoloring\u003c/b\u003e for data visualization/analysis is also provided by the `vcp::imvis` module.\n  Back when I started working on this library, OpenCV didn't provide pseudocoloring capabilities. The `vcp::imvis` module allows visualization via common color maps (you might remember these from such frameworks as MATLAB, matplotlib, and whatnot).\n\n  ![Pseudocoloring Example](https://github.com/snototter/vitocpp/raw/master/doc/example-pseudocolor.png)\n* \u003cb\u003eMath\u003c/b\u003e utilities - besides enabling most of the fancy visualizations within `vcp::imvis`, you can also do basic geometry tasks with the `vcp::math` module (_e.g._ computing tangents of circles, line (segment) intersection, and quite a lot more).\n\n  ![Geometry Example](https://github.com/snototter/vitocpp/raw/master/doc/example-geometry.png)\n* \u003cb\u003eC++\u003c/b\u003e utilities - for basic file/path and string manipulation, sorting, and more (if you want to avoid heavier dependencies, such as Boost).\n\n\n## Repository Contents\n* `./build-scripts` - shell scripts to prepare the build system, build the libraries, etc.\n* `./cmake` - CMake utilities (incl. custom `Find\u003cpackage\u003e.cmake` scripts).\n* `./examples` - example usage of these utilities.\n* `./src` - source code for all C++ modules and python bindings.\n* `./third-party` - third party dependencies (which are not part of default system packages).\n\n\n## Installation\n* If you want to build the C++ library and Python3 bindings, simply run `./build-scripts/build-ubuntu-18.04.sh`, this will:\n  * Check and ask you to install missing system packages.\n  * Configure the build (depending on which optional packages you installed, _e.g._ `libk4a` to stream from Azure Kinect).\n  * Build the C++ `vcp` libraries and corresponding Python3 bindings.\n  * Build the example applications and prepare the virtual environment for Python demos.\n* If you prefer to do it on your own, crank up CMake:\n    ```bash\n    $ cd \u003cVCP_ROOT_DIR\u003e\n    $ mkdir build \u0026\u0026 cd build\n    $ cmake -DVCP_BUILD_PYTHON=ON ..\n    $ make -j install\n    ```\n* The default install location (for `make install`) of `vcp` is `\u003cVCP_ROOT_DIR\u003e/gen`.\n  * Public C++ headers are inside `\u003cVCP_ROOT_DIR\u003e/gen/include`.\n  * `vcp` library files are inside `\u003cVCP_ROOT_DIR\u003e/gen/lib`.\n  * The Python3 package is located at `\u003cVCP_ROOT_DIR\u003e/gen/vcp`.\n\n\n## Tools\nThis repository comes with a few \"tools\", _i.e._ standalone applications that go beyond simple demos/examples.\nCurrently (as of Jan/2020), there are only python applications available, which you can find at `\u003cVCP_ROOT_DIR\u003e/examples/python3/tools`.\n* Set up the \u003cb\u003evirtual environment\u003c/b\u003e. If you didn't use the `./build-scripts/build-X.sh` script to prepare the library, you should run:\n  ```bash\n  $ cd \u003cVCP_ROOT_DIR\u003e/examples/python3\n  $ ./prepare_environment_py3.sh\n  $ source .venv3/bin/activate\n  $ cd tools\n  ```\n* \u003cb\u003eExtrinsic multi-camera calibration\u003c/b\u003e. For partially overlapping multi-camera setups, you can use the `calibrate-extrinsics.py` UI to estimate the camera poses using [AprilTags](https://april.eecs.umich.edu/software/apriltag).\u003cbr/\u003e\n  For example, calibrating two Azure Kinects via `python tools/calibrate-extrinsics.py ../data/data-best/kinects.cfg 225 --max-depth 10000 --max-ir 255` looks like this (depth measurements are visualized as surface normals, reflectivity of the infrared stream is shown as heatmap, TODO explain (?)):\n\n  ![Camera Extrinsics Example](https://github.com/snototter/vitocpp/raw/master/doc/example-calib-extrinsics.jpg)\n* \u003cb\u003e3D image plots\u003c/b\u003e. Plot a single image (`plot-image.py`) or an image sequence (`plot-image-sequence.py`) by interactively adjusting the camera extrinsics.\n\n  ![Image Sequence Example](https://github.com/snototter/vitocpp/raw/master/doc/example-render-img-sequence.png)\n* \u003cb\u003eImage abstraction:\u003c/b\u003e cartoonification, pixelation, etc. can be experimented with via `cartoonify.py`.\n\n\n## Examples\nBesides the more complex `tools`, there are also simple demos showcasing the library capabilities.\n### C++\n* The C++ applications at `\u003cVCP_ROOT_DIR\u003e/examples/cpp` demonstrate how you can use `vcp` from your own CMake projects. After building the vcp library, building these examples is as easy as:\n  ```bash\n  $ cd \u003cVCP_ROOT_DIR\u003e/examples\n  $ mkdir build \u0026\u0026 cd build\n  $ cmake ..\n  $ make -j\n  ```\n* Highly recommended examples (best/well documented, useful functionality):\n  * `best_demo`\n\n\n### Python\n* You can find Python3 examples for all modules at `\u003cVCP_ROOT_DIR\u003e/examples/python3`.\n  ```bash\n  $ cd \u003cVCP_ROOT_DIR\u003e/examples/python3\n  # Set up the virtual environment\n  $ ./prepare_environment_py3.sh\n  $ source .venv3/bin/activate\n  $ python imvis_demo.py\n  ```\n* Highly recommended examples (best/well documented, useful functionality):\n  * `bgm_demo.py` - Usage example of the background subtraction module.\n  * `geometry_demoy.py` - Usage example of the `math2d` and `math3d` modules.\n  * `imutils_demo.py` - Usage example of the `imutils` (image manipulation) module.\n  * `imvis_demo.py` - Usage example for visualization utilities within the `imvis` module.\n\n## Tests\nWhile all of vcp has been tested \"in-the-wild\", unit tests are rather sparse, unfortunately.\nEspecially for the \"best effort streaming\" module, tests become quite difficult to automate (threading + the need for the specific hardware connected to the test server).\n\n### C++\n* Testing the C++ core library requires `gtest`:\n  ```bash\n  $ sudo apt-get install libgtest-dev\n\n  # This package does not provide binaries, so look for the installed\n  # source at /usr/src. It should be (Ubuntu 18.04) at /usr/src/googletest.\n  $ cd /usr/src/googletest\n  $ sudo cmake CMakeLists.txt\n  $ sudo make\n\n  # Copy or symlink googlemock/gtest/libgtest.a \n  # and googlemock/gtest/libgtest_main.a to your /usr/lib folder\n  $ sudo cp googlemock/gtest/*.a /usr/lib\n  ```\n* Now `vcp` can be tested:\n  ```bash\n  $ cd \u003cVCP_ROOT_DIR\u003e/build\n\n  # Enable tests and link the gtest libraries\n  $ cmake -DVCP_BUILD_TESTS=ON ..\n  $ make test \n\n  # Or, if you prefer:\n  $ ctest -V\n  ```\n\n### Python\n* You can find the Python3 tests at `\u003cVCP_ROOT_DIR\u003e/examples/python3`, _i.e._ all files following the pattern `test_*.py`.\n* Testing requires `pytest`:\n  ```bash\n  $ cd \u003cVCP_ROOT_DIR\u003e/examples/python3\n  $ source .venv3/bin/activate\n  $ pip install pytest\n  $ pytest\n  ```\n\n## TODOs\n* [ ] Additional tools/examples\n  * [ ] C++ Viewer (resize streams and use liveview)\n  * [ ] Qt Viewer\n  * [ ] Capturing tool\n* [ ] Camera calibration (nice-to-have)\n  * [ ] Intrinsic calibration\n  * [x] Extrinsic calibration\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnototter%2Fvitocpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsnototter%2Fvitocpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnototter%2Fvitocpp/lists"}