Mostly lots of documentation updates.

Author: rknop

README.txt

@@ -8,23 +8,26 @@ information about the underlying implementation.)  This documentation
 was generated from the source code using the utility pydoc (for Python
 3).
 
-physvis (c) 2019 by Rob Knop, and is available under the GPL version 3.0
+physvis (c) 2020 by Rob Knop, and is available under the GPL version 3.0
 or later; see the file COPYING for the full license.
 
 REQUIREMENTS
 
 physvis works only with Python 3; it will not work with Python 2.
 
 physvis requires numpy (https://www.numpy.org) and PyOpenGL
-(http://pyopengl.sourceforge.net/).  If you're on Linux, almost
-certainly both of these (for Python 3) are included with your
-distribution.
+(http://pyopengl.sourceforge.net/); if you want to use it with the Qt
+GUI library, you also need PyQT5
+(https://www.riverbankcomputing.com/software/pyqt/intro).  If you're on
+Linux, almost certainly both of these (for Python 3) are included with
+your distribution.
 
 I've used this on Linux.  It has been succesfully used on Windows with
 Anaconda installed.  You can install the needed PyOpenGL libraries with
 
    conda install pyopengl
    conda install freeglut
+   conda install pyqt5
 
 USAGE
 
@@ -49,5 +52,16 @@ For cut and paste purposes:
   grcontext.py object_collection.py physvis_observer.py physvis.py qtgrcontext.py quaternions.py rater.py visual_base.py visual_label.py
 
 See doc/physvis.html for a very brief introduction to code that uses
-this library.  See bouncing_ball.py, rotating_spring.py, and
-vibrating_array.py for examples.
+this library.  In the archive there are also various example programs,
+in increasing order of complexity:
+  bouncing_ball.py
+  testfaces.py
+  facestest.py  (I'm sure there's a good reason for both this and the previous)
+  toomanyspheres.py
+  testcurve.py
+  axes.py
+  many_rotators.py
+  rotating_spring.py
+  testtwowin.py
+  testtwocurves.py (Qt; run with --help to see more info)
+  vibrating_array.py (requires scipy; run with argument "qt" to use Qt backend)

doc/grcontext.html

@@ -70,7 +70,11 @@
 </dl>
 <hr>
 Methods defined here:<br>
-<dl><dt><a name="GLUTContext-__init__"><strong>__init__</strong></a>(self, width=500, height=400, title='PhysVis', *args, **kwargs)</dt><dd><tt>Initialize&nbsp;self.&nbsp;&nbsp;See&nbsp;help(type(self))&nbsp;for&nbsp;accurate&nbsp;signature.</tt></dd></dl>
+<dl><dt><a name="GLUTContext-__init__"><strong>__init__</strong></a>(self, width=500, height=400, title='PhysVis', *args, **kwargs)</dt><dd><tt>Parameters:<br>
+&nbsp;<br>
+width&nbsp;—&nbsp;width&nbsp;of&nbsp;the&nbsp;display&nbsp;(window&nbsp;will&nbsp;be&nbsp;this&nbsp;plus&nbsp;borders)<br>
+height&nbsp;—&nbsp;height&nbsp;of&nbsp;the&nbsp;display<br>
+title&nbsp;—&nbsp;title&nbsp;of&nbsp;the&nbsp;window</tt></dd></dl>
 
 <dl><dt><a name="GLUTContext-add_idle_func"><strong>add_idle_func</strong></a>(func)</dt></dl>
 
@@ -136,7 +140,7 @@
 
 <dl><dt><a name="GLUTContext-determine_perspective_matrix"><strong>determine_perspective_matrix</strong></a>(self)</dt></dl>
 
-<dl><dt><a name="GLUTContext-gl_version_info"><strong>gl_version_info</strong></a>(self)</dt></dl>
+<dl><dt><a name="GLUTContext-gl_version_info"><strong>gl_version_info</strong></a>(self)</dt><dd><tt>Get&nbsp;some&nbsp;perhaps-misleading&nbsp;information&nbsp;about&nbsp;the&nbsp;OpenGL&nbsp;version.</tt></dd></dl>
 
 <dl><dt><a name="GLUTContext-resize2d"><strong>resize2d</strong></a>(self, width, height)</dt><dd><tt>Callback&nbsp;that&nbsp;is&nbsp;called&nbsp;when&nbsp;window&nbsp;is&nbsp;resized.</tt></dd></dl>
 
@@ -161,20 +165,28 @@
 <hr>
 Data descriptors inherited from <a href="grcontext.html#GrContext">GrContext</a>:<br>
 <dl><dt><strong>background</strong></dt>
+<dd><tt>The&nbsp;background&nbsp;color&nbsp;of&nbsp;the&nbsp;display&nbsp;(defaults&nbsp;to&nbsp;black).</tt></dd>
 </dl>
 <dl><dt><strong>center</strong></dt>
+<dd><tt>The&nbsp;point&nbsp;that&nbsp;the&nbsp;camera&nbsp;looks&nbsp;at.</tt></dd>
 </dl>
 <dl><dt><strong>foreground</strong></dt>
+<dd><tt>The&nbsp;background&nbsp;color&nbsp;of&nbsp;the&nbsp;display&nbsp;(defaults&nbsp;to&nbsp;black).</tt></dd>
 </dl>
 <dl><dt><strong>forward</strong></dt>
+<dd><tt>The&nbsp;direction&nbsp;the&nbsp;camera&nbsp;is&nbsp;facing.</tt></dd>
 </dl>
 <dl><dt><strong>fov</strong></dt>
+<dd><tt>Field&nbsp;of&nbsp;view&nbsp;of&nbsp;the&nbsp;camrea&nbsp;in&nbsp;radians.</tt></dd>
 </dl>
 <dl><dt><strong>range</strong></dt>
+<dd><tt>It's&nbsp;complicated&nbsp;and&nbsp;I&nbsp;don't&nbsp;think&nbsp;I've&nbsp;done&nbsp;it&nbsp;right.</tt></dd>
 </dl>
 <dl><dt><strong>scale</strong></dt>
+<dd><tt>Related&nbsp;to&nbsp;range,&nbsp;and&nbsp;I&nbsp;don't&nbsp;think&nbsp;I've&nbsp;done&nbsp;it&nbsp;right.</tt></dd>
 </dl>
 <dl><dt><strong>up</strong></dt>
+<dd><tt>The&nbsp;camera&nbsp;will&nbsp;rotate&nbsp;about&nbsp;its&nbsp;forward&nbsp;axis&nbsp;in&nbsp;an&nbsp;attempt&nbsp;to&nbsp;make&nbsp;this&nbsp;direction&nbsp;up&nbsp;on&nbsp;the&nbsp;screen.</tt></dd>
 </dl>
 <hr>
 Data and other attributes inherited from <a href="grcontext.html#GrContext">GrContext</a>:<br>
@@ -261,7 +273,7 @@
 
 <dl><dt><a name="GrContext-determine_perspective_matrix"><strong>determine_perspective_matrix</strong></a>(self)</dt></dl>
 
-<dl><dt><a name="GrContext-gl_version_info"><strong>gl_version_info</strong></a>(self)</dt></dl>
+<dl><dt><a name="GrContext-gl_version_info"><strong>gl_version_info</strong></a>(self)</dt><dd><tt>Get&nbsp;some&nbsp;perhaps-misleading&nbsp;information&nbsp;about&nbsp;the&nbsp;OpenGL&nbsp;version.</tt></dd></dl>
 
 <dl><dt><a name="GrContext-resize2d"><strong>resize2d</strong></a>(self, width, height)</dt><dd><tt>Callback&nbsp;that&nbsp;is&nbsp;called&nbsp;when&nbsp;window&nbsp;is&nbsp;resized.</tt></dd></dl>
 
@@ -290,24 +302,34 @@
 <hr>
 Data descriptors defined here:<br>
 <dl><dt><strong>background</strong></dt>
+<dd><tt>The&nbsp;background&nbsp;color&nbsp;of&nbsp;the&nbsp;display&nbsp;(defaults&nbsp;to&nbsp;black).</tt></dd>
 </dl>
 <dl><dt><strong>center</strong></dt>
+<dd><tt>The&nbsp;point&nbsp;that&nbsp;the&nbsp;camera&nbsp;looks&nbsp;at.</tt></dd>
 </dl>
 <dl><dt><strong>foreground</strong></dt>
+<dd><tt>The&nbsp;background&nbsp;color&nbsp;of&nbsp;the&nbsp;display&nbsp;(defaults&nbsp;to&nbsp;black).</tt></dd>
 </dl>
 <dl><dt><strong>forward</strong></dt>
+<dd><tt>The&nbsp;direction&nbsp;the&nbsp;camera&nbsp;is&nbsp;facing.</tt></dd>
 </dl>
 <dl><dt><strong>fov</strong></dt>
+<dd><tt>Field&nbsp;of&nbsp;view&nbsp;of&nbsp;the&nbsp;camrea&nbsp;in&nbsp;radians.</tt></dd>
 </dl>
 <dl><dt><strong>height</strong></dt>
+<dd><tt>The&nbsp;height&nbsp;in&nbsp;pixels&nbsp;of&nbsp;the&nbsp;display.</tt></dd>
 </dl>
 <dl><dt><strong>range</strong></dt>
+<dd><tt>It's&nbsp;complicated&nbsp;and&nbsp;I&nbsp;don't&nbsp;think&nbsp;I've&nbsp;done&nbsp;it&nbsp;right.</tt></dd>
 </dl>
 <dl><dt><strong>scale</strong></dt>
+<dd><tt>Related&nbsp;to&nbsp;range,&nbsp;and&nbsp;I&nbsp;don't&nbsp;think&nbsp;I've&nbsp;done&nbsp;it&nbsp;right.</tt></dd>
 </dl>
 <dl><dt><strong>up</strong></dt>
+<dd><tt>The&nbsp;camera&nbsp;will&nbsp;rotate&nbsp;about&nbsp;its&nbsp;forward&nbsp;axis&nbsp;in&nbsp;an&nbsp;attempt&nbsp;to&nbsp;make&nbsp;this&nbsp;direction&nbsp;up&nbsp;on&nbsp;the&nbsp;screen.</tt></dd>
 </dl>
 <dl><dt><strong>width</strong></dt>
+<dd><tt>The&nbsp;width&nbsp;in&nbsp;pixels&nbsp;of&nbsp;the&nbsp;display.</tt></dd>
 </dl>
 <hr>
 Data and other attributes defined here:<br>

doc/physvis.html

@@ -57,11 +57,15 @@
 &nbsp;&nbsp;<a href="#-rate">rate</a>(30)<br>
 &nbsp;<br>
 This&nbsp;does&nbsp;two&nbsp;things.&nbsp;&nbsp;First,&nbsp;it&nbsp;allows&nbsp;the&nbsp;display&nbsp;to&nbsp;update.&nbsp;&nbsp;Second,&nbsp;it&nbsp;limits&nbsp;your<br>
-loop&nbsp;to&nbsp;run&nbsp;no&nbsp;more&nbsp;than&nbsp;30&nbsp;times&nbsp;a&nbsp;second.&nbsp;&nbsp;(You&nbsp;can&nbsp;replace&nbsp;30&nbsp;with&nbsp;a&nbsp;different&nbsp;number,<br>
-of&nbsp;course.&nbsp;&nbsp;It&nbsp;doesn't&nbsp;make&nbsp;sense&nbsp;to&nbsp;do&nbsp;more&nbsp;than&nbsp;30&nbsp;or&nbsp;60&nbsp;frames&nbsp;per&nbsp;second.&nbsp;&nbsp;If&nbsp;you&nbsp;want<br>
-to&nbsp;do&nbsp;calculations&nbsp;more&nbsp;often&nbsp;than&nbsp;that,&nbsp;do&nbsp;multiple&nbsp;calculations&nbsp;in&nbsp;your&nbsp;loop,&nbsp;and&nbsp;only<br>
-update&nbsp;object&nbsp;properties&nbsp;once&nbsp;per&nbsp;loop.)&nbsp;&nbsp;Your&nbsp;loop&nbsp;may&nbsp;run&nbsp;slower&nbsp;than&nbsp;that&nbsp;if&nbsp;the<br>
-computer&nbsp;takes&nbsp;more&nbsp;than&nbsp;1/30&nbsp;seconds&nbsp;to&nbsp;process&nbsp;everything&nbsp;in&nbsp;your&nbsp;loop.<br>
+loop&nbsp;to&nbsp;run&nbsp;no&nbsp;more&nbsp;than&nbsp;30&nbsp;times&nbsp;a&nbsp;second.&nbsp;&nbsp;Your&nbsp;loop&nbsp;may&nbsp;run&nbsp;slower&nbsp;than&nbsp;that&nbsp;if&nbsp;the<br>
+computer&nbsp;takes&nbsp;more&nbsp;than&nbsp;1/30&nbsp;seconds&nbsp;to&nbsp;process&nbsp;everything&nbsp;in&nbsp;your&nbsp;loop.&nbsp;&nbsp;(You&nbsp;can<br>
+replace&nbsp;30&nbsp;with&nbsp;a&nbsp;different&nbsp;number,&nbsp;of&nbsp;course.&nbsp;&nbsp;From&nbsp;a&nbsp;human&nbsp;visual&nbsp;point&nbsp;of&nbsp;view,&nbsp;it<br>
+doesn't&nbsp;make&nbsp;sense&nbsp;to&nbsp;do&nbsp;more&nbsp;than&nbsp;30&nbsp;or&nbsp;60&nbsp;frames&nbsp;per&nbsp;second.&nbsp;&nbsp;If&nbsp;you&nbsp;want&nbsp;to&nbsp;do<br>
+calculations&nbsp;more&nbsp;often&nbsp;than&nbsp;that,&nbsp;do&nbsp;multiple&nbsp;calculations&nbsp;in&nbsp;your&nbsp;loop,&nbsp;and&nbsp;only&nbsp;update<br>
+object&nbsp;properties&nbsp;once&nbsp;per&nbsp;loop.&nbsp;&nbsp;What's&nbsp;more,&nbsp;your&nbsp;rate&nbsp;may&nbsp;be&nbsp;clamped&nbsp;anyway&nbsp;to<br>
+something&nbsp;liek&nbsp;60&nbsp;updates&nbsp;per&nbsp;second&nbsp;based&nbsp;on&nbsp;the&nbsp;graphics&nbsp;system&nbsp;framerate.&nbsp;&nbsp;See&nbsp;comments<br>
+in&nbsp;Rater.py&nbsp;for&nbsp;a&nbsp;description&nbsp;of&nbsp;this,&nbsp;and&nbsp;run&nbsp;"python3&nbsp;testtwocurves.py&nbsp;--help"&nbsp;for<br>
+options&nbsp;on&nbsp;that&nbsp;program&nbsp;to&nbsp;play&nbsp;with&nbsp;this.)<br>
 &nbsp;<br>
 The&nbsp;user&nbsp;can&nbsp;rotate&nbsp;the&nbsp;orientation&nbsp;of&nbsp;the&nbsp;display&nbsp;by&nbsp;holding&nbsp;down&nbsp;the&nbsp;right&nbsp;mouse&nbsp;button<br>
 and&nbsp;moving&nbsp;the&nbsp;mouse.&nbsp;&nbsp;Roll&nbsp;the&nbsp;mouse&nbsp;wheel,&nbsp;or&nbsp;hold&nbsp;down&nbsp;the&nbsp;middle&nbsp;mouse&nbsp;button&nbsp;and&nbsp;move<br>

doc/quaternions.html

@@ -27,17 +27,27 @@
 <font color="#ffffff" face="helvetica, arial"><big><strong>Modules</strong></big></font></td></tr>
 
 <tr><td bgcolor="#aa55cc"><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt></td><td>&nbsp;</td>
-<td width="100%"><table width="100%" summary="list"><tr><td width="25%" valign=top><a href="numpy.html">numpy</a><br>
-</td><td width="25%" valign=top></td><td width="25%" valign=top></td><td width="25%" valign=top></td></tr></table></td></tr></table><p>
+<td width="100%"><table width="100%" summary="list"><tr><td width="25%" valign=top><a href="math.html">math</a><br>
+</td><td width="25%" valign=top><a href="numpy.html">numpy</a><br>
+</td><td width="25%" valign=top></td><td width="25%" valign=top></td></tr></table></td></tr></table><p>
 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
 <tr bgcolor="#eeaa77">
 <td colspan=3 valign=bottom>&nbsp;<br>
 <font color="#ffffff" face="helvetica, arial"><big><strong>Functions</strong></big></font></td></tr>
 
 <tr><td bgcolor="#eeaa77"><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt></td><td>&nbsp;</td>
-<td width="100%"><dl><dt><a name="-quaternion_multiply"><strong>quaternion_multiply</strong></a>(p, q)</dt><dd><tt>Multiply&nbsp;a&nbsp;vector&nbsp;or&nbsp;quaternion&nbsp;p&nbsp;by&nbsp;a&nbsp;quaternion&nbsp;q.<br>
+<td width="100%"><dl><dt><a name="-axistrig_rotate"><strong>axistrig_rotate</strong></a>(v, axis, cosangle_2, sinangle_2)</dt><dd><tt>Rotate&nbsp;vector&nbsp;v&nbsp;about&nbsp;axis&nbsp;by&nbsp;angle&nbsp;θ,&nbsp;where&nbsp;cosangle_2=cos(θ/2)&nbsp;and&nbsp;sinangle_2=sin(θ/2)</tt></dd></dl>
+ <dl><dt><a name="-quaternion_multiply"><strong>quaternion_multiply</strong></a>(p, q)</dt><dd><tt>Multiply&nbsp;a&nbsp;vector&nbsp;or&nbsp;quaternion&nbsp;p&nbsp;by&nbsp;a&nbsp;quaternion&nbsp;q.<br>
+&nbsp;<br>
+In&nbsp;this&nbsp;context,&nbsp;a&nbsp;quaternion&nbsp;is&nbsp;[&nbsp;sin(θ/2)*ux,&nbsp;sin(θ/2)*uy,<br>
+sin(θ/2)*uz,&nbsp;cos(θ/2)&nbsp;]&nbsp;where&nbsp;(ux,&nbsp;uy,&nbsp;uz)&nbsp;is&nbsp;the&nbsp;unit&nbsp;vector&nbsp;about<br>
+which&nbsp;to&nbsp;rotate&nbsp;and&nbsp;θ&nbsp;is&nbsp;the&nbsp;angle&nbsp;by&nbsp;which&nbsp;to&nbsp;rotate.<br>
 &nbsp;<br>
 If&nbsp;p&nbsp;is&nbsp;a&nbsp;quaternion,&nbsp;the&nbsp;returned&nbsp;quaternion&nbsp;represents&nbsp;rotation&nbsp;q&nbsp;followed&nbsp;by&nbsp;rotation&nbsp;p</tt></dd></dl>
- <dl><dt><a name="-quaternion_rotate"><strong>quaternion_rotate</strong></a>(p, q)</dt><dd><tt>Rotate&nbsp;vector&nbsp;p&nbsp;by&nbsp;quaternion&nbsp;q.</tt></dd></dl>
+ <dl><dt><a name="-quaternion_rotate"><strong>quaternion_rotate</strong></a>(p, q)</dt><dd><tt>Rotate&nbsp;vector&nbsp;p&nbsp;by&nbsp;quaternion&nbsp;q.<br>
+&nbsp;<br>
+In&nbsp;this&nbsp;context,&nbsp;a&nbsp;quaternion&nbsp;is&nbsp;[&nbsp;sin(θ/2)*ux,&nbsp;sin(θ/2)*uy,<br>
+sin(θ/2)*uz,&nbsp;cos(θ/2)&nbsp;]&nbsp;where&nbsp;(ux,&nbsp;uy,&nbsp;uz)&nbsp;is&nbsp;the&nbsp;unit&nbsp;vector&nbsp;about<br>
+which&nbsp;to&nbsp;rotate&nbsp;and&nbsp;θ&nbsp;is&nbsp;the&nbsp;angle&nbsp;by&nbsp;which&nbsp;to&nbsp;rotate.</tt></dd></dl>
 </td></tr></table>
 </body></html>