Metadata-Version: 2.1
Name: slamd
Version: 2.1.5
Summary: Python bindings for SlamDunk
Author-Email: Robert Leo <robert.leo.jonsson@gmail.com>
Requires-Python: >=3.11
Requires-Dist: numpy>=1.23
Description-Content-Type: text/markdown

![](./images/logo.png)

---

SlamDunk is a powerful and user-friendly C++/Python library for making live 3D and 2D visualizations for prototyping, data exploration, and algorithm development.

It is very lightweight, built using OpenGL and ImGui.

The project is in very early development with many improvements coming in the near future.

# Examples

## Hello world

Here is a simple "hello world" program for a SlamDunk visualization.

```python
#python
import slamd

if __name__ == "__main__":
    vis = slamd.Visualizer("Hello world")

    scene = slamd.Scene()

    scene.set_object("/origin", slamd.geom.Triad())

    vis.add_scene("scene", scene)

    vis.hang_forever()
```

```c++
// C++
#include <slamd/slamd.hpp>

int main() {
    auto vis = slamd::visualizer("hello_world");

    auto scene = slamd::scene();

    scene->set_object("/origin", slamd::geom::triad());

    vis->add_scene("scene", scene);

    vis->hang_forever();
}
```

This example highlights the main components of SlamDunk.

1. The `Visualizer` object maintains the state of the visualization. It starts a TCP server, and spawns a viewer process that reads from it and displays the visualizations.
2. A `Scene` object represents and contains a tree of 3D objects.
3. `Geometry` objects can be added to `Scene`s with a path in the tree.
4. To display a scene, we must add it to the visualizer - this creates a _view_ of the scene.

Running this program results in the following interactive visualization:
![](./images/hello_world.png)

## Multiple scenes

We use ImGui to allow multiple sub-windows with floating and docking support inside the SlamDunk viewer. The following example illustrates creating two windows, each showing its own scene.

```python
# python
import slamd
import numpy as np

if __name__ == "__main__":
    vis = slamd.Visualizer("two windows")

    scene1 = slamd.Scene()
    scene2 = slamd.Scene()

    vis.add_scene("scene 1", scene1)
    scene1.set_object("/box", slamd.geom.Box())

    vis.add_scene("scene 2", scene2)
    scene2.set_object("/origin", slamd.geom.Triad())

    scene2.set_object("/ball", slamd.geom.Sphere(2.0))

    sphere_transform = np.identity(4, dtype=np.float32)
    sphere_transform[:, 3] = np.array([5.0, 1.0, 2.0, 1.0])

    scene2.set_transform("/ball", sphere_transform)

    vis.hang_forever()

```

```c++
// C++
#include <glm/glm.hpp>
#include <slamd/slamd.hpp>

int main() {
    auto vis = slamd::visualizer("two windows");

    auto scene1 = slamd::scene();
    auto scene2 = slamd::scene();

    vis->add_scene("scene 1", scene1);
    scene1->set_object("/box", slamd::geom::box());

    vis->add_scene("scene 2", scene2);
    scene2->set_object("/origin", slamd::geom::triad());
    scene2->set_object("/ball", slamd::geom::sphere(2.0f));

    glm::mat4 sphere_transform(1.0);
    sphere_transform[3] += glm::vec4(5.0, 1.0, 2.0, 1.0);

    scene2->set_transform("/ball", sphere_transform);

    vis->hang_forever();
}

```

The resulting window looks like this:

![](./images/two_scenes.png)

The windows are fully controllable - you can drag then around, make tabs, use them in floating mode, dock them to the sides like you see in the screenshot. All of this is supported by [ImGui](https://github.com/ocornut/imgui).

## Further reading

The examples in the `/examples` folder showcase some more features of SlamDunk, like

- Canvases for 2D visualizations
- Multiple views of the same scene
- Moving objects around.
- Taking control of the render loop to create fully-fletced GUIs around SlamDunk using the power of ImGui.

# Installation

## Python

The python binding wheels are available on [PyPi](https://pypi.org/project/slamd/), so you can simply

```bash
pip install slamd
```

## C++

### With FetchContent

You can use CMake's `FetchContent`. Add this to your `CMakeLists.txt`:

```cmake
include(FetchContent)

FetchContent_Declare(
  slamd
  GIT_REPOSITORY https://github.com/Robertleoj/slam_dunk.git
  GIT_TAG main
  SOURCE_SUBDIR slamd
)

FetchContent_MakeAvailable(slamd)
```

Linking to it then looks like:

```cmake
target_link_libraries(
    your_target PRIVATE

    slamd::slamd
)
```

### With git submodules

If you add the repo as a submodule in your project, you can add it as a subdirectory with

```cmake
add_subdirectory(path/to/slam_dunk/slamd)

```

Just make sure to

```bash
git submodule update --init --recursive

```

inside the submodule, as all necessary dependencies are vendored.

You can then link it to your executable or library with

```cmake
target_link_libraries(
    your_target PRIVATE

    slamd::slamd
)
```

# Contributions

All contributions are welcome! SlamDunk is in very early development, so there is enough work to do, and multiple things to improve.
