zooui.objects.physicalobject module

An object that obeys the laws of physics.

class zooui.objects.physicalobject.PhysicalObject(initial_zoom=None)

Bases: object

Constructor :

PhysicalObject()

Parameters :

None

PhysicalObject() –> None

Physicalobject objects are sets of declarations and methods that are used to represent anything that has a 3-dimensional position and velocity, where the z-dimension represents a zoomlevel.

PhysicalObject gets declared on MediaObject and Scene initializations, giving them the necessary attributes, (position, zoomlevel, damp factor zoomlevel, eccetera).

Create a new PhysicalObject at the origin with zero velocity.

Initializes position coordinates (_x, _y, _z) to 0.0, where z represents zoomlevel. Initializes velocity components (vx, vy, vz) to 0.0. Sets the center offset (_centre) to (0,0).

This initialization is used by both Scene and MediaObject classes.

Class Inheritance Hierarchy:

PhysicalObject (Abstract Base)
│   • _x, _y, _z (position & zoom)
│   • vx, vy, vz (velocity)
│   • damping factor
│   • _centre (center point)
│
├── MediaObject (Abstract)
│   │   • Coordinate transforms
│   │   • Scaling management
│   │   • Reference frames
│   │
│   ├── TiledMediaObject
│   │       • Large image support
│   │       • Tile grid management
│   │       • Efficient for huge images
│   │
│   ├── StringMediaObject
│   │       • Text rendering
│   │       • Font support
│   │
│   └── SVGMediaObject
│           • Vector graphics
│           • Scalable rendering
│
└── Scene
       • Container for MediaObjects
       • Viewport management
       • Scene persistence
       • Thread-safe operations

_zoom_manager = None

classmethod set_zoom_manager(manager)

Set the ZoomManager instance for all PhysicalObjects.

damping_factor = 1024

__damp(velocity, t)

Method :

__damp(velocity, t)

Parameters :

velocity : float t : float

__damp(velocity, t) –> float

Damp the given velocity over time t.

Applies exponential damping using the formula:

v = u * damping_factor**-t

If the absolute value of the velocity falls below 0.1, it is set to 0.0 to prevent infinitesimal movements.

Returns the damped velocity value.

__displacement(t, u)

Method :

__displacement(t, u)

Parameters :

t : float u : float

__displacement(t, u) –> float

Calculate the displacement at time t given initial velocity u.

Uses the formula derived from integrating the damped velocity:

s(t) = (u / log(d)) * (1 - d**-t)

where d is the damping_factor.

This accounts for the exponential decay of velocity over time.

Returns the calculated displacement.

move(dx, dy)

Method :

PhysicalObject.move(dx, dy)

Parameters :

dx : float dy : float

PhysicalObject.move(dx, dy) –> None

Move the object by the displacement (dx, dy).

Increments the object’s x position by dx and y position by dy.

zoom(amount)

Method :

PhysicalObject.zoom(amount)

Parameters :

amount : float

PhysicalObject.zoom(amount) –> None

Zoom by the given amount with the center maintaining its position on the screen.

Adjusts the position and zoom level such that the center point remains at the same screen coordinates after the zoom operation.

aim(v, s, t=None)

Calculate the initial velocity such that at time t the relative displacement of the object will be s, and increase the velocity represented by v by this amount.

If t is omitted then it will be taken that s is the limit of the displacement as t approaches infinity i.e. the initial velocity will be calculated such that the total displacement will be s once the object has stopped moving.

Parameters :

v : str s : float t : Optional[float]

velocity(string, float[, float]) -> None

Precondition: v is either ‘x’, ‘y’, or ‘z’

step(t)

Method :

PhysicalObject.step(t)

Parameters :

t : float

PhysicalObject.step(t) –> None

Step forward t seconds in time.

Updates the object’s position based on velocity and damping. Calculates displacement for x and y using the velocity and time, then damps the velocities.

If there is z velocity (zoom), applies zoom displacement and damps the z velocity.

This method is called every frame to update physics simulation.

property vzmoving

Property:

PhysicalObject.moving

Parameters :

None

PhysicalObject.moving –> bool

Boolean value indicating whether the object has z non-zero velocity.

Returns True if vz is non-zero. Returns False if all velocity components are zero.

property moving

Property:

PhysicalObject.moving

Parameters :

None

PhysicalObject.moving –> bool

Boolean value indicating whether the object has a non-zero velocity.

Returns True if any of vx, vy, or vz are non-zero. Returns False if all velocity components are zero.

__get_zoomlevel()

Method :

__get_zoomlevel

Parameters :

None

__get_zoomlevel –> float

Get the zoomlevel of the object.

Returns the z-coordinate which represents the zoom level.

__set_zoomlevel(zoomlevel)

Method :

__set_zoomlevel(zoomlevel)

Parameters :

zoomlevel : float

__set_zoomlevel –> None

Set the zoomlevel of the object.

Validates and clamps zoomlevel using ZoomManager if available, then assigns the value to the z-coordinate.

property zoomlevel

Creating PhysicalObject.zoomlevel property with __get_zoomlevel as getter and __set_zoomlevel as setter

__get_centre()

Method :

__get_centre

Parameters :

None

__get_centre –> Tuple[float, float]

Get the on-screen position of the object’s center.

Converts object-coordinate C to screen-coordinate P using:

P = pos + C * math.exp2(zoomlevel)

Note: This definition applies to Scene objects. MediaObjects have their own center definition.

Returns the screen coordinates of the center.

__set_centre(centre)

Method :

__set_centre(centre)

Parameters :

centre : Tuple[float, float]

__set_centre –> None

Set the on-screen position of the object’s center.

Converts screen-coordinate P to object-coordinate C using:

C = (P - pos) * math.exp2(-zoomlevel)

Note: This definition applies to Scene objects. MediaObjects have their own center definition.

property centre

Creating PhysicalObject.centre property with __get_centre as getter and __set_centre as setter