Pyvoronoi - API documentation

Cython wrapper for the C++ translation of the Voronoi diagram part of Boost’s Polygon library: https://www.boost.org/doc/libs/1_80_0/libs/polygon/doc/voronoi_diagram.htm

class pyvoronoi.Cell(cell_identifier: int, site: int, vertices: list[int], edges: list[int], source_category: int)

This class represents any cell generated when constructing Boost Voronoi output. A Voronoi cell represents a region of the Voronoi diagram bounded by the Voronoi edges. Voronoi cells are built around an input site that can be either site or segment. When a cells is on the border of the Voronoi solution, it might have infinite edges, meaning edges that do not have coordinates at one of their end point.

The list of source categories for each cell can be found on the boost website.

• SOURCE_CATEGORY_SINGLE_POINT: 0

• SOURCE_CATEGORY_SEGMENT_START_POINT: 1

• SOURCE_CATEGORY_SEGMENT_END_POINT: 2

• SOURCE_CATEGORY_INITIAL_SEGMENT: 3

• SOURCE_CATEGORY_REVERSE_SEGMENT: 4

• SOURCE_CATEGORY_GEOMETRY_SHIFT: 5

• SOURCE_CATEGORY_BITMASK: 6

class pyvoronoi.Edge(start: int, end: int, cell: int, twin: int)

This class represents any edge generated when constructing Boost Voronoi output. Those edges are referenced by cells. Think of an edge as a linear component. It can be either straight lines or parabolas when returned by Boost Voronoi. An edge can only belong to one cell. That means that if two cells share a border, two edges will exist. Those two edges will be twins.

exception pyvoronoi.FocusOnDirectixException

When computing a parabola between a point and a line, the input point must not be on the input line. If this scenario occurs, this exception is raised.

class pyvoronoi.Pyvoronoi

The wrapper class around Boost Voronoi. Add input point or segments, and then call Construct to generate Voronoi cells.

AddPoint(point: list[float, float]) → None

Add a point to the Voronoi builder. The coordinate will be multiplied by the factor, then rounded as an integer.

Parameters:

point (list[float, float]) – A list with 2 elements. The first element represents the X-coordinate of the point. The second element represents the Y-coordinate of the point.

Returns:

None

AddSegment(segment: list[list[float, float], list[float, float]]) → None

Add a segment to the Voronoi builder. The segment is made of an array of coordinates. The coordinates will be multiplied by the factor, then rounded as an integer.

Parameters:

segment (list[list[float, float], list[float, float]]) – A list that contains two elements. Each element is an array containing the [X, Y] coordinate for each of the segment end points.

Returns:

None

CheckUnsolvableParabolaEquation(boost_x: float, boost_y: float, focus: list[float, float], directix: float, tolerance: float) → list[float, float]

Used for interpolating parabolas

Compare the y-coordinate of a point on the parabola returned by Boost with the computed value.

The function will return an exception if the difference between the computed y-value and the y-value returned by Boost. The computed point will be returned otherwise.

Parameters:

• boost_x (float) – the x-value of the point parabola returned by boost.

• boost_y (float) – the y-value of the point parabola returned by boost.

• focus (list[float, float]) – the focus point used for solving the equation of the parabola.

• directix (float :param tolerance: the distance allowed between the point computed by boost and the point computed by the equation. :type tolerance: float :raises UnsolvableParabolaEquation: Indicates a scenario where a parabola cannot be computed. :return: the point on the parabola computed using the value of boost_x. :rtype: list[float, float]) – the directix value used for solving the equation of the parabola.

Construct()

Generates the voronoi diagram for the added points and segments. Voronoi cell structure will be generated. Calling this method will prevent adding any new input point or segment.

CountCells()

Returns the number of output Cells generated as part of the Voronoi solution after having called Construct.

Returns:

The number of cells.

Return type:

int

CountEdges()

Returns the number of output Edges generated as part of the Voronoi solution after having called Construct.

Returns:

The number of edges.

Return type:

int

CountPoints()

Returns the number of input points stored in memory to solve the Voronoi problem.

Returns:

The number of input points.

Return type:

int

CountSegments()

Returns the number of input segments stored in memory to solve the Voronoi problem.

Returns:

The number of input segments.

Return type:

int

CountVertices()

Returns the number of output Vertices generated as part of the Voronoi solution after having called Construct.

Returns:

The number of vertices.

Return type:

int

Discretize(point: list[float, float], segment: list[list[float, float], list[float, float]], parabola_start: list[float, float], parabola_end: list[float, float], max_dist: float, parabola_equation_tolerance: float) → map[list[float, float]]

Interpolate points on a parabola. The points are garanteed to be closer than the value of the parameter max_dist.

Parameters:

• point (list[float, float]) – The input point associated with the cell or the neighbour cell. The point is used as the focus in the equation of the parabola.

• segment (list[float, float]) – The input segment associated with the cell or the neighbour cell. The point is used as the directix in the equation of the parabola.

• parabola_start (list[float, float]) – The starting point of the parabola.

• parabola_end (list[float, float]) – The end point of the parabola

• max_dist (float) – The maximum distance between 2 vertices on the discretized geometry.

• parabola_equation_tolerance (float) – The maximum difference allowed between the y coordinate returned by Boost, and the equation of the parabola.

Returns:

The list of points on the parabola.

Return type:

map[list[float, float]]

DiscretizeCurvedEdge(index: int, max_dist: float, parabola_equation_tolerance=0.0001) → map[list[float, float]]

Returns a list of point that represent the parabola given the index of an edge. This is a convenience wrapper around the function Discretize

Parameters:

• index (int) – The index of the edge discretize.

• max_dist (float) – The maximum distance between points.

• parabola_equation_tolerance (float) – The maximum difference allowed between the y coordinate returned by Boost, and the equation of the parabola.

Returns:

The list of points on the parabola returned as a map.

Return type:

map[list[float, float]]

EnumerateCells()

Iterate through the list of output cells generated after calling Construct.

Returns:

A generator iterating through the output edges. Each object is tuple with two elements. The first one is the index. The second element is the cell.

Return type:

Generator[(int, Cell)]

EnumerateEdges()

Iterate through the list of output edges generated after calling Construct.

Returns:

A generator iterating through the output edges. Each object is tuple with two elements. The first one is the index. The second element is the edge.

Return type:

Generator[(int, Edge)]

EnumerateVertices()

Iterate through the list of output vertices generated after calling Construct.

Returns:

A generator iterating through the output vertices. Each object is tuple with two elements. The first one is the index. The second element is the vertex.

Return type:

Generator[(int, Vertex)]

GetCell(index: int) → Cell

Return the cell at a given index. The list of cells is generated upon calling Construct.

Parameters:

index (int) – The index of the cell to retrieve.

Returns:

The matching cell.

Return type:

Cell

GetCells()

Get the list of cells generated after calling construct. This returns a duplicated list of the output cells. Consider using EnumerateCells instead.

Returns:

A copy of the output cells.

Return type:

list[Cell]

GetDegenerateSegments()

Input Data Validation

Return the indexes of segments which has identical coordinates for its start point and end point. Those segments can prevent the voronoi algorithm from solving, or generate a corrupted output. The indexes are returned as a list.

Returns:

A list of indexes.

Return type:

list[int]

GetEdge(index: int) → Edge

Return the edge at a given index. The list of edge is generated upon calling Construct.

Parameters:

index (int) – The index of the edge to retrieve.

Returns:

The matching edge.

Return type:

Edge

GetEdges()

Get the list of edges generated after calling construct. This returns a duplicated list of the output edges. Consider using EnumerateEdges instead.

Returns:

A copy of the output edges.

Return type:

list[Edge]

GetIntersectingSegments()

Input Data Validation

Returns the indexes of segments that intersect another segment beyond sharing an end point. Those segments can prevent the voronoi algorithm from solving, or generate a corrupted output. The indexes are returned as a list.

Returns:

A list of indexes.

Return type:

list[int]

GetParabolaY(x: float, focus: list[float, float], directrix_y: float) → float

Used for interpolating parabolas

Solve the parabola equation for a given value on the x-axis and return the associated value on the y-axis. This equation assumes that the directix is parallel to the x-axis. Parabola equation are different if the directix is parallel to the y-axis.

Parameters:

• x (float) – The position of a point on the X-axis. The Y value is derived based on this coordinate.

• focus (list[float, float]) – The focus point used to solve the equation.

• directrix_y (float) – The value on the Y-axis of the directix.

Returns:

the value on the y-axis derivated for x

Return type:

float

GetPoint(index: int) → list[int, int]

Return an input point used to generate the voronoi diagram.

Parameters:

index (int) – The index of the point to retrieve. The function CountPoints can be used to retrieve the number of input points stored in memory.

Returns:

A list with two elements. The first element is the X coordinate of the input point. The second element is the Y coordinate.

Return type:

list[int, int]

GetPoints()

Iterate through the input points added to the voronoi builder

Returns:

A generator that iterates through the list of input points.

Return type:

Generator[list[int, int]]

GetPointsOnSegments()

Input Data Validation

Return the indexes of points located on a segments. Connection at any of the end points is disregarded. Those situations can prevent the voronoi algorithm from solving, or generate a corrupted output. The indexes are returned as a list.

Returns:

A list of indexes.

Return type:

list[int]

GetSegment(index: int) → list[list[int, int], list[int, int]]

Return an input point segment to generate the voronoi diagram.

Parameters:

index (int) – The index of the segment to retrieve. The function CountSegments can be used to retrieve the number of input segments stored in memory.

Returns:

A list with two elements. The first element is a list representing the start point of the segment. The second element is a list representing the end point of the segment.

Return type:

list[int, int]

GetSegments()

Iterate through the input segments added to the voronoi builder

Returns:

A generator that iterates through the list of input segments.

Return type:

Generator[list[int, int]]

GetVertex(index: int) → Vertex

Return the output vertex at a given index. The list of vertex is generated upon calling Construct.

Parameters:

index (int) – The index of the vertex to retrieve.

Returns:

The matching vertex.

Return type:

Vertex

GetVertices()

Get the list of vertices generated after calling construct. This returns a duplicated list of the output Vertices. Consider using EnumerateVertices instead.

Returns:

A copy of the output vertices.

Return type:

list[Vertex]

RetrievePoint(cell: Cell) → list[int, int]

Retrieve the input point associated with a cell. The point coordinates are as used by Boost Voronoi: they have been multiplied by the factor.

Parameters:

cell (Cell) – the cell that contains a point. The point can either an input point or the end point of an input segment.

Returns:

An input point

Return type:

list[int, int]

RetrieveScaledPoint(cell: Cell) → list[float, float]

Retrieve the input point associated with a cell. The point coordinates are returned as passed to Boost Voronoi, before applying the factor.

Parameters:

cell (Cell) – the cell that contains a point. The point can either an input point or the end point of an input segment.

Returns:

An input point

Return type:

list[int, int]

RetrieveScaledSegment(cell: Cell) → list[list[float, float], list[float, float]]

Retrieve the input segment associated with a cell. The segment coordinates are returned as passed to Boost Voronoi, before applying the factor.

Parameters:

cell (Cell) – the cell that contains a segment.

Returns:

An input segment

Return type:

list[list[int, int], list[int, int]]

RetrieveSegment(cell: Cell) → list[list[int, int], list[int, int]]

Retrieve the input segment associated with a cell. The segment coordinates are as used by Boost Voronoi: they have been multiplied by the factor.

Parameters:

cell (Cell) – the cell that contains a segment.

Returns:

An input segment

Return type:

list[list[int, int], list[int, int]]

ReturnCurvedSiteInformation(edge: Edge) → list[int, int]

Returns the index of the input point site and the segment site associated with a segment index.

Parameters:

edge (Edge) – The edge for which to retrieve information.

Returns:

A list with two elements. The first element is the input point. The second element is the input segment.

Return type:

list[list[float, float], list[list[float, float], list[float, float]]]

exception pyvoronoi.UnsolvableParabolaEquation

Indicates a scenario where a parabola cannot be computed.

class pyvoronoi.Vertex(x: float, y: float)

This class represents any vertex generated when constructing Boost Voronoi output. Those vertices are referenced by edges and cells.

exception pyvoronoi.VoronoiException

Indicate a problem generating a output with Boost Voronoi. This might indicate problem with your input data.

pyvoronoi.get_distance(point_start: list[float, float], point_end: list[float, float]) → float

Returns the distance between two points.

Parameters:

• point_start (list[float, float]) – the start point of the line.

• point_end (list[float, float]) – the end point of the line.

Returns:

the distance between the two points

Return type:

float

pyvoronoi.get_distance_squared(point_start: list[float, float], point_end: list[float, float]) → float

Returns the squared distance between two points.

Parameters:

• point_start (list[float, float]) – the start point of the line as a list of coordinates

• point_end (list[float, float]) – the end point of the line as a list of coordinates

Returns:

the squared distance between the two points

Return type:

float

pyvoronoi.get_line_angle_in_radians(start_point_x: float, start_point_y: float, end_point_x: float, end_point_y: float) → float

Get the orientation of a line in radians

Parameters:

• start_point_x (float) – The x coordinate of the start point.

• start_point_y (float) – The y coordinate of the start point.

• end_point_x (float) – The x coordinate of the end point.

• end_point_y (float) – The y coordinate of the end point.

Returns:

The orientation of the line from the start point to the end point in radians

Return type:

float

pyvoronoi.rotate(point: list[float, float], theta: float) → list[float, float]

Rotate a point around the origin using an angle

Parameters:

• point (list[float, float]) – the input point

• theta (float) – the angle of rotation

Returns:

the rotated point.

Return type:

list[float, float]

pyvoronoi.rotate_with_shift(point: list[float, float], theta: float, shift_x: float, shift_y: float) → list[float, float]

Rotate a point around the origin and shift it along the x-axis and the y-axis

Parameters:

• point (list[float, float]) – the input point

• theta (float) – the angle of rotation around the origin

• shift_x (float) – the translation to apply on the x-value.

• shift_y (float) – the translation to apply on the y-value.

Returns:

the rotated point.

Return type:

list[float, float]

pyvoronoi.unrotate_with_shift(point: list[float, float], theta: float, shift_x: float, shift_y: float) → list[float, float]

Undo the rotation and shift done by the function rotate_with_shift

Parameters:

• point (list[float, float]) – the input point

• theta (float) – the angle of rotation around the origin used during the initial rotation

• shift_x (float) – the translation to apply on the x-value to undo.

• shift_y (float) – the translation to apply on the y-value to undo.

Returns:

the unrotated point.

Return type:

list[float, float]