Skip to content

Scattered

Demo

Quick Start

scattered.py
from terminaltexteffects.effects.effect_scattered import Scattered

effect = Scattered("YourTextHere")
with effect.terminal_output() as terminal:
    for frame in effect:
        terminal.print(frame)

Text is scattered across the canvas and moves into position.

Classes:

Name Description
Scattered

Move the characters into place from random starting locations.
ScatteredConfig

Configuration for the Scattered effect.
ScatteredIterator

Effect iterator for the effect. Does not normally need to be called directly.

Scattered

Bases: BaseEffect[ScatteredConfig]

Text is scattered across the canvas and moves into position.

Attributes:

Name Type Description
effect_config ScatteredConfig

Configuration for the effect.
terminal_config TerminalConfig

Configuration for the terminal.
Source code in terminaltexteffects/effects/effect_scattered.py 
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
class Scattered(BaseEffect[ScatteredConfig]):
    """Text is scattered across the canvas and moves into position.

    Attributes:
        effect_config (ScatteredConfig): Configuration for the effect.
        terminal_config (TerminalConfig): Configuration for the terminal.

    """

    @property
    def _config_cls(self) -> type[ScatteredConfig]:
        return ScatteredConfig

    @property
    def _iterator_cls(self) -> type[ScatteredIterator]:
        return ScatteredIterator

ScatteredConfig dataclass

Bases: BaseConfig

Configuration for the effect.

Attributes:

Name Type Description
movement_speed float

Movement speed of the characters. Valid values are n > 0.
movement_easing EasingFunction

Easing function to use for character movement.
final_gradient_stops tuple[Color, ...]

Tuple of colors for the character gradient. If only one color is " "provided, the characters will be displayed in that color.
final_gradient_steps tuple[int, ...] | int

Tuple of the number of gradient steps to use. More steps will " "create a smoother and longer gradient animation. Valid values are n > 0.
final_gradient_frames int

Number of frames to display each gradient step. Increase to slow down the " "gradient animation.
final_gradient_direction Direction

Direction of the final gradient.
Source code in terminaltexteffects/effects/effect_scattered.py 
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
@dataclass
class ScatteredConfig(BaseConfig):
    """Configuration for the effect.

    Attributes:
        movement_speed (float): Movement speed of the characters. Valid values are n > 0.
        movement_easing (easing.EasingFunction): Easing function to use for character movement.
        final_gradient_stops (tuple[Color, ...]): Tuple of colors for the character gradient. If only one color is "
            "provided, the characters will be displayed in that color.
        final_gradient_steps (tuple[int, ...] | int): Tuple of the number of gradient steps to use. More steps will "
            "create a smoother and longer gradient animation. Valid values are n > 0.
        final_gradient_frames (int): Number of frames to display each gradient step. Increase to slow down the "
            "gradient animation.
        final_gradient_direction (Gradient.Direction): Direction of the final gradient.

    """

    parser_spec: argutils.ParserSpec = argutils.ParserSpec(
        name="scattered",
        help="Text is scattered across the canvas and moves into position.",
        description="scattered | Text is scattered across the canvas and moves into position.",
        epilog=(
            f"{argutils.EASING_EPILOG} Example: terminaltexteffects scattered --final-gradient-stops ff9048 "
            "ab9dff bdffea --final-gradient-steps 12 --final-gradient-frames 9 --final-gradient-direction vertical "
            "--movement-speed 0.5 "
            "--movement-easing IN_OUT_BACK"
        ),
    )

    movement_speed: float = argutils.ArgSpec(
        name="--movement-speed",
        type=argutils.PositiveFloat.type_parser,
        default=0.5,
        metavar=argutils.PositiveFloat.METAVAR,
        help="Movement speed of the characters. ",
    )  # pyright: ignore[reportAssignmentType]
    "float : Movement speed of the characters. "

    movement_easing: easing.EasingFunction = argutils.ArgSpec(
        name="--movement-easing",
        default=easing.in_out_back,
        type=argutils.Ease.type_parser,
        help="Easing function to use for character movement.",
    )  # pyright: ignore[reportAssignmentType]
    "easing.EasingFunction : Easing function to use for character movement."

    final_gradient_stops: tuple[Color, ...] = FinalGradientStopsArg(
        default=(Color("#ff9048"), Color("#ab9dff"), Color("#bdffea")),
    )  # pyright: ignore[reportAssignmentType]
    (
        "tuple[Color, ...] : Tuple of colors for the character gradient. If only one color is provided, the "
        "characters will be displayed in that color."
    )

    final_gradient_steps: tuple[int, ...] | int = FinalGradientStepsArg(
        default=12,
    )  # pyright: ignore[reportAssignmentType]
    (
        "tuple[int, ...] | int : Int or Tuple of ints for the number of gradient steps to use. More steps will create "
        "a smoother and longer gradient animation."
    )

    final_gradient_frames: int = FinalGradientFramesArg(
        default=9,
    )  # pyright: ignore[reportAssignmentType]
    "int : Number of frames to display each gradient step. Increase to slow down the gradient animation."

    final_gradient_direction: Gradient.Direction = FinalGradientDirectionArg(
        default=Gradient.Direction.VERTICAL,
    )  # pyright: ignore[reportAssignmentType]
    "Gradient.Direction : Direction of the final gradient."

    @classmethod
    def get_effect_class(cls) -> type[Scattered]:
        """Get the effect class associated with this configuration."""
        return Scattered

final_gradient_direction = FinalGradientDirectionArg(default=(Gradient.Direction.VERTICAL)) class-attribute instance-attribute

Gradient.Direction : Direction of the final gradient.

final_gradient_frames = FinalGradientFramesArg(default=9) class-attribute instance-attribute

int : Number of frames to display each gradient step. Increase to slow down the gradient animation.

final_gradient_steps = FinalGradientStepsArg(default=12) class-attribute instance-attribute

tuple[int, ...] | int : Int or Tuple of ints for the number of gradient steps to use. More steps will create a smoother and longer gradient animation.

final_gradient_stops = FinalGradientStopsArg(default=(Color('#ff9048'), Color('#ab9dff'), Color('#bdffea'))) class-attribute instance-attribute

tuple[Color, ...] : Tuple of colors for the character gradient. If only one color is provided, the characters will be displayed in that color.

movement_easing = argutils.ArgSpec(name='--movement-easing', default=(easing.in_out_back), type=(argutils.Ease.type_parser), help='Easing function to use for character movement.') class-attribute instance-attribute

easing.EasingFunction : Easing function to use for character movement.

movement_speed = argutils.ArgSpec(name='--movement-speed', type=(argutils.PositiveFloat.type_parser), default=0.5, metavar=(argutils.PositiveFloat.METAVAR), help='Movement speed of the characters. ') class-attribute instance-attribute

float : Movement speed of the characters.

get_effect_class() classmethod

Get the effect class associated with this configuration.

Source code in terminaltexteffects/effects/effect_scattered.py 
107
108
109
110
@classmethod
def get_effect_class(cls) -> type[Scattered]:
    """Get the effect class associated with this configuration."""
    return Scattered

ScatteredIterator

Bases: BaseEffectIterator[ScatteredConfig]

Effect iterator for the effect.

Source code in terminaltexteffects/effects/effect_scattered.py 
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
class ScatteredIterator(BaseEffectIterator[ScatteredConfig]):
    """Effect iterator for the effect."""

    def __init__(self, effect: Scattered) -> None:
        """Initialize the effect iterator."""
        super().__init__(effect)
        self.pending_chars: list[EffectCharacter] = []
        self.character_final_color_map: dict[EffectCharacter, ColorPair] = {}
        self.build()

    def build(self) -> None:
        """Build the effect."""
        final_gradient = Gradient(*self.config.final_gradient_stops, steps=self.config.final_gradient_steps)
        final_gradient_mapping = final_gradient.build_coordinate_color_mapping(
            self.terminal.canvas.text_bottom,
            self.terminal.canvas.text_top,
            self.terminal.canvas.text_left,
            self.terminal.canvas.text_right,
            self.config.final_gradient_direction,
        )
        for character in self.terminal.get_characters():
            if self.terminal.config.existing_color_handling == "dynamic":
                self.character_final_color_map[character] = ColorPair(
                    fg=character.animation.input_fg_color,
                    bg=character.animation.input_bg_color,
                )
            else:
                self.character_final_color_map[character] = ColorPair(
                    fg=final_gradient_mapping[character.input_coord],
                )
            if self.terminal.canvas.right < 2 or self.terminal.canvas.top < 2:
                character.motion.set_coordinate(Coord(1, 1))
            else:
                character.motion.set_coordinate(self.terminal.canvas.random_coord())
            input_coord_path = character.motion.new_path(
                speed=self.config.movement_speed,
                ease=self.config.movement_easing,
            )
            input_coord_path.new_waypoint(character.input_coord)
            character.event_handler.register_event(
                EventHandler.Event.PATH_ACTIVATED,
                input_coord_path,
                EventHandler.Action.SET_LAYER,
                1,
            )
            character.event_handler.register_event(
                EventHandler.Event.PATH_COMPLETE,
                input_coord_path,
                EventHandler.Action.SET_LAYER,
                0,
            )
            character.motion.activate_path(input_coord_path)
            self.terminal.set_character_visibility(character, is_visible=True)
            gradient_scn = character.animation.new_scene(sync=Scene.SyncMetric.DISTANCE)
            if self.terminal.config.existing_color_handling == "dynamic":
                gradient_scn.add_frame(
                    character.input_symbol,
                    self.config.final_gradient_frames,
                    colors=self.character_final_color_map[character],
                )
            else:
                final_fg_color = self.character_final_color_map[character].fg_color
                assert final_fg_color is not None
                char_gradient = Gradient(final_gradient.spectrum[0], final_fg_color, steps=10)
                gradient_scn.apply_gradient_to_symbols(
                    character.input_symbol,
                    self.config.final_gradient_frames,
                    fg_gradient=char_gradient,
                )
            character.animation.activate_scene(gradient_scn)
            self.active_characters.add(character)
        self._initial_hold_frames = 25

    def __next__(self) -> str:
        """Return the next frame in the animation."""
        if self.pending_chars or self.active_characters:
            if self._initial_hold_frames:
                self._initial_hold_frames -= 1
                return self.frame
            self.update()
            return self.frame
        raise StopIteration

__init__(effect)

Initialize the effect iterator.

Source code in terminaltexteffects/effects/effect_scattered.py 
116
117
118
119
120
121
def __init__(self, effect: Scattered) -> None:
    """Initialize the effect iterator."""
    super().__init__(effect)
    self.pending_chars: list[EffectCharacter] = []
    self.character_final_color_map: dict[EffectCharacter, ColorPair] = {}
    self.build()

__next__()

Return the next frame in the animation.

Source code in terminaltexteffects/effects/effect_scattered.py 
186
187
188
189
190
191
192
193
194
def __next__(self) -> str:
    """Return the next frame in the animation."""
    if self.pending_chars or self.active_characters:
        if self._initial_hold_frames:
            self._initial_hold_frames -= 1
            return self.frame
        self.update()
        return self.frame
    raise StopIteration

build()

Build the effect.

Source code in terminaltexteffects/effects/effect_scattered.py 
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
def build(self) -> None:
    """Build the effect."""
    final_gradient = Gradient(*self.config.final_gradient_stops, steps=self.config.final_gradient_steps)
    final_gradient_mapping = final_gradient.build_coordinate_color_mapping(
        self.terminal.canvas.text_bottom,
        self.terminal.canvas.text_top,
        self.terminal.canvas.text_left,
        self.terminal.canvas.text_right,
        self.config.final_gradient_direction,
    )
    for character in self.terminal.get_characters():
        if self.terminal.config.existing_color_handling == "dynamic":
            self.character_final_color_map[character] = ColorPair(
                fg=character.animation.input_fg_color,
                bg=character.animation.input_bg_color,
            )
        else:
            self.character_final_color_map[character] = ColorPair(
                fg=final_gradient_mapping[character.input_coord],
            )
        if self.terminal.canvas.right < 2 or self.terminal.canvas.top < 2:
            character.motion.set_coordinate(Coord(1, 1))
        else:
            character.motion.set_coordinate(self.terminal.canvas.random_coord())
        input_coord_path = character.motion.new_path(
            speed=self.config.movement_speed,
            ease=self.config.movement_easing,
        )
        input_coord_path.new_waypoint(character.input_coord)
        character.event_handler.register_event(
            EventHandler.Event.PATH_ACTIVATED,
            input_coord_path,
            EventHandler.Action.SET_LAYER,
            1,
        )
        character.event_handler.register_event(
            EventHandler.Event.PATH_COMPLETE,
            input_coord_path,
            EventHandler.Action.SET_LAYER,
            0,
        )
        character.motion.activate_path(input_coord_path)
        self.terminal.set_character_visibility(character, is_visible=True)
        gradient_scn = character.animation.new_scene(sync=Scene.SyncMetric.DISTANCE)
        if self.terminal.config.existing_color_handling == "dynamic":
            gradient_scn.add_frame(
                character.input_symbol,
                self.config.final_gradient_frames,
                colors=self.character_final_color_map[character],
            )
        else:
            final_fg_color = self.character_final_color_map[character].fg_color
            assert final_fg_color is not None
            char_gradient = Gradient(final_gradient.spectrum[0], final_fg_color, steps=10)
            gradient_scn.apply_gradient_to_symbols(
                character.input_symbol,
                self.config.final_gradient_frames,
                fg_gradient=char_gradient,
            )
        character.animation.activate_scene(gradient_scn)
        self.active_characters.add(character)
    self._initial_hold_frames = 25

get_effect_resources()

Get the command, effect class, and configuration class for the effect.

Returns:

Type Description
tuple[str, type[BaseEffect], type[BaseConfig]]

tuple[str, type[BaseEffect], type[BaseConfig]]: The command name, effect class, and configuration class.
Source code in terminaltexteffects/effects/effect_scattered.py 
25
26
27
28
29
30
31
32
def get_effect_resources() -> tuple[str, type[BaseEffect], type[BaseConfig]]:
    """Get the command, effect class, and configuration class for the effect.

    Returns:
        tuple[str, type[BaseEffect], type[BaseConfig]]: The command name, effect class, and configuration class.

    """
    return "scattered", Scattered, ScatteredConfig