A community-maintained Python framework for creating mathematical animations.
Added documentation to :mod:`.three_dimensions` (#2915)
Alex Lembcke59b83d8d1045
diff --git a/manim/mobject/three_d/three_dimensions.py b/manim/mobject/three_d/three_dimensions.pyindex a2ab19e8b..a47095a3e 100644--- a/manim/mobject/three_d/three_dimensions.py+++ b/manim/mobject/three_d/three_dimensions.py@@ -47,16 +47,31 @@ class Surface(VGroup, metaclass=ConvertToOpenGL):Parameters----------- func :- The function that defines the surface.- u_range :+ func+ The function defining the :class:`Surface`.+ u_rangeThe range of the ``u`` variable: ``(u_min, u_max)``.- v_range :+ v_rangeThe range of the ``v`` variable: ``(v_min, v_max)``.- resolution :- The number of samples taken of the surface. A tuple- can be used to define different resolutions for ``u`` and- ``v`` respectively.+ resolution+ The number of samples taken of the :class:`Surface`. A tuple can be+ used to define different resolutions for ``u`` and ``v`` respectively.+ fill_color+ The color of the :class:`Surface`. Ignored if ``checkerboard_colors``+ is set.+ fill_opacity+ The opacity of the :class:`Surface`, from 0 being fully transparent+ to 1 being fully opaque. Defaults to 1.+ checkerboard_colors+ Colors individual faces alternating colors. Overrides ``fill_color``.+ stroke_color+ Color of the stroke surrounding each face of :class:`Surface`.+ stroke_width+ Width of the stroke surrounding each face of :class:`Surface`.+ Defaults to 0.5.+ should_make_jagged+ Changes the anchor mode of the Bézier curves from smooth to jagged.+ Defaults to ``False``.Examples--------@@ -162,6 +177,22 @@ class Surface(VGroup, metaclass=ConvertToOpenGL):self.set_fill_by_checkerboard(*self.checkerboard_colors)def set_fill_by_checkerboard(self, *colors, opacity=None):+ """Sets the fill_color of each face of :class:`Surface` in+ an alternating pattern.++ Parameters+ ----------+ colors+ List of colors for alternating pattern.+ opacity+ The fill_opacity of :class:`Surface`, from 0 being fully transparent+ to 1 being fully opaque.++ Returns+ -------+ :class:`~.Surface`+ The parametric surface with an alternating pattern.+ """n_colors = len(colors)for face in self:c_index = (face.u_index + face.v_index) % n_colors@@ -176,16 +207,19 @@ class Surface(VGroup, metaclass=ConvertToOpenGL):axis: int = 2,**kwargs,):- """Sets the color of each mobject of a parametric surface to a color relative to its axis-value+ """Sets the color of each mobject of a parametric surface to a color+ relative to its axis-value.Parameters----------- axes :- The axes for the parametric surface, which will be used to map axis-values to colors.- colorscale :- A list of colors, ordered from lower axis-values to higher axis-values. If a list of tuples is passed- containing colors paired with numbers, then those numbers will be used as the pivots.- axis :+ axes+ The axes for the parametric surface, which will be used to map+ axis-values to colors.+ colorscale+ A list of colors, ordered from lower axis-values to higher axis-values.+ If a list of tuples is passed containing colors paired with numbers,+ then those numbers will be used as the pivots.+ axisThe chosen axis to use for the color mapping. (0 = x, 1 = y, 2 = z)Returns@@ -282,10 +316,24 @@ class Surface(VGroup, metaclass=ConvertToOpenGL):class Sphere(Surface):- """A mobject representing a three-dimensional sphere.+ """An three-dimensional sphere.++ Parameters+ ----------+ center+ Center of the :class:`Sphere`.+ radius+ The radius of the :class:`Sphere`.+ resolution+ The number of samples taken of the :class:`Sphere`. A tuple can be used+ to define different resolutions for ``u`` and ``v`` respectively.+ u_range+ The range of the ``u`` variable: ``(u_min, u_max)``.+ v_range+ The range of the ``v`` variable: ``(v_min, v_max)``.Examples- ---------+ --------.. manim:: ExampleSphere:save_last_frame:@@ -348,13 +396,16 @@ class Dot3D(Sphere):"""A spherical dot.Parameters- --------+ ----------pointThe location of the dot.radiusThe radius of the dot.color- The color of the :class:`Dot3D`+ The color of the :class:`Dot3D`.+ resolution+ The number of samples taken of the :class:`Dot3D`. A tuple can be+ used to define different resolutions for ``u`` and ``v`` respectively.Examples--------@@ -386,6 +437,35 @@ class Dot3D(Sphere):class Cube(VGroup):+ """A three-dimensional cube.++ Parameters+ ----------+ side_length+ Length of each side of the :class:`Cube`.+ fill_opacity+ The opacity of the :class:`Cube`, from 0 being fully transparent to 1 being+ fully opaque. Defaults to 0.75.+ fill_color+ The color of the :class:`Cube`.+ stroke_width+ The width of the stroke surrounding each face of the :class:`Cube`.++ Examples+ --------++ .. manim:: CubeExample+ :save_last_frame:++ class CubeExample(ThreeDScene):+ def construct(self):+ self.set_camera_orientation(phi=75*DEGREES, theta=-45*DEGREES)++ axes = ThreeDAxes()+ cube = Cube(side_length=3, fill_opacity=0.7, fill_color=BLUE)+ self.add(cube)+ """+def __init__(self,side_length=2,@@ -418,7 +498,13 @@ class Cube(VGroup):class Prism(Cube):- """A cuboid.+ """A right rectangular prism (or rectangular cuboid).+ Defined by the length of each side in ``[x, y, z]`` format.++ Parameters+ ----------+ dimensions+ Dimensions of the :class:`Prism` in ``[x, y, z]`` format.Examples--------@@ -451,24 +537,13 @@ class Cone(Surface):height) The spherical radius, r, is calculated using the pythagoreantheorem.- Examples- --------- .. manim:: ExampleCone- :save_last_frame:-- class ExampleCone(ThreeDScene):- def construct(self):- axes = ThreeDAxes()- cone = Cone(direction=X_AXIS+Y_AXIS+2*Z_AXIS, resolution=8)- self.set_camera_orientation(phi=5*PI/11, theta=PI/9)- self.add(axes, cone)-Parameters- --------+ ----------base_radiusThe base radius from which the cone tapers.height- The height measured from the plane formed by the base_radius to the apex of the cone.+ The height measured from the plane formed by the base_radius to+ the apex of the cone.directionThe direction of the apex.show_base@@ -479,6 +554,18 @@ class Cone(Surface):The radius at the apex.checkerboard_colorsShow checkerboard grid texture on the cone.++ Examples+ --------+ .. manim:: ExampleCone+ :save_last_frame:++ class ExampleCone(ThreeDScene):+ def construct(self):+ axes = ThreeDAxes()+ cone = Cone(direction=X_AXIS+Y_AXIS+2*Z_AXIS, resolution=8)+ self.set_camera_orientation(phi=5*PI/11, theta=PI/9)+ self.add(axes, cone)"""def __init__(@@ -520,8 +607,9 @@ class Cone(Surface):def func(self, u: float, v: float):"""Converts from spherical coordinates to cartesian.+Parameters- ---------+ ----------uThe radius.v@@ -571,30 +659,32 @@ class Cone(Surface):self._current_phi = phidef set_direction(self, direction):+ """Changes the direction of the apex of the :class:`Cone`.++ Parameters+ ----------+ direction : :class:`numpy.array`+ The direction of the apex.+ """self.direction = directionself._rotate_to_direction()def get_direction(self):+ """Returns the current direction of the apex of the :class:`Cone`.++ Returns+ -------+ direction : :class:`numpy.array`+ The direction of the apex.+ """return self.directionclass Cylinder(Surface):"""A cylinder, defined by its height, radius and direction,- Examples- ---------- .. manim:: ExampleCylinder- :save_last_frame:-- class ExampleCylinder(ThreeDScene):- def construct(self):- axes = ThreeDAxes()- cylinder = Cylinder(radius=2, height=3)- self.set_camera_orientation(phi=75 * DEGREES, theta=30 * DEGREES)- self.add(axes, cylinder)-Parameters- ---------+ ----------radiusThe radius of the cylinder.height@@ -605,6 +695,21 @@ class Cylinder(Surface):The height along the height axis (given by direction) to start and end on.show_endsWhether to show the end caps or not.+ resolution+ The number of samples taken of the :class:`Cylinder`. A tuple can be used+ to define different resolutions for ``u`` and ``v`` respectively.++ Examples+ --------+ .. manim:: ExampleCylinder+ :save_last_frame:++ class ExampleCylinder(ThreeDScene):+ def construct(self):+ axes = ThreeDAxes()+ cylinder = Cylinder(radius=2, height=3)+ self.set_camera_orientation(phi=75 * DEGREES, theta=30 * DEGREES)+ self.add(axes, cylinder)"""def __init__(@@ -634,8 +739,9 @@ class Cylinder(Surface):def func(self, u: float, v: float):"""Converts from cylindrical coordinates to cartesian.+Parameters- ---------+ ----------uThe height.v@@ -702,21 +808,45 @@ class Cylinder(Surface):self._current_phi = phidef set_direction(self, direction):+ """Sets the direction of the central axis of the :class:`Cylinder`.++ Parameters+ ----------+ direction+ The direction of the central axis of the :class:`Cylinder`.+ """# if get_norm(direction) is get_norm(self.direction):# passself.direction = directionself._rotate_to_direction()def get_direction(self):- """Returns the direction of the central axis of the cylinder."""+ """Returns the direction of the central axis of the :class:`Cylinder`.++ Returns+ -------+ direction+ The direction of the central axis of the :class:`Cylinder`.+ """return self.directionclass Line3D(Cylinder):"""A cylindrical line, for use in ThreeDScene.+ Parameters+ ----------+ start+ The start point of the line.+ end+ The end point of the line.+ thickness+ The thickness of the line.+ color+ The color of the line.+Examples- ---------+ --------.. manim:: ExampleLine3D:save_last_frame:@@ -726,15 +856,6 @@ class Line3D(Cylinder):line = Line3D(start=np.array([0, 0, 0]), end=np.array([2, 2, 2]))self.set_camera_orientation(phi=75 * DEGREES, theta=30 * DEGREES)self.add(axes, line)-- Parameters- ---------- start- The start position of the line.- end- The end position of the line.- thickness- The thickness of the line."""def __init__(@@ -753,7 +874,15 @@ class Line3D(Cylinder):def set_start_and_end_attrs(self, start, end, **kwargs):"""Sets the start and end points of the line.- If either ``start`` or ``end`` are :class:`Mobjects <.Mobject>`, this gives their centers.+ If either ``start`` or ``end`` are :class:`Mobjects <.Mobject>`,+ this gives their centers.++ Parameters+ ----------+ start+ Starting point or :class:`Mobject`.+ end+ Ending point or :class:`Mobject`."""rough_start = self.pointify(start)rough_end = self.pointify(end)@@ -783,9 +912,23 @@ class Line3D(Cylinder):return np.array(mob_or_point)def get_start(self):+ """Returns the starting point of the :class:`Line3D`.++ Returns+ -------+ start : :class:`numpy.array`+ Starting point of the :class:`Line3D`.+ """return self.startdef get_end(self):+ """Returns the ending point of the :class:`Line3D`.++ Returns+ -------+ end : :class:`numpy.array`+ Ending point of the :class:`Line3D`.+ """return self.end@classmethod@@ -872,8 +1015,23 @@ class Line3D(Cylinder):class Arrow3D(Line3D):"""An arrow made out of a cylindrical line and a conical tip.+ Parameters+ ----------+ start+ The start position of the arrow.+ end+ The end position of the arrow.+ thickness+ The thickness of the arrow.+ height+ The height of the conical tip.+ base_radius+ The base radius of the conical tip.+ color+ The color of the arrow.+Examples- ---------+ --------.. manim:: ExampleArrow3D:save_last_frame:@@ -887,19 +1045,6 @@ class Arrow3D(Line3D):)self.set_camera_orientation(phi=75 * DEGREES, theta=30 * DEGREES)self.add(axes, arrow)-- Parameters- ---------- start- The start position of the arrow.- end- The end position of the arrow.- thickness- The thickness of the arrow.- height- The height of the conical tip.- base_radius- The base radius of the conical tip."""def __init__(@@ -934,8 +1079,22 @@ class Arrow3D(Line3D):class Torus(Surface):"""A torus.+ Parameters+ ----------+ major_radius+ Distance from the center of the tube to the center of the torus.+ minor_radius+ Radius of the tube.+ u_range+ The range of the ``u`` variable: ``(u_min, u_max)``.+ v_range+ The range of the ``v`` variable: ``(v_min, v_max)``.+ resolution+ The number of samples taken of the :class:`Torus`. A tuple can be+ used to define different resolutions for ``u`` and ``v`` respectively.+Examples- ---------+ --------.. manim :: ExampleTorus:save_last_frame:@@ -945,13 +1104,6 @@ class Torus(Surface):torus = Torus()self.set_camera_orientation(phi=75 * DEGREES, theta=30 * DEGREES)self.add(axes, torus)-- Parameters- ---------- major_radius- Distance from the center of the tube to the center of the torus.- minor_radius- Radius of the tube."""def __init__(