gewel.draw.MarkerX

class gewel.draw.MarkerX(x: Union[float, Tvf, PyTvf] = 0.0, y: Union[float, Tvf, PyTvf] = 0.0, width: Union[float, Tvf, PyTvf] = 16.0, height: Optional[Union[float, Tvf, PyTvf]] = None, theta: Union[float, Tvf, PyTvf] = 0.0, color: Optional[gewel.color.BaseColor] = None, line_width: Union[float, Tvf, PyTvf] = 1.0, z: Union[float, Tvf, PyTvf] = 0.0, alpha: Union[float, Tvf, PyTvf] = 1.0)

Bases: gewel.draw.MarkerBase

A marker that is the shape of an X. See MarkerBase for more details on markers.

Parameters

• x (tvx.FloatOrTVF) – x location

• y (tvx.FloatOrTVF) – y location

• width (Union[float, Tvf, PyTvf]) – width of the marker

• height – height of the marker

• theta (tvx.FloatOrTVF) – angle of the marker

• color (BaseColor) – color of the marker

• line_width (tvx.FloatOrTVF) – line width

• z (tvx.FloatOrTVF) – depth of the marker

• alpha (tvx.FloatOrTVF) – alpha of the marker

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.
center
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.
local_xform
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.
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
line_width
theta	Angle of rotation in radians.
time	The next-action time.
width
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]