Improve 3D plot documentation

[novoselt]

As mentioned at https://groups.google.com/d/topic/sage-devel/na7d3kwMk68/discussion 3D documentation can greatly benefit from someone actually trying to read/use it from the beginning.

CC: @kcrisman @egourgoulhon

Component: documentation

Author: Javier Honrubia González

Branch/Commit: f530caf

Reviewer: Karl-Dieter Crisman, Eric Gourgoulhon

Issue created by migration from https://trac.sagemath.org/ticket/22685

[sagetrac-jhonrubia6]

Branch: u/jhonrubia6/improve_3d_plot_documentation

[sagetrac-jhonrubia6]

Commit: 16120c8

[sagetrac-jhonrubia6]

New commits:

16120c8

Introduction to 3d graphics rewritten to mimi 2d graphics introduction page

[sagetrac-jhonrubia6]

Author: Javier Honrubia González

[kcrisman]

comment:4

Superficially this looks good, though

+Different viewers are supported other jmol, like a web-based interactive viewer
+using the Three.js JavaScript library and accesible through the ``show(viewer='threejs')``
+method of any 3d graphic. A raytraced representation is accesible by typing
+``show(viewer='tachyon')``:

needs to be updated a bit or changed for grammar, and I wonder about this change:

@@ -260,10 +275,10 @@ class _Coordinates(object):
             sage: v_phi=array([ 0.,  1.57079637,  3.14159274, 4.71238911,  6.28318548])
             sage: v_theta=array([ 0.,  0.78539819,  1.57079637,  2.35619456,  3.14159274])
             sage: m_r=array([[ 0.16763356,  0.25683223,  0.16649297,  0.10594339, 0.55282422],
-            ....: [ 0.16763356,  0.19993708,  0.31403568,  0.47359696, 0.55282422],
-            ....: [ 0.16763356,  0.25683223,  0.16649297,  0.10594339, 0.55282422],
-            ....: [ 0.16763356,  0.19993708,  0.31403568,  0.47359696, 0.55282422],
-            ....: [ 0.16763356,  0.25683223,  0.16649297,  0.10594339, 0.55282422]])
+            ... [ 0.16763356,  0.19993708,  0.31403568,  0.47359696, 0.55282422],
+            ... [ 0.16763356,  0.25683223,  0.16649297,  0.10594339, 0.55282422],
+            ... [ 0.16763356,  0.19993708,  0.31403568,  0.47359696, 0.55282422],
+            ... [ 0.16763356,  0.25683223,  0.16649297,  0.10594339, 0.55282422]])
             sage: import scipy.interpolate
             sage: f=scipy.interpolate.RectBivariateSpline(v_phi,v_theta,m_r)
             sage: spherical_plot3d(f,(0,2*pi),(0,pi))

because I didn't think we changed the continuation style back, but I may not be knowledgeable about that any more.

[sagetrac-jhonrubia6]

comment:5

Replying to @kcrisman:

Superficially this looks good, though

+Different viewers are supported other jmol, like a web-based interactive viewer
+using the Three.js JavaScript library and accesible through the ``show(viewer='threejs')``
+method of any 3d graphic. A raytraced representation is accesible by typing
+``show(viewer='tachyon')``:

needs to be updated a bit or changed for grammar,

Ok, I'll rephrase it.

and I wonder about this change:

@@ -260,10 +275,10 @@ class _Coordinates(object):
             sage: v_phi=array([ 0.,  1.57079637,  3.14159274, 4.71238911,  6.28318548])
             sage: v_theta=array([ 0.,  0.78539819,  1.57079637,  2.35619456,  3.14159274])
             sage: m_r=array([[ 0.16763356,  0.25683223,  0.16649297,  0.10594339, 0.55282422],
-            ....: [ 0.16763356,  0.19993708,  0.31403568,  0.47359696, 0.55282422],
-            ....: [ 0.16763356,  0.25683223,  0.16649297,  0.10594339, 0.55282422],
-            ....: [ 0.16763356,  0.19993708,  0.31403568,  0.47359696, 0.55282422],
-            ....: [ 0.16763356,  0.25683223,  0.16649297,  0.10594339, 0.55282422]])
+            ... [ 0.16763356,  0.19993708,  0.31403568,  0.47359696, 0.55282422],
+            ... [ 0.16763356,  0.25683223,  0.16649297,  0.10594339, 0.55282422],
+            ... [ 0.16763356,  0.19993708,  0.31403568,  0.47359696, 0.55282422],
+            ... [ 0.16763356,  0.25683223,  0.16649297,  0.10594339, 0.55282422]])
             sage: import scipy.interpolate
             sage: f=scipy.interpolate.RectBivariateSpline(v_phi,v_theta,m_r)
             sage: spherical_plot3d(f,(0,2*pi),(0,pi))

because I didn't think we changed the continuation style back, but I may not be knowledgeable about that any more.

I didn't do this change, II'll take a look

[sagetrac-jhonrubia6]

comment:6

Replying to @sagetrac-jhonrubia6:

Replying to @kcrisman:

Superficially this looks good, though

+Different viewers are supported other jmol, like a web-based interactive viewer
+using the Three.js JavaScript library and accesible through the ``show(viewer='threejs')``
+method of any 3d graphic. A raytraced representation is accesible by typing
+``show(viewer='tachyon')``:

needs to be updated a bit or changed for grammar,

Ok, I'll rephrase it.

and I wonder about this change:

@@ -260,10 +275,10 @@ class _Coordinates(object):
             sage: v_phi=array([ 0.,  1.57079637,  3.14159274, 4.71238911,  6.28318548])
             sage: v_theta=array([ 0.,  0.78539819,  1.57079637,  2.35619456,  3.14159274])
             sage: m_r=array([[ 0.16763356,  0.25683223,  0.16649297,  0.10594339, 0.55282422],
-            ....: [ 0.16763356,  0.19993708,  0.31403568,  0.47359696, 0.55282422],
-            ....: [ 0.16763356,  0.25683223,  0.16649297,  0.10594339, 0.55282422],
-            ....: [ 0.16763356,  0.19993708,  0.31403568,  0.47359696, 0.55282422],
-            ....: [ 0.16763356,  0.25683223,  0.16649297,  0.10594339, 0.55282422]])
+            ... [ 0.16763356,  0.19993708,  0.31403568,  0.47359696, 0.55282422],
+            ... [ 0.16763356,  0.25683223,  0.16649297,  0.10594339, 0.55282422],
+            ... [ 0.16763356,  0.19993708,  0.31403568,  0.47359696, 0.55282422],
+            ... [ 0.16763356,  0.25683223,  0.16649297,  0.10594339, 0.55282422]])
             sage: import scipy.interpolate
             sage: f=scipy.interpolate.RectBivariateSpline(v_phi,v_theta,m_r)
             sage: spherical_plot3d(f,(0,2*pi),(0,pi))

because I didn't think we changed the continuation style back, but I may not be knowledgeable about that any more.

I didn't do this change, II'll take a look

I don't remember doing this but, anyway, I'll revert this

[sagetrac-git]

Changed commit from 16120c8 to f530caf

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

f530caf

Reverted some changes and somw rewriting done

[egourgoulhon]

comment:11

Thank you very much for this work. It enhances significantly the 3D plot doc!
I have two minor suggestions, that you might consider:

• in the sentence The viewer is invoked by adding the keyword argument viewer='jmol' (respectively 'tachyon' or 'threejs') to the command show() on any three-dimensional graphic, one should rather write (respectively 'threejs' or 'tachyon') to match the order of the previous sentence.
• in the same sentence, it would nice to replace show() by :funct:~sage.plot.plot3d.base.Graphics3d.show; this would ease the access to the documentation of show, which is somewhat hidden for the end user.

[egourgoulhon]

Reviewer: Karl-Dieter Crisman, Eric Gourgoulhon

[egourgoulhon]

comment:12

OK, since it is highly desirable to have this in Sage 8.0 and the current state of the ticket branch is already very nice, I am setting the ticket to positive review. The suggestions made in comment:11 are not crucial and could be added later on.

[vbraun]

Changed branch from u/jhonrubia6/improve_3d_plot_documentation to f530caf