Revision: 68876 http://sourceforge.net/p/brlcad/code/68876 Author: brlcad Date: 2016-09-21 14:16:01 +0000 (Wed, 21 Sep 2016) Log Message: ----------- mark commands and subcommands as commands
Modified Paths: -------------- brlcad/branches/brep-debug/doc/docbook/system/implementation/en/bool_eval_development.xml Modified: brlcad/branches/brep-debug/doc/docbook/system/implementation/en/bool_eval_development.xml =================================================================== --- brlcad/branches/brep-debug/doc/docbook/system/implementation/en/bool_eval_development.xml 2016-09-20 23:31:20 UTC (rev 68875) +++ brlcad/branches/brep-debug/doc/docbook/system/implementation/en/bool_eval_development.xml 2016-09-21 14:16:01 UTC (rev 68876) @@ -52,9 +52,9 @@ </para> </section> <section> - <title>NURBS Boolean Evaluation Using the <function>brep</function> Command</title> + <title>NURBS Boolean Evaluation Using the <command>brep</command> Command</title> <para> - The <function>brep</function> command is available in BRL-CAD's + The <command>brep</command> command is available in BRL-CAD's MGED and Archer applications. If the command is run with a single argument naming a combination, the components of the combination are converted into NURBS objects which are combined @@ -65,10 +65,10 @@ By default, the evaluated B-Rep-type object is written to the database with its original name plus the suffix <literal>.brep</literal> (e.g. running the - <function>brep</function> command on <literal>obj</literal> + <command>brep</command> command on <literal>obj</literal> produces <literal>obj.brep</literal>). If a specific name is desired for the output object, it can be provided as the second - argument to the <function>brep</function> command. + argument to the <command>brep</command> command. </para> <para> There are a number of known limitations to the NURBS Boolean @@ -1251,7 +1251,7 @@ These commands work by creating temporary wireframe objects that are drawn in the view window. While drawn, these objects appear in the in-memory database, so the - <function>ls</function> command will show these objects (with + <command>ls</command> command will show these objects (with names like <varname>_BC_S_<obj>_646464></varname> or <varname>bool1_brep1_surface03838ff</varname>), but they are not saved with the database, and are deleted when erased from @@ -1261,9 +1261,10 @@ <para> Debug wireframe objects are not drawn the same way as geometry, and do not trigger an automatic resize and refresh - of the view. This means that after running a plot command, - you may have to trigger a refresh manually (e.g. by running - the <function>autoview</function> command or interactively + of the view. This means that after running + a <command>plot</command> command, you may have to trigger a + refresh manually (e.g. by running + the <command>autoview</command> command or interactively rotating/resizing the view. </para> <para> @@ -1278,25 +1279,25 @@ <para> </para> <section> - <title>The brep Command</title> + <title>The <command>brep</command> Command</title> <para> - The Archer <function>brep</function> command (also + The Archer <command>brep</command> command (also implemented in MGED) can be used to get structural information about B-Rep objects and visualize different subcomponents. </para> <para> - Most importantly, <function>brep <obj> info</function> + Most importantly, <command>brep <obj> info</command> will report summary information, including the number of - NURBS surfaces and faces and <function>brep <obj> plot - S <index></function> can be used to plot individual + NURBS surfaces and faces and <command>brep <obj> plot + S <index></command> can be used to plot individual surfaces in 3D. </para> <para> This is the primary way you can conceptually link a surface or face index to the 3D geometry it represents. So if you notice an error in an object while viewing it in the editor, - you can use the <function>brep</function> command to + you can use the <command>brep</command> command to determine the index of the surface with the error, and then inspect the in-memory object in a debugger using that index into the final surface array, tracing that surface object to @@ -1314,10 +1315,10 @@ <para> In order to inspect the surfaces and indices for a particular stage of the overall evaluation using the - <function>brep</function> command, it's necessary to + <command>brep</command> command, it's necessary to manually create the intermediate combination (a subtree of the one being evaluated), and use the - <function>brep</function> command to produce the + <command>brep</command> command to produce the intermediate NURBS result. </para> </note> @@ -1325,14 +1326,14 @@ <section> <title>The dplot Command</title> <para> - The <function>dplot</function> command is used to visualize + The <command>dplot</command> command is used to visualize the results of different stages of the NURBS Boolean Evaluation algorithm. This makes it easier to isolate the source of a problem in an evaluation. </para> <para> - Unlike the <function>brep</function> command, the - <function>dplot</function> command is purely a development + Unlike the <command>brep</command> command, the + <command>dplot</command> command is purely a development tool. Its implementation does not honor library boundaries and does not conform to the typical conventions for editor commands, and for this reason is only available as an Archer @@ -1354,7 +1355,7 @@ <filename>bool1_*.plot3</filename>. An additional <filename>bool1.dplot</filename> is written which describes the <filename>.plot3</filename> files that were written in a - format understood by the <function>dplot</function> command. + format understood by the <command>dplot</command> command. </para> <para> One set of files is written for each evaluation. Between @@ -1372,18 +1373,18 @@ the same file names and do not check if written files already exist. It is assumed that you will run an evaluation, inspect the generated files using the - <function>dplot</function> command, and then manually remove + <command>dplot</command> command, and then manually remove (or just move) the generated <filename>.dplot</filename> and <filename>.plot3</filename> files before performing another - evaluation with the <function>brep</function> command. + evaluation with the <command>brep</command> command. </para> <section> <title>The ssx Subcommands</title> <itemizedlist> <listitem> <para> - <emphasis role="bold"><function>dplot bool1.dplot - ssx</function></emphasis> lets you interactively step + <emphasis role="bold"><command>dplot bool1.dplot + ssx</command></emphasis> lets you interactively step through the pairs of surfaces whose axis-aligned bounding boxes were found to intersect. The wireframes of the B-Rep objects being intersected are drawn with @@ -1395,14 +1396,14 @@ </listitem> <listitem> <para> - <emphasis role="bold"><function>dplot bool1.dplot - <ssx_index></function></emphasis> lets you + <emphasis role="bold"><command>dplot bool1.dplot + <ssx_index></command></emphasis> lets you interactively step through the specific surface-surface intersections found between the pair of surfaces identified by an <varname>ssx_index</varname>, excluding isocurve-surface intersections (shown by - <function>dplot bool1.dplot isocsx</function>). + <command>dplot bool1.dplot isocsx</command>). </para> <para> To make it easier to check that drawn intersection @@ -1445,8 +1446,8 @@ <itemizedlist> <listitem> <para> - <emphasis role="bold"><function>dplot bool1.dplot - isocsx <ssx_index></function></emphasis> lets + <emphasis role="bold"><command>dplot bool1.dplot + isocsx <ssx_index></command></emphasis> lets you step through the isocurve-surface intersections from the pair of intersecting surfaces identified by the given <varname>ssx_index</varname>. Wireframe @@ -1455,15 +1456,15 @@ highlighted. Each combination of isocurve and surface is assigned an <varname>isocsx_index</varname> (shown in the command window) that can be used as an argument - in the second form of the <function>isocsx</function> + in the second form of the <command>isocsx</command> subcommand. </para> </listitem> <listitem> <para> - <emphasis role="bold"><function>dplot bool1.dplot + <emphasis role="bold"><command>dplot bool1.dplot isocsx <ssx_index> - <isocsx_index></function></emphasis> shows the + <isocsx_index></command></emphasis> shows the actual intersection curve found between the isocurve and surface pair identified by the given <varname>ssx_index</varname> and @@ -1488,8 +1489,8 @@ <itemizedlist> <listitem> <para> - <emphasis role="bold"><function>dplot bool1.dplot - fcurves <ssx_index></function></emphasis> lets + <emphasis role="bold"><command>dplot bool1.dplot + fcurves <ssx_index></command></emphasis> lets you step through the surface-surface intersection curves identified by the given <varname>ssx_index</varname> after they've been @@ -1503,8 +1504,8 @@ </listitem> <listitem> <para> - <emphasis role="bold"><function>dplot bool1.dplot - lcurves</function></emphasis> steps through the final + <emphasis role="bold"><command>dplot bool1.dplot + lcurves</command></emphasis> steps through the final 3D intersection curves used to split faces, after contiguous face-clipped pieces have been linked together. @@ -1541,8 +1542,8 @@ </listitem> <listitem> <para> - <emphasis role="bold"><function>dplot bool1.dplot - faces</function></emphasis> lets you step through the + <emphasis role="bold"><command>dplot bool1.dplot + faces</command></emphasis> lets you step through the new set of faces formed by splitting the original faces with the final linked intersection curves. Faces that are considered part of the final result are drawn @@ -1578,7 +1579,7 @@ <para> It's possible to write out custom curves from any part of the evaluation (i.e. those not covered by - <function>dplot</function>) and view them in MGED/Archer. + <command>dplot</command>) and view them in MGED/Archer. </para> <para> You can pass a 3D <classname>ON_Curve</classname> to the @@ -1617,7 +1618,7 @@ </example> <para> After running an evaluation that produces a custom plot3 - file, you can draw it using the <function>overlay</function> + file, you can draw it using the <command>overlay</command> editor command. </para> <example> @@ -1629,12 +1630,12 @@ </section> </section> <section> - <title>Debugging with the dplot Command</title> + <title>Debugging with the <command>dplot</command> Command</title> <section> <title>Tracing Output to the Code That Created It</title> <para> After you notice a problem in the output shown by the - <function>dplot</function> command, you need to locate the + <command>dplot</command> command, you need to locate the source code that created the erroneous geometry so you can start debugging. The following sections provide example procedures you can perform in Archer and a debugger to start @@ -1645,9 +1646,9 @@ <orderedlist> <listitem> <para> - Use the <function>info</function> and - <function>plot</function> subcommands of the - <function>brep</function> command to find the indexes + Use the <command>info</command> and + <command>plot</command> subcommands of the + <command>brep</command> command to find the indexes (<literal><i></literal> and <literal><j></literal>) of the two faces involved in the missing intersection. @@ -1657,7 +1658,7 @@ create the appropriate intermediate evaluation, corresponding to the <filename>bool<n>.dplot</filename> showing the - error, to run the <function>brep</function> command on. + error, to run the <command>brep</command> command on. </para> </listitem> <listitem> @@ -1684,21 +1685,21 @@ </para> </listitem> </orderedlist> - <bridgehead>If the isocsx subcommand shows that an + <bridgehead>If the <command>isocsx</command> subcommand shows that an isocurve-surface intersection is missing...</bridgehead> <orderedlist> <listitem> <para> Note the index <literal><n></literal> of the surface-surface intersection used as the argument to the - <function>isocsx</function> subcommand. + <command>isocsx</command> subcommand. </para> </listitem> <listitem> <para> - Use the <function>info</function> and - <function>plot</function> subcommands of the - <function>brep</function> command to find the indexes + Use the <command>info</command> and + <command>plot</command> subcommands of the + <command>brep</command> command to find the indexes (<literal><i></literal> and <literal><j></literal>) of the two faces involved in the missing intersection. @@ -1708,7 +1709,7 @@ create the appropriate intermediate evaluation, corresponding to the <filename>bool<n>.dplot</filename> showing the - error, to run the <function>brep</function> command on. + error, to run the <command>brep</command> command on. </para> </listitem> <listitem> @@ -1755,14 +1756,14 @@ </para> </listitem> </orderedlist> - <bridgehead>If the isocsx subcommand shows that isocurve + <bridgehead>If the <command>isocsx</command> subcommand shows that isocurve intersections are incorrect...</bridgehead> <orderedlist> <listitem> <para> Note the index <literal><n></literal> of the surface-surface intersection used as the argument to the - <function>isocsx</function> subcommand. + <command>isocsx</command> subcommand. </para> </listitem> <listitem> @@ -1788,14 +1789,14 @@ </para> </listitem> </orderedlist> - <bridgehead>If the ssx subcommand shows an incorrect + <bridgehead>If the <command>ssx</command> subcommand shows an incorrect intersection curve...</bridgehead> <orderedlist> <listitem> <para> Note the index <literal><n></literal> of the surface-surface intersection used as the argument to the - <function>ssx</function> subcommand, and the index + <command>ssx</command> subcommand, and the index <literal><k></literal> assigned to the incorrect intersection event. </para> @@ -1839,10 +1840,10 @@ <para> Note the index <literal><n></literal> of the surface-surface intersection used as the argument to the - <function>ssx</function> and - <function>fcurves</function> subcommands, and the index + <command>ssx</command> and + <command>fcurves</command> subcommands, and the index <literal><k></literal> assigned by - <function>fcurves</function> to the incorrect clipped + <command>fcurves</command> to the incorrect clipped curves. </para> </listitem> @@ -1879,7 +1880,7 @@ <listitem> <para> Note the index <literal><n></literal> assigned by - <function>lcurves</function> to the relevant linked + <command>lcurves</command> to the relevant linked curves. </para> </listitem> @@ -1971,8 +1972,8 @@ </mediaobject> </figure> <para> - The <function>ssx</function> subcommand of - <function>dplot</function> is used to check that all + The <command>ssx</command> subcommand of + <command>dplot</command> is used to check that all expected surface-surface intersections were attempted between the B-Rep NURBS versions of the two arb8s, hereafter referred to as <emphasis>brep1</emphasis> and @@ -2003,8 +2004,8 @@ </listitem> <listitem> <para> - The <function>ssx <ssx_index></function> subcommand of - <function>dplot</function> is used to check the + The <command>ssx <ssx_index></command> subcommand of + <command>dplot</command> is used to check the individual intersection events. </para> <screen> @@ -2039,8 +2040,8 @@ intersections that make each edge of the square overlap. </para> <para> - The <function>isocsx <ssx_index></function> - subcommand of the <function>dplot</function> command is + The <command>isocsx <ssx_index></command> + subcommand of the <command>dplot</command> command is used to check that all isocurve-surface intersections were attempted. </para> @@ -2054,9 +2055,9 @@ </listitem> <listitem> <para> - The <function>isocsx <ssx_index> - <isocsx_index></function> subcommand of the - <function>dplot</function> command is used to check each + The <command>isocsx <ssx_index> + <isocsx_index></command> subcommand of the + <command>dplot</command> command is used to check each isocurve-surface intersection curve. </para> <screen> @@ -2075,8 +2076,8 @@ </listitem> <listitem> <para> - The <function>fcurves</function> subcommand of the - <function>dplot</function> command is used to check the + The <command>fcurves</command> subcommand of the + <command>dplot</command> command is used to check the overlap intersection curve that resulted from stitching together the four (correct) isocurve-surface intersection curves. The command shows the 3D projection @@ -2125,7 +2126,7 @@ </para> <para> Since the <varname>ssx_index</varname> values reported - by <function>dplot</function> are numbered from 0, the + by <command>dplot</command> are numbered from 0, the intersection we want to investigate, whose <varname>ssx_index</varname> is 10, will be the 11th intersection recorded during the evaluation. @@ -2176,7 +2177,7 @@ <filename>split_overlap7.plot3</filename>. </para> <para> - The <function>overlay</function> command is used to draw + The <command>overlay</command> command is used to draw the contents of the <filename>.plot3</filename> files. </para> <screen> @@ -2202,10 +2203,10 @@ <para> Curve endpoints are tested to see if they coincide, and contiguous curves are linked with the - <function>link_curves</function> routine, which returns + <function>link_curves()</function> routine, which returns a linked curve that replaces the original curves in the <varname>overlaps</varname> array. We'll write out each - such curve returned by <function>link_curves</function>. + such curve returned by <function>link_curves()</function>. </para> <programlisting> <![CDATA[ @@ -2297,7 +2298,7 @@ </screen> <para> Stepping from the breakpoint (e.g. with gdb's - <function>next</function> command) we see that the macro + <command>next</command> command) we see that the macro test <literal>OVERLAPS_LINKED(Start, End)</literal> evaluates as true, indicating that the start of the <varname>overlaps[i]</varname> curves coincide with the @@ -2374,7 +2375,7 @@ <para> This error is corrected and the code is rebuilt. The evaluation is re-run, and we use the - <function>dplot</function> command to verify that the + <command>dplot</command> command to verify that the overlap intersection associated with <varname>ssx_index</varname> 10 is now correct. </para> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. ------------------------------------------------------------------------------ _______________________________________________ BRL-CAD Source Commits mailing list brlcad-commits@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/brlcad-commits