Installation ============ DIPLOMAT currently supports being installed as a normal python package on Windows, Linux, and MacOS. DIPLOMAT and can be installed by following the installation guide below. .. contents:: Contents Installing Python ----------------- If you have not already, you'll need to install python to utilize DIPLOMAT. It is recommend that you use `Miniforge `_ which provides a python environment and install process that is consistent across platforms. To install Miniforge: - Visit `https://github.com/conda-forge/miniforge `_. - Select the installer for your OS from the list of installers. - Run the installer and follow the installation instructions. Installing DIPLOMAT ------------------- With Support for SLEAP Projects ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Using Mamba or Conda ~~~~~~~~~~~~~~~~~~~~ Once you have a mamba installed, you'll want to open a terminal and type one of these two commands: .. code-block:: sh # Install diplomat with GPU support... mamba env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-SLEAP.yaml # Install diplomat with CPU support only... mamba env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-SLEAP-CPU.yaml .. hint:: Both running and installing diplomat requires access to a terminal. To access one: **Windows:** Open the start menu and search for *Miniforge Prompt*. **Linux:** Press :kbd:`CTRL` + :kbd:`ALT` + :kbd:`T`. This will open a terminal window. **Mac:** Select the search icon in the top right corner of the screen to open Spotlight, and then search for *Terminal*. Once done, simply activate the brand new environment. .. code-block:: sh mamba activate DIPLOMAT-SLEAP From here, the ``diplomat`` command will be available from the command line. Using PIP ~~~~~~~~~ If you are using an alternative package for managing python environments, you can install DIPLOMAT with SLEAP support by simply using pip, using one of the two commands below: NOTE: SLEAP is known to have installation issues on Windows when attempting to use pip. If you're trying to install DIPLOMAT with SLEAP support on Windows, prefer using the mamba/miniforge method above. .. code-block:: sh # Install DIPLOMAT with SLEAP with GUI support. pip install diplomat-track[sleap, gui] # Install DIPLOMAT with SLEAP without UI support. pip install diplomat-track[sleap] Troubleshooting for DIPLOMAT-SLEAP ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the Mamba method fails to install DIPLOMAT and SLEAP, or if DIPLOMAT does not run after installation, you may need to downgrade the numpy version manually. Activate the mamba environment with ``mamba activate DIPLOMAT-SLEAP``, then downgrade numpy with ``pip install numpy<1.23.0``. With Support for DeepLabCut Projects ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Using Mamba or Conda ~~~~~~~~~~~~~~~~~~~~ Once you have mamba or a mamba compatible CLI installed, you'll want to open a terminal and type one of these two commands: .. code-block:: sh # Install diplomat with GPU support... mamba env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-DEEPLABCUT.yaml # Install diplomat with CPU support only... mamba env create -f https://raw.githubusercontent.com/TravisWheelerLab/DIPLOMAT/main/conda-environments/DIPLOMAT-DEEPLABCUT-CPU.yaml .. hint:: Both running and installing diplomat requires access to a terminal. To access one: **Windows:** Open the start menu and search for *Miniforge Prompt*. **Linux:** Press :kbd:`CTRL` + :kbd:`ALT` + :kbd:`T`. This will open a terminal window. **Mac:** Select the search icon in the top right corner of the screen to open Spotlight, and then search for *Terminal*. Once done, simply activate the brand new environment. .. code-block:: sh mamba activate DIPLOMAT-DEEPLABCUT From here, the ``diplomat`` command will be available from the command line. Using PIP ~~~~~~~~~ If you are using an alternative package for managing python environments, you can install DIPLOMAT with DeepLabCut support by simply using pip, using one of the two commands below: .. code-block:: sh # Install DIPLOMAT with DeepLabCut with GUI support. pip install diplomat-track[dlc, gui] # Install DIPLOMAT with DeepLabCut without UI support. pip install diplomat-track[dlc] Troubleshooting for DIPLOMAT-DLC ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the standard methods fail to install DIPLOMAT and DLC, you can install from the Github source code. This method requires `git `_, as well as Miniforge. .. code-block:: sh # Clone the DIPLOMAT repository and navigate into it. git clone https://github.com/TravisWheelerLab/DIPLOMAT cd DIPLOMAT # With Miniforge, create a Python 3.10 environment and activate it. conda create -n py310 python==3.10 conda activate py310 # Use the environment you just activated to create a virtual environment ("venv") containing Python 3.10. python -m venv venv # Fully deactivate the Miniforge environment. # (run the command twice) conda deactivate conda deactivate # Now, activate the virtual environment. ## On Windows, the first time you activate the venv, you may need to configure your execution policy. Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser ## Activate the venv on Windows. venv/scripts/Activate ## Activate the venv on Mac/Linux. source venv/bin/activate # Update PIP python -m pip install --upgrade pip # Finally, install DIPLOMAT and DLC. The installation may take several minutes to complete. python -m pip install -e ".[dlc,gui]" --ignore-installed # Verify that the installation was successful. The following command should output the current version number. diplomat --version On Windows, if DIPLOMAT crashes with "OSError: [WinError 126]", you need the libomp DLL. Download the .zip from https://www.dllme.com/dll/files/libomp140_x86_64/versions, extract it, and copy the .dll file to the torch libraries folder of your virtual environment, which should be located at ``.\venv\lib\site-packages\torch\lib`` within the DIPLOMAT directory. If you named your virtual environment something other than ``venv``, change the path accordingly. Verifying the DIPLOMAT installation ----------------------------------- Downloading the Sample data ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Sample models and a video are provided `on Zenodo `_ for verifying the installation. Download the video clip `N5PZS.avi` and the model corresponding to your installation (DLC_5bp.zip for DeepLabCut, SLEAP_5bp.zip for SLEAP.) Unzip the model. Your working directory should now contain both the video file `N5PZS.avi` and the model folder, either `test_dlc_5/` or `test_sleap_5/`. Verify that both are present by running ``ls``. Activating the environment ^^^^^^^^^^^^^^^^^^^^^^^^^^ Next, you will activate the environment for DIPLOMAT. Unless you installed with the `Using PIP` method, you have to activate the environment that was created for DIPLOMAT in a previous step. Activating with Mamba ~~~~~~~~~~~~~~~~~~~~~ If you used the mamba installation process, you'll run ``mamba activate DIPLOMAT-DEEPLABCUT`` or ``mamba activate DIPLOMAT-SLEAP``. Activating with venv ~~~~~~~~~~~~~~~~~~ If you followed the virtual environment-based methods (DLC troubleshooting or developer install) you'll run ``venv/scripts/Activate`` on Windows or ``source venv/bin/activate`` on Mac/Linux (replacing `venv` with whatever you named the virtual environment.) Activating with PIP ~~~~~~~~~~~~~~~~~~~ If you followed the PIP-only method and installed DIPLOMAT to your default environment, no action is necessary. Verify ^^^^^^ In the directory containing the sample video and model, you can run track to verify that all of DIPLOMAT's functionality were installed properly. Verify tracking without GUI ~~~~~~~~~~~~~~~~~~~~ For DeepLabCut, run ``diplomat track -c test_dlc_5 -v N5PZS.avi``. For SLEAP, run ``diplomat track -c test_sleap_5 -v N5PZS.avi``. If the tracking completes successfully, a new file ending with extension either `.h5` or `.slp` will now be present. Verify tracking with GUI ~~~~~~~~~~~~~~~~~ For DeepLabCut, run ``diplomat track_and_interact -c test_dlc_5 -v N5PZS.avi``. For SLEAP, run ``diplomat track_and_interact -c test_sleap_5 -v N5PZS.avi``. After tracking completes, the manual annotation window will be opened and you should be able to make changes to the automated results.