Quick Start

Quick Start#

Installing#

Ubuntu#

Download the ubuntu 24 kdFlex Debian file and

  1. Debian package (and Windows WSL2): Run

    sudo apt update && sudo apt install ./kdflex-*-Linux.deb

    to install the kdFlex package.

  2. Python dependencies: Install the Python requirements located in /usr/share/Karana/requirements.txt. The recommended way is to do this is in a Python virtual environment. To do so, run (this will take a few minutes to complete)

    python3 -m venv --system-site-packages .venv 
source .venv/bin/activate 
pip install --upgrade -r /usr/share/Karana/requirements.txt

    The virtual environment can be deactivated at any time using the deactivate command, or re-activated at any time by running source .venv/bin/activate. Alternative ways to install the Python packages are described in the Alternative Python package installation options section below.

  3. License setup: Please set the KARANA_LICENSE_FILE environment variable to the location of your license file. This can be done by running one of the following commands in your terminal, or adding the line to your shell configuration file.

  • For bash or zsh, use

    export KARANA_LICENSE_FILE=<path to the license file>

  • For csh use setenv KARANA_LICENSE_FILE <path to the license file>

  1. Verify installation: Run

    cd /usr/share/Karana/Tutorials/example_urdf &&  python3 notebook.py

    to verify that the installation is working correctly. This should run a kdFlex example that creates a robot arm multibody model and 3D visualization for it. There may be a start up delay the first time as python generates .pyc files.

MacOS#

The macOS (experimental) build is is a homebrew package for macOS sequoia. Since the files require login access, you will need to create a brew tap yourself (instructions below). To begin, download macOS sequoia kdFlex package from the downloads page. Then:

  1. Install via Brew: If you do not already have homebrew set up, please do so by following the homebrew setup instructions.

    a. Brew tap: Create a brew tap for the kdFlex package by running

    brew tap-new karana/kdflex

    b. Brew formula: Untar the *.tar.gz file from the downloads page into /opt/homebrew/Library/Taps/karana/homebrew-kdflex/Formula. From the directory where you originally downloaded the files, run

    tar -vxf kdflex*.tar.gz -C /opt/homebrew/Library/Taps/karana/homebrew-kdflex/Formula

    c. Brew install: Run the following to install the kdFlex package:

    brew install karana/kdflex/kdflex

  2. Python dependencies: Install the Python requirements located in /opt/homebrew/share/Karana/requirements.txt. The recommended way is to do this is in a Python virtual environment. To do so, run (this will take a few minutes to complete)

    python3.14 -m venv --system-site-packages .venv 
source .venv/bin/activate 
pip install --upgrade -r /opt/homebrew/share/Karana/requirements.txt

    The virtual environment can be deactivated at any time using the deactivate command, and re-activate at any time by running source .venv/bin/activate. Alternative ways to install the Python packages are described in the Alternative Python package installation options section below.

  3. License setup: Please set the KARANA_LICENSE_FILE environment variable to the location of your license file. This can be done by running one of the following commands in your terminal, or adding the line to your shell configuration file.

  • For bash or zsh, use

    export KARANA_LICENSE_FILE=<path to the license file>

  • For csh use setenv KARANA_LICENSE_FILE <path to the license file>

  1. Verify installation: Run

    cd /opt/homebrew/share/Karana/Tutorials/example_urdf  &&  python3 notebook.py

    to verify that the installation is working correctly. This should run a kdFlex example that creates a robot arm multibody model and 3D visualization for it. There may be a start up delay the first time as python generates .pyc files.

Windows WSL#

kdFlex can be run on a Windows system via WSL. Instructions on setting up WSL itself are available here. kdFlex installation instruction are the same as for ubuntu above.

Next steps#

You now have a working installation of kdFlex. The next step would be to review the Usage Guide for an overview of kdFlex’s capabilities, API, and usage. You can explore the Jupyter notebook tutorial examples included in the installation are described in the Examples section. These working examples illustrate the use of kdFlex’s Python API. The Program Skeletons area summarizes the steps needed for setting up your own simulations, and the Recipes area has details for specific steps that may be needed. The online kdFlex Chatbot is another handy way to get answers to your questions.

Forum, Issue tracker: You may want to create accounts on the online kdFlex community forum and issue tracker for additional support resources.

Documentation#

Upgrading#

To upgrade kdFlex to a newer version, you can repeat the instructions given in steps 1 and 2 above in the Installing section. This will remove the old version of kdFlex and install the new version. In addition, it will update the Python dependencies if required.

Docker image#

This section is for users interested in running the Ubuntu kdFlex build on a different Linux OS. The following describes the process for creating a docker container to host kdFlex. The instructions below assume that you are already familiar with basic docker usage. Docker documentation is available here.

The Dockerfile below can be used to build a basic container with kdFlex installed. This should be built with the kdFlex DEB package and license file in the same directory as the Dockerfile.

# Use Ubuntu 24 image
FROM ubuntu:24.04

# Set the shell to /bin/bash
SHELL ["/bin/bash", "-ec"]

# Set LANG
ENV LANG="C.UTF-8"

# Update apt update
RUN apt update

# Install kdFlex
COPY ./kdflex*.deb /tmp
RUN apt install -y --fix-broken /tmp/kdflex*.deb

# Install Python dependencies 
RUN (cd /opt && python3 -m venv --system-site-packages .venv && source .venv/bin/activate && pip install --upgrade -r /usr/share/Karana/requirements.txt)

# Add source command to bashrc so the venv is automatically sourced
RUN echo "source /opt/.venv/bin/activate" >> ~/.bashrc

# Copy license file to /opt
COPY ./*.license /opt

# Add license file to bashrc
RUN echo "export KARANA_LICENSE_FILE=`ls /opt/*.license | head -n 1`" >> ~/.bashrc

The image can be built by running the following command:

docker build -f Dockerfile -t kdflex:latest .

The image can be run using:

docker run --net=host -ti kdflex:latest bash

The --net=host is added to map ports from the docker container to the local machine. This allows one to view the graphics, data plots, etc. by connecting to the appropriate URL with a web browser. The image above does not contain any logic to forward graphics applications from the docker image to the localhost, so bringing up a local window via the electron app is not an option from within the container as written above. Doing so is possible, but is OS and machine specific.

Known issues#

  • When using web browsers on Windows operating systems for remote viewing of kdFlex 3D graphics, render updates do not work properly for Chrome based browsers such as Chromium and Edge. Firefox does work properly.

Alternative Python package installation options#

The following describe alternative options (instead of the recommended virtual environment option described in the Installing section) for installing the Python packages needed by kdFlex:

  1. User local installation: Install the requirements for your user by running

    pip install --break-system-packages -r /usr/share/Karana/requirements.txt

    or

    pip install --break-system-packages -r /opt/homebrew/share/Karana/requirements.txt

    if on macOS. This will install the packages to locally. You will likely need to add ~/.local/bin to your path if it is not on there already, e.g., for bash run

    export PATH=~/.local/bin:$PATH

    to do it for the current terminal session or add the export line to your shell configuration file.

  2. System level installation: (Ubuntu only) (CAUTION: This will modify the system-wide Python install so please use with care.) This should not be done on macOS, as the system Python version is too old to work with kdFlex. Install the requirements at the system level by running

    sudo pip install --break-system-packages -r /usr/share/Karana/requirements.txt

    This may require uninstalling some Python packages installed via apt with conflicting versions. This can be done using

    sudo apt remove <package_name>
Contents