Basic Shapes

`viren2d.Ellipse`	An ellipse for visualization.
`viren2d.Line2d`	A line (or line segment) in 2D space.
`viren2d.Rect`	A rectangle for visualization.
`viren2d.ellipse_from_endpoints`	Alias of `viren2d.Ellipse.from_endpoints()`.
`viren2d.rect_from_cwh`	Alias of `viren2d.Rect.from_cwh()`.
`viren2d.rect_from_lrtb`	Alias of `viren2d.Rect.from_lrtb()`.
`viren2d.rect_from_ltwh`	Alias of `viren2d.Rect.from_ltwh()`.

Ellipse

class viren2d.Ellipse

An ellipse for visualization.

An ellipse is defined by its center point (cx and cy), length of its major_axis, length of its minor_axis and it’s clockwise rotation (in degrees). At 0° rotation, the major axis is aligned with the \(x\) axis.

Optionally, an ellipse can be drawn only partially, i.e. starting at angle_from, drawing clockwise (with increasing angles) until angle_to. For such partially drawn ellipses, you should consider adding the center point to the drawn path via include_center (which is the default behavior).

For convenience, an ellipse can be implicitly created from a list or a tuple:

>>> # Explicit initialization:
>>> ellipse = viren2d.Ellipse(center, axes, ...)
>>> # Implicitly cast from tuple:
>>> painter.draw_ellipse((center, axes, ...), line_style=...)

Corresponding C++ API: viren2d::Ellipse.

The code listing to create this visualization is shown in the RTD tutorial section on ellipses.

Methods:

`__eq__`	Checks for equality.
`__getstate__`
`__init__`	Overloaded function.
`__ne__`	Checks for inequality.
`__setstate__`	`Ellipse` instances can be pickled.
`copy`	Returns a deep copy.
`from_endpoints`	Returns an ellipse defined by the endpoints of its major axis.
`is_valid`	Returns `True` if the ellipse can be drawn.

Attributes:

`angle_from`	Drawing the contour/filling starts at this angle (clockwise in degrees).
`angle_to`	Drawing the contour/filling stops at this angle (clockwise in degrees).
`axes`	Provides convenience access to the axes (i.e. `major_axis` and `minor_axis`) as 2D vector, i.e. `(major, minor)`.
`center`	Provides convenience access to the center position (i.e. `cx` and `cy`) as 2D vector.
`cx`	Horizontal center coordinate.
`cy`	Vertical center coordinate.
`include_center`	If you explicitly change `angle_from` or `angle_to`, you very likely also want to include the center point in the rendered path.
`major_axis`	Length of the major axis.
`minor_axis`	Length of the minor axis.
`rotation`	Rotation angle (clockwise) in degrees.

__eq__(self: viren2d.Ellipse, arg0: viren2d.Ellipse) → bool: Checks for equality.

__getstate__(self: viren2d.Ellipse) → tuple

__init__(*args, **kwargs)

Overloaded function.

__init__(self: viren2d.Ellipse, center: viren2d.Vec2d, axes: viren2d.Vec2d, rotation: float = 0.0, angle_from: float = 0.0, angle_to: float = 360.0, include_center: bool = True) -> None

Creates an ellipse.

Parameters:

center – Center position as Vec2d.
axes – Lengths of the major and minor axes as Vec2d. Order is (major, minor).
rotation – Clockwise rotation angle in degrees as float.
angle_from – Starting angle in degrees as float.
angle_to – Ending angle in degrees as float.
include_center – If True and angle_from or angle_to differ from their defaults, the center point will be included in the drawn/filled ellipse path (type bool).

__init__(self: viren2d.Ellipse, tpl: object) -> None
Creates an ellipse from a tuple or list.

This overloaded constructor is required to allow implicit casting and supports 2 general tuple/list constellations:
- A tuple/list holding (center, size, rotation, angle_from, angle_to, include_center), where center & size are Vec2d, rotation, angle_from and angle_to are float and include_center is a bool.
- A tuple/list holding (cx, cy, major, minor, rotation, angle_from, angle_to, include_center), where all entries (except for include_center) are float.
In both cases, rotation, angle_from, angle_to and include_center are optional.

__ne__(self: viren2d.Ellipse, arg0: viren2d.Ellipse) → bool: Checks for inequality.

__setstate__(self: viren2d.Ellipse, arg0: tuple) → None: Ellipse instances can be pickled.

property angle_from

Drawing the contour/filling starts at this angle (clockwise in degrees).

Corresponding C++ API: viren2d::Ellipse::angle_from.

Type:: float

property angle_to

Drawing the contour/filling stops at this angle (clockwise in degrees).

Corresponding C++ API: viren2d::Ellipse::angle_to.

Type:: float

property axes

Provides convenience access to the axes (i.e. major_axis and minor_axis) as 2D vector, i.e. (major, minor).

Corresponding C++ API: viren2d::Ellipse::Axes.

Type:: Vec2d

property center

Provides convenience access to the center position (i.e. cx and cy) as 2D vector.

Corresponding C++ API: viren2d::Ellipse::Center.

Type:: Vec2d

copy(self: viren2d.Ellipse) → viren2d.Ellipse

Returns a deep copy.

Corresponding C++ API: Copy constructor of viren2d::Ellipse.

property cx

Horizontal center coordinate.

Corresponding C++ API: viren2d::Ellipse::cx.

Type:: float

property cy

Vertical center coordinate.

Corresponding C++ API: viren2d::Ellipse::cy.

Type:: float

static from_endpoints(pt1: viren2d.Vec2d, pt2: viren2d.Vec2d, width: float, angle_from: float = 0.0, angle_to: float = 360.0, include_center: bool = True) → viren2d.Ellipse

Returns an ellipse defined by the endpoints of its major axis.

Assumes that the given coordinates specify the endpoints of the major axis.

Corresponding C++ API: viren2d::Ellipse::FromEndpoints.

Parameters:

pt1 – First endpoint of the major axis as Vec2d.
pt2 – Second endpoint of the major axis as Vec2d.
width – Length of the minor axis as float.
angle_from – Starting angle in degrees as float.
angle_to – Ending angle in degrees as float.
include_center – If True and angle_from or angle_to differ from their defaults, the center point will be included in the drawn/filled ellipse path (type bool).

property include_center

If you explicitly change angle_from or angle_to, you very likely also want to include the center point in the rendered path. Otherwise, filling can easily lead to irritating results.

Corresponding C++ API: viren2d::Ellipse::include_center.

Type:: bool

is_valid(self: viren2d.Ellipse) → bool

Returns True if the ellipse can be drawn.

Corresponding C++ API: viren2d::Ellipse::IsValid.

property major_axis

Length of the major axis.

Corresponding C++ API: viren2d::Ellipse::major_axis.

Type:: float

property minor_axis

Length of the minor axis.

Corresponding C++ API: viren2d::Ellipse::minor_axis.

Type:: float

property rotation

Rotation angle (clockwise) in degrees.

Corresponding C++ API: viren2d::Ellipse::rotation.

Type:: float

2D Line

class viren2d.Line2d

A line (or line segment) in 2D space.

A line/segment is represented by two Vec2d.

Corresponding C++ API: viren2d::Line2d.

Methods:

`__getstate__`
`__init__`	Overloaded function.
`__setstate__`	`Line2d` instances can be pickled.
`angle_deg`	Returns the angle \(\alpha \in [0, 180]\) between this line and the second line.
`angle_rad`	Returns the angle \(\alpha \in [0, \pi]\) between this line and the second line.
`angle_vec_deg`	Returns the angle \(\alpha \in [0, 180]\) between this line and the given directional vector.
`angle_vec_rad`	Returns the angle \(\alpha \in [0, \pi]\) between this line and the given directional vector.
`clip_line_by_rectangle`	Clips this line against the given axis-aligned rectangle.
`clip_segment_by_rectangle`	Clips this segment against the given axis-aligned rectangle.
`closest_point_on_line`	Returns the closest point on the line, i.e. the projection of the given point onto this line.
`closest_point_on_segment`	Returns the closest point on this segment.
`direction`	Returns the non-normalized direction vector from the start point to the end point.
`distance_point_line`	Returns the minimum distance between the point and this line.
`distance_point_segment`	Returns the minimum distance between the point and this segment.
`homogeneous`	Returns the representation of this line in \(\mathbb{P}^2\).
`is_collinear`	Returns `True` if the two lines are collinear.
`is_parallel`	Returns `True` if the two lines are parallel.
`is_valid`	Returns `True` if the line is valid, i.e. \(\text{length} > 0\).
`left_to_right`	Returns a line/segment where `pt1` is left of `pt2`.
`point_at_offset`	Returns the interpolated point on the line/segment.
`reversed`	Returns a line/segment with flipped start/end points.
`tilt_deg`	Tilts the segment around its start point.
`unit_direction`	Returns the unit direction vector from the start point to the end point.

Attributes:

`length`	Length of the segment between `pt1` and `pt2`.
`mid_point`	Mid point between `pt1` and `pt2`.
`pt1`	Starting point.
`pt2`	End point.

__getstate__(self: viren2d.Line2d) → tuple

__init__(*args, **kwargs)

Overloaded function.

__init__(self: viren2d.Line2d, pt1: viren2d.Vec2d, pt2: viren2d.Vec2d) -> None

Creates a line from 2 points.

Parameters:

pt1 – Start point as Vec2d.
pt2 – End point as Vec2d.

__init__(self: viren2d.Line2d, tpl: tuple) -> None

Creates a line from a tuple.

This overloaded constructor is required to allow implicit casting from a tuple holding (pt1, pt2),where pt1 & pt2 are the start and end pointsas Vec2d.

__init__(self: viren2d.Line2d, lst: list) -> None

Creates a line from a list.

This overloaded constructor is required to allow implicit casting from a list holding [pt1, pt2],where pt1 & pt2 are the start and end pointsas Vec2d.

__setstate__(self: viren2d.Line2d, arg0: tuple) → None: Line2d instances can be pickled.

angle_deg(self: viren2d.Line2d, other: viren2d.Line2d) → float

Returns the angle \(\alpha \in [0, 180]\) between this line and the second line.

Corresponding C++ API: viren2d::Line2d::AngleDeg.

angle_rad(self: viren2d.Line2d, other: viren2d.Line2d) → float

Returns the angle \(\alpha \in [0, \pi]\) between this line and the second line.

Corresponding C++ API: viren2d::Line2d::AngleRad.

angle_vec_deg(self: viren2d.Line2d, vec: viren2d.Vec2d) → float

Returns the angle \(\alpha \in [0, 180]\) between this line and the given directional vector.

Corresponding C++ API: viren2d::Line2d::AngleDeg.

angle_vec_rad(self: viren2d.Line2d, vec: viren2d.Vec2d) → float

Returns the angle \(\alpha \in [0, \pi]\) between this line and the given directional vector.

Corresponding C++ API: viren2d::Line2d::AngleRad.

clip_line_by_rectangle(self: viren2d.Line2d, top_left: viren2d.Vec2d, size: viren2d.Vec2d) → viren2d.Line2d

Clips this line against the given axis-aligned rectangle.

Corresponding C++ API: viren2d::Line2d::ClipLineByRectangle.

Parameters:

top_left – Position of the rectangle’s top-left corner as Vec2d.
size – Dimension of the rectangle as Vec2d.

Returns:

The clipped Line2d. If the line did not intersect the rectangle, the result will be invalid. Check this via is_valid().

clip_segment_by_rectangle(self: viren2d.Line2d, top_left: viren2d.Vec2d, size: viren2d.Vec2d) → viren2d.Line2d

Clips this segment against the given axis-aligned rectangle.

Corresponding C++ API: viren2d::Line2d::ClipLineSegmentByRectangle.

Parameters:

top_left – Position of the rectangle’s top-left corner as Vec2d.
size – Dimension of the rectangle as Vec2d.

Returns:

The clipped Line2d. If the segment did not intersect the rectangle, the result will be invalid. Check this via is_valid().

closest_point_on_line(self: viren2d.Line2d, point: viren2d.Vec2d) → viren2d.Vec2d

Returns the closest point on the line, i.e. the projection of the given point onto this line.

Corresponding C++ API: viren2d::Line2d::ClosestPointOnLine.

closest_point_on_segment(self: viren2d.Line2d, point: viren2d.Vec2d) → viren2d.Vec2d

Returns the closest point on this segment.

Corresponding C++ API: viren2d::Line2d::ClosestPointOnSegment.

direction(self: viren2d.Line2d) → viren2d.Vec2d

Returns the non-normalized direction vector from the start point to the end point.

Corresponding C++ API: viren2d::Line2d::Direction.

distance_point_line(self: viren2d.Line2d, point: viren2d.Vec2d) → float

Returns the minimum distance between the point and this line.

Corresponding C++ API: viren2d::Line2d::DistancePointToLine.

distance_point_segment(self: viren2d.Line2d, point: viren2d.Vec2d) → float

Returns the minimum distance between the point and this segment.

Corresponding C++ API: viren2d::Line2d::DistancePointToSegment.

homogeneous(self: viren2d.Line2d) → viren2d.Vec3d

Returns the representation of this line in \(\mathbb{P}^2\).

For more details on lines in projective space, refer to Bob Fisher’s CVonline, or Stan Birchfield’s lecture notes.

Corresponding C++ API: viren2d::Line2d::HomogeneousForm.

Returns:: The Vec3d as the result of :math:` ext{pt1} imes ext{pt2}`.

is_collinear(self: viren2d.Line2d, other: viren2d.Line2d) → bool

Returns True if the two lines are collinear.

Corresponding C++ API: viren2d::Line2d::IsCollinear.

is_parallel(self: viren2d.Line2d, other: viren2d.Line2d) → bool

Returns True if the two lines are parallel.

Corresponding C++ API: viren2d::Line2d::IsParallel.

is_valid(self: viren2d.Line2d) → bool

Returns True if the line is valid, i.e. \(\text{length} > 0\).

Corresponding C++ API: viren2d::Line2d::IsValid.

left_to_right(self: viren2d.Line2d) → viren2d.Line2d

Returns a line/segment where pt1 is left of pt2.

If this line is vertical, the points will be sorted such that the y coordinates are in ascending order.

Corresponding C++ API: viren2d::Line2d::LeftToRight.

property length

Length of the segment between pt1 and pt2.

Corresponding C++ API: viren2d::Line2d::Length.

Type:: float

property mid_point

Mid point between pt1 and pt2.

This property simply provides convenience access to the mid point. Alternatively, use point_at_offset() for an adjustable offset along the line/segment.

Corresponding C++ API: viren2d::Line2d::MidPoint.

Type:: Vec2d

point_at_offset(self: viren2d.Line2d, offset: float) → viren2d.Vec2d

Returns the interpolated point on the line/segment.

Computes \(\text{pt}_1 + \text{offset} * (\text{pt}_2 - \text{pt}_1)\).

Corresponding C++ API: viren2d::Line2d::PointAtOffset.

property pt1

Starting point.

Corresponding C++ API: viren2d::Line2d::From and viren2d::Line2d::SetFrom.

Type:: Vec2d

property pt2

End point.

Corresponding C++ API: viren2d::Line2d::To and viren2d::Line2d::SetTo.

Type:: Vec2d

reversed(self: viren2d.Line2d) → viren2d.Line2d

Returns a line/segment with flipped start/end points.

Corresponding C++ API: viren2d::Line2d::Reversed.

tilt_deg(self: viren2d.Line2d, angle: float) → viren2d.Line2d: Tilts the segment around its start point.

unit_direction(self: viren2d.Line2d) → viren2d.Vec2d

Returns the unit direction vector from the start point to the end point.

Corresponding C++ API: viren2d::Line2d::UnitDirection.

Rectangle

Exemplary rectangle configurations:

The code listing to create this visualization is shown in the tutorial section on rectangles.

class viren2d.Rect

A rectangle for visualization.

A rectangle is defined by its center, width, height, rotation (clockwise, in degrees), and a corner radius.

For convenience, a rectangle can be implicitly created from a list or a tuple:

>>> # Explicit initialization:
>>> rect = viren2d.Rect(center, size, ...)
>>> # Implicitly cast from tuple:
>>> painter.draw_rect((center, size, ...), line_style=...)

Alternatively, an axis-aligned rectangle can also be initialized from the L,T,W,H and L,R,T,B representations:

>>> # If top-left and dimensions are given:
>>> rect = viren2d.Rect.rom_ltwh(left, top, width, height)
>>> # If top-left and bottom-right corners are given:
>>> rect = viren2d.Rect.rom_lrtb(left, right, top, bottom)

Corresponding C++ API: viren2d::Rect.

The code listing to create this visualization is shown in the RTD tutorial section on rectangles.

Methods:

`__eq__`	Checks for equality.
`__getstate__`
`__init__`	Overloaded function.
`__ne__`	Checks for inequality.
`__setstate__`	`Rect` instances can be pickled.
`copy`	Returns a deep copy.
`from_cwh`	Returns a rectangle for the `Cx,Cy,W,H` representation.
`from_lrtb`	Returns an axis-aligned rectangle for the `L,R,T,B` representation.
`from_ltwh`	Returns an axis-aligned rectangle for the `L,T,W,H` representation.
`is_valid`	Returns `True` if the rectangle can be drawn.

Attributes:

`center`	Provides convenience access to the center position (i.e. `cx` and `cy`) as 2D vector.
`cx`	Horizontal center coordinate.
`cy`	Vertical center coordinate.
`half_height`	Half the rectangle height (read-only).
`half_width`	Half the rectangle width (read-only).
`height`	Rectangle height.
`radius`	Corner radius.
`rotation`	Clockwise rotation angle in degrees.
`size`	Provides convenience access to the size (i.e. `width` and `height`) as 2D vector.
`width`	Rectangle width.

__eq__(self: viren2d.Rect, arg0: viren2d.Rect) → bool: Checks for equality.

__getstate__(self: viren2d.Rect) → tuple

__init__(*args, **kwargs)

Overloaded function.

__init__(self: viren2d.Rect, tpl: object) -> None
Creates a rectangle from a tuple or list.

This overloaded constructor is required to allow implicit casting and supports 2 general tuple/list constellations:
- A tuple/list holding (center, size, rotation, radius), where center & size are Vec2ds, and rotation & radius are float.
- A tuple/list holding (cx, cy, w, h, rotation, radius), where all entries are float.
In both cases, rotation and radius are optional.
__init__(self: viren2d.Rect, center: viren2d.Vec2d, size: viren2d.Vec2d, rotation: float = 0.0, radius: float = 0.0) -> None

Creates a rectangle.

Parameters:

center – Center position as Vec2d.
size – Size, i.e. (width, height) of the rectangle as Vec2d.
rotation – Clockwise rotation angle in degrees as float.
radius – Corner radius as float, see documentation of the radius attribute.

__ne__(self: viren2d.Rect, arg0: viren2d.Rect) → bool: Checks for inequality.

__setstate__(self: viren2d.Rect, arg0: tuple) → None: Rect instances can be pickled.

property center

Provides convenience access to the center position (i.e. cx and cy) as 2D vector.

Corresponding C++ API: viren2d::Rect::Size.

Type:: Vec2d

copy(self: viren2d.Rect) → viren2d.Rect

Returns a deep copy.

Corresponding C++ API: Copy constructor of viren2d::Rect.

property cx

Horizontal center coordinate.

Corresponding C++ API: viren2d::Rect::cx.

Type:: float

property cy

Vertical center coordinate.

Corresponding C++ API: viren2d::Rect::cy.

Type:: float

static from_cwh(cx: float, cy: float, width: float, height: float, rotation: float = 0.0, radius: float = 0.0) → viren2d.Rect

Returns a rectangle for the Cx,Cy,W,H representation.

Corresponding C++ API: viren2d::Rect::FromCWH.

Parameters:

cx – Horizontal center coordinate as float.
cy – Vertical center coordinate as float.
width – Width (extent along the \(x\) axis if the rectangle is not rotated) as float.
height – Height (extent along the \(y\) axis if the rectangle is not rotated) as float.
rotation – Clockwise rotation in degrees as float.
radius – Corner radius as float, see documentation of the radius attribute.

static from_lrtb(left: float, right: float, top: float, bottom: float, radius: float = 0.0) → viren2d.Rect

Returns an axis-aligned rectangle for the L,R,T,B representation.

Corresponding C++ API: viren2d::Rect::FromLRTB.

Parameters:

left – \(x\) coordinate of the left edge as float.
right – \(x\) coordinate of the right edge as float.
top – \(y\) coordinate of top edge as float.
bottom – \(y\) coordinate of bottom edge as float.
radius – Corner radius as float, see documentation of the radius attribute.

static from_ltwh(left: float, top: float, width: float, height: float, radius: float = 0.0) → viren2d.Rect

Returns an axis-aligned rectangle for the L,T,W,H representation.

Corresponding C++ API: viren2d::Rect::FromLTWH.

Parameters:

left – \(x\) coordinate of the left edge as float.
top – \(y\) coordinate of the top edge as float.
width – Width (extent along the \(x\) axis) as float.
height – Height (extent along the \(y\) axis) as float.
radius – Corner radius as float, see documentation of the radius attribute.

property half_height

Half the rectangle height (read-only).

Corresponding C++ API: viren2d::Rect::HalfHeight.

Type:: float

property half_width

Half the rectangle width (read-only).

Corresponding C++ API: viren2d::Rect::HalfWidth.

Type:: float

property height

Rectangle height.

Corresponding C++ API: viren2d::Rect::height.

Type:: float

is_valid(self: viren2d.Rect) → bool

Returns True if the rectangle can be drawn.

Corresponding C++ API: viren2d::Rect::IsValid.

property radius

Corner radius.

If \(0 \leq \text{radius} \leq 0.5\), the actural corner radius will be computed as \(\text{radius} * \min(\text{width}, \text{height})\).

If \(\text{radius} > 1\), it denotes the absolute corner radius in pixels.

Otherwise, i.e. \(0.5 < \text{radius} < 1\), the rectangle will be invalid.

Corresponding C++ API: viren2d::Rect::radius.

Type:: float

property rotation

Clockwise rotation angle in degrees.

Corresponding C++ API: viren2d::Rect::rotation.

Type:: float

property size

Provides convenience access to the size (i.e. width and height) as 2D vector.

Corresponding C++ API: viren2d::Rect::Size.

Type:: Vec2d

property width

Rectangle width.

Corresponding C++ API: viren2d::Rect::width.

Type:: float

Shape Utilitites

viren2d.ellipse_from_endpoints(pt1: viren2d.Vec2d, pt2: viren2d.Vec2d, width: float, angle_from: float = 0.0, angle_to: float = 360.0, include_center: bool = True) → viren2d.Ellipse: Alias of viren2d.Ellipse.from_endpoints().

viren2d.rect_from_cwh(cx: float, cy: float, width: float, height: float, rotation: float = 0.0, radius: float = 0.0) → viren2d.Rect: Alias of viren2d.Rect.from_cwh().

viren2d.rect_from_lrtb(left: float, right: float, top: float, bottom: float, radius: float = 0.0) → viren2d.Rect: Alias of viren2d.Rect.from_lrtb().

viren2d.rect_from_ltwh(left: float, top: float, width: float, height: float, radius: float = 0.0) → viren2d.Rect: Alias of viren2d.Rect.from_ltwh().