Coverage for src/manimgx/mobjects/annotations.py: 97%
201 statements
« prev ^ index » next coverage.py v7.16.1, created at 2026-10-26 05:52 +0000
« prev ^ index » next coverage.py v7.16.1, created at 2026-10-26 05:52 +0000
1# SPDX-FileCopyrightText: 2026 Academa, Inc.
2# SPDX-FileCopyrightText: 2024 the Manim Community Developers
3# SPDX-FileCopyrightText: 2018 3Blue1Brown LLC
4# SPDX-License-Identifier: MIT
6"Frames, braces and labels placed relative to existing geometric objects."
8from __future__ import annotations
10__all__ = [
11 "ArcBrace",
12 "BackgroundRectangle",
13 "Brace",
14 "BraceBetweenPoints",
15 "BraceLabel",
16 "BraceText",
17 "Cross",
18 "Label",
19 "LabeledArrow",
20 "LabeledDot",
21 "LabeledLine",
22 "LabeledPolygram",
23 "SurroundingRectangle",
24 "Underline",
25]
27from collections.abc import Callable, Sequence
28from typing import TYPE_CHECKING, ClassVar, Self, Unpack
30import numpy as np
32from manimgx.constants import (
33 DEFAULT_FONT_SIZE,
34 DEFAULT_MOBJECT_TO_MOBJECT_BUFFER,
35 DOWN,
36 LEFT,
37 ORIGIN,
38 RIGHT,
39 SMALL_BUFF,
40 UP,
41)
42from manimgx.drawing.geometry import polylabel
43from manimgx.drawing.paint import (
44 BLACK,
45 PURE_YELLOW,
46 RED,
47 WHITE,
48 Look,
49 ParsableManimColor,
50 Style,
51 _Style,
52)
53from manimgx.mobject import Mobject, Placement, VGroup, VMobject, _family, _family_box
54from manimgx.mobjects.shapes import (
55 Arc,
56 Arced,
57 Arrow,
58 Dot,
59 Line,
60 LineOptions,
61 Polygram,
62 RoundedRectangle,
63 Tipped,
64)
65from manimgx.mobjects.svg import VMobjectFromSVGPath
66from manimgx.mobjects.text import (
67 MathTex,
68 MathTexOptions,
69 Tex,
70 Text,
71 TypstOptions,
72)
73from manimgx.settings import config
74from manimgx.typing import ManimTextLabel
76if TYPE_CHECKING:
77 from manimgx.mobject import Mobject
78 from manimgx.typing import (
79 ManimTextLabel,
80 Point3D,
81 Point3DLike,
82 Point3DLike_Array,
83 Vector3D,
84 Vector3DLike,
85 )
88class FrameOptions(_Style, total=False, closed=True):
89 """The keywords of a rectangle made around a mobject, as a
90 [SurroundingRectangle][manimgx.SurroundingRectangle] or a
91 [BackgroundRectangle][manimgx.BackgroundRectangle] is: its margin and its corners,
92 with the style keywords (for the classes that pass them on)."""
94 buff: float | tuple[float, float]
95 """The margin around the mobject, in scene units: one for all sides, or
96 (horizontal, vertical) (default 0.1 around a surrounding rectangle, 0 behind a
97 background rectangle)."""
98 corner_radius: float
99 """The radius of the rectangle's corners, in scene units (default 0: square
100 corners)."""
103class SurroundingRectangle(RoundedRectangle):
104 r"""A rectangle around mobjects: around their bounding box, all of them together,
105 with a margin; bright yellow (`PURE_YELLOW`) unless styled.
107 It is sized and placed when it is made, and does not follow the mobjects
108 afterwards.
110 Args:
111 *mobjects: The mobjects to surround.
112 buff: The margin around them, in scene units: one for all sides, or
113 (horizontal, vertical).
114 corner_radius: The radius of its corners, in scene units: 0 for square
115 corners.
117 Examples:
118 ```python
119 import manimgx as m
122 class SurroundingRectangleExample(m.Scene):
123 def construct(self) -> None:
124 formula = m.MathTex(r"e^{i\pi} + 1 = 0", font_size=96)
125 words = m.Text("Euler's identity").next_to(formula, m.DOWN, buff=1)
126 self.add(formula, words)
127 self.play(
128 m.Create(m.SurroundingRectangle(formula, buff=0.3)),
129 m.Create(
130 m.SurroundingRectangle(words, corner_radius=0.2, color=m.BLUE)
131 ),
132 )
133 ```
134 """
136 defaults: ClassVar[Style] = {"color": PURE_YELLOW}
138 def __init__(
139 self,
140 *mobjects: Mobject,
141 buff: float | tuple[float, float] = SMALL_BUFF,
142 corner_radius: float = 0.0,
143 **kwargs: Unpack[Style],
144 ) -> None:
145 if isinstance(buff, tuple):
146 buff_x = buff[0]
147 buff_y = buff[1]
148 else:
149 buff_x = buff_y = buff
150 box = _family_box(_family(mobjects))
151 if box is None:
152 box = np.zeros((2, 3))
153 super().__init__(
154 width=float(box[1, 0] - box[0, 0]) + 2 * buff_x,
155 height=float(box[1, 1] - box[0, 1]) + 2 * buff_y,
156 corner_radius=corner_radius,
157 **kwargs,
158 )
159 self.buff = buff
160 self.move_to((box[0] + box[1]) / 2)
163class BackgroundRectangle(SurroundingRectangle):
164 """A rectangle behind mobjects, in the background's color and three quarters
165 opaque, so they stand out from what lies behind them; without an outline.
167 Its color is the scene's background color when it is made, unless given. It goes
168 behind the mobjects: add it to the scene before them.
170 Args:
171 *mobjects: The mobjects to go behind.
172 buff: The margin around them, in scene units: one for all sides, or
173 (horizontal, vertical).
174 corner_radius: The radius of its corners, in scene units: 0 for square
175 corners.
177 Examples:
178 ```python
179 import manimgx as m
182 class BackgroundRectangleExample(m.Scene):
183 def construct(self) -> None:
184 bare = m.Text("on the grid", font_size=60).shift(3.5 * m.LEFT)
185 backed = m.Text("on a background", font_size=60).shift(3.2 * m.RIGHT)
186 background = m.BackgroundRectangle(backed, buff=0.2)
187 self.add(m.NumberPlane(), bare, background, backed)
188 ```
189 """
191 defaults: ClassVar[Style] = {
192 "stroke_width": 0,
193 "stroke_opacity": 0.0,
194 "fill_opacity": 0.75,
195 }
197 def __init__(
198 self,
199 *mobjects: Mobject,
200 buff: float | tuple[float, float] = 0,
201 corner_radius: float = 0.0,
202 **kwargs: Unpack[Style],
203 ) -> None:
204 if kwargs.get("color") is None: # not given (None too): the scene's, when made
205 kwargs["color"] = config.background_color
206 super().__init__(*mobjects, buff=buff, corner_radius=corner_radius, **kwargs)
207 self.original_fill_opacity: float = self.fill_opacity
210class Cross(VGroup):
211 """A cross, an X: two lines from corner to corner of a mobject's bounding box, or of
212 a square 2 on a side at the origin; red, 6 wide, unless styled.
214 Args:
215 mobject: The mobject to cross out: the cross is stretched over its bounding
216 box; None for none.
217 stroke_color: The color of its lines.
218 stroke_width: The width of its lines, in hundredths of a scene unit.
219 scale_factor: How much larger than the bounding box (or the square) it is,
220 about its center.
221 color: The color of its lines, in place of `stroke_color`; None to use that.
223 Examples:
224 ```python
225 import manimgx as m
228 class CrossExample(m.Scene):
229 def construct(self) -> None:
230 wrong = m.MathTex("2 + 2 = 5", font_size=96).shift(2 * m.RIGHT)
231 self.add(m.Cross().shift(4 * m.LEFT), wrong)
232 self.play(m.Create(m.Cross(wrong, scale_factor=1.2, color=m.YELLOW)))
233 ```
234 """
236 def __init__(
237 self,
238 mobject: Mobject | None = None,
239 stroke_color: ParsableManimColor = RED,
240 stroke_width: float = 6.0,
241 scale_factor: float = 1.0,
242 color: ParsableManimColor | None = None,
243 **kwargs: Unpack[Look],
244 ) -> None:
245 super().__init__(
246 Line(UP + LEFT, DOWN + RIGHT), Line(UP + RIGHT, DOWN + LEFT), **kwargs
247 )
248 if mobject is not None:
249 self.replace(mobject, stretch=True)
250 self.scale(scale_factor)
251 self.set_stroke(
252 color=stroke_color if color is None else color, width=stroke_width
253 )
256class Underline(Line):
257 """A line under a mobject: as wide as it, `buff` below it; white unless styled.
259 It is sized and placed when it is made, and does not follow the mobject afterwards.
261 Args:
262 mobject: The mobject to underline.
263 buff: The gap between the mobject and the line, in scene units.
265 Examples:
266 ```python
267 import manimgx as m
270 class UnderlineExample(m.Scene):
271 def construct(self) -> None:
272 word = m.Text("important", font_size=120)
273 self.add(word)
274 self.play(m.Create(m.Underline(word, buff=0.2, color=m.YELLOW)))
275 ```
276 """
278 def __init__(
279 self, mobject: Mobject, buff: float = SMALL_BUFF, **kwargs: Unpack[Arced]
280 ) -> None:
281 super().__init__(LEFT, RIGHT, buff=buff, **kwargs)
282 self.match_width(mobject)
283 self.next_to(mobject, DOWN, buff=self.buff)
286class Label(VGroup):
287 """A label on a background, in a frame: text or math, over an opaque rectangle in
288 the background's color, inside a thin white outline.
290 A string is typeset as math, white, at font size 48 (see
291 [MathTex][manimgx.MathTex]); a mobject of text or math is used as it is. Its parts
292 are its submobjects, in drawing order: its
293 [background_rect][manimgx.Label.background_rect], its
294 [rendered_label][manimgx.Label.rendered_label] and its
295 [frame][manimgx.Label.frame].
297 Args:
298 label: The label: a string, typeset as math, or a text or math mobject.
299 label_config: [MathTex
300 keywords][manimgx.MathTex] for a string
301 label, over white at font size 48.
302 box_config: [Surrounding rectangle
303 keywords][manimgx.mobjects.annotations.FrameOptions] for the
304 background, over a margin of 0.05 and an opaque fill (see
305 [BackgroundRectangle][manimgx.BackgroundRectangle]).
306 frame_config: [Surrounding rectangle
307 keywords][manimgx.mobjects.annotations.FrameOptions] for the
308 frame, over white, a margin of 0.05 and an outline 0.5 wide.
309 **kwargs: [Style keywords][manimgx.drawing.paint.Style] of the group itself; its
310 parts keep the styles the configs give them.
312 Examples:
313 ```python
314 import manimgx as m
317 class LabelExample(m.Scene):
318 def construct(self) -> None:
319 plain = m.Label("x^2 + y^2 = r^2")
320 styled = m.Label(
321 m.Text("a label", color=m.YELLOW),
322 box_config={"color": m.BLUE, "buff": 0.2},
323 frame_config={"color": m.YELLOW, "stroke_width": 4, "buff": 0.2},
324 )
325 self.add(m.VGroup(plain, styled).arrange(m.DOWN, buff=1).scale(2))
326 ```
327 """
329 def __init__(
330 self,
331 label: str | ManimTextLabel,
332 label_config: MathTexOptions | None = None,
333 box_config: FrameOptions | None = None,
334 frame_config: FrameOptions | None = None,
335 **kwargs: Unpack[Style],
336 ) -> None:
337 super().__init__(**kwargs)
338 label_style = MathTexOptions(color=WHITE, font_size=DEFAULT_FONT_SIZE) | (
339 label_config or MathTexOptions()
340 )
341 box_style = FrameOptions(buff=0.05, fill_opacity=1, stroke_width=0.5) | (
342 box_config or FrameOptions()
343 )
344 frame_style = FrameOptions(color=WHITE, buff=0.05, stroke_width=0.5) | (
345 frame_config or FrameOptions()
346 )
347 if isinstance(label, str):
348 self.rendered_label: ManimTextLabel = MathTex(label, **label_style)
349 """The label's text or math, a submobject."""
350 else:
351 self.rendered_label = label
352 self.background_rect = BackgroundRectangle(self.rendered_label, **box_style)
353 """The rectangle behind the label, a submobject."""
354 self.frame = SurroundingRectangle(self.rendered_label, **frame_style)
355 """The outline around the label, a submobject."""
356 self.add(self.background_rect, self.rendered_label, self.frame)
359class LabeledLine(Line):
360 """A line with a label on it: a [Label][manimgx.Label] centered at a point
361 `label_position` of the way from the line's start to its end; white unless styled.
363 The label is a submobject, the line's [label][manimgx.LabeledLine.label]. It is
364 placed on the straight way between the ends, even when the line is bent.
366 Args:
367 label: The label: a string, typeset as math, or a text or math mobject.
368 label_position: Where the label goes, as a proportion of the way from the
369 line's start (0) to its end (1).
370 label_config: [MathTex
371 keywords][manimgx.MathTex] for a string
372 label (see [Label][manimgx.Label]).
373 box_config: [Surrounding rectangle
374 keywords][manimgx.mobjects.annotations.FrameOptions] for the
375 label's background.
376 frame_config: [Surrounding rectangle
377 keywords][manimgx.mobjects.annotations.FrameOptions] for the
378 label's frame.
379 start: Where the line starts: a point, or a mobject (see [Line][manimgx.Line]).
380 end: Where it ends: a point, or a mobject.
382 Examples:
383 ```python
384 import manimgx as m
387 class LabeledLineExample(m.Scene):
388 def construct(self) -> None:
389 a, b, c = [-4, -2, 0], [4, -2, 0], [4, 2.5, 0]
390 sides = m.VGroup(
391 m.LabeledLine("8", start=a, end=b, color=m.BLUE),
392 m.LabeledLine("4.5", start=b, end=c, color=m.GREEN),
393 m.LabeledLine("c", start=c, end=a, label_position=0.4),
394 )
395 self.add(sides)
396 ```
397 """
399 def __init__(
400 self,
401 label: str | ManimTextLabel,
402 label_position: float = 0.5,
403 label_config: MathTexOptions | None = None,
404 box_config: FrameOptions | None = None,
405 frame_config: FrameOptions | None = None,
406 *,
407 start: Point3DLike | Mobject = LEFT,
408 end: Point3DLike | Mobject = RIGHT,
409 **kwargs: Unpack[LineOptions],
410 ) -> None:
411 super().__init__(start, end, **kwargs)
412 self.label = Label(
413 label=label,
414 label_config=label_config,
415 box_config=box_config,
416 frame_config=frame_config,
417 )
418 """The label, a submobject."""
419 line_start, line_end = self.get_start_and_end()
420 self.label.move_to(line_start + (line_end - line_start) * label_position)
421 self.add(self.label)
424class LabeledArrow(LabeledLine, Arrow):
425 """An arrow with a label on it: a [LabeledLine][manimgx.LabeledLine] that is an
426 [Arrow][manimgx.Arrow], stopping 0.25 short of its ends unless given another
427 `buff`; white unless styled.
429 Args:
430 label: The label: a string, typeset as math, or a text or math mobject.
431 label_position: Where the label goes, as a proportion of the way from the
432 arrow's start (0) to its tip's point (1).
433 label_config: [MathTex
434 keywords][manimgx.MathTex] for a string
435 label (see [Label][manimgx.Label]).
436 box_config: [Surrounding rectangle
437 keywords][manimgx.mobjects.annotations.FrameOptions] for the
438 label's background.
439 frame_config: [Surrounding rectangle
440 keywords][manimgx.mobjects.annotations.FrameOptions] for the
441 label's frame.
442 start: Where the arrow starts: a point, or a mobject (see [Line][manimgx.Line]).
443 end: Where it points to: a point, or a mobject.
444 **kwargs: [Line keywords][manimgx.Line].
446 Examples:
447 ```python
448 import manimgx as m
451 class LabeledArrowExample(m.Scene):
452 def construct(self) -> None:
453 arrows = m.VGroup(
454 m.LabeledArrow("F", start=4 * m.LEFT, end=4 * m.RIGHT),
455 m.LabeledArrow(
456 "0.5",
457 label_position=0.3,
458 start=3 * m.LEFT + m.DOWN,
459 end=3 * m.RIGHT + 2 * m.UP,
460 color=m.YELLOW,
461 ),
462 ).arrange(m.DOWN, buff=1)
463 self.add(arrows)
464 ```
465 """
468class LabeledPolygram(Polygram):
469 """A polygram with a label inside it, at its pole of inaccessibility: the point
470 inside it farthest from its edges, found to within `precision`; blue unless styled.
472 The first group of vertices is its outline, and the others are holes the label is
473 kept out of. The label is a submobject, [label][manimgx.LabeledPolygram.label];
474 `pole` is where it is, and `radius` how far that is from the nearest edge.
476 Args:
477 *vertex_groups: The groups of vertices, each a closed path (see
478 [Polygram][manimgx.Polygram]): the outline first, then its holes.
479 label: The label: a string, typeset as math, or a text or math mobject.
480 precision: Allowed error in the largest distance from the polygon's edges,
481 in scene units. Several label positions can meet this radius tolerance.
482 label_config: [MathTex
483 keywords][manimgx.MathTex] for a string
484 label (see [Label][manimgx.Label]).
485 box_config: [Surrounding rectangle
486 keywords][manimgx.mobjects.annotations.FrameOptions] for the
487 label's background.
488 frame_config: [Surrounding rectangle
489 keywords][manimgx.mobjects.annotations.FrameOptions] for the
490 label's frame.
492 Examples:
493 ```python
494 import manimgx as m
497 class LabeledPolygramExample(m.Scene):
498 def construct(self) -> None:
499 outline = [[-6, -3, 0], [5, -3, 0], [6, 3, 0], [0, 0.5, 0], [-5, 3, 0]]
500 hole = [[0, -2, 0], [0, -0.5, 0], [4, -0.5, 0], [4, -2, 0]]
501 shape = m.LabeledPolygram(outline, hole, label="P", fill_opacity=0.3)
502 reach = m.Circle(shape.radius, color=m.YELLOW).move_to(shape.pole)
503 self.add(shape, reach)
504 ```
505 """
507 def __init__(
508 self,
509 *vertex_groups: Point3DLike_Array,
510 label: str | ManimTextLabel,
511 precision: float = 0.01,
512 label_config: MathTexOptions | None = None,
513 box_config: FrameOptions | None = None,
514 frame_config: FrameOptions | None = None,
515 **kwargs: Unpack[Style],
516 ) -> None:
517 super().__init__(*vertex_groups, **kwargs)
518 self.label = Label(
519 label=label,
520 label_config=label_config,
521 box_config=box_config,
522 frame_config=frame_config,
523 )
524 """The label, a submobject."""
525 rings = []
526 for group in vertex_groups:
527 ring = np.asarray(group, dtype=float)
528 rings.append(
529 ring
530 if np.array_equal(ring[0], ring[-1])
531 else np.vstack([ring, ring[:1]])
532 )
533 cell = polylabel(rings, precision=precision)
534 self.pole, self.radius = (np.pad(cell.c, (0, 1), "constant"), cell.d)
535 self.label.move_to(self.pole)
536 self.add(self.label)
539class BraceOptions(_Style, total=False, closed=True):
540 """A [brace][manimgx.Brace]'s keywords but its direction, for the classes that pass
541 them on.
543 Beyond these, they take the [style keywords][manimgx.drawing.paint.Style].
544 """
546 buff: float
547 """The gap between the mobject and the brace, in scene units (default 0.2)."""
548 sharpness: float
549 """How sharp the brace's tip and ends are: the higher, the narrower its curls
550 (default 2)."""
553class Brace(VMobjectFromSVGPath):
554 """A curly brace along a side of a mobject, as long as the mobject is wide there:
555 filled white, without an outline, unless styled.
557 The brace lies `buff` beyond the mobject's bounding box, on the side `direction`
558 points to, spanning the mobject across that direction, its tip pointing away; the
559 mobject is left as it is. [get_text][manimgx.Brace.get_text] and
560 [get_tex][manimgx.Brace.get_tex] label its tip.
562 Args:
563 mobject: The mobject to brace.
564 direction: The side the brace is on, as a direction (DOWN: below).
565 buff: The gap between the mobject and the brace, in scene units.
566 sharpness: How sharp the brace's tip and ends are: the higher, the narrower its
567 curls.
569 Examples:
570 ```python
571 import manimgx as m
574 class BraceExample(m.Scene):
575 def construct(self) -> None:
576 square = m.Square(side_length=3, color=m.BLUE, fill_opacity=0.5)
577 self.add(square)
578 self.play(
579 m.GrowFromCenter(m.Brace(square)),
580 m.GrowFromCenter(m.Brace(square, m.RIGHT, color=m.YELLOW)),
581 m.GrowFromCenter(m.Brace(square, m.UP, buff=0.5, color=m.GREEN)),
582 )
583 ```
584 """
586 defaults: ClassVar[Style] = {
587 "stroke_width": 0,
588 "fill_opacity": 1.0,
589 "background_stroke_width": 0,
590 "background_stroke_color": BLACK,
591 }
593 def __init__(
594 self,
595 mobject: Mobject,
596 direction: Vector3DLike = DOWN,
597 buff: float = 0.2,
598 sharpness: float = 2,
599 **kwargs: Unpack[Style],
600 ):
601 path_string_template = (
602 "m0.01216 0c-0.01152 0-0.01216 6.103e-4 -0.01216 0.01311v0.007762c0.06776"
603 " 0.122 0.1799 0.1455 0.2307 0.1455h{0}c0.03046 3.899e-4 0.07964 0.00449"
604 " 0.1246 0.02636 0.0537 0.02695 0.07418 0.05816 0.08648 0.07769 0.001562"
605 " 0.002538 0.004539 0.002563 0.01098 0.002563 0.006444-2e-8"
606 " 0.009421-2.47e-5 0.01098-0.002563 0.0123-0.01953 0.03278-0.05074"
607 " 0.08648-0.07769 0.04491-0.02187 0.09409-0.02597"
608 " 0.1246-0.02636h{0}c0.05077 0 0.1629-0.02346"
609 " 0.2307-0.1455v-0.007762c-1.78e-6 -0.0125-6.365e-4"
610 " -0.01311-0.01216-0.01311-0.006444-3.919e-8 -0.009348 2.448e-5 -0.01091"
611 " 0.002563-0.0123 0.01953-0.03278 0.05074-0.08648 0.07769-0.04491"
612 " 0.02187-0.09416 0.02597-0.1246 0.02636h{1}c-0.04786 0-0.1502"
613 " 0.02094-0.2185"
614 " 0.1256-0.06833-0.1046-0.1706-0.1256-0.2185-0.1256h{1}c-0.03046-3.899e-4"
615 " -0.07972-0.004491-0.1246-0.02636-0.0537-0.02695-0.07418-0.05816-0.08648-0.07769-0.001562-0.002538-0.004467-0.002563-0.01091-0.002563z"
616 )
617 default_min_width = 0.90552
618 self.buff = buff
619 dx, dy = np.asarray(direction, dtype=float)[:2]
620 angle = -np.arctan2(dx, dy) + np.pi
621 mobject.rotate(-angle, about_point=ORIGIN)
622 left = mobject.get_corner(DOWN + LEFT)
623 right = mobject.get_corner(DOWN + RIGHT)
624 target_width = right[0] - left[0]
625 linear_section_length = max(
626 0, (target_width * sharpness - default_min_width) / 2
627 )
628 import svgelements as se
630 path = se.Path(
631 path_string_template.format(linear_section_length, -linear_section_length)
632 )
633 super().__init__(path_obj=path, **kwargs)
634 self.flip(RIGHT)
635 self.stretch_to_fit_width(target_width)
636 self.shift(left - self.get_corner(UP + LEFT) + self.buff * DOWN)
637 for mob in (mobject, self):
638 mob.rotate(angle, about_point=ORIGIN)
640 def put_at_tip(
641 self, mob: Mobject, use_next_to: bool = True, **kwargs: Unpack[Placement]
642 ) -> Self:
643 """Put a mobject at the brace's tip, beyond it.
645 Args:
646 mob: The mobject to put there.
647 use_next_to: Whether it goes next to the tip, on the side the brace points
648 to (its direction rounded to one of the eight compass directions); if
649 not, its center goes from the tip along the brace's direction, by half
650 its width and `buff`.
651 **kwargs: [Placement keywords][manimgx.mobject.Placement]: `buff`, the
652 gap, is 0.25 unless given.
653 """
654 if use_next_to:
655 mob.next_to(self.get_tip(), np.round(self.get_direction()), **kwargs)
656 else:
657 mob.move_to(self.get_tip())
658 buff = kwargs.get("buff", DEFAULT_MOBJECT_TO_MOBJECT_BUFFER)
659 shift_distance = mob.width / 2.0 + buff
660 mob.shift(self.get_direction() * shift_distance)
661 return self
663 def get_text(self, *text: str, **kwargs: Unpack[Placement]) -> Tex:
664 """Make a label of LaTeX text at the brace's tip, as
665 [put_at_tip][manimgx.Brace.put_at_tip] puts it.
667 Args:
668 *text: The label, in LaTeX: a string per part (see [Tex][manimgx.Tex]).
669 **kwargs: [Placement keywords][manimgx.mobject.Placement].
671 Returns:
672 A new [Tex][manimgx.Tex], at the tip; add it to the scene.
674 Examples:
675 ```python
676 import manimgx as m
679 class BraceGetTextExample(m.Scene):
680 def construct(self) -> None:
681 line = m.Line([-3, -1.5, 0], [3, 1.5, 0], color=m.ORANGE)
682 normal = line.copy().rotate(m.PI / 2).get_unit_vector()
683 below, side = m.Brace(line), m.Brace(line, normal)
684 self.add(line, below, side)
685 self.play(
686 m.Write(below.get_text("Horizontal distance")),
687 m.Write(side.get_tex("x - x_1")),
688 )
689 ```
690 """
691 text_mob = Tex(*text)
692 self.put_at_tip(text_mob, **kwargs)
693 return text_mob
695 def get_tex(self, *tex: str, **kwargs: Unpack[Placement]) -> MathTex:
696 """Make a label of LaTeX math at the brace's tip, as
697 [put_at_tip][manimgx.Brace.put_at_tip] puts it.
699 Args:
700 *tex: The label, in LaTeX: a string per part (see
701 [MathTex][manimgx.MathTex]).
702 **kwargs: [Placement keywords][manimgx.mobject.Placement].
704 Returns:
705 A new [MathTex][manimgx.MathTex], at the tip; add it to the scene.
706 """
707 tex_mob = MathTex(*tex)
708 self.put_at_tip(tex_mob, **kwargs)
709 return tex_mob
711 def get_tip(self) -> Point3D:
712 """The brace's tip: the point of its middle cusp.
714 Returns:
715 The point, in scene coordinates.
716 """
717 return self.points[28]
719 def get_direction( # ty: ignore[invalid-method-override] # CE's: a brace's direction is a vector, a path's a winding
720 self,
721 ) -> Vector3D:
722 """The direction the brace points to: from its center to its tip.
724 Returns:
725 A unit vector.
726 """
727 vect = self.get_tip() - self.get_center()
728 return vect / np.linalg.norm(vect)
731type LabelMaker = Callable[
732 ..., ManimTextLabel
733] # strings (MathTex takes several) to a label
736class BraceLabelOptions(_Style, total=False, closed=True):
737 """A [brace label][manimgx.BraceLabel]'s keywords but its label's class, for the
738 classes that choose it.
740 Beyond these, they take the [style keywords][manimgx.drawing.paint.Style].
741 """
743 brace_direction: Vector3DLike
744 """The side the brace is on, as a direction (default DOWN: below)."""
745 font_size: float
746 """The label's font size (default 48)."""
747 buff: float
748 """The gap between the mobject and the brace, in scene units (default 0.2)."""
749 brace_config: BraceOptions | None
750 """[Brace keywords][manimgx.Brace], over `buff` (default
751 None)."""
754class BraceLabel(VMobject):
755 r"""A brace along a side of a mobject, and a label at its tip: math unless another
756 label class is given.
758 Its parts are its [brace][manimgx.BraceLabel.brace] and its
759 [label][manimgx.BraceLabel.label].
761 Args:
762 obj: The mobject to brace.
763 text: The label: a string, or several (as a [MathTex][manimgx.MathTex]'s
764 parts).
765 brace_direction: The side the brace is on, as a direction.
766 label_constructor: The label's class: MathTex, or another text class.
767 font_size: The label's font size.
768 buff: The gap between the mobject and the brace, in scene units.
769 brace_config: [Brace keywords][manimgx.Brace], over
770 `buff`.
771 **kwargs: [Style keywords][manimgx.drawing.paint.Style] of the group itself, and
772 of the label when `text` is several strings.
774 Examples:
775 ```python
776 import manimgx as m
779 class BraceLabelExample(m.Scene):
780 def construct(self) -> None:
781 square = m.Square(side_length=3, color=m.BLUE, fill_opacity=0.5)
782 side = m.BraceLabel(square, "a", font_size=72)
783 diagonal = m.BraceLabel(square, r"a\sqrt{2}", m.UR, font_size=72)
784 self.add(square)
785 self.play(m.Write(side), m.Write(diagonal))
786 ```
787 """
789 def __init__(
790 self,
791 obj: Mobject,
792 text: str | Sequence[str],
793 brace_direction: Vector3DLike = DOWN,
794 label_constructor: LabelMaker = MathTex,
795 font_size: float = DEFAULT_FONT_SIZE,
796 buff: float = 0.2,
797 brace_config: BraceOptions | None = None,
798 **kwargs: Unpack[Style],
799 ):
800 self.label_constructor = label_constructor
801 super().__init__(**kwargs)
802 self.brace_direction = brace_direction
803 self.brace = Brace(
804 obj,
805 brace_direction,
806 **(BraceOptions(buff=buff) | (brace_config or BraceOptions())),
807 )
808 """The brace, a part."""
809 if isinstance(text, str):
810 self.label: ManimTextLabel = self.label_constructor(
811 text, font_size=font_size
812 )
813 """The label, at the brace's tip: a part."""
814 else:
815 self.label = self.label_constructor(*text, font_size=font_size, **kwargs)
816 self.brace.put_at_tip(self.label)
817 self.add(self.brace, self.label)
819 def change_label(self, *text: str, **kwargs: Unpack[TypstOptions]) -> Self:
820 """Replace the label with a new one, made of `text` by the label class, at the
821 brace's tip.
823 Args:
824 *text: The new label's strings.
825 **kwargs: [Typst keywords][manimgx.mobjects.text.TypstOptions]
826 for it (at font size 48 unless given).
827 """
828 self.remove(self.label)
829 self.label = self.label_constructor(*text, **kwargs)
830 self.brace.put_at_tip(self.label)
831 self.add(self.label)
832 return self
835class BraceText(BraceLabel):
836 """A brace along a side of a mobject, and a label of text at its tip: a
837 [BraceLabel][manimgx.BraceLabel] whose label is a [Text][manimgx.Text].
839 Args:
840 obj: The mobject to brace.
841 text: The label's text.
842 label_constructor: The label's class.
844 Examples:
845 ```python
846 import manimgx as m
849 class BraceTextExample(m.Scene):
850 def construct(self) -> None:
851 rectangle = m.Rectangle(width=6, height=3, color=m.BLUE)
852 width = m.BraceText(rectangle, "width")
853 height = m.BraceText(rectangle, "height", brace_direction=m.RIGHT)
854 self.add(rectangle, width, height)
855 ```
856 """
858 def __init__(
859 self,
860 obj: Mobject,
861 text: str | Sequence[str],
862 label_constructor: LabelMaker = Text,
863 **kwargs: Unpack[BraceLabelOptions],
864 ):
865 super().__init__(obj, text, label_constructor=label_constructor, **kwargs)
868class BraceBetweenPoints(Brace):
869 """A brace spanning the segment between two points.
871 Args:
872 point_1: One end.
873 point_2: The other end.
874 direction: The side the brace is on, as a direction; ORIGIN (the default) for
875 the right-hand side going from `point_1` to `point_2` (below, for points
876 from left to right).
878 Examples:
879 ```python
880 import manimgx as m
883 class BraceBetweenPointsExample(m.Scene):
884 def construct(self) -> None:
885 a, b = [-3, -1, 0], [3, 2, 0]
886 self.add(m.Line(a, b), m.Dot(a), m.Dot(b))
887 brace = m.BraceBetweenPoints(a, b, color=m.YELLOW)
888 self.play(m.GrowFromCenter(brace))
889 ```
890 """
892 def __init__(
893 self,
894 point_1: Point3DLike,
895 point_2: Point3DLike,
896 direction: Vector3DLike = ORIGIN,
897 **kwargs: Unpack[BraceOptions],
898 ):
899 if not np.any(np.asarray(direction, dtype=float)): # a side of the line
900 line_vector = np.array(point_2, dtype=float) - np.array(
901 point_1, dtype=float
902 )
903 direction = np.array([line_vector[1], -line_vector[0], 0])
904 super().__init__(Line(point_1, point_2), direction=direction, **kwargs)
907class ArcBrace(Brace):
908 """A brace bent along an arc, outside it or inside.
910 Args:
911 arc: The arc to brace; None for one of radius 1, from -1 to 1 radian.
912 direction: RIGHT for the brace outside the arc, LEFT for inside.
914 Examples:
915 ```python
916 import manimgx as m
919 class ArcBraceExample(m.Scene):
920 def construct(self) -> None:
921 arc = m.Arc(radius=2.5, angle=2 * m.PI / 3, color=m.BLUE)
922 arc.shift(1.5 * m.DOWN)
923 self.add(arc)
924 self.play(
925 m.GrowFromCenter(m.ArcBrace(arc)),
926 m.GrowFromCenter(m.ArcBrace(arc, m.LEFT, color=m.YELLOW)),
927 )
928 ```
929 """
931 def __init__(
932 self,
933 arc: Arc | None = None,
934 direction: Vector3DLike = RIGHT,
935 **kwargs: Unpack[BraceOptions],
936 ):
937 if arc is None:
938 arc = Arc(start_angle=-1, angle=2, radius=1)
939 arc_end_angle = arc.start_angle + arc.angle
940 line = Line(UP * arc.start_angle, UP * arc_end_angle)
941 scale_shift = RIGHT * np.log(arc.radius)
942 if arc.radius >= 1:
943 line.scale(arc.radius, about_point=ORIGIN)
944 super().__init__(line, direction=direction, **kwargs)
945 self.scale(1 / arc.radius, about_point=ORIGIN)
946 else:
947 super().__init__(line, direction=direction, **kwargs)
948 if arc.radius >= 0.3:
949 self.shift(scale_shift)
950 else:
951 self.shift(RIGHT * np.log(0.3))
952 self.apply_complex_function(np.exp)
953 self.shift(arc.get_arc_center())
956class LabeledDot(Dot):
957 r"""A dot with a label in its middle: a disc just large enough for the label unless
958 given a radius; white, without an outline, unless styled.
960 It is made at the origin, and the label, centered on it, is its submobject.
962 Args:
963 label: The label: a string, typeset as math in black (see
964 [MathTex][manimgx.MathTex]), or a mobject, as it is.
965 radius: Its radius, in scene units; None for half the diagonal of the label's
966 bounding box, plus `buff`.
967 buff: The margin between the label's corners and the dot's edge, in scene
968 units, when the radius fits the label.
970 Examples:
971 ```python
972 import manimgx as m
975 class LabeledDotExample(m.Scene):
976 def construct(self) -> None:
977 dots = m.VGroup(
978 m.LabeledDot("A"),
979 m.LabeledDot("42", color=m.BLUE),
980 m.LabeledDot(m.MathTex(r"\alpha"), color=m.PURPLE, radius=0.5),
981 m.LabeledDot(m.Text("hi", color=m.BLACK), color=m.YELLOW),
982 ).arrange(buff=1)
983 self.add(dots.scale(2))
984 ```
985 """
987 def __init__(
988 self,
989 label: str | Mobject,
990 radius: float | None = None,
991 buff: float = SMALL_BUFF,
992 **kwargs: Unpack[Tipped],
993 ) -> None:
994 if isinstance(label, str):
995 from manimgx.mobjects.text import MathTex
997 rendered_label: Mobject = MathTex(label, color=BLACK)
998 else:
999 rendered_label = label
1000 if radius is None:
1001 radius = buff + float(
1002 np.linalg.norm([rendered_label.width, rendered_label.height]) / 2
1003 )
1004 super().__init__(radius=radius, **kwargs)
1005 rendered_label.move_to(self.get_center())
1006 self.add(rendered_label)