pymations 0.1.0 → 0.2.0

package/pymations.py

@@ -1,9 +1,9 @@
-# GENERATED by circuitry/scripts/sync-pymations-lib.mjs from src/lib/python-canvas/canvas-anim-py.ts (version 15).
+# GENERATED by circuitry/scripts/sync-pymations-lib.mjs from src/lib/python-canvas/canvas-anim-py.ts (version 22).
 # Do not edit here: change it in Circuitry, then run the script.
 # Pymations is MIT licensed; see LICENSE.
 import sys, math, types, inspect
 
-VERSION = "15"
+VERSION = "22"
 _rt = sys.modules["pyctures"]
 H_ANIM = 6
 
@@ -101,6 +101,41 @@ def _reset_once():
         _rt._emit("call", 0, H_ANIM, "reset", [{}])
 
 
+def _outer_opts():
+    """Where a play()/wait() sits in the user's code, for the editor's cursor:
+    {"outer_line": n} when it is called from a helper function (n is the line in
+    construct(), or the script's top level, that led here), and {"line_end": m}
+    when that call spans several lines (Python 3.11+ knows the end). Empty for a
+    one-line call written in construct()."""
+    f = sys._getframe(1)
+    inner = outer = 0
+    outer_frame = None
+    while f is not None:
+        if f.f_code.co_filename == _rt.USER_FILE:
+            inner = inner or f.f_lineno
+            outer, outer_frame = f.f_lineno, f
+            if f.f_code.co_name in ("construct", "<module>"):
+                break
+        f = f.f_back
+    opts = {"outer_line": outer} if outer and outer != inner else {}
+    end = _call_end_line(outer_frame)
+    if end and end > outer:
+        opts["line_end"] = end
+    return opts
+
+
+def _call_end_line(frame):
+    """The last line of the call a frame is making (Python 3.11+), else None."""
+    positions = getattr(getattr(frame, "f_code", None), "co_positions", None)
+    if positions is None or frame.f_lasti < 0:
+        return None
+    try:
+        pos = list(positions())[frame.f_lasti // 2]
+    except (IndexError, ValueError):
+        return None
+    return pos[1]
+
+
 def _call(method, *args):
     if _st().trace is not None:
         raise _Untraceable("it calls %s()" % method)
@@ -1283,6 +1318,10 @@ class Mobject:
     def has_updaters(self):
         return bool(self.__dict__.get("updaters"))
 
+    def apply_function(self, function, **kwargs):
+        """Move every point p to function(p) (np maths on p works)."""
+        return self._op("apply_function", {"function": _trace_formula(function, (_var("p", "v"),), "apply_function")})
+
     def point_from_proportion(self, alpha):
         return Point(["get", self._ref(), "point_from_proportion", _coord(alpha)])
 
@@ -2131,7 +2170,8 @@ class Axes(VMobject):
                 "tips": bool(tips), "axis_config": _style_dict(axis_config),
                 "x_axis_config": _style_dict(x_axis_config), "y_axis_config": _style_dict(y_axis_config)}
         geom.update(self._extra(kwargs))
-        self._make(self._kind, geom, kwargs, n=4 if isinstance(self, NumberPlane) else 2)
+        self._make(self._kind, geom, kwargs,
+                   n=4 if isinstance(self, NumberPlane) else 3 if isinstance(self, ThreeDAxes) else 2)
 
     def _length(self, frame_length, r):
         return float(frame_length)
@@ -2300,10 +2340,57 @@ class Axes(VMobject):
 
 
 class ThreeDAxes(Axes):
-    def __init__(self, x_range=None, y_range=None, z_range=None, x_length=None, y_length=None,
-                 z_length=None, **kwargs):
-        _tell("3d", "Note: 3D is not shown yet, so this scene plays in 2D.")
-        Axes.__init__(self, x_range, y_range, x_length, y_length, **kwargs)
+    """x, y and z axes (parts [0], [1], [2]), seen through the 3D camera."""
+    _kind = "three_d_axes"
+
+    def __init__(self, x_range=(-6, 6, 1), y_range=(-5, 5, 1), z_range=(-4, 4, 1), x_length=None, y_length=None,
+                 z_length=None, z_axis_config=None, z_normal=DOWN, num_axis_pieces=20, light_source=None, depth=None,
+                 gloss=0.5, **kwargs):
+        _w, h = _frame_size()
+        self.z_range = _range3(z_range, (-4, 4, 1))
+        self._z = {"z_range": self.z_range,
+                   "z_length": _num(z_length) if z_length is not None else h - 1.5,
+                   "z_axis_config": _style_dict(z_axis_config), "z_normal": _P(z_normal)}
+        Axes.__init__(self, x_range, y_range, x_length if x_length is not None else h + 2.5,
+                      y_length if y_length is not None else h + 2.5, **kwargs)
+
+    def _extra(self, kwargs):
+        return self._z
+
+    @property
+    def z_axis(self):
+        return self[2]
+
+    def get_axes(self):
+        return VGroup(self[0], self[1], self[2])
+
+    def coords_to_point(self, *coords):
+        if len(coords) == 1:
+            coords = tuple(_unarray(coords[0]))
+        x = _coord(coords[0])
+        y = _coord(coords[1]) if len(coords) > 1 else 0.0
+        z = _coord(coords[2]) if len(coords) > 2 else 0.0
+        return Point(["c2p", self._ref(), x, y, z])
+
+    c2p = coords_to_point
+
+    def get_z_axis_label(self, label, edge=OUT, direction=RIGHT, buff=SMALL_BUFF, rotation=PI / 2,
+                         rotation_axis=RIGHT, **kwargs):
+        m = label if isinstance(label, Mobject) else MathTex(label)
+        m.rotate(rotation, axis=rotation_axis)
+        return m.next_to(self.z_axis.get_corner(edge), direction, buff=buff)
+
+    def get_axis_labels(self, x_label="x", y_label="y", z_label="z"):
+        return VGroup(self.get_x_axis_label(x_label), self.get_y_axis_label(y_label), self.get_z_axis_label(z_label))
+
+    def plot_surface(self, function, u_range=None, v_range=None, colorscale=None, colorscale_axis=2, **kwargs):
+        """z = function(u, v) over the axes, sampled here on a grid."""
+        u = list(u_range) if u_range is not None else self.x_range[:2]
+        v = list(v_range) if v_range is not None else self.y_range[:2]
+        surface = Surface(lambda a, b: [a, b, function(a, b)], u_range=u, v_range=v, _axes=self, **kwargs)
+        if colorscale is not None:
+            surface.set_fill_by_value(self, colorscale, axis=colorscale_axis)
+        return surface
 
 
 class NumberPlane(Axes):
@@ -2393,6 +2480,49 @@ class _Camera:
     def __init__(self):
         self.frame = CameraFrame()
 
+    # The 3D camera's angles (ThreeDScene), as trackers and as attributes.
+    phi_tracker = property(lambda self: _camera_tracker("phi"))
+    theta_tracker = property(lambda self: _camera_tracker("theta"))
+    gamma_tracker = property(lambda self: _camera_tracker("gamma"))
+    zoom_tracker = property(lambda self: _camera_tracker("zoom"))
+    focal_distance_tracker = property(lambda self: _camera_tracker("focal_distance"))
+
+    def get_phi(self):
+        return self.phi_tracker.get_value()
+
+    def get_theta(self):
+        return self.theta_tracker.get_value()
+
+    def get_gamma(self):
+        return self.gamma_tracker.get_value()
+
+    def get_zoom(self):
+        return self.zoom_tracker.get_value()
+
+    def get_focal_distance(self):
+        return self.focal_distance_tracker.get_value()
+
+    def set_phi(self, value):
+        _camera_op("set_camera_orientation", _camera_args(phi=value))
+
+    def set_theta(self, value):
+        _camera_op("set_camera_orientation", _camera_args(theta=value))
+
+    def set_gamma(self, value):
+        _camera_op("set_camera_orientation", _camera_args(gamma=value))
+
+    def set_zoom(self, value):
+        _camera_op("set_camera_orientation", _camera_args(zoom=value))
+
+    def set_focal_distance(self, value):
+        _camera_op("set_camera_orientation", _camera_args(focal_distance=value))
+
+    phi = property(get_phi, set_phi)
+    theta = property(get_theta, set_theta)
+    gamma = property(get_gamma, set_gamma)
+    zoom = property(get_zoom, set_zoom)
+    focal_distance = property(get_focal_distance, set_focal_distance)
+
     @property
     def background_color(self):
         return config.background_color
@@ -2956,10 +3086,13 @@ class MarkupText(Text):
                    _FILLED, n=sum(1 for ch in plain if not ch.isspace()))
 
 
-def _entry(v, element):
-    """A table or matrix entry: a string the engine sets in the element kind, or an existing mobject."""
+def _entry(v, element=None):
+    """A table or matrix cell: a string the engine sets as the element kind, or an
+    object already made, sent as {"id": n, "path": [...]} so it can never be
+    mistaken for a number to write out. The engine places that object in the cell."""
     if isinstance(v, Mobject):
-        return v._embed()
+        t = v._embed()
+        return {"id": t, "path": []} if isinstance(t, int) else t
     return str(v)
 
 
@@ -2994,9 +3127,9 @@ class Table(VGroup):
         self._kids = None
         self._make("table", {
             "table": [[_entry(v, element) for v in r] for r in rows], "element": element,
-            "row_labels": [m._embed() for m in row_labels] if row_labels else None,
-            "col_labels": [m._embed() for m in col_labels] if col_labels else None,
-            "top_left_entry": top_left_entry._embed() if top_left_entry is not None else None,
+            "row_labels": [_entry(m) for m in row_labels] if row_labels else None,
+            "col_labels": [_entry(m) for m in col_labels] if col_labels else None,
+            "top_left_entry": _entry(top_left_entry) if top_left_entry is not None else None,
             "v_buff": _num(v_buff), "h_buff": _num(h_buff), "include_outer_lines": bool(include_outer_lines),
             "include_inner_lines": bool(include_inner_lines),
             "include_background_rectangle": bool(include_background_rectangle),
@@ -3902,11 +4035,16 @@ def _end_section_sound():
         _call("wait_sound", {"src": src, "extra": 0})
 
 
-def _section(name, transition=None, transition_time=None, sound=None):
+def _section(name, transition=None, transition_time=None, sound=None, lines=None):
     _end_section_sound()
+    opts = {}
     if transition and transition != "none":
         tt = transition_time if transition_time is not None else (config.transition_time or 0.5)
-        _call("section", str(name), {"transition": transition, "transition_time": _num(tt)})
+        opts.update(transition=transition, transition_time=_num(tt))
+    if lines:
+        opts["lines"] = list(lines)   # the Scene class's first and last source line
+    if opts:
+        _call("section", str(name), opts)
     else:
         _call("section", str(name))
     if sound is not None:
@@ -3914,6 +4052,566 @@ def _section(name, transition=None, transition_time=None, sound=None):
         _st().section_sound = str(sound)
 
 
+# ---------------------------------------------------------------- 3D
+#
+# 3D is drawn the way Manim draws it: shapes projected through a 3D camera,
+# sorted by depth and shaded, by the engine. Python sends the objects (surfaces
+# sampled here on their grid, like plots) and the camera's moves.
+
+def _res2(resolution, default):
+    r = default if resolution is None else resolution
+    if isinstance(r, (int, float)):
+        return [int(r), int(r)]
+    r = list(r)
+    return [int(r[0]), int(r[1] if len(r) > 1 else r[0])]
+
+
+def _surface_style(kwargs, fill_color=BLUE_D, fill_opacity=1.0, checkerboard_colors=(BLUE_D, BLUE_E),
+                   stroke_color=LIGHT_GREY, stroke_width=0.5, set_color=False):
+    """Manim's Surface look: a checkerboard of two blues, a thin grey grid. As in
+    Manim, color= / fill_color= change the fill under the checkerboard, which stays
+    unless checkerboard_colors=False. set_color: the shape calls Manim's
+    set_color(color) itself (Dot3D, Arrow3D, a coloured Line3D): one colour over
+    fill and stroke, no checkerboard."""
+    checkerboard_colors = kwargs.pop("checkerboard_colors", checkerboard_colors)
+    color = kwargs.pop("color", None)
+    if color is not None:
+        fill_color = color
+        if set_color:
+            checkerboard_colors = False
+            if "stroke_color" not in kwargs:
+                stroke_color = color
+    if "fill_color" in kwargs:
+        fill_color = kwargs.pop("fill_color")
+    cb = [_color(c) for c in checkerboard_colors] if checkerboard_colors else False
+    return {"fill_color": _color(fill_color), "fill_opacity": _num(kwargs.pop("fill_opacity", fill_opacity)),
+            "checkerboard_colors": cb, "stroke_color": _color(kwargs.pop("stroke_color", stroke_color)),
+            "stroke_width": _num(kwargs.pop("stroke_width", stroke_width))}
+
+
+def _grid(func, u_range, v_range, res, to_point):
+    (u0, u1), (v0, v1) = (float(u_range[0]), float(u_range[1])), (float(v_range[0]), float(v_range[1]))
+    ru, rv = res
+    pts = []
+    for i in range(ru + 1):
+        u = u0 + (u1 - u0) * i / ru
+        for j in range(rv + 1):
+            v = v0 + (v1 - v0) * j / rv
+            pts.append(to_point(func, u, v))
+    return pts
+
+
+def _uv_point(func, u, v):
+    p = _unarray(func(u, v))
+    if _is_sym(p):
+        p = list(p)
+        return {"$pt": _tree((p + [0.0, 0.0])[:3])}
+    return list(Vec.of(p))
+
+
+class Surface(VGroup):
+    """func(u, v) → a point, sampled on a resolution grid (u outer, v inner)."""
+
+    def __init__(self, func, u_range=(0, 1), v_range=(0, 1), resolution=32, surface_piece_config=None,
+                 fill_color=BLUE_D, fill_opacity=1.0, checkerboard_colors=(BLUE_D, BLUE_E), stroke_color=LIGHT_GREY,
+                 stroke_width=0.5, should_make_jagged=False, pre_function_handle_to_anchor_scale_factor=0.00001,
+                 _axes=None, **kwargs):
+        self._func = func
+        self.u_range, self.v_range = list(u_range), list(v_range)
+        res = self.resolution = _res2(resolution, 32)
+        style = _surface_style(kwargs, fill_color=fill_color, fill_opacity=fill_opacity,
+                               checkerboard_colors=checkerboard_colors, stroke_color=stroke_color,
+                               stroke_width=stroke_width)
+        flat = _grid(func, u_range, v_range, res, _uv_point)
+        # grid[i][j]: u step i (outer), v step j (inner).
+        grid = [flat[i * (res[1] + 1):(i + 1) * (res[1] + 1)] for i in range(res[0] + 1)]
+        geom = dict(style, grid=grid, resolution=res, u_range=[_num(x) for x in u_range[:2]],
+                    v_range=[_num(x) for x in v_range[:2]])
+        if _axes is not None:
+            geom["axes"] = _axes._ref()
+        self._kids = None
+        self._make("surface", geom, kwargs, {}, n=res[0] * res[1])
+
+    def set_fill_by_checkerboard(self, *colors, opacity=None):
+        return self._op("set_fill_by_checkerboard", {"colors": [_color(c) for c in _flat_colors(colors)],
+                                                     "opacity": None if opacity is None else _num(opacity)})
+
+    def set_fill_by_value(self, axes, colorscale=None, axis=2, **kwargs):
+        scale = colorscale if colorscale is not None else [BLUE, GREEN, YELLOW, RED]
+        enc = [[_color(c[0]), _num(c[1])] if isinstance(c, (list, tuple)) else _color(c) for c in scale]
+        return self._op("set_fill_by_value", {"axes": axes._ref(), "colorscale": enc, "axis": int(axis)})
+
+
+class _Solid(VGroup):
+    """A 3D shape the engine builds from its parameters (Manim's look and defaults)."""
+    _kind = ""
+    _style = None   # None = the Surface checkerboard
+
+    _set_color = False   # True: Manim's class colours itself with set_color(color)
+
+    def _solid(self, geom, kwargs, n, style_defaults=None):
+        self._kids = None
+        style = _surface_style(kwargs, set_color=self._set_color, **(style_defaults or {}))
+        self._make(self._kind, dict(style, **geom), kwargs, {}, n=n)
+
+
+class Sphere(_Solid):
+    _kind = "sphere"
+
+    def __init__(self, center=ORIGIN, radius=1, resolution=None, u_range=(0, TAU), v_range=(0, PI), **kwargs):
+        res = _res2(resolution, (24, 12))
+        self._solid({"center": _P(center), "radius": _num(radius), "resolution": res,
+                     "u_range": [_num(x) for x in u_range], "v_range": [_num(x) for x in v_range]},
+                    kwargs, res[0] * res[1])
+
+
+class Dot3D(Sphere):
+    _kind = "dot3d"
+    _set_color = True
+
+    def __init__(self, point=ORIGIN, radius=DEFAULT_DOT_RADIUS, color=WHITE, resolution=(8, 8), **kwargs):
+        res = _res2(resolution, (8, 8))
+        self._solid({"point": _P(point), "radius": _num(radius), "resolution": res}, dict(kwargs, color=color),
+                    res[0] * res[1])
+
+
+class Torus(_Solid):
+    _kind = "torus"
+
+    def __init__(self, major_radius=3, minor_radius=1, u_range=(0, TAU), v_range=(0, TAU), resolution=None,
+                 **kwargs):
+        res = _res2(resolution, (24, 24))
+        self._solid({"major_radius": _num(major_radius), "minor_radius": _num(minor_radius), "resolution": res,
+                     "u_range": [_num(x) for x in u_range], "v_range": [_num(x) for x in v_range]},
+                    kwargs, res[0] * res[1])
+
+
+class Cone(_Solid):
+    _kind = "cone"
+
+    def __init__(self, base_radius=1, height=1, direction=Z_AXIS, show_base=False, v_range=(0, TAU), u_min=0,
+                 checkerboard_colors=False, resolution=None, **kwargs):
+        res = _res2(resolution, 32)
+        self._solid({"base_radius": _num(base_radius), "height": _num(height), "direction": _P(direction),
+                     "show_base": bool(show_base), "v_range": [_num(x) for x in v_range], "u_min": _num(u_min),
+                     "resolution": res}, kwargs, None, {"checkerboard_colors": checkerboard_colors})
+
+
+class Cylinder(_Solid):
+    _kind = "cylinder"
+
+    def __init__(self, radius=1, height=2, direction=Z_AXIS, v_range=(0, TAU), show_ends=True, resolution=(24, 24),
+                 **kwargs):
+        res = _res2(resolution, (24, 24))
+        self._solid({"radius": _num(radius), "height": _num(height), "direction": _P(direction),
+                     "v_range": [_num(x) for x in v_range], "show_ends": bool(show_ends), "resolution": res},
+                    kwargs, None)
+
+
+def _line_res(resolution):
+    """A Line3D's resolution: a number is the way round; along it, 2 (Manim's)."""
+    if isinstance(resolution, (int, float)):
+        return [2, int(resolution)]
+    return _res2(resolution, (2, 24))
+
+
+class Line3D(Cylinder):
+    _kind = "line3d"
+
+    def __init__(self, start=LEFT, end=RIGHT, thickness=0.02, color=None, resolution=24, **kwargs):
+        if color is not None:
+            kwargs["color"] = color
+            self._set_color = True
+        self.start, self.end = start, end
+        self._solid({"start": _MP(start), "end": _MP(end), "thickness": _num(thickness),
+                     "resolution": _line_res(resolution)}, kwargs, None)
+
+    @classmethod
+    def parallel_to(cls, line, point=ORIGIN, length=5, **kwargs):
+        d = line.get_end() - line.get_start()
+        return cls(point - d * (length / 2.0) / _fn("norm", d), point + d * (length / 2.0) / _fn("norm", d), **kwargs)
+
+    @classmethod
+    def perpendicular_to(cls, line, point=ORIGIN, length=5, **kwargs):
+        raise NotImplementedError("Line3D.perpendicular_to is not available in Pymations yet")
+
+
+class Arrow3D(Line3D):
+    _kind = "arrow3d"
+    _set_color = True
+
+    def __init__(self, start=LEFT, end=RIGHT, thickness=0.02, height=0.3, base_radius=0.08, color=WHITE,
+                 resolution=24, **kwargs):
+        self.start, self.end = start, end
+        self._solid({"start": _MP(start), "end": _MP(end), "thickness": _num(thickness), "height": _num(height),
+                     "base_radius": _num(base_radius), "resolution": _line_res(resolution)},
+                    dict(kwargs, color=color), None)
+
+
+class Cube(_Solid):
+    _kind = "cube"
+
+    def __init__(self, side_length=2, fill_opacity=0.75, fill_color=BLUE, stroke_width=0, **kwargs):
+        self._solid({"side_length": _num(side_length)}, kwargs, 6,
+                    {"fill_color": fill_color, "fill_opacity": fill_opacity, "stroke_width": stroke_width,
+                     "stroke_color": WHITE, "checkerboard_colors": False})
+
+
+class Prism(Cube):
+    _kind = "prism"
+
+    def __init__(self, dimensions=(3, 2, 1), fill_opacity=0.75, fill_color=BLUE, stroke_width=0, **kwargs):
+        self._solid({"dimensions": [_num(x) for x in dimensions]}, kwargs, 6,
+                    {"fill_color": fill_color, "fill_opacity": fill_opacity, "stroke_width": stroke_width,
+                     "stroke_color": WHITE, "checkerboard_colors": False})
+
+
+class Polyhedron(VGroup):
+    """Faces from vertex_coords and faces_list; parts [0] the faces, [1] the vertices and edges."""
+    _kind = "polyhedron"
+
+    def __init__(self, vertex_coords=None, faces_list=None, faces_config=None, graph_config=None, **kwargs):
+        self._kids = None
+        geom = {"faces_config": _style_dict(faces_config), "graph_config": _style_dict(graph_config)}
+        if self._kind == "polyhedron":
+            geom.update(vertex_coords=[_P(v) for v in vertex_coords], faces_list=[[int(i) for i in f]
+                                                                                  for f in faces_list])
+        geom.update(self._params())
+        self._make(self._kind, geom, kwargs, {}, n=2)
+
+    def _params(self):
+        return {}
+
+    @property
+    def faces(self):
+        return self[0]
+
+    @property
+    def graph(self):
+        return self[1]
+
+
+class _Platonic(Polyhedron):
+    def __init__(self, edge_length=1, faces_config=None, graph_config=None, **kwargs):
+        self.edge_length = edge_length
+        Polyhedron.__init__(self, faces_config=faces_config, graph_config=graph_config, **kwargs)
+
+    def _params(self):
+        return {"edge_length": _num(self.edge_length)}
+
+
+class Tetrahedron(_Platonic):
+    _kind = "tetrahedron"
+
+
+class Octahedron(_Platonic):
+    _kind = "octahedron"
+
+
+class Icosahedron(_Platonic):
+    _kind = "icosahedron"
+
+
+class Dodecahedron(_Platonic):
+    _kind = "dodecahedron"
+
+
+# ---------------------------------------------------------------- Boolean shapes
+
+class Union(VMobject):
+    """The outline around all the shapes together."""
+    _kind = "union"
+
+    def __init__(self, *vmobjects, **kwargs):
+        mobs = _flat(vmobjects)
+        if len(mobs) < 2:
+            raise ValueError("%s needs at least 2 shapes" % type(self).__name__)
+        self._make(self._kind, {"mobjects": [m._embed() for m in mobs]}, kwargs, n=0)
+
+
+class Intersection(Union):
+    """Where all the shapes overlap."""
+    _kind = "intersection"
+
+
+class Difference(VMobject):
+    """subject with clip cut away."""
+    _kind = "difference"
+
+    def __init__(self, subject, clip, **kwargs):
+        self._make(self._kind, {"subject": subject._embed(), "clip": clip._embed()}, kwargs, n=0)
+
+
+class Exclusion(Difference):
+    """Where exactly one of the two shapes is."""
+    _kind = "exclusion"
+
+
+# ---------------------------------------------------------------- the 3D camera
+
+_CAMERA_DEFAULTS = {"phi": 0.0, "theta": -90 * DEGREES, "gamma": 0.0, "zoom": 1.0, "focal_distance": 20.0}
+
+
+class _CameraTracker(ValueTracker):
+    """A camera angle as a tracker: animate it, read it in updaters."""
+
+    def __init__(self, param):
+        value = _CAMERA_DEFAULTS[param]
+        self._value = self._initial = value
+        self._make("value_tracker", {"value": value, "camera": param}, {}, {}, n=0)
+
+
+def _camera_tracker(param):
+    st = _st()
+    trackers = st.__dict__.setdefault("camera_trackers", {})
+    t = trackers.get(param)
+    if t is None:
+        # A real object even when first touched inside an updater being traced.
+        prev, st.trace = st.trace, None
+        try:
+            t = trackers[param] = _CameraTracker(param)
+        finally:
+            st.trace = prev
+    return t
+
+
+def _camera_args(phi=None, theta=None, gamma=None, zoom=None, focal_distance=None, frame_center=None):
+    args = {}
+    for k, v in (("phi", phi), ("theta", theta), ("gamma", gamma), ("zoom", zoom),
+                 ("focal_distance", focal_distance)):
+        if v is not None:
+            args[k] = _num(v)
+            t = _st().__dict__.get("camera_trackers", {}).get(k)
+            if t is not None and _real_number(v):
+                t._value = float(v)
+    if frame_center is not None:
+        args["frame_center"] = _MP(frame_center)
+    return args
+
+
+def _camera_op(name, args):
+    _call("op", 0, name, args)
+
+
+class _MoveCamera(Animation):
+    kind = "move_camera"
+
+    def __init__(self, cam_args, **kwargs):
+        self._cam = cam_args
+        Animation.__init__(self, None, **kwargs)
+
+    def _anim(self):
+        return _timing({"kind": self.kind, "target": 0, "args": self._cam}, self._kw)
+
+    def _added(self):
+        return []
+
+
+# ---------------------------------------------------------------- complex maths, as formulas
+#
+# ApplyComplexFunction(lambda z: z ** 2, plane) traces the function on a
+# symbolic z = x + iy: complex arithmetic is expanded here into a real and an
+# imaginary formula, which the engine maps every point with.
+
+def _re_im(v):
+    if isinstance(v, _CExpr):
+        return v.re, v.im
+    if isinstance(v, complex):
+        return v.real, v.imag
+    if isinstance(v, (int, float, Expr)) and not isinstance(v, bool):
+        return v, 0.0
+    tolist = getattr(v, "tolist", None)
+    if tolist is not None:
+        return _re_im(tolist())
+    raise TypeError("expected a complex number, got %r" % (v,))
+
+
+def _is_zero(v):
+    return isinstance(v, (int, float)) and not isinstance(v, bool) and v == 0
+
+
+def _m(a, b):
+    if _is_zero(a) or _is_zero(b):
+        return 0.0
+    return a * b
+
+
+def _a(a, b):
+    if _is_zero(a):
+        return b
+    if _is_zero(b):
+        return a
+    return a + b
+
+
+class _CExpr:
+    """A complex value worked out in the browser: re + i·im, each a formula or a number."""
+    __slots__ = ("re", "im")
+
+    def __array_ufunc__(self, ufunc, method, *inputs, **kwargs):
+        if method != "__call__" or len(inputs) != 1:
+            return NotImplemented
+        names = {"exp": "exp", "log": "log", "sqrt": "sqrt", "sin": "sin", "cos": "cos", "tan": "tan",
+                 "sinh": "sinh", "cosh": "cosh", "absolute": "abs", "conjugate": "conj", "real": "real",
+                 "imag": "imag"}
+        name = names.get(ufunc.__name__)
+        return NotImplemented if name is None else _cfn(name, self)
+
+    def __init__(self, re, im):
+        self.re, self.im = re, im
+
+    @property
+    def real(self):
+        return self.re
+
+    @property
+    def imag(self):
+        return self.im
+
+    def conjugate(self):
+        return _CExpr(self.re, -self.im if not _is_zero(self.im) else 0.0)
+
+    def __add__(self, o):
+        a, b = _re_im(o)
+        return _CExpr(_a(self.re, a), _a(self.im, b))
+
+    __radd__ = __add__
+
+    def __sub__(self, o):
+        a, b = _re_im(o)
+        return _CExpr(_a(self.re, -a), _a(self.im, -b))
+
+    def __rsub__(self, o):
+        return _CExpr(*_re_im(o)) - self
+
+    def __neg__(self):
+        return _CExpr(-self.re, -self.im)
+
+    def __mul__(self, o):
+        a, b = _re_im(o)
+        return _CExpr(_a(_m(self.re, a), -_m(self.im, b) if not _is_zero(_m(self.im, b)) else 0.0),
+                      _a(_m(self.re, b), _m(self.im, a)))
+
+    __rmul__ = __mul__
+
+    def __truediv__(self, o):
+        a, b = _re_im(o)
+        if not isinstance(a, Expr) and not isinstance(b, Expr):
+            d = a * a + b * b
+            return self * _CExpr(a / d, -b / d)
+        d = _a(_m(a, a), _m(b, b))
+        return self * _CExpr(a / d, -b / d)
+
+    def __rtruediv__(self, o):
+        return _CExpr(*_re_im(o)) / self
+
+    def __pow__(self, n):
+        if isinstance(n, int) and not isinstance(n, bool):
+            if n == 0:
+                return _CExpr(1.0, 0.0)
+            out = self
+            for _ in range(abs(n) - 1):
+                out = out * self
+            return 1 / out if n < 0 else out
+        # Any other power, through polar form.
+        r, th = abs(self), _fn("atan2", self.im, self.re)
+        a, b = _re_im(n)
+        if not _is_zero(b):
+            return _cexp(_CExpr(_fn("log", r), th) * _CExpr(a, b))
+        rn = r ** a
+        return _CExpr(rn * _fn("cos", th * a), rn * _fn("sin", th * a))
+
+    def __abs__(self):
+        return _fn("sqrt", _a(_m(self.re, self.re), _m(self.im, self.im)))
+
+    def _no(self, *a):
+        _lazy_error("this complex value")
+
+    __bool__ = __float__ = __complex__ = __int__ = _no
+
+
+def _cexp(z):
+    e = _fn("exp", z.re) if isinstance(z.re, Expr) else math.exp(z.re)
+    return _CExpr(_m(e, _fn("cos", z.im) if isinstance(z.im, Expr) else math.cos(z.im)),
+                  _m(e, _fn("sin", z.im) if isinstance(z.im, Expr) else math.sin(z.im)))
+
+
+def _cfn(name, z):
+    """np.exp(z), np.sin(z) … on a symbolic complex z."""
+    if name == "exp":
+        return _cexp(z)
+    if name == "log":
+        return _CExpr(_fn("log", abs(z)), _fn("atan2", z.im, z.re))
+    if name == "sqrt":
+        return z ** 0.5
+    if name in ("sin", "cos", "sinh", "cosh"):
+        iz = _CExpr(-z.im, z.re) if name in ("sin", "cos") else z
+        e1, e2 = _cexp(iz), _cexp(-iz)
+        if name == "sin":     # (e^{iz} - e^{-iz}) / 2i
+            d = e1 - e2
+            return _CExpr(d.im / 2, -d.re / 2)
+        if name == "cos":
+            return (e1 + e2) * 0.5
+        return (e1 - e2) * 0.5 if name == "sinh" else (e1 + e2) * 0.5
+    if name == "tan":
+        return _cfn("sin", z) / _cfn("cos", z)
+    if name == "abs":
+        return abs(z)
+    if name in ("conj", "conjugate"):
+        return z.conjugate()
+    if name == "real":
+        return z.re
+    if name == "imag":
+        return z.im
+    raise TypeError("np.%s does not work on a complex value in Pymations" % name)
+
+
+def _complex_formula(fn, args, what):
+    tr, result, err = _run_trace(fn, args)
+    if err is None:
+        try:
+            re, im = _re_im(result)
+            return ["v", [_tree(re), _tree(im), 0.0]]
+        except Exception as e:  # noqa: BLE001
+            err = e
+    raise TypeError("%s needs a function the browser can work out with + - * / ** and np.exp, np.sin, np.log … "
+                    "(not cmath.* or an if on z): %s" % (what, err))
+
+
+def _z():
+    return _CExpr(Expr(["var", "x"], "s"), Expr(["var", "y"], "s"))
+
+
+class ApplyComplexFunction(Animation):
+    """Moves every point z (x + iy) to function(z): ApplyComplexFunction(lambda z: z ** 2, plane)."""
+    kind = "apply_complex_function"
+
+    def __init__(self, function, mobject, **kwargs):
+        self._formula = _complex_formula(function, (_z(),), "ApplyComplexFunction")
+        Animation.__init__(self, mobject, **kwargs)
+
+    def _make_args(self, **kwargs):
+        return {"function": self._formula}
+
+
+class ComplexHomotopy(Animation):
+    """function(z, t) for t from 0 to 1 moves every point z: a complex Homotopy."""
+    kind = "complex_homotopy"
+
+    def __init__(self, complex_homotopy, mobject, run_time=3, **kwargs):
+        self._formula = _complex_formula(complex_homotopy, (_z(), _var("t")), "ComplexHomotopy")
+        Animation.__init__(self, mobject, run_time=run_time, **kwargs)
+
+    def _make_args(self, **kwargs):
+        return {"function": self._formula}
+
+
+class PhaseFlow(Animation):
+    def __init__(self, *a, **k):
+        raise NotImplementedError("PhaseFlow is not available in Pymations yet; Homotopy or "
+                                  "ApplyPointwiseFunction can often show the same motion")
+
+
 # ---------------------------------------------------------------- scenes
 
 class Scene:
@@ -4010,14 +4708,18 @@ class Scene:
             d = a._anim()
             d.update(over)
             encoded.append(d)
-        _call("play", encoded, {})
+        _call("play", encoded, _outer_opts())
         for a in anims:
             self._keep(a._added())
         for a in anims:
             self._drop(a._removed())
 
     def wait(self, duration=DEFAULT_WAIT_TIME, stop_condition=None, frozen_frame=None):
-        _call("wait", _num(duration))
+        opts = _outer_opts()
+        if opts:
+            _call("wait", _num(duration), opts)
+        else:
+            _call("wait", _num(duration))
 
     pause = wait
 
@@ -4054,32 +4756,64 @@ class ZoomedScene(MovingCameraScene):
 
 
 class ThreeDScene(Scene):
-    def _flat_note(self):
-        _tell("3d", "Note: 3D is not shown yet, so this scene plays in 2D.")
+    """A scene seen through a 3D camera: shapes projected, depth-sorted and shaded."""
 
-    def set_camera_orientation(self, *a, **k):
-        self._flat_note()
+    def __init__(self, ambient_camera_rotation=None, default_angled_camera_orientation_kwargs=None, **kwargs):
+        Scene.__init__(self, **kwargs)
+        self.default_angled_camera_orientation_kwargs = default_angled_camera_orientation_kwargs or {
+            "phi": 70 * DEGREES, "theta": -135 * DEGREES}
 
-    def move_camera(self, *a, added_anims=(), run_time=None, **k):
-        self._flat_note()
-        if added_anims:
-            self.play(*added_anims, run_time=run_time)
-        else:
-            self.wait(run_time or 1.0)
+    def set_camera_orientation(self, phi=None, theta=None, gamma=None, zoom=None, focal_distance=None,
+                               frame_center=None, **kwargs):
+        _camera_op("set_camera_orientation", _camera_args(phi, theta, gamma, zoom, focal_distance, frame_center))
 
-    def begin_ambient_camera_rotation(self, *a, **k):
-        self._flat_note()
+    def move_camera(self, phi=None, theta=None, gamma=None, zoom=None, focal_distance=None, frame_center=None,
+                    added_anims=(), **kwargs):
+        timing = {k: kwargs.pop(k) for k in ("run_time", "rate_func", "lag_ratio") if k in kwargs}
+        cam = _MoveCamera(_camera_args(phi, theta, gamma, zoom, focal_distance, frame_center))
+        self.play(cam, *list(added_anims), **timing)
 
-    def stop_ambient_camera_rotation(self, *a, **k):
-        pass
+    def begin_ambient_camera_rotation(self, rate=0.02, about="theta"):
+        _call("begin_ambient_camera_rotation", _num(rate), str(about).lower())
+
+    def stop_ambient_camera_rotation(self, about="theta"):
+        _call("stop_ambient_camera_rotation", str(about).lower())
+
+    def begin_3dillusion_camera_rotation(self, rate=1, origin_phi=None, origin_theta=None):
+        _call("begin_3dillusion_camera_rotation", _num(rate), None if origin_phi is None else _num(origin_phi),
+              None if origin_theta is None else _num(origin_theta))
 
-    def set_to_default_angled_camera_orientation(self, *a, **k):
-        self._flat_note()
+    def stop_3dillusion_camera_rotation(self):
+        _call("stop_3dillusion_camera_rotation")
+
+    def set_to_default_angled_camera_orientation(self, **kwargs):
+        self.set_camera_orientation(**dict(self.default_angled_camera_orientation_kwargs, **kwargs))
 
     def add_fixed_in_frame_mobjects(self, *mobjects):
-        return self.add(*mobjects)
+        """Kept flat on the screen (titles, labels): not turned by the camera."""
+        mobs = _flat(mobjects)
+        for m in mobs:
+            m._op("fix_in_frame", {})
+        return self.add(*mobs)
+
+    def remove_fixed_in_frame_mobjects(self, *mobjects):
+        for m in _flat(mobjects):
+            m._op("unfix_from_frame", {})
+
+    def add_fixed_orientation_mobjects(self, *mobjects, use_static_center_func=False, center_func=None):
+        """Placed in 3D but always facing the camera (labels on axes)."""
+        mobs = _flat(mobjects)
+        for m in mobs:
+            m._op("fix_orientation", {})
+        return self.add(*mobs)
+
+    def remove_fixed_orientation_mobjects(self, *mobjects):
+        for m in _flat(mobjects):
+            m._op("unfix_orientation", {})
 
-    add_fixed_orientation_mobjects = add_fixed_in_frame_mobjects
+
+class SpecialThreeDScene(ThreeDScene):
+    pass
 
 
 def _split(group, gone):
@@ -4097,7 +4831,36 @@ def _split(group, gone):
 def _scene_section(scene, first):
     tr = scene.transition if scene.transition is not None else config.transition
     tt = scene.transition_time if scene.transition_time is not None else config.transition_time
-    _section(type(scene).__name__, None if first else tr, tt)
+    _section(type(scene).__name__, None if first else tr, tt, lines=_class_lines(type(scene).__name__))
+
+
+def _class_lines(name):
+    """[first, last] source lines of a top-level class in the user's file, so the
+    editor's cursor in it finds that Scene's section of the timeline."""
+    st = _st()
+    spans = st.__dict__.get("class_spans")
+    if spans is None:
+        spans = {}
+        try:
+            import ast
+            for node in ast.parse(getattr(_rt.S, "source", "") or "").body:
+                if isinstance(node, ast.ClassDef):
+                    first = min([node.lineno] + [d.lineno for d in node.decorator_list])
+                    spans[node.name] = [first, getattr(node, "end_lineno", None) or node.lineno]
+        except SyntaxError:
+            pass
+        st.__dict__["class_spans"] = spans
+    return spans.get(name)
+
+
+def _scene_camera(scene):
+    """After a scene's clear(): a ThreeDScene switches the engine to the 3D camera,
+    a plain Scene after one switches it back."""
+    st = _st()
+    three_d = isinstance(scene, ThreeDScene)
+    if three_d or st.__dict__.get("three_d"):
+        _call("config", {"three_d": three_d})
+        st.__dict__["three_d"] = three_d
 
 
 def _run_scene_sync(scene):
@@ -4105,6 +4868,7 @@ def _run_scene_sync(scene):
     _scene_section(scene, not st.scenes_run)
     st.scenes_run += 1
     scene.clear()
+    _scene_camera(scene)
     for step in (scene.setup, scene.construct, scene.tear_down):
         r = step()
         if hasattr(r, "send"):
@@ -4122,6 +4886,7 @@ async def _run_scenes(classes):
         _scene_section(scene, not st.scenes_run)
         st.scenes_run += 1
         scene.clear()
+        _scene_camera(scene)
         for step in (scene.setup, scene.construct, scene.tear_down):
             r = step()
             if hasattr(r, "send"):
@@ -4215,6 +4980,8 @@ def section(name, sound=None, transition=None, transition_time=None):
 # the stand-in directly, real numpy through Expr.__array_ufunc__.
 def _np_fn(name, py):
     def f(*args):
+        if args and isinstance(args[0], _CExpr):
+            return _cfn(name, args[0])
         if any(_is_sym(a) for a in args):
             return _fn(name, *[_tree_arg(a) for a in args])
         if any(isinstance(a, (list, tuple)) for a in args):