DOCSEARCHbyAlgolia
Submit Docs

dlib C++ Toolkit

repository·master·Indexed 12 days ago

https://github.com/davisking/dlib

A modern C++ toolkit containing machine learning algorithms and tools for creating complex software to solve real-world problems. It provides both C++ and Python interfaces and includes support for AVX instructions and integration via CMake or vcpkg.

Tokens
7.7K
Snippets
30
Records
48
Agent score
92%

What's inside dlib

  1. What is pybind11

    master
    pybind11 is a lightweight, header-only C++ library designed to facilitate seamless interoperability between C++ and Python. It is primarily used to create Python bindings for existing C++ code by using compile-time introspection to infer type information, which minimizes the boilerplate code typically required for extension modules. Unlike Boost.Python, pybind11 is a compact, self-contained implementation that leverages C++11 features (such as tuples, lambda functions, and variadic templates) and does not require linking against large external libraries.

  2. Core C++ features supported by pybind11

    master

    pybind11 can map a wide range of C++ features directly to Python, including:

    • Functions: Support for functions accepting/returning custom data structures (via value, reference, or pointer), overloaded functions, and instance/static methods.
    • Classes & Inheritance: Single and multiple inheritance, instance and static attributes, and C++ classes with virtual (or pure virtual) methods that can be extended in Python.
    • Data Structures: STL data structures, enumerations, and iterators/ranges.
    • Memory Management: Smart pointers (e.g., std::shared_ptr) with reference counting and internal references with correct reference counting.
    • Error Handling: Arbitrary exception types.
    • Advanced Features: Callbacks, custom operators, and integrated NumPy support (Note: NumPy 2 requires pybind11 2.12+).

  3. Advanced pybind11 capabilities and 'Goodies'

    master

    Beyond basic binding, pybind11 offers several advanced features for high-performance and ergonomic integration:

    • NumPy Integration:
      • Supports fast conversion between C++ matrix classes (like Eigen) and NumPy via Python's buffer protocols.
      • Can automatically vectorize functions to apply them transparently to NumPy array arguments.
    • Performance:
      • Uses C++11 move constructors and move assignment operators for efficient data transfer.
      • Uses constexpr to precompute function signatures at compile time, resulting in smaller binaries.
    • Python Ergonomics:
      • Supports Python's slice-based access and assignment.
      • Allows binding C++11 lambda functions with captured variables (the capture data is stored in the Python function object).
      • Enables C++ types to be pickled/unpickled like regular Python objects.
    • Deployment: Everything is contained in a few header files; no additional libraries need to be linked.

  4. Install the htmlify utility

    master

    The htmlify utility is required for automating documentation generation. It is located in the tools/htmlify directory of the dlib repository. To install it, you must have cmake installed on your system.

    Follow these steps to build and install htmlify:

    1. Navigate to tools/htmlify.
    2. Create a build subdirectory.
    3. Enter the build directory.
    4. Run the CMake build process and install.
    cd tools/htmlify
mkdir build
cd build
cmake ..
make
sudo make install

  5. Improve dlib matrix visualization in Visual Studio using Natvis

    master

    You can improve the debugger experience in Visual Studio (versions 2012 and later) by using a Natvis file. This allows for much nicer and more readable visualization of dlib matrices during debugging sessions.

    To install the visualizer, copy the Natvis file into one of the following directories:

    1. User-specific directory: %USERPROFILE%\My Documents\Visual Studio [VERSION]\Visualizers (e.g., %USERPROFILE%\My Documents\Visual Studio 2015\Visualizers)
    2. System-wide directory: %VSINSTALLDIR%\Common7\Packages\Debugger\Visualizers
    # Example paths for installation:
# User-specific:
%USERPROFILE%\My Documents\Visual Studio 2015\Visualizers

# System-wide:
%VSINSTALLDIR%\Common7\Packages\Debugger\Visualizers

  6. Integration examples for pybind11

    master

    Depending on your build system, you can use the following examples to integrate pybind11 into your project:

    • Setuptools: For standard Python packaging.
    • Scikit-build: For a more modern approach to building Python extensions.
    • CMake: For projects using the CMake build system.
    <!-- Examples referenced in documentation -->
Setuptools example: https://github.com/pybind/python_example
Scikit-build example: https://github.com/pybind/scikit_build_example
CMake example: https://github.com/pybind/cmake_example

  7. Annotate images with imglab

    master

    The imglab tool is used to create training datasets for object detectors by annotating images with bounding boxes.

    1. Initialize a dataset

    To start a new annotation session, provide a name for your XML dataset file and the directory containing your images: ./imglab -c <dataset_name>.xml <images_directory>

    2. Labeling objects

    To open an existing dataset for labeling, run: ./imglab <dataset_name>.xml

    Controls:

    • Cycle Images: Use the Up and Down arrow keys.
    • Draw Bounding Boxes: Hold the Shift key, Left-click, and drag the mouse over the object.
    • Save: Go to the File menu, click Save, and then close the program. The boxes are written back to the XML file.

    3. Verify annotations

    You can verify that your work was saved by re-opening the dataset with the same command used in step 2.

    # Initialize a new dataset
./imglab -c mydataset.xml /tmp/images

# Open dataset to add/edit bounding boxes
./imglab mydataset.xml

  8. Regenerate HTML documentation

    master

    The makedocs script automates the process of pulling XML files from the dlib repository and transforming them into HTML using the stylesheet.xsl stylesheet.

    It generates two sets of documentation:

    • docs/web: HTML intended for web hosting (e.g., dlib.net).
    • docs/chm: HTML intended for offline use via the htmlhelp tool.

    Note: If using this for a different project, you will need to modify the makedocs script to point to your own files.

    ./docs/makedocs

  9. Regenerate the Table of Contents file

    master

    The Table of Contents.hhc file is automatically generated from toc.xml and htmlhelp_stylesheet.xsl. While you can edit the .hhc file directly, it is recommended to use the stylesheet to regenerate it to ensure consistency. If you have msxsl.exe installed, you can regenerate the file using the following command:

    msxsl toc.xml htmlhelp_stylesheet.xsl

  10. Run the dlib unit test suite

    master

    To compile and execute the dlib unit tests, follow these steps:

    1. Navigate to the dlib/test directory.
    2. Create a build directory and configure with CMake.
    3. Build the project in Release mode.
    4. Run the ./dtest executable with the --runall flag.

    Note for Windows users: Your compiler may place the test executable in a Release subfolder. If so, navigate into that folder before running the test command.

    cd dlib/test
mkdir build
cd build
cmake ..
cmake --build . --config Release
./dtest --runall
    cd dlib/test
mkdir build
cd build
cmake ..
cmake --build . --config Release
./dtest --runall

  11. Test your documentation environment

    master

    To verify that your system has all the necessary utilities installed to process the XML and XSLT documentation files, run the testenv_rel script located in the docs folder. This script will identify any missing dependencies required for the automation scripts to function.

    ./docs/testenv_rel

  12. Compile dlib C++ example programs

    master

    To build all the example programs included with dlib, navigate to the examples folder and use CMake to configure and build the project.

    Standard Build

    mkdir build; cd build; cmake .. ; cmake --build .

    Build with AVX Support

    If your CPU supports AVX instructions, you can enable them to improve performance:

    mkdir build; cd build; cmake .. -DUSE_AVX_INSTRUCTIONS=1; cmake --build .

    Visual Studio (64-bit) Configuration

    Visual Studio defaults to 32-bit mode. To ensure you are building in 64-bit mode, use the following CMake invocation:

    cmake .. -G "Visual Studio 14 2015 Win64" -T host=x64
    mkdir build; cd build; cmake .. ; cmake --build .