doc/parts/extensions/Shapes-Geometry3D-circle.sxml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <?xml-stylesheet type="text/xsl" href="formats/html.xsl"?>
   3
   4 <!-- This file is part of Shapes.                                           -->
   5 <!--                                                                        -->
   6 <!-- Shapes is free software: you can redistribute it and/or modify         -->
   7 <!-- it under the terms of the GNU General Public License as published by   -->
   8 <!-- the Free Software Foundation, either version 3 of the License, or      -->
   9 <!-- any later version.                                                     -->
  10 <!--                                                                        -->
  11 <!-- Shapes is distributed in the hope that it will be useful,              -->
  12 <!-- but WITHOUT ANY WARRANTY; without even the implied warranty of         -->
  13 <!-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          -->
  14 <!-- GNU General Public License for more details.                           -->
  15 <!--                                                                        -->
  16 <!-- You should have received a copy of the GNU General Public License      -->
  17 <!-- along with Shapes.  If not, see <http://www.gnu.org/licenses/>.        -->
  18 <!--                                                                        -->
  19 <!-- Copyright 2008, 2014, 2015 Henrik Tidefelt                             -->
  20
  21
  22 <book>
  23   <within-namespace>..Shapes..Geometry3D</within-namespace>
  24   <extension>circle</extension>
  25   <description>
  26     <p>Functions for construction of circular arcs in <str-3D />.</p>
  27   </description>
  28   <prelude />
  29   <needs></needs>
  30
  31   <title><self /></title>
  32   <meta-selflink><self-href /></meta-selflink>
  33   <up-link><parent-namespace /></up-link>
  34   <base href=<!--#expand-next-string-->"$(BASE)" />
  35   <examples-home href=<!--#expand-next-string-->"$(EXAMPLES)" />
  36   <shapes-version number=<!--#expand-next-string-->"$(SHAPES_VERSION)" />
  37   <external>
  38     <!--#include virtual="^/toc.xml" -->
  39   </external>
  40
  41   <top>
  42     <alphabetical-index/>
  43     <p>Circles and circular arcs in <str-3D /> are basically constructed by immersing a <str-2D /> circle or arc, and then move it to the right location.  This extension provides <str-3D /> wrappers of the <str-2D /> counterparts in <extension path="..Shapes..Geometry/circle" />.</p>
  44   </top>
  45
  46   <body>
  47
  48     <system-binding name="generic_arc3D">
  49       <summary><str-3D /> embedding of <str-2D /> arcs</summary>
  50       <function>
  51         <case constructor-of="Path">
  52           <arguments>
  53             <arg identifier="arc2D">
  54               <type><named-type name="Function" /></type>
  55             </arg>
  56             <arg identifier="z0">
  57               <type><named-type name="Coords3D" /></type>
  58             </arg>
  59             <arg identifier="zStart">
  60               <type><named-type name="Coords3D" /></type>
  61             </arg>
  62             <arg identifier="zEnd">
  63               <type><named-type name="Coords3D" /></type>
  64             </arg>
  65             <arg identifier="r">
  66               <type><named-type name="Length" /></type>
  67             </arg>
  68           </arguments>
  69           <dynamic-references></dynamic-references>
  70           <description>
  71             <p>The argument <arg name="arc2D" /> should be a function accepting the same arguments as, for instance, <value name="..Shapes..Geometry..ccw_arc" />.</p>
  72             <p>This function computes the transform that maps the plane spanned by <arg name="z0" />, <arg name="zStart" />, and <arg name="zEnd" />, to a plane through the origin, normal to the <eq>z</eq> direction.  Using this transform in combination with <value name="view" />, the task of constructing arcs is moved from <str-3D /> to <str-2D />, where the arc is constructed using <arg name="arc2D" />, and then the result is immersed and mapped back the the right position in <str-3D />.</p>
  73             <p>The orientation of the intermediate <str-2D /> representation is chosen to ensure that rotation about <arg name="z0" /> from the direction to <arg name="zStart" /> to <arg name="zEnd" /> becomes counter-clockwise in <str-2D />.</p>
  74             <p>The cuts of this function obtained by using <value name="..Shapes..Geometry..ccw_arc" /> or <value name="..Shapes..Geometry..cw_arc" /> are bound to separate variables.</p>
  75           </description>
  76           <see-also>
  77             <value name="..Shapes..Geometry..ccw_arc3D" />
  78             <value name="..Shapes..Geometry..cw_arc3D" />
  79           </see-also>
  80         </case>
  81       </function>
  82     </system-binding>
  83
  84     <system-binding name="ccw_arc3D">
  85       <summary>Couter-clockwise circular arc</summary>
  86       <function>
  87         <case constructor-of="Path">
  88           <arguments>
  89             <arg identifier="z0">
  90               <type><named-type name="Coords3D" /></type>
  91             </arg>
  92             <arg identifier="zStart">
  93               <type><named-type name="Coords3D" /></type>
  94             </arg>
  95             <arg identifier="zEnd">
  96               <type><named-type name="Coords3D" /></type>
  97             </arg>
  98             <arg identifier="r">
  99               <type><named-type name="Length" /></type>
 100             </arg>
 101           </arguments>
 102           <dynamic-references></dynamic-references>
 103           <description>
 104             <p>Uses <value name="..Shapes..Geometry..generic_arc3D" /> with <value name="..Shapes..Geometry..ccw_arc" /> to construct the arc in <str-2D />.</p>
 105           </description>
 106         </case>
 107       </function>
 108     </system-binding>
 109
 110     <system-binding name="cw_arc3D">
 111       <summary>Clockwise circular arc</summary>
 112       <function>
 113         <case constructor-of="Path">
 114           <arguments>
 115             <arg identifier="z0">
 116               <type><named-type name="Coords3D" /></type>
 117             </arg>
 118             <arg identifier="zStart">
 119               <type><named-type name="Coords3D" /></type>
 120             </arg>
 121             <arg identifier="zEnd">
 122               <type><named-type name="Coords3D" /></type>
 123             </arg>
 124             <arg identifier="r">
 125               <type><named-type name="Length" /></type>
 126             </arg>
 127           </arguments>
 128           <dynamic-references></dynamic-references>
 129           <description>
 130             <p>Uses <value name="..Shapes..Geometry..generic_arc3D" /> with <value name="..Shapes..Geometry..cw_arc" /> to construct the arc in <str-2D />.</p>
 131           </description>
 132         </case>
 133       </function>
 134     </system-binding>
 135
 136   </body>
 137 </book>