torch-efd 1.0.0

Elliptic Fourier Descriptors in PyTorch

Elliptic Fourier Descriptors in PyTorch

Elliptic Fourier descriptors (EFDs) [1] represent a closed contour and are useful for shape analysis, matching, recognition and augmentation.

Adapted from PyEFD.

Install

pip install torch-efd

Example

import torch
from torch_efd import (
    compute_efds,
    integrate_total_length,
    compute_curvature,
    rotate_efds,
    reconstruct_efds
)

# 2d contour of a square
contour = torch.tensor(
    [[1, -1], [1, 1], [-1, 1], [-1, -1], [1, -1]],
    dtype=torch.float32,
)

# compute EFD coefficents
# higher order increases precision
# set normalize=True for scale/phase/rotation-invariant descriptors
efds = compute_efds(contour, order=20)

# compute length and curvature of shape
length = integrate_total_length(efds)
curvature = compute_curvature(efds, ts=100)

# transform shape
efds = rotate_efds(efds, angle=torch.pi / 4)

# back to coordinates
reconstructed = reconstruct_efds(efds, ts=100)

API

Basics

Function	Description
compute_efds( contour: Tensor, order: int, normalize: bool = False, ) -> Tensor	Compute EFDs, see example
reconstruct_efds( efds: Tensor, ts: Tensor | int ) -> Tensor	Reconstruct contour, see example
normalize_phase(efds: Tensor) -> Tensor	Normalize the EFDs to have zero phase shift from the first major axis.
normalize_rotation(efds: Tensor) -> Tensor	Normalize the EFDs to be rotation invariant by aligning the semi-major axis with the x-axis.
normalize_scale(efds: Tensor) -> Tensor	Normalize the scale of the EFDs.
normalize_efds(efds: Tensor) -> Tensor	Normalize phase, rotation and scale of EFDs.

Geometry

Function	Description
derive_tangent_efds(efds: Tensor) -> Tensor derive_normal_efds(efds: Tensor) -> Tensor	Compute EFDs for tangent or normal function
reconstruct_tangents( efds: Tensor, ts: Tensor | int, normed: bool = False, ) -> Tensor reconstruct_normals( efds: Tensor, ts: Tensor | int, normed: bool = False, ) -> Tensor reconstruct_tangrads( efds: Tensor, ts: Tensor | int, normed: bool = False, ) -> Tensor	Compute tangent/normal/tangrad vectors
compute_curvature( efds: Tensor, ts: Tensor | int, signed: bool = True, ) -> Tensor	Compute (signed) curvature of a contour.
compute_speed( efds: Tensor, ts: Tensor | int ) -> Tensor compute_arclens( efds: Tensor, ts: Tensor | int ) -> Tensor	Compute speed (magnitude of tangents) or arc lengths
integrate_total_length( efds: Tensor, ts: Tensor | int = 100 ) -> Tensor	Compute total length of contour
compute_area( efds: Tensor, ts: Tensor | int = 100 ) -> Tensor	Compute area of polygon bounded by contour using the shoelace method

Transform

Function	Description
scale_efds( efds: Tensor, scale: float | Tensor ) -> Tensor rotate_efds( efds: Tensor, angle: float | Tensor ) -> Tensor	Scale or rotate contour by transforming EFDs
smooth_efds( efds: Tensor, sigma: float, normalize: bool = False ) -> Tensor	Apply gaussian smoothing with standard deviation sigma in fourier space

Render

Function	Description
draw_mask( efds: Tensor, shape: tuple[int, int], n_points: int ) -> Tensor draw_perimeter( efds: Tensor, shape: tuple[int, int], n_points: int ) -> Tensor	Draw image of mask/perimeter of the polygon bounded by the contour. Requires scikit-image.
compute_sdf( efds: Tensor, shape: tuple[int, int], n_points: int ) -> Tensor	Compute signed distance function for a contour. Requires scipy.
plot_efds( efds: Tensor, ts: int | Tensor = 100, ax: Axes | None = None, *args, **kwargs, )	Plot a contour. Extra args/kwargs will be passed to Axes.plot. Requires matplotlib.

References

[1] F. Kuhl and C. P. Giardina. Elliptic Fourier Features of a Closed Contour. Computer Graphics and Image Processing 18, 1982, 236-258. https://www.sci.utah.edu/~gerig/CS7960-S2010/handouts/Kuhl-Giardina-CGIP1982.pdf