Base Classes for 3D Graphics Objects and Plotting¶

AUTHORS:

Robert Bradshaw (2007-02): initial version
Robert Bradshaw (2007-08): Cythonization, much optimization
William Stein (2008)
Paul Masson (2016): Three.js support
Joshua Campbell (2020): Three.js animation support

Todo

finish integrating tachyon – good default lights, camera

class sage.plot.plot3d.base.BoundingSphere(cen, r)¶

Bases: sage.structure.sage_object.SageObject

A bounding sphere is like a bounding box, but is simpler to deal with and behaves better under rotations.

transform(T)¶

Return the bounding sphere of this sphere acted on by T. This always returns a new sphere, even if the resulting object is an ellipsoid.

EXAMPLES:

sage: from sage.plot.plot3d.transform import Transformation
sage: from sage.plot.plot3d.base import BoundingSphere
sage: BoundingSphere((0,0,0), 10).transform(Transformation(trans=(1,2,3)))
Center (1.0, 2.0, 3.0) radius 10.0
sage: BoundingSphere((0,0,0), 10).transform(Transformation(scale=(1/2, 1, 2)))
Center (0.0, 0.0, 0.0) radius 20.0
sage: BoundingSphere((0,0,3), 10).transform(Transformation(scale=(2, 2, 2)))
Center (0.0, 0.0, 6.0) radius 20.0

class sage.plot.plot3d.base.Graphics3d¶

Bases: sage.structure.sage_object.SageObject

This is the baseclass for all 3d graphics objects.

__add__(left, right)¶

Addition of objects adds them to the same scene.

EXAMPLES:

sage: A = sphere((0,0,0), 1, color='red')
sage: B = dodecahedron((2, 0, 0), color='yellow')
sage: A+B
Graphics3d Object

For convenience, we take 0 and None to be the additive identity:

sage: A + 0 is A
True
sage: A + None is A, 0 + A is A, None + A is A
(True, True, True)

In particular, this allows us to use the sum() function without having to provide an empty starting object:

sage: sum(point3d((cos(n), sin(n), n)) for n in [0..10, step=.1])
Graphics3d Object

A Graphics 3d object can also be added a 2d graphic object:

sage: A = sphere((0, 0, 0), 1) + circle((0, 0), 1.5)
sage: A.show(aspect_ratio=1)

_rich_repr_(display_manager, **kwds)¶

Rich Output Magic Method

See sage.repl.rich_output for details.

EXAMPLES:

sage: from sage.repl.rich_output import get_display_manager
sage: dm = get_display_manager()
sage: g = sphere()
sage: g._rich_repr_(dm)  # OutputSceneThreejs container outside doctest mode
OutputSceneJmol container

amf_ascii_string(name='surface')¶

Return an AMF (Additive Manufacturing File Format) representation of the surface.

Warning

This only works for triangulated surfaces!

INPUT:

name (string, default: “surface”) – name of the surface.

OUTPUT:

A string that represents the surface in the AMF format.

See Wikipedia article Additive_Manufacturing_File_Format

Todo

This should rather be saved as a ZIP archive to save space.

EXAMPLES:

sage: x,y,z = var('x,y,z')
sage: a = implicit_plot3d(x^2+y^2+z^2-9,[x,-5,5],[y,-5,5],[z,-5,5])
sage: a_amf = a.amf_ascii_string()
sage: a_amf[:160]
'<?xml version="1.0" encoding="utf-8"?><amf><object id="surface"><mesh><vertices><vertex><coordinates><x>2.948717948717948</x><y>-0.384615384615385</y><z>-0.3935'

sage: p = polygon3d([[0,0,0], [1,2,3], [3,0,0]])
sage: print(p.amf_ascii_string(name='triangle'))
<?xml version="1.0" encoding="utf-8"?><amf><object id="triangle"><mesh><vertices><vertex><coordinates><x>0.0</x><y>0.0</y><z>0.0</z></coordinates></vertex><vertex><coordinates><x>1.0</x><y>2.0</y><z>3.0</z></coordinates></vertex><vertex><coordinates><x>3.0</x><y>0.0</y><z>0.0</z></coordinates></vertex></vertices><volume><triangle><v1>0</v1><v2>1</v2><v3>2</v3></triangle></volume></mesh></object></amf>

aspect_ratio(v=None)¶

Set or get the preferred aspect ratio of self.

INPUT:

v – (default: None) must be a list or tuple of length three, or the integer 1. If no arguments are provided then the default aspect ratio is returned.

EXAMPLES:

sage: D = dodecahedron()
sage: D.aspect_ratio()
[1.0, 1.0, 1.0]
sage: D.aspect_ratio([1,2,3])
sage: D.aspect_ratio()
[1.0, 2.0, 3.0]
sage: D.aspect_ratio(1)
sage: D.aspect_ratio()
[1.0, 1.0, 1.0]

bounding_box()¶

Return the lower and upper corners of a 3d bounding box for self.

This is used for rendering and self should fit entirely within this box.

Specifically, the first point returned should have x, y, and z coordinates should be the respective infimum over all points in self, and the second point is the supremum.

The default return value is simply the box containing the origin.

EXAMPLES:

sage: sphere((1,1,1), 2).bounding_box()
((-1.0, -1.0, -1.0), (3.0, 3.0, 3.0))
sage: G = line3d([(1, 2, 3), (-1,-2,-3)])
sage: G.bounding_box()
((-1.0, -2.0, -3.0), (1.0, 2.0, 3.0))

default_render_params()¶

Return an instance of RenderParams suitable for plotting this object.

EXAMPLES:

sage: type(dodecahedron().default_render_params())
<class 'sage.plot.plot3d.base.RenderParams'>

export_jmol(filename='jmol_shape.jmol', force_reload=False, zoom=1, spin=False, background=1, 1, 1, stereo=False, mesh=False, dots=False, perspective_depth=True, orientation=- 764, - 346, - 545, 76.39, **ignored_kwds)¶

A jmol scene consists of a script which refers to external files. Fortunately, we are able to put all of them in a single zip archive, which is the output of this call.

EXAMPLES:

sage: out_file = tmp_filename(ext=".jmol")
sage: G = sphere((1, 2, 3), 5) + cube() + sage.plot.plot3d.shapes.Text("hi")
sage: G.export_jmol(out_file)
sage: import zipfile
sage: z = zipfile.ZipFile(out_file)
sage: z.namelist()
['obj_...pmesh', 'SCRIPT']

sage: print(z.read('SCRIPT').decode('ascii'))
data "model list"
2
empty
Xx 0 0 0
Xx 5.5 5.5 5.5
end "model list"; show data
select *
wireframe off; spacefill off
set labelOffset 0 0
background [255,255,255]
spin OFF
moveto 0 -764 -346 -545 76.39
centerAt absolute {0 0 0}
zoom 100
frank OFF
set perspectivedepth ON
isosurface sphere_1  center {1.0 2.0 3.0} sphere 5.0
color isosurface  [102,102,255]
pmesh obj_... "obj_...pmesh"
color pmesh  [102,102,255]
select atomno = 1
color atom  [102,102,255]
label "hi"
isosurface fullylit; pmesh o* fullylit; set antialiasdisplay on;

sage: print(z.read(z.namelist()[0]).decode('ascii'))
24
0.5 0.5 0.5
-0.5 0.5 0.5
...
-0.5 -0.5 -0.5
6
5
0
1
...

flatten()¶

Try to reduce the depth of the scene tree by consolidating groups and transformations.

The generic Graphics3d object cannot be made flatter.

EXAMPLES:

sage: G = sage.plot.plot3d.base.Graphics3d()
sage: G.flatten() is G
True

frame_aspect_ratio(v=None)¶

Set or get the preferred frame aspect ratio of self.

INPUT:

v – (default: None) must be a list or tuple of length three, or the integer 1. If no arguments are provided then the default frame aspect ratio is returned.

EXAMPLES:

sage: D = dodecahedron()
sage: D.frame_aspect_ratio()
[1.0, 1.0, 1.0]
sage: D.frame_aspect_ratio([2,2,1])
sage: D.frame_aspect_ratio()
[2.0, 2.0, 1.0]
sage: D.frame_aspect_ratio(1)
sage: D.frame_aspect_ratio()
[1.0, 1.0, 1.0]

jmol_repr(render_params)¶

A (possibly nested) list of strings which will be concatenated and used by jmol to render self.

(Nested lists of strings are used because otherwise all the intermediate concatenations can kill performance). This may refer to several remove files, which are stored in render_parames.output_archive.

EXAMPLES:

sage: G = sage.plot.plot3d.base.Graphics3d()
sage: G.jmol_repr(G.default_render_params())
[]
sage: G = sphere((1, 2, 3))
sage: G.jmol_repr(G.default_render_params())
[['isosurface sphere_1  center {1.0 2.0 3.0} sphere 1.0\ncolor isosurface  [102,102,255]']]

json_repr(render_params)¶

A (possibly nested) list of strings. Each entry is formatted as JSON, so that a JavaScript client could eval it and get an object. Each object has fields to encapsulate the faces and vertices of self. This representation is intended to be consumed by the canvas3d viewer backend.

EXAMPLES:

sage: G = sage.plot.plot3d.base.Graphics3d()
sage: G.json_repr(G.default_render_params())
[]

mtl_str()¶

Return the contents of a .mtl file, to be used to provide coloring information for an .obj file.

EXAMPLES:

sage: G = tetrahedron(color='red') + tetrahedron(color='yellow', opacity=0.5)
sage: print(G.mtl_str())
newmtl ...
Ka 0.5 5e-06 5e-06
Kd 1.0 1e-05 1e-05
Ks 0.0 0.0 0.0
illum 1
Ns 1.0
d 1.0
newmtl ...
Ka 0.5 0.5 5e-06
Kd 1.0 1.0 1e-05
Ks 0.0 0.0 0.0
illum 1
Ns 1.0
d 0.5

obj()¶

An .obj scene file (as a string) containing the this object.

A .mtl file of the same name must also be produced for coloring.

EXAMPLES:

sage: from sage.plot.plot3d.shapes import ColorCube
sage: print(ColorCube(1, ['red', 'yellow', 'blue']).obj())
g obj_1
usemtl ...
v 1 1 1
v -1 1 1
v -1 -1 1
v 1 -1 1
f 1 2 3 4
...
g obj_6
usemtl ...
v -1 -1 1
v -1 1 1
v -1 1 -1
v -1 -1 -1
f 21 22 23 24

obj_repr(render_params)¶

A (possibly nested) list of strings which will be concatenated and used to construct an .obj file of self.

(Nested lists of strings are used because otherwise all the intermediate concatenations can kill performance). This may include a reference to color information which is stored elsewhere.

EXAMPLES:

sage: G = sage.plot.plot3d.base.Graphics3d()
sage: G.obj_repr(G.default_render_params())
[]
sage: G = cube()
sage: G.obj_repr(G.default_render_params())
['g obj_1',
 'usemtl ...',
 ['v 0.5 0.5 0.5',
  'v -0.5 0.5 0.5',
  'v -0.5 -0.5 0.5',
  'v 0.5 -0.5 0.5',
  'v 0.5 0.5 -0.5',
  'v -0.5 0.5 -0.5',
  'v 0.5 -0.5 -0.5',
  'v -0.5 -0.5 -0.5'],
 ['f 1 2 3 4',
  'f 1 5 6 2',
  'f 1 4 7 5',
  'f 6 5 7 8',
  'f 7 4 3 8',
  'f 3 2 6 8'],
 []]

plot()¶

Draw a 3D plot of this graphics object, which just returns this object since this is already a 3D graphics object. Needed to support PLOT in doctrings, see trac ticket #17498

EXAMPLES:

sage: S = sphere((0,0,0), 2)
sage: S.plot() is S
True

ply_ascii_string(name='surface')¶

Return a PLY (Polygon File Format) representation of the surface.

INPUT:

name (string, default: “surface”) – name of the surface.

OUTPUT:

A string that represents the surface in the PLY format.

See Wikipedia article PLY_(file_format)

EXAMPLES:

sage: x,y,z = var('x,y,z')
sage: a = implicit_plot3d(x^2+y^2+z^2-9,[x,-5,5],[y,-5,5],[z,-5,5])
sage: astl = a.ply_ascii_string()
sage: astl.splitlines()[:10]
['ply',
'format ascii 1.0',
'comment surface',
'element vertex 15540',
'property float x',
'property float y',
'property float z',
'element face 5180',
'property list uchar int vertex_indices',
'end_header']

sage: p = polygon3d([[0,0,0], [1,2,3], [3,0,0]])
sage: print(p.ply_ascii_string(name='triangle'))
ply
format ascii 1.0
comment triangle
element vertex 3
property float x
property float y
property float z
element face 1
property list uchar int vertex_indices
end_header
0.0 0.0 0.0
1.0 2.0 3.0
3.0 0.0 0.0
3 0 1 2

rotate(v, theta)¶

Return self rotated about the vector \(v\) by \(\theta\) radians.

EXAMPLES:

sage: from sage.plot.plot3d.shapes import Cone
sage: v = (1,2,3)
sage: G = arrow3d((0, 0, 0), v)
sage: G += Cone(1/5, 1).translate((0, 0, 2))
sage: C = Cone(1/5, 1, opacity=.25).translate((0, 0, 2))
sage: G += sum(C.rotate(v, pi*t/4) for t in [1..7])
sage: G.show(aspect_ratio=1)

sage: from sage.plot.plot3d.shapes import Box
sage: Box(1/3, 1/5, 1/7).rotate((1, 1, 1), pi/3).show(aspect_ratio=1)

rotateX(theta)¶

Return self rotated about the \(x\)-axis by the given angle.

EXAMPLES:

sage: from sage.plot.plot3d.shapes import Cone
sage: G = Cone(1/5, 1) + Cone(1/5, 1, opacity=.25).rotateX(pi/2)
sage: G.show(aspect_ratio=1)

rotateY(theta)¶

Return self rotated about the \(y\)-axis by the given angle.

EXAMPLES:

sage: from sage.plot.plot3d.shapes import Cone
sage: G = Cone(1/5, 1) + Cone(1/5, 1, opacity=.25).rotateY(pi/3)
sage: G.show(aspect_ratio=1)

rotateZ(theta)¶

Return self rotated about the \(z\)-axis by the given angle.

EXAMPLES:

sage: from sage.plot.plot3d.shapes import Box
sage: G = Box(1/2, 1/3, 1/5) + Box(1/2, 1/3, 1/5, opacity=.25).rotateZ(pi/5)
sage: G.show(aspect_ratio=1)

save(filename, **kwds)¶

Save the graphic in a file.

The file type depends on the file extension you give in the filename. This can be either:

an image file (of type: PNG, BMP, GIF, PPM, or TIFF) rendered using Jmol (default) or Tachyon,
a Sage object file (of type .sobj) that you can load back later (a pickle),
an HTML file depicting the graphic using the Three.js viewer,
a data file (of type: X3D, STL, AMF, PLY) for export and use in other software.

For data files, the support is only partial. For instance STL and AMF only works for triangulated surfaces. The prefered format is X3D.

INPUT:

filename – string. Where to save the image or object.
**kwds – When specifying an image file to be rendered by Tachyon or Jmol, any of the viewing options accepted by show() are valid as keyword arguments to this function and they will behave in the same way. Accepted keywords include: viewer, verbosity, figsize, aspect_ratio, frame_aspect_ratio, zoom, frame, and axes. Default values are provided.

EXAMPLES:

sage: f = tmp_filename(ext='.png')
sage: G = sphere()
sage: G.save(f)

We demonstrate using keyword arguments to control the appearance of the output image:

sage: G.save(f, zoom=2, figsize=[5, 10])

Using Tachyon instead of the default viewer (Jmol) to create the image:

sage: G.save(f, viewer='tachyon')

Since Tachyon only outputs PNG images, PIL will be used to convert to alternate formats:

sage: cube().save(tmp_filename(ext='.gif'), viewer='tachyon')

Here is how to save in one of the data formats:

sage: f = tmp_filename(ext='.x3d')
sage: cube().save(f)

sage: open(f).read().splitlines()[7]
"<Shape><Box size='0.5 0.5 0.5'/><Appearance><Material diffuseColor='0.4 0.4 1.0' shininess='1.0' specularColor='0.0 0.0 0.0'/></Appearance></Shape>"

Producing a Three.js-based HTML file:

sage: f = tmp_filename(ext='.html')
sage: G.save(f, frame=False, online=True)

save_image(filename, **kwds)¶

Save a 2-D image rendering.

The image type is determined by the extension of the filename. For example, this could be .png, .jpg, .gif, .pdf, .svg.

INPUT:

filename – string. The file name under which to save the image.

Any further keyword arguments are passed to the renderer.

EXAMPLES:

sage: G = sphere()
sage: png = tmp_filename(ext='.png')
sage: G.save_image(png)
sage: with open(png, 'rb') as fobj:
....:     assert fobj.read().startswith(b'\x89PNG')

sage: gif = tmp_filename(ext='.gif')
sage: G.save_image(gif)
sage: with open(gif, 'rb') as fobj:
....:     assert fobj.read().startswith(b'GIF')

scale(*x)¶

Return self scaled in the x, y, and z directions.

EXAMPLES:

sage: G = dodecahedron() + dodecahedron(opacity=.5).scale(2)
sage: G.show(aspect_ratio=1)
sage: G = icosahedron() + icosahedron(opacity=.5).scale([1, 1/2, 2])
sage: G.show(aspect_ratio=1)

show(**kwds)¶

Display graphics immediately

This method attempts to display the graphics immediately, without waiting for the currently running code (if any) to return to the command line. Be careful, calling it from within a loop will potentially launch a large number of external viewer programs.

INPUT:

viewer – string (default: 'threejs'), how to view the plot; admissible values are
- 'threejs': interactive web-based 3D viewer using JavaScript and a WebGL renderer
- 'jmol': interactive 3D viewer using Java
- 'tachyon': ray tracer generating a static PNG image
- 'canvas3d': web-based 3D viewer using JavaScript and a canvas renderer (Sage notebook only)
verbosity – display information about rendering the figure
figsize – (default: 5); x or pair [x,y] for numbers, e.g., [5,5]; controls the size of the output figure. E.g., with Tachyon the number of pixels in each direction is 100 times figsize[0]. This is ignored for the jmol embedded renderer.
aspect_ratio – (default: 'automatic') – aspect ratio of the coordinate system itself. Give [1,1,1] to make spheres look round.
frame_aspect_ratio – (default: 'automatic') aspect ratio of frame that contains the 3d scene.
zoom – (default: 1) how zoomed in
frame – (default: True) if True, draw a bounding frame with labels
axes – (default: False) if True, draw coordinate axes
**kwds – other options, which make sense for particular rendering engines

OUTPUT:

This method does not return anything. Use save() if you want to save the figure as an image.

CHANGING DEFAULTS: Defaults can be uniformly changed by importing a dictionary and changing it. For example, here we change the default so images display without a frame instead of with one:

sage: from sage.plot.plot3d.base import SHOW_DEFAULTS
sage: SHOW_DEFAULTS['frame'] = False

This sphere will not have a frame around it:

sage: sphere((0,0,0))
Graphics3d Object

We change the default back:

sage: SHOW_DEFAULTS['frame'] = True

Now this sphere is enclosed in a frame:

sage: sphere((0,0,0))
Graphics3d Object

EXAMPLES: We illustrate use of the aspect_ratio option:

sage: x, y = var('x,y')
sage: p = plot3d(2*sin(x*y), (x, -pi, pi), (y, -pi, pi))
sage: p.show(aspect_ratio=[1,1,1])

This looks flattened, but filled with the plot:

sage: p.show(frame_aspect_ratio=[1,1,1/16])

This looks flattened, but the plot is square and smaller:

sage: p.show(aspect_ratio=[1,1,1], frame_aspect_ratio=[1,1,1/8])

This example shows indirectly that the defaults from plot() are dealt with properly:

sage: plot(vector([1,2,3]))
Graphics3d Object

We use the ‘canvas3d’ backend from inside the notebook to get a view of the plot rendered inline using HTML canvas:

sage: p.show(viewer='canvas3d')

stl_ascii_string(name='surface')¶

Return an STL (STereoLithography) representation of the surface.

Warning

This only works for surfaces, not for general plot objects!

INPUT:

name (string, default: “surface”) – name of the surface.

OUTPUT:

A string that represents the surface in the STL format.

See Wikipedia article STL_(file_format)

See also

stl_ascii_string()

EXAMPLES:

sage: x,y,z = var('x,y,z')
sage: a = implicit_plot3d(x^2+y^2+z^2-9,[x,-5,5],[y,-5,5],[z,-5,5])
sage: astl = a.stl_binary()
sage: print(astl[:40].decode('ascii'))
STL binary file / made by SageMath / ###

sage: p = polygon3d([[0,0,0], [1,2,3], [3,0,0]])
sage: print(p.stl_binary()[:40].decode('ascii'))
STL binary file / made by SageMath / ###

This works when faces have more then 3 sides:

sage: P = polytopes.dodecahedron()
sage: Q = P.plot().all[-1]
sage: print(Q.stl_binary()[:40].decode('ascii'))
STL binary file / made by SageMath / ###

tachyon()¶

An tachyon input file (as a string) containing the this object.

EXAMPLES:

sage: print(sphere((1, 2, 3), 5, color='yellow').tachyon())
begin_scene
resolution 400 400
         camera
        ...
      plane
        center -2000 -1000 -500
        normal 2.3 2.4 2.0
        TEXTURE
            AMBIENT 1.0 DIFFUSE 1.0 SPECULAR 1.0 OPACITY 1.0
            COLOR 1.0 1.0 1.0
            TEXFUNC 0
    Texdef texture...
  Ambient 0.3333333333333333 Diffuse 0.6666666666666666 Specular 0.0 Opacity 1.0
   Color 1.0 1.0 0.0
   TexFunc 0
    Sphere center 1.0 -2.0 3.0 Rad 5.0 texture...
end_scene

sage: G = icosahedron(color='red') + sphere((1,2,3), 0.5, color='yellow')
sage: G.show(viewer='tachyon', frame=false)
sage: print(G.tachyon())
begin_scene
...
Texdef texture...
  Ambient 0.3333333333333333 Diffuse 0.6666666666666666 Specular 0.0 Opacity 1.0
   Color 1.0 1.0 0.0
   TexFunc 0
TRI V0 ...
Sphere center 1.0 -2.0 3.0 Rad 0.5 texture...
end_scene

tachyon_repr(render_params)¶

A (possibly nested) list of strings which will be concatenated and used by tachyon to render self.

(Nested lists of strings are used because otherwise all the intermediate concatenations can kill performance). This may include a reference to color information which is stored elsewhere.

EXAMPLES:

sage: G = sage.plot.plot3d.base.Graphics3d()
sage: G.tachyon_repr(G.default_render_params())
[]
sage: G = sphere((1, 2, 3))
sage: G.tachyon_repr(G.default_render_params())
['Sphere center 1.0 2.0 3.0 Rad 1.0 texture...']

testing_render_params()¶

Return an instance of RenderParams suitable for testing this object.

In particular, it opens up a temporary file as an auxiliary zip file for jmol.

EXAMPLES:

sage: type(dodecahedron().testing_render_params())
<class 'sage.plot.plot3d.base.RenderParams'>

texture¶

texture_set()¶

Often the textures of a 3d file format are kept separate from the objects themselves. This function returns the set of textures used, so they can be defined in a preamble or separate file.

EXAMPLES:

sage: sage.plot.plot3d.base.Graphics3d().texture_set()
set()

sage: G = tetrahedron(color='red') + tetrahedron(color='yellow') + tetrahedron(color='red', opacity=0.5)
sage: [t for t in G.texture_set() if t.color == colors.red] # we should have two red textures
[Texture(texture..., red, ff0000), Texture(texture..., red, ff0000)]
sage: [t for t in G.texture_set() if t.color == colors.yellow] # ...and one yellow
[Texture(texture..., yellow, ffff00)]

threejs_repr(render_params)¶

A flat list of (kind, desc) tuples where kind is one of: ‘point’, ‘line’, ‘text’, or ‘surface’; and where desc is a dictionary describing a point, line, text, or surface.

EXAMPLES:

sage: G = sage.plot.plot3d.base.Graphics3d()
sage: G.threejs_repr(G.default_render_params())
[]

transform(**kwds)¶

Apply a transformation to self, where the inputs are passed onto a TransformGroup object.

Mostly for internal use; see the translate, scale, and rotate methods for more details.

EXAMPLES:

sage: sphere((0,0,0), 1).transform(trans=(1, 0, 0), scale=(2,3,4)).bounding_box()
((-1.0, -3.0, -4.0), (3.0, 3.0, 4.0))

translate(*x)¶

Return self translated by the given vector (which can be given either as a 3-iterable or via positional arguments).

EXAMPLES:

sage: icosahedron() + sum(icosahedron(opacity=0.25).translate(2*n, 0, 0) for n in [1..4])
Graphics3d Object
sage: icosahedron() + sum(icosahedron(opacity=0.25).translate([-2*n, n, n^2]) for n in [1..4])
Graphics3d Object

viewpoint()¶

Return the viewpoint of this plot.

Currently only a stub for x3d.

EXAMPLES:

sage: type(dodecahedron().viewpoint())
<class 'sage.plot.plot3d.base.Viewpoint'>

x3d()¶

An x3d scene file (as a string) containing the this object.

EXAMPLES:

sage: print(sphere((1, 2, 3), 5).x3d())
<X3D version='3.0' profile='Immersive' xmlns:xsd='http://www.w3.org/2001/XMLSchema-instance' xsd:noNamespaceSchemaLocation=' http://www.web3d.org/specifications/x3d-3.0.xsd '>
<head>
<meta name='title' content='sage3d'/>
</head>
<Scene>
<Viewpoint position='0 0 6'/>
<Transform translation='1 2 3'>
<Shape><Sphere radius='5.0'/><Appearance><Material diffuseColor='0.4 0.4 1.0' shininess='1.0' specularColor='0.0 0.0 0.0'/></Appearance></Shape>
</Transform>
</Scene>
</X3D>

sage: G = icosahedron() + sphere((0,0,0), 0.5, color='red')
sage: print(G.x3d())
<X3D version='3.0' profile='Immersive' xmlns:xsd='http://www.w3.org/2001/XMLSchema-instance' xsd:noNamespaceSchemaLocation=' http://www.web3d.org/specifications/x3d-3.0.xsd '>
<head>
<meta name='title' content='sage3d'/>
</head>
<Scene>
<Viewpoint position='0 0 6'/>
<Shape>
<IndexedFaceSet coordIndex='...'>
  <Coordinate point='...'/>
</IndexedFaceSet>
<Appearance><Material diffuseColor='0.4 0.4 1.0' shininess='1.0' specularColor='0.0 0.0 0.0'/></Appearance></Shape>
<Transform translation='0 0 0'>
<Shape><Sphere radius='0.5'/><Appearance><Material diffuseColor='1.0 0.0 0.0' shininess='1.0' specularColor='0.0 0.0 0.0'/></Appearance></Shape>
</Transform>
</Scene>
</X3D>

class sage.plot.plot3d.base.Graphics3dGroup(all=(), rot=None, trans=None, scale=None, T=None)¶

Bases: sage.plot.plot3d.base.Graphics3d

This class represents a collection of 3d objects. Usually they are formed implicitly by summing.

bounding_box()¶

Box that contains the bounding boxes of all the objects that make up self.

EXAMPLES:

sage: A = sphere((0,0,0), 5)
sage: B = sphere((1, 5, 10), 1)
sage: A.bounding_box()
((-5.0, -5.0, -5.0), (5.0, 5.0, 5.0))
sage: B.bounding_box()
((0.0, 4.0, 9.0), (2.0, 6.0, 11.0))
sage: (A+B).bounding_box()
((-5.0, -5.0, -5.0), (5.0, 6.0, 11.0))
sage: (A+B).show(aspect_ratio=1, frame=True)

sage: sage.plot.plot3d.base.Graphics3dGroup([]).bounding_box()
((0.0, 0.0, 0.0), (0.0, 0.0, 0.0))

flatten()¶

Try to reduce the depth of the scene tree by consolidating groups and transformations.

EXAMPLES:

sage: G = sum([circle((0, 0), t) for t in [1..10]], sphere()); G
Graphics3d Object
sage: G.flatten()
Graphics3d Object
sage: len(G.all)
2
sage: len(G.flatten().all)
11

jmol_repr(render_params)¶

The jmol representation of a group is simply the concatenation of the representation of its objects.

EXAMPLES:

sage: G = sphere() + sphere((1,2,3))
sage: G.jmol_repr(G.default_render_params())
[[['isosurface sphere_1  center {0.0 0.0 0.0} sphere 1.0\ncolor isosurface  [102,102,255]']],
 [['isosurface sphere_2  center {1.0 2.0 3.0} sphere 1.0\ncolor isosurface  [102,102,255]']]]

json_repr(render_params)¶

The JSON representation of a group is simply the concatenation of the representations of its objects.

EXAMPLES:

sage: G = sphere() + sphere((1, 2, 3))
sage: G.json_repr(G.default_render_params())
[[['{"vertices":...']], [['{"vertices":...']]]

obj_repr(render_params)¶

The obj representation of a group is simply the concatenation of the representation of its objects.

EXAMPLES:

sage: G = tetrahedron() + tetrahedron().translate(10, 10, 10)
sage: G.obj_repr(G.default_render_params())
[['g obj_1',
  'usemtl ...',
  ['v 0 0 1',
   'v 0.942809 0 -0.333333',
   'v -0.471405 0.816497 -0.333333',
   'v -0.471405 -0.816497 -0.333333'],
  ['f 1 2 3', 'f 2 4 3', 'f 1 3 4', 'f 1 4 2'],
  []],
 [['g obj_2',
   'usemtl ...',
   ['v 10 10 11',
    'v 10.9428 10 9.66667',
    'v 9.5286 10.8165 9.66667',
    'v 9.5286 9.1835 9.66667'],
   ['f 5 6 7', 'f 6 8 7', 'f 5 7 8', 'f 5 8 6'],
   []]]]

plot()¶

set_texture(**kwds)¶

EXAMPLES:

sage: G = dodecahedron(color='red', opacity=.5) + icosahedron((3, 0, 0), color='blue')
sage: G
Graphics3d Object
sage: G.set_texture(color='yellow')
sage: G
Graphics3d Object

stl_binary_repr(render_params)¶

The stl binary representation of a group is simply the concatenation of the representation of its objects.

The STL binary representation is a list of binary strings, one for each triangle.

EXAMPLES:

sage: G = sphere() + sphere((1,2,3))
sage: len(G.stl_binary_repr(G.default_render_params()))
2736

tachyon_repr(render_params)¶

The tachyon representation of a group is simply the concatenation of the representations of its objects.

EXAMPLES:

sage: G = sphere() + sphere((1,2,3))
sage: G.tachyon_repr(G.default_render_params())
[['Sphere center 0.0 0.0 0.0 Rad 1.0 texture...'],
 ['Sphere center 1.0 2.0 3.0 Rad 1.0 texture...']]

texture_set()¶

The texture set of a group is simply the union of the textures of all its objects.

EXAMPLES:

sage: G = sphere(color='red') + sphere(color='yellow')
sage: [t for t in G.texture_set() if t.color == colors.red] # one red texture
[Texture(texture..., red, ff0000)]
sage: [t for t in G.texture_set() if t.color == colors.yellow] # one yellow texture
[Texture(texture..., yellow, ffff00)]

sage: T = sage.plot.plot3d.texture.Texture('blue'); T
Texture(texture..., blue, 0000ff)
sage: G = sphere(texture=T) + sphere((1, 1, 1), texture=T)
sage: len(G.texture_set())
1

threejs_repr(render_params)¶

The three.js representation of a group is the concatenation of the representations of its objects.

EXAMPLES:

sage: G = point3d((1,2,3)) + point3d((4,5,6)) + line3d([(1,2,3), (4,5,6)])
sage: G.threejs_repr(G.default_render_params())
[('point',
  {'color': '#6666ff', 'opacity': 1.0, 'point': (1.0, 2.0, 3.0), 'size': 5.0}),
 ('point',
  {'color': '#6666ff', 'opacity': 1.0, 'point': (4.0, 5.0, 6.0), 'size': 5.0}),
 ('line',
  {'color': '#6666ff',
   'linewidth': 1.0,
   'opacity': 1.0,
   'points': [(1.0, 2.0, 3.0), (4.0, 5.0, 6.0)]})]

transform(**kwds)¶

Transforming this entire group simply makes a transform group with the same contents.

EXAMPLES:

sage: G = dodecahedron(color='red', opacity=.5) + icosahedron(color='blue')
sage: G
Graphics3d Object
sage: G.transform(scale=(2,1/2,1))
Graphics3d Object
sage: G.transform(trans=(1,1,3))
Graphics3d Object

x3d_str()¶

The x3d representation of a group is simply the concatenation of the representation of its objects.

EXAMPLES:

sage: G = sphere() + sphere((1,2,3))
sage: print(G.x3d_str())
<Transform translation='0 0 0'>
<Shape><Sphere radius='1.0'/><Appearance><Material diffuseColor='0.4 0.4 1.0' shininess='1.0' specularColor='0.0 0.0 0.0'/></Appearance></Shape>
</Transform>
<Transform translation='1 2 3'>
<Shape><Sphere radius='1.0'/><Appearance><Material diffuseColor='0.4 0.4 1.0' shininess='1.0' specularColor='0.0 0.0 0.0'/></Appearance></Shape>
</Transform>

class sage.plot.plot3d.base.KeyframeAnimationGroup(all=(), **kwds)¶

Bases: sage.plot.plot3d.base.Graphics3dGroup

A group of objects, each depicting a single frame of animation

threejs_repr(render_params)¶

Adds keyframe information to the representations of the group’s contents.

EXAMPLES:

sage: a = point3d((0, 0, 1))
sage: b = point3d((0, 1, 0))
sage: c = point3d((1, 0, 0))
sage: g = sage.plot.plot3d.base.KeyframeAnimationGroup([a, b, c])
sage: g.threejs_repr(g.default_render_params())
[('point', {..., 'keyframe': 0, ..., 'point': (0.0, 0.0, 1.0), ...}),
 ('point', {..., 'keyframe': 1, ..., 'point': (0.0, 1.0, 0.0), ...}),
 ('point', {..., 'keyframe': 2, ..., 'point': (1.0, 0.0, 0.0), ...})]

Only top-level objects get a unique keyframe. Nested objects share the same keyframe:

sage: g = sage.plot.plot3d.base.KeyframeAnimationGroup([a + b, c])
sage: g.threejs_repr(g.default_render_params())
[('point', {..., 'keyframe': 0, ..., 'point': (0.0, 0.0, 1.0), ...}),
 ('point', {..., 'keyframe': 0, ..., 'point': (0.0, 1.0, 0.0), ...}),
 ('point', {..., 'keyframe': 1, ..., 'point': (1.0, 0.0, 0.0), ...})]

class sage.plot.plot3d.base.PrimitiveObject¶

Bases: sage.plot.plot3d.base.Graphics3d

This is the base class for the non-container 3d objects.

get_texture()¶

EXAMPLES:

sage: G = dodecahedron(color='red')
sage: G.get_texture()
Texture(texture..., red, ff0000)

jmol_repr(render_params)¶

Default behavior is to render the triangulation. The actual polygon data is stored in a separate file.

EXAMPLES:

sage: from sage.plot.plot3d.shapes import Torus
sage: G = Torus(1, .5)
sage: G.jmol_repr(G.testing_render_params())
['pmesh obj_1 "obj_1.pmesh"\ncolor pmesh  [102,102,255]']

obj_repr(render_params)¶

Default behavior is to render the triangulation.

EXAMPLES:

sage: from sage.plot.plot3d.shapes import Torus
sage: G = Torus(1, .5)
sage: G.obj_repr(G.default_render_params())
['g obj_1',
 'usemtl ...',
 ['v 0 1 0.5',
 ...
  'f ...'],
 []]

set_texture(texture=None, **kwds)¶

EXAMPLES:

sage: G = dodecahedron(color='red'); G
Graphics3d Object
sage: G.set_texture(color='yellow'); G
Graphics3d Object

tachyon_repr(render_params)¶

Default behavior is to render the triangulation.

EXAMPLES:

sage: from sage.plot.plot3d.shapes import Torus
sage: G = Torus(1, .5)
sage: G.tachyon_repr(G.default_render_params())
['TRI V0 0 1 0.5
...
'texture...']

texture_set()¶

EXAMPLES:

sage: G = dodecahedron(color='red')
sage: G.texture_set()
{Texture(texture..., red, ff0000)}

threejs_repr(render_params)¶

Default behavior is to render the triangulation.

EXAMPLES:

sage: from sage.plot.plot3d.base import PrimitiveObject
sage: class SimpleTriangle(PrimitiveObject):
....:     def triangulation(self):
....:         return polygon3d([(0,0,0), (1,0,0), (0,1,0)])
sage: G = SimpleTriangle()
sage: G.threejs_repr(G.default_render_params())
[('surface',
  {'color': '#0000ff',
   'faces': [[0, 1, 2]],
   'opacity': 1.0,
   'vertices': [{'x': 0.0, 'y': 0.0, 'z': 0.0},
    {'x': 1.0, 'y': 0.0, 'z': 0.0},
    {'x': 0.0, 'y': 1.0, 'z': 0.0}]})]

x3d_str()¶

EXAMPLES:

sage: sphere().flatten().x3d_str()
"<Transform>\n<Shape><Sphere radius='1.0'/><Appearance><Material diffuseColor='0.4 0.4 1.0' shininess='1.0' specularColor='0.0 0.0 0.0'/></Appearance></Shape>\n\n</Transform>"

class sage.plot.plot3d.base.RenderParams(**kwds)¶

Bases: sage.structure.sage_object.SageObject

This class is a container for all parameters that may be needed to render triangulate/render an object to a certain format. It can contain both cumulative and global parameters.

Of particular note is the transformation object, which holds the cumulative transformation from the root of the scene graph to this node in the tree.

pop_transform()¶

Remove the last transformation off the stack, resetting self.transform to the previous value.

EXAMPLES:

sage: from sage.plot.plot3d.transform import Transformation
sage: params = sage.plot.plot3d.base.RenderParams()
sage: T = Transformation(trans=(100, 500, 0))
sage: params.push_transform(T)
sage: params.transform.get_matrix()
[  1.0   0.0   0.0 100.0]
[  0.0   1.0   0.0 500.0]
[  0.0   0.0   1.0   0.0]
[  0.0   0.0   0.0   1.0]
sage: params.push_transform(Transformation(trans=(-100, 500, 200)))
sage: params.transform.get_matrix()
[   1.0    0.0    0.0    0.0]
[   0.0    1.0    0.0 1000.0]
[   0.0    0.0    1.0  200.0]
[   0.0    0.0    0.0    1.0]
sage: params.pop_transform()
sage: params.transform.get_matrix()
[  1.0   0.0   0.0 100.0]
[  0.0   1.0   0.0 500.0]
[  0.0   0.0   1.0   0.0]
[  0.0   0.0   0.0   1.0]

push_transform(T)¶

Push a transformation onto the stack, updating self.transform.

EXAMPLES:

sage: from sage.plot.plot3d.transform import Transformation
sage: params = sage.plot.plot3d.base.RenderParams()
sage: params.transform is None
True
sage: T = Transformation(scale=(10,20,30))
sage: params.push_transform(T)
sage: params.transform.get_matrix()
[10.0  0.0  0.0  0.0]
[ 0.0 20.0  0.0  0.0]
[ 0.0  0.0 30.0  0.0]
[ 0.0  0.0  0.0  1.0]
sage: params.push_transform(T)  # scale again
sage: params.transform.get_matrix()
[100.0   0.0   0.0   0.0]
[  0.0 400.0   0.0   0.0]
[  0.0   0.0 900.0   0.0]
[  0.0   0.0   0.0   1.0]

unique_name(desc='name')¶

Return a unique identifier starting with desc.

INPUT:

desc (string) – the prefix of the names (default ‘name’)

EXAMPLES:

sage: params = sage.plot.plot3d.base.RenderParams()
sage: params.unique_name()
'name_1'
sage: params.unique_name()
'name_2'
sage: params.unique_name('texture')
'texture_3'

class sage.plot.plot3d.base.TransformGroup(all=[], rot=None, trans=None, scale=None, T=None)¶

Bases: sage.plot.plot3d.base.Graphics3dGroup

This class is a container for a group of objects with a common transformation.

bounding_box()¶

Return the bounding box of self, i.e., the box containing the contents of self after applying the transformation.

EXAMPLES:

sage: G = cube()
sage: G.bounding_box()
((-0.5, -0.5, -0.5), (0.5, 0.5, 0.5))
sage: G.scale(4).bounding_box()
((-2.0, -2.0, -2.0), (2.0, 2.0, 2.0))
sage: G.rotateZ(pi/4).bounding_box()
((-0.7071067811865475, -0.7071067811865475, -0.5),
 (0.7071067811865475, 0.7071067811865475, 0.5))

flatten()¶

Try to reduce the depth of the scene tree by consolidating groups and transformations.

EXAMPLES:

sage: G = sphere((1,2,3)).scale(100)
sage: T = G.get_transformation()
sage: T.get_matrix()
[100.0   0.0   0.0   0.0]
[  0.0 100.0   0.0   0.0]
[  0.0   0.0 100.0   0.0]
[  0.0   0.0   0.0   1.0]

sage: G.flatten().get_transformation().get_matrix()
[100.0   0.0   0.0 100.0]
[  0.0 100.0   0.0 200.0]
[  0.0   0.0 100.0 300.0]
[  0.0   0.0   0.0   1.0]

get_transformation()¶

Return the actual transformation object associated with self.

EXAMPLES:

sage: G = sphere().scale(100)
sage: T = G.get_transformation()
sage: T.get_matrix()
[100.0   0.0   0.0   0.0]
[  0.0 100.0   0.0   0.0]
[  0.0   0.0 100.0   0.0]
[  0.0   0.0   0.0   1.0]

jmol_repr(render_params)¶

Transformations for jmol are applied at the leaf nodes.

EXAMPLES:

sage: G = sphere((1,2,3)).scale(2)
sage: G.jmol_repr(G.default_render_params())
[[['isosurface sphere_1  center {2.0 4.0 6.0} sphere 2.0\ncolor isosurface  [102,102,255]']]]

json_repr(render_params)¶

Transformations are applied at the leaf nodes.

EXAMPLES:

sage: G = cube().rotateX(0.2)
sage: G.json_repr(G.default_render_params())
[['{"vertices":[{"x":0.5,"y":0.589368,"z":0.390699},...']]

obj_repr(render_params)¶

Transformations for .obj files are applied at the leaf nodes.

EXAMPLES:

sage: G = cube().scale(4).translate(1, 2, 3)
sage: G.obj_repr(G.default_render_params())
[[['g obj_1',
   'usemtl ...',
   ['v 3 4 5',
    'v -1 4 5',
    'v -1 0 5',
    'v 3 0 5',
    'v 3 4 1',
    'v -1 4 1',
    'v 3 0 1',
    'v -1 0 1'],
   ['f 1 2 3 4',
    'f 1 5 6 2',
    'f 1 4 7 5',
    'f 6 5 7 8',
    'f 7 4 3 8',
    'f 3 2 6 8'],
   []]]]

stl_binary_repr(render_params)¶

Transformations are applied at the leaf nodes.

The STL binary representation is a list of binary strings, one for each triangle.

EXAMPLES:

sage: G = sphere().translate((1,2,0))
sage: len(G.stl_binary_repr(G.default_render_params()))
1368

tachyon_repr(render_params)¶

Transformations for Tachyon are applied at the leaf nodes.

EXAMPLES:

sage: G = sphere((1,2,3)).scale(2)
sage: G.tachyon_repr(G.default_render_params())
[['Sphere center 2.0 4.0 6.0 Rad 2.0 texture...']]

threejs_repr(render_params)¶

Transformations for three.js are applied at the leaf nodes.

EXAMPLES:

sage: G = point3d((1,2,3)) + point3d((4,5,6))
sage: G = G.translate(-1, -2, -3).scale(10)
sage: G.threejs_repr(G.default_render_params())
[('point',
  {'color': '#6666ff', 'opacity': 1.0, 'point': (0.0, 0.0, 0.0), 'size': 5.0}),
 ('point',
  {'color': '#6666ff',
   'opacity': 1.0,
   'point': (30.0, 30.0, 30.0),
   'size': 5.0})]

transform(**kwds)¶

Transforming this entire group can be done by composing transformations.

EXAMPLES:

sage: G = dodecahedron(color='red', opacity=.5) + icosahedron(color='blue')
sage: G
Graphics3d Object
sage: G.transform(scale=(2,1/2,1))
Graphics3d Object
sage: G.transform(trans=(1,1,3))
Graphics3d Object

x3d_str()¶

To apply a transformation to a set of objects in x3d, simply make them all children of an x3d Transform node.

EXAMPLES:

sage: sphere((1,2,3)).x3d_str()
"<Transform translation='1 2 3'>\n<Shape><Sphere radius='1.0'/><Appearance><Material diffuseColor='0.4 0.4 1.0' shininess='1.0' specularColor='0.0 0.0 0.0'/></Appearance></Shape>\n\n</Transform>"

class sage.plot.plot3d.base.Viewpoint(*x)¶

Bases: sage.plot.plot3d.base.Graphics3d

This class represents a viewpoint, necessary for x3d.

In the future, there could be multiple viewpoints, and they could have more properties. (Currently they only hold a position).

x3d_str()¶

EXAMPLES:

sage: sphere((0,0,0), 100).viewpoint().x3d_str()
"<Viewpoint position='0 0 6'/>"

sage.plot.plot3d.base.flatten_list(L)¶

This is an optimized routine to turn a list of lists (of lists …) into a single list. We generate data in a non-flat format to avoid multiple data copying, and then concatenate it all at the end.

This is NOT recursive, otherwise there would be a lot of redundant copying (which we are trying to avoid in the first place, though at least it would be just the pointers).

EXAMPLES:

sage: from sage.plot.plot3d.base import flatten_list
sage: flatten_list([])
[]
sage: flatten_list([[[[]]]])
[]
sage: flatten_list([['a', 'b'], 'c'])
['a', 'b', 'c']
sage: flatten_list([['a'], [[['b'], 'c'], ['d'], [[['e', 'f', 'g']]]]])
['a', 'b', 'c', 'd', 'e', 'f', 'g']

sage.plot.plot3d.base.max3(v)¶

Return the componentwise maximum of a list of 3-tuples.

EXAMPLES:

sage: from sage.plot.plot3d.base import min3, max3
sage: max3([(-1,2,5), (-3, 4, 2)])
(-1, 4, 5)

sage.plot.plot3d.base.min3(v)¶

Return the componentwise minimum of a list of 3-tuples.

EXAMPLES:

sage: from sage.plot.plot3d.base import min3, max3
sage: min3([(-1,2,5), (-3, 4, 2)])
(-3, 2, 2)

sage.plot.plot3d.base.optimal_aspect_ratios(ratios)¶

sage.plot.plot3d.base.optimal_extra_kwds(v)¶: Given a list v of dictionaries, this function merges them such that later dictionaries have precedence.

sage.plot.plot3d.base.point_list_bounding_box(v)¶

Return the bounding box of a list of points.

EXAMPLES:

sage: from sage.plot.plot3d.base import point_list_bounding_box
sage: point_list_bounding_box([(1,2,3),(4,5,6),(-10,0,10)])
((-10.0, 0.0, 3.0), (4.0, 5.0, 10.0))
sage: point_list_bounding_box([(float('nan'), float('inf'), float('-inf')), (10,0,10)])
((10.0, 0.0, 10.0), (10.0, 0.0, 10.0))

Base Classes for 3D Graphics Objects and Plotting¶

Previous topic

Next topic

This Page