zooui.objects.mediaobjects.mediaobject module

Media to be displayed in the ZUI (abstract base class).

class zooui.objects.mediaobjects.mediaobject.MediaObject(media_id, scene)[source]

Bases: PhysicalObject

Create a new MediaObject from the media identified by media_id, and the parent Scene referenced by scene.

Initializes PhysicalObject center, position and velocity attributes, then sets the _media_id and _scene instance variables.

transparent = False
Constructor:

MediaObject(media_id, scene)

Parameters :

media_id[‘string’], scene[‘Scene’]

Media_object(media_id, scene) –> PhysicalObject

MediaObject objects are used to represent media that can be rendered in the ZUI.

Screen view it’s fixed unless user change mainwindow size on the screen. Both scene and MediaObjects have their own reference systems so that zooms can be applied bot to Scene and Mediaobject indipendently trough their reference system transformation.

You can think about it as fixed window looking at a scene that can strecth or shrink beneath it, with this stretch or shrink always having it’s origin at the Scene center for scene zoom and MediaObject center for the mediobject zoom as at the same time individual mediaobject can also strecth or shrink. The fixed window can then move on the 2d plane bringing objects into view.

World:

 --------------------------------------->
|   Scene
|  @ ------------------------------+--->
|  |  ViewPort        MediaObj     |
|  |  (Screen View)   *-------+--> |
|  |                  |   &   |    |
|  |               %  +-------"    |
|  |                  |            |
|  |                  ∨            |
|  |                               |
|  +-------------------------------#
|  |
|  ∨
∨

Legend:

(All attributes are relative to screen view)
* -> MediaObject.topleft()
" -> MediaObject.bottomright()
& -> MediaObject.center()
# -> Scene.viewport_size()
% -> Scene.center()
@ -> Scene.origin()

MediaObject topleft coordinates relative to screen view are given by:

MediaObject.topleft[0-1] = self._scene.origin[0-1] + self.pos[0-1] * (2 ** self._scene.zoomlevel)

Where self.pos[0-1] it’s MediaObject position relative to Scene reference system wich get’s scaled by math.exp2() of scene zoom level

MediaObject centre coordinates relative to screen view are given firstly by calculating image center coordinates relative to Scene reference coordinates:

C_s[0-1] = self.pos[0-1] + self._centre[0-1] * math.exp2(self._z)

Where self._centre[0-1] are center coordinates relative to the mediaobject frame of reference and self._z it’s MediaObject reference frame scaling (zoom).

Take note that self.pos[0-1] dosen’t get to be scaled by self._z as that position it’s relative to Scene reference frame.

Then we can calculate MediaObject centre coordinates relative to screen view as:

MediaObject.centre[0-1] = self._scene.origin[0] + C_s[0-1] * math.exp2(self._scene.zoomlevel)
render(painter, mode)[source]
Method :

MediaObject.render(painter, mode)

Parameters :

painter : QPainter mode : int

MediaObject.render(painter, mode) –> None

Render the media using the given painter and rendering mode.

Precondition: mode is equal to one of the constants defined in RenderMode

is_size_visible(mode)[source]

Check if object is visible based on size and render mode.

Parameters:

mode – RenderMode (Invisible, Draft, or HighQuality)

Returns:

True if object should be rendered, False if too small, too large, or mode is Invisible.

Base implementation returns True unless mode is Invisible. Subclasses should override to add size-based visibility checks.

move(dx, dy)[source]
Method :

MediaObject.move(dx, dy)

Parameters :

dx : float dy : float

MediaObject.move(dx, dy) –> None

Move the image relative to the scene, where (dx,`dy`) is given as an on-screen distance.

zoom(amount)[source]
Method :

MediaObject.zoom(amount)

Parameters :

amount : float

MediaObject.zoom(amount) –> None

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

hides(other)[source]
Method :

MediaObject.hides(other)

Parameters :

other : MediaObject

MediaObject.hides(other) –> bool

Returns True iff other is completely hidden behind self on the screen.

fit(bbox)[source]
Method :

MediaObject.fit(bbox)

Parameters :

bbox : Tuple[float, float, float, float]

MediaObject.fit(bbox) –> None

Move and resize the image such that it is the greatest size possible whilst fitting inside and centred in the onscreen bounding box bbox (x1,y1,x2,y2).

property media_id
Property:

MediaObject.media_id

Parameters :

None

MediaObject.media_id –> str

The object’s media_id.

property scale
Property:

MediaObject.scale

Parameters :

None

MediaObject.scale –> float

The factor by which each dimension of the image should be scaled when rendering it to the screen.

property topleft
Property:

MediaObject.topleft

Parameters :

None

MediaObject.topleft –> Tuple[float, float]

The on-screen position of the top-left corner of the image. self._scene.origin -> the world-space X coordinate of the top-left of the screen view (the camera/view origin) self.pos -> the object’s position inside the view before applying zoom (a coordinate in the camera’s internal coordinate system)

here self.pos() is mediaobject

property onscreen_size
Property:

MediaObject.onscreen_size

Parameters :

None

MediaObject.onscreen_size –> Tuple[float, float]

The on-screen size of the image. This gets inherited by higher order classes (StringMediaObject, TiledMediaObject, etc.)

property bottomright
Property:

MediaObject.bottomright

Parameters :

None

MediaObject.bottomright –> Tuple[float, float]

The on-screen position of the bottom-right corner of the image.

property onscreen_area
Property:

MediaObject.onscreen_area

Parameters :

None

MediaObject.onscreen_area –> float

The number of pixels the image occupies on the screen.

__get_pos()
Method :

__get_pos

Parameters :

None

__get_pos –> Tuple[float, float]

Return MediaObject position (_x, _y).

__set_pos(pos)
Method :

__set_pos(pos)

Parameters :

pos : Tuple[float, float]

__set_pos –> None

Set self._x, self._y variables to MediaObject position.

property pos

Creating MediaObject.pos property with __get_pos as getter and __set_pos as setter

__get_centre()
Method :

__get_centre

Parameters :

None

__get_centre –> Tuple[float, float]

Get the on-screen position of the MediaObject center.

Converts image-coordinate C_i to screen-coordinate P through scene-coordinate C_s using the formulas:

P = scene.origin + C_s * math.exp2(zoomlevel_s)
C_s = self.pos + C_i * math.exp2(zoomlevel_i)
__set_centre(centre)
Method :

__set_centre(centre)

Parameters :

centre : Tuple[float, float]

__set_centre –> None

Set the on-screen position of the MediaObject center.

Converts screen-coordinate P to image-coordinate C_i through scene-coordinate C_s using the formulas:

P = scene.origin + C_s * math.exp2(zoomlevel_s)
C_s = self.pos + C_i * math.exp2(zoomlevel_i)
property centre

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

to_dict()[source]
Method :

MediaObject.to_dict()

Parameters :

None

MediaObject.to_dict() –> Dict[str, Any]

Serialize object to dictionary for copying.

classmethod from_dict(data, scene)[source]
Method :

MediaObject.from_dict(data, scene)

Parameters :

data : Dict[str, Any] scene : Any

MediaObject.from_dict(data, scene) –> MediaObject

Create MediaObject from serialized data. Subclasses must override this method.

exception zooui.objects.mediaobjects.mediaobject.LoadError[source]

Bases: Exception

Exception :

LoadError

LoadError exception is raised when there is an error loading or processing media content. This can occur during file loading, format conversion, or media initialization.

class zooui.objects.mediaobjects.mediaobject.RenderMode[source]

Bases: object

Class :

RenderMode

RenderMode is a namespace class that defines constants used to indicate the rendering mode for MediaObjects.

Constants:
Invisibleint = 0

MediaObject should not be rendered at all

Draftint = 1

MediaObject should be rendered in draft/fast mode

HighQualityint = 2

MediaObject should be rendered in high quality mode

Invisible = 0
Draft = 1
HighQuality = 2