manim-extensions 1.0.0__tar.gz

manim_extensions-1.0.0/PKG-INFO

@@ -0,0 +1,586 @@
+Metadata-Version: 2.4
+Name: manim_extensions
+Version: 1.0.0
+Summary: A package for tools and extensions in Manim
+Author-email: Zhu Chongjing <zhuchongjing_pypi@163.com>
+License: MIT
+Project-URL: Homepage, https://github.com/zhuchongjing/manim_extensions
+Project-URL: Issues, https://github.com/zhuchongjing/manim_extensions/issues
+Keywords: manim,animation,math,latex,geometry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: manim
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# manim_extensions
+
+[English](#english) | [中文](#中文)
+
+<a name="中文"></a>
+## 中文
+
+manim_extensions 是一个用于 [Manim](https://www.manim.community/) 的扩展工具包，提供了中文公式渲染、几何计算、带标注的图形以及常用动画效果，帮助你更高效地制作数学动画。
+
+### 安装
+
+```bash
+pip install manim_extensions
+```
+
+依赖：`manim`
+
+### 模块概览
+
+| 模块 | 说明 |
+|------|------|
+| `mobjects` | Mobject 类扩展，包含中文公式、带标签圆点、可延长线段等 |
+| `geometry` | 纯几何计算函数，用于求交点、切点等 |
+| `animations` | 动画效果，如可视化绘弧、打字机效果 |
+
+---
+
+### mobjects 模块
+
+#### `ChineseMathTex(*texts, font="SimSun", tex_to_color_map={}, **kwargs)`
+
+支持中文显示的 `MathTex` 子类。可直接在公式中写入中文，无需手动包裹 `\text{}`。
+
+```python
+from manim_extensions import ChineseMathTex
+
+formula = ChineseMathTex(
+    "\\frac{1}{2} + 你好 = x",
+    tex_to_color_map={"你好": RED},
+    font="SimSun"
+)
+```
+
+**参数**
+- `*texts` — LaTeX 文本字符串
+- `font` — 中文字体名称，默认 `"SimSun"`
+- `tex_to_color_map` — 文本到颜色的映射字典，默认 `{}`
+- `**kwargs` — 传递给 `MathTex` 的其他参数
+
+---
+
+#### `LabelDot(dot_label, dot_pos, label_pos=DOWN, buff=0.1, **kwargs)`
+
+在指定位置创建一个圆点，并在其旁边添加 `MathTex` 标签。
+
+```python
+from manim_extensions import LabelDot
+
+dot = LabelDot("A", [1, 2, 0], label_pos=UP, buff=0.2)
+```
+
+**参数**
+- `dot_label` — 标签文本
+- `dot_pos` — 圆点位置
+- `label_pos` — 标签相对圆点的方向，默认 `DOWN`
+- `buff` — 标签与圆点的间距，默认 `0.1`
+- `**kwargs` — 传递给 `VGroup` 的其他参数
+
+---
+
+#### `MathTexLine(formula, direction=UP, buff=0.5, **kwargs)`
+
+创建一条线段，并在其指定方向旁放置 `MathTex` 公式。
+
+```python
+from manim_extensions import MathTexLine
+
+line = MathTexLine(MathTex("y = x"), direction=UP, color=BLUE)
+```
+
+**参数**
+- `formula` — `MathTex` 公式对象
+- `direction` — 公式相对线段的方向，默认 `UP`
+- `buff` — 公式与线段的间距，默认 `0.5`
+- `**kwargs` — 传递给 `Line` 的其他参数
+
+---
+
+#### `MathTexBrace(target, formula, direction=UP, buff=0.5, **kwargs)`
+
+为指定对象创建一个花括号，并在其旁边放置 `MathTex` 公式。
+
+```python
+from manim_extensions import MathTexBrace
+
+line = Line(LEFT, RIGHT)
+brace = MathTexBrace(line, MathTex("\\Delta x"), direction=UP)
+```
+
+**参数**
+- `target` — 要被花括号标注的目标对象
+- `formula` — `MathTex` 公式对象
+- `direction` — 公式与花括号相对目标的方向，默认 `UP`
+- `buff` — 公式与花括号的间距，默认 `0.5`
+- `**kwargs` — 传递给 `Brace` 的其他参数
+
+---
+
+#### `MathTexDoublearrow(formula, direction=UP, buff=0.5, **kwargs)`
+
+创建一个双向箭头，并在其指定方向旁放置 `MathTex` 公式。
+
+```python
+from manim_extensions import MathTexDoublearrow
+
+arrow = MathTexDoublearrow(MathTex("\\Leftrightarrow"), direction=DOWN)
+```
+
+**参数**
+- `formula` — `MathTex` 公式对象
+- `direction` — 公式相对箭头的方向，默认 `UP`
+- `buff` — 公式与箭头的间距，默认 `0.5`
+- `**kwargs` — 传递给 `DoubleArrow` 的其他参数
+
+---
+
+#### `ExtendedLine(line, extend_distance, **kwargs)`
+
+基于一条已有的 `Line`，在其两端按原方向各延长指定距离。
+
+```python
+from manim_extensions import ExtendedLine
+
+original = Line(LEFT, RIGHT)
+extended = ExtendedLine(original, extend_distance=1.0, color=RED)
+```
+
+**参数**
+- `line` — 原始线段
+- `extend_distance` — 两端各延长的距离
+- `**kwargs` — 传递给 `Line` 的其他参数
+
+---
+
+### geometry 模块
+
+#### `CircleInt(circle1, circle2)`
+
+计算两个圆的交点。
+
+```python
+from manim_extensions import CircleInt
+
+c1 = Circle(radius=2).shift(LEFT)
+c2 = Circle(radius=2).shift(RIGHT)
+result = CircleInt(c1, c2)  # ([x1, y1, 0], [x2, y2, 0]) 或 None
+```
+
+**返回**
+- 若相交，返回两个交点坐标的元组 `([x, y, 0], [x, y, 0])`
+- 若不相交，返回 `None`
+
+---
+
+#### `LineCircleInt(line, circle)`
+
+计算线段与圆的交点，仅返回落在线段参数范围 `[0, 1]` 内的交点。
+
+```python
+from manim_extensions import LineCircleInt
+
+line = Line(LEFT * 3, RIGHT * 3)
+circle = Circle(radius=1)
+result = LineCircleInt(line, circle)
+```
+
+**返回**
+- 两个交点、一个交点，或 `None`
+
+---
+
+#### `LineInt(line1, line2)`
+
+在二维平面上计算两条无限延长线段的交点（不限制在线段端点范围内）。
+
+```python
+from manim_extensions import LineInt
+
+l1 = Line(LEFT, RIGHT)
+l2 = Line(DOWN, UP)
+result = LineInt(l1, l2)  # [0.0, 0.0, 0] 或 None
+```
+
+**返回**
+- 交点坐标 `[x, y, 0]`，或平行时返回 `None`
+
+---
+
+#### `LineArcInt(line, arc)`
+
+计算线段与圆弧的交点，会检查交点是否真正落在圆弧的角度范围内。
+
+```python
+from manim_extensions import LineArcInt
+
+line = Line(LEFT, RIGHT)
+arc = Arc(start_angle=0, angle=PI, radius=1)
+result = LineArcInt(line, arc)
+```
+
+**返回**
+- 两个交点、一个交点，或 `None`
+
+---
+
+#### `TangentPoint(p1, p2, line_start, line_end)`
+
+计算以 `p1` 和 `p2` 为圆上点、且与线段相切的切点坐标。
+
+```python
+from manim_extensions import TangentPoint
+
+p = TangentPoint(
+    [1, 0, 0], [-1, 0, 0],
+    line_start=[0, -2, 0], line_end=[0, 2, 0]
+)
+```
+
+**参数**
+- `p1`, `p2` — 圆上的两个点，格式 `(x, y)` 或 `(x, y, z)`
+- `line_start`, `line_end` — 线段的起点和终点
+
+**返回**
+- 切点坐标 `np.ndarray`，若无法计算则返回 `None`
+
+---
+
+### animations 模块
+
+#### `VisDrawArc(scene, arc, axis=OUT, run_time=1)`
+
+可视化绘制圆弧的动画，会同时显示一个沿圆弧移动的点及半径虚线。**直接调用即可，无需放入 `self.play()` 中。**
+
+```python
+from manim_extensions import VisDrawArc
+
+class MyScene(Scene):
+    def construct(self):
+        arc = Arc(start_angle=0, angle=PI, radius=2)
+        VisDrawArc(self, arc, axis=OUT, run_time=2)
+```
+
+**参数**
+- `scene` — Manim 场景对象
+- `arc` — 要绘制的 `Arc`
+- `axis` — 旋转方向，`OUT` 为逆时针，`IN` 为顺时针，默认 `OUT`
+- `run_time` — 动画时长（秒），默认 `1`
+
+---
+
+#### `TypeWriter(mobject, interval=2, **kwargs)`
+
+打字机效果动画，逐个字符显示 `Text` 对象的内容。自动根据字符数量与间隔计算动画总时长。
+
+```python
+from manim_extensions import TypeWriter
+
+class MyScene(Scene):
+    def construct(self):
+        text = Text("Hello World")
+        self.play(TypeWriter(text, interval=0.1))
+```
+
+**参数**
+- `mobject` — `Text` 对象
+- `interval` — 字符间显示间隔（秒），默认 `2`
+- `**kwargs` — 传递给 `Animation` 的其他参数
+
+---
+
+<a name="english"></a>
+## English
+
+manim_extensions is an extension toolkit for [Manim](https://www.manim.community/), providing Chinese formula rendering, geometric calculations, annotated graphics, and common animation effects to help you create mathematical animations more efficiently.
+
+### Installation
+
+```bash
+pip install manim_extensions
+```
+
+Dependency: `manim`
+
+### Module Overview
+
+| Module | Description |
+|--------|-------------|
+| `mobjects` | Mobject class extensions, including Chinese formulas, labeled dots, extendable lines, etc. |
+| `geometry` | Pure geometric calculation functions for finding intersections, tangent points, etc. |
+| `animations` | Animation effects, such as visualized arc drawing and typewriter effects |
+
+---
+
+### mobjects Module
+
+#### `ChineseMathTex(*texts, font="SimSun", tex_to_color_map={}, **kwargs)`
+
+A `MathTex` subclass that supports Chinese characters. You can write Chinese directly in the formula without manually wrapping it in `\text{}`.
+
+```python
+from manim_extensions import ChineseMathTex
+
+formula = ChineseMathTex(
+    "\\frac{1}{2} + 你好 = x",
+    tex_to_color_map={"你好": RED},
+    font="SimSun"
+)
+```
+
+**Parameters**
+- `*texts` — LaTeX text strings
+- `font` — Chinese font name, default `"SimSun"`
+- `tex_to_color_map` — Dictionary mapping text to colors, default `{}`
+- `**kwargs` — Other arguments passed to `MathTex`
+
+---
+
+#### `LabelDot(dot_label, dot_pos, label_pos=DOWN, buff=0.1, **kwargs)`
+
+Creates a dot at the specified position and adds a `MathTex` label next to it.
+
+```python
+from manim_extensions import LabelDot
+
+dot = LabelDot("A", [1, 2, 0], label_pos=UP, buff=0.2)
+```
+
+**Parameters**
+- `dot_label` — Label text
+- `dot_pos` — Dot position
+- `label_pos` — Direction of the label relative to the dot, default `DOWN`
+- `buff` — Spacing between label and dot, default `0.1`
+- `**kwargs` — Other arguments passed to `VGroup`
+
+---
+
+#### `MathTexLine(formula, direction=UP, buff=0.5, **kwargs)`
+
+Creates a line segment and places a `MathTex` formula next to it in the specified direction.
+
+```python
+from manim_extensions import MathTexLine
+
+line = MathTexLine(MathTex("y = x"), direction=UP, color=BLUE)
+```
+
+**Parameters**
+- `formula` — `MathTex` formula object
+- `direction` — Direction of the formula relative to the line, default `UP`
+- `buff` — Spacing between formula and line, default `0.5`
+- `**kwargs` — Other arguments passed to `Line`
+
+---
+
+#### `MathTexBrace(target, formula, direction=UP, buff=0.5, **kwargs)`
+
+Creates a brace for a target object and places a `MathTex` formula next to it.
+
+```python
+from manim_extensions import MathTexBrace
+
+line = Line(LEFT, RIGHT)
+brace = MathTexBrace(line, MathTex("\\Delta x"), direction=UP)
+```
+
+**Parameters**
+- `target` — The object to be braced
+- `formula` — `MathTex` formula object
+- `direction` — Direction of the brace relative to the target, default `UP`
+- `buff` — Spacing between formula and brace, default `0.5`
+- `**kwargs` — Other arguments passed to `Brace`
+
+---
+
+#### `MathTexDoublearrow(formula, direction=UP, buff=0.5, **kwargs)`
+
+Creates a double arrow and places a `MathTex` formula next to it in the specified direction.
+
+```python
+from manim_extensions import MathTexDoublearrow
+
+arrow = MathTexDoublearrow(MathTex("\\Leftrightarrow"), direction=DOWN)
+```
+
+**Parameters**
+- `formula` — `MathTex` formula object
+- `direction` — Direction of the formula relative to the arrow, default `UP`
+- `buff` — Spacing between formula and arrow, default `0.5`
+- `**kwargs` — Other arguments passed to `DoubleArrow`
+
+---
+
+#### `ExtendedLine(line, extend_distance, **kwargs)`
+
+Extends an existing `Line` by a specified distance at both ends along its original direction.
+
+```python
+from manim_extensions import ExtendedLine
+
+original = Line(LEFT, RIGHT)
+extended = ExtendedLine(original, extend_distance=1.0, color=RED)
+```
+
+**Parameters**
+- `line` — Original line segment
+- `extend_distance` — Distance to extend at each end
+- `**kwargs` — Other arguments passed to `Line`
+
+---
+
+### geometry Module
+
+#### `CircleInt(circle1, circle2)`
+
+Calculates the intersection points of two circles.
+
+```python
+from manim_extensions import CircleInt
+
+c1 = Circle(radius=2).shift(LEFT)
+c2 = Circle(radius=2).shift(RIGHT)
+result = CircleInt(c1, c2)  # ([x1, y1, 0], [x2, y2, 0]) or None
+```
+
+**Returns**
+- A tuple of two intersection points `([x, y, 0], [x, y, 0])` if they intersect
+- `None` if they do not intersect
+
+---
+
+#### `LineCircleInt(line, circle)`
+
+Calculates the intersection points of a line segment and a circle, returning only points within the segment parameter range `[0, 1]`.
+
+```python
+from manim_extensions import LineCircleInt
+
+line = Line(LEFT * 3, RIGHT * 3)
+circle = Circle(radius=1)
+result = LineCircleInt(line, circle)
+```
+
+**Returns**
+- Two intersection points, one intersection point, or `None`
+
+---
+
+#### `LineInt(line1, line2)`
+
+Calculates the intersection point of two infinitely extended line segments in 2D (not restricted to the segment endpoints).
+
+```python
+from manim_extensions import LineInt
+
+l1 = Line(LEFT, RIGHT)
+l2 = Line(DOWN, UP)
+result = LineInt(l1, l2)  # [0.0, 0.0, 0] or None
+```
+
+**Returns**
+- Intersection point `[x, y, 0]`, or `None` if parallel
+
+---
+
+#### `LineArcInt(line, arc)`
+
+Calculates the intersection points of a line segment and an arc, checking whether the points truly lie within the arc's angle range.
+
+```python
+from manim_extensions import LineArcInt
+
+line = Line(LEFT, RIGHT)
+arc = Arc(start_angle=0, angle=PI, radius=1)
+result = LineArcInt(line, arc)
+```
+
+**Returns**
+- Two intersection points, one intersection point, or `None`
+
+---
+
+#### `TangentPoint(p1, p2, line_start, line_end)`
+
+Calculates the tangent point of a circle (passing through `p1` and `p2`) and a line segment.
+
+```python
+from manim_extensions import TangentPoint
+
+p = TangentPoint(
+    [1, 0, 0], [-1, 0, 0],
+    line_start=[0, -2, 0], line_end=[0, 2, 0]
+)
+```
+
+**Parameters**
+- `p1`, `p2` — Two points on the circle, in the format `(x, y)` or `(x, y, z)`
+- `line_start`, `line_end` — Start and end points of the line segment
+
+**Returns**
+- Tangent point coordinates as `np.ndarray`, or `None` if calculation fails
+
+---
+
+### animations Module
+
+#### `VisDrawArc(scene, arc, axis=OUT, run_time=1)`
+
+Visualized arc drawing animation, showing a moving dot and a dashed radius line. **Call it directly; no need to wrap it in `self.play()`.**
+
+```python
+from manim_extensions import VisDrawArc
+
+class MyScene(Scene):
+    def construct(self):
+        arc = Arc(start_angle=0, angle=PI, radius=2)
+        VisDrawArc(self, arc, axis=OUT, run_time=2)
+```
+
+**Parameters**
+- `scene` — Manim scene object
+- `arc` — The `Arc` to draw
+- `axis` — Rotation direction, `OUT` for counterclockwise and `IN` for clockwise, default `OUT`
+- `run_time` — Animation duration in seconds, default `1`
+
+---
+
+#### `TypeWriter(mobject, interval=2, **kwargs)`
+
+Typewriter effect animation that displays `Text` content character by character. Automatically calculates the total animation duration based on character count and interval.
+
+```python
+from manim_extensions import TypeWriter
+
+class MyScene(Scene):
+    def construct(self):
+        text = Text("Hello World")
+        self.play(TypeWriter(text, interval=0.1))
+```
+
+**Parameters**
+- `mobject` — `Text` object
+- `interval` — Display interval between characters in seconds, default `2`
+- `**kwargs` — Other arguments passed to `Animation`
+
+---
+
+## License
+
+MIT License