superellipse 0.8.0
Generalized superellipse (Lamé curve) geometry: discretization, curvature, arc-length, and export
License: MIT
Requires Python: >=3.10
Keywords: cad, curves, geometry, lame, squircle, superellipse, svg

# superellipse

Generalized superellipse (Lamé curve) geometry for Python.

[![PyPI version](https://img.shields.io/pypi/v/superellipse.svg)](https://pypi.org/project/superellipse/)
[![Python versions](https://img.shields.io/pypi/pyversions/superellipse.svg)](https://pypi.org/project/superellipse/)
[![License](https://img.shields.io/github/license/egoughnour/superellipse.svg)](https://github.com/egoughnour/superellipse/blob/main/LICENSE)
[![CI](https://github.com/egoughnour/superellipse/actions/workflows/ci.yml/badge.svg)](https://github.com/egoughnour/superellipse/actions/workflows/ci.yml)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://egoughnour.github.io/superellipse/)
[![codecov](https://codecov.io/gh/egoughnour/superellipse/branch/main/graph/badge.svg)](https://codecov.io/gh/egoughnour/superellipse)

## Overview

A superellipse (or Lamé curve) is defined by:

$$|x/a|^p + |y/b|^q = 1$$

This package provides tools for working with these curves:

- **Geometry**: Points, tangents, normals, curvature
- **Discretization**: Uniform, arc-length, or adaptive panel-based sampling
- **Signed distance**: Fast SDF evaluation for level-set methods
- **Export**: SVG paths, JSON, NumPy arrays
- **Special cases**: Squircle (p=q=4), rounded rectangles, stadium curves

## Installation

```bash
pip install superellipse

# With plotting support
pip install superellipse[plot]

# With SVG export
pip install superellipse[export]

# Everything
pip install superellipse[all]
```

## Quick Start

```python
from superellipse import Superellipse

# Create a squircle (p=4, like iOS icons)
curve = Superellipse(a=1.0, b=1.0, p=4)

# Sample 100 points
points = curve.sample(n=100)

# Get curvature at each point
kappa = curve.curvature(points)

# Export to SVG path
path_data = curve.to_svg_path(n=100)
```

## CLI

```bash
# Plot a superellipse
superellipse plot --a 1 --b 0.8 --p 4 --output squircle.png

# Export to SVG
superellipse export --a 1 --b 1 --p 6 --format svg --output curve.svg

# Compute arc length
superellipse info --a 1 --b 1 --p 4
```

## Use Cases

- **UI/UX Design**: Squircles for app icons (iOS-style rounded rectangles)
- **CAD/CAM**: Smooth corner profiles for machining
- **Graphics**: Procedural shape generation
- **Scientific Computing**: Boundary geometry for PDEs
- **Typography**: Letterform design with smooth corners

## API Reference

### `Superellipse(a, b, p, q=None)`

Create a superellipse with semi-axes `a`, `b` and exponents `p`, `q`.
If `q` is None, uses `q=p` (symmetric exponent).

#### Methods

| Method | Description |
|--------|-------------|
| `sample(n, method='uniform')` | Sample n points on the curve |
| `curvature(points)` | Signed curvature at given points |
| `normal(points)` | Outward unit normals |
| `tangent(points)` | Unit tangent vectors |
| `arc_length(t0=0, t1=2π)` | Arc length between parameter values |
| `signed_distance(points)` | Signed distance from points to curve |
| `to_svg_path(n=100)` | Export as SVG path data string |
| `to_json()` | Export curve parameters as JSON |

### Sampling Methods

- `'uniform'`: Uniform in parameter t ∈ [0, 2π]
- `'arclength'`: Uniform in arc length
- `'adaptive'`: Refine near high-curvature regions
- `'panels'`: Panel-based with Gauss-Legendre nodes (for BIE)

## License

MIT License. See [LICENSE](LICENSE) for details.