Skip to content

API reference

Catmull-Rom spline based on splines library.

CatmullRom 

CatmullRom(vertices, grid=None, alpha=None, bc_type='natural', gaussian_sigma=None, *, sigma_units='vertices', taubin_iterations=None, continuity='c1')

Catmull-Rom spline generator.

Parameters:

  • vertices (array_like) –

    Sequence of (x, y) vertices, shape (n, 2).

  • grid (array_like, default: None ) –

    Sequence of parameter values. Must be strictly increasing. If not specified, a uniform grid is used (0, 1, 2, 3, ...).

  • alpha (float, default: None ) –

    Catmull-Rom parameter. If specified, grid is ignored.

  • bc_type (('closed', 'natural', 'clamped'), default: "closed" ) –

    Start/end conditions. If "closed", the first vertex is reused as last vertex and an additional grid value has to be specified. If "clamped", endpoint tangents are set to ensure the spline passes through the start and end points without deviation.

  • gaussian_sigma (float, default: None ) –

    Standard deviation of a Gaussian kernel applied to the vertices before fitting, by default None (no smoothing). Open lines keep their end vertices; closed rings wrap around.

  • sigma_units (('vertices', 'length'), default: "vertices" ) –

    Units of the Gaussian sigma: vertex index steps (default), or Euclidean length along the input line in coordinate units. With "length", each vertex is weighted by the length of line it stands for, so uneven vertex spacing does not bias the smoothing.

  • taubin_iterations (int, default: None ) –

    Number of Taubin lambda/mu smoothing iterations (lambda 0.5, mu -0.53) applied to the vertices before fitting, by default None. Each iteration is one lambda step and one mu step; it damps vertex jitter and keeps the size of curves drawn with more than about a dozen vertices per turn. Cannot be combined with a Gaussian sigma.

  • continuity (('c1', 'g2', 'c2'), default: "c1" ) –

    Smoothness where spline pieces join, by default "c1" (Catmull-Rom tangent continuity). "g2" makes curvature continuous and follows the "c1" shape closely; "c2" also makes the second derivative with respect to grid continuous. Both split each piece into three cubic pieces (Yuksel, SIGGRAPH 2026) and keep every vertex and its tangent.

Examples:

>>> verts = [(0., 0.), (1., 1.), (2., 0.), (3., 1.)]
>>> s = CatmullRom(verts, alpha=0.5, bc_type="clamped")
>>> grid = np.linspace(0, s.grid[-1], 5)
>>> s.evaluate(grid)
array([[0.      , 0.      ],
       [0.75    , 0.890625],
       [1.5     , 0.5     ],
       [2.25    , 0.109375],
       [3.      , 1.      ]])
References

[1] E. Catmull and R. Rom, "A Class of Local Interpolating Splines," in Computer Aided Geometric Design, 1974. DOI: 10.1016/B978-0-12-079050-0.50020-5

evaluate 

evaluate(distances, n=0)

Get value (or n-th derivative) at given parameter value(s).

Parameters:

  • distances (array_like) –

    Distance(s) along the curve to evaluate.

  • n (int, default: 0 ) –

    Order of derivative with respect to the curve parameter (grid), by default 0, i.e., the value itself.

Returns:

  • array_like –

    Value (or n-th derivative) at given parameter value(s).

uniform_distances 

uniform_distances(n_pts, tolerance=None, max_iterations=None)

Get parameter values whose points are evenly spaced by arc length.

Parameters:

  • n_pts (int) –

    Number of points to generate, including both ends of the curve.

  • tolerance (float, default: None ) –

    Deprecated and ignored: points are spaced by arc length directly.

  • max_iterations (int, default: None ) –

    Deprecated and ignored: points are spaced by arc length directly.

Returns:

  • array_like –

    Parameter values of evenly spaced points.

smooth_linestrings 

smooth_linestrings(lines: LineString, distances: float | None = None, n_pts: int | None = None, gaussian_sigmas: float | None = None, bc_types: BCType | None = None, *, tolerance: float | None = None, max_iterations: int | None = None, sigma_units: SigmaUnits = 'vertices', taubin_iterations: int | None = None, continuity: Continuity = 'c1') -> LineString

smooth_linestrings(lines: list[LineString], distances: list[float] | None = None, n_pts: list[int] | None = None, gaussian_sigmas: list[float] | None = None, bc_types: list[BCType] | None = None, *, tolerance: float | None = None, max_iterations: int | None = None, sigma_units: SigmaUnits = 'vertices', taubin_iterations: int | None = None, continuity: Continuity = 'c1') -> list[LineString]

smooth_linestrings(lines, distances=None, n_pts=None, gaussian_sigmas=None, bc_types=None, *, tolerance=None, max_iterations=None, sigma_units='vertices', taubin_iterations=None, continuity='c1')

Smooth LineStrings using Centripetal Catmull-Rom splines and uniform spacing.

Parameters:

  • lines (list of shapely.LineString) –

    LineStrings to be smoothed.

  • distances (list of float, default: None ) –

    Largest distance between consecutive points along the curve, by default None. Points are spaced evenly at the widest spacing that does not exceed it. You must specify either distances or n_pts.

  • n_pts (list of int, default: None ) –

    Number of points to be generated, by default None. You must specify either distances or n_pts.

  • gaussian_sigmas (list of float, default: None ) –

    Standard deviation of a Gaussian kernel applied to each line's vertices before fitting, by default None (no smoothing). Open lines keep their end vertices; closed rings wrap around.

  • bc_types (list of {"closed", "natural", "clamped"}, default: None ) –

    Start/end conditions for each LineString, defaults to clamped. If closed, the first vertex is reused as last vertex and an additional distances value has to be specified. If clamped, endpoint tangents are set to ensure the spline passes through the start and end points without deviation.

  • tolerance (float, default: None ) –

    Deprecated and ignored: points are spaced by arc length directly.

  • max_iterations (int, default: None ) –

    Deprecated and ignored: points are spaced by arc length directly.

  • sigma_units (('vertices', 'length'), default: "vertices" ) –

    Units of the Gaussian sigma: vertex index steps (default), or Euclidean length along the input line in coordinate units. With "length", each vertex is weighted by the length of line it stands for, so uneven vertex spacing does not bias the smoothing.

  • taubin_iterations (int, default: None ) –

    Number of Taubin lambda/mu smoothing iterations (lambda 0.5, mu -0.53) applied to the vertices before fitting, by default None. Each iteration is one lambda step and one mu step; it damps vertex jitter and keeps the size of curves drawn with more than about a dozen vertices per turn. Cannot be combined with a Gaussian sigma.

  • continuity (('c1', 'g2', 'c2'), default: "c1" ) –

    Smoothness where spline pieces join, by default "c1" (Catmull-Rom tangent continuity). "g2" makes curvature continuous and follows the "c1" shape closely; "c2" also makes the second derivative with respect to grid continuous. Both split each piece into three cubic pieces (Yuksel, SIGGRAPH 2026) and keep every vertex and its tangent.

Returns:

  • shapely.LineString or numpy.ndarray of shapely.LineString –

    Fitted CatmullRom curve as either a LineString.

linestrings_tangent_angles 

linestrings_tangent_angles(lines: list[LineString], gaussian_sigmas: list[float] | None = None, *, sigma_units: SigmaUnits = 'vertices', taubin_iterations: int | None = None) -> list[FloatArray]

linestrings_tangent_angles(lines: LineString, gaussian_sigmas: float | None = None, *, sigma_units: SigmaUnits = 'vertices', taubin_iterations: int | None = None) -> FloatArray

linestrings_tangent_angles(lines, gaussian_sigmas=None, *, sigma_units='vertices', taubin_iterations=None)

Compute tangent angles for a line.

Parameters:

  • lines (list of shapely.LineString) –

    LineStrings to be smoothed.

  • gaussian_sigmas (list of float, default: None ) –

    Standard deviation of a Gaussian kernel applied to each line's vertices before fitting, by default None (no smoothing). Open lines keep their end vertices; closed rings wrap around.

  • sigma_units (('vertices', 'length'), default: "vertices" ) –

    Units of the Gaussian sigma: vertex index steps (default), or Euclidean length along the input line in coordinate units. With "length", each vertex is weighted by the length of line it stands for, so uneven vertex spacing does not bias the smoothing.

  • taubin_iterations (int, default: None ) –

    Number of Taubin lambda/mu smoothing iterations (lambda 0.5, mu -0.53) applied to the vertices before fitting, by default None. Each iteration is one lambda step and one mu step; it damps vertex jitter and keeps the size of curves drawn with more than about a dozen vertices per turn. Cannot be combined with a Gaussian sigma.

Returns:

  • np.ndarray or list of np.ndarray –

    Signed tangent angles in radians. LinearRing inputs use periodic splines, so the first and last angles match.

smooth_polygon 

smooth_polygon(polygon, distance=None, n_pts=None, gaussian_sigma=None, *, tolerance=None, max_iterations=None, sigma_units='vertices', taubin_iterations=None, continuity='c1')

Smooth a (Multi)Polygon using Centripetal Catmull-Rom splines with uniform spacing.

Parameters:

  • polygon (Polygon or MultiPolygon) –

    (Multi)Polygon to be smoothed.

  • distance (float, default: None ) –

    Largest distance between consecutive points along the curve, by default None. Points are spaced evenly at the widest spacing that does not exceed it. You must specify either distance or n_pts.

  • n_pts (int, default: None ) –

    Number of points to be generated, by default None. You must specify either distance or n_pts.

  • gaussian_sigma (float, default: None ) –

    Standard deviation of a Gaussian kernel applied to each ring's vertices before fitting, by default None (no smoothing).

  • tolerance (float, default: None ) –

    Deprecated and ignored: points are spaced by arc length directly.

  • max_iterations (int, default: None ) –

    Deprecated and ignored: points are spaced by arc length directly.

  • sigma_units (('vertices', 'length'), default: "vertices" ) –

    Units of the Gaussian sigma: vertex index steps (default), or Euclidean length along the input line in coordinate units. With "length", each vertex is weighted by the length of line it stands for, so uneven vertex spacing does not bias the smoothing.

  • taubin_iterations (int, default: None ) –

    Number of Taubin lambda/mu smoothing iterations (lambda 0.5, mu -0.53) applied to the vertices before fitting, by default None. Each iteration is one lambda step and one mu step; it damps vertex jitter and keeps the size of curves drawn with more than about a dozen vertices per turn. Cannot be combined with a Gaussian sigma.

  • continuity (('c1', 'g2', 'c2'), default: "c1" ) –

    Smoothness where spline pieces join, by default "c1" (Catmull-Rom tangent continuity). "g2" makes curvature continuous and follows the "c1" shape closely; "c2" also makes the second derivative with respect to grid continuous. Both split each piece into three cubic pieces (Yuksel, SIGGRAPH 2026) and keep every vertex and its tangent.

Returns: