Sphere

Sphere(

radius: float = 0.5,

center: VectorLike[float] = (0.0, 0.0, 0.0),

direction: VectorLike[float] = (0.0, 0.0, 1.0),

theta_resolution: int = 30,

phi_resolution: int = 30,

start_theta: float = 0.0,

end_theta: float = 360.0,

start_phi: float = 0.0,

end_phi: float = 180.0,

tessellation: Literal['triangle', 'phi_theta'] = 'triangle',

texture_coordinates: bool = False,

) → PolyData

Create a sphere.

A sphere describes a 2D surface in comparison to pyvista.SolidSphere(), which fills a 3D volume.

PyVista uses a convention where theta represents the azimuthal angle (similar to degrees longitude on the globe) and phi represents the polar angle (similar to degrees latitude on the globe). In contrast to latitude on the globe, here phi is 0 degrees at the North Pole and 180 degrees at the South Pole. phi=0 is on the positive z-axis by default. theta=0 is on the positive x-axis by default.

See Create Sphere Mesh Multiple Ways for examples on creating spheres in other ways.

Parameters:

radiusfloat, default: 0.5

Sphere radius.

centersequence[float], default: (0.0, 0.0, 0.0)

Center coordinate vector in [x, y, z].

directionsequence[float], default: (0.0, 0.0, 1.0)

Direction coordinate vector in [x, y, z] pointing from center to the sphere’s north pole at zero degrees phi.

theta_resolutionint, default: 30

Set the number of points in the azimuthal direction (ranging from start_theta to end_theta).

phi_resolutionint, default: 30

Set the number of points in the polar direction (ranging from start_phi to end_phi).

start_thetafloat, default: 0.0

Starting azimuthal angle in degrees [0, 360].

end_thetafloat, default: 360.0

Ending azimuthal angle in degrees [0, 360].

start_phifloat, default: 0.0

Starting polar angle in degrees [0, 180].

end_phifloat, default: 180.0

Ending polar angle in degrees [0, 180].

tessellation‘triangle’ | ‘phi_theta’, default: ‘triangle’

Configure the tessellation of the sphere.

• 'triangle': tessellate with all TRIANGLE cells.

• 'phi_theta': tessellate with QUAD cells aligned to the phi and theta directions. Cells at the poles are TRIANGLE cells.

Added in version 0.49.

texture_coordinatesbool, default: False

If True, include a 'Texture Coordinates' array as the active texture coordinates. Enabling this option will also generate a topological seam at theta=0 by duplicating vertices, and the sphere will not be a closed surface.

This option is only supported for complete spheres.

Note

For textures of Earth such as load_globe_texture(), the texture’s seam corresponds to 180 degrees longitude. Accordingly, it is necessary to rotate the sphere 180 degrees along the polar axis, (e.g. using rotate_x()) to ensure correct orientation with the Prime Meridian along the positive x-axis.

In this case, consider using load_planet() instead, which already includes this rotation.

Added in version 0.49.

Returns:

pyvista.PolyData

Sphere mesh.

See also

pyvista.Icosphere

Sphere created from projection of icosahedron.

pyvista.SolidSphere

Sphere that fills 3D space.

Turning the sphere inside out

Example turning a sphere inside-out.

pyvista.examples.planets.load_planet()

Sphere with phi/theta tessellation, texture coordinates, and seam at 180-degrees theta.

Examples

Create a sphere using default parameters.

>>> import pyvista as pv
>>> sphere = pv.Sphere()
>>> sphere.plot(show_edges=True)

Static Scene

Interactive Scene

Create a quarter sphere by setting end_theta.

>>> sphere = pv.Sphere(end_theta=90)
>>> out = sphere.plot(show_edges=True)

Static Scene

Interactive Scene

Create a hemisphere by setting end_phi.

>>> sphere = pv.Sphere(end_phi=90)
>>> out = sphere.plot(show_edges=True)

Static Scene

Interactive Scene

Tessellate along phi and theta directions. The sphere is mostly quads with triangles at the poles.

>>> sphere = pv.Sphere(tessellation='phi_theta')
>>> sorted(sphere.distinct_cell_types)
[<CellType.TRIANGLE: 5>, <CellType.QUAD: 9>]

>>> out = sphere.plot(show_edges=True)

Static Scene

Interactive Scene

Include texture coordinates.

>>> sphere = pv.Sphere(tessellation='phi_theta', texture_coordinates=True)
>>> sphere.active_texture_coordinates[0]
pyvista_ndarray([0., 1.], dtype=float32)