You are here: Start » PyAVL » Operators on Geometry Types

Operators on Geometry Types

PyAVL lets the geometry types, Location, Matrix and the shape types be combined with the Python operators +, -, *, / and @. Where Aurora Vision Library already provides the operation, the operator calls the same function, so the result and the errors are identical to those of the function.

The operators never modify their operands. Each operation returns a new object. A combination that is not listed on this page raises the Python TypeError exception.

The types of PyAVL and PyAVL-DL are interchangeable. An object created with AVL can be combined with an object created with AVLDL.

Points and Vectors

The table applies to the 2D types (Point2D, Vector2D) and to the 3D types (Point3D, Vector3D). Both operands must have the same dimension.

Expression	Result	Meaning
`point + vector`	Point	The point moved by the vector.
`point - vector`	Point	The point moved by the opposite vector.
`point + point`	Point	The sum of the coordinates.
`point - point`	Point	The difference of the coordinates.
`point * number`, `number * point`	Point	The coordinates multiplied by the number (scaling about the origin).
`point / number`	Point	The coordinates divided by the number.
`vector + vector`, `vector - vector`	Vector	The sum or the difference of the vectors.
`vector * number`, `number * vector`	Vector	The vector multiplied by the number.
`vector / number`	Vector	The vector divided by the number.
`-vector`	Vector	The opposite vector.
`vector @ vector`	float	The dot product of the vectors.

The operators * and / accept a Python int or float. Dividing by zero raises AVL.DomainError. Multiplying two vectors with * is not defined; use @ for the dot product.

import AVL

p = AVL.Point2D(10, 20)
v = AVL.Vector2D(3, -4)

moved = p + v                      # Point2D (13, 16)
doubled = v * 2                    # Vector2D (6, -8)
halved = v / 2                     # Vector2D (1.5, -2)
projection = v @ AVL.Vector2D(1, 0)   # 3.0, the dot product
difference = AVL.Point2D(5, 5) - p    # Point2D (-5, -15)

Locations

Location holds integer coordinates, so only Python integers are accepted as the second operand. The result is a Location.

Expression	Meaning
`location + location`, `location - location`	The sum or the difference of the coordinates.
`location + int`, `int + location`, `location - int`	The integer is added to or subtracted from both coordinates.
`location * int`, `int * location`	Both coordinates multiplied by the integer.
`-location`	Both coordinates negated.

A floating-point operand, for example location + 1.5, raises TypeError. A result that does not fit the 32-bit integer range raises OverflowError.

Translating Shapes

Adding a vector to a shape moves the shape; subtracting a vector moves it in the opposite direction. The operands of + can be given in either order (shape + vector or vector + shape). A shape cannot be subtracted from a vector, so vector - shape raises TypeError.

Shapes	Vector	Function used
`Region`	`Vector2D`	TranslateRegion
`Box`	`Vector2D`	TranslateBox
`Rectangle2D`	`Vector2D`	TranslateRectangle
`Circle2D`	`Vector2D`	TranslateCircle
`Ellipse2D`	`Vector2D`	The center is moved by the vector.
`Segment2D`	`Vector2D`	TranslateSegment
`Line2D`	`Vector2D`	TranslateLine
`Arc2D`	`Vector2D`	TranslateArc
`Path`	`Vector2D`	TranslatePath
`Box3D`	`Vector3D`	`TranslateBox3D`
`Circle3D`	`Vector3D`	`TranslateCircle3D`
`Sphere3D`	`Vector3D`	The center is moved by the vector.
`Segment3D`	`Vector3D`	`TranslateSegment3D`
`Line3D`	`Vector3D`	`TranslateLine3D`
`Plane3D`	`Vector3D`	`TranslatePlane`

A 2D shape requires a Vector2D and a 3D shape requires a Vector3D. Mixing them, for example Box + Vector3D, raises TypeError.

Notes

Regions and boxes are defined on the pixel grid, so they can only be moved by whole pixels. The components of the vector are rounded to the nearest integer. A component that is not finite or does not fit the integer range raises AVL.DomainError. A translated region keeps its frame size.
Lines in 3D are stored in a normalized form, as in TranslateLine3D. The point of a translated Line3D is the point of the line closest to the origin, so it may differ from the original point plus the vector along the direction of the line.
Planes without a defined orientation (all of the first three coefficients equal to zero) cannot be translated and raise AVL.DomainError. The same applies to a Circle3D in such a plane.

import AVL

delta = AVL.Vector2D(5, -3)

box = AVL.Box(10, 20, 30, 40)
shifted_box = box + delta              # Box (15, 17, 30, 40)

circle = AVL.Circle2D(50, 50, 10)
moved_circle = circle - delta          # center (45, 53)

region = AVL.Region()
AVL.CreateBoxRegion(box, 100, 100, region)
moved_region = region + delta          # the same as AVL.TranslateRegion(region, 5, -3, ...)

sphere = AVL.Sphere3D(1, 2, 3, 4)
moved_sphere = sphere + AVL.Vector3D(10, 0, 0)   # center (11, 2, 3)

Transforming 3D Points and Vectors

A Matrix can be applied to a 3D vector or point with the @ operator. See Working with Matrices.

Errors

Exception	Cause
`TypeError`	The operator is not defined for the operand types, for example `vector * vector`, `Location + float`, `Box + Vector3D` or `vector - shape`.
`AVL.DomainError`	The operands are of the right types but their values are not valid, for example a division by zero, a translation of a region by a value that is not finite, or an indefinite plane.
`OverflowError`	The result of an operation on a `Location` does not fit the integer range.