Skip to content

armgit / manim

Public Imported from GitHub
0

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.py
index 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_range
The range of the ``u`` variable: ``(u_min, u_max)``.
- v_range :
+ v_range
The 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.
+ axis
The 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
- --------
+ ----------
point
The location of the dot.
radius
The 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 pythagorean
theorem.
- 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_radius
The 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.
direction
The direction of the apex.
show_base
@@ -479,6 +554,18 @@ class Cone(Surface):
The radius at the apex.
checkerboard_colors
Show 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
- ---------
+ ----------
u
The radius.
v
@@ -571,30 +659,32 @@ class Cone(Surface):
self._current_phi = phi
def 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 = direction
self._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.direction
class 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
- ---------
+ ----------
radius
The 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_ends
Whether 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
- ---------
+ ----------
u
The height.
v
@@ -702,21 +808,45 @@ class Cylinder(Surface):
self._current_phi = phi
def 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):
# pass
self.direction = direction
self._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.direction
class 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.start
def 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__(