soar.sim.geometry¶

Geometry classes, for manipulating points, collections of points, lines, and normalizing angles.

class soar.sim.geometry.Line(p1, p2, eps=1e-08, normalize=False)¶

Bases: object

A line in the (x, y) plane defined by two points on the line.

Parameters:	p1 – An `(x, y)` tuple or `Point` as one of the points on the line. p2 – An `(x, y)` tuple or `Point` as another point on the line. eps (float, optional) – The epsilon within which to consider a line horizontal or vertical, for precision purposes. normalize (bool, optional) – If `True`, normalize the internal vector representation to be a unit vector.

distance_from_line(p)¶

Determine the (signed) distance of a point from the line.

Parameters:	p – An `(x, y)` tuple or `Point` to measure distance from.
Returns:	The signed distance from the line.
Return type:	float

has_point(p, eps=1e-08)¶

Determine whether a point lies on the line.

Parameters:	p – The `(x, y)` tuple or `Point` to check. eps (float, optional) – The distance to tolerate before a point is considered not to be on the line.
Returns:	`True` if the point is on the line, `False` otherwise.
Return type:	bool

intersection(other, eps=1e-08)¶

Determine whether two lines intersect.

Parameters:	other – The `Line` to find the intersection with. eps (float, optional) – The smallest absolute difference to tolerate before the lines are considered to be converging.
Returns:	The `Point` of intersection, or `None` if the lines are parallel (based on epsilon).

class soar.sim.geometry.LineSegment(p1, p2, eps=1e-08)¶

Bases: soar.sim.geometry.Line

A line segment in the (x, y) plane defined by two endpoints.

Parameters:	p1 – An `(x, y)` tuple or `Point` as the first endpoint. p2 – An `(x, y)` tuple or `Point` as the second endpoint. eps (float, optional) – The minimum absolute difference in x or y before the line is considered horizontal or vertical.

has_intersect(other)¶

Determine whether one segment intersects with another.

Parameters:	other – Another `LineSegment`.
Returns:	`True` if the segments have an intersection, `False` otherwise.
Return type:	bool

has_point(p, eps=1e-08)¶

Determine whether a point lies on the line segment.

Parameters:	p – The `(x, y)` tuple or `Point` to check. eps (float, optional) – The distance to tolerate before a point is considered not to be on the line segment.
Returns:	`True` if the point is on the line segment, `False` otherwise.
Return type:	bool

intersection(other, eps=1e-08)¶

Find the intersection(s) between two line segments, or this line segment and a Line.

Parameters:	other – The other `LineSegment` to find intersections with. eps (float, optional) – The epsilon or tolerance to pass to the `Line` intersection and `has_point` checks.
Returns:	Either a list of `Point` (s) representing all of the intersections, or `None`, if there weren’t any. Also returns `None` if the segment and a `Line` are exactly parallel.

class soar.sim.geometry.Point(x, y)¶

Bases: object

Represents a point in the x, y plane.

Points can be interpreted and treated as x, y tuples in most cases.

x¶: float – The x coordinate of the point.

y¶: float – The y coordinate of the point.

Parameters:	x (float) – The x coordinate of the point. y (float) – The y coordinate of the point.

add(other)¶

Vector addition; adds two points.

Parameters:	other – An `(x, y)` tuple or an instance of `Point`.
Returns:	The `Point` that is the sum of this point and the argument.

angle_to(other)¶

Return the angle between two points.

Parameters:	other – An `(x, y)` tuple or an instance of `Point`.
Returns:	Angle in radians of the vector from self to other.
Return type:	float

copy()¶: Returns a copy of the Point.

distance(other)¶

Calculate the distance between two points.

Parameters:	other – An `(x, y)` tuple or an instance of `Point`.
Returns:	The Euclidean distance between the points.
Return type:	float

is_near(other, eps)¶

Determine whether the distance between two points is within a certain value.

Parameters:	other – An `(x, y)` tuple or an instance of `Point`. eps (float) – The epilson within which to consider the points near one another.
Returns:	`True` if the points are withing `eps` of each other, `False` otherwise.
Return type:	bool

magnitude()¶

The magnitude of this point interpreted as a vector.

Returns:	The magnitude of the vector from the origin to this point.
Return type:	float

midpoint(other)¶

Return a new Point that is the midpoint of self and other.

Parameters:	other – An `(x, y)` tuple or an instance of `Point`.
Returns:	A `Point` that is the midpoint of self and other.

rotate(other, theta)¶

Rotate about other by theta radians (positive values are counterclockwise).

Parameters:	other – An `(x, y)` tuple or an instance of `Point`. theta (float) – The number of radians to rotate counterclockwise.
Returns:	The rotated `Point`.

scale(value, other=(0, 0))¶

Scale the vector from other to self by value, and return the endpoint of that vector.

Parameters:	value (float) – The value to scale by. other – An `(x, y)` tuple or a `Point` as the origin to scale from.
Returns:	The endpoint of the scaled vector, as a `Point`.

sub(other)¶

Vector subtraction; subtracts subtracts two points.

Parameters:	other – An `(x, y)` tuple or an instance of `Point`.
Returns:	The `Point` that is the difference of this point and the argument.

xy_tuple()¶: Returns: An (x, y) tuple representing the point.

class soar.sim.geometry.PointCollection(points, center=None)¶

Bases: object

A movable collection of points.

Can be iterated over like a list of Point. Unlike Point, PointCollections are mutable–that is, rotating them, translating them, etc. changes the internal point list.

Parameters:	points – A list of `(x, y)` tuples or `Point`. center – An `(x, y)` tuple or `Point` as the pivot or center of the collection.

recenter(new_center)¶

Re-center the collection.

Parameters:	new_center – An `(x, y)` tuple or `Point` that will be the collection’s new center.

rotate(pivot, theta)¶

Rotate about other by theta radians (positive values are counterclockwise).

Parameters:	pivot – An `(x, y)` tuple or a `Point`. theta (float) – The number of radians to rotate counterclockwise.

scale(value, origin=(0, 0))¶

Scale each point away/towards some origin.

Parameters:	value (float) – The scale amount. origin – An `(x, y)` tuple or `Point` from which the collection’s points will move away/towards.

translate(delta)¶

Translate the collection by the vector delta.

Parameters:	delta – An `(x, y)` tuple or `Point`, treated as a vector and added to each point in the collection.

class soar.sim.geometry.Pose(x, y, t)¶

Bases: soar.sim.geometry.Point

A point facing a direction in the xy plane.

Poses can be interpreted and treated as (x, y, theta) tuples in most cases.

Parameters:	x – The x coordinate of the pose. y – The y coordinate of the pose. t – The angle between the direction the pose is facing and the positive x axis, in radians.

copy()¶: Returns a copy of the Pose.

is_near(other, dist_eps, angle_eps)¶

Determine whether two poses are close.

Parameters:	other – An `(x, y, t)` tuple or `Pose`. dist_eps (float) – The distance epilson within which to consider the poses close. angle_eps (float) – The angle episilon within which to consider the poses close.
Returns:	`True` if the distance between the point portions is within `dist_eps`, and the normalized difference between the angle portions is within `angle_eps`.
Return type:	bool

point()¶

Strips the angle component of the pose and returns a point at the same position.

Returns:	The `(x, y)` portion of the pose, as a `Point`.

rotate(pivot, theta)¶

Rotate the point portion of the pose about a pivot. Leaves the theta portion unchanged.

Parameters:	pivot – A `Point`, subclass (like `Pose`), or `(x, y)` tuple as the pivot/axis of rotation. theta (float) – The number of radians to rotate by. Positive values are counterclockwise.

transform(other)¶

Return a new pose that has been transformed (translated and turned).

Parameters:	other – A `Pose` or 3-tuple-like object, by which to translate and turn.
Returns:	A new `Pose` equivalent to translating `self` by `(other[0], other[1])` and rotating by `other[2]`.

xyt_tuple()¶: Returns: An (x, y, t) tuple representing the pose.

soar.sim.geometry.ccw(p1, p2, p3)¶

Determine whether the turn formed by points p1, p2, and p3 is counterclockwise.

Parameters:	p1 – An `(x, y)` tuple or `Point` as the start of the turn. p2 – An `(x, y)` tuple or `Point` as the midpoint of the turn. p3 – An `(x, y)` tuple or `Point` as the end of the turn.

soar.sim.geometry.clip(value, m1, m2)¶

Clip a value between two bounds.

Parameters:	value (float) – The value to clip. m1 (float) – The first bound. m2 (float) – The second bound.
Returns:	A clipped value guaranteed to be between the min and max of the bounds.
Return type:	float

soar.sim.geometry.normalize_angle_180(theta)¶

Normalize an angle in radians to be within -pi and pi.

Parameters:	theta (float) – The angle to normalize, in radians.
Returns:	The normalized angle.
Return type:	float

soar.sim.geometry.normalize_angle_360(theta)¶

Normalize an angle in radians to be within 0 and 2*pi.

Parameters:	theta (float) – The angle to normalize, in radians.
Returns:	The normalized angle.
Return type:	float