zooui.objects.mediaobjects.stringmediaobject module

Strings to be displayed in the ZUI.

class zooui.objects.mediaobjects.stringmediaobject.StringMediaObject(media_id, scene)

Bases: MediaObject

Constructor :

StringMediaObject(media_id, scene)

Parameters :

media_id : str scene : Scene

StringMediaObject(media_id, scene) –> None

StringMediaObject implements a hybrid rendering system for text displayin the ZUI.

StringMediaObject.media_id should be of the form ‘string:rrggbb:foobar’, where ‘rrggbb’ is a string of three two-digit hexadecimal numbers representing the colour of the text, and ‘foobar’ is the string to be displayed.

Overview:

• render Dual-mode triggered by scene.vzmoving (zoom velocity)

• moving mode: Direct QPainter.drawText() rendering for smooth zoom/pan operations

• static mode: Cached QImage rendering for optimal quality when stationary

• Automatic cache invalidation when movement starts to ensure fresh rendering

From “foobar” string QImage gets generated, from form ‘string:rrggbb:foobar’ hash get’s generated for cache invalidation in case string color of text content changes. Also Qfont, QFontMetrics, text dimension (width, height), and scale are cached.

QImage cached image gets invalidated if relative_scale_diff > 1% or if self__scene_vzmoving returns True

For direct text rendering :

• longest line index gets Pre-calculated for efficient multi-line rendering

• Font creation only when point size ≥ 1 (visible text)

• Visibility culling based on viewport size ratios

• Automatic cache validation with comprehensive invalidation triggers

Initialize a new StringMediaObject from the media identified by media_id, and the parent Scene referenced by scene.

transparent = True

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)

base_pointsize = 24.0

__compute_text_hash()

Method :

StringMediaObject.__compute_text_hash()

Parameters :

None

StringMediaObject.__compute_text_hash() –> int

Compute hash of text content and color for cache invalidation. Returns a combined hash of all text lines and the color RGB value.

__is_image_cache_valid(current_scale, mode)

Method :

StringMediaObject.__is_image_cache_valid(current_scale, mode)

Parameters :

current_scale : float mode : int

StringMediaObject.__is_image_cache_valid(current_scale, mode) –> bool

Check if cached text image is valid for current scale and render mode. Returns True if cache is valid, False otherwise.

__render_text_direct(painter, x, y, mode)

Method :

StringMediaObject.__render_text_direct(painter, x, y, mode)

Parameters :

painter : QPainter x : float - x position to render at y : float - y position to render at mode : int

StringMediaObject.__render_text_direct(painter, x, y, mode) –> None

Render text directly using QPainter.drawText(). This is the original rendering method used before caching was implemented.

__render_text_to_image(mode)

Method :

StringMediaObject.__render_text_to_image(mode)

Parameters :

mode : int

StringMediaObject.__render_text_to_image(mode) –> QImage

Render text to QImage for caching. Creates a transparent image with the text rendered at current scale.

invalidate_cache()

Method :

StringMediaObject.invalidate_cache()

Parameters :

None

StringMediaObject.invalidate_cache() –> None

Invalidate text image cache. Clears all cached image data to force re-rendering on next render call.

_get_text()

Get the text content for parallel rendering.

Returns:

The text string to render

_get_font()

Get the font properties for parallel rendering (thread-safe).

Returns plain Python data (dict) instead of a QFont object so that this method can be safely called from any thread. QtGui.QFont construction is deferred to TextLayoutData.to_qfont() which runs on the main thread during rendering.

Returns:

family, pointsize, weight, italic

Return type:

dict with keys

_get_color()

Get the text color for parallel rendering.

Returns:

QColor object for text color

precalculate_layout(viewport_rect)

Pre-calculate layout data for parallel rendering.

Parameters:

viewport_rect – Current viewport rectangle

Returns:

TextLayoutData if successful, None otherwise

render_with_layout(painter, layout_data)

Render text using pre-calculated layout data.

Parameters:

• painter – QPainter object to render with

• layout_data – Pre-calculated TextLayoutData

Returns:

True if rendering successful, False otherwise

get_parallel_stats()

Get parallel rendering statistics.

Returns:

Dictionary with parallel rendering statistics

enable_parallel_rendering(enabled=True)

Enable or disable parallel rendering for this object.

Parameters:

enabled – Whether to enable parallel rendering

render(painter, mode)

Method :

StringMediaObject.render(painter, mode)

Parameters :

painter : QPainter mode : int

StringMediaObject.render(painter, mode) –> None

Given QPainter and Rendering mode renders the string calculating the rendering rectangle and using QtPainter.drawText

Note: Size visibility is checked by the scene via is_size_visible().

is_size_visible(mode)

String-specific size visibility check.

Returns False if text is too small or too large to be visible, otherwise returns super().is_size_visible(mode).

property __pointsize

Property:

__pointsize

Parameters :

None

__pointsize –> float

Calculate and return the font point size based on the current scale.

Returns base_pointsize multiplied by the current scale factor.

property __font

Property:

__font

Parameters :

None

__font –> QFont or None

Create and return a QFont object with the appropriate point size for the current scale.

Returns minimum font (1.0 point) if the point size is less than 1. Otherwise returns a Sans Serif font with the calculated point size.

Uses caching to avoid recreating font objects on every access.

property onscreen_size

Property:

StringMediaObject.onscreen_size

Parameters :

None

StringMediaObject.onscreen_size –> Tuple[float, float]

Returns width and height of the MediaObject passed to the StringMediaObject Class.

Uses caching to avoid recalculating size on every access.

property lines

Property:

lines

Parameters :

None

lines –> list[str]

Get the list of text lines.