Geometry#

Points, vectors, boxes and circles – the entire vocabulary the solver has for describing a character.

scenet.geom#

Geometry primitives: points, vectors, boxes and circles.

Everything downstream of the frontend speaks in these four types. They are the whole vocabulary the solver has for describing a character – a silhouette is a list of Point, a face is a Circle, a balloon is a BBox, a gaze is a Vector – which is what keeps the layout engine from ever needing to know what anything looks like.

Coordinate system. SVG’s: x runs rightward, y runs downward, and the origin is the panel’s top-left corner. Angles are in degrees, measured clockwise, which is what “clockwise” means once y points down. All lengths are in panel units; a panel declares its own size, so a unit is whatever fraction of the panel you decide it is.

Strictness. Every containment and intersection test here is strict: a point exactly on a circle’s edge is not inside it, and two shapes that merely touch do not intersect. Applied consistently, a shared boundary belongs to neither shape – so two balloons resting edge to edge are legal, and a tail grazing a face outline is not diverted. Mixing strict and non-strict tests would make those cases depend on which function you happened to ask. The one deliberate exception is BBox.contains, documented there.

Immutability. Every type here is frozen and slotted. The balloon search creates these in tight loops, so the memory layout matters; and a resolved layout that cannot be mutated is a layout the emitter cannot quietly change on its way out.

A note on annotations: self- and forward-references are quoted (-> "Point"). Before Python 3.14 and PEP 649 a bare -> Point inside class Point is evaluated at definition time and raises NameError, and BBox and Circle refer to each other mutually so no ordering fixes it. Self is deliberately not used: these methods construct their own class by name, so Self would promise subclass-preserving behaviour the bodies do not deliver.

class scenet.geom.BBox[source]#

Bases: object

An axis-aligned rectangle, given as a corner plus a size.

Balloons are boxes, panel frames are boxes, and every silhouette has one as its bounds. Stored as x, y, width, height rather than as two corners because that is what SVG wants and what the constraint solver’s variables map onto directly.

x#

Left edge.

Type:

float

y#

Top edge.

Type:

float

width#

Extent rightward.

Type:

float

height#

Extent downward.

Type:

float

Example

>>> from scenet.geom import BBox
>>> balloon = BBox(10.0, 20.0, 100.0, 50.0)
>>> balloon.right, balloon.bottom
(110.0, 70.0)
>>> balloon.centre
Point(x=60.0, y=45.0)
property right: float#

The right edge, x + width.

property bottom: float#

The bottom edge, y + height. Larger than y, because y runs downward.

property centre: Point#

The midpoint of the box.

property area: float#

Width times height.

contains(other)[source]#

Whether another box lies entirely within this one.

Edges may coincide: a box exactly filling this one is contained. This is the module’s one deliberate departure from strictness, because a balloon sitting flush against the panel margin is inside the panel.

Parameters:

other (BBox) – The box to test.

Return type:

bool

Returns:

True if no part of other falls outside this box.

overlap_area(other)[source]#

Return the area shared with another box.

Parameters:

other (BBox) – The box to intersect with.

Return type:

float

Returns:

The overlapping area, or 0.0 when the boxes are disjoint or merely touch.

Example

>>> from scenet.geom import BBox
>>> BBox(0.0, 0.0, 10.0, 10.0).overlap_area(BBox(5.0, 5.0, 10.0, 10.0))
25.0
>>> BBox(0.0, 0.0, 10.0, 10.0).overlap_area(BBox(10.0, 0.0, 10.0, 10.0))
0.0
intersects_circle(circle)[source]#

Whether a circle overlaps this box.

Uses the closest-point test: clamp the circle’s centre to the box, then compare that distance against the radius. Strict, so tangency is not an intersection.

This is the test that keeps a balloon off a face.

Parameters:

circle (Circle) – The circle to test, typically an actor’s face exclusion zone.

Return type:

bool

Returns:

True if the two overlap by any positive amount.

expanded(margin)[source]#

Return this box grown by margin on every side.

Parameters:

margin (float) – Distance to add to each edge. A negative value shrinks the box, and a sufficiently negative one inverts it, which is not checked for.

Return type:

BBox

Returns:

A new box, 2 * margin wider and taller than this one.

moved_to(x, y)[source]#

Return this box with the same size at a new top-left corner.

Parameters:
  • x (float) – New left edge.

  • y (float) – New top edge.

Return type:

BBox

Returns:

A new box.

__init__(x, y, width, height)#
class scenet.geom.Circle[source]#

Bases: object

A disc, used throughout as a face exclusion zone.

A head is not a circle, but for layout purposes it is close enough and vastly cheaper than the alternative: every “would this balloon cover someone’s face?” test reduces to one distance comparison.

cx#

Centre x.

Type:

float

cy#

Centre y.

Type:

float

r#

Radius.

Type:

float

Example

>>> from scenet.geom import Circle, Point
>>> head = Circle(100.0, 100.0, 30.0)
>>> head.contains_point(Point(110.0, 100.0))
True
>>> head.contains_point(Point(130.0, 100.0))
False
property centre: Point#

The centre, as a point.

contains_point(point)[source]#

Whether a point lies strictly inside this circle.

Parameters:

point (Point) – The point to test.

Return type:

bool

Returns:

True if the point is inside; False if it is outside or exactly on the edge.

as_bbox()[source]#

Return the smallest axis-aligned box containing this circle.

Return type:

BBox

__init__(cx, cy, r)#
class scenet.geom.Point[source]#

Bases: object

A position in panel space.

The most common type in the codebase. Anchors are points, silhouette hulls are sequences of points, and both ends of a balloon tail are points.

x#

Distance rightward from the panel’s left edge.

Type:

float

y#

Distance downward from the panel’s top edge.

Type:

float

Example

>>> from scenet.geom import Point
>>> mouth = Point(120.0, 84.0)
>>> mouth.translated(0, 10)
Point(x=120.0, y=94.0)
translated(dx, dy)[source]#

Return this point moved by an offset.

Parameters:
  • dx (float) – Rightward offset.

  • dy (float) – Downward offset.

Return type:

Point

Returns:

A new point; this one is unchanged.

rotated_around(origin, degrees)[source]#

Return this point rotated about another.

This is the workhorse of forward kinematics: posing a limb is rotating its far end around its joint.

Parameters:
  • origin (Point) – The centre of rotation.

  • degrees (float) – Rotation angle, clockwise on screen – which is the positive direction once y points downward.

Return type:

Point

Returns:

A new point.

Example

>>> from scenet.geom import Point, rounded
>>> turned = Point(10.0, 0.0).rotated_around(Point(0.0, 0.0), 90)
>>> rounded(turned.x), rounded(turned.y)
(0.0, 10.0)
distance_to(other)[source]#

Return the straight-line distance to another point.

Parameters:

other (Point) – The point to measure to.

Return type:

float

Returns:

Distance in panel units, never negative.

as_tuple()[source]#

Return (x, y) rounded for emission.

Return type:

tuple[float, float]

Returns:

The pair a Panel Core document stores, already passed through rounded.

__init__(x, y)#
class scenet.geom.Vector[source]#

Bases: object

A direction and magnitude, with no position.

Distinct from Point on purpose. A gaze direction and an eye position are both pairs of floats and mean entirely different things; giving them different types means the type checker catches you confusing them.

dx#

Rightward component.

Type:

float

dy#

Downward component.

Type:

float

Example

>>> from scenet.geom import Vector
>>> Vector(3.0, 4.0).length
5.0
>>> Vector(3.0, 4.0).normalised()
Vector(dx=0.6, dy=0.8)
property length: float#

The vector’s magnitude.

normalised()[source]#

Return this vector scaled to unit length.

A zero vector is returned unchanged rather than raising. That lets callers treat “this character is not looking at anything” as a neutral term in the arithmetic instead of special-casing None at every use.

Return type:

Vector

Returns:

A unit vector in the same direction, or the zero vector unchanged.

mirrored_x()[source]#

Return this vector reflected left-to-right.

Used when an actor faces the other way: the whole puppet is mirrored, and its gaze has to come along.

Return type:

Vector

Returns:

A new vector with dx negated.

dot(other)[source]#

Return the dot product with another vector.

Parameters:

other (Vector) – The vector to project onto.

Return type:

float

Returns:

Positive when the two point broadly the same way, negative when opposed, zero when perpendicular.

as_tuple()[source]#

Return (dx, dy) rounded for emission.

Return type:

tuple[float, float]

__init__(dx, dy)#
scenet.geom.rounded(value)[source]#

Round a coordinate for emission.

Uses Python’s built-in round, which is round-half-to-even – so 0.125 becomes 0.12 and 0.135 becomes 0.14. That asymmetry looks like a bug the first time you meet it in a golden file and is not one: half-to-even is deterministic and unbiased, which is exactly what byte-identical output needs.

Adding 0.0 afterwards normalises -0.0 to 0.0. Without it a coordinate that rounds to negative zero emits as -0.0 and produces a spurious diff against an otherwise identical file.

Parameters:

value (float) – A coordinate in panel units.

Return type:

float

Returns:

The value rounded to PRECISION decimal places, never negative zero.

Example

>>> from scenet.geom import rounded
>>> rounded(12.3456)
12.35
>>> rounded(-0.001)
0.0
scenet.geom.segment_intersects_circle(start, end, circle)[source]#

Whether the line segment start to end passes through a circle.

This is the test that decides whether a straight balloon tail would cross somebody’s face, and so whether the tail has to bend instead. Implemented by projecting the circle’s centre onto the segment, clamped to its extent, and comparing that distance to the radius – exact, and cheaper than solving the quadratic.

Parameters:
  • start (Point) – One end of the segment.

  • end (Point) – The other end.

  • circle (Circle) – The obstacle.

Return type:

bool

Returns:

True if any part of the segment lies strictly inside the circle. A segment that only grazes the edge does not count.

Example

>>> from scenet.geom import Circle, Point, segment_intersects_circle
>>> face = Circle(50.0, 50.0, 20.0)
>>> segment_intersects_circle(Point(0.0, 50.0), Point(100.0, 50.0), face)
True
>>> segment_intersects_circle(Point(0.0, 0.0), Point(100.0, 0.0), face)
False

See also

Circle.contains_point, which this falls back to for a zero-length segment.