Metadata-Version: 2.1
Name: commonroad-clcs
Version: 2025.2.0
Summary: Curvilinear (Frenet) Coordinate System for motion planning.
Keywords: autonomous vehicles,automated driving,motion planning,frenet coordinates,commonroad
Author-Email: Cyber-Physical Systems Group - Technical University of Munich <commonroad@lists.lrz.de>
License: BSD 3-Clause License
         
         Copyright (c) 2019, Technical University of Munich, Professorship Cyber-Physical Systems.
         All rights reserved.
         
         Redistribution and use in source and binary forms, with or without
         modification, are permitted provided that the following conditions are met:
         
         * Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
         
         * Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
         
         * Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
         
         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
         AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
         IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
         DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
         FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
         DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
         SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
         CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
         OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
         
         
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: POSIX :: Linux
Project-URL: Homepage, https://commonroad.in.tum.de/tools/commonroad-clcs
Project-URL: Documentation, https://commonroad.in.tum.de/docs/commonroad-clcs/
Project-URL: Source, https://github.com/CommonRoad/commonroad-curvilinear-coordinate-system
Requires-Python: <3.14,>=3.10
Requires-Dist: commonroad-io>=2023.1
Requires-Dist: matplotlib>=3.3.3
Requires-Dist: numpy>=1.19.2
Requires-Dist: omegaconf>=2.1.1
Requires-Dist: scipy>=1.4.1
Requires-Dist: shapely>=2.0.0
Requires-Dist: osqp~=0.6.5
Provides-Extra: test
Requires-Dist: pytest>=3.8.0; extra == "test"
Requires-Dist: parameterized~=0.9.0; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs<2.0.0,>=1.6.1; extra == "docs"
Requires-Dist: mkdocstrings-python<2.0.0,>=1.8.0; extra == "docs"
Requires-Dist: mkdocs-material<10.0.0,>=9.5.10; extra == "docs"
Requires-Dist: mkdoxy~=1.2.4; extra == "docs"
Provides-Extra: build
Requires-Dist: scikit-build-core~=0.11.0; extra == "build"
Requires-Dist: nanobind~=2.2.0; extra == "build"
Requires-Dist: pathspec>=0.12.1; extra == "build"
Requires-Dist: pyproject-metadata>=0.7.1; extra == "build"
Requires-Dist: typing_extensions~=4.12.2; extra == "build"
Requires-Dist: cmake<4.0,>=3.24; extra == "build"
Description-Content-Type: text/markdown

# CommonRoad Curvilinear Coordinate System (CLCS)

Curvilinear coordinate frames (also Frenet frames) are a widely used representation in motion planning for automated
vehicles. Curvilinear frames are aligned with a reference path and Cartesian points (x, y) are described by 
coordinates (s, d), where s is the arc length and d the lateral deviation to the reference path.
The coordinate transformation is performed via a projection on the reference path for which different methods can be 
used [1] [2].

<img src="docs/assets/animation.gif" alt="clcs" width="500"/>

This project software for constructing and using curvilinear coordinate frames for reference paths given as polylines.
We offer:
* C++ backend for efficient coordinate transformations
* Python frontend for usage with CommonRoad scenarios
* various utility methods for processing reference path (e.g., smoothing, curvature reduction, resampling etc ...)

## :wrench: Installation
We provide two installation options for CommonRoad-CLCS: 
Installation as a Python package (recommended) or building from source.

1. **Python Package**: Install the python package via `pip` in your Conda environment:
    ```bash
    pip install commonroad-clcs
    ```
2. **Build from source**: To build the project from source and install it in your Conda environment, 
   please refer to the [README_FOR_DEVS](./README_FOR_DEVS.md).
   This option is only recommended for advanced users who would like to use or modify the C++ backend directly.



## :link: System Requirements
The software is written in Python 3.10 and C++17, and was tested on Ubuntu 20.04 and 22.04.
It should be compatible with later versions.
For building the code, the following minimum versions are required:
* **GCC and G++**: version 10 or above
* **CMake**: version 3.28 or above.
* **Pip**: version 24.2 or above

We recommend using [Anaconda](https://www.anaconda.com/) as a package manager for Python.


## :rocket: Getting Started
To get started, please see the minimal example in `./tutorials/clcs_minimal_example.py`.

For more details, please refer to the Jupyter notebook tutorials provided in `./tutorials/`. 


## :books: Documentation
A documentation including APIs is available on our website at:
https://cps.pages.gitlab.lrz.de/commonroad/commonroad-clcs/.

To build the documentation locally, please install the optional `docs` listed in [pyproject.toml](pyproject.toml) first.
The documentation can then be built using mkdocs via:
```bash
mkdocs build
```
You can browse the doc by launching `./docs/site/index.html`

## :busts_in_silhouette: Authors
**Contributors** (alphabetic order by last name): Peter Kocsis, Edmond Irani Liu,
Stefanie Manzinger, Tobias Markus, Evald Nexhipi, Vitaliy Rusinov, Daniel Tar, Gerald Würsching

## :speech_balloon: References
If you use our software for research, please cite:
```
@inproceedings{wursching2024robust,
    author={W{\"u}rsching, Gerald and Althoff, Matthias},
    title={Robust and Efficient Curvilinear Coordinate Transformation with Guaranteed Map Coverage for Motion Planning},
    booktitle={Proc. of the  IEEE Intelligent Vehicles Symposium},
    year={2024}
}
```

#### Additional references:
[1] [Héry, Elwan, Stefano Masi, Philippe Xu, and Philippe Bonnifait. "Map-based curvilinear coordinates for autonomous vehicles." ITSC, 2017](https://ieeexplore.ieee.org/document/8317775)

[2] [Bender, Philipp, Julius Ziegler, and Christoph Stiller. "Lanelets: Efficient map representation for autonomous driving." IV, 2014](https://ieeexplore.ieee.org/document/6856487)
