Metadata-Version: 2.4
Name: superellipse
Version: 0.1.0
Summary: Generalized superellipse (Lamé curve) geometry: discretization, curvature, arc-length, and export
Project-URL: Homepage, https://github.com/egoughnour/superellipse
Project-URL: Documentation, https://github.com/egoughnour/superellipse#readme
Project-URL: Repository, https://github.com/egoughnour/superellipse
Project-URL: Issues, https://github.com/egoughnour/superellipse/issues
Author-email: Erik Goughnour <e.goughnour@gmail.com>
License: MIT
License-File: LICENSE
Keywords: cad,curves,geometry,lame,squircle,superellipse,svg
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Provides-Extra: all
Requires-Dist: matplotlib>=3.7; extra == 'all'
Requires-Dist: svgwrite>=1.4; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: export
Requires-Dist: svgwrite>=1.4; extra == 'export'
Provides-Extra: plot
Requires-Dist: matplotlib>=3.7; extra == 'plot'
Description-Content-Type: text/markdown

# 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.
