Class: QgsCircle

Circle geometry type.

A circle is defined by a center point with a radius and an azimuth. The azimuth is the north angle to the semi-major axis, in degrees. By default, the semi-major axis is oriented to the north (0 degrees).

Class Hierarchy

Inheritance diagram of qgis.core.QgsCircle

Base classes

QgsEllipse

Ellipse geometry type.

Methods

asGml2

Returns a GML2 representation of the geometry.

asGml3

Returns a GML3 representation of the geometry.

contains

Returns True if the circle contains the point.

innerTangents

Calculates the inner tangent points between this circle and an other circle.

intersections

Calculates the intersections points between this circle and an other circle.

northQuadrant

The four quadrants of the ellipse.

outerTangents

Calculates the outer tangent points between this circle and an other circle.

radius

Returns the radius of the circle

setRadius

Sets the radius of the circle

tangentToPoint

Calculates the tangent points between this circle and the point p.

toCircularString

Returns a circular string from the circle.

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsCircle. See the FAQ for more details.

setSemiMajorAxis

Inherited method.

setSemiMinorAxis

Inherited method.

Static Methods

calculateSegments

Calculates the number of segments needed to approximate a circle.

calculateSegmentsAdaptive

calculateSegmentsByAreaError

calculateSegmentsByConstant

calculateSegmentsStandard

from2Points

Constructs a circle by 2 points on the circle.

from3Points

Constructs a circle by 3 points on the circle.

from3Tangents

Constructs a circle by 3 tangents on the circle (aka inscribed circle of a triangle).

from3TangentsMulti

Returns an array of circle constructed by 3 tangents on the circle (aka inscribed circle of a triangle).

fromCenterDiameter

Constructs a circle by a center point and a diameter.

fromCenterPoint

Constructs a circle by a center point and another point.

fromExtent

Constructs a circle by an extent (aka bounding box / QgsRectangle).

minimalCircleFrom3Points

Constructs the smallest circle from 3 points.

class qgis.core.QgsCircle[source]

Bases: QgsEllipse

__init__()
__init__(center: QgsPoint, radius: float, azimuth: float = 0)

Constructs a circle by defining all the members.

Parameters:
  • center (QgsPoint) – The center of the circle.

  • radius (float) – The radius of the circle.

  • azimuth (float = 0) – Angle in degrees started from the North to the first quadrant.

__init__(a0: QgsCircle)
Parameters:

a0 (QgsCircle)

asGml2(self, doc: QDomDocument, precision: int = 17, ns: str | None = '', axisOrder: QgsAbstractGeometry.AxisOrder = QgsAbstractGeometry.AxisOrder.XY) QDomElement[source]

Returns a GML2 representation of the geometry. Since GML2 does not supports curve, it will be converted to a LineString.

Parameters:
  • doc (QDomDocument) – DOM document

  • precision (int = 17) – number of decimal places for coordinates

  • ns (Optional[str] = '') – XML namespace

  • axisOrder (QgsAbstractGeometry.AxisOrder = QgsAbstractGeometry.AxisOrder.XY) – Axis order for generated GML

See also

asGml3()

Return type:

QDomElement

asGml3(self, doc: QDomDocument, precision: int = 17, ns: str | None = '', axisOrder: QgsAbstractGeometry.AxisOrder = QgsAbstractGeometry.AxisOrder.XY) QDomElement[source]

Returns a GML3 representation of the geometry.

From the GML3 description: A Circle is an arc whose ends coincide to form a simple closed loop. The three control points shall be distinct non-co-linear points for the circle to be unambiguously defined. The arc is simply extended past the third control point until the first control point is encountered.

Coordinates are taken from quadrant North, East and South.

Parameters:
  • doc (QDomDocument) – DOM document

  • precision (int = 17) – number of decimal places for coordinates

  • ns (Optional[str] = '') – XML namespace

  • axisOrder (QgsAbstractGeometry.AxisOrder = QgsAbstractGeometry.AxisOrder.XY) – Axis order for generated GML

See also

asGml2()

Return type:

QDomElement

static calculateSegments(radius: float, parameter: float, minSegments: int, method: Qgis.SegmentCalculationMethod) int[source]

Calculates the number of segments needed to approximate a circle.

Parameters:
  • radius (float) – Circle radius. Must be positive; if <= 0, minSegments is returned.

  • parameter (float) – Maximum tolerance allowed for the deviation between the circle and its approximation, except for the ConstantDensity method where it is a constant. If <= 0, a default value of 0.01 is used.

  • minSegments (int) – Minimum number of segments to use. If < 3, it is set to 3.

  • method (Qgis.SegmentCalculationMethod) – Calculation method to use.

Return type:

int

Returns:

Number of segments needed for the approximation.

pre radius must be strictly positive; otherwise, the function returns minSegments. pre parameter should be positive; if not, it defaults to 0.01. pre minSegments should be at least 3; if less, it is clamped to 3.

Added in version 3.44.

static calculateSegmentsAdaptive()[source]
static calculateSegmentsByAreaError()[source]
static calculateSegmentsByConstant()[source]
static calculateSegmentsStandard()[source]
contains(self, point: QgsPoint, epsilon: float = 1e-08) bool[source]

Returns True if the circle contains the point.

Parameters:
  • point (QgsPoint)

  • epsilon (float = 1e-08)

Return type:

bool

static from2Points(pt1: QgsPoint, pt2: QgsPoint) QgsCircle[source]

Constructs a circle by 2 points on the circle. The center point can have m value which is the result from the midpoint operation between pt1 and pt2. Z dimension is also supported and is retrieved from the first 3D point amongst pt1 and pt2. The radius is calculated from the 2D distance between pt1 and pt2. The azimuth is the angle between pt1 and pt2.

Parameters:
Return type:

QgsCircle

static from3Points(pt1: QgsPoint, pt2: QgsPoint, pt3: QgsPoint, epsilon: float = 1e-08) QgsCircle[source]

Constructs a circle by 3 points on the circle. M value is dropped for the center point. Z dimension is supported and is retrieved from the first 3D point amongst pt1, pt2 and pt3. The azimuth always takes the default value. If the points are colinear an empty circle is returned.

Parameters:
  • pt1 (QgsPoint) – First point.

  • pt2 (QgsPoint) – Second point.

  • pt3 (QgsPoint) – Third point.

  • epsilon (float = 1e-08) – Value used to compare point.

Return type:

QgsCircle

static from3Tangents(pt1_tg1: QgsPoint, pt2_tg1: QgsPoint, pt1_tg2: QgsPoint, pt2_tg2: QgsPoint, pt1_tg3: QgsPoint, pt2_tg3: QgsPoint, epsilon: float = 1e-08, pos: QgsPoint = QgsPoint()) QgsCircle[source]

Constructs a circle by 3 tangents on the circle (aka inscribed circle of a triangle). Z and m values are dropped for the center point. The azimuth always takes the default value.

Parameters:
  • pt1_tg1 (QgsPoint) – First point of the first tangent.

  • pt2_tg1 (QgsPoint) – Second point of the first tangent.

  • pt1_tg2 (QgsPoint) – First point of the second tangent.

  • pt2_tg2 (QgsPoint) – Second point of the second tangent.

  • pt1_tg3 (QgsPoint) – First point of the third tangent.

  • pt2_tg3 (QgsPoint) – Second point of the third tangent.

  • epsilon (float = 1e-08) – Value used to compare point.

  • pos (QgsPoint = QgsPoint()) – Point to determine which circle use in case of multi return. If the solution is not unique and pos is an empty point, an empty circle is returned. – This case happens only when two tangents are parallels. (since QGIS 3.18)

Example

# [(0 0), (5 0)] and [(5 5), (10 5)] are parallels
QgsCircle.from3Tangents(QgsPoint(0, 0), QgsPoint(5, 0), QgsPoint(5, 5), QgsPoint(10, 5), QgsPoint(2.5, 0), QgsPoint(7.5, 5))
# <QgsCircle: Empty>
QgsCircle.from3Tangents(QgsPoint(0, 0), QgsPoint(5, 0), QgsPoint(5, 5), QgsPoint(10, 5), QgsPoint(2.5, 0), QgsPoint(7.5, 5), pos=QgsPoint(2, 0))
# <QgsCircle: Circle (Center: Point (1.46446609406726203 2.49999999999999911), Radius: 2.5, Azimuth: 0)>
QgsCircle.from3Tangents(QgsPoint(0, 0), QgsPoint(5, 0), QgsPoint(5, 5), QgsPoint(10, 5), QgsPoint(2.5, 0), QgsPoint(7.5, 5), pos=QgsPoint(3, 0))
# <QgsCircle: Circle (Center: Point (8.53553390593273775 2.5), Radius: 2.5, Azimuth: 0)>
rtype:

QgsCircle

static from3TangentsMulti(pt1_tg1: QgsPoint, pt2_tg1: QgsPoint, pt1_tg2: QgsPoint, pt2_tg2: QgsPoint, pt1_tg3: QgsPoint, pt2_tg3: QgsPoint, epsilon: float = 1e-08, pos: QgsPoint = QgsPoint()) List[QgsCircle]

Returns an array of circle constructed by 3 tangents on the circle (aka inscribed circle of a triangle).

The vector can contain 0, 1 or 2 circles:

  • 0: Impossible to construct a circle from 3 tangents (three parallel tangents)

  • 1: The three tangents make a triangle or when two tangents are parallel there are two possible circles (see examples). If pos is not an empty point, we use its coordinates to determine which circle will be returned. More precisely the circle that will be returned will be the one whose center is on the same side as pos relative to the third tangent.

  • 2: Returns both solutions when two tangents are parallel (this implies that pos is an empty point).

Z and m values are dropped for the center point. The azimuth always takes the default value.

Parameters:
  • pt1_tg1 (QgsPoint) – First point of the first tangent.

  • pt2_tg1 (QgsPoint) – Second point of the first tangent.

  • pt1_tg2 (QgsPoint) – First point of the second tangent.

  • pt2_tg2 (QgsPoint) – Second point of the second tangent.

  • pt1_tg3 (QgsPoint) – First point of the third tangent.

  • pt2_tg3 (QgsPoint) – Second point of the third tangent.

  • epsilon (float = 1e-08) – Value used to compare point.

  • pos (QgsPoint = QgsPoint()) – (optional) Point to determine which circle use in case of multi return.

See also

from3Tangents()

Example

# [(0 0), (5 0)] and [(5 5), (10 5)] are parallels
QgsCircle.from3TangentsMulti(QgsPoint(0, 0), QgsPoint(5, 0), QgsPoint(5, 5), QgsPoint(10, 5), QgsPoint(2.5, 0), QgsPoint(7.5, 5))
# [<QgsCircle: Circle (Center: Point (8.53553390593273775 2.5), Radius: 2.5, Azimuth: 0)>, <QgsCircle: Circle (Center: Point (1.46446609406726203 2.49999999999999911), Radius: 2.5, Azimuth: 0)>]
QgsCircle.from3TangentsMulti(QgsPoint(0, 0), QgsPoint(5, 0), QgsPoint(5, 5), QgsPoint(10, 5), QgsPoint(2.5, 0), QgsPoint(7.5, 5), pos=QgsPoint(2, 0))
# [<QgsCircle: Circle (Center: Point (1.46446609406726203 2.49999999999999911), Radius: 2.5, Azimuth: 0)>]
QgsCircle.from3TangentsMulti(QgsPoint(0, 0), QgsPoint(5, 0), QgsPoint(5, 5), QgsPoint(10, 5), QgsPoint(2.5, 0), QgsPoint(7.5, 5), pos=QgsPoint(3, 0))
# [<QgsCircle: Circle (Center: Point (8.53553390593273775 2.5), Radius: 2.5, Azimuth: 0)>]
# [(0 0), (5 0)], [(5 5), (10 5)] and [(15 5), (20 5)] are parallels
QgsCircle.from3TangentsMulti(QgsPoint(0, 0), QgsPoint(5, 0), QgsPoint(5, 5), QgsPoint(10, 5), QgsPoint(15, 5), QgsPoint(20, 5))
# []
rtype:

List[QgsCircle]

static fromCenterDiameter(center: QgsPoint, diameter: float, azimuth: float = 0) QgsCircle[source]

Constructs a circle by a center point and a diameter. The center point keeps z and m values from center.

Parameters:
  • center (QgsPoint) – Center point.

  • diameter (float) – Diameter of the circle.

  • azimuth (float = 0) – Azimuth of the circle.

Return type:

QgsCircle

static fromCenterPoint(center: QgsPoint, pt1: QgsPoint) QgsCircle[source]

Constructs a circle by a center point and another point. The center point keeps z and m values from center. Axes are calculated from the 2D distance between center and pt1. The azimuth is the angle between center and pt1.

Parameters:
Return type:

QgsCircle

static fromExtent(pt1: QgsPoint, pt2: QgsPoint) QgsCircle[source]

Constructs a circle by an extent (aka bounding box / QgsRectangle). The center point can have m value which is the result from the midpoint operation between pt1 and pt2. Z dimension is also supported and is retrieved from the first 3D point amongst pt1 and pt2. Axes are calculated from the 2D distance between pt1 and pt2. The azimuth always takes the default value.

Parameters:
Return type:

QgsCircle

innerTangents(self, other: QgsCircle)[source]

Calculates the inner tangent points between this circle and an other circle.

The inner tangent points correspond to the points at which the two lines which are drawn so that they are tangential to both circles but on different sides, touching the circles and crossing each other.

The first tangent line is described by the points stored in line1P1 and line1P2, and the second line is described by the points stored in line2P1 and line2P2.

Returns the number of tangents (either 0 or 2).

Note

This method is 2D only and does not consider the z-value of the circle.

See also

tangentToPoint()

See also

outerTangents()

Added in version 3.6.

Parameters:

other (QgsCircle) -> (int)

intersections(self, other: QgsCircle, useZ: bool = False)[source]

Calculates the intersections points between this circle and an other circle.

If found, the intersection points will be stored in intersection1 and intersection2.

By default this method does not consider any z values and instead treats the circles as 2-dimensional. If useZ is set to True, then an intersection will only occur if the z values of both circles are equal. In this case the points returned for intersection1 and intersection2 will contain the z value of the circle intersections.

Returns:

number of intersection points found.

Added in version 3.2.

Parameters:
  • other (QgsCircle)

  • useZ (bool = False) -> (int)

static minimalCircleFrom3Points(pt1: QgsPoint, pt2: QgsPoint, pt3: QgsPoint, epsilon: float = 1e-08) QgsCircle[source]

Constructs the smallest circle from 3 points. Z and m values are dropped for the center point. The azimuth always takes the default value. If the points are colinear an empty circle is returned.

Parameters:
  • pt1 (QgsPoint) – First point.

  • pt2 (QgsPoint) – Second point.

  • pt3 (QgsPoint) – Third point.

  • epsilon (float = 1e-08) – Value used to compare point.

Return type:

QgsCircle

northQuadrant(self) List[QgsPoint]

The four quadrants of the ellipse. They are oriented and started from North.

Return type:

List[QgsPoint]

Returns:

quadrants defined by four points.

See also

quadrant()

outerTangents(self, other: QgsCircle)[source]

Calculates the outer tangent points between this circle and an other circle.

The outer tangent points correspond to the points at which the two lines which are drawn so that they are tangential to both circles touch the circles.

The first tangent line is described by the points stored in line1P1 and line1P2, and the second line is described by the points stored in line2P1 and line2P2.

Returns the number of tangents (either 0 or 2).

Note

This method is 2D only and does not consider the z-value of the circle.

See also

tangentToPoint()

See also

innerTangents()

Added in version 3.2.

Parameters:

other (QgsCircle) -> (int)

radius(self) float[source]

Returns the radius of the circle

Return type:

float

setRadius(self, radius: float)[source]

Sets the radius of the circle

Parameters:

radius (float)

virtual setSemiMajorAxis(self, semiMajorAxis: float)[source]

Inherited method. Use setRadius() instead.

See also

radius()

See also

setRadius()

Parameters:

semiMajorAxis (float)

virtual setSemiMinorAxis(self, semiMinorAxis: float)[source]

Inherited method. Use setRadius() instead.

See also

radius()

See also

setRadius()

Parameters:

semiMinorAxis (float)

tangentToPoint(self, p: QgsPointXY)[source]

Calculates the tangent points between this circle and the point p.

If found, the tangent points will be stored in pt1 and pt2.

Note

This method is 2D only and does not consider the z-value of the circle.

Returns:

True if tangent was found.

See also

outerTangents()

See also

innerTangents()

Added in version 3.2.

Parameters:

p (QgsPointXY) -> (bool)

toCircularString(self, oriented: bool = False) QgsCircularString | None[source]

Returns a circular string from the circle.

Parameters:

oriented (bool = False) – If oriented is True the start point is from azimuth instead from north.

Return type:

Optional[QgsCircularString]