Quick Start#

Installing#

Ubuntu#

Download the ubuntu 24 kdFlex package and

Debian package: Run

sudo apt update

followed by

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

to install the kdFlex package.

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
```
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 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.
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, this can be done by running

export KARANA_LICENSE_FILE=<path to the license file>

For cshrc, this can be done by running

setenv KARANA_LICENSE_FILE <path to the license file>

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 creates a 3D visualization for it. 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 tutorial examples included in your installation as described in Examples section. These working examples illustrate use of kdFlex’s Python API.
Forum, Issue tracker: You may want to create accounts on the online kdFlex community forum and issue tracker for additional support resources.

MacOS#

The macOS build is currently experimental. Some features may not work as intended, and currently, there is only a homebrew package for macOS sequoia. Since the files are behind a login, you will need to create a brew tap yourself (instructions below). To begin, download both files (the *.tar.gz and *.rb files) for macOS sequoia from the downloads page. Then:

Install homebrew: If you do not already have homebrew set up, please do so by following the homebrew setup instructions.
Brew tap: Create a brew tap for the kdflex package by running
```
brew tap-new karana/kdflex
```
Brew formula: Move both the *.tar.gz and *.rb files from the downloads page to /opt/homebrew/Library/Taps/karana/homebrew-kdflex/Formula. From the directory where you originally downloaded the files, run
```
cp kdflex.rb /opt/homebrew/Library/Taps/karana/homebrew-kdflex/Formula 
cp kdflex*.tar.gz /opt/homebrew/Library/Taps/karana/homebrew-kdflex/Formula
```
Brew install: Run the following to install the kdflex package:
```
brew install karana/kdflex/kdflex
```
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
```
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, or 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.
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, this can be done by running

export KARANA_LICENSE_FILE=<path to the license file>

For cshrc, this can be done by running

setenv KARANA_LICENSE_FILE <path to the license file>

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 creates a 3D visualization for it.
Forum, Issue tracker: You may want to create accounts on the online kdFlex community forum and issue tracker for additional support resources.

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 tutorial examples included in your installation as described in Examples section. These working examples illustrate use of kdFlex’s Python API.

Documentation#

kdFlex Chatbot
Examples
Usage Guide
Documentation
Concepts
Spatial Operator Algebra (SOA) theory (book)
Working with C++: See the C++ and Python layers section for details about how to build and use your application with kdFlex.

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.

Windows WSL#

kdFlex can be run on a Windows system via WSL. Instructions on setting up WSL itself are available here.

Docker image#

TODO

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:

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/hombrew/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.
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>
```

Quick Start

Contents