Warning

On Windows and Linux a NVIDIA graphics-card is required for hardware accelerated machine learning. On macOS (Apple Silicone), the Metal backend is used for hardware acceleration.

Installation

Installation

You can download the latest version of 🦖 using Miniforge (conda). To install 🦖, you need to have Miniforge installed on your system.

If you’re not familiar with conda or Miniforge, you can find more information on how to install them here. Miniforge is a minimal installer for conda, an open-source package manager that helps you create virtual environments and install software and libraries without installing them globally on your system [1]. We do not support Anaconda’s default channels, so please use Miniforge instead - do not use Anaconda or some stuff might not work as expected.

Open your Miniforge Prompt and run:

conda create -n track -c trexing trex

This will create a new conda environment called track with 🦖 installed. This could take a while, especially during conda’s ‘verifying transaction’ phase when it is installing additional packages via pip. Once it’s done, you can activate the environment using:

conda activate track

Then start 🦖 by typing:

trex

and pressing Enter.

If a window showing a friendly T-Rex appears, you’ve successfully installed the software and can proceed to the next section.

_images/welcome_screen.png

Figure 1 The TRex graphical user interface (GUI) showing the welcome screen.

If you have any issues with the installation, please refer to the (more detailed) installation guide.

Compile it yourself

There are two ways to get your own version of 🦖:

  • creating a local conda channel, and installing from there

  • running CMake/build manually with customized options

Both are obviously similar in result, but there are differences (the local channel is essentially a script for the manual procedure, with some caveats). For example, the conda build is limited to certain compiler and OS-SDK versions – which is something that you may want to change in order to enable certain optimizations. There is also no straight-forward way to add options like enabling Pylon support, for which you’d have to go the manual way described after the next section. We start out here by describing the more rigid (but more automated) way using conda, followed by a description of how to do everything manually.

Local conda channel

In order to get your own (local) conda channel, all you need to do is make sure you have conda installed, as well as the conda-build package. This is a package that allows you to make your own packages locally (use conda deactivate, until it says base on the left). Now you should probably create a new build environment first, keeping your base environment clean:

conda create -n build conda-build git python pip
conda activate build

Once this is done, you can clone the 🦖 repository and change your directory to the trex/conda folder in the downloaded repository:

git clone --recursive https://github.com/mooch443/trex
cd trex/conda

Note

Please make sure that you do not have a bareRepository = explicit value in your ~/.gitconfig file. This sometimes prevents proper git repository cloning using conda build!

Next, make sure you have Visual Studio 2022 installed, or Xcode on macOS. Linux should work out of the box, and if not you could try to install build-essential first to get g++ (at least version 11).

On MacOS you may need to adjust the SDK location as well as the deployment target. This can be done in the conda_build_config.yaml file - so these lines here need to be changed:

    SDKROOT:
  - /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX15.2.sdk # [osx]

CONDA_BUILD_SYSROOT:
  - /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX15.2.sdk # [osx]

Change them to the correct location within your filesystem. You may also have to adapt the MACOSX_DEPLOYMENT_TARGET and SDK paths in build.sh.

Finally, you can build the package using:

conda build .

Note

Note that if you want to enable/disable certain features (e.g. use a locally installed OpenCV library, enable the Pylon SDK, etc.) the build script (namely build.sh or bld.bat on Windows) is the place where you can do that. You may need to add absolute paths to the cmake call (e.g. adding folders to CMAKE_PREFIX_PATH in build.sh) so that it can find all your locally installed libraries – in which case your conda package will probably not be portable.

After compilation is successful, 🦖 can be installed using:

conda create -n tracking –override-channels -c local -c conda-forge trex

Notice there is a -c local, instead of the -c trexing for a normal installation. If this does not work, you can also put the full output folder here that conda build displayed at the end of a successful compilation. For example:

conda create -n tracking --override-channels -c /home/user/miniforge3/conda-bld -c conda-forge trex

Finally, to run it simply switch to the environment you just created (tracking) using conda activate tracking and run trex to see if the window appears!

Compiling manually (TODO)

Warning

Please note that the below instructions may not be up-to-date yet. I am working on it and will update them as soon as possible.

First, make sure that you fulfill the platform-specific requirements:

  • Windows: Please make sure you have Visual Studio installed on your computer. It can be downloaded for free from https://visualstudio.microsoft.com. We have tested Visual Studio versions 2019 up to 2022. We are using the Anaconda PowerShell here in our examples.

  • MacOS: Make sure you have Xcode and the Xcode compiler tools installed. They can be downloaded for free from the App Store (Xcode includes the compiler tools). We used macOS >=15 and Xcode >=13.

  • Linux: You should have build-essential installed, as well as g++ >=13 or a different compiler with C++23 support.

As well as the general requirements:

  • Python: We use version >= 3.7,<4.

  • CMake: Version >= 3.22.

Note

We will be using Miniforge here. However, it is not required to use Miniforge when compiling 🦖 – it is just a straight-forward way to obtain dependencies. In case you do not want to use Miniforge, please make sure that all mentioned dependencies are installed in a way that can be detected by CMake. You may also add necessary paths to the CMake command-line, such as -DOpenCV_DIR=/path/to/opencv and use switches to compile certain libraries (such as OpenCV) statically with 🦖.

The easiest way to ensure that all requirements are met, is by using conda to create a new environment:

conda create -n trex git cmake ffmpeg pip numpy==1.26.4 python=3.11 nasm

Next, switch to the conda environment using:

conda activate trex

You can now clone the repository and change your directory to a build folder:

git clone --recursive https://github.com/mooch443/trex

Now run the post-link script to install some required pip packages:

# Windows
cd trex/conda
post-link.bat

# Linux or MacOS
cd trex/conda
sh post-link.sh

Create and switch to the build folder:

cd ../Application
mkdir build
cd build

On MacOS you may need to adjust the SDK location as well as the deployment target. This can be done in the Application/trex_build_unix.sh script - there is a line that defines e.g.:

MACOSX_DEPLOYMENT_TARGET="15.2"

Which you can change to your installed SDK version.

Now we have to generate the project files for the given platform and compiler. The required CMake command varies slightly depending on the operating system. Within the environment, execute the compile script for your platform:

# Linux/MacOS
../trex_build_unix.sh

# Windows (Miniforge PowerShell)
../trex_build_windows.bat

Regarding switches, TRex offers a couple of additional options, with which you can decide to either compile libraries on your own or use existing ones in your system/environment path – see next section.

The compile scripts will attempt to compile the software in Release mode and compile sub packages in a specific order, since I was too lazy to make the CMakeLists work by themselves. To compile in a different mode, let this run and then simply run cmake --build . --config Debug, for example. If compilation succeeds, you should now be able to run 🦖 from the command-line, within the environment selected during compilation.

Note

In order to compile the documentation you’ll need a few more packages, installable via pip:

python -m pip install sphinx-hoverxref sphinx-rtd-theme sphinx-rtd-dark-mode sphinx-copybutton

Then go to the trex/docs folder and run:

make html

This is for HTML, but I am told sphinx supports more formats, too :)

Special needs

🦖 compilation using CMake offers switches to customize your build. Each of them can be appended to the above CMake command with -D<option>=<value> where value is usually either ON or OFF (unless it is a path, in which case it is a path). Below, we explain a couple of use-cases where these might come in handy – but first, let’s see a list of all CMake options available:

  • WITH_PYLON: Activates Pylon compatibility, enabling support for machine vision cameras from Basler (using USB interfaces). We tested this with versions 5 and 6. See Basler Pylon support below.

  • WITH_FFMPEG: Enabled by default, but can be forcibly turned off. This enables the streaming of MP4 video when recording from a camera in |grabs|. See `FFMPEG support`_.

  • TREX_BUILD_OPENCV: If set to ON, 🦖 builds its own version of OpenCV with OpenCL support enabled, but otherwise limited features. Avoids using system provided binaries (or binaries in the conda environment) if enabled. See `Use an existing OpenCV distribution`_.

  • TREX_BUILD_ZIP: Builds libzip and libz.

  • TREX_BUILD_PNG: Builds libpng. If set to OFF, then both libraries have to be provided in a way that CMake can find them.

  • TREX_BUILD_GLFW: In order to display windows and graphics inside these windows, GLFW is required. You can use a custom build by enabling this option.

  • TREX_WITH_TESTS: Build or don’t build additional test executables.

Basler Pylon support

In case you are planning to use |grabs| to record from Basler cameras directly, you have to compile the program with the additional option -DWITH_PYLON=ON. Prior to this, you will also need to install the Basler Pylon SDK from their website at https://www.baslerweb.com/. We tested 🦖 with version 5.2.0.