# Core Concepts

## A Point

Beziers.py provides a rich abstraction over the concept of a two-dimensional point, containing the kind of methods that someone manipulating Bezier curves would find handy.

class beziers.point.Point(x, y)

  Bases: `object`

  A representation of a point within the Beziers world.

  Here are some things you can do with points. You can interpret them as vectors, and add them together:

      >>> a = Point(5,5)
      >>> b = Point(10,10)
      >>> a + b
      <15.0,15.0>

  You can multiply them by a scalar to scale them:

      >>> a * 2
      <10.0,10.0>

  You can adjust them:

      >>> a += b
      >>> a
      <15.0,15.0>

  If you’re using Python 3, you can abuse operator overloading and compute the dot product of two vectors:

      >>> a = Point(5,5)
      >>> b = Point(10,10)
      >>> a @ b
      100.0

  classmethod fromRepr(text: str) → Point

    Create a new point from a string representation.

  dot(other: Point) → float

    Compute the dot product of two points, interpreted as vectors.

  clone() → Point

    Clone a point, returning a new object with the same co-ordinates.

  rounded() → Point

    Return a point with the co-ordinates truncated to integers

  lerp(other: Point, t: float) → Point

    Interpolate between two points, at time t.

  property squareMagnitude: float

    Interpreting this point as a vector, returns the squared magnitude (Euclidean length) of the vector.

  property magnitude: float

    Interpreting this point as a vector, returns the magnitude (Euclidean length) of the vector.

  toUnitVector() → Point

    Divides this point by its magnitude, returning a vector of length 1.

  property angle: float

    Interpreting this point as a vector, returns the angle in radians of the vector.

  property slope: float

    Returns slope y/x

  classmethod fromAngle(angle: float) → Point

    Given an angle in radians, return a unit vector representing that angle.

  rotated(around: Point, by: float) → Point

    Return a new point found by rotating this point around another point, by an angle given in radians.

  rotate(around: Point, by: float)

    Mutate this point by rotating it around another point, by an angle given in radians.

  squareDistanceFrom(other: Point) → float

    Returns the squared Euclidean distance between this point and another.

  distanceFrom(other: Point) → float

    Returns the Euclidean distance between this point and another.

  transformed(transformation: AffineTransformation) → Point

    Returns a new point, transformed by the given transformation.

  transform(transformation: AffineTransformation)

    Mutate this point by transforming it by the given transformation.

## A Segment

class beziers.segment.Segment

  Bases: `IntersectionsMixin`, `SampleMixin`, `object`

  A segment is part of a path. Although this package is called beziers.py, it’s really for font people, and paths in the font world are made up of cubic Bezier curves, lines and (if you’re dealing with TrueType) quadratic Bezier curves. Each of these things is represented as an object derived from the Segment base class. So, when you inspect the path in the segment representation, you will get a list of CubicBezier, Line and QuadraticBezier objects, all of which derive from Segment.

  Because of this, a Segment can have two, three or four elements: lines have two end points; quadratic Beziers have a start, a control point and an end point; cubic have a start, two control points and an end point.

  You can pretend that a Segment object is an array and index it like one:

      q = CubicBezier(
        Point(122,102), Point(35,200), Point(228,145), Point(190,46)
      )

      start, cp1, cp2, end = q[0],q[1],q[2],q[3]

  You can also access the start and end points like so:

      start = q.start
      end = q.end

  clone() → Segment

    Returns a new Segment which is a copy of this segment.

  round() → None

    Rounds the points of segment to integer coordinates.

  property order: int

    Returns the order of the segment. i.e. 2 for a line, 3 for a quadratic, 4 for a cubic.

  property start: Point

    Returns a Point object representing the start of this segment.

  property end: Point

    Returns a Point object representing the end of this segment.

  property startAngle: float

    Returns the angle of the start of the segment in radians.

  property endAngle: float

    Returns the angle of the end of the segment in radians.

  tangentAtTime(t: float) → Point

    Returns a Point representing the unit vector of tangent at time t.

  normalAtTime(t: float) → Point

    Returns a Point representing the normal (rotated tangent) at time t.

  translated(vector: Point) → Segment

    Returns a new Segment object representing the translation of this segment by the given vector. i.e.:

        >>> l = Line(Point(0,0), Point(10,10))
        >>> l.translated(Point(5,5))
        L<<5.0,5.0>--<15.0,15.0>>
        >>> l
        L<<0.0,0.0>--<10.0,10.0>>

  rotated(around: Point, by: float)

    Returns a new Segment object representing the rotation of this segment around the given point and by the given angle. i.e.:

        >>> l = Line(Point(0,0), Point(10,10))
        >>> l.rotated(Point(5,5), math.pi/2)
        L<<10.0,-8.881784197e-16>--<-8.881784197e-16,10.0>>

  scaled(bx: float) → Segment

    Returns a new Segment object representing the scaling of this segment by the given magnification. i.e.:

        >>> l = Line(Point(0,0), Point(10,10))
        >>> l.scaled(2)
        L<<0,0>--<20,20>>

  transformed(transformation: AffineTransformation) → Segment

    Returns a new Segment object transformed by the given AffineTransformation matrix.

  alignmentTransformation() → AffineTransformation

    Returns an AffineTransformation object representing the transformation required to align the segment to the origin. i.e. with the first point translated to the origin (0,0) and the last point with y=0.

  aligned() → Segment

    Returns a new Segment object aligned to the origin. i.e. with the first point translated to the origin (0,0) and the last point with y=0. Obviously, for a Line this is a bit pointless, but it’s quite handy for higher-order curves.

  lengthAtTime(t: float) → float

    Returns the length of the subset of the path from the start up to the point t (0->1), where 1 is the end of the whole curve.

  reversed() → Segment

    Returns a new segment with the points reversed.

  bounds() → BoundingBox

    Returns a BoundingBox object for this segment.

  property hasLoop: bool

    Returns True if the segment has a loop. (Only possible for cubics.)

## A Line

class beziers.line.Line(start: Point, end: Point)

  Bases: `Segment`

  Represents a line segment within a Bezier path.

  classmethod fromRepr(text: str) → Line

    Create a new line segment from a string representation.

  pointAtTime(t: float) → Point

    Returns the point at time t (0->1) along the line.

  tangentAtTime(t: float) → Point

    Returns the tangent at time t (0->1) along the line.

  normalAtTime(t: float) → Point

    Returns the normal at time t (0->1) along the line.

  curvatureAtTime(_t: float) → float

    Returns the C curvature at time t.

  splitAtTime(t: float) → Tuple[Line, Line]

    Returns two segments, dividing the given segment at a point t (0->1) along the line.

  tOfPoint(point: Point, its_on_the_line_i_swear=False) → float

    Returns the t (0->1) value of the given point, assuming it lies on the line, or -1 if it does not.

  flatten(_degree=8) → List[Line]
  property slope: float

    Returns the slope of the line.

  property intercept: float

    Returns the y-intercept of the line.

  property length: float

    Returns the length of the line.

  findExtremes() → List[Point]

    Returns the extrema of the line.

  property area: float

    Returns the signed area of the line.

## A QuadraticBezier curve

class beziers.quadraticbezier.QuadraticBezier(start, c1, end)

  Bases: `ArcLengthMixin`, `Segment`

  classmethod fromRepr(text)
  pointAtTime(t)

    Returns the point at time t (0->1) along the curve.

  tOfPoint(p)

    Returns the time t (0->1) of a point on the curve.

  splitAtTime(t)

    Returns two segments, dividing the given segment at a point t (0->1) along the curve.

  derivative()

    Returns a Line representing the derivative of this curve.

  flatten(degree=8)
  findExtremes()

    Returns a list of time t values for extremes of the curve.

  property area

    Returns the signed area between the curve and the y-axis

  toCubicBezier()

    Converts the quadratic bezier to a CubicBezier

## A CubicBezier curve

class beziers.cubicbezier.CubicBezier(start: Point, c1: Point, c2: Point, end: Point)

  Bases: `ArcLengthMixin`, `Segment`

  A representation of a cubic bezier curve.

  classmethod fromRepr(text: str)

    Create a new cubic bezier curve from a string representation.

  pointAtTime(t: float) → Point

    Returns the point at time t (0->1) along the curve.

  tOfPoint(p: Point) → float

    Returns the time t (0->1) of a point on the curve.

  splitAtTime(t: float) → Tuple[CubicBezier, CubicBezier]

    Returns two segments, dividing the given segment at a point t (0->1) along the curve.

  join(other)

    Not currently implemented: join two CubicBezier together.

  toQuadratic()

    Not currently implemented: reduce this to a QuadraticBezier.

  derivative() → QuadraticBezier

    Returns a QuadraticBezier representing the derivative of this curve.

  flatten(degree=8) → List[Line]

    Flattens the curve into a list of Line segments.

    Args:

      degree (int): The degree of flattening to perform.

  findExtremes(inflections=False) → List[float]

    Returns a list of time t values for extremes of the curve.

  curvatureAtTime(t: float) → float

    Returns the C curvature at time t.

  property tunniPoint: Point

    Returns the Tunni point of this Bezier (the intersection of the handles).

  balance() → None

    Perform Tunni balancing on this Bezier.

  property hasLoop: bool

    Returns True if the curve has a loop.

  property area: float

    Returns the signed area between the curve and the y-axis

## A BoundingBox

class beziers.boundingbox.SupportsBounds(*args, **kwargs)

  Bases: `Protocol`

  bounds() → BoundingBox

class beziers.boundingbox.BoundingBox

  Bases: `object`

  A representation of a rectangle within the Beziers world, used to store bounding boxes.

  Args:

    bl (Point): The bottom-left corner of the bounding box. tr (Point): The top-right corner of the bounding box.

  bounds() → BoundingBox

    Determine the bounding box - returns the bounding box itself.

  property area: float

    Returns the area of the bounding box.

  property left: float

    Returns the X coordinate of the left edge of the box.

  property right: float

    Returns the X coordinate of the right edge of the box.

  property top: float

    Returns the Y coordinate of the top edge of the box.

  property bottom: float

    Returns the Y coordinate of the bottom edge of the box.

  property width: float

    Returns the width of the box.

  property height: float

    Returns the height of the box.

  property centroid: Point

    Returns a Point representing the centroid of the box.

  extend(other: BoundingBox | Point | SupportsBounds) → None

    Add an object to the bounding box. Object can be a Point, another BoundingBox, or something which has a bounds() method.

  translated(point: Point) → BoundingBox

    Returns a new BoundingBox translated by the vector

  includes(point: Point) → bool

    Returns True if the point is included in this bounding box.

  overlaps(other: BoundingBox) → bool

    Returns True if the given bounding box overlaps with this bounding box.

  addMargin(size: float) → None

    Adds a few units of margin around the edges of the bounding box.

# Helpful utility classes

## Geometric shapes

beziers.path.geometricshapes.Circle(x_radius, origin=None, superness=0.5522847498307935)

  Returns a path representing a circle of given radius. You can specify the origin as a Point and the superness of the circle.

beziers.path.geometricshapes.Ellipse(x_radius, y_radius, origin=None, superness=0.5522847498307935)

  Returns a path representing an ellipse of given x and y radii. You can specify the origin as a Point and the superness of the ellipse.

beziers.path.geometricshapes.Rectangle(width, height, origin=None)

  Returns a path representing an rectangle of given width and height. You can specify the origin as a Point.

beziers.path.geometricshapes.Square(width, origin=None)

  Returns a path representing a square of given width. You can specify the origin as a Point.