Skip to content

Burn

Demo

Quick Start

burn.py
from terminaltexteffects.effects.effect_burn import Burn

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

Characters are ignited and burn up the screen.

Classes:

Name Description
Burn

Characters are ignited and burn up the screen.
BurnConfig

Configuration for the Burn effect.
BurnIterator

Iterates over the Burn effect. Does not normally need to be called directly.

Burn

Bases: BaseEffect[BurnConfig]

Characters are ignited and burn up the screen.

Attributes:

Name Type Description
effect_config BurnConfig

Configuration for the effect.
terminal_config TerminalConfig

Configuration for the terminal.
Source code in terminaltexteffects/effects/effect_burn.py 
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
class Burn(BaseEffect[BurnConfig]):
    """Characters are ignited and burn up the screen.

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

    """

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

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

BurnConfig dataclass

Bases: ArgsDataClass

Configuration for the Burn effect.

Attributes:

Name Type Description
starting_color Color

Color of the characters before they start to burn.
burn_colors tuple[Color, ...]

Colors transitioned through as the characters burn.
final_gradient_stops tuple[Color, ...]

Tuple of colors for the final color 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_direction Direction

Direction of the final gradient.
Source code in terminaltexteffects/effects/effect_burn.py 
 28
 29
 30
 31
 32
 33
 34
 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
111
@argclass(
    name="burn",
    help="Burns vertically in the canvas.",
    description="burn | Burn the canvas.",
    epilog=(
        "Example: terminaltexteffects burn --starting-color 837373 --burn-colors ffffff fff75d fe650d 8a003c "
        "510100 --final-gradient-stops 00c3ff ffff1c --final-gradient-steps 12"
    ),
)
@dataclass
class BurnConfig(ArgsDataClass):
    """Configuration for the Burn effect.

    Attributes:
        starting_color (Color): Color of the characters before they start to burn.
        burn_colors (tuple[Color, ...]): Colors transitioned through as the characters burn.
        final_gradient_stops (tuple[Color, ...]): Tuple of colors for the final color 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_direction (Gradient.Direction): Direction of the final gradient.

    """

    starting_color: Color = ArgField(
        cmd_name="--starting-color",
        type_parser=argvalidators.ColorArg.type_parser,
        default=Color("837373"),
        metavar=argvalidators.ColorArg.METAVAR,
        help="Color of the characters before they start to burn.",
    )  # type: ignore[assignment]
    "Color : Color of the characters before they start to burn."

    burn_colors: tuple[Color, ...] = ArgField(
        cmd_name=["--burn-colors"],
        type_parser=argvalidators.ColorArg.type_parser,
        default=(Color("ffffff"), Color("fff75d"), Color("fe650d"), Color("8A003C"), Color("510100")),
        nargs="+",
        metavar=argvalidators.ColorArg.METAVAR,
        help="Colors transitioned through as the characters burn.",
    )  # type: ignore[assignment]
    "tuple[Color, ...] : Colors transitioned through as the characters burn."

    final_gradient_stops: tuple[Color, ...] = ArgField(
        cmd_name=["--final-gradient-stops"],
        type_parser=argvalidators.ColorArg.type_parser,
        nargs="+",
        default=(Color("00c3ff"), Color("ffff1c")),
        metavar=argvalidators.ColorArg.METAVAR,
        help="Space separated, unquoted, list of colors for the character gradient (applied across the canvas). "
        "If only one color is provided, the characters will be displayed in that color.",
    )  # type: ignore[assignment]
    (
        "tuple[Color, ...] : Tuple of colors for the final color gradient. If only one color is provided, the "
        "characters will be displayed in that color."
    )

    final_gradient_steps: tuple[int, ...] | int = ArgField(
        cmd_name=["--final-gradient-steps"],
        type_parser=argvalidators.PositiveInt.type_parser,
        nargs="+",
        default=12,
        metavar=argvalidators.PositiveInt.METAVAR,
        help="Space separated, unquoted, list of the number of gradient steps to use. More steps will create a "
        "smoother and longer gradient animation.",
    )  # type: ignore[assignment]
    (
        "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_direction: Gradient.Direction = ArgField(
        cmd_name="--final-gradient-direction",
        type_parser=argvalidators.GradientDirection.type_parser,
        default=Gradient.Direction.VERTICAL,
        metavar=argvalidators.GradientDirection.METAVAR,
        help="Direction of the final gradient.",
    )  # type: ignore[assignment]
    "Gradient.Direction : Direction of the final gradient."

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

burn_colors = ArgField(cmd_name=['--burn-colors'], type_parser=argvalidators.ColorArg.type_parser, default=(Color('ffffff'), Color('fff75d'), Color('fe650d'), Color('8A003C'), Color('510100')), nargs='+', metavar=argvalidators.ColorArg.METAVAR, help='Colors transitioned through as the characters burn.') class-attribute instance-attribute

tuple[Color, ...] : Colors transitioned through as the characters burn.

final_gradient_direction = ArgField(cmd_name='--final-gradient-direction', type_parser=argvalidators.GradientDirection.type_parser, default=Gradient.Direction.VERTICAL, metavar=argvalidators.GradientDirection.METAVAR, help='Direction of the final gradient.') class-attribute instance-attribute

Gradient.Direction : Direction of the final gradient.

final_gradient_steps = ArgField(cmd_name=['--final-gradient-steps'], type_parser=argvalidators.PositiveInt.type_parser, nargs='+', default=12, metavar=argvalidators.PositiveInt.METAVAR, help='Space separated, unquoted, list of the number of gradient steps to use. More steps will create a smoother and longer gradient animation.') 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 = ArgField(cmd_name=['--final-gradient-stops'], type_parser=argvalidators.ColorArg.type_parser, nargs='+', default=(Color('00c3ff'), Color('ffff1c')), metavar=argvalidators.ColorArg.METAVAR, help='Space separated, unquoted, list of colors for the character gradient (applied across the canvas). If only one color is provided, the characters will be displayed in that color.') class-attribute instance-attribute

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

starting_color = ArgField(cmd_name='--starting-color', type_parser=argvalidators.ColorArg.type_parser, default=Color('837373'), metavar=argvalidators.ColorArg.METAVAR, help='Color of the characters before they start to burn.') class-attribute instance-attribute

Color : Color of the characters before they start to burn.

get_effect_class() classmethod

Get the effect class associated with this configuration.

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

BurnIterator

Bases: BaseEffectIterator[BurnConfig]

Iterator for the Burn effect.

Source code in terminaltexteffects/effects/effect_burn.py 
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
195
196
class BurnIterator(BaseEffectIterator[BurnConfig]):
    """Iterator for the Burn effect."""

    def __init__(self, effect: Burn) -> None:
        """Initialize the Burn effect iterator.

        Args:
            effect (Burn): The effect to use for the iterator.

        """
        super().__init__(effect)
        self.pending_chars: list[EffectCharacter] = []
        self.character_final_color_map: dict[EffectCharacter, Color] = {}
        self.build()

    def build(self) -> None:
        """Build the Burn effect."""
        vertical_build_order = [
            "'",
            ".",
            "▖",
            "▙",
            "█",
            "▜",
            "▀",
            "▝",
            ".",
        ]
        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():
            self.character_final_color_map[character] = final_gradient_mapping[character.input_coord]
        fire_gradient = Gradient(*self.config.burn_colors, steps=10)
        groups = dict(
            enumerate(
                self.terminal.get_characters_grouped(grouping=self.terminal.CharacterGroup.COLUMN_LEFT_TO_RIGHT),
            ),
        )

        def groups_remaining(rows: dict[int, list[EffectCharacter]]) -> bool:
            """Check if there are any groups remaining."""
            return any(row for row in rows.values())

        while groups_remaining(groups):
            keys = [key for key in groups if groups[key]]
            next_char = groups[random.choice(keys)].pop(0)
            self.terminal.set_character_visibility(next_char, is_visible=True)
            next_char.animation.set_appearance(
                next_char.input_symbol,
                colors=ColorPair(fg=self.config.starting_color),
            )
            burn_scn = next_char.animation.new_scene(scene_id="burn")
            burn_scn.apply_gradient_to_symbols(vertical_build_order, 12, fg_gradient=fire_gradient)
            final_color_scn = next_char.animation.new_scene()
            for color in Gradient(fire_gradient.spectrum[-1], self.character_final_color_map[next_char], steps=8):
                final_color_scn.add_frame(next_char.input_symbol, 4, colors=ColorPair(fg=color))
            next_char.event_handler.register_event(
                EventHandler.Event.SCENE_COMPLETE,
                burn_scn,
                EventHandler.Action.ACTIVATE_SCENE,
                final_color_scn,
            )

            self.pending_chars.append(next_char)

    def __next__(self) -> str:
        """Return the next frame in the animation."""
        if self.pending_chars or self.active_characters:
            for _ in range(random.randint(2, 4)):
                if self.pending_chars:
                    next_char = self.pending_chars.pop(0)
                    next_char.animation.activate_scene(next_char.animation.query_scene("burn"))
                    self.active_characters.add(next_char)

            self.update()
            return self.frame
        raise StopIteration

__init__(effect)

Initialize the Burn effect iterator.

Parameters:

Name Type Description Default
effect Burn

The effect to use for the iterator.

 required
Source code in terminaltexteffects/effects/effect_burn.py 
117
118
119
120
121
122
123
124
125
126
127
def __init__(self, effect: Burn) -> None:
    """Initialize the Burn effect iterator.

    Args:
        effect (Burn): The effect to use for the iterator.

    """
    super().__init__(effect)
    self.pending_chars: list[EffectCharacter] = []
    self.character_final_color_map: dict[EffectCharacter, Color] = {}
    self.build()

__next__()

Return the next frame in the animation.

Source code in terminaltexteffects/effects/effect_burn.py 
185
186
187
188
189
190
191
192
193
194
195
196
def __next__(self) -> str:
    """Return the next frame in the animation."""
    if self.pending_chars or self.active_characters:
        for _ in range(random.randint(2, 4)):
            if self.pending_chars:
                next_char = self.pending_chars.pop(0)
                next_char.animation.activate_scene(next_char.animation.query_scene("burn"))
                self.active_characters.add(next_char)

        self.update()
        return self.frame
    raise StopIteration

build()

Build the Burn effect.

Source code in terminaltexteffects/effects/effect_burn.py 
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
def build(self) -> None:
    """Build the Burn effect."""
    vertical_build_order = [
        "'",
        ".",
        "▖",
        "▙",
        "█",
        "▜",
        "▀",
        "▝",
        ".",
    ]
    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():
        self.character_final_color_map[character] = final_gradient_mapping[character.input_coord]
    fire_gradient = Gradient(*self.config.burn_colors, steps=10)
    groups = dict(
        enumerate(
            self.terminal.get_characters_grouped(grouping=self.terminal.CharacterGroup.COLUMN_LEFT_TO_RIGHT),
        ),
    )

    def groups_remaining(rows: dict[int, list[EffectCharacter]]) -> bool:
        """Check if there are any groups remaining."""
        return any(row for row in rows.values())

    while groups_remaining(groups):
        keys = [key for key in groups if groups[key]]
        next_char = groups[random.choice(keys)].pop(0)
        self.terminal.set_character_visibility(next_char, is_visible=True)
        next_char.animation.set_appearance(
            next_char.input_symbol,
            colors=ColorPair(fg=self.config.starting_color),
        )
        burn_scn = next_char.animation.new_scene(scene_id="burn")
        burn_scn.apply_gradient_to_symbols(vertical_build_order, 12, fg_gradient=fire_gradient)
        final_color_scn = next_char.animation.new_scene()
        for color in Gradient(fire_gradient.spectrum[-1], self.character_final_color_map[next_char], steps=8):
            final_color_scn.add_frame(next_char.input_symbol, 4, colors=ColorPair(fg=color))
        next_char.event_handler.register_event(
            EventHandler.Event.SCENE_COMPLETE,
            burn_scn,
            EventHandler.Action.ACTIVATE_SCENE,
            final_color_scn,
        )

        self.pending_chars.append(next_char)

get_effect_and_args()

Get the effect class and its configuration class.

Source code in terminaltexteffects/effects/effect_burn.py 
23
24
25
def get_effect_and_args() -> tuple[type[typing.Any], type[ArgsDataClass]]:
    """Get the effect class and its configuration class."""
    return Burn, BurnConfig