Inkscape: Geom::SBasisCurve Class Reference

Searching...

No Matches

Symmetric power basis curve. More...

#include <sbasis-curve.h>

Inheritance diagram for Geom::SBasisCurve:

Public Member Functions
	SBasisCurve (D2< SBasis > const &sb)

	SBasisCurve (Curve const &other)

Curve *	duplicate () const override
	Create an exact copy of this curve.

Point	initialPoint () const override
	Retrieve the start of the curve.

Point	finalPoint () const override
	Retrieve the end of the curve.

bool	isDegenerate () const override
	Check whether the curve has exactly zero length.

bool	isLineSegment () const override
	Check whether the curve is a line segment.

Point	pointAt (Coord t) const override
	Evaluate the curve at a specified time value.

std::vector< Point >	pointAndDerivatives (Coord t, unsigned n) const override
	Evaluate the curve and its derivatives.

Coord	valueAt (Coord t, Dim2 d) const override
	Evaluate one of the coordinates at the specified time value.

void	setInitial (Point const &v) override
	Change the starting point of the curve.

void	setFinal (Point const &v) override
	Change the ending point of the curve.

Rect	boundsFast () const override
	Quickly compute the curve's approximate bounding box.

Rect	boundsExact () const override
	Compute the curve's exact bounding box.

void	expandToTransformed (Rect &bbox, Affine const &transform) const override
	Expand the given rectangle to include the transformed curve, assuming it already contains its initial point.

OptRect	boundsLocal (OptInterval const &i, unsigned deg) const override

std::vector< Coord >	roots (Coord v, Dim2 d) const override
	Computes time values at which the curve intersects an axis-aligned line.

Coord	nearestTime (Point const &p, Coord from=0, Coord to=1) const override
	Compute a time value at which the curve comes closest to a specified point.

std::vector< Coord >	allNearestTimes (Point const &p, Coord from=0, Coord to=1) const override
	Compute time values at which the curve comes closest to a specified point.

Coord	length (Coord tolerance) const override
	Compute the arc length of this curve.

Curve *	portion (Coord f, Coord t) const override
	Create a curve that corresponds to a part of this curve.

void	operator*= (Affine const &m) override

Curve *	derivative () const override
	Create a derivative of this curve.

D2< SBasis >	toSBasis () const override
	Convert the curve to a symmetric power basis polynomial.

bool	isNear (Curve const &, Coord) const override
	Test whether two curves are approximately the same.

int	degreesOfFreedom () const override
	Return the number of independent parameters required to represent all variations of this curve.

virtual void	operator*= (Translate const &tr)

virtual void	operator*= (Scale const &s)

virtual void	operator*= (Rotate const &r)

virtual void	operator*= (HShear const &hs)

virtual void	operator*= (VShear const &vs)

virtual void	operator*= (Zoom const &z)

virtual void	operator*= (Affine const &m)=0

Public Member Functions inherited from Geom::Curve
virtual	~Curve ()

virtual Interval	timeRange () const
	Get the interval of allowed time values.

virtual Point	operator() (Coord t) const
	Evaluate the function at the specified time value.

OptRect	boundsLocal (OptInterval const &a) const
	Compute the bounding box of a part of the curve.

void	transform (Affine const &m)
	Transform this curve by an affine transformation.

virtual Curve *	transformed (Affine const &m) const
	Create a curve transformed by an affine transformation.

Curve *	portion (Interval const &i) const
	A version of that accepts an Interval.

virtual Curve *	reverse () const
	Create a reversed version of this curve.

Coord	nearestTime (Point const &p, Interval const &i) const
	A version that takes an Interval.

std::vector< Coord >	allNearestTimes (Point const &p, Interval const &i)
	A version that takes an Interval.

virtual int	winding (Point const &p) const
	Compute the partial winding number of this curve.

virtual std::vector< CurveIntersection >	intersect (Curve const &other, Coord eps=EPSILON) const
	Compute intersections with another curve.

virtual std::vector< CurveIntersection >	intersectSelf (Coord eps=EPSILON) const
	Compute intersections of this curve with itself.

virtual Point	unitTangentAt (Coord t, unsigned n=3) const
	Compute a vector tangent to the curve.

bool	operator== (Curve const &c) const
	Test equality of two curves.

virtual void	feed (PathSink &sink, bool moveto_initial) const
	Feed the curve to a PathSink.

Protected Member Functions
bool	_equalTo (Curve const &c) const override

Private Attributes
D2< SBasis >	inner

Detailed Description

Symmetric power basis curve.

Symmetric power basis (S-basis for short) polynomials are a versatile numeric representation of arbitrary continuous curves. They are the main representation of curves in 2Geom.

S-basis is defined for odd degrees and composed of the following polynomials:

\begin{align*} P_k^0(t) &= t^k (1-t)^{k+1} \\ P_k^1(t) &= t^{k+1} (1-t)^k \end{align*}

This can be understood more easily with the help of the chart below. Each square represents a product of a specific number of \(t\) and \((1-t)\) terms. Red dots are the canonical (monomial) basis, the green dots are the Bezier basis, and the blue dots are the S-basis, all of them of degree 7.

Illustration of the monomial, Bezier and symmetric power bases

The S-Basis has several important properties:

S-basis polynomials are closed under multiplication.
Evaluation is fast, using a modified Horner scheme.
Degree change is as trivial as in the monomial basis. To elevate, just add extra zero coefficients. To reduce the degree, truncate the terms in the highest powers. Compare this with Bezier curves, where degree change is complicated.
Conversion between S-basis and Bezier basis is numerically stable.

More in-depth information can be found in the following paper: J Sanchez-Reyes, "The symmetric analogue of the polynomial power basis". ACM Transactions on Graphics, Vol. 16, No. 3, July 1997, pages 319–357. http://portal.acm.org/citation.cfm?id=256162

Definition at line 80 of file sbasis-curve.h.

Constructor & Destructor Documentation

◆ SBasisCurve() [1/2]

Geom::SBasisCurve::SBasisCurve ( D2< SBasis > const & sb )

inlineexplicit

Definition at line 85 of file sbasis-curve.h.

◆ SBasisCurve() [2/2]

Geom::SBasisCurve::SBasisCurve ( Curve const & other )

inlineexplicit

Definition at line 86 of file sbasis-curve.h.

Member Function Documentation

◆ _equalTo()

bool Geom::SBasisCurve::_equalTo ( Curve const & c ) const

inlineoverrideprotectedvirtual

Implements Geom::Curve.

Definition at line 142 of file sbasis-curve.h.

References c, and inner.

◆ allNearestTimes()

std::vector< Coord > Geom::SBasisCurve::allNearestTimes	(	Point const &	p,
		Coord	from = `0`,
		Coord	to = `1`
	)		const

inlineoverridevirtual

Compute time values at which the curve comes closest to a specified point.

Parameters

p	Query point
a	Minimum time value to consider
b	Maximum time value to consider; \(a < b\)

Returns: Vector of points closest and equally far away from the query point

Reimplemented from Geom::Curve.

Definition at line 116 of file sbasis-curve.h.

References Geom::all_nearest_times(), and inner.

◆ boundsExact()

Rect Geom::SBasisCurve::boundsExact ( ) const

inlineoverridevirtual

Compute the curve's exact bounding box.

This method can be dramatically slower than boundsFast() depending on the curve type.

Returns: The smallest possible rectangle containing all of the curve's points.

Implements Geom::Curve.

Definition at line 105 of file sbasis-curve.h.

References Geom::bounds_exact(), and inner.

◆ boundsFast()

Rect Geom::SBasisCurve::boundsFast ( ) const

inlineoverridevirtual

Quickly compute the curve's approximate bounding box.

The resulting rectangle is guaranteed to contain all points belonging to the curve, but it might not be the smallest such rectangle. This method is usually fast.

Returns: A rectangle that contains all points belonging to the curve.

Implements Geom::Curve.

Definition at line 104 of file sbasis-curve.h.

References Geom::bounds_fast(), and inner.

◆ boundsLocal()

OptRect Geom::SBasisCurve::boundsLocal	(	OptInterval const &	i,
		unsigned	deg
	)		const

inlineoverridevirtual

Implements Geom::Curve.

Definition at line 109 of file sbasis-curve.h.

References Geom::bounds_local(), and inner.

Referenced by Geom::EllipticalArc::boundsLocal().

◆ degreesOfFreedom()

int Geom::SBasisCurve::degreesOfFreedom ( ) const

inlineoverridevirtual

Return the number of independent parameters required to represent all variations of this curve.

For example, for Bezier curves it returns the curve's order multiplied by 2.

Reimplemented from Geom::Curve.

Definition at line 137 of file sbasis-curve.h.

References inner.

◆ derivative()

Curve * Geom::SBasisCurve::derivative ( ) const

inlineoverridevirtual

Create a derivative of this curve.

It's best to think of the derivative in physical terms: if the curve describes the position of some object on the plane from time \(t=0\) to \(t=1\) as said in the introduction, then the curve's derivative describes that object's speed at the same times. The second derivative refers to its acceleration, the third to jerk, etc.

Returns: New curve \(\mathbf{D} = \mathbf{C}'\).

Implements Geom::Curve.

Definition at line 129 of file sbasis-curve.h.

References Geom::derivative(), and inner.

◆ duplicate()

Curve * Geom::SBasisCurve::duplicate ( ) const

inlineoverridevirtual

Create an exact copy of this curve.

Returns: Pointer to a newly allocated curve, identical to the original

Implements Geom::Curve.

Definition at line 88 of file sbasis-curve.h.

◆ expandToTransformed()

void Geom::SBasisCurve::expandToTransformed	(	Rect &	bbox,
		Affine const &	transform
	)		const

inlineoverridevirtual

Expand the given rectangle to include the transformed curve, assuming it already contains its initial point.

Parameters

bbox[in,out]	bbox The rectangle to expand; it is assumed to already contain (initialPoint() * transform).
transform	The transform to apply to the curve before taking its bounding box.

Implements Geom::Curve.

Definition at line 106 of file sbasis-curve.h.

References Geom::bounds_exact(), inner, and Geom::Curve::transform().

◆ finalPoint()

Point Geom::SBasisCurve::finalPoint ( ) const

inlineoverridevirtual

Retrieve the end of the curve.

Returns: The point corresponding to \(\mathbf{C}(1)\).

Implements Geom::Curve.

Definition at line 90 of file sbasis-curve.h.

References inner.

◆ initialPoint()

Point Geom::SBasisCurve::initialPoint ( ) const

inlineoverridevirtual

Retrieve the start of the curve.

Returns: The point corresponding to \(\mathbf{C}(0)\).

Implements Geom::Curve.

Definition at line 89 of file sbasis-curve.h.

References inner.

◆ isDegenerate()

bool Geom::SBasisCurve::isDegenerate ( ) const

inlineoverridevirtual

Check whether the curve has exactly zero length.

Returns: True if the curve's initial point is exactly the same as its final point, and it contains no other points (its value set contains only one element).

Implements Geom::Curve.

Definition at line 91 of file sbasis-curve.h.

References inner.

◆ isLineSegment()

bool Geom::SBasisCurve::isLineSegment ( ) const

inlineoverridevirtual

Check whether the curve is a line segment.

Reimplemented from Geom::Curve.

Definition at line 92 of file sbasis-curve.h.

References inner, and Geom::X.

◆ isNear()

bool Geom::SBasisCurve::isNear	(	Curve const &	c,
		Coord	precision
	)		const

inlineoverridevirtual

Test whether two curves are approximately the same.

Implements Geom::Curve.

Definition at line 133 of file sbasis-curve.h.

◆ length()

Coord Geom::SBasisCurve::length ( Coord tolerance ) const

inlineoverridevirtual

Compute the arc length of this curve.

For a curve \(\mathbf{C}(t) = (C_x(t), C_y(t))\), arc length is defined for 2D curves as

\[ \ell = \int_{0}^{1} \sqrt { [C_x'(t)]^2 + [C_y'(t)]^2 }\, \text{d}t \]

In other words, we divide the curve into infinitely small linear segments and add together their lengths. Of course we can't subdivide the curve into infinitely many segments on a computer, so this method returns an approximation. Not that there is usually no closed form solution to such integrals, so this method might be slow.

Parameters

tolerance Maximum allowed error

Returns: Total distance the curve's value travels on the plane when going from 0 to 1

Reimplemented from Geom::Curve.

Definition at line 121 of file sbasis-curve.h.

References inner.

◆ nearestTime()

Coord Geom::SBasisCurve::nearestTime	(	Point const &	p,
		Coord	a = `0`,
		Coord	b = `1`
	)		const

inlineoverridevirtual

Compute a time value at which the curve comes closest to a specified point.

The first value with the smallest distance is returned if there are multiple such points.

Parameters

p	Query point
a	Minimum time value to consider
b	Maximum time value to consider; \(a < b\)

Returns: \(q \in [a, b]: ||\mathbf{C}(q) - \mathbf{p}|| = \inf(\{r \in \mathbb{R} : ||\mathbf{C}(r) - \mathbf{p}||\})\)

Reimplemented from Geom::Curve.

Definition at line 113 of file sbasis-curve.h.

References inner, and Geom::nearest_time().

◆ operator*=() [1/8]

void Geom::SBasisCurve::operator*= ( Affine const & m )

inlineoverridevirtual

Implements Geom::Curve.

Definition at line 127 of file sbasis-curve.h.

References inner.

◆ operator*=() [2/8]

virtual void Geom::Curve::operator*= ( Affine const & m )

virtual

Implements Geom::Curve.

◆ operator*=() [3/8]

virtual void Geom::Curve::operator*= ( HShear const & hs )

inlinevirtual

Reimplemented from Geom::Curve.

Definition at line 200 of file curve.h.

◆ operator*=() [4/8]

virtual void Geom::Curve::operator*= ( Rotate const & r )

inlinevirtual

Reimplemented from Geom::Curve.

Definition at line 199 of file curve.h.

◆ operator*=() [5/8]

virtual void Geom::Curve::operator*= ( Scale const & s )

inlinevirtual

Reimplemented from Geom::Curve.

Definition at line 198 of file curve.h.

◆ operator*=() [6/8]

virtual void Geom::Curve::operator*= ( Translate const & tr )

inlinevirtual

Reimplemented from Geom::Curve.

Definition at line 197 of file curve.h.

◆ operator*=() [7/8]

virtual void Geom::Curve::operator*= ( VShear const & vs )

inlinevirtual

Reimplemented from Geom::Curve.

Definition at line 201 of file curve.h.

◆ operator*=() [8/8]

virtual void Geom::Curve::operator*= ( Zoom const & z )

inlinevirtual

Reimplemented from Geom::Curve.

Definition at line 202 of file curve.h.

◆ pointAndDerivatives()

std::vector< Point > Geom::SBasisCurve::pointAndDerivatives	(	Coord	t,
		unsigned	n
	)		const

inlineoverridevirtual

Evaluate the curve and its derivatives.

This will return a vector that contains the value of the curve and the specified number of derivatives. However, the returned vector might contain less elements than specified if some derivatives do not exist.

Parameters

t	Time value
n	The number of derivatives to compute

Returns: Vector of at most \(n+1\) elements of the form \([\mathbf{C}(t), \mathbf{C}'(t), \mathbf{C}''(t), \ldots]\)

Implements Geom::Curve.

Definition at line 94 of file sbasis-curve.h.

References inner.

◆ pointAt()

Point Geom::SBasisCurve::pointAt ( Coord t ) const

inlineoverridevirtual

Evaluate the curve at a specified time value.

Parameters

t	Time value

Returns: \(\mathbf{C}(t)\)

Reimplemented from Geom::Curve.

Definition at line 93 of file sbasis-curve.h.

References inner.

◆ portion()

Curve * Geom::SBasisCurve::portion	(	Coord	a,
		Coord	b
	)		const

inlineoverridevirtual

Create a curve that corresponds to a part of this curve.

For \(a > b\), the returned portion will be reversed with respect to the original. The returned curve will always be of the same type.

Parameters

a	Beginning of the interval specifying the portion of the curve
b	End of the interval

Returns

New curve \(\mathbf{D}\) such that:

\(\mathbf{D}(0) = \mathbf{C}(a)\)
\(\mathbf{D}(1) = \mathbf{C}(b)\)
\(\mathbf{D}[ [0, 1] ] = \mathbf{C}[ [a?b] ]\), where \([a?b] = [\min(a, b), \max(a, b)]\)

Implements Geom::Curve.

Definition at line 122 of file sbasis-curve.h.

References inner, and Geom::portion().

◆ roots()

std::vector< Coord > Geom::SBasisCurve::roots	(	Coord	v,
		Dim2	d
	)		const

inlineoverridevirtual

Computes time values at which the curve intersects an axis-aligned line.

Parameters

v	The coordinate of the line
d	Which axis the coordinate is on. X means a vertical line, Y a horizontal line.

Implements Geom::Curve.

Definition at line 112 of file sbasis-curve.h.

References inner, and Geom::roots().

◆ setFinal()

void Geom::SBasisCurve::setFinal ( Point const & v )

inlineoverridevirtual

Change the ending point of the curve.

After calling this method, it is guaranteed that \(\mathbf{C}(0) = \mathbf{p}\), and the curve is still continuous. The precise new shape of the curve varies with curve type.

Parameters

p	New ending point of the curve

Implements Geom::Curve.

Definition at line 101 of file sbasis-curve.h.

References inner.

◆ setInitial()

void Geom::SBasisCurve::setInitial ( Point const & v )

inlineoverridevirtual

Change the starting point of the curve.

After calling this method, it is guaranteed that \(\mathbf{C}(0) = \mathbf{p}\), and the curve is still continuous. The precise new shape of the curve varies with curve type.

Parameters

p	New starting point of the curve

Implements Geom::Curve.

Definition at line 98 of file sbasis-curve.h.

References inner.

◆ toSBasis()

D2< SBasis > Geom::SBasisCurve::toSBasis ( ) const

inlineoverridevirtual

Convert the curve to a symmetric power basis polynomial.

Symmetric power basis polynomials (S-basis for short) are numerical representations of curves with excellent numerical properties. Most high level operations provided by 2Geom are implemented in terms of S-basis operations, so every curve has to provide a method to convert it to an S-basis polynomial on two variables. See SBasis class reference for more information.

Implements Geom::Curve.

Definition at line 132 of file sbasis-curve.h.

References inner.

◆ valueAt()

Coord Geom::SBasisCurve::valueAt	(	Coord	t,
		Dim2	d
	)		const

inlineoverridevirtual

Evaluate one of the coordinates at the specified time value.

Parameters

t	Time value
d	The dimension to evaluate

Returns: The specified coordinate of \(\mathbf{C}(t)\)

Reimplemented from Geom::Curve.

Definition at line 97 of file sbasis-curve.h.

References inner.

Member Data Documentation

◆ inner

D2<SBasis> Geom::SBasisCurve::inner

private

Definition at line 82 of file sbasis-curve.h.

Referenced by _equalTo(), allNearestTimes(), boundsExact(), boundsFast(), boundsLocal(), degreesOfFreedom(), derivative(), expandToTransformed(), finalPoint(), initialPoint(), isDegenerate(), isLineSegment(), length(), nearestTime(), operator*=(), pointAndDerivatives(), pointAt(), portion(), roots(), setFinal(), setInitial(), toSBasis(), and valueAt().

The documentation for this class was generated from the following file:

/builds/inkscape/inkscape/src/3rdparty/2geom/include/2geom/sbasis-curve.h

Public Member Functions

Protected Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ SBasisCurve() [1/2]

◆ SBasisCurve() [2/2]

Member Function Documentation

◆ _equalTo()

◆ allNearestTimes()

◆ boundsExact()

◆ boundsFast()

◆ boundsLocal()

◆ degreesOfFreedom()

◆ derivative()

◆ duplicate()

◆ expandToTransformed()

◆ finalPoint()

◆ initialPoint()

◆ isDegenerate()

◆ isLineSegment()

◆ isNear()

◆ length()

◆ nearestTime()

◆ operator*=() [1/8]

◆ operator*=() [2/8]

◆ operator*=() [3/8]

◆ operator*=() [4/8]

◆ operator*=() [5/8]

◆ operator*=() [6/8]

◆ operator*=() [7/8]

◆ operator*=() [8/8]

◆ pointAndDerivatives()

◆ pointAt()

◆ portion()

◆ roots()

◆ setFinal()

◆ setInitial()

◆ toSBasis()

◆ valueAt()

Member Data Documentation

◆ inner