Classes for Lines, Frames, Rulers, Spheres, Points, Dots, and Text#
AUTHORS:
William Stein (2007-12): initial version
William Stein and Robert Bradshaw (2008-01): Many improvements
- class sage.plot.plot3d.shapes2.Line(points, thickness=5, corner_cutoff=0.5, arrow_head=False, **kwds)#
Bases:
PrimitiveObject
Draw a 3d line joining a sequence of points.
This line has a fixed diameter unaffected by transformations and zooming. It may be smoothed if
corner_cutoff < 1
.INPUT:
points
– list of points to pass throughthickness
– (optional, default 5) diameter of the linecorner_cutoff
– (optional, default 0.5) threshold for smoothing (seecorners()
).arrow_head
– (optional, defaultFalse
) ifTrue
make this curve into an arrow
The parameter
corner_cutoff
is a bound for the cosine of the angle made by two successive segments. This angle is close to \(0\) (and the cosine close to 1) if the two successive segments are almost aligned and close to \(\pi\) (and the cosine close to -1) if the path has a strong peak. If the cosine is smaller than the bound (which means a sharper peak) then no smoothing is done.EXAMPLES:
sage: from sage.plot.plot3d.shapes2 import Line sage: Line([(i*math.sin(i), i*math.cos(i), i/3) for i in range(30)], ....: arrow_head=True) Graphics3d Object
Smooth angles less than 90 degrees:
sage: Line([(0,0,0),(1,0,0),(2,1,0),(0,1,0)], corner_cutoff=0) Graphics3d Object
Make sure that the
corner_cutoff
keyword works (github issue #3859):sage: N = 11 sage: c = 0.4 sage: sum(Line([(i,1,0), (i,0,0), (i,cos(2*pi*i/N), sin(2*pi*i/N))], # needs sage.symbolic ....: corner_cutoff=c, ....: color='red' if -cos(2*pi*i/N)<=c else 'blue') ....: for i in range(N+1)) Graphics3d Object
- bounding_box()#
Return the lower and upper corners of a 3-D bounding box for
self
.This is used for rendering and
self
should fit entirely within this box. In this case, we return the highest and lowest values of each coordinate among all points.
- corners(corner_cutoff=None, max_len=None)#
Figure out where the curve turns too sharply to pretend it is smooth.
INPUT:
corner_cutoff
– (optional, defaultNone
) If the cosine of the angle between adjacent line segments is smaller than this bound, then there will be a sharp corner in the path. Otherwise, the path is smoothed. IfNone
, then the default value 0.5 is used.max_len
– (optional, defaultNone
) Maximum number of points allowed in a single path. If this is set, this creates corners at smooth points in order to break the path into smaller pieces.
The parameter
corner_cutoff
is a bound for the cosine of the angle made by two successive segments. This angle is close to \(0\) (and the cosine close to 1) if the two successive segments are almost aligned and close to \(\pi\) (and the cosine close to -1) if the path has a strong peak. If the cosine is smaller than the bound (which means a sharper peak) then there must be a corner.OUTPUT:
List of points at which to start a new line. This always includes the first point, and never the last.
EXAMPLES:
No corners, always smooth:
sage: from sage.plot.plot3d.shapes2 import Line sage: Line([(0,0,0),(1,0,0),(2,1,0),(0,1,0)], corner_cutoff=-1).corners() [(0, 0, 0)]
Smooth if the angle is greater than 90 degrees:
sage: Line([(0,0,0),(1,0,0),(2,1,0),(0,1,0)], corner_cutoff=0).corners() [(0, 0, 0), (2, 1, 0)]
Every point (corners everywhere):
sage: Line([(0,0,0),(1,0,0),(2,1,0),(0,1,0)], corner_cutoff=1).corners() [(0, 0, 0), (1, 0, 0), (2, 1, 0)]
- jmol_repr(render_params)#
Return representation of the object suitable for plotting using Jmol.
- obj_repr(render_params)#
Return complete representation of the line as an object.
- stl_binary_repr(render_params)#
Return an empty list, as this is not useful for STL export.
EXAMPLES:
sage: L = line3d([(1,2,3), (4,5,6)]).translate(-1, -2, -3) sage: L.stl_binary_repr(L.default_render_params()) []
- tachyon_repr(render_params)#
Return representation of the line suitable for plotting using the Tachyon ray tracer.
- threejs_repr(render_params)#
Return representation of the line suitable for plotting with three.js.
EXAMPLES:
sage: L = line3d([(1,2,3), (4,5,6)], thickness=10, color=(1,0,0), opacity=0.5) sage: L.threejs_repr(L.default_render_params()) [('line', {'color': '#ff0000', 'linewidth': 10.0, 'opacity': 0.5, 'points': [(1.0, 2.0, 3.0), (4.0, 5.0, 6.0)]})]
- class sage.plot.plot3d.shapes2.Point(center, size=1, **kwds)#
Bases:
PrimitiveObject
Create a position in 3-space, represented by a sphere of fixed size.
INPUT:
center
– point (3-tuple)size
– (default: 1)
EXAMPLES:
We normally access this via the
point3d
function. Note that extra keywords are correctly used:sage: point3d((4,3,2),size=2,color='red',opacity=.5) Graphics3d Object
- bounding_box()#
Returns the lower and upper corners of a 3-D bounding box for
self
.This is used for rendering and
self
should fit entirely within this box. In this case, we simply return the center of the point.
- jmol_repr(render_params)#
Return representation of the object suitable for plotting using Jmol.
- obj_repr(render_params)#
Return complete representation of the point as a sphere.
- stl_binary_repr(render_params)#
Return an empty list, as this is not useful for STL export.
EXAMPLES:
sage: P = point3d((1,2,3)).translate(-1, -2, -3) sage: P.stl_binary_repr(P.default_render_params()) []
- tachyon_repr(render_params)#
Return representation of the point suitable for plotting using the Tachyon ray tracer.
- threejs_repr(render_params)#
Return representation of the point suitable for plotting with three.js.
EXAMPLES:
sage: P = point3d((1,2,3), color=(0,1,0), opacity=0.5, size=10) sage: P.threejs_repr(P.default_render_params()) [('point', {'color': '#00ff00', 'opacity': 0.5, 'point': (1.0, 2.0, 3.0), 'size': 10.0})]
- sage.plot.plot3d.shapes2.bezier3d(path, opacity=1, color='blue', aspect_ratio=[1, 1, 1], thickness=2, **options)#
Draw a 3-dimensional bezier path.
Input is similar to bezier_path, but each point in the path and each control point is required to have 3 coordinates.
INPUT:
path
– a list of curves, which each is a list of points. See furtherdetail below.
thickness
– (default: 2)color
– a string ("red"
,"green"
etc) or a tuple (r, g, b) with r, g, b numbers between 0 and 1opacity
– (default: 1) if less than 1 then is transparentaspect_ratio
– (default: [1,1,1])
The path is a list of curves, and each curve is a list of points. Each point is a tuple (x,y,z).
The first curve contains the endpoints as the first and last point in the list. All other curves assume a starting point given by the last entry in the preceding list, and take the last point in the list as their opposite endpoint. A curve can have 0, 1 or 2 control points listed between the endpoints. In the input example for path below, the first and second curves have 2 control points, the third has one, and the fourth has no control points:
path = [[p1, c1, c2, p2], [c3, c4, p3], [c5, p4], [p5], ...]
In the case of no control points, a straight line will be drawn between the two endpoints. If one control point is supplied, then the curve at each of the endpoints will be tangent to the line from that endpoint to the control point. Similarly, in the case of two control points, at each endpoint the curve will be tangent to the line connecting that endpoint with the control point immediately after or immediately preceding it in the list.
So in our example above, the curve between p1 and p2 is tangent to the line through p1 and c1 at p1, and tangent to the line through p2 and c2 at p2. Similarly, the curve between p2 and p3 is tangent to line(p2,c3) at p2 and tangent to line(p3,c4) at p3. Curve(p3,p4) is tangent to line(p3,c5) at p3 and tangent to line(p4,c5) at p4. Curve(p4,p5) is a straight line.
EXAMPLES:
sage: path = [[(0,0,0),(.5,.1,.2),(.75,3,-1),(1,1,0)], ....: [(.5,1,.2),(1,.5,0)], [(.7,.2,.5)]] sage: b = bezier3d(path, color='green'); b # needs sage.symbolic Graphics3d Object
To construct a simple curve, create a list containing a single list:
sage: path = [[(0,0,0),(1,0,0),(0,1,0),(0,1,1)]] sage: curve = bezier3d(path, thickness=5, color='blue'); curve # needs sage.symbolic Graphics3d Object
- sage.plot.plot3d.shapes2.frame3d(lower_left, upper_right, **kwds)#
Draw a frame in 3-D.
Primarily used as a helper function for creating frames for 3-D graphics viewing.
INPUT:
lower_left
– the lower left corner of the frame, as a list, tuple, or vector.upper_right
– the upper right corner of the frame, as a list, tuple, or vector.
EXAMPLES:
A frame:
sage: from sage.plot.plot3d.shapes2 import frame3d sage: frame3d([1,3,2],vector([2,5,4]),color='red') Graphics3d Object
This is usually used for making an actual plot:
sage: y = var('y') # needs sage.symbolic sage: plot3d(sin(x^2+y^2), (x,0,pi), (y,0,pi)) # needs sage.symbolic Graphics3d Object
- sage.plot.plot3d.shapes2.frame_labels(lower_left, upper_right, label_lower_left, label_upper_right, eps=1, **kwds)#
Draw correct labels for a given frame in 3-D.
Primarily used as a helper function for creating frames for 3-D graphics viewing - do not use directly unless you know what you are doing!
INPUT:
lower_left
– the lower left corner of the frame, as a list, tuple, or vector.upper_right
– the upper right corner of the frame, as a list, tuple, or vector.label_lower_left
– the label for the lower left corner of the frame, as a list, tuple, or vector. This label must actually have all coordinates less than the coordinates of the other label.label_upper_right
– the label for the upper right corner of the frame, as a list, tuple, or vector. This label must actually have all coordinates greater than the coordinates of the other label.eps
– (default: 1) a parameter for how far away from the frame to put the labels.
EXAMPLES:
We can use it directly:
sage: from sage.plot.plot3d.shapes2 import frame_labels sage: frame_labels([1,2,3],[4,5,6],[1,2,3],[4,5,6]) Graphics3d Object
This is usually used for making an actual plot:
sage: # needs sage.symbolic sage: y = var('y') sage: P = plot3d(sin(x^2+y^2), (x,0,pi), (y,0,pi)) sage: a,b = P._rescale_for_frame_aspect_ratio_and_zoom(1.0,[1,1,1],1) sage: F = frame_labels(a, b, *P._box_for_aspect_ratio("automatic",a,b)) sage: F.jmol_repr(F.default_render_params())[0] [['select atomno = 1', 'color atom [76,76,76]', 'label "0.0"']]
- sage.plot.plot3d.shapes2.line3d(points, thickness=1, radius=None, arrow_head=False, **kwds)#
Draw a 3d line joining a sequence of points.
One may specify either a thickness or radius. If a thickness is specified, this line will have a constant diameter regardless of scaling and zooming. If a radius is specified, it will behave as a series of cylinders.
INPUT:
points
– a list of at least 2 pointsthickness
– (default: 1)radius
– (default: None)arrow_head
– (default: False)color
– a string ("red"
,"green"
etc) or a tuple (r, g, b) with r, g, b numbers between 0 and 1opacity
– (default: 1) if less than 1 then is transparent
EXAMPLES:
A line in 3-space:
sage: line3d([(1,2,3), (1,0,-2), (3,1,4), (2,1,-2)]) Graphics3d Object
The same line but red:
sage: line3d([(1,2,3), (1,0,-2), (3,1,4), (2,1,-2)], color='red') Graphics3d Object
The points of the line provided as a numpy array:
sage: import numpy sage: line3d(numpy.array([(1,2,3), (1,0,-2), (3,1,4), (2,1,-2)])) Graphics3d Object
A transparent thick green line and a little blue line:
sage: line3d([(0,0,0), (1,1,1), (1,0,2)], opacity=0.5, radius=0.1, ....: color='green') + line3d([(0,1,0), (1,0,2)]) Graphics3d Object
A Dodecahedral complex of 5 tetrahedra (a more elaborate example from Peter Jipsen):
sage: def tetra(col): ....: return line3d([(0,0,1), (2*sqrt(2.)/3,0,-1./3), (-sqrt(2.)/3, sqrt(6.)/3,-1./3),\ ....: (-sqrt(2.)/3,-sqrt(6.)/3,-1./3), (0,0,1), (-sqrt(2.)/3, sqrt(6.)/3,-1./3),\ ....: (-sqrt(2.)/3,-sqrt(6.)/3,-1./3), (2*sqrt(2.)/3,0,-1./3)],\ ....: color=col, thickness=10, aspect_ratio=[1,1,1]) sage: from math import pi sage: v = (sqrt(5.)/2-5/6, 5/6*sqrt(3.)-sqrt(15.)/2, sqrt(5.)/3) sage: t = acos(sqrt(5.)/3)/2 sage: t1 = tetra('blue').rotateZ(t) sage: t2 = tetra('red').rotateZ(t).rotate(v,2*pi/5) sage: t3 = tetra('green').rotateZ(t).rotate(v,4*pi/5) sage: t4 = tetra('yellow').rotateZ(t).rotate(v,6*pi/5) sage: t5 = tetra('orange').rotateZ(t).rotate(v,8*pi/5) sage: show(t1+t2+t3+t4+t5, frame=False)
- sage.plot.plot3d.shapes2.point3d(v, size=5, **kwds)#
Plot a point or list of points in 3d space.
INPUT:
v
– a point or list of pointssize
– (default: 5) size of the point (or points)color
– a string ("red"
,"green"
etc) or a tuple (r, g, b) with r, g, b numbers between 0 and 1opacity
– (default: 1) if less than 1 then is transparent
EXAMPLES:
sage: sum(point3d((i,i^2,i^3), size=5) for i in range(10)) Graphics3d Object
We check to make sure this works with vectors and other iterables:
sage: pl = point3d([vector(ZZ,(1, 0, 0)), vector(ZZ,(0, 1, 0)), (-1, -1, 0)]) sage: print(point(vector((2,3,4)))) Graphics3d Object sage: c = polytopes.hypercube(3) # needs sage.geometry.polyhedron sage: v = c.vertices()[0]; v # needs sage.geometry.polyhedron A vertex at (1, -1, -1) sage: print(point(v)) # needs sage.geometry.polyhedron Graphics3d Object
We check to make sure the options work:
sage: point3d((4,3,2), size=20, color='red', opacity=.5) Graphics3d Object
numpy arrays can be provided as input:
sage: import numpy sage: point3d(numpy.array([1,2,3])) Graphics3d Object
sage: point3d(numpy.array([[1,2,3], [4,5,6], [7,8,9]])) Graphics3d Object
We check that iterators of points are accepted (github issue #13890):
sage: point3d(iter([(1,1,2),(2,3,4),(3,5,8)]), size=20, color='red') Graphics3d Object
- sage.plot.plot3d.shapes2.polygon3d(points, opacity=1, color=(0, 0, 1), **options)#
Draw a polygon in 3d.
INPUT:
points
– the vertices of the polygon
Type
polygon3d.options
for a dictionary of the default options for polygons. You can change this to change the defaults for all future polygons. Usepolygon3d.reset()
to reset to the default options.EXAMPLES:
A simple triangle:
sage: polygon3d([[0,2,0], [1.5,1,3], [3,0,0]]) Graphics3d Object
Some modern art – a random polygon:
sage: v = [(randrange(-5,5), randrange(-5,5), randrange(-5, 5)) ....: for _ in range(10)] sage: polygon3d(v) Graphics3d Object
A bent transparent green triangle:
sage: polygon3d([[1, 2, 3], [0,1,0], [1,0,1], [3,0,0]], ....: color=(0,1,0), opacity=0.7) Graphics3d Object
This is the same as using
alpha=0.7
:sage: polygon3d([[1, 2, 3], [0,1,0], [1,0,1], [3,0,0]], ....: color=(0,1,0), alpha=0.7) Graphics3d Object
- sage.plot.plot3d.shapes2.polygons3d(faces, points, opacity=1, color=(0, 0, 1), **options)#
Draw the union of several polygons in 3d.
Useful to plot a polyhedron as just one
IndexFaceSet
.INPUT:
faces
– list of faces, every face given by the list of indices of its verticespoints
– coordinates of the vertices in the union
EXAMPLES:
Two adjacent triangles:
sage: f = [[0,1,2],[1,2,3]] sage: v = [(-1,0,0),(0,1,1),(0,-1,1),(1,0,0)] sage: polygons3d(f, v, color='red') Graphics3d Object
- sage.plot.plot3d.shapes2.ruler(start, end, ticks=4, sub_ticks=4, absolute=False, snap=False, **kwds)#
Draw a ruler in 3-D, with major and minor ticks.
INPUT:
start
– the beginning of the ruler, as a list, tuple, or vector.end
– the end of the ruler, as a list, tuple, or vector.ticks
– (default: 4) the number of major ticks shown on the ruler.sub_ticks
– (default: 4) the number of shown subdivisions between each major tick.absolute
– (default:False
) ifTrue
, makes a huge ruler in the direction of an axis.snap
– (default:False
) ifTrue
, snaps to an implied grid.
EXAMPLES:
A ruler:
sage: from sage.plot.plot3d.shapes2 import ruler sage: R = ruler([4, 2, 1],vector([3, 3, 2])); R Graphics3d Object
A ruler with some options:
sage: R = ruler([4, 2, 1],vector([3, 3, 2]),ticks=6, sub_ticks=2, color='red'); R Graphics3d Object
The keyword
snap
makes the ticks not necessarily coincide with the ruler:sage: ruler([4, 2, 1],vector([3, 3, 2]),snap=True) Graphics3d Object
The keyword
absolute
makes a huge ruler in one of the axis directions:sage: ruler([1,2,3],vector([1,2,4]),absolute=True) Graphics3d Object
- sage.plot.plot3d.shapes2.ruler_frame(lower_left, upper_right, ticks=4, sub_ticks=4, **kwds)#
Draw a frame made of 3-D rulers, with major and minor ticks.
INPUT:
lower_left
– the lower left corner of the frame, as a list, tuple, or vector.upper_right
– the upper right corner of the frame, as a list, tuple, or vector.ticks
– (default: 4) the number of major ticks shown on each ruler.sub_ticks
– (default: 4) the number of shown subdivisions between each major tick.
EXAMPLES:
A ruler frame:
sage: from sage.plot.plot3d.shapes2 import ruler_frame sage: F = ruler_frame([1,2,3],vector([2,3,4])); F Graphics3d Object
A ruler frame with some options:
sage: F = ruler_frame([1,2,3],vector([2,3,4]),ticks=6, sub_ticks=2, color='red'); F Graphics3d Object
- sage.plot.plot3d.shapes2.sphere(center=(0, 0, 0), size=1, **kwds)#
Return a plot of a sphere of radius
size
centered at \((x,y,z)\).INPUT:
\((x,y,z)\) – center (default: (0,0,0))
size
– the radius (default: 1)
EXAMPLES: A simple sphere:
sage: sphere() Graphics3d Object
Two spheres touching:
sage: sphere(center=(-1,0,0)) + sphere(center=(1,0,0), aspect_ratio=[1,1,1]) Graphics3d Object
Spheres of radii 1 and 2 one stuck into the other:
sage: sphere(color='orange') + sphere(color=(0,0,0.3), ....: center=(0,0,-2), size=2, opacity=0.9) Graphics3d Object
We draw a transparent sphere on a saddle.
sage: u,v = var('u v') # needs sage.symbolic sage: saddle = plot3d(u^2 - v^2, (u,-2,2), (v,-2,2)) # needs sage.symbolic sage: sphere((0,0,1), color='red', opacity=0.5, aspect_ratio=[1,1,1]) + saddle # needs sage.symbolic Graphics3d Object
- sage.plot.plot3d.shapes2.text3d(txt, x_y_z, **kwds)#
Display 3d text.
INPUT:
txt
– some text(x,y,z)
– position tuple \((x,y,z)\)**kwds
– standard 3d graphics options
EXAMPLES:
We write the word Sage in red at position (1,2,3):
sage: text3d("Sage", (1,2,3), color=(0.5,0,0)) Graphics3d Object
We draw a multicolor spiral of numbers:
sage: sum([text3d('%.1f'%n, (cos(n),sin(n),n), color=(n/2,1-n/2,0)) ....: for n in [0,0.2,..,8]]) Graphics3d Object
Another example:
sage: text3d("Sage is really neat!!",(2,12,1)) Graphics3d Object
And in 3d in two places:
sage: text3d("Sage is...",(2,12,1), color=(1,0,0)) + text3d("quite powerful!!",(4,10,0), color=(0,0,1)) Graphics3d Object
Adjust the font size, family, style, and weight (Three.js viewer only):
sage: t0 = text3d("Pixel size", (0, 0, 0), fontsize=20) sage: t1 = text3d("Percentage size", (0, 0, 1), fontsize='300%') sage: t2 = text3d("Keyword size", (0, 0, 2), fontsize='x-small') sage: t3 = text3d("Single family", (0, 0, 3), fontfamily='serif') sage: t4 = text3d("Family fallback", (0, 0, 4), fontfamily=['Consolas', 'Lucida Console', 'monospace']) sage: t5 = text3d("Another way", (0, 0, 5), fontfamily='Consolas, Lucida Console, monospace') sage: t6 = text3d("Style", (0, 0, 6), fontstyle='italic') sage: t7 = text3d("Keyword weight", (0, 0, 7), fontweight='bold') sage: t8 = text3d("Integer weight (1-1000)", (0, 0, 8), fontweight=800) # 'extra bold' sage: sum([t0, t1, t2, t3, t4, t5, t6, t7, t8]).show(viewer='threejs', frame=False)
Adjust the text’s opacity (Three.js viewer only):
sage: def echo(o): ....: return text3d("Echo!", (0, 0, o), opacity=o) sage: show(sum([echo(o) for o in (0.1, 0.2, .., 1)]), viewer='threejs')