gewel.draw.TimeClock

class gewel.draw.TimeClock(x: Union[float, Tvf, PyTvf], y: Union[float, Tvf, PyTvf], font_size: float = 12, color: gewel.color.BaseColor = Color(red=0.0, green=0.0, blue=0.0, alpha=1.0), show_hours: bool = False, z: Union[float, Tvf, PyTvf] = 0.0)[source]

Bases: gewel.draw._BaseTextDrawable

A drawable that shows the current time.

This is commonly used while developing and debugging animated scenes and then removed before the final version is rendered.

The format of the time shown in MM:SS.mmm’ where `MM is minutes, SS is seconds, and mmm is milliseconds. If the optional show_hours parameter is set to true, then the format is HH:MM:SS.mmm where HH is hours.

See Update Time for an example of how this class is typically used.

Parameters

x – x location
y – y location
font_size (float) – The side of the font to render the time.
color (gewel.color.BaseColor) – The color of the the time.
show_hours – If True, show hours, otherwise don’t.
z – z depth

Methods

`bezier_move_to`	Move to a new location over the course of a given amount of time, following a cubic bezier path specified by the current position, a final position, and two control points.
`current_xy`	Compute the value of x and y at time t.
`draw`	This method renders the drawable into pixels.
`fade_to`	Fade the object from it's current alpha to a new value.
`move_to`	Move to a new location over the course of a given amount of time.
`orbit`	Orbit another object or a point.
`quadratic_move_to`	Move to a new location over the course of a given amount of time, following a quadratic path specified by the current position, a final position, and a control point.
`ramp_attr_to`	Change the value of an attribute of the object from the value it has at the current next-action time to a new value by ramping it linearly between the old and new values over the course of a given duration.
`rotate_to`	Rotate to a new angle over the course of a given amount of time.
`rotate_to_degrees`	Rotate the object a certain number of degrees.
`rotated`	Return a version of the drawable that is rotated.
`rotated_degrees`	Return a version of the drawable that is rotated.
`scaled`	Construct and return a new drawable that is scaled in the x and y directions.
`set_time`	Set the next-action time.
`text`
`track`	Track the motion of another object at a given offset.
`transformed`	Construct and return a new drawable that is transformed by the translation matrix specified by the parameters.
`translated`	Construct and return a new drawable that is translated by a relative amount in the x and y directions.
`wait`	Wait for a specified amount of time.
`wait_for`	Wait for another object to finish whatever action it is currently doing.
`wait_until`	Update the next-action time so that it is at least the given time.
`xy`	Return the possibly time-varying values of x and y.

Attributes

`alpha`	Transparency/opacity.
`color`
`font_size`
`theta`	Angle of rotation in radians.
`time`	The next-action time.
`x`	x value of the object's location.
`y`	y value of the object's location.
`z`	z depth of the object.

bezier_move_to(x1: float, y1: float, x2: float, y2: float, x3: float, y3: float, duration: float, update_time: bool = True, scaffold: bool = False)

Move to a new location over the course of a given amount of time, following a cubic bezier path specified by the current position, a final position, and two control points. This is similar to move_to(), which moves an object along a linear path and quadratic_move_to(), which moves along a quadratic path.

This method is used in the scripting phase of the object’s lifetime to schedule it to move from one location on or off-screen to another. This is one of the core methods used to produce animations.

See Using bezier_move_to() for sample code.

The object follows a cubic path parameterized by \(t\) which varies from 0 to 1 over the duration of motion. The position of the object for any given value of \(t\) is

\[ \begin{align}\begin{aligned}x = (1 - t)^3 x_0 + 3 (1 - t)^2 t x_1 + 3 (1 - t) t^2 x_2 + t^3 x_3\\y = (1 - t)^3 y_0 + 3 (1 - t)^2 t y_1 + 3 (1 - t) t^2 y_2 + t^3 x_3\end{aligned}\end{align} \]

Note that when \(t = 0\), \(x = x_0\) and \(y = y_0\), putting us at the starting point. When \(t = 1\), \(x = x_3\) and \(y = y_3\), putting us at the final point.

Parameters

x1 – The x coordinate of the first control point.
y1 – The y coordinate of the first control point.
x2 – The x coordinate the second control point.
y2 – The y coordinate the second control point.
x3 – The x coordinate to move to.
y3 – The y coordinate to move to.
duration – The amount of time, in seconds, the move from the current location to the new location should take.
update_time – Should the object’s time be updated. Normally this is True. Making it False does not change the time, so that other updates can be made on the same object at the same time it is moving. For example, rotate_to() can be called to make the object spin as it moves.
scaffold – Should we also generate scaffolding to show the path that the object will move along during animation? This is primarily for debugging purposes.

Returns

None if scaffold is False or a Drawable representing the scaffolding if the scaffold is True.

Return type

Drawable or None

current_xy(t: float) → Tuple[float, float]

Compute the value of x and y at time t. self.x and self.y may be time-varying values (See tvx for details). This method returns the floating point values computed for the specified time.

Parameters: t – The time to evaluate the time-varying values self.x and self.y
Returns: A tuple containing the x and y values at the current time.
Return type: Tuple[float, float]

draw(ctx: cairocffi.context.Context, t: float) → None

This method renders the drawable into pixels. Drawable objects typically have time-varying behavior. For example, the x and y location of the object in a scene may be time-varying floats (see the Tvf class for details). It is the responsibility of the draw() method to render the correct pixels for time passed in.

Note that this method is very rarely called directly by user code. Instead, it is called by utility classes that render a Scene containing a Drawable objects. Examples include gewel.record.Mp4Recorder, which renders a scene to an MP4 file, or gewel.player.Player that creates an interactive preview of a Scene or the gewel.draw.Scene.__repr__() method that render a scene into an IPython notebook widget.

Parameters

ctx – The context in which to render. This is an object with low-level drawing primitives that the draw() method relies on to render at the pixel level.
t – The time at which to render. That is, we should render the object as it is intended to appear at this time in the scene. Exactly what that is is typically controlled by properties of the object that are Tvf objects.

fade_to(alpha: Union[float, Tvf, PyTvf], duration: float, update_time: bool = True)

Fade the object from it’s current alpha to a new value. Alpha values range from 0.0, which means completely transparent, to 1.0, which means completely opaque. Most newly constructed Drawable classes that support alpha default to a value of 1.0.

See Using fade_to() for sample usage.

Parameters

alpha – The new alpha value. Should be between 0.0 and 1.0, inclusive. Values outside this range produce undefined behavior that may change in future versions.
duration – The amount of time, in seconds, the fade from the current alpha to the new alpha should take.
update_time – Should the object’s time be updated. Normally this is True. Making it False does not change the time, so that other updates can be made on the same object at the same time it is fading. For example, move_to() can be called to make the object move as it fades.

Returns

Return type

None

move_to(x: float, y: float, duration: float, update_time: bool = True, scaffold: bool = False) → Optional[gewel.draw.Drawable]

Move to a new location over the course of a given amount of time. This method is used in the scripting phase of the object’s lifetime to schedule it to move from one location on or off-screen to another. This is one of the core methods used to produce animations.

The object follows a linear path parameterized by \(t\) which varies from 0 to 1 over the duration of motion. The position of the object for any given value of \(t\) is

\[ \begin{align}\begin{aligned}x = (1 - t) x_0 + t x_1\\y = (1 - t) y_0 + t y_1\end{aligned}\end{align} \]

Note that when \(t = 0\), \(x = x_0\) and \(y = y_0\), putting us at the starting point. When \(t = 1\), \(x = x_1\) and \(y = y_1\), putting us at the final point.

See Using move_to() for sample usage.

Parameters

x – The x coordinate to move to.
y – The y coordinate to move to.
duration – The amount of time, in seconds, the move from the current location to the new location should take.
update_time – Should the object’s time be updated. Normally this is True. Making it False does not change the time, so that other updates can be made on the same object at the same time it is moving. For example, rotate_to() can be called to make the object spin as it moves.
scaffold – Should we also generate scaffolding to show the path that the object will move along during animation? This is primarily for debugging purposes.

Returns

None if scaffold is False or a Drawable representing the scaffolding if the scaffold is True.

Return type

Drawable or None

orbit(other: Union[XYDrawable, Tuple[Union[float, Tvf, PyTvf], Union[float, Tvf, PyTvf]]], x_amplitude: Union[float, Tvf, PyTvf], y_amplitude: Union[float, Tvf, PyTvf], orbit_duration: float, phase: float = 0.0, ccw: bool = False)

Orbit another object or a point. The orbit motion begins at self’s next-action time and continues until either the scene ends or another action that affects the location is taken.

See A Motion Linked Solar System for sample code.

Parameters

other – The object to orbit. If it is an XYDrawable, the center of the orbit will be it’s location. If it is a tuple of two elements, those elements are the x and y center of the orbit. In either case, the center of the orbit can be time-varying.
x_amplitude – The amplitude of the orbit in the x direction.
y_amplitude – The amplitude of the orbit in the y direction.
orbit_duration – How long it takes to complete one orbit, in seconds.
phase – The phase of the orbit in radians. This determines the location of the orbiting object at the beginning of the orbit time.
ccw – If TRUE the orbit is in a counter-clockwise direction. Otherwise, it is in a clockwise direction.

quadratic_move_to(x1: float, y1: float, x2: float, y2: float, duration: float, update_time: bool = True, scaffold: bool = False) → Optional[gewel.draw.Drawable]

Move to a new location over the course of a given amount of time, following a quadratic path specified by the current position, a final position, and a control point. This is similar to move_to(), which moves an object along a linear path.

This method is used in the scripting phase of the object’s lifetime to schedule it to move from one location on or off-screen to another. This is one of the core methods used to produce animations.

See Using quadratic_move_to() for sample code.

The object follows a quadratic path parameterized by \(t\) which varies from 0 to 1 over the duration of motion. The position of the object for any given value of \(t\) is

\[ \begin{align}\begin{aligned}x = (1 - t)^2 x_0 + 2 (1 - t) t x_1 + t^2 x_2\\y = (1 - t)^2 y_0 + 2 (1 - t) t y_1 + t^2 y_2\end{aligned}\end{align} \]

Note that when \(t = 0\), \(x = x_0\) and \(y = y_0\), putting us at the starting point. When \(t = 1\), \(x = x_2\) and \(y = y_2\), putting us at the final point.

Parameters

x1 – The x coordinate of the control point.
y1 – The y coordinate of the control point.
x2 – The x coordinate to move to.
y2 – The y coordinate to move to.
duration – The amount of time, in seconds, the move from the current location to the new location should take.
update_time – Should the object’s time be updated. Normally this is True. Making it False does not change the time, so that other updates can be made on the same object at the same time it is moving. For example, rotate_to() can be called to make the object spin as it moves.
scaffold – Should we also generate scaffolding to show the path that the object will move along during animation? This is primarily for debugging purposes.

Returns

None if scaffold is False or a Drawable representing the scaffolding if the scaffold is True.

Return type

Drawable or None

ramp_attr_to(name: str, to: float, duration: float, update_time: bool = True) → None

Change the value of an attribute of the object from the value it has at the current next-action time to a new value by ramping it linearly between the old and new values over the course of a given duration.

See Next-Action Time During Scripting for more on next-action time.

Parameters

name – Name of the attribute to update.
to – Value to change to.
duration – Time in seconds over which the value ramps from the old to the new value.
update_time – If True, update the object’s next-action time so that it is duration later than it was.

rotate_to(theta: float, duration: float, update_time: bool = True, scaffold: bool = False) → Optional[gewel.draw.Drawable]

Rotate to a new angle over the course of a given amount of time. This method is used in the scripting phase of the object’s lifetime to schedule it to rotate the object. This is one of the core methods used to produce animations.

See Using rotate_to() for sample usage.

Parameters

theta – The angle to rotate to, expressed in radians. The drawable will be rotated from it’s current angle to this value. When a drawable is first created it’s angle is normally set to zero, though individual class constructors may allow this default to be overridden. If you would prefer to specify angles in degrees instead of radians, see rotate_to_degrees().
duration – The amount of time, in seconds, the rotation from the current angle to the new angle should take.
update_time – Should the object’s time be updated. Normally this is True. Making it False does not change the time, so that other updates can be made on the same object at the same time it is moving. For example, move_to() can be called to make the object move as it rotates.
scaffold – Should we also generate scaffolding to show the path that the object will move along during animation? This is primarily for debugging purposes.

Returns

None if scaffold is False or a Drawable representing the scaffolding if the scaffold is True.

Return type

Drawable or None

rotate_to_degrees(degrees: float, duration: float, update_time: bool = True, scaffold: bool = False) → Optional[gewel.draw.Drawable]

Rotate the object a certain number of degrees. See rotate_to() for more details and an example. The only difference here is that the angle of rotation is expressed in degrees instead of radians.

Note that

d.rotate_to_degrees(180, 1.0)

and

import numpy as np

d.rotate_to(np.pi, 1.0)

are equivalent because 180 degrees is the same as pi radians.

See Using rotate_to_degrees() for sample usage.

Parameters

degrees – The angle to rotate to, expressed in degrees. The drawable will be rotated from it’s current angle to this value. When a drawable is first created it’s angle is normally set to zero, though individual class constructors may allow this default to be overridden. If you would prefer to specify angles in radians instead of degrees, see rotate_to().
duration – The amount of time, in seconds, the rotation from the current angle to the new angle should take.
update_time – Should the object’s time be updated. Normally this is True. Making it False does not change the time, so that other updates can be made on the same object at the same time it is moving. For example, move_to() can be called to make the object move as it rotates.
scaffold – Should we also generate scaffolding to show the path that the object will move along during animation? This is primarily for debugging purposes.

Returns

None if scaffold is False or a Drawable representing the scaffolding if the scaffold is True.

Return type

Drawable or None

rotated(radians: Union[float, Tvf, PyTvf], z: Optional[Union[float, Tvf, PyTvf]] = None) → Drawable

Return a version of the drawable that is rotated. See also rotated_degrees().

Parameters

radians – How much to rotate by, in radians.
z – The z depth of the resulting drawable. If not supplied, the z depth of self is used.

Returns

A new drawable that renders as the original but rotated.

Return type

Drawable

rotated_degrees(degrees: Union[float, Tvf, PyTvf], z: Optional[Union[float, Tvf, PyTvf]] = None) → Drawable

Return a version of the drawable that is rotated. See also rotated().

Parameters

degrees – How much to rotate by, in degrees.
z – The z depth of the resulting drawable. If not supplied, the z depth of self is used.

Returns

A new drawable that renders as the original but rotated.

Return type

Drawable

scaled(sx: Union[float, Tvf, PyTvf], sy: Optional[Union[float, Tvf, PyTvf]] = None, z: Optional[Union[float, Tvf, PyTvf]] = None) → Drawable

Construct and return a new drawable that is scaled in the x and y directions.

Parameters

sx – Scale in the x direction.
sy – Scale in the y direction.
z – The z depth of the resulting drawable. If not supplied, the z depth of self is used.

Returns

A new drawable that renders as the original but scaled.

Return type

Drawable

set_time(t: float)

Set the next-action time.

See Next-Action Time During Scripting for more on next-action time.

Parameters: t – The new next-action time.

property time: float

The next-action time. See Next-Action Time During Scripting for more on next-action time.

Returns: The next action time.
Return type: float

track(other: XYDrawable, x_offset: Union[float, Tvf, PyTvf] = 0.0, y_offset: Union[float, Tvf, PyTvf] = 0.0)

Track the motion of another object at a given offset. The offset can be either a constant or time-varying. The tracking begins at self’s next-action time and continues until either the scene ends or another action that affects the location is taken.

See Motion Linking with track() for sample code.

Parameters

other – The object to offset from.
x_offset – The offset in the x direction.
y_offset – The offset in the y direction.

transformed(xx: Union[float, Tvf, PyTvf] = 1.0, yx: Union[float, Tvf, PyTvf] = 0.0, xy: Union[float, Tvf, PyTvf] = 0.0, yy: Union[float, Tvf, PyTvf] = 1.0, x0: Union[float, Tvf, PyTvf] = 0.0, y0: Union[float, Tvf, PyTvf] = 0.0, z: Optional[Union[float, Tvf, PyTvf]] = None) → Drawable

Construct and return a new drawable that is transformed by the translation matrix specified by the parameters. The default parameter values produce the identity transform.

The location of any point (x, y) in the original drawable is translated to the new point (x’, y’) where

x’ = xx * x + xy * y + x0

and

y’ = yy * y + yx * x + y0

Parameters

xx – Element of the matrix.
yx – Element of the matrix.
xy – Element of the matrix.
yy – Element of the matrix.
x0 – Translation in x
y0 – Translation in y
z – z depth of the new drawable. If None then self.z is used.

Returns

A transformed version of self.

Return type

Drawable

translated(dx: Union[float, Tvf, PyTvf], dy: Union[float, Tvf, PyTvf], z: Optional[Union[float, Tvf, PyTvf]] = None) → Drawable

Construct and return a new drawable that is translated by a relative amount in the x and y directions.

Parameters

dx – How far to translate in the x direction.
dy – How far to translate in the y direction.
z – The z depth of the resulting drawable. If not supplied, the z depth of self is used.

Returns

A new drawable that renders as the original but translated.

Return type

Drawable

wait(duration: float) → None

Wait for a specified amount of time. This updates the object’s next-action time by adding a constant amount of time to it.

See Next-Action Time During Scripting for more on next-action time.

Parameters: duration – How long to wait, in seconds.

wait_for(other: Union[gewel._timekeeper.TimekeeperMixin, Iterable[gewel._timekeeper.TimekeeperMixin]]) → None

Wait for another object to finish whatever action it is currently doing. This method us used at scripting time to ensure that an object updates its next-action time so that it is no earlier than the next-action time of another object.

See Next-Action Time During Scripting for more on next-action time.

Parameters: other – The object to wait for. Or, an iterable collection of objects. If iterable, then wait for the one with the latest time.

wait_until(at_least: float) → None

Update the next-action time so that it is at least the given time. If it is already greater than that, change nothing.

See Next-Action Time During Scripting for more on next-action time.

Parameters: at_least – The minimum new next-action time.

xy() → Tuple[Union[float, Tvf, PyTvf], Union[float, Tvf, PyTvf]]

Return the possibly time-varying values of x and y.

Returns: The tuple (self.x, self.y).
Return type: Tuple[tvx.FloatOrTVF, tvx.FloatOrTVF]