Metadata-Version: 2.3
Name: catsmoothing
Version: 0.1.0
Summary: Smoothing Shapely geometries using CatMull-Rom spline
Project-URL: Changelog, https://github.com/cheginit/catsmoothing/blob/main/CHANGELOG.md
Project-URL: CI, https://github.com/cheginit/catsmoothing/actions
Project-URL: Homepage, https://github.com/cheginit/catsmoothing
Project-URL: Issues, https://github.com/cheginit/catsmoothing/issues
Author-email: Taher Chegini <cheginit@gmail.com>
License: MIT
License-File: AUTHORS.md
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: numpy>=2
Requires-Dist: shapely>=2
Provides-Extra: dev
Requires-Dist: asv; extra == 'dev'
Requires-Dist: ipykernel; extra == 'dev'
Requires-Dist: ipywidgets; extra == 'dev'
Requires-Dist: mapclassify; extra == 'dev'
Requires-Dist: matplotlib; extra == 'dev'
Provides-Extra: docs
Requires-Dist: black; extra == 'docs'
Requires-Dist: mdx-truly-sane-lists>=1.3; extra == 'docs'
Requires-Dist: mkdocs-jupyter; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5.20; extra == 'docs'
Requires-Dist: mkdocs>=1.5.3; extra == 'docs'
Requires-Dist: mkdocstrings-python; extra == 'docs'
Provides-Extra: scipy
Requires-Dist: scipy; extra == 'scipy'
Provides-Extra: test
Requires-Dist: coverage[toml]; extra == 'test'
Requires-Dist: opt-einsum; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-sugar; extra == 'test'
Requires-Dist: scipy; extra == 'test'
Description-Content-Type: text/markdown

![CatSmoothing](https://raw.githubusercontent.com/cheginit/catsmoothing/refs/heads/main/docs/assets/logo_small.png)

# CatSmoothing: Smoothing Shapely Geometries with Catmull-Rom Splines

[![PyPI](https://img.shields.io/pypi/v/catsmoothing)](https://pypi.org/project/catsmoothing/)
[![Conda](https://img.shields.io/conda/vn/conda-forge/catsmoothing)](https://anaconda.org/conda-forge/catsmoothing)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/cheginit/catsmoothing/HEAD?labpath=docs%2Fexamples)

[![codecov](https://codecov.io/gh/cheginit/catsmoothing/graph/badge.svg?token=U2638J9WKM)](https://codecov.io/gh/cheginit/catsmoothing)
[![CI](https://github.com/cheginit/catsmoothing/actions/workflows/test.yml/badge.svg)](https://github.com/cheginit/catsmoothing/actions/workflows/test.yml)
[![Documentation Status](https://readthedocs.org/projects/catsmoothing/badge/?version=latest)](https://catsmoothing.readthedocs.io/latest/?badge=latest)

## Overview

**CatSmoothing** smooths [Shapely](https://shapely.readthedocs.io)
geometries, `LineString` and `(Multi)Polygon`, using the Catmull-Rom spline algorithm.
The implementation is based on the
[Splines](https://github.com/AudioSceneDescriptionFormat/splines)
library, but offers performance improvements and additional features.

You can try CatSmoothing directly in your browser by clicking the Binder badge above.

## Key Features

- Creating splines from 2D/3D vertices of a line that allows computing n-th derivatives
- Smoothing geometries with Centripetal Catmull-Rom splines with **uniform spacing**
    (spacing is determined iteratively based on the arc length of the input geometry)
- Computing tangent vectors at each vertex of a line
- Optional Gaussian filtering to reduce noise in input geometries before smoothing
    (requires `scipy` to be installed)
- Automatically using `opt-einsum` for efficient computation of the spline coefficients,
    if it is installed

## Installation

Install CatSmoothing via `pip` or `micromamba`:

Using `pip`:

```bash
pip install catsmoothing
```

Using `micromamba` (or `conda`/`mamba`):

```bash
micromamba install -c conda-forge catsmoothing
```

## Quick Start

CatSmoothing provide one class called `CatmullRom` that is general purpose,
Catmull-Rom spline interpolation class. You can tweak the `alpha` parameter of
the class to interpolate with different versions of the Catmull-Rom spline
from 2D/3D vertices of a line and compute n-th derivatives.
For smoothing geometries, CatSmoothing uses the centripetal Catmull-Rom spline
algorithm, i.e., `alpha=0.5`. There are two functions that can be used
for smoothing geometries: `smooth_line` and `smooth_polygon`.

### Basic Usage

For fitting a Catmull-Rom spline to a line, we can use the following code:

```python
from catsmoothing import CatmullRom


verts = [(0, 0), (0, 0.5), (1.5, 1.5), (1.6, 1.5), (3, 0.2), (3, 0)]
n_pts = 15
for alpha in (0, 0.5, 1):
    s = CatmullRom(verts, alpha=alpha, bc_types="closed")
    dots = int((s.grid[-1] - s.grid[0]) * n_pts) + 1
    distances = s.grid[0] + np.arange(dots) / n_pts
    smoothed[alpha] = s.evaluate(distances)
```

![Catmull-Rom Splines](https://raw.githubusercontent.com/cheginit/catsmoothing/main/docs/examples/images/alpha.png)

For smoothing a geometry, we can use the following code:

```python
from shapely import Polygon
import catsmoothing as cs


poly = Polygon(verts)
ploy_smoothed = cs.smooth_polygon(poly, n_pts=50)
```

![Polygon Smoothing](https://raw.githubusercontent.com/cheginit/catsmoothing/main/docs/examples/images/poly.png)

For smoothing a noisy line, we can use the following code:

```python
import numpy as np
from shapely import LineString
import catsmoothing as cs


rng = np.random.default_rng(123)
x = np.linspace(-3, 2.5, 50)
y = np.exp(-(x**2)) + 0.1 * rng.standard_normal(50)
line = LineString(np.c_[x, y])
line_smoothed = cs.smooth_linestring(line, n_pts=30, gaussian_sigma=2)
```

![Line Smoothing](https://raw.githubusercontent.com/cheginit/catsmoothing/main/docs/examples/images/line.png)

We can then compute the tangent angles in radians at each vertex of the smoothed line:

```python
vertices = shapely.get_coordinates(line_smoothed)
tangents = cs.compute_tangents(vertices)
```

![Tangent Angles](https://raw.githubusercontent.com/cheginit/catsmoothing/main/docs/examples/images/tangents.png)

For more examples, visit the [documentation](https://catsmoothing.readthedocs.io).

## Contributing

We welcome contributions! For guidelines, please refer to the [CONTRIBUTING.md](https://catsmoothing.readthedocs.io/latest/CONTRIBUTING) and [CODE_OF_CONDUCT.md](https://github.com/cheginit/catsmoothing/blob/main/CODE_OF_CONDUCT.md).

## License

CatSmoothing is licensed under the MIT License. See the [LICENSE](https://github.com/cheginit/catsmoothing/blob/main/LICENSE) file for details.
