telekinesis-datatypes 0.0.1rc5
Official core data types and serialization utilities package for the Telekinesis SDK and APIs.
Requires Python: <3.13,>=3.11

<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-datatypes)](https://pypi.org/project/telekinesis-datatypes/)
[![License](https://img.shields.io/pypi/l/telekinesis-datatypes)](https://pypi.org/project/telekinesis-datatypes/)
[![Python versions](https://img.shields.io/pypi/pyversions/telekinesis-datatypes)](https://pypi.org/project/telekinesis-datatypes/)

</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>


# Telekinesis Datatypes

Telekinesis Datatypes is a core library providing canonical, strongly typed data structures for robotics and computer vision within the Telekinesis ecosystem.
It includes:
- 3D data types: point clouds, meshes, transforms, and geometric primitives
- 2D data types: images, bounding boxes, masks, and pixel-space geometry
- Standardized representations for common perception and geometry formats
- Efficient serialization and deserialization for reliable data exchange

This library is used internally by the Telekinesis SDK as the foundation for data exchange across perception, planning, and learning components.

Telekinesis Datatypes is currently in its **initial release cycle**, published as release candidates (RC).

**Important: Please note that in this phase, the modules are introduced incrementally, and the versions are continuously evolving, therefore please always ensure you are on the latest version of the package.**

## Installation

1. Create an isolated environment so that there is no dependency conflicts. We recommend installing `Miniconda` environment by following instructions from [here](https://docs.conda.io/en/latest/miniconda.html#installing). 

2. Create a new `conda` environment called `datatypes`:
    ```bash
    conda create -n datatypes python=3.11
    ```

3. Activate the environment:
    ```bash
    conda activate datatypes
    ```

4. Install the core SDK using `pip`:

    **We currently support Python versions - 3.11, 3.12. Ensure your  environment is in the specified Python version.**

    ```bash
    pip install telekinesis-datatypes
    ```

    Note: The Python module is called `datatypes`, while the package  published on PyPI is `telekinesis-datatypes`.

## Example

Run a sample python code to quickly test your installation.

1. Create a `Python` file named `datatypes_example.py` in a directory of your choice in your system, and copy paste the below:

    ```python
    import numpy as np
    from datatypes import datatypes

    # Create Rgba32 colors for R, G, B
    red = datatypes.Rgba32([255, 0, 0, 255])
    green = datatypes.Rgba32([0, 255, 0, 255])
    blue = datatypes.Rgba32([0, 0, 255, 255])

    print(f"Red color (packed uint32): {red.rgba}")
    print(f"Green color (packed uint32): {green.rgba}")
    print(f"Blue color (packed uint32): {blue.rgba}")

    # Use __int__() to convert to integer
    red_int = int(red)

    print(f"Red as int: {red_int}")
    print(f"Direct comparison: int(red) == red.rgba: {red_int == red.rgba}" )
    ```

2. On a terminal, navigate to the directory where the above file named `datatypes_example.py` has been created, run the below command:

    ```bash
    python datatypes_example.py
    ```
    
    Expected output:
    ```bash
    Red color (packed uint32): 4278190335
    Green color (packed uint32): 16711935
    Blue color (packed uint32): 65535
    Red as int: 4278190335
    Direct comparison: int(red) == red.rgba: True
    ```

You are now set up with Telekinesis Datatypes.

## Resources

- Examples  
  Runnable usage examples for Telekinesis Datatypes: [Telekinesis Examples](https://github.com/telekinesis-ai/telekinesis-examples) (see examples/datatypes_examples.py)

- 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).