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

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 

5 

6"Frames, braces and labels placed relative to existing geometric objects." 

7 

8from __future__ import annotations 

9 

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] 

26 

27from collections.abc import Callable, Sequence 

28from typing import TYPE_CHECKING, ClassVar, Self, Unpack 

29 

30import numpy as np 

31 

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 

75 

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 ) 

86 

87 

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).""" 

93 

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).""" 

101 

102 

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. 

106 

107 It is sized and placed when it is made, and does not follow the mobjects 

108 afterwards. 

109 

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. 

116 

117 Examples: 

118 ```python 

119 import manimgx as m 

120 

121 

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 """ 

135 

136 defaults: ClassVar[Style] = {"color": PURE_YELLOW} 

137 

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) 

161 

162 

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. 

166 

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. 

169 

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. 

176 

177 Examples: 

178 ```python 

179 import manimgx as m 

180 

181 

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 """ 

190 

191 defaults: ClassVar[Style] = { 

192 "stroke_width": 0, 

193 "stroke_opacity": 0.0, 

194 "fill_opacity": 0.75, 

195 } 

196 

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 

208 

209 

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. 

213 

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. 

222 

223 Examples: 

224 ```python 

225 import manimgx as m 

226 

227 

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 """ 

235 

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 ) 

254 

255 

256class Underline(Line): 

257 """A line under a mobject: as wide as it, `buff` below it; white unless styled. 

258 

259 It is sized and placed when it is made, and does not follow the mobject afterwards. 

260 

261 Args: 

262 mobject: The mobject to underline. 

263 buff: The gap between the mobject and the line, in scene units. 

264 

265 Examples: 

266 ```python 

267 import manimgx as m 

268 

269 

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 """ 

277 

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) 

284 

285 

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. 

289 

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]. 

296 

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. 

311 

312 Examples: 

313 ```python 

314 import manimgx as m 

315 

316 

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 """ 

328 

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) 

357 

358 

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. 

362 

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. 

365 

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. 

381 

382 Examples: 

383 ```python 

384 import manimgx as m 

385 

386 

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 """ 

398 

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) 

422 

423 

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. 

428 

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]. 

445 

446 Examples: 

447 ```python 

448 import manimgx as m 

449 

450 

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 """ 

466 

467 

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. 

471 

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. 

475 

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. 

491 

492 Examples: 

493 ```python 

494 import manimgx as m 

495 

496 

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 """ 

506 

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) 

537 

538 

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. 

542 

543 Beyond these, they take the [style keywords][manimgx.drawing.paint.Style]. 

544 """ 

545 

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).""" 

551 

552 

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. 

556 

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. 

561 

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. 

568 

569 Examples: 

570 ```python 

571 import manimgx as m 

572 

573 

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 """ 

585 

586 defaults: ClassVar[Style] = { 

587 "stroke_width": 0, 

588 "fill_opacity": 1.0, 

589 "background_stroke_width": 0, 

590 "background_stroke_color": BLACK, 

591 } 

592 

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 

629 

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) 

639 

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. 

644 

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 

662 

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. 

666 

667 Args: 

668 *text: The label, in LaTeX: a string per part (see [Tex][manimgx.Tex]). 

669 **kwargs: [Placement keywords][manimgx.mobject.Placement]. 

670 

671 Returns: 

672 A new [Tex][manimgx.Tex], at the tip; add it to the scene. 

673 

674 Examples: 

675 ```python 

676 import manimgx as m 

677 

678 

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 

694 

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. 

698 

699 Args: 

700 *tex: The label, in LaTeX: a string per part (see 

701 [MathTex][manimgx.MathTex]). 

702 **kwargs: [Placement keywords][manimgx.mobject.Placement]. 

703 

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 

710 

711 def get_tip(self) -> Point3D: 

712 """The brace's tip: the point of its middle cusp. 

713 

714 Returns: 

715 The point, in scene coordinates. 

716 """ 

717 return self.points[28] 

718 

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. 

723 

724 Returns: 

725 A unit vector. 

726 """ 

727 vect = self.get_tip() - self.get_center() 

728 return vect / np.linalg.norm(vect) 

729 

730 

731type LabelMaker = Callable[ 

732 ..., ManimTextLabel 

733] # strings (MathTex takes several) to a label 

734 

735 

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. 

739 

740 Beyond these, they take the [style keywords][manimgx.drawing.paint.Style]. 

741 """ 

742 

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).""" 

752 

753 

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. 

757 

758 Its parts are its [brace][manimgx.BraceLabel.brace] and its 

759 [label][manimgx.BraceLabel.label]. 

760 

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. 

773 

774 Examples: 

775 ```python 

776 import manimgx as m 

777 

778 

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 """ 

788 

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) 

818 

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. 

822 

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 

833 

834 

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]. 

838 

839 Args: 

840 obj: The mobject to brace. 

841 text: The label's text. 

842 label_constructor: The label's class. 

843 

844 Examples: 

845 ```python 

846 import manimgx as m 

847 

848 

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 """ 

857 

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) 

866 

867 

868class BraceBetweenPoints(Brace): 

869 """A brace spanning the segment between two points. 

870 

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). 

877 

878 Examples: 

879 ```python 

880 import manimgx as m 

881 

882 

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 """ 

891 

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) 

905 

906 

907class ArcBrace(Brace): 

908 """A brace bent along an arc, outside it or inside. 

909 

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. 

913 

914 Examples: 

915 ```python 

916 import manimgx as m 

917 

918 

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 """ 

930 

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()) 

954 

955 

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. 

959 

960 It is made at the origin, and the label, centered on it, is its submobject. 

961 

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. 

969 

970 Examples: 

971 ```python 

972 import manimgx as m 

973 

974 

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 """ 

986 

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 

996 

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)