Metadata-Version: 2.4
Name: trafolib
Version: 1.0.0
Summary: Trafolib: a Python framework for handling transformations in 2D and 3D
Author-email: Philipp Roebrock <philipp.roebrock@fhgr.ch>
License: MIT License
        
        Lighthouse: https://gitlab.com/proebrock/lighthouse/
        Copyright (c) 2021 Philipp Roebrock
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://gitlab.com/proebrock/trafolib
Project-URL: Issues, https://gitlab.com/proebrock/trafolib/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: numpy-quaternion
Requires-Dist: matplotlib
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# Trafolib
![Pipeline Status](https://gitlab.com/proebrock/trafolib/badges/devel/pipeline.svg)
![Coverage](https://gitlab.com/proebrock/trafolib/badges/devel/coverage.svg)

The use of 2D and 3D rigid body transformations is common in fields such as robotics and computer vision. This package provides two classes, `Trafo2d` and `Trafo3d`, to handle all different representations, such as homogeneous matrices, quaternions, and various flavors of Euler angles. All classes are well tested and documented. The library has few external dependencies and can be easily used in any project requiring transformation computations.

## Features
- Class representations for 2D and 3D rigid body transformations
- Conversions from/to rotation matrices, homogeneous matrices, RPY angles, Euler angles, quaternions and Rodrigues vectors
- Inversion and concatenation of transformations
- Transformation of points
- Save to dictionary/JSON, load from dictionary/JSON
- Interpolations of transformations
- Averaging and distance computations
- Visualizations in `Matplotlib`
- Very well tested in unit tests and various projects
- **Permissive License (MIT)**, code can be used in commercial software

## Requirements
- [Python](https://www.python.org/) >=3.10
- [NumPy](https://numpy.org/)
- [Quaternions in NumPy](https://quaternion.readthedocs.io/en/latest/)
- [Matplotlib](https://matplotlib.org/)
- [pytest](https://docs.pytest.org/en/stable/) and [pytest-cov](https://pypi.org/project/pytest-cov/) for testing
- [Ruff](https://github.com/astral-sh/ruff) for linting


All dependencies are declared in [`pyproject.toml`](pyproject.toml).

## Installation
It is strongly recommended to use a **virtual environment**.

### For Users (Runtime Only)
This will install the core libraries needed to run Trafolib, without any development tools or tests.

```bash
pip install trafolib
```

### 2. For Developers
This installation is for **contributors** who want to run tests or modify the code.

1. Clone the repository:
    ```bash
    git clone https://gitlab.com/proebrock/trafolib.git
    cd trafolib
    ```
2. Create a virtual environment (recommended):
    ```bash
    python -m venv .venv
    source .venv/bin/activate  # Linux / macOS
    .venv\Scripts\activate     # Windows
    ```
   
3. Install the project with development extras:
    ```bash
    pip install -e ".[dev]"
    ```
4. Run ruff:
   - As a linter:
     ```bash
     ruff check
     ```
   - As a formatter:
     ```bash
     ruff format
     ```
5. Run all tests:
    ```bash
    pytest
    ```

## About me and the project
My name is Philipp Roebrock and I work as a lecturer at the Institute for Photonics and Robotics at the University of Applied Sciences of the Grisons [FHGR](https://www.fhgr.ch/) in Chur in Switzerland.

If you have any questions or suggestions please drop and issue or a personal message to `philipp DOT roebrock AT fhgr DOT ch`.
