vortex-oct 0.5.1

A library for building real-time OCT engines in C++ or Python.

vortex is a high-performance C++ library with Python bindings for building real-time OCT engines. It provides:

• modular components out of which an OCT engine is built

• a flexible OCT engine that accommodates most use cases

• extensive Python bindings that interoperate with NumPy and CuPy

vortex is designed from the ground up to:

• promote reproducibility in data acquisition and processing

• guarantee synchronization between data streams

• support on-the-fly changes for interactive use cases

• integrate cleanly with user interfaces

• facilitate rapid prototyping with high-level abstractions and sane defaults

• minimize restrictions and assumptions

Documentation

Documentation is available for the latest release and for specific versions.

Getting Started

Python

For an official release, install with pip, where the suffix -cudaXXY denotes a version for CUDA XX.Y.

> pip install vortex-oct-cuda12x --index-url https://vortex-oct.dev/stable

$ pip3 install vortex-oct-cuda12x --index-url https://vortex-oct.dev/stable

To test a development build, use https://vortex-oct.dev/develop as the index URL for pip. Visit the online documentation for more details.

C++

The build procedure varies based on the use-case for vortex. Visit the online documentation for full details.

As an Application Dependency

Most users will want to include vortex as a dependency in a larger application. See the vortex application example for a walkthrough.

As a Library for Development

To compile vortex directly for development or customization purposes, follow the steps below.

1. Install and/or setup vcpkg for vortex’s C++ dependencies. Avoiding using shallow clones of vcpkg (e.g., with --depth) as this can cause problems when installing packages with the specific package versions specified in vortex’s manifest file.

   > git clone https://github.com/microsoft/vcpkg.git
   > ./vcpkg/bootstrap-vcpkg.bat -disableMetrics

   $ git clone https://github.com/microsoft/vcpkg.git
   $ ./vcpkg/bootstrap-vcpkg.sh -disableMetrics

2. Export the path to vcpkg’s build system for CMake. Use an absolute path to avoid unexpected build failures in the future.

   > $env:CMAKE_TOOLCHAIN_FILE=C:/.../vcpkg/scripts/buildsystems/vcpkg.cmake

   $ export CMAKE_TOOLCHAIN_FILE="/.../vcpkg/scripts/buildsystems/vcpkg.cmake"

   Alternatively, set CMAKE_TOOLCHAIN_FILE as a cache variable as shown below.

3. Clone vortex.

   > git clone https://gitlab.com/vortex-oct/vortex.git

   $ git clone https://gitlab.com/vortex-oct/vortex.git

4. Edit the cache variables for the top-level CMake preset (base-x64) for building vortex in vortex/CMakePresets.json. Configure the vortex features to build using the VCPKG_MANIFEST_FEATURES cache variable. Also, you can define the CMAKE_TOOLCHAIN_FILE cache variable here rather than setting it as an environment variable above.

   "cacheVariables": {
     "CMAKE_INSTALL_PREFIX": "${sourceDir}/install/${presetName}"
     "CMAKE_TOOLCHAIN_FILE": "/.../vcpkg/scripts/buildsystems/vcpkg.cmake",
     "VCPKG_MANIFEST_FEATURES": "reflexxes;cuda;python;teledyne;alazar;alazar-dac;daqmx;asio;backward"
   },

   Find a complete list of feature names using vcpkg search vortex --featurepackages or in the vortex port manifest. See the documentation for additional build options.

5. Choose and customize the build preset for your system. vortex provides presets for building with Clang-CL on Windows and clang or gcc on Linux in debug, unoptimized, or release modes.

   • Debug mode builds with debug versions of all libraries and includes symbols. This mode is generally not compatible with Python support since you will need to have a debug version of NumPy installed.

   • Unoptimized mode builds with release versions of all libraries but turns debug symbols on and optimizations off for vortex. This is the recommended mode for debugging vortex if Python features are enabled.

   • Release mode builds with release versions of all libraries and turns on all optimizations for vortex. Debug symbols are included for vortex if not optimized out.

   Edit the presets with names that start with base- so that changes propagate to debug, unoptimized, and release builds.

   "name": "base-clang-win-x64",
   "inherits": "base-x64",
   "generator": "Ninja",
   "environment": {
       "CC": "clang-cl",
       "CXX": "clang-cl",
       "CXXFLAGS": "-m64 -fdiagnostics-absolute-paths -fcolor-diagnostics -Wno-unused-command-line-argument /Zi",
       "CUDAFLAGS": "--expt-relaxed-constexpr -lineinfo -Xcudafe --diag_suppress=base_class_has_different_dll_interface -diag-suppress 27 -Wno-deprecated-gpu-targets -Xcompiler=/wd4984 --debug",
       "LDFLAGS": "/debug"
   },
   "cacheVariables": {
       "CMAKE_CUDA_STANDARD": "17"
   },

6. If you plan to build with Python support, install the Python requirements first.

   > pip install -r vortex/requirements.txt

   $ pip3 install -r vortex/requirements.txt

7. Build vortex using your chosen environment.

   • For Visual Studio, open the root folder for vortex as a CMake project. Select the correct preset from the configuration dropdown in the toolbar and then build.

   • For Visual Studio Code, open the root folder for vortex. Make sure to install the C++ and CMake extensions. Select the correct configure preset using the CMake extension and then build.

   • For CMake from the command line, configure using the selected preset.

     > cmake -S vortex -B vortex/build --preset clang-win-x64-release
     > cmake --build vortex/build

     $ cmake -S vortex -B vortex/build --preset gcc-linux-x64-release
     $ cmake --build vortex/build

   If you edit the CMake preset, delete your CMake cache and reconfigure to ensure that the changes take effect.

License

vortex is released under the permissive BSD-3 license to support research and commercial use.