Metadata-Version: 2.4
Name: telekinesis-medulla
Version: 0.1.15
Summary: Module for connecting to cameras and hardware devices within the Telekinesis ecosystem.
Author-email: Telekinesis <support@telekinesis.ai>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://telekinesis.ai
Project-URL: Documentation, https://docs.telekinesis.ai
Project-URL: Telekinesis Examples Repository, https://github.com/telekinesis-ai/telekinesis-examples
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: loguru
Requires-Dist: numpy>=2.0
Requires-Dist: opencv-python
Requires-Dist: pathlib
Requires-Dist: babyros==0.1.2
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Requires-Dist: mkdocstrings[python]<1,>=0.25; extra == "docs"
Requires-Dist: mkdocs-awesome-pages-plugin<3,>=2; extra == "docs"
Provides-Extra: examples
Requires-Dist: rerun-sdk>=0.31.2; extra == "examples"
Provides-Extra: dev
Requires-Dist: ruff==0.15.9; extra == "dev"
Requires-Dist: pylint==4.0.5; extra == "dev"
Provides-Extra: ids
Requires-Dist: ids_peak; extra == "ids"
Requires-Dist: ids_peak_ipl; extra == "ids"
Requires-Dist: ids_peak_icv; extra == "ids"
Provides-Extra: realsense
Requires-Dist: pyrealsense2==2.56.5.9235; extra == "realsense"
Provides-Extra: zivid
Requires-Dist: zivid==2.17.2; extra == "zivid"
Requires-Dist: open3d==0.19.0; extra == "zivid"
Dynamic: license-file

<div align="center">
  <p>
    <a align="center" href="" target="_blank">
      <img
        width="100%"
        src="https://telekinesis-public-assets.s3.us-east-1.amazonaws.com/Telekinesis+Banner.png"
      >
    </a>
  </p>

  <br>

[Telekinesis Examples](https://github.com/telekinesis-ai/telekinesis-examples) | [Telekinesis Data](https://gitlab.com/telekinesis/telekinesis-data)
<br>

[![PyPI version](https://img.shields.io/pypi/v/telekinesis-medulla)](https://pypi.org/project/telekinesis-medulla/)
[![License](https://img.shields.io/pypi/l/telekinesis-medulla)](https://pypi.org/project/telekinesis-medulla/)
[![Python versions](https://img.shields.io/pypi/pyversions/telekinesis-medulla)](https://pypi.org/project/telekinesis-medulla/)

</div>

<p align="center">
  <a href="https://github.com/telekinesis-ai">GitHub</a>
  &nbsp;•&nbsp;
  <a href="https://www.linkedin.com/company/telekinesis-ai/">LinkedIn</a>
  &nbsp;•&nbsp;
  <a href="https://x.com/telekinesis_ai">X</a>
  &nbsp;•&nbsp;
  <a href="https://discord.gg/7NnQ3bQHqm">Discord</a>
</p>

# `medulla`: Hardware Communication Skills

`medulla` is a module in the Telekinesis SDK for connecting to cameras and hardware devices. It provides tools to interface with various 2D and 3D cameras and integrate them into Telekinesis applications.
It includes:

- 2D and 3D camera interfacing
- Data acquisition and preprocessing
- Time-synchronized sensor streams
- Integration with Telekinesis modules (`vitreous`, `retina`, `cornea`, `pupil`)

This library is used for robotics applications that require camera connectivity, including vision pipelines, multi-camera robot perception, and Physical AI agent integration.

**`medulla` is currently in its early development phase (pre-1.0). There will be continuous minor version updates that may introduce new features and improvements. To ensure compatibility and have the latest features, please always install or upgrade to the latest version of the package.**

## Installation

1. Create an isolated environment to avoid dependency conflicts. We recommend installing `Miniconda` by following the instructions from [here](https://docs.conda.io/en/latest/miniconda.html#installing).

2. Create a new `conda` environment called `telekinesis-medulla`:

   ```bash
   conda create -n telekinesis-medulla python=3.11
   ```

3. Activate the environment:

   ```bash
   conda activate telekinesis-medulla
   ```

4. Install `medulla` using `pip`:

   **We currently support Python versions - 3.11, 3.12. Ensure your environment is in the specified Python version.**

   ```bash
   pip install telekinesis-medulla
   ```

5. Install the additional dependencies to run the official [examples](https://github.com/telekinesis-ai/telekinesis-examples):

   ```bash
   pip install telekinesis-medulla[examples]
   ```

### Additional Setup

Camera drivers and vendor SDKs require additional installation steps. Please follow the official [documentation](https://docs.telekinesis.ai/medulla/overview.html) for vendor-specific SDK setup.

**IDS cameras:** Installing the `ids` extras (`pip install telekinesis-medulla[ids]`) fetches `ids_peak`, `ids_peak_ipl`, and `ids_peak_icv` directly from IDS Imaging Development Systems GmbH's own PyPI distribution. By installing these packages, you become the licensee under the [IDS Software Suite License Terms](https://www.ids-imaging.com) and are bound by its conditions.

**RealSense cameras:** Installing the `realsense` extras (`pip install telekinesis-medulla[realsense]`) fetches `pyrealsense2` directly from Intel's PyPI distribution. By installing this package, you become the licensee under the [Intel RealSense SDK 2.0 License Terms](https://github.com/IntelRealSense/librealsense/blob/master/LICENSE) and are bound by its conditions.

## Example

Run a sample Python script to quickly test your installation.

1. Create a `Python` file named `medulla_example.py` in a directory of your choice and paste the following:

   ```python
   from telekinesis.medulla.cameras import webcam

   camera = webcam.Webcam(name="my_webcam_camera", camera_id=0)
   camera.connect()
   image = camera.capture_color_image()
   print(image)
   camera.disconnect()
   ```

2. Activate the previously created conda environment. On a terminal, navigate to the directory where `medulla_example.py` was created and run:

   ```bash
   python medulla_example.py
   ```

   Expected output: Some logs and an image from the connected webcam in the below format:

   ```bash
    ...
    [[[158 155 140]
    [159 155 142]
    [160 154 144]
    ...
    [255 255 252]
    [255 255 251]
    [255 255 251]]
    ...
   ```

## Supported Cameras

| Vendor                                                    | Status      |
| --------------------------------------------------------- | ----------- |
| [Webcam](https://docs.telekinesis.ai/medulla/webcam.html) | Available   |
| [IDS](https://docs.telekinesis.ai/medulla/ids.html)       | Available   |
| [Intel RealSense](/medulla/realsense)                     | Available   |
| ZIVID                                                     | Coming Soon |
| SensoPart                                                 | Coming Soon |
| MechMind                                                  | Coming Soon |
| Azure Kinect                                              | Coming Soon |

## Resources

- Examples
  Runnable usage examples for Medulla: [Telekinesis Examples](https://github.com/telekinesis-ai/telekinesis-examples)

- Documentation
  Full SDK documentation and usage details: [Telekinesis Documentation](https://docs.telekinesis.ai)

- Sample Data
  Datasets used across the examples: [Telekinesis Data](https://gitlab.com/telekinesis/telekinesis-data)

## Support

For issues and questions:

- Create an [issue](https://github.com/telekinesis-ai/telekinesis-examples/issues) in the GitHub repository.
- Contact the Telekinesis development team at support@telekinesis.ai or on [Discord](https://discord.com/invite/7NnQ3bQHqm).
