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:
objectAn 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, heightrather than as two corners because that is what SVG wants and what the constraint solver’s variables map onto directly.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)
- 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.
- overlap_area(other)[source]#
Return the area shared with another box.
- Parameters:
other (
BBox) – The box to intersect with.- Return type:
- Returns:
The overlapping area, or
0.0when 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.
- __init__(x, y, width, height)#
- class scenet.geom.Circle[source]#
Bases:
objectA 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.
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
- __init__(cx, cy, r)#
- class scenet.geom.Point[source]#
Bases:
objectA 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.
Example
>>> from scenet.geom import Point >>> mouth = Point(120.0, 84.0) >>> mouth.translated(0, 10) Point(x=120.0, y=94.0)
- 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:
- Return type:
- 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)
- __init__(x, y)#
- class scenet.geom.Vector[source]#
Bases:
objectA direction and magnitude, with no position.
Distinct from
Pointon 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.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)
- 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
Noneat every use.- Return type:
- 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:
- Returns:
A new vector with
dxnegated.
- __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 – so0.125becomes0.12and0.135becomes0.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.0afterwards normalises-0.0to0.0. Without it a coordinate that rounds to negative zero emits as-0.0and produces a spurious diff against an otherwise identical file.- Parameters:
value (
float) – A coordinate in panel units.- Return type:
- Returns:
The value rounded to
PRECISIONdecimal 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
starttoendpasses 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:
- Return type:
- 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.