diff options
Diffstat (limited to 'xs/src/qhull/html')
34 files changed, 15550 insertions, 0 deletions
diff --git a/xs/src/qhull/html/index.htm b/xs/src/qhull/html/index.htm new file mode 100644 index 000000000..ca4789b47 --- /dev/null +++ b/xs/src/qhull/html/index.htm @@ -0,0 +1,935 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<meta http-equiv="Content-Type" +content="text/html; charset=iso-8859-1"> +<meta name="GENERATOR" content="Microsoft FrontPage 2.0"> +<title>Qhull manual</title> +<!-- Navigation links +NOTE -- verify all links by 'grep href=' 'grep name=' add # 'sort /+7' + index.htm +--> +</head> + +<body> + +<p><a name="TOP"><b>Up:</b></a> <a +href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b><a +href="http://www.qhull.org/news">News</a> about Qhull<br> +<b>Up:</b> <a href="http://www.qhull.org/html/qh-faq.htm">FAQ</a> about Qhull<br> +<b>To:</b> <a href="#TOC">Qhull manual: Table of Contents</a> +(please wait while loading) <br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> + +<hr> +<!-- Main text of document --> +<h1><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/fixed.html"><img +src="qh--rand.gif" alt="[random-fixed]" align="middle" +width="100" height="100"></a> Qhull manual </h1> + +<p>Qhull is a general dimension code for computing convex hulls, +Delaunay triangulations, halfspace intersections about a point, Voronoi +diagrams, furthest-site Delaunay triangulations, and +furthest-site Voronoi diagrams. These structures have +applications in science, engineering, statistics, and +mathematics. See <a +href="http://www.cs.mcgill.ca/~fukuda/soft/polyfaq/polyfaq.html">Fukuda's +introduction</a> to convex hulls, Delaunay triangulations, +Voronoi diagrams, and linear programming. For a detailed +introduction, see O'Rourke [<a href="#orou94">'94</a>], <i>Computational +Geometry in C</i>. +</p> + +<p>There are six programs. Except for rbox, they use +the same code. Each program includes instructions and examples. +<blockquote> +<ul> +<li><a href="qconvex.htm">qconvex</a> -- convex hulls +<li><a href="qdelaun.htm">qdelaunay</a> -- Delaunay triangulations and + furthest-site Delaunay triangulations +<li><a href="qhalf.htm">qhalf</a> -- halfspace intersections about a point +<li><a href="qhull.htm">qhull</a> -- all structures with additional options +<li><a href="qvoronoi.htm">qvoronoi</a> -- Voronoi diagrams and + furthest-site Voronoi diagrams +<li><a href="rbox.htm">rbox</a> -- generate point distributions for qhull +</ul> +</blockquote> + +<p>Qhull implements the Quickhull algorithm for computing the +convex hull. Qhull includes options +for hull volume, facet area, multiple output formats, and +graphical output. It can approximate a convex hull. </p> + +<p>Qhull handles roundoff errors from floating point +arithmetic. It generates a convex hull with "thick" facets. +A facet's outer plane is clearly above all of the points; +its inner plane is clearly below the facet's vertices. Any +exact convex hull must lie between the inner and outer plane. + +<p>Qhull uses merged facets, triangulated output, or joggled +input. Triangulated output triangulates non-simplicial, merged +facets. Joggled input also +guarantees simplicial output, but it +is less accurate than merged facets. For merged facets, Qhull +reports the maximum outer and inner plane. + +<p><i>Brad Barber, Arlington, MA</i></p> + +<p><b>Copyright © 1995-2015 C.B. Barber</b></p> + +<hr> + +<h2><a href="#TOP">»</a><a name="TOC">Qhull manual: Table of +Contents </a></h2> + +<ul> + <li><a href="#when">When</a> to use Qhull + <ul> + <li><a href="http://www.qhull.org/news">News</a> for Qhull + with new features and reported bugs. + <li><a href="http://www.qhull.org">Home</a> for Qhull with additional URLs + (<a href=index.htm>local copy</a>) + <li><a href="http://www.qhull.org/html/qh-faq.htm">FAQ</a> for Qhull (<a href="qh-faq.htm">local copy</a>) + <li><a href="http://www.qhull.org/download">Download</a> Qhull (<a href=qh-get.htm>local copy</a>) + <li><a href="qh-quick.htm#programs">Quick</a> reference for Qhull and its <a href="qh-quick.htm#options">options</a> + <p> + <li><a href="../COPYING.txt">COPYING.txt</a> - copyright notice<br> + <li><a href="../REGISTER.txt">REGISTER.txt</a> - registration<br> + <li><a href="../README.txt">README.txt</a> - installation + instructions<br> + <li><a href="../src/Changes.txt">Changes.txt</a> - change history <br> + <li><a href="qhull.txt">qhull.txt</a> - Unix manual page + </ul> + <p> + <li><a href="#description">Description</a> of Qhull + <ul> + <li><a href="#definition">de</a>finition • <a + href="#input">in</a>put • <a href="#output">ou</a>tput + • <a href="#algorithm">al</a>gorithm • <a + href="#structure">da</a>ta structure </li> + <li><a href="qh-impre.htm">Imprecision</a> in Qhull</li> + <li><a href="qh-impre.htm#joggle">Merged facets</a> or joggled input + <li><a href="qh-eg.htm">Examples</a> of Qhull</li> + </ul> + <p> + <li><a href=qh-quick.htm#programs>Qhull programs</a>, with instructions and examples + <ul> + <li><a href="qconvex.htm">qconvex</a> -- convex hulls + <li><a href="qdelaun.htm">qdelaunay</a> -- Delaunay triangulations and + furthest-site Delaunay triangulations + <li><a href="qhalf.htm">qhalf</a> -- halfspace intersections about a point + <li><a href="qhull.htm">qhull</a> -- all structures with additional options + <li><a href="qvoronoi.htm">qvoronoi</a> -- Voronoi diagrams and + furthest-site Voronoi diagrams + <li><a href="rbox.htm">rbox</a> -- generate point distributions for qhull + </ul> + <p> + <li><a href="qh-quick.htm#options">Qhull options</a><ul> + <li><a href="qh-opto.htm#output">Output</a> formats</li> + <li><a href="qh-optf.htm#format">Additional</a> I/O + formats</li> + <li><a href="qh-optg.htm#geomview">Geomview</a> + output options</li> + <li><a href="qh-optp.htm#print">Print</a> options</li> + <li><a href="qh-optq.htm#qhull">Qhull</a> control + options</li> + <li><a href="qh-optc.htm#prec">Precision</a> options</li> + <li><a href="qh-optt.htm#trace">Trace</a> options</li> + </ul> + </li> + <p> + <li><a href="#geomview">Geomview</a>, Qhull's graphical viewer</li> + <ul> + <li><a href="#geomview-install">Installing Geomview</a></li> + <li><a href="#geomview-use">Using Geomview</a></li> + <li><a href="#geomview-win">Building Geomview for Windows</a></li> + </ul> + <p> + <li><a href="qh-code.htm">Qhull internals</a><ul> + <li><a href="qh-code.htm#reentrant">Reentrant</a> Qhull</li> + <li><a href="qh-code.htm#convert">How to convert</a> code to reentrant Qhull</li> + <li><a href="qh-code.htm#64bit">Qhull</a> on 64-bit computers</li> + <li><a href="qh-code.htm#cpp">Calling</a> Qhull + from C++ programs</li> + <li><a href="qh-code.htm#library">Calling</a> Qhull + from C programs</li> + <li><a href="qh-code.htm#performance">Performance</a> + of Qhull</li> + <li><a href="qh-code.htm#enhance">Enhancements</a> to + Qhull</li> + <li><a href="../src/libqhull_r/index.htm">Reentrant</a> Qhull functions, macros, and + data structures </li> + <li><a href="../src/libqhull/index.htm">Qhull</a> functions, macros, and + data structures </li> + </ul> + </li> + <p> + <li>Related URLs + <ul> + + <li><a href="news:comp.graphics.algorithms">Newsgroup</a>: + comp.graphics.algorithms + <li><a + href="http://www.faqs.org/faqs/graphics/algorithms-faq/">FAQ</a> for computer graphics algorithms and + Exaflop's <a href="http://exaflop.org/docs/cgafaq/cga6.html">geometric</a> structures. + <li>Amenta's <a href="http://www.geom.uiuc.edu/software/cglist">Directory + of Computational Geometry Software </a></li> + <li>Erickson's <a + href="http://compgeom.cs.uiuc.edu/~jeffe/compgeom/code.html">Computational + Geometry Software</a> </li> + <li>Fukuda's <a + href="http://www.cs.mcgill.ca/~fukuda/soft/polyfaq/polyfaq.html"> + introduction</a> to convex hulls, Delaunay triangulations, + Voronoi diagrams, and linear programming. + <li>Stony Brook's <a + href="http://www.cs.sunysb.edu/~algorith/major_section/1.6.shtml">Algorithm Repository</a> on computational geometry. + </li> + </ul> + <p> + <li><a href="#bugs">What to do</a> if something goes wrong</li> + <li><a href="#email">Email</a></li> + <li><a href="#authors">Authors</a></li> + <li><a href="#ref">References</a></li> + <li><a href="#acknowledge">Acknowledgments</a></li> +</ul> +<h2><a href="#TOC">»</a><a name="when">When to use Qhull</a></h2> +<blockquote> + +<p>Qhull constructs convex hulls, Delaunay triangulations, +halfspace intersections about a point, Voronoi diagrams, furthest-site Delaunay +triangulations, and furthest-site Voronoi diagrams.</p> + +<p>For convex hulls and halfspace intersections, Qhull may be used +for 2-d upto 8-d. For Voronoi diagrams and Delaunay triangulations, Qhull may be +used for 2-d upto 7-d. In higher dimensions, the size of the output +grows rapidly and Qhull does not work well with virtual memory. +If <i>n</i> is the size of +the input and <i>d</i> is the dimension (d>=3), the size of the output +and execution time +grows by <i>n^(floor(d/2)</i> +[see <a href=qh-code.htm#performance>Performance</a>]. For example, do +not try to build a 16-d convex hull of 1000 points. It will +have on the order of 1,000,000,000,000,000,000,000,000 facets. + +<p>On a 600 MHz Pentium 3, Qhull computes the 2-d convex hull of +300,000 cocircular points in 11 seconds. It computes the +2-d Delaunay triangulation and 3-d convex hull of 120,000 points +in 12 seconds. It computes the +3-d Delaunay triangulation and 4-d convex hull of 40,000 points +in 18 seconds. It computes the +4-d Delaunay triangulation and 5-d convex hull of 6,000 points +in 12 seconds. It computes the +5-d Delaunay triangulation and 6-d convex hull of 1,000 points +in 12 seconds. It computes the +6-d Delaunay triangulation and 7-d convex hull of 300 points +in 15 seconds. It computes the +7-d Delaunay triangulation and 8-d convex hull of 120 points +in 15 seconds. It computes the +8-d Delaunay triangulation and 9-d convex hull of 70 points +in 15 seconds. It computes the +9-d Delaunay triangulation and 10-d convex hull of 50 points +in 17 seconds. The 10-d convex hull of 50 points has about 90,000 facets. + +<!-- duplicated in index.htm and html/index.htm --> +<p>Qhull does <i>not</i> support constrained Delaunay +triangulations, triangulation of non-convex surfaces, mesh +generation of non-convex objects, or medium-sized inputs in 9-D +and higher. </p> + +<p>This is a big package with many options. It is one of the +fastest available. It is the only 3-d code that handles precision +problems due to floating point arithmetic. For example, it +implements the identity function for extreme points (see <a +href="qh-impre.htm">Imprecision in Qhull</a>). </p> + +<p>[2016] A newly discovered, bad case for Qhull is multiple, nearly incident points within a 10^-13 ball of 3-d and higher +Delaunay triangulations (input sites in the unit cube). Nearly incident points within substantially +smaller or larger balls are OK. Error QH6271 is reported if a problem occurs. A future release of Qhull +will handle this case. For more information, see "Nearly coincident points on an edge" in <a href="../html/qh-impre.htm#limit">Limitations of merged facets</a> + +<p>If you need a short code for convex hull, Delaunay +triangulation, or Voronoi volumes consider Clarkson's <a +href="http://www.netlib.org/voronoi/hull.html">hull +program</a>. If you need 2-d Delaunay triangulations consider +Shewchuk's <a href="http://www.cs.cmu.edu/~quake/triangle.html">triangle +program</a>. It is much faster than Qhull and it allows +constraints. Both programs use exact arithmetic. They are in <a +href="http://www.netlib.org/voronoi/">http://www.netlib.org/voronoi/</a>. + +<p>If your input is in general position (i.e., no coplanar or colinear points), +<li><a href="https://github.com/tomilov/quickhull/blob/master/include/quickhull.hpp">Tomilov's quickhull.hpp</a> (<a href"http://habrahabr.ru/post/245221/"documentation-ru</a/>) +or Qhull <a +href="http://www.qhull.org/download">version +1.0</a> may meet your needs. Both programs detect precision problems, +but do not handle them.</p> + +<p><a href=http://www.cgal.org>CGAL</a> is a library of efficient and reliable +geometric algorithms. It uses C++ templates and the Boost library to produce dimension-specific +code. This allows more efficient use of memory than Qhull's general-dimension +code. CGAL simulates arbitrary precision while Qhull handles round-off error +with thick facets. Compare the two approaches with <a href="http://doc.cgal.org/latest/Manual/devman_robustness.html">Robustness Issues in CGAL</a>, +and <a href+"qh-impre.htm">Imprecision in Qhull</a>. + + +<p><a href=http://www.algorithmic-solutions.com/enleda.htm>Leda</a> is a +library for writing computational +geometry programs and other combinatorial algorithms. It +includes routines for computing 3-d convex +hulls, 2-d Delaunay triangulations, and 3-d Delaunay triangulations. +It provides rational arithmetic and graphical output. It runs on most +platforms. + +<p>If your problem is in high dimensions with a few, +non-simplicial facets, try Fukuda's <a +href="http://www.cs.mcgill.ca/~fukuda/soft/cdd_home/cdd.html">cdd</a>. +It is much faster than Qhull for these distributions. </p> + +<p>Custom software for 2-d and 3-d convex hulls may be faster +than Qhull. Custom software should use less memory. Qhull uses +general-dimension data structures and code. The data structures +support non-simplicial facets.</p> + +<p>Qhull is not suitable for mesh generation or triangulation of +arbitrary surfaces. You may use Qhull if the surface is convex or +completely visible from an interior point (e.g., a star-shaped +polyhedron). First, project each site to a sphere that is +centered at the interior point. Then, compute the convex hull of +the projected sites. The facets of the convex hull correspond to +a triangulation of the surface. For mesh generation of arbitrary +surfaces, see <a +href="http://www.robertschneiders.de/meshgeneration/meshgeneration.html">Schneiders' +Finite Element Mesh Generation</a>.</p> + +<p>Qhull is not suitable for constrained Delaunay triangulations. +With a lot of work, you can write a program that uses Qhull to +add constraints by adding additional points to the triangulation.</p> + +<p>Qhull is not suitable for the subdivision of arbitrary +objects. Use <tt>qdelaunay</tt> to subdivide a convex object.</p> + +</blockquote> +<h2><a href="#TOC">»</a><a name="description">Description of +Qhull </a></h2> +<blockquote> + +<h3><a href="#TOC">»</a><a name="definition">definition</a></h3> +<blockquote> + +<p>The <i>convex hull</i> of a point set <i>P</i> is the smallest +convex set that contains <i>P</i>. If <i>P</i> is finite, the +convex hull defines a matrix <i>A</i> and a vector <i>b</i> such +that for all <i>x</i> in <i>P</i>, <i>Ax+b <= [0,...]</i>. </p> + +<p>Qhull computes the convex hull in 2-d, 3-d, 4-d, and higher +dimensions. Qhull represents a convex hull as a list of facets. +Each facet has a set of vertices, a set of neighboring facets, +and a halfspace. A halfspace is defined by a unit normal and an +offset (i.e., a row of <i>A</i> and an element of <i>b</i>). </p> + +<p>Qhull accounts for round-off error. It returns +"thick" facets defined by two parallel hyperplanes. The +outer planes contain all input points. The inner planes exclude +all output vertices. See <a href="qh-impre.htm#imprecise">Imprecise +convex hulls</a>.</p> + +<p>Qhull may be used for the Delaunay triangulation or the +Voronoi diagram of a set of points. It may be used for the +intersection of halfspaces. </p> + +</blockquote> +<h3><a href="#TOC">»</a><a name="input">input format</a></h3> +<blockquote> + +<p>The input data on <tt>stdin</tt> consists of:</p> + +<ul> + <li>first line contains the dimension</li> + <li>second line contains the number of input points</li> + <li>remaining lines contain point coordinates</li> +</ul> + +<p>For example: </p> + +<pre> + 3 #sample 3-d input + 5 + 0.4 -0.5 1.0 + 1000 -1e-5 -100 + 0.3 0.2 0.1 + 1.0 1.0 1.0 + 0 0 0 +</pre> + +<p>Input may be entered by hand. End the input with a control-D +(^D) character. </p> + +<p>To input data from a file, use I/O redirection or '<a +href="qh-optt.htm#TI">TI file</a>'. The filename may not +include spaces or quotes.</p> + +<p>A comment starts with a non-numeric character and continues to +the end of line. The first comment is reported in summaries and +statistics. With multiple <tt>qhull</tt> commands, use option '<a +href="qh-optf.htm#FQ">FQ</a>' to place a comment in the output.</p> + +<p>The dimension and number of points can be reversed. Comments +and line breaks are ignored. Error reporting is better if there +is one point per line.</p> + +</blockquote> +<h3><a href="#TOC">»</a><a name="option">option format</a></h3> +<blockquote> + +<p>Use options to specify the output formats and control +Qhull. The <tt>qhull</tt> program takes all options. The +other programs use a subset of the options. They disallow +experimental and inappropriate options. + +<blockquote> +<ul> +<li> +qconvex == qhull +<li> +qdelaunay == qhull d Qbb +<li> +qhalf == qhull H +<li> +qvoronoi == qhull v Qbb +</ul> +</blockquote> + +<p>Single letters are used for output formats and precision +constants. The other options are grouped into menus for formats +('<a href="qh-optf.htm#format">F</a>'), Geomview ('<a +href="qh-optg.htm#geomview">G </a>'), printing ('<a +href="qh-optp.htm#print">P</a>'), Qhull control ('<a +href="qh-optq.htm#qhull">Q </a>'), and tracing ('<a +href="qh-optt.htm#trace">T</a>'). The menu options may be listed +together (e.g., 'GrD3' for 'Gr' and 'GD3'). Options may be in any +order. Capitalized options take a numeric argument (except for '<a +href="qh-optp.htm#PG">PG</a>' and '<a href="qh-optf.htm#format">F</a>' +options). Use option '<a href="qh-optf.htm#FO">FO</a>' to print +the selected options.</p> + +<p>Qhull uses zero-relative indexing. If there are <i>n</i> +points, the index of the first point is <i>0</i> and the index of +the last point is <i>n-1</i>.</p> + +<p>The default options are:</p> + +<ul> + <li>summary output ('<a href="qh-opto.htm#s">s</a>') </li> + <li>merged facets ('<a href="qh-optc.htm#C0">C-0</a>' in 2-d, + 3-d, 4-d; '<a href="qh-optq.htm#Qx">Qx</a>' in 5-d and + up)</li> +</ul> + +<p>Except for bounding box +('<a href="qh-optq.htm#Qbk">Qbk:n</a>', etc.), drop facets +('<a href="qh-optp.htm#Pdk">Pdk:n</a>', etc.), and +Qhull command ('<a href="qh-optf.htm#FQ">FQ</a>'), only the last +occurence of an option counts. +Bounding box and drop facets may be repeated for each dimension. +Option 'FQ' may be repeated any number of times. + +<p>The Unix <tt>tcsh</tt> and <tt>ksh </tt>shells make it easy to +try out different options. In Windows 95, use a command window with <tt>doskey</tt> +and a window scroller (e.g., <tt>peruse</tt>). </p> + +</blockquote> +<h3><a href="#TOC">»</a><a name="output">output format</a></h3> +<blockquote> + +<p>To write the results to a file, use I/O redirection or '<a +href="qh-optt.htm#TO">TO file</a>'. Windows 95 users should use +'TO file' or the console. If a filename is surrounded by single quotes, +it may include spaces. +</p> + +<p>The default output option is a short summary ('<a +href="qh-opto.htm#s">s</a>') to <tt>stdout</tt>. There are many +others (see <a href="qh-opto.htm">output</a> and <a +href="qh-optf.htm">formats</a>). You can list vertex incidences, +vertices and facets, vertex coordinates, or facet normals. You +can view Qhull objects with Geomview, Mathematica, or Maple. You can +print the internal data structures. You can call Qhull from your +application (see <a href="qh-code.htm#library">Qhull library</a>).</p> + +<p>For example, 'qhull <a href="qh-opto.htm#o">o</a>' lists the +vertices and facets of the convex hull. </p> + +<p>Error messages and additional summaries ('<a +href="qh-opto.htm#s">s</a>') go to <tt>stderr</tt>. Unless +redirected, <tt>stderr</tt> is the console.</p> + +</blockquote> +<h3><a href="#TOC">»</a><a name="algorithm">algorithm</a></h3> +<blockquote> + +<p>Qhull implements the Quickhull algorithm for convex hull +[Barber et al. <a href="#bar-dob96">'96</a>]. This algorithm +combines the 2-d Quickhull algorithm with the <em>n</em>-d +beneath-beyond algorithm [c.f., Preparata & Shamos <a +href="#pre-sha85">'85</a>]. It is similar to the randomized +algorithms of Clarkson and others [Clarkson & Shor <a +href="#cla-sho89">'89</a>; Clarkson et al. <a href="#cla-meh93">'93</a>; +Mulmuley <a href="#mulm94">'94</a>]. For a demonstration, see <a +href="qh-eg.htm#how">How Qhull adds a point</a>. The main +advantages of Quickhull are output sensitive performance (in +terms of the number of extreme points), reduced space +requirements, and floating-point error handling. </p> + +</blockquote> +<h3><a href="#TOC">»</a><a name="structure">data structures</a></h3> +<blockquote> + +<p>Qhull produces the following data structures for dimension <i>d</i>: +</p> + +<ul> + <li>A <em>coordinate</em> is a real number in floating point + format. </li> + <li>A <em>point</em> is an array of <i>d</i> coordinates. + With option '<a href="qh-optq.htm#QJn">QJ</a>', the + coordinates are joggled by a small amount. </li> + <li>A <em>vertex</em> is an input point. </li> + <li>A <em>hyperplane</em> is <i>d</i> normal coefficients and + an offset. The length of the normal is one. The + hyperplane defines a halfspace. If <i>V</i> is a normal, <i>b</i> + is an offset, and <i>x</i> is a point inside the convex + hull, then <i>Vx+b <0</i>.</li> + <li>An <em>outer plane</em> is a positive + offset from a hyperplane. When Qhull is done, all points + will be below all outer planes.</li> + <li>An <em>inner plane</em> is a negative + offset from a hyperplane. When Qhull is done, all + vertices will be above the corresponding inner planes.</li> + <li>An <em>orientation</em> is either 'top' or 'bottom'. It is the + topological equivalent of a hyperplane's geometric + orientation. </li> + <li>A <em>simplicial facet</em> is a set of + <i>d</i> neighboring facets, a set of <i>d</i> vertices, a + hyperplane equation, an inner plane, an outer plane, and + an orientation. For example in 3-d, a simplicial facet is + a triangle. </li> + <li>A <em>centrum</em> is a point on a facet's hyperplane. A + centrum is the average of a facet's vertices. Neighboring + facets are <em>convex</em> if each centrum is below the + neighbor facet's hyperplane. </li> + <li>A <em>ridge</em> is a set of <i>d-1</i> vertices, two + neighboring facets, and an orientation. For example in + 3-d, a ridge is a line segment. </li> + <li>A <em>non-simplicial facet</em> is a set of ridges, a + hyperplane equation, a centrum, an outer plane, and an + inner plane. The ridges determine a set of neighboring + facets, a set of vertices, and an orientation. Qhull + produces a non-simplicial facet when it merges two facets + together. For example, a cube has six non-simplicial + facets. </li> +</ul> + +<p>For examples, use option '<a href="qh-opto.htm#f">f</a>'. See <a +href="../src/libqhull/qh-poly.htm">polyhedron operations</a> for further +design documentation. </p> + +</blockquote> +<h3><a href="#TOC">»</a>Imprecision in Qhull</h3> +<blockquote> + +<p>See <a href="qh-impre.htm">Imprecision in Qhull</a> and <a href="qh-impre.htm#joggle">Merged facets or joggled input</a></p> + +</blockquote> +<h3><a href="#TOC">»</a>Examples of Qhull</h3> +<blockquote> + +<p>See <a href="qh-eg.htm">Examples of Qhull</a>. Most of these examples require <a href="#geomview">Geomview</a>. +Some of the examples have <a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/welcome.html">pictures +</a>.</p> + +</blockquote> +</blockquote> +<h2><a href="#TOC">»</a>Options for using Qhull </h2> +<blockquote> + +<p>See <a href="qh-quick.htm#options">Options</a>.</p> + +</blockquote> +<h2><a href="#TOC">»</a>Qhull internals </h2> +<blockquote> + +<p>See <a href="qh-code.htm">Internals</a>.</p> + +</blockquote> +<h2><a href="#TOC">»</a><a name="geomview">Geomview, Qhull's +graphical viewer</a></h2> +<blockquote> + +<p><a href="http://www.geomview.org">Geomview</a> +is an interactive geometry viewing program. +Geomview provides a good visualization of Qhull's 2-d and 3-d results. + +<p>Qhull includes <a href="qh-eg.htm">Examples of Qhull</a> that may be viewed with Geomview. + +<p>Geomview can help visulalize a 3-d Delaunay triangulation or the surface of a 4-d convex hull, +Use option '<a href="qh-optq.htm#QVn">QVn</a>' to select the 3-D facets adjacent to a vertex. + +<p>You may use Geomview to create movies that animate your objects (c.f., <a href="http://www.geomview.org/FAQ/answers.shtml#mpeg">How can I create a video animation?</a>). +Geomview helped create the <a href="http://www.geom.uiuc.edu/video/">mathematical videos</a> "Not Knot", "Outside In", and "The Shape of Space" from the Geometry Center. + + +<h3><a href="#TOC">»</a><a name="geomview-install">Installing Geomview</a></h3> +<blockquote> + +<p>Geomview is an <a href=http://sourceforge.net/projects/geomview>open source project</a> +under SourceForge. + +<p> +For build instructions see +<a href="http://www.geomview.org/download/">Downloading Geomview</a>. +Geomview builds under Linux, Unix, Macintosh OS X, and Windows. + +<p>Geomview has <a href="https://packages.debian.org/search?keywords=geomview">installable packages</a> for Debian and Ubuntu. +The OS X build needs Xcode, an X11 SDK, and Lesstif or Motif. +The Windows build uses Cygwin (see <a href="#geomview-win">Building Geomview</a> below for instructions). + +<p>If using Xforms (e.g., for Geomview's <a href="http://www.geomview.org/docs/html/Modules.html">External Modules</a>), install the 'libXpm-devel' package from cygwin and move the xforms directory into your geomview directory, e.g.,<br><tt>mv xforms-1.2.4 geomview-1.9.5/xforms</tt> + +<p>Geomview's <a href="http://www.geom.uiuc.edu/software/geomview/docs/NDview/manpagehelp.html">ndview<a/> provides multiple views into 4-d and higher objects. +This module is out-of-date (<a href="http://sourceforge.net/p/geomview/mailman/message/2004152/">geomview-users: 4dview</a>). +Download NDview-sgi.tar.Z at <a href="ftp://www.geom.uiuc.edu/pub/software/geomview/newpieces/sgi">newpieces</a> and 4dview at <a href="https://stuff.mit.edu/afs/sipb/project/3d/arch/sgi_62/lib/Geomview/modules/">Geomview/modules</a>. + +</blockquote> +<h3><a href="#TOC">»</a><a name="geomview-use">Using Geomview</a></h3> +<blockquote> + +<p>Use Geomview to view <a href="qh-eg.htm">Examples of Qhull</a>. You can spin the convex hull, fly a camera through its facets, +and see how Qhull produces thick facets in response to round-off error. + +<p>Follow these instructions to view 'eg,01.cube' from Examples of Qhull +<ol> +<li>Launch an XTerm command shell +<ul> +<li>If needed, start the X terminal server, Use 'xinit' or 'startx' in /usr/X11R6/bin<br><tt>xinit -- -multiwindow -clipboard</tt><br><tt>startx</tt> +<li>Start an XTerm command shell. In Windows, click the Cygwin/bash icon on your desktop. +<li>Set the DISPLAY variable, e.g.,<br><tt>export DISPLAY=:0</tt><br><tt>export DISPLAY=:0 >>~/.bashenv</tt> +</ul> +<li>Use Qhull's <a href="qh-optg.htm">Geomview options</a> to create a geomview object +<ul> +<li><tt>rbox c D3 | qconvex G >eg.01.cube</tt> +<li>On windows, convert the output to Unix text format with 'd2u'<br><tt>rbox c D3 | qconvex G | d2u >eg.01.cube</tt><br><tt>d2u eg.*</tt> +</ul> +<li>Run Geomview +<ul> +<li>Start Geomview with your example<br><tt>./geomview eg.01.cube</tt> +<li>Follow the instructions in <a href="http://www.geomview.org/docs/html/Tutorial.html">Gemoview Tutorial</a> +<li>Geomview creates the <i>Geomview control panel</i> with Targets and External Module, the <i>Geomview toolbar</i> with buttons for controlling Geomview, and the <i>Geomview camera window</i> showing a cube. +<li>Clear the camera window by selecting your object in the Targets list and 'Edit > Delete' or 'dd' +<li>Load the <i>Geomview files panel</i>. Select 'Open' in the 'File' menu. +<li>Set 'Filter' in the files panel to your example directory followed by '/*' (e.g., '/usr/local/qhull-2015.2/eg/*') +<li>Click 'Filter' in the files panel to view your examples in the 'Files' list. +<li>Load another example into the camera window by selecting it and clicking 'OK'. +<li>Review the instructions for <a href="http://www.geomview.org/docs/html/Interaction.html">Interacting with Geomview</a> +<li>When viewing multiple objects at once, you may want to turn off normalization. In the 'Inspect > Apperance' control panel, set 'Normalize' to 'None'. +</ul> +</ol> + +<p>Geomview defines GCL (a textual API for controlling Geomview) and OOGL (a textual file format for defining objects). +<ul> +<li>To control Geomview, you may use any program that reads and writes from stdin and stdout. For example, it could report Qhull's information about a vertex identified by a double-click 'pick' event. +<li><a href="http://www.geomview.org/docs/html/GCL.html">GCL</a> command language for controlling Geomview +<li><a href="http://www.geomview.org/docs/html/OOGL-File-Formats.html">OOGL</a> file format for defining objects (<a href="http://www.geomview.org/docs/oogltour.html">tutorial</a>). +<li><a href="http://www.geomview.org/docs/html/Modules.html">External Modules</a> for interacting with Geomview via GCL +<li>Interact with your objects via <a href="http://www.geomview.org/docs/html/pick.html">pick</a> commands in response to right-mouse double clicks. Enable pick events with the <a href="http://www.geomview.org/docs/html/interest.html">interest</a> command. +</ul> + +</blockquote> +<h3><a href="#TOC">»</a><a name="geomview-win">Building Geomview for Windows</a></h3> +<blockquote> + +<p>Compile Geomview under Cygwin. For detailed instructions, see +<a href="http://www.ee.surrey.ac.uk/Personal/L.Wood/software/SaVi/building-under-Windows/" +>Building Savi and Geomview under Windows</a>. These instructions are somewhat out-of-date. Updated +instructions follow. + +<p>How to compile Geomview under 32-bit Cygwin (October 2015)</p> +<ol> +<li><b>Note:</b> L. Wood has run into multiple issues with Geomview on Cygwin. He recommends Virtualbox/Ubuntu +and a one-click install of geomview via the Ubuntu package. See his Savi/Geomview link above. +<li>Install 32-bit <a href="http://cygwin.com/">Cygwin</a> as follows. +For additional guidance, see Cygwin's <a href="https://cygwin.com/install.html">Installing and Updating Cygwin Packages</a> +and <a href="http://www.qhull.org/road/road-faq/xml/cmdline.xml#setup-cygwin">Setup cygwin</a>. +<ul> +<li>Launch the cygwin installer. +<li>Select a mirror from <a href="http://cygwin.com/mirrors.html">Cygwin mirrors</a> (e.g., http://mirrors.kernel.org/sourceware/cygwin/ in California). +<li>Select the packages to install. Besides the cygwin packages listed in the Savi/Windows instructions consider adding +<ul> +<li><b>Default</b> -- libXm-devel (required for /usr/include/Xm/Xm.h) +<li><b>Devel</b> -- bashdb, gcc-core (in place of gcc), gdb +<li><b>Lib</b> -- libGL-devel, libGLU1 (required, obsolete), libGLU-devel (required, obsolete), libjpeg-devel(XForms), libXext-devel (required), libXpm-devel (Xforms) +libGL and lib +<li><b>Math</b> -- bc +<li><b>Net</b> -- autossh, inetutils, openssh +<li><b>System</b> -- chere +<li><b>Utils</b> -- dos2unix (required for qhull), keychain +<li>If installing perl, ActiveState Perl may be a better choice than cygwin's perl. Perl is not used by Geomview or Qhull. +<li><a href="https://cygwin.com/cgi-bin2/package-grep.cgi">Cygwin Package Search</a> -- Search for cygwin programs and packages +</ul> +<li>Click 'Next' to download and install the packages. +<li>If the download is incomplete, try again. +<li>If you try again after a successful install, cygwin will uninstall and reinstall all modules.. +<li>Click on the 'Cywin Terminal' icon on the Desktop. It sets up a user directory in /home from /etc/skel/... +<li>Mount your disk drives<br>mount c: /c # Ignore the warning /c does not exist +</ul> +<li>Consider installing the <a href="http://www.qhull.org/bash/doc/road-bash.html">Road Bash</a> scripts (/etc/road-*) from <a href="http://www.qhull.org/road/">Road</a>. +They define aliases and functions for Unix command shells (Unix, Linux, Mac OS X, Windows), +<ul> +<li>Download Road Bash and unzip the downloaded file +<li>Copy .../bash/etc/road-* to the Cywin /etc directory (by default, C:\cygwin\etc). +<li>Using the cygwin terminal, convert the road scripts to Unix format<br>d2u /etc/road-* +<li>Try it<br>source /etc/road-home.bashrc +<li>Install it<br>cp /etc/road-home.bashrc ~/.bashrc +</ul> +<li>Launch the X terminal server from '<tt>Start > All programs > Cygwin-X > Xwin Server</tt>'. Alternatively, run 'startx' +<li>Launch an XTerm shell +<ul> +<li>Right click the Cywin icon on the system tray in the Windows taskbar. +<li>Select '<tt>System Tools > XTerm</tt>' +</ul> +<li>Download and extract Geomview -- <a href="http://www.geomview.org/download/">Downloading Geomview</a> +<li>Compile Geomview +<ul> +<li>./configure +<li>make +</ul> +<li>If './configure' fails, check 'config.log' at the failing step. Look carefully for missing libraries, etc. The <a href="http://www.geomview.org/FAQ/answers.shtml">Geomview FAQ</a> contains suggestions (e.g., "configure claims it can't find OpenGl"). +<li>If 'make' fails, read the output carefully for error messages. Usually it is a missing include file or package. Locate and install the missing cygwin packages +(<a href="https://cygwin.com/cgi-bin2/package-grep.cgi">Cygwin Package Search</a>). +</ol> + +</blockquote> +</blockquote> +<h2><a href="#TOC">»</a><a name="bugs">What to do if something +goes wrong</a></h2> +<blockquote> + +<p>Please report bugs to <a href=mailto:qhull_bug@qhull.org>qhull_bug@qhull.org</a> +</a>. Please report if Qhull crashes. Please report if Qhull +generates an "internal error". Please report if Qhull +produces a poor approximate hull in 2-d, 3-d or 4-d. Please +report documentation errors. Please report missing or incorrect +links.</p> + +<p>If you do not understand something, try a small example. The <a +href="rbox.htm">rbox</a> program is an easy way to generate +test cases. The <a href="#geomview">Geomview</a> program helps to +visualize the output from Qhull.</p> + +<p>If Qhull does not compile, it is due to an incompatibility +between your system and ours. The first thing to check is that +your compiler is ANSI standard. Qhull produces a compiler error +if __STDC__ is not defined. You may need to set a flag (e.g., +'-A' or '-ansi').</p> + +<p>If Qhull compiles but crashes on the test case (rbox D4), +there's still incompatibility between your system and ours. +Sometimes it is due to memory management. This can be turned off +with qh_NOmem in mem.h. Please let us know if you figure out how +to fix these problems. </p> + +<p>If you doubt the output from Qhull, add option '<a +href="qh-optt.htm#Tv">Tv</a>'. It checks that every point is +inside the outer planes of the convex hull. It checks that every +facet is convex with its neighbors. It checks the topology of the +convex hull.</p> + +<p>Qhull should work on all inputs. It may report precision +errors if you turn off merged facets with option '<a +href="qh-optq.htm#Q0">Q0</a>'. This can get as bad as facets with +flipped orientation or two facets with the same vertices. You'll +get a long help message if you run into such a case. They are +easy to generate with <tt>rbox</tt>.</p> + +<p>If you do find a problem, try to simplify it before reporting +the error. Try different size inputs to locate the smallest one +that causes an error. You're welcome to hunt through the code +using the execution trace ('<a href="qh-optt.htm#Tn">T4</a>') as +a guide. This is especially true if you're incorporating Qhull +into your own program. </p> + +<p>When you report an error, please attach a data set to the end +of your message. Include the options that you used with Qhull, +the results of option '<a href="qh-optf.htm#FO">FO</a>', and any +messages generated by Qhull. This allows me to see the error for +myself. Qhull is maintained part-time. </p> + +</blockquote> +<h2><a href="#TOC">»</a><a name="email">Email</a></h2> +<blockquote> + +<p>Please send correspondence to Brad Barber at <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +and report bugs to <a href=mailto:qhull_bug@qhull.org>qhull_bug@qhull.org</a> +</a>. Let me know how you use Qhull. If you mention it in a +paper, please send a reference and abstract.</p> + +<p>If you would like to get Qhull announcements (e.g., a new +version) and news (any bugs that get fixed, etc.), let us know +and we will add you to our mailing list. For Internet news about geometric algorithms +and convex hulls, look at comp.graphics.algorithms and +sci.math.num-analysis. For Qhull news look at <a +href="http://www.qhull.org/news">qhull-news.html</a>.</p> + +</blockquote> +<h2><a href="#TOC">»</a><a name="authors">Authors</a></h2> +<blockquote> + +<pre> + C. Bradford Barber Hannu Huhdanpaa + bradb@shore.net hannu@qhull.org +</pre> + +</blockquote> +<h2><a href="#TOC">»</a><a name="acknowledge">Acknowledgments</a></h2> +<blockquote> + +<p>A special thanks to David Dobkin for his guidance. A special +thanks to Albert Marden, Victor Milenkovic, the Geometry Center, +and Harvard University for supporting this work.</p> + +<p>A special thanks to Mark Phillips, Robert Miner, and Stuart Levy for running the Geometry + Center web site long after the Geometry Center closed. + Stuart moved the web site to the University of Illinois at Champaign-Urbana. +Mark and Robert are founders of <a href=http://www.geomtech.com>Geometry Technologies</a>. +Mark, Stuart, and Tamara Munzner are the original authors of <a href=http://www.geomview.org>Geomview</a>. + +<p>A special thanks to <a href="http://www.endocardial.com/">Endocardial +Solutions, Inc.</a> of St. Paul, Minnesota for their support of the +internal documentation (<a href=../src/libqhull/index.htm>src/libqhull/index.htm</a>). They use Qhull to build 3-d models of +heart chambers.</p> + +<p>Qhull 1.0 and 2.0 were developed under National Science Foundation +grants NSF/DMS-8920161 and NSF-CCR-91-15793 750-7504. If you find +it useful, please let us know.</p> + +<p>The Geometry Center was supported by grant DMS-8920161 from the +National Science Foundation, by grant DOE/DE-FG02-92ER25137 from +the Department of Energy, by the University of Minnesota, and by +Minnesota Technology, Inc.</p> + +</blockquote> +<h2><a href="#TOC">»</a><a name="ref">References</a></h2> +<blockquote> + +<p><a name="aure91">Aurenhammer</a>, F., "Voronoi diagrams +-- A survey of a fundamental geometric data structure," <i>ACM +Computing Surveys</i>, 1991, 23:345-405. </p> + +<p><a name="bar-dob96">Barber</a>, C. B., D.P. Dobkin, and H.T. +Huhdanpaa, "The Quickhull Algorithm for Convex Hulls," <i>ACM +Transactions on Mathematical Software</i>, 22(4):469-483, Dec 1996, www.qhull.org +[<a +href="http://portal.acm.org/citation.cfm?doid=235815.235821">http://portal.acm.org</a>; +<a href="http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.117.405">http://citeseerx.ist.psu.edu</a>]. +</p> + +<p><a name="cla-sho89">Clarkson</a>, K.L. and P.W. Shor, +"Applications of random sampling in computational geometry, +II", <i>Discrete Computational Geometry</i>, 4:387-421, 1989</p> + +<p><a name="cla-meh93">Clarkson</a>, K.L., K. Mehlhorn, and R. +Seidel, "Four results on randomized incremental +construction," <em>Computational Geometry: Theory and +Applications</em>, vol. 3, p. 185-211, 1993.</p> + +<p><a name="devi01">Devillers</a>, et. al., +"Walking in a triangulation," <i>ACM Symposium on +Computational Geometry</i>, June 3-5,2001, Medford MA. + +<p><a name="dob-kir90">Dobkin</a>, D.P. and D.G. Kirkpatrick, +"Determining the separation of preprocessed polyhedra--a +unified approach," in <i>Proc. 17th Inter. Colloq. Automata +Lang. Program.</i>, in <i>Lecture Notes in Computer Science</i>, +Springer-Verlag, 443:400-413, 1990. </p> + +<p><a name="edel01">Edelsbrunner</a>, H, <i>Geometry and Topology for Mesh Generation</i>, +Cambridge University Press, 2001. + +<p><a name=gart99>Gartner, B.</a>, "Fast and robust smallest enclosing balls", <i>Algorithms - ESA '99</i>, LNCS 1643. + +<p><a name=golub83>Golub, G.H. and van Loan, C.F.</a>, <i>Matric Computations</i>, Baltimore, Maryland, USA: John Hopkins Press, 1983 + +<p><a name="fort93">Fortune, S.</a>, "Computational +geometry," in R. Martin, editor, <i>Directions in Geometric +Computation</i>, Information Geometers, 47 Stockers Avenue, +Winchester, SO22 5LB, UK, ISBN 1-874728-02-X, 1993.</p> + +<p><a name="mile93">Milenkovic, V.</a>, "Robust polygon +modeling," Computer-Aided Design, vol. 25, p. 546-566, +September 1993. </p> + +<p><a name="muck96">Mucke</a>, E.P., I. Saias, B. Zhu, <i>Fast +randomized point location without preprocessing in Two- and +Three-dimensional Delaunay Triangulations</i>, ACM Symposium on +Computational Geometry, p. 274-283, 1996 [<a +href="http://www.geom.uiuc.edu/software/cglist/GeomDir/">GeomDir</a>]. +</p> + +<p><a name="mulm94">Mulmuley</a>, K., <i>Computational Geometry, +An Introduction Through Randomized Algorithms</i>, Prentice-Hall, +NJ, 1994.</p> + +<p><a name="orou94">O'Rourke</a>, J., <i>Computational Geometry +in C</i>, Cambridge University Press, 1994.</p> + +<p><a name="pre-sha85">Preparata</a>, F. and M. Shamos, <i>Computational +Geometry</i>, Springer-Verlag, New York, 1985.</p> + +</blockquote> +<!-- Navigation links --> +<hr> + +<p><b>Up:</b> <a +href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b><a +href="http://www.qhull.org/news">News</a> about Qhull<br> +<b>Up:</b> <a href="http://www.qhull.org/html/qh-faq.htm">FAQ</a> about Qhull<br> +<b>To:</b> <a href="#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>Dn:</b> <a href="qh-impre.htm">Imprecision in Qhull</a><br> +<b>Dn:</b> <a href="qh-eg.htm">Description of Qhull examples</a><br> +<b>Dn:</b> <a href="qh-code.htm">Qhull internals</a><br> +<b>Dn:</b> <a href="../src/libqhull/index.htm">Qhull functions, macros, and data +structures</a> +<!-- GC common information --> +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="qh--geom.gif" +align="middle" width="40" height="40"></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: Sept. 25, 1995 --- <!-- hhmts start --> Last modified: see top <!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/normal_voronoi_knauss_oesterle.jpg b/xs/src/qhull/html/normal_voronoi_knauss_oesterle.jpg Binary files differnew file mode 100644 index 000000000..f46d42127 --- /dev/null +++ b/xs/src/qhull/html/normal_voronoi_knauss_oesterle.jpg diff --git a/xs/src/qhull/html/qconvex.htm b/xs/src/qhull/html/qconvex.htm new file mode 100644 index 000000000..38a363b08 --- /dev/null +++ b/xs/src/qhull/html/qconvex.htm @@ -0,0 +1,630 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<title>qconvex -- convex hull</title> +</head> + +<body> +<!-- Navigation links --> +<a name="TOP"><b>Up</b></a><b>:</b> +<a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a> -- Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#synopsis">sy</a>nopsis +• <a href="#input">in</a>put • <a href="#outputs">ou</a>tputs +• <a href="#controls">co</a>ntrols • <a href="#graphics">gr</a>aphics +• <a href="#notes">no</a>tes • <a href="#conventions">co</a>nventions +• <a href="#options">op</a>tions +<hr> +<!-- Main text of document --> +<h1><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/cone.html"><img +src="qh--cone.gif" alt="[cone]" align="middle" width="100" +height="100"></a>qconvex -- convex hull</h1> + +<p>The convex hull of a set of points is the smallest convex set +containing the points. See the detailed introduction by O'Rourke +[<a href="index.htm#orou94">'94</a>]. See <a +href="index.htm#description">Description of Qhull</a> and <a +href="qh-eg.htm#how">How Qhull adds a point</a>.</p> + +<blockquote> +<dl> + <dt><b>Example:</b> rbox 10 D3 | qconvex <a + href="qh-opto.htm#s">s</a> <a href="qh-opto.htm#o">o</a> <a + href="qh-optt.htm#TO">TO result</a></dt> + <dd>Compute the 3-d convex hull of 10 random points. Write a + summary to the console and the points and facets to + 'result'.</dd> + + <dt> </dt> + <dt><b>Example:</b> rbox c | qconvex <a + href="qh-opto.htm#n">n</a></dt> + <dd>Print the normals for each facet of a cube.</dd> + <dt> </dt> + <dt><b>Example:</b> rbox c | qconvex <a + href="qh-opto.htm#i">i</a> <a href="qh-optq.htm#Qt">Qt</a></dt> + <dd>Print the triangulated facets of a cube.</dd> + <dt> </dt> + <dt><b>Example:</b> rbox y 500 W0 | qconvex</dt> + <dd>Compute the convex hull of a simplex with 500 + points on its surface.</dd> + <dt> </dt> + <dt><b>Example:</b> rbox x W1e-12 1000 | qconvex + <a href="qh-optq.htm#QR">QR0</a></dt> + <dd>Compute the convex hull of 1000 points near the + surface of a randomly rotated simplex. Report + the maximum thickness of a facet.</dd> + <dt> </dt> + <dt><b>Example:</b> rbox 1000 s | qconvex <a + href="qh-opto.htm#s">s</a> <a + href="qh-optf.htm#FA">FA</a> </dt> + <dd>Compute the convex hull of 1000 cospherical + points. Verify the results and print a summary + with the total area and volume.</dd> + <dt> </dt> + <dt><b>Example:</b> rbox d D12 | qconvex <a + href="qh-optq.htm#QRn">QR0</a> <a + href="qh-optf.htm#FA">FA</a></dt> + <dd>Compute the convex hull of a 12-d diamond. + Randomly rotate the input. Note the large number + of facets and the small volume.</dd> + <dt> </dt> + <dt><b>Example:</b> rbox c D7 | qconvex <a + href="qh-optf.htm#FA">FA</a> <a + href="qh-optt.htm#TFn">TF1000</a></dt> + <dd>Compute the convex hull of the 7-d hypercube. + Report on progress every 1000 facets. Computing + the convex hull of the 9-d hypercube takes too + much time and space. </dd> + <dt> </dt> + <dt><b>Example:</b> rbox c d D2 | qconvex <a + href="qh-optq.htm#Qc">Qc</a> <a + href="qh-opto.htm#s">s</a> <a + href="qh-opto.htm#f">f</a> <a + href="qh-optf.htm#Fx">Fx</a> | more</dt> + <dd>Dump all fields of all facets for a square and a + diamond. Also print a summary and a list of + vertices. Note the coplanar points.</dd> + <dt> </dt> +</dl> +</blockquote> + +<p>Except for rbox, all of the qhull programs compute a convex hull. + +<p>By default, Qhull merges coplanar facets. For example, the convex +hull of a cube's vertices has six facets. + +<p>If you use '<a href="qh-optq.htm#Qt">Qt</a>' (triangulated output), +all facets will be simplicial (e.g., triangles in 2-d). For the cube +example, it will have 12 facets. Some facets may be +degenerate and have zero area. + +<p>If you use '<a href="qh-optq.htm#QJn">QJ</a>' (joggled input), +all facets will be simplicial. The corresponding vertices will be +slightly perturbed and identical points will be joggled apart. +Joggled input is less accurate that triangulated +output.See <a +href="qh-impre.htm#joggle">Merged facets or joggled input</a>. </p> + +<p>The output for 4-d convex hulls may be confusing if the convex +hull contains non-simplicial facets (e.g., a hypercube). See +<a href=qh-faq.htm#extra>Why +are there extra points in a 4-d or higher convex hull?</a><br> +</p> +</p> + +<p>The 'qconvex' program is equivalent to +'<a href=qhull.htm#outputs>qhull</a>' in 2-d to 4-d, and +'<a href=qhull.htm#outputs>qhull</a> <a href=qh-optq.htm#Qx>Qx</a>' +in 5-d and higher. It disables the following Qhull +<a href=qh-quick.htm#options>options</a>: <i>d v H Qbb Qf Qg Qm +Qr Qu Qv Qx Qz TR E V Fp Gt Q0,etc</i>. + +<p><b>Copyright © 1995-2015 C.B. Barber</b></p> + +<hr> + +<h3><a href="#TOP">»</a><a name="synopsis">qconvex synopsis</a></h3> +<pre> +qconvex- compute the convex hull. + input (stdin): dimension, number of points, point coordinates + comments start with a non-numeric character + +options (qconvex.htm): + Qt - triangulated output + QJ - joggle input instead of merging facets + Tv - verify result: structure, convexity, and point inclusion + . - concise list of all options + - - one-line description of all options + +output options (subset): + s - summary of results (default) + i - vertices incident to each facet + n - normals with offsets + p - vertex coordinates (includes coplanar points if 'Qc') + Fx - extreme points (convex hull vertices) + FA - compute total area and volume + o - OFF format (dim, n, points, facets) + G - Geomview output (2-d, 3-d, and 4-d) + m - Mathematica output (2-d and 3-d) + QVn - print facets that include point n, -n if not + TO file- output results to file, may be enclosed in single quotes + +examples: + rbox c D2 | qconvex s n rbox c D2 | qconvex i + rbox c D2 | qconvex o rbox 1000 s | qconvex s Tv FA + rbox c d D2 | qconvex s Qc Fx rbox y 1000 W0 | qconvex s n + rbox y 1000 W0 | qconvex s QJ rbox d G1 D12 | qconvex QR0 FA Pp + rbox c D7 | qconvex FA TF1000 +</pre> + +<h3><a href="#TOP">»</a><a name="input">qconvex +input</a></h3> +<blockquote> + +<p>The input data on <tt>stdin</tt> consists of:</p> +<ul> + <li>dimension + <li>number of points</li> + <li>point coordinates</li> +</ul> + +<p>Use I/O redirection (e.g., qconvex < data.txt), a pipe (e.g., rbox 10 | qconvex), +or the '<a href=qh-optt.htm#TI>TI</a>' option (e.g., qconvex TI data.txt). + +<p>Comments start with a non-numeric character. Error reporting is +simpler if there is one point per line. Dimension +and number of points may be reversed. + +<p>Here is the input for computing the convex +hull of the unit cube. The output is the normals, one +per facet.</p> + +<blockquote> + <p>rbox c > data </p> + <pre> +3 RBOX c +8 + -0.5 -0.5 -0.5 + -0.5 -0.5 0.5 + -0.5 0.5 -0.5 + -0.5 0.5 0.5 + 0.5 -0.5 -0.5 + 0.5 -0.5 0.5 + 0.5 0.5 -0.5 + 0.5 0.5 0.5 +</pre> + <p>qconvex s n < data</p> + <pre> + +Convex hull of 8 points in 3-d: + + Number of vertices: 8 + Number of facets: 6 + Number of non-simplicial facets: 6 + +Statistics for: RBOX c | QCONVEX s n + + Number of points processed: 8 + Number of hyperplanes created: 11 + Number of distance tests for qhull: 35 + Number of merged facets: 6 + Number of distance tests for merging: 84 + CPU seconds to compute hull (after input): 0.081 + +4 +6 + 0 0 -1 -0.5 + 0 -1 0 -0.5 + 1 0 0 -0.5 + -1 0 0 -0.5 + 0 1 0 -0.5 + 0 0 1 -0.5 +</pre> +</blockquote> + +</blockquote> +<h3><a href="#TOP">»</a><a name="outputs">qconvex outputs</a></h3> +<blockquote> + +<p>These options control the output of qconvex. They may be used +individually or together.</p> +<blockquote> +<dl compact> + <dt> </dt> + <dd><b>Vertices</b></dd> + <dt><a href="qh-optf.htm#Fx">Fx</a></dt> + <dd>list extreme points (i.e., vertices). The first line is the number of + extreme points. Each point is listed, one per line. The cube example + has eight vertices.</dd> + <dt><a href="qh-optf.htm#Fv">Fv</a></dt> + <dd>list vertices for each facet. The first line is the number of facets. + Each remaining line starts with the number of vertices. For the cube example, + each facet has four vertices.</dd> + <dt><a href="qh-opto.htm#i">i</a></dt> + <dd>list vertices for each facet. The first line is the number of facets. The + remaining lines list the vertices for each facet. In 4-d and + higher, triangulate non-simplicial facets by adding an extra point.</dd> + <dt> </dt> + <dt> </dt> + <dd><b>Coordinates</b></dd> + <dt><a href="qh-opto.htm#o">o</a></dt> + <dd>print vertices and facets of the convex hull in OFF format. The + first line is the dimension. The second line is the number of + vertices, facets, and ridges. The vertex + coordinates are next, followed by the facets. Each facet starts with + the number of vertices. The cube example has four vertices per facet.</dd> + <dt><a href="qh-optf.htm#Ft">Ft</a></dt> + <dd>print a triangulation of the convex hull in OFF format. The first line + is the dimension. The second line is the number of vertices and added points, + followed by the number of facets and the number of ridges. + The vertex coordinates are next, followed by the centrum coordinates. There is + one centrum for each non-simplicial facet. + The cube example has six centrums, one per square. + Each facet starts with the number of vertices or centrums. + In the cube example, each facet uses two vertices and one centrum.</dd> + <dt><a href="qh-opto.htm#p">p</a></dt> + <dd>print vertex coordinates. The first line is the dimension and the second + line is the number of vertices. The following lines are the coordinates of each + vertex. The cube example has eight vertices.</dd> + <dt><a href="qh-optq.htm#Qc">Qc</a> <a href="qh-opto.htm#p">p</a></dt> + <dd>print coordinates of vertices and coplanar points. The first line is the dimension. + The second line is the number of vertices and coplanar points. The coordinates + are next, one line per point. Use '<a href="qh-optq.htm#Qc">Qc</a> <a href="qh-optq.htm#Qi">Qi</a> p' + to print the coordinates of all points.</dd> + <dt> </dt> + <dt> </dt> + <dd><b>Facets</b></dd> + <dt><a href="qh-optf.htm#Fn">Fn</a></dt> + <dd>list neighboring facets for each facet. The first line is the + number of facets. Each remaining line starts with the number of + neighboring facets. The cube example has four neighbors per facet.</dd> + <dt><a href="qh-optf.htm#FN">FN</a></dt> + <dd>list neighboring facets for each point. The first line is the + total number of points. Each remaining line starts with the number of + neighboring facets. Each vertex of the cube example has three neighboring + facets. Use '<a href="qh-optq.htm#Qc">Qc</a> <a href="qh-optq.htm#Qi">Qi</a> FN' + to include coplanar and interior points. </dd> + <dt><a href="qh-optf.htm#Fa">Fa</a></dt> + <dd>print area for each facet. The first line is the number of facets. + Facet area follows, one line per facet. For the cube example, each facet has area one.</dd> + <dt><a href="qh-optf.htm#FI">FI</a></dt> + <dd>list facet IDs. The first line is the number of + facets. The IDs follow, one per line.</dd> + + <dt> </dt> + <dt> </dt> + <dd><b>Coplanar and interior points</b></dd> + <dt><a href="qh-optf.htm#Fc">Fc</a></dt> + <dd>list coplanar points for each facet. The first line is the number + of facets. The remaining lines start with the number of coplanar points. + A coplanar point is assigned to one facet.</dd> + <dt><a href="qh-optq.htm#Qi">Qi</a> <a href="qh-optf.htm#Fc">Fc</a></dt> + <dd>list interior points for each facet. The first line is the number + of facets. The remaining lines start with the number of interior points. + A coplanar point is assigned to one facet.</dd> + <dt><a href="qh-optf.htm#FP">FP</a></dt> + <dd>print distance to nearest vertex for coplanar points. The first line is the + number of coplanar points. Each remaining line starts with the point ID of + a vertex, followed by the point ID of a coplanar point, its facet, and distance. + Use '<a href="qh-optq.htm#Qc">Qc</a> <a href="qh-optq.htm#Qi">Qi</a> + <a href="qh-optf.htm#FP">FP</a>' for coplanar and interior points.</dd> + + <dt> </dt> + <dt> </dt> + <dd><b>Hyperplanes</b></dd> + <dt><a href="qh-opto.htm#n">n</a></dt> + <dd>print hyperplane for each facet. The first line is the dimension. The + second line is the number of facets. Each remaining line is the hyperplane's + coefficients followed by its offset.</dd> + <dt><a href="qh-optf.htm#Fo">Fo</a></dt> + <dd>print outer plane for each facet. The output plane is above all points. + The first line is the dimension. The + second line is the number of facets. Each remaining line is the outer plane's + coefficients followed by its offset.</dd> + <dt><a href="qh-optf.htm#Fi">Fi</a></dt> + <dd>print inner plane for each facet. The inner plane of a facet is + below its vertices. + The first line is the dimension. The + second line is the number of facets. Each remaining line is the inner plane's + coefficients followed by its offset.</dd> + + <dt> </dt> + <dt> </dt> + <dd><b>General</b></dd> + <dt><a href="qh-opto.htm#s">s</a></dt> + <dd>print summary for the convex hull. Use '<a + href="qh-optf.htm#Fs">Fs</a>' and '<a + href="qh-optf.htm#FS">FS</a>' if you need numeric data.</dd> + <dt><a href="qh-optf.htm#FA">FA</a></dt> + <dd>compute total area and volume for '<a + href="qh-opto.htm#s">s</a>' and '<a href="qh-optf.htm#FS">FS</a>'</dd> + <dt><a href="qh-opto.htm#m">m</a></dt> + <dd>Mathematica output for the convex hull in 2-d or 3-d.</dd> + <dt><a href="qh-optf.htm#FM">FM</a></dt> + <dd>Maple output for the convex hull in 2-d or 3-d.</dd> + <dt><a href="qh-optg.htm#G">G</a></dt> + <dd>Geomview output for the convex hull in 2-d, 3-d, or 4-d.</dd> + + <dt> </dt> + <dt> </dt> + <dd><b>Scaling and rotation</b></dd> + <dt><a href="qh-optq.htm#Qbk">Qbk:n</a></dt> + <dd>scale k'th coordinate to lower bound.</dd> + <dt><a href="qh-optq.htm#QBk">QBk:n</a></dt> + <dd>scale k'th coordinate to upper bound.</dd> + <dt><a href="qh-optq.htm#QbB">QbB</a></dt> + <dd>scale input to unit cube centered at the origin.</dd> + <dt><a href="qh-optq.htm#QRn">QRn</a></dt> + <dd>randomly rotate the input with a random seed of n. If n=0, the + seed is the time. If n=-1, use time for the random seed, but do + not rotate the input.</dd> + <dt><a href="qh-optq.htm#Qb0">Qbk:0Bk:0</a></dt> + <dd>remove k'th coordinate from input. This computes the + convex hull in one lower dimension.</dd> +</dl> +</blockquote> + +</blockquote> +<h3><a href="#TOP">»</a><a name="controls">qconvex controls</a></h3> +<blockquote> + +<p>These options provide additional control:</p> + +<blockquote> +<dl compact> + <dt><a href="qh-optq.htm#Qt">Qt</a></dt> + <dd>triangulated output. Qhull triangulates non-simplicial facets. It may produce + degenerate facets of zero area.</dd> + <dt><a href="qh-optq.htm#QJn">QJ</a></dt> + <dd>joggle the input instead of merging facets. This guarantees simplicial facets + (e.g., triangles in 3-d). It is less accurate than triangulated output ('Qt').</dd> + <dt><a href="qh-optq.htm#Qc">Qc</a></dt> + <dd>keep coplanar points</dd> + <dt><a href="qh-optq.htm#Qi">Qi</a></dt> + <dd>keep interior points</dd> + <dt><a href="qh-opto.htm#f">f </a></dt> + <dd>facet dump. Print the data structure for each facet.</dd> + <dt><a href="qh-optq.htm#QVn">QVn</a></dt> + <dd>select facets containing point <em>n</em> as a vertex,</dd> + <dt><a href="qh-optq.htm#QGn">QGn</a></dt> + <dd>select facets that are visible from point <em>n</em> + (marked 'good'). Use <em>-n</em> for the remainder.</dd> + <dt><a href="qh-optp.htm#PDk">PDk:0</a></dt> + <dd>select facets with a negative coordinate for dimension <i>k</i></dd> + <dt><a href="qh-optt.htm#TFn">TFn</a></dt> + <dd>report progress after constructing <em>n</em> facets</dd> + <dt><a href="qh-optt.htm#Tv">Tv</a></dt> + <dd>verify result</dd> + <dt><a href="qh-optt.htm#TO">TI file</a></dt> + <dd>input data from file. The filename may not use spaces or quotes.</dd> + <dt><a href="qh-optt.htm#TO">TO file</a></dt> + <dd>output results to file. Use single quotes if the filename + contains spaces (e.g., <tt>TO 'file with spaces.txt'</tt></dd> + <dt><a href="qh-optq.htm#Qs">Qs</a></dt> + <dd>search all points for the initial simplex. If Qhull can + not construct an initial simplex, it reports a +descriptive message. Usually, the point set is degenerate and one +or more dimensions should be removed ('<a href="qh-optq.htm#Qb0">Qbk:0Bk:0</a>'). +If not, use option 'Qs'. It performs an exhaustive search for the +best initial simplex. This is expensive is high dimensions.</dd> +</dl> +</blockquote> + +</blockquote> +<h3><a href="#TOP">»</a><a name="graphics">qconvex graphics</a></h3> +<blockquote> + +<p>Display 2-d, 3-d, and 4-d convex hulls with Geomview ('<a +href="qh-optg.htm#G">G</a>').</p> + +<p>Display 2-d and 3-d convex hulls with Mathematica ('<a +href="qh-opto.htm#m">m</a>').</p> + +<p>To view 4-d convex hulls in 3-d, use '<a +href="qh-optp.htm#Pdk">Pd0d1d2d3</a>' to select the positive +octant and '<a href="qh-optg.htm#GDn">GrD2</a>' to drop dimension +2. </p> + +</blockquote> +<h3><a href="#TOP">»</a><a name="notes">qconvex notes</a></h3> +<blockquote> + +<p>Qhull always computes a convex hull. The +convex hull may be used for other geometric structures. The +general technique is to transform the structure into an +equivalent convex hull problem. For example, the Delaunay +triangulation is equivalent to the convex hull of the input sites +after lifting the points to a paraboloid.</p> + +</blockquote> +<h3><a href="#TOP">»</a><a name="conventions">qconvex +conventions</a></h3> +<blockquote> + +<p>The following terminology is used for convex hulls in Qhull. +See <a href="index.htm#structure">Qhull's data structures</a>.</p> + +<ul> + <li><em>point</em> - <em>d</em> coordinates</li> + <li><em>vertex</em> - extreme point of the input set</li> + <li><em>ridge</em> - <i>d-1</i> vertices between two + neighboring facets</li> + <li><em>hyperplane</em> - halfspace defined by a unit normal + and offset</li> + <li><em>coplanar point</em> - a nearly incident point to a + hyperplane</li> + <li><em>centrum</em> - a point on the hyperplane for testing + convexity</li> + <li><em>facet</em> - a facet with vertices, ridges, coplanar + points, neighboring facets, and hyperplane</li> + <li><em>simplicial facet</em> - a facet with <em>d</em> + vertices, <em>d</em> ridges, and <em>d</em> neighbors</li> + <li><em>non-simplicial facet</em> - a facet with more than <em>d</em> + vertices</li> + <li><em>good facet</em> - a facet selected by '<a + href="qh-optq.htm#QVn">QVn</a>', etc.</li> +</ul> +</blockquote> +<h3><a href="#TOP">»</a><a name="options">qconvex options</a></h3> + +<pre> +qconvex- compute the convex hull + http://www.qhull.org + +input (stdin): + first lines: dimension and number of points (or vice-versa). + other lines: point coordinates, best if one point per line + comments: start with a non-numeric character + +options: + Qt - triangulated output + QJ - joggle input instead of merging facets + Qc - keep coplanar points with nearest facet + Qi - keep interior points with nearest facet + +Qhull control options: + Qbk:n - scale coord k so that low bound is n + QBk:n - scale coord k so that upper bound is n (QBk is 0.5) + QbB - scale input to unit cube centered at the origin + Qbk:0Bk:0 - remove k-th coordinate from input + QJn - randomly joggle input in range [-n,n] + QRn - random rotation (n=seed, n=0 time, n=-1 time/no rotate) + Qs - search all points for the initial simplex + QGn - good facet if visible from point n, -n for not visible + QVn - good facet if it includes point n, -n if not + +Trace options: + T4 - trace at level n, 4=all, 5=mem/gauss, -1= events + Tc - check frequently during execution + Ts - print statistics + Tv - verify result: structure, convexity, and point inclusion + Tz - send all output to stdout + TFn - report summary when n or more facets created + TI file - input data from file, no spaces or single quotes + TO file - output results to file, may be enclosed in single quotes + TPn - turn on tracing when point n added to hull + TMn - turn on tracing at merge n + TWn - trace merge facets when width > n + TVn - stop qhull after adding point n, -n for before (see TCn) + TCn - stop qhull after building cone for point n (see TVn) + +Precision options: + Cn - radius of centrum (roundoff added). Merge facets if non-convex + An - cosine of maximum angle. Merge facets if cosine > n or non-convex + C-0 roundoff, A-0.99/C-0.01 pre-merge, A0.99/C0.01 post-merge + Rn - randomly perturb computations by a factor of [1-n,1+n] + Un - max distance below plane for a new, coplanar point + Wn - min facet width for outside point (before roundoff) + +Output formats (may be combined; if none, produces a summary to stdout): + f - facet dump + G - Geomview output (see below) + i - vertices incident to each facet + m - Mathematica output (2-d and 3-d) + n - normals with offsets + o - OFF file format (dim, points and facets; Voronoi regions) + p - point coordinates + s - summary (stderr) + +More formats: + Fa - area for each facet + FA - compute total area and volume for option 's' + Fc - count plus coplanar points for each facet + use 'Qc' (default) for coplanar and 'Qi' for interior + FC - centrum for each facet + Fd - use cdd format for input (homogeneous with offset first) + FD - use cdd format for numeric output (offset first) + FF - facet dump without ridges + Fi - inner plane for each facet + FI - ID for each facet + Fm - merge count for each facet (511 max) + FM - Maple output (2-d and 3-d) + Fn - count plus neighboring facets for each facet + FN - count plus neighboring facets for each point + Fo - outer plane (or max_outside) for each facet + FO - options and precision constants + FP - nearest vertex for each coplanar point + FQ - command used for qconvex + Fs - summary: #int (8), dimension, #points, tot vertices, tot facets, + for output: #vertices, #facets, + #coplanar points, #non-simplicial facets + #real (2), max outer plane, min vertex + FS - sizes: #int (0) + #real(2) tot area, tot volume + Ft - triangulation with centrums for non-simplicial facets (OFF format) + Fv - count plus vertices for each facet + FV - average of vertices (a feasible point for 'H') + Fx - extreme points (in order for 2-d) + +Geomview output (2-d, 3-d, and 4-d) + Ga - all points as dots + Gp - coplanar points and vertices as radii + Gv - vertices as spheres + Gi - inner planes only + Gn - no planes + Go - outer planes only + Gc - centrums + Gh - hyperplane intersections + Gr - ridges + GDn - drop dimension n in 3-d and 4-d output + +Print options: + PAn - keep n largest facets by area + Pdk:n - drop facet if normal[k] <= n (default 0.0) + PDk:n - drop facet if normal[k] >= n + Pg - print good facets (needs 'QGn' or 'QVn') + PFn - keep facets whose area is at least n + PG - print neighbors of good facets + PMn - keep n facets with most merges + Po - force output. If error, output neighborhood of facet + Pp - do not report precision problems + + . - list of all options + - - one line descriptions of all options + +</pre> + +<!-- Navigation links --> +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +•<a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#synopsis">sy</a>nopsis +• <a href="#input">in</a>put • <a href="#outputs">ou</a>tputs +• <a href="#controls">co</a>ntrols • <a href="#graphics">gr</a>aphics +• <a href="#notes">no</a>tes • <a href="#conventions">co</a>nventions +• <a href="#options">op</a>tions +<!-- GC common information --> +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="qh--geom.gif" +align="middle" width="40" height="40"></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: Sept. 25, 1995 --- <!-- hhmts start --> Last modified: see top <!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/qdelau_f.htm b/xs/src/qhull/html/qdelau_f.htm new file mode 100644 index 000000000..d8981e16b --- /dev/null +++ b/xs/src/qhull/html/qdelau_f.htm @@ -0,0 +1,416 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<title>qdelaunay Qu -- furthest-site Delaunay triangulation</title> +</head> + +<body> +<!-- Navigation links --> +<a name="TOP"><b>Up</b></a><b>:</b> +<a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#synopsis">sy</a>nopsis +• <a href="#input">in</a>put • <a href="#outputs">ou</a>tputs +• <a href="#controls">co</a>ntrols • <a href="#graphics">gr</a>aphics +• <a href="#notes">no</a>tes • <a href="#conventions">co</a>nventions +• <a href="#options">op</a>tions + +<hr> +<!-- Main text of document --> +<h1><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/delaunay.html"><img +src="qh--dt.gif" alt="[delaunay]" align="middle" width="100" +height="100"></a>qdelaunay Qu -- furthest-site Delaunay triangulation</h1> + +<p>The furthest-site Delaunay triangulation corresponds to the upper facets of the <a href="qdelaun.htm">Delaunay construction</a>. +Its vertices are the +extreme points of the input sites. +It is the dual of the <a +href="qvoron_f.htm">furthest-site Voronoi diagram</a>. + +<blockquote> +<dl> + <dt><b>Example:</b> rbox 10 D2 | qdelaunay <a + href="qh-optq.htm#Qu">Qu</a> <a + href="qh-optq.htm#Qt">Qt</a> <a href="qh-opto.htm#s">s</a> + <a href="qh-opto.htm#i">i</a> <a href="qh-optt.htm#TO">TO + result</a></dt> + <dd>Compute the 2-d, furthest-site Delaunay triangulation of 10 random + points. Triangulate the output. + Write a summary to the console and the regions to + 'result'.</dd> + <dt> </dt> + <dt><b>Example:</b> rbox 10 D2 | qdelaunay <a + href="qh-optq.htm#Qu">Qu</a> <a + href="qh-optq.htm#QJn">QJ</a> <a href="qh-opto.htm#s">s</a> + <a href="qh-opto.htm#i">i</a> <a href="qh-optt.htm#TO">TO + result</a></dt> + <dd>Compute the 2-d, furthest-site Delaunay triangulation of 10 random + points. Joggle the input to guarantee triangular output. + Write a summary to the console and the regions to + 'result'.</dd> + <dt> </dt> + <dt><b>Example:</b> rbox r y c G1 D2 | qdelaunay <a + href="qh-optq.htm#Qu">Qu</a> <a href="qh-opto.htm#s">s</a> + <a href="qh-optf.htm#Fv">Fv</a> <a href="qh-optt.htm#TO">TO + result</a></dt> + <dd>Compute the 2-d, furthest-site Delaunay triangulation of a triangle inside + a square. + Write a summary to the console and unoriented regions to 'result'. + Merge regions for cocircular input sites (e.g., the square). + The square is the only furthest-site + Delaunay region.</dd> +</dl> +</blockquote> + +<p>As with the Delaunay triangulation, Qhull computes the +furthest-site Delaunay triangulation by lifting the input sites to a +paraboloid. The lower facets correspond to the Delaunay +triangulation while the upper facets correspond to the +furthest-site triangulation. Neither triangulation includes +"vertical" facets (i.e., facets whose last hyperplane +coefficient is nearly zero). Vertical facets correspond to input +sites that are coplanar to the convex hull of the input. An +example is points on the boundary of a lattice.</p> + +<p>By default, qdelaunay merges cocircular and cospherical regions. +For example, the furthest-site Delaunay triangulation of a square inside a diamond +('rbox D2 c d G4 | qdelaunay Qu') consists of one region (the diamond). + +<p>If you use '<a href="qh-optq.htm#Qt">Qt</a>' (triangulated output), +all furthest-site Delaunay regions will be simplicial (e.g., triangles in 2-d). +Some regions may be +degenerate and have zero area. + +<p>If you use '<a href="qh-optq.htm#QJn">QJ</a>' (joggled input), all furthest-site +Delaunay regions +will be simplicial (e.g., triangles in 2-d). Joggled input +is less accurate than triangulated output ('Qt'). See <a +href="qh-impre.htm#joggle">Merged facets or joggled input</a>. </p> + +<p>The output for 3-d, furthest-site Delaunay triangulations may be confusing if the +input contains cospherical data. See the FAQ item +<a href=qh-faq.htm#extra>Why +are there extra points in a 4-d or higher convex hull?</a> +Avoid these problems with triangulated output ('<a href="qh-optq.htm#Qt">Qt</a>') or +joggled input ('<a href="qh-optq.htm#QJn">QJ</a>'). +</p> + +<p>The 'qdelaunay' program is equivalent to +'<a href=qhull.htm#outputs>qhull d</a> <a href=qh-optq.htm#Qbb>Qbb</a>' in 2-d to 3-d, and +'<a href=qhull.htm#outputs>qhull d</a> <a href=qh-optq.htm#Qbb>Qbb</a> <a href=qh-optq.htm#Qx>Qx</a>' +in 4-d and higher. It disables the following Qhull +<a href=qh-quick.htm#options>options</a>: <i>d n v H U Qb QB Qc Qf Qg Qi +Qm Qr QR Qv Qx TR E V FC Fi Fo Fp FV Q0,etc</i>. + + +<p><b>Copyright © 1995-2015 C.B. Barber</b></p> + +<hr> + +<h3><a href="#TOP">»</a><a name="synopsis">furthest-site qdelaunay synopsis</a></h3> +<blockquote> + +See <a href="qdelaun.htm#synopsis">qdelaunay synopsis</a>. The same +program is used for both constructions. Use option '<a href="qh-optq.htm#Qu">Qu</a>' +for furthest-site Delaunay triangulations. + +</blockquote> +<h3><a href="#TOP">»</a><a name="input">furthest-site qdelaunay +input</a></h3> + +<blockquote> +<p>The input data on <tt>stdin</tt> consists of:</p> +<ul> + <li>dimension + <li>number of points</li> + <li>point coordinates</li> +</ul> + +<p>Use I/O redirection (e.g., qdelaunay Qu < data.txt), a pipe (e.g., rbox 10 | qdelaunay Qu), +or the '<a href=qh-optt.htm#TI>TI</a>' option (e.g., qdelaunay Qu TI data.txt). + +<p>For example, this is a square containing four random points. +Its furthest-site Delaunay +triangulation contains one square. +<p> +<blockquote> +<tt>rbox c 4 D2 > data</tt> +<blockquote><pre> +2 RBOX c 4 D2 +8 +-0.4999921736307369 -0.3684622117955817 +0.2556053225468894 -0.0413498678629751 +0.0327672376602583 -0.2810408135699488 +-0.452955383763607 0.17886471718444 + -0.5 -0.5 + -0.5 0.5 + 0.5 -0.5 + 0.5 0.5 +</pre></blockquote> + +<p><tt>qdelaunay Qu i < data</tt> +<blockquote><pre> + +Furthest-site Delaunay triangulation by the convex hull of 8 points in 3-d: + + Number of input sites: 8 + Number of Delaunay regions: 1 + Number of non-simplicial Delaunay regions: 1 + +Statistics for: RBOX c 4 D2 | QDELAUNAY s Qu i + + Number of points processed: 8 + Number of hyperplanes created: 20 + Number of facets in hull: 11 + Number of distance tests for qhull: 34 + Number of merged facets: 1 + Number of distance tests for merging: 107 + CPU seconds to compute hull (after input): 0.02 + +1 +7 6 4 5 +</pre></blockquote> +</blockquote> + +</blockquote> +<h3><a href="#TOP">»</a><a name="outputs">furthest-site qdelaunay +outputs</a></h3> +<blockquote> + +<p>These options control the output of furthest-site Delaunay triangulations:</p> +<blockquote> + +<dl compact> + <dd><b>furthest-site Delaunay regions</b></dd> + <dt><a href="qh-opto.htm#i">i</a></dt> + <dd>list input sites for each furthest-site Delaunay region. The first line is the number of regions. The + remaining lines list the input sites for each region. The regions are + oriented. In 3-d and + higher, report cospherical sites by adding extra points. For the points-in-square example, + the square is the only furthest-site Delaunay region.</dd> + <dt><a href="qh-optf.htm#Fv">Fv</a></dt> + <dd>list input sites for each furthest-site Delaunay region. The first line is the number of regions. + Each remaining line starts with the number of input sites. The regions + are unoriented. For the points-in-square example, + the square is the only furthest-site Delaunay region.</dd> + <dt><a href="qh-optf.htm#Ft">Ft</a></dt> + <dd>print a triangulation of the furthest-site Delaunay regions in OFF format. The first line + is the dimension. The second line is the number of input sites and added points, + followed by the number of simplices and the number of ridges. + The input coordinates are next, followed by the centrum coordinates. There is + one centrum for each non-simplicial furthest-site Delaunay region. Each remaining line starts + with dimension+1. The + simplices are oriented. + For the points-in-square example, the square has a centrum at the + origin. It splits the square into four triangular regions.</dd> + <dt><a href="qh-optf.htm#Fn">Fn</a></dt> + <dd>list neighboring regions for each furthest-site Delaunay region. The first line is the + number of regions. Each remaining line starts with the number of + neighboring regions. Negative indices (e.g., <em>-1</em>) indicate regions + outside of the furthest-site Delaunay triangulation. + For the points-in-square example, the four neighboring regions + are outside of the triangulation. They belong to the regular + Delaunay triangulation.</dd> + <dt><a href="qh-optf.htm#FN">FN</a></dt> + <dd>list the furthest-site Delaunay regions for each input site. The first line is the + total number of input sites. Each remaining line starts with the number of + furthest-site Delaunay regions. Negative indices (e.g., <em>-1</em>) indicate regions + outside of the furthest-site Delaunay triangulation. + For the points-in-square example, the four random points belong to no region + while the square's vertices belong to region <em>0</em> and three + regions outside of the furthest-site Delaunay triangulation.</dd> + <dt><a href="qh-optf.htm#Fa">Fa</a></dt> + <dd>print area for each furthest-site Delaunay region. The first line is the number of regions. + The areas follow, one line per region. For the points-in-square example, the + square has unit area. </dd> + + <dt> </dt> + <dt> </dt> + <dd><b>Input sites</b></dd> + <dt><a href="qh-optf.htm#Fx">Fx</a></dt> + <dd>list extreme points of the input sites. These points are vertices of the furthest-point + Delaunay triangulation. They are on the + boundary of the convex hull. The first line is the number of + extreme points. Each point is listed, one per line. The points-in-square example + has four extreme points.</dd> + <dt> </dt> + <dt> </dt> + <dd><b>General</b></dd> + <dt><a href="qh-optf.htm#FA">FA</a></dt> + <dd>compute total area for '<a href="qh-opto.htm#s">s</a>' + and '<a href="qh-optf.htm#FS">FS</a>'. This is the + same as the area of the convex hull.</dd> + <dt><a href="qh-opto.htm#o">o</a></dt> + <dd>print upper facets of the corresponding convex hull (a + paraboloid)</dd> + <dt><a href="qh-opto.htm#m">m</a></dt> + <dd>Mathematica output for the upper facets of the paraboloid (2-d triangulations).</dd> + <dt><a href="qh-optf.htm#FM">FM</a></dt> + <dd>Maple output for the upper facets of the paraboloid (2-d triangulations).</dd> + <dt><a href="qh-optg.htm#G">G</a></dt> + <dd>Geomview output for the paraboloid (2-d or 3-d triangulations).</dd> + <dt><a href="qh-opto.htm#s">s</a></dt> + <dd>print summary for the furthest-site Delaunay triangulation. Use '<a + href="qh-optf.htm#Fs">Fs</a>' and '<a + href="qh-optf.htm#FS">FS</a>' for numeric data.</dd> +</dl> +</blockquote> + +</blockquote> +<h3><a href="#TOP">»</a><a name="controls">furthest-site qdelaunay +controls</a></h3> +<blockquote> + +<p>These options provide additional control:</p> +<blockquote> + +<dl compact> + <dt><a href="qh-optq.htm#Qu">Qu</a></dt> + <dd>must be used for furthest-site Delaunay triangulation.</dd> + <dt><a href="qh-optq.htm#Qt">Qt</a></dt> + <dd>triangulated output. Qhull triangulates non-simplicial facets. It may produce + degenerate facets of zero area.</dd> + <dt><a href="qh-optq.htm#QJn">QJ</a></dt> + <dd>joggle the input to avoid cospherical and coincident + sites. It is less accurate than triangulated output ('Qt').</dd> + <dt><a href="qh-optq.htm#QVn">QVn</a></dt> + <dd>select facets adjacent to input site <em>n</em> (marked + 'good').</dd> + <dt><a href="qh-optt.htm#Tv">Tv</a></dt> + <dd>verify result.</dd> + <dt><a href="qh-optt.htm#TO">TI file</a></dt> + <dd>input data from file. The filename may not use spaces or quotes.</dd> + <dt><a href="qh-optt.htm#TO">TO file</a></dt> + <dd>output results to file. Use single quotes if the filename + contains spaces (e.g., <tt>TO 'file with spaces.txt'</tt></dd> + <dt><a href="qh-optt.htm#TFn">TFn</a></dt> + <dd>report progress after constructing <em>n</em> facets</dd> + <dt><a href="qh-optp.htm#PDk">PDk:1</a></dt> + <dd>include upper and lower facets in the output. Set <em>k</em> + to the last dimension (e.g., 'PD2:1' for 2-d inputs). </dd> + <dt><a href="qh-opto.htm#f">f</a></dt> + <dd>facet dump. Print the data structure for each facet (i.e., furthest-site Delaunay region).</dd> +</dl> +</blockquote> + +</blockquote> +<h3><a href="#TOP">»</a><a name="graphics">furthest-site qdelaunay +graphics</a></h3> +<blockquote> + +See <a href="qdelaun.htm#graphics">Delaunay graphics</a>. +They are the same except for Mathematica and Maple output. + +</blockquote> +<h3><a href="#TOP">»</a><a name="notes">furthest-site +qdelaunay notes</a></h3> +<blockquote> + +<p>The furthest-site Delaunay triangulation does not +record coincident input sites. Use <tt>qdelaunay</tt> instead. + +<p><tt>qdelaunay Qu</tt> does not work for purely cocircular +or cospherical points (e.g., rbox c | qdelaunay Qu). Instead, +use <tt>qdelaunay Qz</tt> -- when all points are vertices of the convex +hull of the input sites, the Delaunay triangulation is the same +as the furthest-site Delaunay triangulation. + +<p>A non-simplicial, furthest-site Delaunay region indicates nearly cocircular or +cospherical input sites. To avoid non-simplicial regions triangulate +the output ('<a href="qh-optq.htm#Qt">Qt</a>') or joggle +the input ('<a href="qh-optq.htm#QJn">QJ</a>'). Joggled input +is less accurate than triangulated output. +You may also triangulate +non-simplicial regions with option '<a +href="qh-optf.htm#Ft">Ft</a>'. It adds +the centrum to non-simplicial regions. Alternatively, use an <a +href="qh-impre.htm#exact">exact arithmetic code</a>.</p> + +<p>Furthest-site Delaunay triangulations do not include facets that are +coplanar with the convex hull of the input sites. A facet is +coplanar if the last coefficient of its normal is +nearly zero (see <a href="../src/libqhull/user.h#ZEROdelaunay">qh_ZEROdelaunay</a>). + +</blockquote> +<h3><a href="#TOP">»</a><a name="conventions">furthest-site qdelaunay conventions</a></h3> +<blockquote> + +<p>The following terminology is used for furthest-site Delaunay +triangulations in Qhull. The underlying structure is the upper +facets of a convex hull in one higher dimension. See <a +href="qconvex.htm#conventions">convex hull conventions</a>, <a +href="qdelaun.htm#conventions">Delaunay conventions</a>, +and <a href="index.htm#structure">Qhull's data structures</a></p> +<blockquote> +<ul> + <li><em>input site</em> - a point in the input (one dimension + lower than a point on the convex hull)</li> + <li><em>point</em> - <i>d+1</i> coordinates. The last + coordinate is the sum of the squares of the input site's + coordinates</li> + <li><em>vertex</em> - a point on the paraboloid. It + corresponds to a unique input site. </li> + <li><em>furthest-site Delaunay facet</em> - an upper facet of the + paraboloid. The last coefficient of its normal is + clearly positive.</li> + <li><em>furthest-site Delaunay region</em> - a furthest-site Delaunay + facet projected to the input sites</li> + <li><em>non-simplicial facet</em> - more than <em>d</em> + points are cocircular or cospherical</li> + <li><em>good facet</em> - a furthest-site Delaunay facet with optional + restrictions by '<a href="qh-optq.htm#QVn">QVn</a>', etc.</li> +</ul> +</blockquote> +</blockquote> +<h3><a href="#TOP">»</a><a name="options">furthest-site qdelaunay options</a></h3> +<blockquote> + +See <a href="qdelaun.htm#options">qdelaunay options</a>. The same +program is used for both constructions. Use option '<a href="qh-optq.htm#Qu">Qu</a>' +for furthest-site Delaunay triangulations. + +</blockquote> +<!-- Navigation links --> +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#synopsis">sy</a>nopsis +• <a href="#input">in</a>put • <a href="#outputs">ou</a>tputs +• <a href="#controls">co</a>ntrols • <a href="#graphics">gr</a>aphics +• <a href="#notes">no</a>tes • <a href="#conventions">co</a>nventions +• <a href="#options">op</a>tions +<!-- GC common information --> +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="qh--geom.gif" +align="middle" width="40" height="40"></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: Sept. 25, 1995 --- <!-- hhmts start --> Last modified: see top <!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/qdelaun.htm b/xs/src/qhull/html/qdelaun.htm new file mode 100644 index 000000000..a42223c66 --- /dev/null +++ b/xs/src/qhull/html/qdelaun.htm @@ -0,0 +1,628 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<title>qdelaunay -- Delaunay triangulation</title> +</head> + +<body> +<!-- Navigation links --> +<a name="TOP"><b>Up</b></a><b>:</b> +<a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#synopsis">sy</a>nopsis +• <a href="#input">in</a>put • <a href="#outputs">ou</a>tputs +• <a href="#controls">co</a>ntrols • <a href="#graphics">gr</a>aphics +• <a href="#notes">no</a>tes • <a href="#conventions">co</a>nventions +• <a href="#options">op</a>tions + +<hr> +<!-- Main text of document --> +<h1><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/delaunay.html"><img +src="qh--dt.gif" alt="[delaunay]" align="middle" width="100" +height="100"></a>qdelaunay -- Delaunay triangulation</h1> + +<p>The Delaunay triangulation is the triangulation with empty +circumspheres. It has many useful properties and applications. +See the survey article by Aurenhammer [<a +href="index.htm#aure91">'91</a>] and the detailed introduction +by O'Rourke [<a href="index.htm#orou94">'94</a>]. </p> + +<blockquote> +<dl> + <dt><b>Example:</b> rbox r y c G0.1 D2 | qdelaunay <a href="qh-opto.htm#s">s</a> + <a href="qh-optf.htm#Fv">Fv</a> <a href="qh-optt.htm#TO">TO + result</a></dt> + <dd>Compute the 2-d Delaunay triangulation of a triangle and + a small square. + Write a summary to the console and unoriented regions to 'result'. + Merge regions for cocircular input sites (i.e., the + square).</dd> + <dt> </dt> + <dt><b>Example:</b> rbox r y c G0.1 D2 | qdelaunay <a href="qh-opto.htm#s">s</a> + <a href="qh-optf.htm#Fv">Fv</a> <a href="qh-optq.htm#Qt">Qt</a></dt> + <dd>Compute the 2-d Delaunay triangulation of a triangle and + a small square. Write a summary and unoriented + regions to the console. Produce triangulated output.</dd> + <dt> </dt> + <dt><b>Example:</b> rbox 10 D2 | qdelaunay <a + href="qh-optq.htm#QJn">QJ</a> <a href="qh-opto.htm#s">s</a> + <a href="qh-opto.htm#i">i</a> <a href="qh-optt.htm#TO">TO + result</a></dt> + <dd>Compute the 2-d Delaunay triangulation of 10 random + points. Joggle the input to guarantee triangular output. + Write a summary to the console and the regions to + 'result'.</dd> +</dl> +</blockquote> + +<p>Qhull computes the Delaunay triangulation by computing a +convex hull. It lifts the input sites to a paraboloid by adding +the sum of the squares of the coordinates. It scales the height +of the paraboloid to improve numeric precision ('<a href=qh-optq.htm#Qbb>Qbb</a>'). +It computes the convex +hull of the lifted sites, and projects the lower convex hull to +the input. + +<p>Each region of the Delaunay triangulation +corresponds to a facet of the lower half of the convex hull. +Facets of the upper half of the convex hull correspond to the <a +href="qdelau_f.htm">furthest-site Delaunay triangulation</a>. +See the examples, <a href="qh-eg.htm#delaunay">Delaunay and +Voronoi diagrams</a>.</p> + +<p>See <a href="http://www.qhull.org/html/qh-faq.htm#TOC">Qhull FAQ</a> - Delaunay and +Voronoi diagram questions.</p> + +<p>By default, qdelaunay merges cocircular and cospherical regions. +For example, the Delaunay triangulation of a square inside a diamond +('rbox D2 c d G4 | qdelaunay') contains one region for the square. + +<p>Use option '<a href="qh-optq.htm#Qz">Qz</a>' if the input is circular, cospherical, or +nearly so. It improves precision by adding a point "at infinity," above the corresponding paraboloid. + +<p>If you use '<a href="qh-optq.htm#Qt">Qt</a>' (triangulated output), +all Delaunay regions will be simplicial (e.g., triangles in 2-d). +Some regions may be +degenerate and have zero area. Triangulated output identifies coincident +points. + +<p>If you use '<a href="qh-optq.htm#QJn">QJ</a>' (joggled input), all Delaunay regions +will be simplicial (e.g., triangles in 2-d). Coincident points will +create small regions since the points are joggled apart. Joggled input +is less accurate than triangulated output ('Qt'). See <a +href="qh-impre.htm#joggle">Merged facets or joggled input</a>. </p> + +<p>The output for 3-d Delaunay triangulations may be confusing if the +input contains cospherical data. See the FAQ item +<a href=qh-faq.htm#extra>Why +are there extra points in a 4-d or higher convex hull?</a> +Avoid these problems with triangulated output ('<a href="qh-optq.htm#Qt">Qt</a>') or +joggled input ('<a href="qh-optq.htm#QJn">QJ</a>'). +</p> + +<p>The 'qdelaunay' program is equivalent to +'<a href=qhull.htm#outputs>qhull d</a> <a href=qh-optq.htm#Qbb>Qbb</a>' in 2-d to 3-d, and +'<a href=qhull.htm#outputs>qhull d</a> <a href=qh-optq.htm#Qbb>Qbb</a> <a href=qh-optq.htm#Qx>Qx</a>' +in 4-d and higher. It disables the following Qhull +<a href=qh-quick.htm#options>options</a>: <i>d n v H U Qb QB Qc Qf Qg Qi +Qm Qr QR Qv Qx TR E V FC Fi Fo Fp Ft FV Q0,etc</i>. + + +<p><b>Copyright © 1995-2015 C.B. Barber</b></p> + +<hr> + +<h3><a href="#TOP">»</a><a name="synopsis">qdelaunay synopsis</a></h3> + +<pre> +qdelaunay- compute the Delaunay triangulation. + input (stdin): dimension, number of points, point coordinates + comments start with a non-numeric character + +options (qdelaun.htm): + Qt - triangulated output + QJ - joggle input instead of merging facets + Qu - furthest-site Delaunay triangulation + Tv - verify result: structure, convexity, and in-circle test + . - concise list of all options + - - one-line description of all options + +output options (subset): + s - summary of results (default) + i - vertices incident to each Delaunay region + Fx - extreme points (vertices of the convex hull) + o - OFF format (shows the points lifted to a paraboloid) + G - Geomview output (2-d and 3-d points lifted to a paraboloid) + m - Mathematica output (2-d inputs lifted to a paraboloid) + QVn - print Delaunay regions that include point n, -n if not + TO file- output results to file, may be enclosed in single quotes + +examples: + rbox c P0 D2 | qdelaunay s o rbox c P0 D2 | qdelaunay i + rbox c P0 D3 | qdelaunay Fv Qt rbox c P0 D2 | qdelaunay s Qu Fv + rbox c G1 d D2 | qdelaunay s i rbox c G1 d D2 | qdelaunay s i Qt + rbox M3,4 z 100 D2 | qdelaunay s rbox M3,4 z 100 D2 | qdelaunay s Qt +</pre> + + +<h3><a href="#TOP">»</a><a name="input">qdelaunay +input</a></h3> + +<blockquote> +<p>The input data on <tt>stdin</tt> consists of:</p> +<ul> + <li>dimension + <li>number of points</li> + <li>point coordinates</li> +</ul> + +<p>Use I/O redirection (e.g., qdelaunay < data.txt), a pipe (e.g., rbox 10 | qdelaunay), +or the '<a href=qh-optt.htm#TI>TI</a>' option (e.g., qdelaunay TI data.txt). + +<p>For example, this is four cocircular points inside a square. Its Delaunay +triangulation contains 8 triangles and one four-sided +figure. +<p> +<blockquote> +<tt>rbox s 4 W0 c G1 D2 > data</tt> +<blockquote><pre> +2 RBOX s 4 W0 c D2 +8 +-0.4941988586954018 -0.07594397977563715 +-0.06448037284989526 0.4958248496365813 +0.4911154367094632 0.09383830681375946 +-0.348353580869097 -0.3586778257652367 + -1 -1 + -1 1 + 1 -1 + 1 1 +</pre></blockquote> + +<p><tt>qdelaunay s i < data</tt> +<blockquote><pre> + +Delaunay triangulation by the convex hull of 8 points in 3-d + + Number of input sites: 8 + Number of Delaunay regions: 9 + Number of non-simplicial Delaunay regions: 1 + +Statistics for: RBOX s 4 W0 c D2 | QDELAUNAY s i + + Number of points processed: 8 + Number of hyperplanes created: 18 + Number of facets in hull: 10 + Number of distance tests for qhull: 33 + Number of merged facets: 2 + Number of distance tests for merging: 102 + CPU seconds to compute hull (after input): 0.028 + +9 +1 7 5 +6 3 4 +2 3 6 +7 2 6 +2 7 1 +0 5 4 +3 0 4 +0 1 5 +1 0 3 2 +</pre></blockquote> +</blockquote> + +</blockquote> +<h3><a href="#TOP">»</a><a name="outputs">qdelaunay +outputs</a></h3> +<blockquote> + +<p>These options control the output of Delaunay triangulations:</p> +<blockquote> + +<dl compact> + <dd><b>Delaunay regions</b></dd> + <dt><a href="qh-opto.htm#i">i</a></dt> + <dd>list input sites for each Delaunay region. The first line is the number of regions. The + remaining lines list the input sites for each region. The regions are + oriented. In 3-d and + higher, report cospherical sites by adding extra points. Use triangulated + output ('<a href="qh-optq.htm#Qt">Qt</a>') to avoid non-simpicial regions. For the circle-in-square example, + eight Delaunay regions are triangular and the ninth has four input sites.</dd> + <dt><a href="qh-optf.htm#Fv">Fv</a></dt> + <dd>list input sites for each Delaunay region. The first line is the number of regions. + Each remaining line starts with the number of input sites. The regions + are unoriented. For the circle-in-square example, + eight Delaunay regions are triangular and the ninth has four input sites.</dd> + <dt><a href="qh-optf.htm#Fn">Fn</a></dt> + <dd>list neighboring regions for each Delaunay region. The first line is the + number of regions. Each remaining line starts with the number of + neighboring regions. Negative indices (e.g., <em>-1</em>) indicate regions + outside of the Delaunay triangulation. + For the circle-in-square example, the four regions on the square are neighbors to + the region-at-infinity.</dd> + <dt><a href="qh-optf.htm#FN">FN</a></dt> + <dd>list the Delaunay regions for each input site. The first line is the + total number of input sites. Each remaining line starts with the number of + Delaunay regions. Negative indices (e.g., <em>-1</em>) indicate regions + outside of the Delaunay triangulation. + For the circle-in-square example, each point on the circle belongs to four + Delaunay regions. Use '<a href="qh-optq.htm#Qc">Qc</a> FN' + to include coincident input sites and deleted vertices. </dd> + <dt><a href="qh-optf.htm#Fa">Fa</a></dt> + <dd>print area for each Delaunay region. The first line is the number of regions. + The areas follow, one line per region. For the circle-in-square example, the + cocircular region has area 0.4. </dd> + <dt> </dt> + <dt> </dt> + <dd><b>Input sites</b></dd> + <dt><a href="qh-optf.htm#Fc">Fc</a></dt> + <dd>list coincident input sites for each Delaunay region. + The first line is the number of regions. The remaining lines start with + the number of coincident sites and deleted vertices. Deleted vertices + indicate highly degenerate input (see'<a href="qh-optf.htm#Fs">Fs</a>'). + A coincident site is assigned to one Delaunay + region. Do not use '<a href="qh-optq.htm#QJn">QJ</a>' with 'Fc'; the joggle will separate + coincident sites.</dd> + <dt><a href="qh-optf.htm#FP">FP</a></dt> + <dd>print coincident input sites with distance to + nearest site (i.e., vertex). The first line is the + number of coincident sites. Each remaining line starts with the point ID of + an input site, followed by the point ID of a coincident point, its region, and distance. + Includes deleted vertices which + indicate highly degenerate input (see'<a href="qh-optf.htm#Fs">Fs</a>'). + Do not use '<a href="qh-optq.htm#QJn">QJ</a>' with 'FP'; the joggle will separate + coincident sites.</dd> + <dt><a href="qh-optf.htm#Fx">Fx</a></dt> + <dd>list extreme points of the input sites. These points are on the + boundary of the convex hull. The first line is the number of + extreme points. Each point is listed, one per line. The circle-in-square example + has four extreme points.</dd> + <dt> </dt> + <dt> </dt> + <dd><b>General</b></dd> + <dt><a href="qh-optf.htm#FA">FA</a></dt> + <dd>compute total area for '<a href="qh-opto.htm#s">s</a>' + and '<a href="qh-optf.htm#FS">FS</a>'</dd> + <dt><a href="qh-opto.htm#o">o</a></dt> + <dd>print lower facets of the corresponding convex hull (a + paraboloid)</dd> + <dt><a href="qh-opto.htm#m">m</a></dt> + <dd>Mathematica output for the lower facets of the paraboloid (2-d triangulations).</dd> + <dt><a href="qh-optf.htm#FM">FM</a></dt> + <dd>Maple output for the lower facets of the paraboloid (2-d triangulations).</dd> + <dt><a href="qh-optg.htm#G">G</a></dt> + <dd>Geomview output for the paraboloid (2-d or 3-d triangulations).</dd> + <dt><a href="qh-opto.htm#s">s</a></dt> + <dd>print summary for the Delaunay triangulation. Use '<a + href="qh-optf.htm#Fs">Fs</a>' and '<a + href="qh-optf.htm#FS">FS</a>' for numeric data.</dd> +</dl> +</blockquote> + +</blockquote> +<h3><a href="#TOP">»</a><a name="controls">qdelaunay +controls</a></h3> +<blockquote> + +<p>These options provide additional control:</p> +<blockquote> + +<dl compact> + <dt><a href="qh-optq.htm#Qt">Qt</a></dt> + <dd>triangulated output. Qhull triangulates non-simplicial facets. It may produce +degenerate facets of zero area.</dd> + <dt><a href="qh-optq.htm#QJn">QJ</a></dt> + <dd>joggle the input to avoid cospherical and coincident + sites. It is less accurate than triangulated output ('Qt').</dd> + <dt><a href="qh-optq.htm#Qu">Qu</a></dt> + <dd>compute the <a href="qdelau_f.htm">furthest-site Delaunay triangulation</a>.</dd> + <dt><a href="qh-optq.htm#Qz">Qz</a></dt> + <dd>add a point above the paraboloid to reduce precision + errors. Use it for nearly cocircular/cospherical input + (e.g., 'rbox c | qdelaunay Qz'). The point is printed for + options '<a href="qh-optf.htm#Ft">Ft</a>' and '<a + href="qh-opto.htm#o">o</a>'.</dd> + <dt><a href="qh-optq.htm#QVn">QVn</a></dt> + <dd>select facets adjacent to input site <em>n</em> (marked + 'good').</dd> + <dt><a href="qh-optt.htm#Tv">Tv</a></dt> + <dd>verify result.</dd> + <dt><a href="qh-optt.htm#TO">TI file</a></dt> + <dd>input data from file. The filename may not use spaces or quotes.</dd> + <dt><a href="qh-optt.htm#TO">TO file</a></dt> + <dd>output results to file. Use single quotes if the filename + contains spaces (e.g., <tt>TO 'file with spaces.txt'</tt></dd> + <dt><a href="qh-optt.htm#TFn">TFn</a></dt> + <dd>report progress after constructing <em>n</em> facets</dd> + <dt><a href="qh-optp.htm#PDk">PDk:1</a></dt> + <dd>include upper and lower facets in the output. Set <em>k</em> + to the last dimension (e.g., 'PD2:1' for 2-d inputs). </dd> + <dt><a href="qh-opto.htm#f">f</a></dt> + <dd>facet dump. Print the data structure for each facet (i.e., Delaunay region).</dd> +</dl> +</blockquote> + +</blockquote> +<h3><a href="#TOP">»</a><a name="graphics">qdelaunay +graphics</a></h3> +<blockquote> + +<p>For 2-d and 3-d Delaunay triangulations, Geomview ('qdelaunay <a +href="qh-optg.htm#G">G</a>') displays the corresponding convex +hull (a paraboloid). </p> + +<p>To view a 2-d Delaunay triangulation, use 'qdelaunay <a +href="qh-optg.htm#GDn">GrD2</a>' to drop the last dimension. This +is the same as viewing the hull without perspective (see +Geomview's 'cameras' menu). </p> + +<p>To view a 3-d Delaunay triangulation, use 'qdelaunay <a +href="qh-optg.htm#GDn">GrD3</a>' to drop the last dimension. You +may see extra edges. These are interior edges that Geomview moves +towards the viewer (see 'lines closer' in Geomview's camera +options). Use option '<a href="qh-optg.htm#Gt">Gt</a>' to make +the outer ridges transparent in 3-d. See <a +href="qh-eg.htm#delaunay">Delaunay and Voronoi examples</a>.</p> + +<p>For 2-d Delaunay triangulations, Mathematica ('<a +href="qh-opto.htm#m">m</a>') and Maple ('<a +href="qh-optf.htm#FM">FM</a>') output displays the lower facets of the corresponding convex +hull (a paraboloid). </p> + +<p>For 2-d, furthest-site Delaunay triangulations, Maple and Mathematica output ('<a +href="qh-optq.htm#Qu">Qu</a> <a +href="qh-opto.htm#m">m</a>') displays the upper facets of the corresponding convex +hull (a paraboloid). </p> + +</blockquote> +<h3><a href="#TOP">»</a><a name="notes">qdelaunay +notes</a></h3> +<blockquote> + +<p>You can simplify the Delaunay triangulation by enclosing the input +sites in a large square or cube. This is particularly recommended +for cocircular or cospherical input data. + +<p>A non-simplicial Delaunay region indicates nearly cocircular or +cospherical input sites. To avoid non-simplicial regions either triangulate +the output ('<a href="qh-optq.htm#Qt">Qt</a>') or joggle +the input ('<a href="qh-optq.htm#QJn">QJ</a>'). Triangulated output +is more accurate than joggled input. Alternatively, use an <a +href="qh-impre.htm#exact">exact arithmetic code</a>.</p> + +<p>Delaunay triangulations do not include facets that are +coplanar with the convex hull of the input sites. A facet is +coplanar if the last coefficient of its normal is +nearly zero (see <a href="../src/libqhull/user.h#ZEROdelaunay">qh_ZEROdelaunay</a>). + +<p>See <a href=qh-impre.htm#delaunay>Imprecision issues :: Delaunay triangulations</a> +for a discussion of precision issues. Deleted vertices indicate +highly degenerate input. They are listed in the summary output and +option '<a href="qh-optf.htm#Fs">Fs</a>'.</p> + +<p>To compute the Delaunay triangulation of points on a sphere, +compute their convex hull. If the sphere is the unit sphere at +the origin, the facet normals are the Voronoi vertices of the +input. The points may be restricted to a hemisphere. [S. Fortune] +</p> + +<p>The 3-d Delaunay triangulation of regular points on a half +spiral (e.g., 'rbox 100 l | qdelaunay') has quadratic size, while the Delaunay triangulation +of random 3-d points is +approximately linear for reasonably sized point sets. + +<p>With the <a href="qh-code.htm#library">Qhull library</a>, you +can use <tt>qh_findbestfacet</tt> in <tt>poly2.c</tt> to locate the facet +that contains a point. You should first lift the point to the +paraboloid (i.e., the last coordinate is the sum of the squares +of the point's coordinates -- <tt>qh_setdelaunay</tt>). Do not use options +'<a href="qh-optq.htm#Qbb">Qbb</a>', '<a href="qh-optq.htm#QbB">QbB</a>', +'<a href="qh-optq.htm#Qbk">Qbk:n</a>', or '<a +href="qh-optq.htm#QBk">QBk:n</a>' since these scale the last +coordinate. </p> + +<p>If a point is interior to the convex hull of the input set, it +is interior to the adjacent vertices of the Delaunay +triangulation. This is demonstrated by the following pipe for +point 0: + +<pre> + qdelaunay <data s FQ QV0 p | qconvex s Qb3:0B3:0 p +</pre> + +<p>The first call to qdelaunay returns the neighboring points of +point 0 in the Delaunay triangulation. The second call to qconvex +returns the vertices of the convex hull of these points (after +dropping the lifted coordinate). If point 0 is interior to the +original point set, it is interior to the reduced point set. </p> + +</blockquote> +<h3><a href="#TOP">»</a><a name="conventions">qdelaunay conventions</a></h3> +<blockquote> + +<p>The following terminology is used for Delaunay triangulations +in Qhull for dimension <i>d</i>. The underlying structure is the +lower facets of a convex hull in dimension <i>d+1</i>. For +further information, see <a href="index.htm#structure">data +structures</a> and <a href="qconvex.htm#conventions">convex hull +conventions</a>.</p> +<blockquote> +<ul> + <li><em>input site</em> - a point in the input (one dimension + lower than a point on the convex hull)</li> + <li><em>point</em> - a point has <i>d+1</i> coordinates. The + last coordinate is the sum of the squares of the input + site's coordinates</li> + <li><em>coplanar point</em> - a <em>coincident</em> + input site or a deleted vertex. Deleted vertices + indicate highly degenerate input.</li> + <li><em>vertex</em> - a point on the paraboloid. It + corresponds to a unique input site. </li> + <li><em>point-at-infinity</em> - a point added above the + paraboloid by option '<a href="qh-optq.htm#Qz">Qz</a>'</li> + <li><em>lower facet</em> - a facet corresponding to a + Delaunay region. The last coefficient of its normal is + clearly negative.</li> + <li><em>upper facet</em> - a facet corresponding to a + furthest-site Delaunay region. The last coefficient of + its normal is clearly positive. </li> + <li><em>Delaunay region</em> - a + lower facet projected to the input sites</li> + <li><em>upper Delaunay region</em> - an upper facet projected + to the input sites</li> + <li><em>non-simplicial facet</em> - more than <em>d</em> + input sites are cocircular or cospherical</li> + <li><em>good facet</em> - a Delaunay region with optional + restrictions by '<a href="qh-optq.htm#QVn">QVn</a>', etc.</li> +</ul> +</blockquote> +</blockquote> +<h3><a href="#TOP">»</a><a name="options">qdelaunay options</a></h3> + +<pre> +qdelaunay- compute the Delaunay triangulation + http://www.qhull.org + +input (stdin): + first lines: dimension and number of points (or vice-versa). + other lines: point coordinates, best if one point per line + comments: start with a non-numeric character + +options: + Qt - triangulated output + QJ - joggle input instead of merging facets + Qu - compute furthest-site Delaunay triangulation + +Qhull control options: + QJn - randomly joggle input in range [-n,n] + Qs - search all points for the initial simplex + Qz - add point-at-infinity to Delaunay triangulation + QGn - print Delaunay region if visible from point n, -n if not + QVn - print Delaunay regions that include point n, -n if not + +Trace options: + T4 - trace at level n, 4=all, 5=mem/gauss, -1= events + Tc - check frequently during execution + Ts - print statistics + Tv - verify result: structure, convexity, and in-circle test + Tz - send all output to stdout + TFn - report summary when n or more facets created + TI file - input data from file, no spaces or single quotes + TO file - output results to file, may be enclosed in single quotes + TPn - turn on tracing when point n added to hull + TMn - turn on tracing at merge n + TWn - trace merge facets when width > n + TVn - stop qhull after adding point n, -n for before (see TCn) + TCn - stop qhull after building cone for point n (see TVn) + +Precision options: + Cn - radius of centrum (roundoff added). Merge facets if non-convex + An - cosine of maximum angle. Merge facets if cosine > n or non-convex + C-0 roundoff, A-0.99/C-0.01 pre-merge, A0.99/C0.01 post-merge + Rn - randomly perturb computations by a factor of [1-n,1+n] + Wn - min facet width for outside point (before roundoff) + +Output formats (may be combined; if none, produces a summary to stdout): + f - facet dump + G - Geomview output (see below) + i - vertices incident to each Delaunay region + m - Mathematica output (2-d only, lifted to a paraboloid) + o - OFF format (dim, points, and facets as a paraboloid) + p - point coordinates (lifted to a paraboloid) + s - summary (stderr) + +More formats: + Fa - area for each Delaunay region + FA - compute total area for option 's' + Fc - count plus coincident points for each Delaunay region + Fd - use cdd format for input (homogeneous with offset first) + FD - use cdd format for numeric output (offset first) + FF - facet dump without ridges + FI - ID of each Delaunay region + Fm - merge count for each Delaunay region (511 max) + FM - Maple output (2-d only, lifted to a paraboloid) + Fn - count plus neighboring region for each Delaunay region + FN - count plus neighboring region for each point + FO - options and precision constants + FP - nearest point and distance for each coincident point + FQ - command used for qdelaunay + Fs - summary: #int (8), dimension, #points, tot vertices, tot facets, + for output: #vertices, #Delaunay regions, + #coincident points, #non-simplicial regions + #real (2), max outer plane, min vertex + FS - sizes: #int (0) + #real (2), tot area, 0 + Fv - count plus vertices for each Delaunay region + Fx - extreme points of Delaunay triangulation (on convex hull) + +Geomview options (2-d and 3-d) + Ga - all points as dots + Gp - coplanar points and vertices as radii + Gv - vertices as spheres + Gi - inner planes only + Gn - no planes + Go - outer planes only + Gc - centrums + Gh - hyperplane intersections + Gr - ridges + GDn - drop dimension n in 3-d and 4-d output + Gt - transparent outer ridges to view 3-d Delaunay + +Print options: + PAn - keep n largest Delaunay regions by area + Pdk:n - drop facet if normal[k] <= n (default 0.0) + PDk:n - drop facet if normal[k] >= n + Pg - print good Delaunay regions (needs 'QGn' or 'QVn') + PFn - keep Delaunay regions whose area is at least n + PG - print neighbors of good regions (needs 'QGn' or 'QVn') + PMn - keep n Delaunay regions with most merges + Po - force output. If error, output neighborhood of facet + Pp - do not report precision problems + + . - list of all options + - - one line descriptions of all options +</pre> + +<!-- Navigation links --> +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#synopsis">sy</a>nopsis +• <a href="#input">in</a>put • <a href="#outputs">ou</a>tputs +• <a href="#controls">co</a>ntrols • <a href="#graphics">gr</a>aphics +• <a href="#notes">no</a>tes • <a href="#conventions">co</a>nventions +• <a href="#options">op</a>tions +<!-- GC common information --> +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="qh--geom.gif" +align="middle" width="40" height="40"></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: Sept. 25, 1995 --- <!-- hhmts start --> Last modified: see top <!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/qh--4d.gif b/xs/src/qhull/html/qh--4d.gif Binary files differnew file mode 100644 index 000000000..08be18c8a --- /dev/null +++ b/xs/src/qhull/html/qh--4d.gif diff --git a/xs/src/qhull/html/qh--cone.gif b/xs/src/qhull/html/qh--cone.gif Binary files differnew file mode 100644 index 000000000..78470ee8f --- /dev/null +++ b/xs/src/qhull/html/qh--cone.gif diff --git a/xs/src/qhull/html/qh--dt.gif b/xs/src/qhull/html/qh--dt.gif Binary files differnew file mode 100644 index 000000000..b6d4e2672 --- /dev/null +++ b/xs/src/qhull/html/qh--dt.gif diff --git a/xs/src/qhull/html/qh--geom.gif b/xs/src/qhull/html/qh--geom.gif Binary files differnew file mode 100644 index 000000000..9c70b5499 --- /dev/null +++ b/xs/src/qhull/html/qh--geom.gif diff --git a/xs/src/qhull/html/qh--half.gif b/xs/src/qhull/html/qh--half.gif Binary files differnew file mode 100644 index 000000000..80a4d0883 --- /dev/null +++ b/xs/src/qhull/html/qh--half.gif diff --git a/xs/src/qhull/html/qh--rand.gif b/xs/src/qhull/html/qh--rand.gif Binary files differnew file mode 100644 index 000000000..4d4e4daee --- /dev/null +++ b/xs/src/qhull/html/qh--rand.gif diff --git a/xs/src/qhull/html/qh-code.htm b/xs/src/qhull/html/qh-code.htm new file mode 100644 index 000000000..fff7faddb --- /dev/null +++ b/xs/src/qhull/html/qh-code.htm @@ -0,0 +1,1062 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<title>Qhull code</title> +<!-- Navigation links --> +</head> + +<body> + +<p><a name="TOP"><b>Up:</b></a> <a +href="http://www.qhull.org">Home page for Qhull</a> +<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual: Table of +Contents</a><br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#TOC">Qhull code</a>: Table of Contents +(please wait while loading) <br> +<b>Dn:</b> <a href="../src/libqhull_r/index.htm">Qhull functions</a>, macros, and data +structures +</p> + +<hr> +<!-- Main text of document --> +<h1><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/4dcube.html"><img +src="qh--4d.gif" alt="[4-d cube]" align="middle" width="100" +height="100"></a> Qhull code</h1> + +<p>This section discusses the code for Qhull. </p> + +<p><b>Copyright © 1995-2015 C.B. Barber</b></p> + +<hr> + +<h2><a href="#TOP">»</a><a name="TOC">Qhull code: Table of +Contents </a></h2> + +<ul> + <li><a href="#reentrant">Reentrant</a> Qhull + <li><a href="#convert">How to convert</a> code to reentrant Qhull + <li><a href="#64bit">Qhull</a> on 64-bit computers + <li><a href="#cpp">Calling</a> Qhull from C++ programs + <ul> + <li><a href="#questions-cpp">Cpp questions for Qhull</a></li> + <li><a href="#coordinate-cpp">CoordinateIterator</a></li> + <li><a href="#qhull-cpp">Qhull</a></li> + <li><a href="#error-cpp">QhullError</a></li> + <li><a href="#facet-cpp">QhullFacet</a></li> + <li><a href="#facetlist-cpp">QhullFacetList</a></li> + <li><a href="#facetset-cpp">QhullFacetSet</a></li> + <li><a href="#iterator-cpp">QhullIterator</a></li> + <li><a href="#linkedlist-cpp">QhullLinkedList</a></li> + <li><a href="#point-cpp">QhullPoint</a></li> + <li><a href="#qh-cpp">QhullQh</a></li> + <li><a href="#pointset-cpp">QhullPointSet</a></li> + <li><a href="#ridge-cpp">QhullRidge</a></li> + <li><a href="#ridgeset-cpp">QhullRidgeSet</a></li> + <li><a href="#set-cpp">QhullSet</a></li> + <li><a href="#vertex-cpp">QhullVertex</a></li> + <li><a href="#vertexlist-cpp">QhullVertexList</a></li> + <li><a href="#vertexset-cpp">QhullVertexSet</a></li> + <li><a href="#rbox-cpp">RboxPoints</a></li> + </ul> + <li><a href="#library">Calling</a> Qhull from C programs + <ul> + <li><a href="#exit">How to avoid</a> exit(), fprintf(), stderr, and stdout</li> + <li><a href="#constrained">Constrained Delaunay</a> + triangulation</li> + <li><a href="#dids">Delaunay triangulations</a> and point indices</li> + <li><a href="#findfacet">Locate facet</a> with + qh_findbestfacet()</li> + <li><a href="#inc">On-line construction</a> with + qh_addpoint()</li> + <li><a href="#mem">Sets and quick memory</a> allocation</li> + <li><a href="#tricoplanar">Tricoplanar facets</a> and option 'Qt'</li> + <li><a href="#vneighbor">Vertex neighbors</a> of a vertex</li> + <li><a href="#vertices">Voronoi vertices</a> of a region</li> + <li><a href="#ridge">Voronoi vertices</a> of a ridge</li> + </ul> + </li> + <li><a href="#performance">Performance</a> of Qhull</li> + <li><a href="#enhance">Enhancements</a> to Qhull</li> + <li><a href="../src/libqhull_r/index.htm">Qhull</a> functions, macros, and data + structures </li> +</ul> + +<hr> + +<h2><a href="#TOC">»</a><a name="reentrant">Reentrant Qhull</a></h2> + +<p>Qhull-2015 introduces reentrant Qhull (libqhull_r). Reentrant Qhull uses a qhT* argument instead of global data structures. +The qhT* pointer is the first argument to most Qhull routines. It allows multiple instances of Qhull to run at the same time. +It simplifies the C++ interface to Qhull. + +<p>New code should be written with libqhull_r. Existing users of libqhull should consider converting to libqhull_r. +Although libqhull will be supported indefinitely, improvements may not be implemented. +Reentrant qhull is 1-2% slower than non-reentrant qhull. + +<p><b>Note:</b> Reentrant Qhull is <i>not</i> thread safe. Do not invoke Qhull routines with the same qhT* pointer from multiple threads. + +<h2><a href="#TOC">»</a><a name="convert">How to convert</a> code to reentrant Qhull</h2> + +<p>C++ users need to convert to libqhull_r. +The new C++ interface does a better, but not perfect, job of hiding Qhull's C data structures. +The previous C++ interface was unusual due to Qhull's global data structures. + +<p>All other users should consider converting to libqhull_r. The conversion is straight forward. +The original conversion of libqhull to libqhull_r required thousands of changes, mostly global +search and replace. The first run of Qhull (unix_r.c) produced the same +output, and nearly the same log files, as the original (unix.c). + +<p>Suggestions to help with conversion. +<ul> +<li>Compare qconvex_r.c with qconvex.c. Define a qhT object and a pointer it. The qhT* pointer is the first argument to most Qhull functions. +Clear <tt>qh_qh-<NOerrext</tt> before calling qh_initflags(). Invoke QHULL_LIB_CHECK to check for a compatible Qhull library. +<li>Compare user_eg2_r.c with user_eg2.c +<li>Compare user_eg_r.c with user_eg.c. If you use qhT before invoking qh_init_A, call qh_zero() to clear the qhT object. +user_eg_r.c includes multiple Qhull runs. +<li>Review user_eg3_r.cpp. As with the other programs, invoke QHULL_LIB_CHECK. +Simple C++ programs should compile as is. +<li>Compare QhullFacet.cpp with the same file in Qhull-2012.1. UsingLibQhull was replaced with the macro QH_TRY_() and '<tt>qh_qh-<NOerrext= true</tt>'. +<li>For detailed notes on libqhull_r, see "libqhull_r (reentrant Qhull)" and "Source code changes for libqhull_r" in <a href="../src/Changes.txt">Changes.txt</a>. +<li>For detailed notes on libqhullcpp, see "C++ interface" and following sections in <a href="../src/Changes.txt">Changes.txt</a>. +<li>For regexps and conversion notes, see <a href="http://www.qhull.org/html/README_r.txt">README_r.txt</a> (unedited). +</ul> + +<h2><a href="#TOC">»</a><a name="64bit">Qhull on 64-bit computers</a></h2> + +<p>Qhull compiles for 64-bit hosts. Since the size of a pointer on a 64-bit host is double the size on a 32-bit host, +memory consumption increases about 50% for simplicial facets and up-to 100% for non-simplicial facets. + +<p>You can check memory consumption with option <a href="qh-optt.htm#Ts">Ts</a>. It includes the size of +each data structure: +<ul> +<li>32-bit -- merge 24 ridge 20 vertex 28 facet 88 normal 24 ridge vertices 16 facet vertices or neighbors 20 +<li>64-bit -- merge 32 ridge 32 vertex 48 facet 120 normal 32 ridge vertices 40 facet vertices or neighbors 48 +</ul> + +<p>For Qhull 2015, the maximum identifier for ridges, vertices, and facets was increased +from 24-bits to 32-bits. This allows for larger convex hulls, but may increase the size of +the corresponding data structures. The sizes for Qhull 2012.1 were +<ul> +<li>32-bit -- merge 24 ridge 16 vertex 24 facet 88 +<li>64-bit -- merge 32 ridge 32 vertex 40 facet 120 +</ul> + +<h2><a href="#TOC">»</a><a name="cpp">Calling Qhull from +C++ programs</a></h2> + +<p>Qhull 2015 uses reentrant Qhull for its C++ interface. If you used +the C++ interface from qhull 2012.1, you may need to adjust how you initialize and use +the Qhull classes. See <a href="#convert">How to convert code to reentrant Qhull</a>. + +<p> +Qhull's C++ interface allows you to explore the results of running Qhull. +It provides access to Qhull's data structures. +Most of the classes derive from the corresponding qhull data structure. +For example, <a href="#facet-cpp">QhullFacet</a> is an instance of Qhull's <a href="../src/libqhull_r/libqhull_r.h#facetT">facetT</a>. +</p> + +<p>You can retain most of the data in Qhull and use the C++ interface to explore its results. +Each object contains a reference the Qhull's data structure (via QhullQh), making the C++ representation less memory efficient. +</p> + +<p>Besides using the C++ interface, you can also use libqhull_r directly. For example, +the FOREACHfacet_(...) macro will visit each facet in turn. +</p> + +<p>The C++ interface to Qhull is incomplete. You may need to extend the interface. +If so, you will need to understand Qhull's data structures and read the code. + +Example (c.f., <code>user_eg3 eg-100</code>). It prints the facets generated by Qhull. + +<pre> + RboxPoints rbox; + rbox.appendRandomPoints("100"); + Qhull qhull; + qhull.runQhull("", rbox); + QhullFacetList facets(qhull); + cout<< facets; +</pre> + +<p> +The C++ iterface for RboxPoints redefines the fprintf() calls +in rboxlib.c. Instead of writing its output to stdout, RboxPoints appends +the output to a std::vector. +The same technique may be used for calling Qhull from C++. +</p> +<ul><li> +Run Qhull with option '<a href="qh-optt.htm#Ta">Ta</a>' to annotate the +output with qh_fprintf() identifiers. +</li><li> +Redefine qh_fprintf() for these identifiers. +</li><li> +See RboxPoints.cpp for an example. +</li></ul> +<p> +Since the C++ interface uses reentrant Qhull, multiple threads may run Qhull at the same time. Each thread is +one run of Qhull. +</p> + +<p> +Do <i>not</i> have two threads accessing the same Qhull instance. Qhull is not thread-safe. +</p> + +<h3><a href="#TOC">»</a><a name="coordinate-cpp">CoordinateIterator</a></h3> +<p> +A CoordinateIterator or ConstCoordinateIterator [RboxPoints.cpp] is a <code>std::vector<realT>::iterator</code> for Rbox and Qhull coordinates. +It is the result type of <a href="#rbox-cpp">RboxPoints</a>.coordinates(). +</p> + +<p>Qhull does not use CoordinateIterator for its data structures. A point in Qhull is an array of reals instead of a std::vector. +See <a href="#point-cpp">QhullPoint</a>. +</p> + +<h3><a href="#TOC">»</a><a name="qhull-cpp">Qhull</a></h3> +<p> +Qhull is the top-level class for running Qhull. +It initializes Qhull, runs the computation, and records errors. +It provides access to the global data structure <a href="#qh-cpp">QhullQh</a>, +Qhull's <a href="#facet-cpp">facets</a>, and <a href="#vertex-cpp">vertices</a>. +</p> + +<h3><a href="#TOC">»</a><a name="error-cpp">QhullError</a></h3> +<p> +QhullError is derived from <code>std::exception</code>. It reports errors from Qhull and captures the output to stderr. +</p> + +<p> +If error handling is not set up, Qhull exits with a code from 1 to 5. The codes are defined by +qh_ERR* in libqhull_r.h. The exit is via qh_exit() in usermem_r.c. +The C++ interface does not report the +captured output in QhullError. Call Qhull::setErrorStream to send output to cerr instead. +</p> + +<h3><a href="#TOC">»</a><a name="facet-cpp">QhullFacet</a></h3> +<p> +A QhullFacet is a facet of the convex hull, a region of the Delaunay triangulation, a vertex of a Voronoi diagram, +or an intersection of the halfspace intersection about a point. +A QhullFacet has a set of <a href="#vertex-cpp">QhullVertex</a>, a set of <a href="#ridge-cpp">QhullRidge</a>, and +a set of neighboring QhullFacets. +</p> + +<h3><a href="#TOC">»</a><a name="facetlist-cpp">QhullFacetList</a></h3> +<p> +A QhullFacetList is a linked list of <a href="#facet-cpp">QhullFacet</a>. The result of <code>Qhull.runQhull</code> is a QhullFacetList stored +in <a href="#qh-cpp">QhullQh</a>. +</p> + +<h3><a href="#TOC">»</a><a name="facetset-cpp">QhullFacetSet</a></h3> +<p> +A QhullFacetSet is a <a href="#set-cpp">QhullSet</a> of <a href="#facet-cpp">QhullFacet</a>. QhullFacetSet may be ordered or unordered. The neighboring facets of a QhullFacet is a QhullFacetSet. +The neighbors of a <a href="#facet-cpp">QhullFacet</a> is a QhullFacetSet. +The neighbors are ordered for simplicial facets, matching the opposite vertex of the facet. +</p> + +<h3><a href="#TOC">»</a><a name="iterator-cpp">QhullIterator</a></h3> +<p> +QhullIterator contains macros for defining Java-style iterator templates from a STL-style iterator template. +</p> + +<h3><a href="#TOC">»</a><a name="linkedlist-cpp">QhullLinkedList</a></h3> +<p> +A QhullLinkedLIst is a template for linked lists with next and previous pointers. +<a href="#facetlist-cpp">QhullFacetList</a> and <a href="#facetlist-cpp">QhullVertexList</a> are QhullLinkedLists. +</p> + +<h3><a href="#TOC">»</a><a name="point-cpp">QhullPoint</a></h3> +<p> +A QhullPoint is an array of point coordinates, typically doubles. The length of the array is <a href="#qh-cpp">QhullQh</a>.hull_dim. +The identifier of a QhullPoint is its 0-based index from QhullQh.first_point followed by QhullQh.other_points. +</p> + +<h3><a href="#TOC">»</a><a name="pointset-cpp">QhullPointSet</a></h3> +<p> +A QhullPointSet is a <a href="#set-cpp">QhullSet</a> of <a href="#point-cpp">QhullPoint</a>. The QhullPointSet of a <a href="#facet-cpp">QhullFacet</a> is its coplanar points. +</p> + +<h3><a href="#TOC">»</a><a name="qh-cpp">QhullQh</a></h3> +<p> +QhullQh is the root of Qhull's data structure. +It contains initialized constants, sets, buffers, and variables. +It contains an array and a set of <a href="#point-cpp">QhullPoint</a>, +a list of <a href="#facet-cpp">QhullFacet</a>, and a list of <a href="#vertex-cpp">QhullVertex</a>. +The points are the input to Qhull. The facets and vertices are the result of running Qhull. +</p> + +<p> +Qhull's functions access QhullQh through the global variable, <code>qh_qh</code>. +The global data structures, qh_stat and qh_mem, record statistics and manage memory respectively. +</p> + +<h3><a href="#TOC">»</a><a name="ridge-cpp">QhullRidge</a></h3> + +<p> +A QhullRidge represents the edge between two <a href="#facet-cpp">QhullFacet</a>'s. +It is always simplicial with qh.hull_dim-1 <a href="#vertex-cpp">QhullVertex</a>)'s. +</p> + +<h3><a href="#TOC">»</a><a name="ridgeset-cpp">QhullRidgeSet</a></h3> + +<p> +A QhullRidgeSet is a <a href="#set-cpp">QhullSet</a> of <a href="#ridge-cpp">QhullRidge</a>. Each <a href="#facet-cpp">QhullFacet</a> contains a QhullRidgeSet. +</p> + +<h3><a href="#TOC">»</a><a name="set-cpp">QhullSet</a></h3> + +<p> +A QhullSet is a set of pointers to objects. QhullSets may be ordered or unordered. They are the core data structure for Qhull. +</p> + +<h3><a href="#TOC">»</a><a name="vertex-cpp">QhullVertex</a></h3> + +<p> +A QhullVertex is a vertex of the convex hull. A simplicial <a href="#facet-cpp">QhullFacet</a> has qh.hull_dim-1 vertices. A QhullVertex contains a <a href="#point-cpp">QhullPoint</a>. +It may list its neighboring <a href="#facet-cpp">QhullFacet</a>'s. +</p> + +<h3><a href="#TOC">»</a><a name="vertexlist-cpp">QhullVertexList</a></h3> + +<p> +A QhullVertexList is a <a href="#linkedlist-cpp">QhullLinkedList</a> of <a href="#vertex-cpp">QhullVertex</a>. +The global data structure, <a href="#qh-cpp">QhullQh</a> contains a QhullVertexList of all +the vertices. +</p> + +<h3><a href="#TOC">»</a><a name="vertexset-cpp">QhullVertexSet</a></h3> + +<p> +A QhullVertexSet is a <a href="#set-cpp">QhullSet</a> of <a href="#vertex-cpp">QhullVertex</a>. +The QhullVertexSet of a <a href="#facet-cpp">QhullFacet</a> is the vertices of the facet. It is +ordered for simplicial facets and unordered for non-simplicial facets. +</p> + +<h3><a href="#TOC">»</a><a name="rbox-cpp">RboxPoints</a></h3> + +<p> +RboxPoints is a std::vector of point coordinates (<a href="#point-cpp">QhullPoint</a>). +It's iterator is <a href="#coordinate-cpp">CoordinateIterator</a>. +</p> +<p> +<code>RboxPoints.appendRandomPoints()</code> appends points from a variety of distributions such as uniformly distributed within a cube and random points on a sphere. +It can also append a cube's vertices or specific points. +</p> + +<h3><a href="#TOC">»</a><a name="questions-cpp">Cpp questions for Qhull</a></h3> + +Developing C++ code requires many conventions, idioms, and technical details. +The following questions have either +mystified the author or do not have a clear answer. See also +<a href="http://www.qhull.org/road/road-faq/xml/cpp-guideline.xml">C++ and Perl Guidelines</a>. +and FIXUP notes in the code. +Please add notes to <a href="http://github.com/qhull/qhull/wiki">Qhull Wiki</a>. + +<ul> +<li>FIXUP QH11028 Should return reference, but get reference to temporary +<pre>iterator Coordinates::operator++() { return iterator(++i); }</pre> +<li>size() as size_t, size_type, or int +<li>Should all containers have a reserve()? +<li>Qhull.feasiblePoint interface +<li>How to avoid copy constructor while logging, maybeThrowQhullMessage() +<li>How to configure Qhull output. Trace and results should go to stdout/stderr +<li>Qhull and RboxPoints messaging. e.g., ~Qhull, hasQhullMessage(). Rename them as QhullErrorMessage? +<li>How to add additional output to an error message, e.g., qh_setprint +<li>Is idx the best name for an index? It's rather cryptic, but BSD strings.h defines index(). +<li>Qhull::feasiblePoint Qhull::useOutputStream as field or getter? +<li>Define virtual functions for user customization of Qhull (e.g., qh_fprintf, qh_memfree,etc.) +<li>Figure out RoadError::global_log. clearQhullMessage currently clearGlobalLog +<li>Should the false QhullFacet be NULL or empty? e.g., QhullFacet::tricoplanarOwner() and QhullFacetSet::end() +<li>Should output format for floats be predefined (qh_REAL_1, 2.2g, 10.7g) or as currently set for stream +<li>Should cout << !point.defined() be blank or 'undefined' +<li>Infinite point as !defined() +<li>qlist and qlinkedlist define pointer, reference, size_type, difference_type, const_pointer, const_reference for the class but not for iterator and const_iterator + vector.h -- <pre>reference operator[](difference_type _Off) const</pre> +<li>When forwarding an implementation is base() an approriate name (e.g., Coordinates::iterator::base() as std::vector<coordT>::iterator). +<li>When forwarding an implementation, does not work "returning address of temporary" +<li>Also --, +=, and -= + <pre>iterator &operator++() { return iterator(i++); }</pre> +<li>if vector<coordT> inheritance is bad, is QhullVertexSet OK? +<li>Should QhullPointSet define pointer and reference data types? +</ul> + +<h2><a href="#TOC">»</a><a name="library">Calling Qhull from +C programs</a></h2> + +<p><b>Warning:</b> Qhull was not designed for calling from C +programs. You may find the <a href="#cpp">C++ interface</a> easier to use. +You will need to understand the data structures and read the code. +Most users will find it easier to call Qhull as an external +command. + +<p>For examples of calling Qhull, see GNU Octave's +<a href=http://www.gnu.org/software/octave/doc/interpreter/Geometry.html>computational geometry code</a>, +and Qhull's +<a href=../src/user_eg/user_eg_r.c>user_eg_r.c</a>, +<a href=../src/user_eg2/user_eg2_r.c>user_eg2_r.c</a>, and +<a href=../src/libqhull_r/user_r.c>user_r.c</a>. To see how Qhull calls its library, read +<a href=../src/qhull/unix_r.c>unix_r.c</a>, +<a href=../src/qconvex/qconvex.c>qconvex.c</a>, +<a href=../src/qdelaunay/qdelaun.c>qdelaun.c</a>, +<a href=../src/qhalf/qhalf.c>qhalf.c</a>, and +<a href=../src/qvoronoi/qvoronoi.c>qvoronoi.c</a>. The '*_r.c' files are reentrant, otherwise they are non-reentrant. +Either version may be used. New code should use reentrant Qhull. + +<p>See <a href="../src/libqhull_r/index.htm">Reentrant Qhull functions, macros, and data +structures</a> for internal documentation of Qhull. The +documentation provides an overview and index. To use the library +you will need to read and understand the code. For most users, it +is better to write data to a file, call the qhull program, and +read the results from the output file.</p> + +<p>If you use non-reentrant Qhull, be aware of the macros "qh" +and "qhstat", e.g., "qh hull_dim". They are +defined in <tt>libqhull.h</tt>. They allow the global data +structures to be pre-allocated (faster access) or dynamically +allocated (allows multiple copies). </p> + +<p>Qhull's <tt>Makefile</tt> produces a library, <tt>libqhull_r.a</tt>, +for inclusion in your programs. First review <tt>libqhull_r.h</tt>. +This defines the data structures used by Qhull and provides +prototypes for the top-level functions. +Most users will only need libqhull_r.h in their programs. For +example, the Qhull program is defined with <tt>libqhull_r.h</tt> and <tt>unix_r.c</tt>. +To access all functions, use <tt>qhull_ra.h</tt>. Include the file +with "<tt>#include <libqhull_r/qhull_ra.h></tt>". This +avoids potential name conflicts.</p> + +<p>If you use the Qhull library, you are on your own as far as +bugs go. Start with small examples for which you know the output. +If you get a bug, try to duplicate it with the Qhull program. The +'<a href="qh-optt.htm#Tc">Tc</a>' option will catch many problems +as they occur. When an error occurs, use '<a +href="qh-optt.htm#Tn">T4</a> <a href="qh-optt.htm#TPn">TPn</a>' +to trace from the last point added to the hull. Compare your +trace with the trace output from the Qhull program.</p> + +<p>Errors in the Qhull library are more likely than errors in the +Qhull program. These are usually due to feature interactions that +do not occur in the Qhull program. Please report all errors that +you find in the Qhull library. Please include suggestions for +improvement. </p> + +<h3><a href="#TOC">»</a><a name="exit">How to avoid exit(), fprintf(), stderr, and stdout</a></h3> + +<p>Qhull sends output to qh.fout and errors, log messages, and summaries to qh.ferr. qh.fout is normally +stdout and qh.ferr is stderr. qh.fout may be redefined by option '<a +href="qh-optt.htm#TO">TO</a>' or the caller. qh.ferr may be redirected to qh.fout by option '<a +href="qh-optt.htm#Tz">Tz</a>'.</p> + +<p>Qhull does not use stderr, stdout, fprintf(), or exit() directly.</p> + +<p>Qhull reports errors via qh_errexit() by writting a message to qh.ferr and invoking longjmp(). +This returns the caller to the corresponding setjmp() (c.f., QH_TRY_ in QhullQh.h). If +qh_errexit() is not available, Qhull functions call qh_exit(). qh_exit() normally calls exit(), +but may be redefined by the user. An example is +libqhullcpp/usermem_r-cpp.cpp. It redefines qh_exit() as a 'throw'.</p> + +<p>If qh_meminit() or qh_new_qhull() is called with ferr==NULL, then they set ferr to stderr. +Otherwise the Qhull libraries use qh->ferr and qh->qhmem.ferr for error output.</p> + +<p>If an error occurs before qh->ferr is initialized, Qhull invokes qh_fprintf_stderr(). The user +may redefine this function along with qh_exit(), qh_malloc(), and qh_free(). + +<p>The Qhull libraries write output via qh_fprintf() [userprintf_r.c]. Otherwise, the Qhull +libraries do not use stdout, fprintf(), or printf(). Like qh_exit(), the user may redefine +qh_fprintf().</p> + +<h3><a href="#TOC">»</a><a name="mem">sets and quick memory +allocation</a></h3> + +<p>You can use <tt>mem_r.c</tt> and <tt>qset_r.c</tt> individually. <tt>Mem_r.c +</tt>implements quick-fit memory allocation. It is faster than +malloc/free in applications that allocate and deallocate lots of +memory. </p> + +<p><tt>Qset_r.c</tt> implements sets and related collections. It's +the inner loop of Qhull, so speed is more important than +abstraction. Set iteration is particularly fast. <tt>qset_r.c</tt> +just includes the functions needed for Qhull. </p> + +<h3><a href="#TOC">»</a><a name="dids">Delaunay triangulations +and point indices</a></h3> + +<p>Here some unchecked code to print the point indices of each +Delaunay triangle. Use option 'QJ' if you want to avoid +non-simplicial facets. Note that upper Delaunay regions are +skipped. These facets correspond to the furthest-site Delaunay +triangulation. </p> + +<blockquote> + <pre> + facetT *facet; + vertexT *vertex, **vertexp; + + FORALLfacets { + if (!facet->upperdelaunay) { + printf ("%d", qh_setsize (facet->vertices); + FOREACHvertex_(facet->vertices) + printf (" %d", qh_pointid (vertex->point)); + printf ("\n"); + } + } + +</pre> +</blockquote> + +<h3><a href="#TOC">»</a><a name="findfacet">locate a facet with +qh_findbestfacet()</a></h3> + +<p>The routine qh_findbestfacet in <tt>poly2_r.c</tt> is +particularly useful. It uses a directed search to locate the +facet that is furthest below a point. For Delaunay +triangulations, this facet is the Delaunay triangle that contains +the lifted point. For convex hulls, the distance of a point to +the convex hull is either the distance to this facet or the +distance to a subface of the facet.</p> + +<blockquote> +<p><b>Warning:</b> If triangulated output ('<a href=qh-optq.htm#Qt>Qt</a>') and +the best facet is triangulated, qh_findbestfacet() returns one of +the corresponding 'tricoplanar' facets. The actual best facet may be a different +tricoplanar facet. +<p> +See qh_nearvertex() in poly2.c for sample code to visit each +tricoplanar facet. To identify the correct tricoplanar facet, +see Devillers, et. al., [<a href="index.htm#devi01">'01</a>] +and Mucke, et al [<a href="index.htm#muck96">'96</a>]. If you +implement this test in general dimension, please notify +<a href="mailto:qhull@qhull.org">qhull@qhull.org</a>. +</blockquote> + +<p>qh_findbestfacet performs an exhaustive search if its directed +search returns a facet that is above the point. This occurs when +the point is inside the hull or if the curvature of the convex +hull is less than the curvature of a sphere centered at the point +(e.g., a point near a lens-shaped convex hull). When the later +occurs, the distance function is bimodal and a directed search +may return a facet on the far side of the convex hull. </p> + +<p>Algorithms that retain the previously constructed hulls +usually avoid an exhaustive search for the best facet. You may +use a hierarchical decomposition of the convex hull [Dobkin and +Kirkpatrick <a href="index.htm#dob-kir90">'90</a>]. </p> + +<p>To use qh_findbestfacet with Delaunay triangulations, lift the +point to a paraboloid by summing the squares of its coordinates +(see qh_setdelaunay in geom2_r.c). Do not scale the input with +options 'Qbk', 'QBk', 'QbB' or 'Qbb'. See Mucke, et al [<a +href="index.htm#muck96">'96</a>] for a good point location +algorithm.</p> + +<p>The intersection of a ray with the convex hull may be found by +locating the facet closest to a distant point on the ray. +Intersecting the ray with the facet's hyperplane gives a new +point to test. </p> + +<h3><a href="#TOC">»</a><a name="inc">on-line construction with +qh_addpoint()</a></h3> + +<p>The Qhull library may be used for the on-line construction of +convex hulls, Delaunay triangulations, and halfspace +intersections about a point. It may be slower than implementations that retain +intermediate convex hulls (e.g., Clarkson's <a +href="http://www.netlib.org/voronoi/hull.html">hull +program</a>). These implementations always use a directed search. +For the on-line construction of convex hulls and halfspace +intersections, Qhull may use an exhaustive search +(qh_findbestfacet). </p> + +<p>You may use qh_findbestfacet and qh_addpoint (<tt>libqhull.c</tt>) to add a point to +a convex hull. Do not modify the point's coordinates since +qh_addpoint does not make a copy of the coordinates. For Delaunay +triangulations, you need to lift the point to a paraboloid by +summing the squares of the coordinates (see qh_setdelaunay in +geom2.c). Do not scale the input with options 'Qbk', 'QBk', 'QbB' +or 'Qbb'. Do not deallocate the point's coordinates. You need to +provide a facet that is below the point (<a href="#findfacet">qh_findbestfacet</a>). +</p> + +<p>You can not delete points. Another limitation is that Qhull +uses the initial set of points to determine the maximum roundoff +error (via the upper and lower bounds for each coordinate). </p> + +<p>For many applications, it is better to rebuild the hull from +scratch for each new point. This is especially true if the point +set is small or if many points are added at a time.</p> + +<p>Calling qh_addpoint from your program may be slower than +recomputing the convex hull with qh_qhull. This is especially +true if the added points are not appended to the qh first_point +array. In this case, Qhull must search a set to determine a +point's ID. [R. Weber] </p> + +<p>See user_eg.c for examples of the on-line construction of +convex hulls, Delaunay triangulations, and halfspace +intersections. The outline is: </p> + +<blockquote> + <pre> +initialize qhull with an initial set of points +qh_qhull(); + +for each additional point p + append p to the end of the point array or allocate p separately + lift p to the paraboloid by calling qh_setdelaunay + facet= qh_findbestfacet (p, !qh_ALL, &bestdist, &isoutside); + if (isoutside) + if (!qh_addpoint (point, facet, False)) + break; /* user requested an early exit with 'TVn' or 'TCn' */ + +call qh_check_maxout() to compute outer planes +terminate qhull</pre> +</blockquote> + +<h3><a href="#TOC">»</a><a name="constrained">Constrained +Delaunay triangulation </a></h3> + +<p>With a fair amount of work, Qhull is suitable for constrained +Delaunay triangulation. See Shewchuk, ACM Symposium on +Computational Geometry, Minneapolis 1998.</p> + +<p>Here's a quick way to add a constraint to a Delaunay +triangulation: subdivide the constraint into pieces shorter than +the minimum feature separation. You will need an independent +check of the constraint in the output since the minimum feature +separation may be incorrect. [H. Geron] </p> + +<h3><a href="#TOC">»</a><a name="tricoplanar">Tricoplanar facets and option 'Qt'</h3> + +<p>Option '<a href=qh-optq.htm#Qt>Qt</a>' triangulates non-simplicial +facets (e.g., a square facet in 3-d or a cubical facet in 4-d). +All facets share the same apex (i.e., the first vertex in facet->vertices). +For each triangulated facet, Qhull +sets facet->tricoplanar true and copies facet->center, facet->normal, facet->offset, and facet->maxoutside. One of +the facets owns facet->normal; its facet->keepcentrum is true. +If facet->isarea is false, facet->triowner points to the owning +facet. + +<p>Qhull sets facet->degenerate if the facet's vertices belong +to the same ridge of the non-simplicial facet. + +<p>To visit each tricoplanar facet of a non-simplicial facet, +either visit all neighbors of the apex or recursively visit +all neighbors of a tricoplanar facet. The tricoplanar facets +will have the same facet->center.</p> + +<p>See <a href=../src/libqhull_r/io_r.c#detvridge>qh_detvridge</a> for an example of ignoring tricoplanar facets.</p> + +<h3><a href="#TOC">»</a><a name="vertices">Voronoi vertices of a +region</a></h3> + +<p>The following code iterates over all Voronoi vertices for each +Voronoi region. Qhull computes Voronoi vertices from the convex +hull that corresponds to a Delaunay triangulation. An input site +corresponds to a vertex of the convex hull and a Voronoi vertex +corresponds to an adjacent facet. A facet is +"upperdelaunay" if it corresponds to a Voronoi vertex +"at-infinity". Qhull uses qh_printvoronoi in <tt>io.c</tt> +for '<a href=qvoronoi.htm>qvoronoi</a> <a href="qh-opto.htm#o">o'</a> </p> + +<blockquote> + <pre> +/* please review this code for correctness */ +qh_setvoronoi_all(); +FORALLvertices { + site_id = qh_pointid (vertex->point); + if (qh hull_dim == 3) + qh_order_vertexneighbors(vertex); + infinity_seen = 0; + FOREACHneighbor_(vertex) { + if (neighbor->upperdelaunay) { + if (!infinity_seen) { + infinity_seen = 1; + ... process a Voronoi vertex "at infinity" ... + } + }else { + voronoi_vertex = neighbor->center; + ... your code goes here ... + } + } +} +</pre> +</blockquote> + +<h3><a href="#TOC">»</a><a name="ridge">Voronoi vertices of a +ridge</a></h3> + +<p>Qhull uses qh_printvdiagram() in io.c to print the ridges of a +Voronoi diagram for option '<a href="qh-optf.htm#Fv2">Fv</a>'. +The helper function qh_eachvoronoi() does the real work. It calls +the callback 'printvridge' for each ridge of the Voronoi diagram. +</p> + +<p>You may call qh_printvdiagram2(), qh_eachvoronoi(), or +qh_eachvoronoi_all() with your own function. If you do not need +the total number of ridges, you can skip the first call to +qh_printvdiagram2(). See qh_printvridge() and qh_printvnorm() in +io.c for examples. </p> + +<h3><a href="#TOC">»</a><a name="vneighbor">vertex neighbors of +a vertex</a></h3> + +<p>To visit all of the vertices that share an edge with a vertex: +</p> + +<ul> + <li>Generate neighbors for each vertex with + qh_vertexneighbors in <tt>poly2.c</tt>. </li> + <li>For simplicial facets, visit the vertices of each + neighbor </li> + <li>For non-simplicial facets, <ul> + <li>Generate ridges for neighbors with qh_makeridges + in <tt>merge.c</tt>. </li> + <li>Generate ridges for a vertex with qh_vertexridges + in <tt>merge.c</tt>. </li> + <li>Visit the vertices of these ridges. </li> + </ul> + </li> +</ul> + +<p>For non-simplicial facets, the ridges form a simplicial +decomposition of the (d-2)-faces between each pair of facets -- +if you need 1-faces, you probably need to generate the full face +graph of the convex hull. </p> + +<h2><a href="#TOC">»</a><a name="performance">Performance of +Qhull </a></h2> + +<p>Empirically, Qhull's performance is balanced in the sense that +the average case happens on average. This may always be true if +the precision of the input is limited to at most <i>O(log n)</i> +bits. Empirically, the maximum number of vertices occurs at the +end of constructing the hull. </p> + +<p>Let <i>n</i> be the number of input points, <i>v</i> be the +number of output vertices, and <i>f_v </i>be the maximum number +of facets for a convex hull of <i>v</i> vertices. If both +conditions hold, Qhull runs in <i>O(n log v)</i> in 2-d and 3-d +and <i>O(n f_v/v)</i> otherwise. The function <i>f_v</i> +increases rapidly with dimension. It is <em>O(v^floor(d/2) / +floor(d/2)!)</em>.</p> + +<p>The time complexity for merging is unknown. Options '<a +href="qh-optc.htm#C0">C-0</a>' and '<a href="qh-optq.htm#Qx">Qx</a>' +(defaults) handle precision problems due to floating-point +arithmetic. They are optimized for simplicial outputs. </p> + +<p>When running large data sets, you should monitor Qhull's +performance with the '<a href="qh-optt.htm#TFn">TFn</a>' option. +The time per facet is approximately constant. In high-d with many +merged facets, the size of the ridge sets grows rapidly. For +example the product of 8-d simplices contains 18 facets and +500,000 ridges. This will increase the time needed per facet. </p> + +<p>As dimension increases, the number of facets and ridges in a +convex hull grows rapidly for the same number of vertices. For +example, the convex hull of 300 cospherical points in 6-d has +30,000 facets. </p> + +<p>If Qhull appears to stop processing facets, check the memory +usage of Qhull. If more than 5-10% of Qhull is in virtual memory, +its performance will degrade rapidly. </p> + +<p>When building hulls in 20-d and higher, you can follow the +progress of Qhull with option '<a href="qh-optt.htm#Tn">T1</a>'. +It reports each major event in processing a point. </p> + +<p>To reduce memory requirements, recompile Qhull for +single-precision reals (REALfloat in <tt>user.h</tt>). +Single-precision does not work with joggle ('<a +href="qh-optq.htm#QJn">QJ</a>'). Check qh_MEMalign in <tt>user.h</tt> +and the match between free list sizes and data structure sizes +(see the end of the statistics report from '<a +href="qh-optt.htm#Ts">Ts</a>'). If free list sizes do not match, +you may be able to use a smaller qh_MEMalign. Setting +qh_COMPUTEfurthest saves a small amount of memory, as does +clearing qh_MAXoutside (both in <tt>user.h</tt>).</p> + +<p>Shewchuk is working on a 3-d version of his triangle +program. It is optimized for 3-d simplicial Delaunay triangulation +and uses less memory than Qhull.</p> + +<p>To reduce the size of the Qhull executable, consider +qh_NOtrace and qh_KEEPstatistics 0 in <tt>user.h</tt>. By +changing <tt>user.c </tt>you can also remove the input/output +code in <tt>io.c</tt>. If you don't need facet merging, then +version 1.01 of Qhull is much smaller. It contains some bugs that +prevent Qhull from initializing in simple test cases. It is +slower in high dimensions.</p> + +<p>The precision options, '<a href="qh-optc.htm#Vn">Vn</a>', '<a +href="qh-optc.htm#Wn">Wn</a>', '<a href="qh-optc.htm#Un">Un</a>'. +'<a href="qh-optc.htm#An">A-n</a>', '<a href="qh-optc.htm#Cn">C-n</a>', +'<a href="qh-optc.htm#An2">An</a>', '<a href="qh-optc.htm#Cn2">Cn</a>', +and '<a href="qh-optq.htm#Qx">Qx</a>', may have large effects on +Qhull performance. You will need to experiment to find the best +combination for your application. </p> + +<p>The verify option ('<a href="qh-optt.htm#Tv">Tv</a>') checks +every point after the hull is complete. If facet merging is used, +it checks that every point is inside every facet. This can take a +very long time if there are many points and many facets. You can +interrupt the verify without losing your output. If facet merging +is not used and there are many points and facets, Qhull uses a +directed search instead of an exhaustive search. This should be +fast enough for most point sets. Directed search is not used for +facet merging because directed search was already used for +updating the facets' outer planes.</p> + +<p>The check-frequently option ('<a href="qh-optt.htm#Tc">Tc</a>') +becomes expensive as the dimension increases. The verify option +('<a href="qh-optt.htm#Tv">Tv</a>') performs many of the same +checks before outputting the results.</p> + +<p>Options '<a href="qh-optq.htm#Q0">Q0</a>' (no pre-merging), '<a +href="qh-optq.htm#Q3">Q3</a>' (no checks for redundant vertices), +'<a href="qh-optq.htm#Q5">Q5</a>' (no updates for outer planes), +and '<a href="qh-optq.htm#Q8">Q8</a>' (no near-interior points) +increase Qhull's speed. The corresponding operations may not be +needed in your application.</p> + +<p>In 2-d and 3-d, a partial hull may be faster to produce. +Option '<a href="qh-optq.htm#QGn">QgGn</a>' only builds facets +visible to point n. Option '<a href="qh-optq.htm#QVn">QgVn</a>' +only builds facets that contain point n. In higher-dimensions, +this does not reduce the number of facets.</p> + +<p><tt>User.h</tt> includes a number of performance-related +constants. Changes may improve Qhull performance on your data +sets. To understand their effect on performance, you will need to +read the corresponding code. </p> + +<p>GNU <tt>gprof</tt> reports that the dominate cost for 3-d +convex hull of cosperical points is qh_distplane(), mainly called +from qh_findbestnew(). The dominate cost for 3-d Delaunay triangulation +is creating new facets in qh_addpoint(), while qh_distplane() remains +the most expensive function. + +</p> +<h2><a href="#TOC">»</a><a name="enhance">Enhancements to Qhull </a></h2> + +<p>There are many ways in which Qhull can be improved. </p> + +<pre> +[Jan 2016] Suggestions +------------ +To do for a future verson of Qhull + - Add a post-merge pass for Delaunay slivers. Merge into a neighbor with a circumsphere that includes the opposite point. [M. Treacy] + - Add a merge pass before cone creation to remove duplicate subridges between horizon facets + - Option to add a bounding box for Delaunay triangulations, e,g., nearly coincident points + - Report error when rbox Cn,r,m does not produce points (e.g., 'r' distributions) + - Rescale output to match 'QbB' on input [J. Metz, 1/30/2014 12:21p] + - Run through valgrind + - Notes to compgeom on conformant triangulation and Voronoi volume + - Git: Create signed tags for Qhull versions + - Implement weighted Delaunay triangulation and weighted Voronoi diagram [A. Liebscher] + e.g., Sugihara, "Three-dimensional convex hull as a fruitful source of diagrams," Theoretical Computer Science, 2000, 235:325-337 + - testqset: test qh_setdelnth and move-to-front + - Makefile: Re-review gcc/g++ warnings. OK in 2011. + - Break up -Wextra into its components or figure out how to override -Wunused-but-set-variable + unused-but-set-variable is reporting incorrectly. All instances are annotated. + - CMakelists.txt: Why are files duplicated for cmake build + - CMakeLists.txt: configure the 'ctest' target + - The size of maxpoints in qh_maxsimplex should be d+3 unique points to help avoid QH6154 + + - Can countT be defined as 'int', 'unsigned int', or 64-bit int? + countT is currently defined as 'int' in qset_r.h + Vertex ID and ridge ID perhaps should be countT, They are currently 'unsigned' + Check use of 'int' vs. countT in all cpp code + Check use of 'int' vs. countT in all c code + qset_r.h defines countT -- duplicates code in user_r.h -- need to add to qset.h/user.h + countT -1 used as a flag in Coordinates.mid(), QhullFacet->id() + Also QhullPoints indexOf and lastIndexOf + Also QhullPointSet indexOf and lastIndexOf + Coordinates.indexOf assumes countT is signed (from end) + Coordinates.lastIndexOf assumes countT is signed (from end) + All error messages with countT are wrong, convert to int? + RboxPoints.qh_fprintf_rbox, etc. message 9393 assumes countT but may be int, va_arg(args, countT); Need to split + +------------ +To do for a furture version of the C++ interface + - Fix C++ memory leak in user_eg3 [M. Sandim] + - Document C++ using Doxygen conventions (//! and //!<) + - Should Qhull manage the output formats for doubles? QH11010 user_r.h defines qh_REAL_1 as %6.8g + - Allocate memory for QhullSet using Qhull.qhmem. Create default constructors for QhullVertexSet etc. Also mid() etc. + - Add interior point for automatic translation? + - Add hasNext() to all next() iterators (e.g., QhullVertex) + - Add defineAs() to each object + - Write a program with concurrent Qhull + - Write QhullStat and QhullStat_test + - Add QList and vector instance of facetT*, etc. + - Generalize QhullPointSetIterator + - qh-code.htm: Document changes to C++ interface. + Organize C++ documentation into collection classes, etc. + - Review all C++ classes and C++ tests + - QhullVertexSet uses QhullSetBase::referenceSetT() to free it's memory. Probably needed elsewhere + - The Boost Graph Library provides C++ classes for graph data structures. It may help + enhance Qhull's C++ interface [Dr. Dobb's 9/00 p. 29-38; OOPSLA '99 p. 399-414]. + +[Jan 2010] Suggestions + - Generate vcproj from qtpro files + cd qtpro && qmake -spec win32-msvc2005 -tp vc -recursive + sed -i 's/C\:\/bash\/local\/qhull\/qtpro\///' qhull-all.sln + Change qhullcpp to libqhull.dll + Allow both builds on same host (keep /tmp separate) + - Make distribution -- remove tmp, news, .git, leftovers from project, change CRLF + search for 2010.1, Dates + qhulltest --all added to output + Add md5sum + Add test of user_eg3, etc. + - C++ class for access to statistics, accumulate vs. add + - Add dialog box to RoadError-- a virtual function? + - Option 'Gt' does not make visible all facets of the mesh example, rbox 32 M1,0,1 | qhull d Gt + - Option to select bounded Voronoi regions [A. Uzunovic] + - Merge small volume boundary cells into unbounded regions [Dominik Szczerba] + - Postmerge with merge options + - Add const to C code + - Add modify operators and MutablePointCoordinateIterator to PointCoordinates + - Add Qtest::toString() functions for QhullPoint and others. QByteArray and qstrdup() + - Fix option Qt for conformant triangulations of merged facets + - Investigate flipped facet -- rbox 100 s D3 t1263080158 | qhull R1e-3 Tcv Qc + - Add doc comments to c++ code + - Measure performance of Qhull, seconds per point by dimension + - Report potential wraparound of 64-bit ints -- e.g., a large set or points + +Documentation +- Qhull::addPoint(). Problems with qh_findbestfacet and otherpoints see + qh-code.htm#inc on-line construction with qh_addpoint() +- How to handle 64-bit possible loss of data. WARN64, ptr_intT, size_t/int +- Show custom of qh_fprintf +- grep 'qh_mem ' x | sort | awk '{ print $2; }' | uniq -c | grep -vE ' (2|4|6|8|10|12|14|16|20|64|162)[^0-9]' +- qtpro/qhulltest contains .pro and Makefile. Remove Makefiles by setting shadow directory to ../../tmp/projectname +- Rules for use of qh_qh and multi processes + UsingQhull + errorIfAnotherUser + ~QhullPoints() needs ownership of qh_qh + Does !qh_pointer work? + When is qh_qh required? Minimize the time. + qhmem, qhstat.ferr + qhull_inuse==1 when qhull globals active [not useful?] + rbox_inuse==1 when rbox globals active + - Multithreaded -- call largest dimension for infinityPoint() and origin() + - Better documentation for qhmem totshort, freesize, etc. + - how to change .h, .c, and .cpp to text/html. OK in Opera + - QhullVertex.dimension() is not quite correct, epensive + - Check globalAngleEpsilon + - Deprecate save_qhull() + +[Dec 2003] Here is a partial list: + - fix finddelaunay() in user_eg.c for tricoplanar facets + - write a BGL, C++ interface to Qhull + http://www.boost.org/libs/graph/doc/table_of_contents.html + - change qh_save_qhull to swap the qhT structure instead of using pointers + - change error handling and tracing to be independent of 'qh ferr' + - determine the maximum width for a given set of parameters + - prove that directed search locates all coplanar facets + - in high-d merging, can a loop of facets become disconnected? + - find a way to improve inner hulls in 5-d and higher + - determine the best policy for facet visibility ('<a href="qh-optc.htm#Vn">Vn</a>') + - determine the limitations of '<a href="qh-optq.htm#Qg">Qg</a>' + +Precision improvements: + - For 'Qt', resolve cross-linked, butterfly ridges. + May allow retriangulation in qh_addpoint(). + - for Delaunay triangulations ('d' or 'v') under joggled input ('QJ'), + remove vertical facets whose lowest vertex may be coplanar with convex hull + - review use of 'Qbb' with 'd QJ'. Is MAXabs_coord better than MAXwidth? + - check Sugihara and Iri's better in-sphere test [Canadian + Conf. on Comp. Geo., 1989; Univ. of Tokyo RMI 89-05] + - replace centrum with center of mass and facet area + - handle numeric overflow in qh_normalize and elsewhere + - merge flipped facets into non-flipped neighbors. + currently they merge into best neighbor (appears ok) + - determine min norm for Cramer's rule (qh_sethyperplane_det). It looks high. + - improve facet width for very narrow distributions + +New features: + - implement Matlab's tsearch() using Qhull + - compute volume of Voronoi regions. You need to determine the dual face + graph in all dimensions [see Clarkson's hull program] + - compute alpha shapes [see Clarkson's hull program] + - implement deletion of Delaunay vertices + see Devillers, ACM Symposium on Computational Geometry, Minneapolis 1999. + - compute largest empty circle [see O'Rourke, chapter 5.5.3] [Hase] + - list redundant (i.e., coincident) vertices [Spitz] + - implement Mucke, et al, ['96] for point location in Delaunay triangulations + - implement convex hull of moving points + - implement constrained Delaunay diagrams + see Shewchuk, ACM Symposium on Computational Geometry, Minneapolis 1998. + - estimate outer volume of hull + - automatically determine lower dimensional hulls + - allow "color" data for input points + need to insert a coordinate for Delaunay triangulations + +Input/output improvements: + - Support the VTK Visualization Toolkit, http://www.kitware.com/vtk.html + - generate output data array for Qhull library [Gautier] + - need improved DOS window with screen fonts, scrollbar, cut/paste + - generate Geomview output for Voronoi ridges and unbounded rays + - generate Geomview output for halfspace intersection + - generate Geomview display of furthest-site Voronoi diagram + - use '<a href="qh-optg.htm#GDn">GDn</a>' to view 5-d facets in 4-d + - convert Geomview output for other 3-d viewers + - add interactive output option to avoid recomputing a hull + - orient vertex neighbors for '<a href="qh-optf.htm#Fv">Fv</a>' in 3-d and 2-d + - track total number of ridges for summary and logging + +Performance improvements: + - optimize Qhull for 2-d Delaunay triangulations + - use O'Rourke's <a href="index.htm#orou94">'94</a> vertex->duplicate_edge + - add bucketing + - better to specialize all of the code (ca. 2-3x faster w/o merging) + - use updated LU decomposition to speed up hyperplane construction + - [Gill et al. 1974, Math. Comp. 28:505-35] + - construct hyperplanes from the corresponding horizon/visible facets + - for merging in high d, do not use vertex->neighbors + +</pre> + +<p>Please let us know about your applications and improvements. </p> +<!-- Navigation links --> +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home +page for Qhull</a> <br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual: Table of +Contents</a><br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#TOC">Qhull code</a>: Table of Contents <br> +<b>Dn:</b> <a href="../src/libqhull_r/index.htm">Qhull functions</a>, macros, and data +structures <!-- GC common information --> + +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="qh--geom.gif" +align="middle" width="40" height="40"></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: Sept. 25, 1995 --- <!-- hhmts start --> Last modified: see changes.txt <!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/qh-eg.htm b/xs/src/qhull/html/qh-eg.htm new file mode 100644 index 000000000..a08f0d13f --- /dev/null +++ b/xs/src/qhull/html/qh-eg.htm @@ -0,0 +1,693 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<title>Examples of Qhull</title> +</head> + +<body> +<!-- Navigation links --> +<p><a name="TOP"><b>Up:</b></a> <a href="http://www.qhull.org">Home +page</a> for Qhull <br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To: </b><a href="#TOC">Qhull examples: Table of Contents</a> (please wait +while loading)<br> + +<hr> +<!-- Main text of document --> +<h1><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/half.html"><img +src="qh--half.gif" alt="[halfspace]" align="middle" width="100" +height="100"></a> Examples of Qhull</h1> + +<p>This section of the Qhull manual will introduce you to Qhull +and its options. Each example is a file for viewing with <a +href="index.htm#geomview">Geomview</a>. You will need to +use a Unix computer with a copy of Geomview. +<p> +If you are not running Unix, you can view <a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/welcome.html">pictures</a> +for some of the examples. To understand Qhull without Geomview, try the +examples in <a href="qh-quick.htm#programs">Programs</a> and +<a href="qh-quick.htm#programs">Programs/input</a>. You can also try small +examples that you compute by hand. Use <a href="rbox.htm">rbox</a> +to generate examples. +<p> +To generate the Geomview examples, execute the shell script <tt>eg/q_eg</tt>. +It uses <tt>rbox</tt>. The shell script <tt>eg/q_egtest</tt> generates +test examples, and <tt>eg/q_test</tt> exercises the code. If you +find yourself viewing the inside of a 3-d example, use Geomview's +normalization option on the 'obscure' menu.</p> + +<p><b>Copyright © 1995-2015 C.B. Barber</b></p> + +<hr> + +<h2><a href="#TOP">»</a><a name="TOC">Qhull examples: Table of +Contents </a></h2> + +<ul> + <li><a href="#2d">2-d and 3-d examples</a></li> + <li><a href="#how">How Qhull adds a point</a></li> + <li><a href="#joggle">Triangulated output or joggled input</a></li> + <li><a href="#delaunay">Delaunay and Voronoi diagrams</a></li> + <li><a href="#merge">Facet merging for imprecision</a></li> + <li><a href="#4d">4-d objects</a></li> + <li><a href="#half">Halfspace intersections</a></li> +</ul> + +<hr> +<ul> + <li><a href="#TOC">»</a><a name="2d">2-d and 3-d examples</a><ul> + <li><a href="#01">eg.01.cube</a></li> + <li><a href="#02">eg.02.diamond.cube</a></li> + <li><a href="#03">eg.03.sphere</a></li> + <li><a href="#04">eg.04.circle</a></li> + <li><a href="#05">eg.05.spiral</a></li> + <li><a href="#06">eg.06.merge.square</a></li> + <li><a href="#07">eg.07.box</a></li> + <li><a href="#08a">eg.08a.cube.sphere</a></li> + <li><a href="#08b">eg.08b.diamond.sphere</a></li> + <li><a href="#09">eg.09.lens</a></li> + </ul> + </li> + <li><a href="#TOC">»</a><a name="how">How Qhull adds a point</a><ul> + <li><a href="#10a">eg.10a.sphere.visible</a></li> + <li><a href="#10b">eg.10b.sphere.beyond</a></li> + <li><a href="#10c">eg.10c.sphere.horizon</a></li> + <li><a href="#10d">eg.10d.sphere.cone</a></li> + <li><a href="#10e">eg.10e.sphere.new</a></li> + <li><a href="#14">eg.14.sphere.corner</a></li> + </ul> + </li> + <li><a href="#TOC">»</a> <a name="joggle">Triangulated output or joggled input</a> + <ul> + <li><a href="#15a">eg.15a.surface</a></li> + <li><a href="#15b">eg.15b.triangle</a></li> + <li><a href="#15c">eg.15c.joggle</a></li> + </ul> + <li><a href="#TOC">»</a><a name="delaunay"> Delaunay and + Voronoi diagrams</a><ul> + <li><a href="#17a">eg.17a.delaunay.2</a></li> + <li><a href="#17b">eg.17b.delaunay.2i</a></li> + <li><a href="#17c">eg.17c.delaunay.2-3</a></li> + <li><a href="#17d">eg.17d.voronoi.2</a></li> + <li><a href="#17e">eg.17e.voronoi.2i</a></li> + <li><a href="#17f">eg.17f.delaunay.3</a></li> + <li><a href="#18a">eg.18a.furthest.2-3</a></li> + <li><a href="#18b">eg.18b.furthest-up.2-3</a></li> + <li><a href="#18c">eg.18c.furthest.2</a></li> + <li><a href="#19">eg.19.voronoi.region.3</a></li> + </ul> + </li> + <li><a href="#TOC">»</a><a name="merge">Facet merging for + imprecision </a><ul> + <li><a href="#20">eg.20.cone</a></li> + <li><a href="#21a">eg.21a.roundoff.errors</a></li> + <li><a href="#21b">eg.21b.roundoff.fixed</a></li> + <li><a href="#22a">eg.22a.merge.sphere.01</a></li> + <li><a href="#22b">eg.22b.merge.sphere.-01</a></li> + <li><a href="#22c">eg.22c.merge.sphere.05</a></li> + <li><a href="#22d">eg.22d.merge.sphere.-05</a></li> + <li><a href="#23">eg.23.merge.cube</a></li> + </ul> + </li> + <li><a href="#TOC">»</a><a name="4d">4-d objects</a><ul> + <li><a href="#24">eg.24.merge.cube.4d-in-3d</a></li> + <li><a href="#30">eg.30.4d.merge.cube</a></li> + <li><a href="#31">eg.31.4d.delaunay</a></li> + <li><a href="#32">eg.32.4d.octant</a></li> + </ul> + </li> + <li><a href="#TOC">»</a><a name="half">Halfspace + intersections</a><ul> + <li><a href="#33a">eg.33a.cone</a></li> + <li><a href="#33b">eg.33b.cone.dual</a></li> + <li><a href="#33c">eg.33c.cone.halfspace</a></li> + </ul> + </li> +</ul> + +<hr> + +<h2><a href="#TOC">»</a>2-d and 3-d examples</h2> + +<h3><a href="#2d">»</a><a name="01">rbox c D3 | qconvex G +>eg.01.cube </a></h3> + +<p>The first example is a cube in 3-d. The color of each facet +indicates its normal. For example, normal [0,0,1] along the Z +axis is (r=0.5, g=0.5, b=1.0). With the 'Dn' option in <tt>rbox</tt>, +you can generate hypercubes in any dimension. Above 7-d the +number of intermediate facets grows rapidly. Use '<a +href="qh-optt.htm#TFn">TFn</a>' to track qconvex's progress. Note +that each facet is a square that qconvex merged from coplanar +triangles.</p> + +<h3><a href="#2d">»</a><a name="02">rbox c d G3.0 | qconvex G +>eg.02.diamond.cube </a></h3> + +<p>The second example is a cube plus a diamond ('d') scaled by <tt>rbox</tt>'s +'G' option. In higher dimensions, diamonds are much simpler than +hypercubes. </p> + +<h3><a href="#2d">»</a><a name="03">rbox s 100 D3 | qconvex G +>eg.03.sphere </a></h3> + +<p>The <tt>rbox s</tt> option generates random points and +projects them to the d-sphere. All points should be on the convex +hull. Notice that random points look more clustered than you +might expect. You can get a smoother distribution by merging +facets and printing the vertices, e.g.,<i> rbox 1000 s | qconvex +A-0.95 p | qconvex G >eg.99</i>.</p> + +<h3><a href="#2d">»</a><a name="04">rbox s 100 D2 | qconvex G +>eg.04.circle </a></h3> + +<p>In 2-d, there are many ways to generate a convex hull. One of +the earliest algorithms, and one of the fastest, is the 2-d +Quickhull algorithm [c.f., Preparata & Shamos <a +href="index.htm#pre-sha85">'85</a>]. It was the model for +Qhull.</p> + +<h3><a href="#2d">»</a><a name="05">rbox 10 l | qconvex G +>eg.05.spiral </a></h3> + +<p>One rotation of a spiral.</p> + +<h3><a href="#2d">»</a><a name="06">rbox 1000 D2 | qconvex C-0.03 +Qc Gapcv >eg.06.merge.square</a></h3> + +<p>This demonstrates how Qhull handles precision errors. Option '<a +href="qh-optc.htm#Cn">C-0.03</a>' requires a clearly convex angle +between adjacent facets. Otherwise, Qhull merges the facets. </p> + +<p>This is the convex hull of random points in a square. The +facets have thickness because they must be outside all points and +must include their vertices. The colored lines represent the +original points and the spheres represent the vertices. Floating +in the middle of each facet is the centrum. Each centrum is at +least 0.03 below the planes of its neighbors. This guarantees +that the facets are convex.</p> + +<h3><a href="#2d">»</a><a name="07">rbox 1000 D3 | qconvex G +>eg.07.box </a></h3> + +<p>Here's the same distribution but in 3-d with Qhull handling +machine roundoff errors. Note the large number of facets. </p> + +<h3><a href="#2d">»</a><a name="08a">rbox c G0.4 s 500 | qconvex G +>eg.08a.cube.sphere </a></h3> + +<p>The sphere is just barely poking out of the cube. Try the same +distribution with randomization turned on ('<a +href="qh-optq.htm#Qr">Qr</a>'). This turns Qhull into a +randomized incremental algorithm. To compare Qhull and +randomization, look at the number of hyperplanes created and the +number of points partitioned. Don't compare CPU times since Qhull's +implementation of randomization is inefficient. The number of +hyperplanes and partitionings indicate the dominant costs for +Qhull. With randomization, you'll notice that the number of +facets created is larger than before. This is especially true as +you increase the number of points. It is because the randomized +algorithm builds most of the sphere before it adds the cube's +vertices.</p> + +<h3><a href="#2d">»</a><a name="08b">rbox d G0.6 s 500 | qconvex G +>eg.08b.diamond.sphere </a></h3> + +<p>This is a combination of the diamond distribution and the +sphere.</p> + +<h3><a href="#2d">»</a><a name="09">rbox 100 L3 G0.5 s | qconvex +G >eg.09.lens </a></h3> + +<p>Each half of the lens distribution lies on a sphere of radius +three. A directed search for the furthest facet below a point +(e.g., qh_findbest in <tt>geom.c</tt>) may fail if started from +an arbitrary facet. For example, if the first facet is on the +opposite side of the lens, a directed search will report that the +point is inside the convex hull even though it is outside. This +problem occurs whenever the curvature of the convex hull is less +than a sphere centered at the test point. </p> + +<p>To prevent this problem, Qhull does not use directed search +all the time. When Qhull processes a point on the edge of the +lens, it partitions the remaining points with an exhaustive +search instead of a directed search (see qh_findbestnew in <tt>geom2.c</tt>). +</p> + +<h2><a href="#TOC">»</a>How Qhull adds a point</h2> + +<h3><a href="#how">»</a><a name="10a">rbox 100 s P0.5,0.5,0.5 | +qconvex Ga QG0 >eg.10a.sphere.visible</a></h3> + +<p>The next 4 examples show how Qhull adds a point. The point +[0.5,0.5,0.5] is at one corner of the bounding box. Qhull adds a +point using the beneath-beyond algorithm. First Qhull finds all +of the facets that are visible from the point. Qhull will replace +these facets with new facets.</p> + +<h3><a href="#how">»</a><a name="10b">rbox 100 s +P0.5,0.5,0.5|qconvex Ga QG-0 >eg.10b.sphere.beyond </a></h3> + +<p>These are the facets that are not visible from the point. +Qhull will keep these facets.</p> + +<h3><a href="#how">»</a><a name="10c">rbox 100 s P0.5,0.5,0.5 | +qconvex PG Ga QG0 >eg.10c.sphere.horizon </a></h3> + +<p>These facets are the horizon facets; they border the visible +facets. The inside edges are the horizon ridges. Each horizon +ridge will form the base for a new facet.</p> + +<h3><a href="#how">»</a><a name="10d">rbox 100 s P0.5,0.5,0.5 | +qconvex Ga QV0 PgG >eg.10d.sphere.cone </a></h3> + +<p>This is the cone of points from the new point to the horizon +facets. Try combining this image with <tt>eg.10c.sphere.horizon</tt> +and <tt>eg.10a.sphere.visible</tt>. +</p> + +<h3><a href="#how">»</a><a name="10e">rbox 100 s P0.5,0.5,0.5 | +qconvex Ga >eg.10e.sphere.new</a></h3> + +<p>This is the convex hull after [0.5,0.5,0.5] has been added. +Note that in actual practice, the above sequence would never +happen. Unlike the randomized algorithms, Qhull always processes +a point that is furthest in an outside set. A point like +[0.5,0.5,0.5] would be one of the first points processed.</p> + +<h3><a href="#how">»</a><a name="14">rbox 100 s P0.5,0.5,0.5 | +qhull Ga QV0g Q0 >eg.14.sphere.corner</a></h3> + +<p>The '<a href="qh-optq.htm#QVn">QVn</a>', '<a +href="qh-optq.htm#QGn">QGn </a>' and '<a href="qh-optp.htm#Pdk">Pdk</a>' +options define good facets for Qhull. In this case '<a +href="qh-optq.htm#QVn">QV0</a>' defines the 0'th point +[0.5,0.5,0.5] as the good vertex, and '<a href="qh-optq.htm#Qg">Qg</a>' +tells Qhull to only build facets that might be part of a good +facet. This technique reduces output size in low dimensions. It +does not work with facet merging.</p> + +<h2><a href="#TOC">»</a>Triangulated output or joggled input</h2> + +<h3><a href="#joggle">»</a><a name="15a">rbox 500 W0 | qconvex QR0 Qc Gvp >eg.15a.surface</a></h3> + +<p>This is the convex hull of 500 points on the surface of +a cube. Note the large, non-simplicial facet for each face. +Qhull merges non-convex facets. + +<p>If the facets were not merged, Qhull +would report precision problems. For example, turn off facet merging +with option '<a href="qh-optq.htm#Q0">Q0</a>'. Qhull may report concave +facets, flipped facets, or other precision errors: +<blockquote> +rbox 500 W0 | qhull QR0 Q0 +</blockquote> + +<p> +<h3><a href="#joggle">»</a><a name="15b">rbox 500 W0 | qconvex QR0 Qt Qc Gvp >eg.15b.triangle</a></h3> + +<p>Like the previous examples, this is the convex hull of 500 points on the +surface of a cube. Option '<a href="qh-optq.htm#Qt">Qt</a>' triangulates the +non-simplicial facets. Triangulated output is +particularly helpful for Delaunay triangulations. + +<p> +<h3><a href="#joggle">»</a><a name="15c">rbox 500 W0 | qconvex QR0 QJ5e-2 Qc Gvp >eg.15c.joggle</a></h3> + +<p>This is the convex hull of 500 joggled points on the surface of +a cube. The option '<a href="qh-optq.htm#QJn">QJ5e-2</a>' +sets a very large joggle to make the effect visible. Notice +that all of the facets are triangles. If you rotate the cube, +you'll see red-yellow lines for coplanar points. +<p> +With option '<a href="qh-optq.htm#QJn">QJ</a>', Qhull joggles the +input to avoid precision problems. It adds a small random number +to each input coordinate. If a precision +error occurs, it increases the joggle and tries again. It repeats +this process until no precision problems occur. +<p> +Joggled input is a simple solution to precision problems in +computational geometry. Qhull can also merge facets to handle +precision problems. See <a href="qh-impre.htm#joggle">Merged facets or joggled input</a>. + +<h2><a href="#TOC">»</a>Delaunay and Voronoi diagrams</h2> + +<h3><a href="#delaunay">»</a><a name="17a">qdelaunay Qt +<eg.data.17 GnraD2 >eg.17a.delaunay.2</a></h3> + +<p> +The input file, <tt>eg.data.17</tt>, consists of a square, 15 random +points within the outside half of the square, and 6 co-circular +points centered on the square. + +<p>The Delaunay triangulation is the triangulation with empty +circumcircles. The input for this example is unusual because it +includes six co-circular points. Every triangular subset of these +points has the same circumcircle. Option '<a href="qh-optq.htm#Qt">Qt</a>' +triangulates the co-circular facet.</p> + +<h3><a href="#delaunay">»</a><a name="17b">qdelaunay <eg.data.17 +GnraD2 >eg.17b.delaunay.2i</a></h3> + +<p>This is the same example without triangulated output ('<a href="qh-optq.htm#Qt">Qt</a>'). qdelaunay +merges the non-unique Delaunay triangles into a hexagon.</p> + +<h3><a href="#delaunay">»</a><a name="17c">qdelaunay <eg.data.17 +Ga >eg.17c.delaunay.2-3 </a></h3> + +<p>This is how Qhull generated both diagrams. Use Geomview's +'obscure' menu to turn off normalization, and Geomview's +'cameras' menu to turn off perspective. Then load this <a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/delaunay.html">object</a> +with one of the previous diagrams.</p> + +<p>The points are lifted to a paraboloid by summing the squares +of each coordinate. These are the light blue points. Then the +convex hull is taken. That's what you see here. If you look up +the Z-axis, you'll see that points and edges coincide.</p> + +<h3><a href="#delaunay">»</a><a name="17d">qvoronoi QJ +<eg.data.17 Gna >eg.17d.voronoi.2</a></h3> + +<p>The Voronoi diagram is the dual of the Delaunay triangulation. +Here you see the original sites and the Voronoi vertices. +Notice the each +vertex is equidistant from three sites. The edges indicate the +Voronoi region for a site. Qhull does not draw the unbounded +edges. Instead, it draws extra edges to close the unbounded +Voronoi regions. You may find it helpful to enclose the input +points in a square. You can compute the unbounded +rays from option '<a href="qh-optf.htm#Fo2">Fo</a>'. +</p> + +<p>Instead +of triangulated output ('<a href="qh-optq.htm#Qt">Qt</a>'), this +example uses joggled input ('<a href="qh-optq.htm#QJn">QJ</a>'). +Normally, you should use neither 'QJ' nor 'Qt' for Voronoi diagrams. + +<h3><a href="#delaunay">»</a><a name="17e">qvoronoi <eg.data.17 +Gna >eg.17e.voronoi.2i </a></h3> + +<p>This looks the same as the previous diagrams, but take a look +at the data. Run 'qvoronoi p <eg/eg.data.17'. This prints +the Voronoi vertices. + +<p>With 'QJ', there are four nearly identical Voronoi vertices +within 10^-11 of the origin. Option 'QJ' joggled the input. After the joggle, +the cocircular +input sites are no longer cocircular. The corresponding Voronoi vertices are +similar but not identical. + +<p>This example does not use options 'Qt' or 'QJ'. The cocircular +input sites define one Voronoi vertex near the origin. </p> + +<p>Option 'Qt' would triangulate the corresponding Delaunay region into +four triangles. Each triangle is assigned the same Voronoi vertex.</p> + +<h3><a href="#delaunay">»</a><a name="17f"> rbox c G0.1 d | +qdelaunay Gt Qz <eg.17f.delaunay.3 </a></h3> + +<p>This is the 3-d Delaunay triangulation of a small cube inside +a prism. Since the outside ridges are transparent, it shows the +interior of the outermost facets. If you slice open the +triangulation with Geomview's ginsu, you will see that the innermost +facet is a cube. Note the use of '<a href="qh-optq.htm#Qz">Qz</a>' +to add a point "at infinity". This avoids a degenerate +input due to cospherical points.</p> + +<h3><a href="#delaunay">»</a><a name="18a">rbox 10 D2 d | qdelaunay +Qu G >eg.18a.furthest.2-3 </a></h3> + +<p>The furthest-site Voronoi diagram contains Voronoi regions for +points that are <i>furthest </i>from an input site. It is the +dual of the furthest-site Delaunay triangulation. You can +determine the furthest-site Delaunay triangulation from the +convex hull of the lifted points (<a href="#17c">eg.17c.delaunay.2-3</a>). +The upper convex hull (blue) generates the furthest-site Delaunay +triangulation. </p> + +<h3><a href="#delaunay">»</a><a name="18b">rbox 10 D2 d | qdelaunay +Qu Pd2 G >eg.18b.furthest-up.2-3</a></h3> + +<p>This is the upper convex hull of the preceding example. The +furthest-site Delaunay triangulation is the projection of the +upper convex hull back to the input points. The furthest-site +Voronoi vertices are the circumcenters of the furthest-site +Delaunay triangles. </p> + +<h3><a href="#delaunay">»</a><a name="18c">rbox 10 D2 d | qvoronoi +Qu Gv >eg.18c.furthest.2</a></h3> + +<p>This shows an incomplete furthest-site Voronoi diagram. It +only shows regions with more than two vertices. The regions are +artificially truncated. The actual regions are unbounded. You can +print the regions' vertices with 'qvoronoi Qu <a +href="qh-opto.htm#o">o</a>'. </p> + +<p>Use Geomview's 'obscure' menu to turn off normalization, and +Geomview's 'cameras' menu to turn off perspective. Then load this +with the upper convex hull.</p> + +<h3><a href="#delaunay">»</a><a name="19">rbox 10 D3 | qvoronoi QV5 +p | qconvex G >eg.19.voronoi.region.3 </a></h3> + +<p>This shows the Voronoi region for input site 5 of a 3-d +Voronoi diagram.</p> + +<h2><a href="#TOC">»</a>Facet merging for imprecision</h2> + +<h3><a href="#merge">»</a><a name="20">rbox r s 20 Z1 G0.2 | +qconvex G >eg.20.cone </a></h3> + +<p>There are two things unusual about this <a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/cone.html">cone</a>. +One is the large flat disk at one end and the other is the +rectangles about the middle. That's how the points were +generated, and if those points were exact, this is the correct +hull. But <tt>rbox</tt> used floating point arithmetic to +generate the data. So the precise convex hull should have been +triangles instead of rectangles. By requiring convexity, Qhull +has recovered the original design.</p> + +<h3><a href="#merge">»</a><a name="21a">rbox 200 s | qhull Q0 +R0.01 Gav Po >eg.21a.roundoff.errors </a></h3> + +<p>This is the convex hull of 200 cospherical points with +precision errors ignored ('<a href="qh-optq.htm#Q0">Q0</a>'). To +demonstrate the effect of roundoff error, we've added a random +perturbation ('<a href="qh-optc.htm#Rn">R0.01</a>') to every +distance and hyperplane calculation. Qhull, like all other convex +hull algorithms with floating point arithmetic, makes +inconsistent decisions and generates wildly wrong results. In +this case, one or more facets are flipped over. These facets have +the wrong color. You can also turn on 'normals' in Geomview's +appearances menu and turn off 'facing normals'. There should be +some white lines pointing in the wrong direction. These +correspond to flipped facets. </p> + +<p>Different machines may not produce this picture. If your +machine generated a long error message, decrease the number of +points or the random perturbation ('<a href="qh-optc.htm#Rn">R0.01</a>'). +If it did not report flipped facets, increase the number of +points or perturbation.</p> + +<h3><a href="#merge">»</a><a name="21b">rbox 200 s | qconvex Qc +R0.01 Gpav >eg.21b.roundoff.fixed </a></h3> + +<p>Qhull handles the random perturbations and returns an +imprecise <a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/fixed.html">sphere</a>. +In this case, the output is a weak approximation to the points. +This is because a random perturbation of '<a +href="qh-optc.htm#Rn">R0.01 </a>' is equivalent to losing all but +1.8 digits of precision. The outer planes float above the points +because Qhull needs to allow for the maximum roundoff error. </p> +<p> +If you start with a smaller random perturbation, you +can use joggle ('<a href="qh-optq.htm#QJn">QJn</a>') to avoid +precision problems. You need to set <i>n</i> significantly +larger than the random perturbation. For example, try +'rbox 200 s | qconvex Qc R1e-4 QJ1e-1'. + +<h3><a href="#merge">»</a><a name="22a">rbox 1000 s| qconvex C0.01 +Qc Gcrp >eg.22a.merge.sphere.01</a></h3> + +<h3><a href="#merge">»</a><a name="22b">rbox 1000 s| qconvex +C-0.01 Qc Gcrp >eg.22b.merge.sphere.-01</a></h3> + +<h3><a href="#merge">»</a><a name="22c">rbox 1000 s| qconvex C0.05 +Qc Gcrpv >eg.22c.merge.sphere.05</a></h3> + +<h3><a href="#merge">»</a><a name="22d">rbox 1000 s| qconvex +C-0.05 Qc Gcrpv >eg.22d.merge.sphere.-05</a></h3> + +<p>The next four examples compare post-merging and pre-merging ('<a +href="qh-optc.htm#Cn2">Cn</a>' vs. '<a href="qh-optc.htm#Cn">C-n</a>'). +Qhull uses '-' as a flag to indicate pre-merging.</p> + +<p>Post-merging happens after the convex hull is built. During +post-merging, Qhull repeatedly merges an independent set of +non-convex facets. For a given set of parameters, the result is +about as good as one can hope for.</p> + +<p>Pre-merging does the same thing as post-merging, except that +it happens after adding each point to the convex hull. With +pre-merging, Qhull guarantees a convex hull, but the facets are +wider than those from post-merging. If a pre-merge option is not +specified, Qhull handles machine round-off errors.</p> + +<p>You may see coplanar points appearing slightly outside +the facets of the last example. This is becomes Geomview moves +line segments forward toward the viewer. You can avoid the +effect by setting 'lines closer' to '0' in Geomview's camera menu. + +<h3><a href="#merge">»</a><a name="23">rbox 1000 | qconvex s +Gcprvah C0.1 Qc >eg.23.merge.cube</a></h3> + +<p>Here's the 3-d imprecise cube with all of the Geomview +options. There's spheres for the vertices, radii for the coplanar +points, dots for the interior points, hyperplane intersections, +centrums, and inner and outer planes. The radii are shorter than +the spheres because this uses post-merging ('<a href="qh-optc.htm#Cn2">C0.1</a>') +instead of pre-merging. + +<h2><a href="#TOC">»</a>4-d objects</h2> + +<p>With Qhull and Geomview you can develop an intuitive sense of +4-d surfaces. When you get into trouble, think of viewing the +surface of a 3-d sphere in a 2-d plane.</p> + +<h3><a href="#4d">»</a><a name="24">rbox 5000 D4 | qconvex s GD0v +Pd0:0.5 C-0.02 C0.1 >eg.24.merge.cube.4d-in-3d</a></h3> + +<p>Here's one facet of the imprecise cube in 4-d. It's projected +into 3-d (the '<a href="qh-optg.htm#GDn">GDn</a>' option drops +dimension n). Each ridge consists of two triangles between this +facet and the neighboring facet. In this case, Geomview displays +the topological ridges, i.e., as triangles between three +vertices. That is why the cube looks lopsided.</p> + +<h3><a href="#4d">»</a><a name="30">rbox 5000 D4 | qconvex s +C-0.02 C0.1 Gh >eg.30.4d.merge.cube </a></h3> + +<p><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/4dcube.html">Here</a> +is the equivalent in 4-d of the imprecise <a href="#06">square</a> +and imprecise <a href="#23">cube</a>. It's the imprecise convex +hull of 5000 random points in a hypercube. It's a full 4-d object +so Geomview's <tt>ginsu </tt>does not work. If you view it in +Geomview, you'll be inside the hypercube. To view 4-d objects +directly, either load the <tt>4dview</tt> module or the <tt>ndview +</tt>module. For <tt>4dview</tt>, you must have started Geomview +in the same directory as the object. For <tt>ndview</tt>, +initialize a set of windows with the prefab menu, and load the +object through Geomview. The <tt>4dview</tt> module includes an +option for slicing along any hyperplane. If you do this in the x, +y, or z plane, you'll see the inside of a hypercube.</p> + +<p>The '<a href="qh-optg.htm#Gh">Gh</a>' option prints the +geometric intersections between adjacent facets. Note the strong +convexity constraint for post-merging ('<a href="qh-optc.htm#Cn2">C0.1</a>'). +It deletes the small facets.</p> + +<h3><a href="#4d">»</a><a name="31">rbox 20 D3 | qdelaunay G +>eg.31.4d.delaunay </a></h3> + +<p>The Delaunay triangulation of 3-d sites corresponds to a 4-d +convex hull. You can't see 4-d directly but each facet is a 3-d +object that you can project to 3-d. This is exactly the same as +projecting a 2-d facet of a soccer ball onto a plane.</p> + +<p>Here we see all of the facets together. You can use Geomview's +<tt>ndview</tt> to look at the object from several directions. +Try turning on edges in the appearance menu. You'll notice that +some edges seem to disappear. That's because the object is +actually two sets of overlapping facets.</p> + +<p>You can slice the object apart using Geomview's <tt>4dview</tt>. +With <tt>4dview</tt>, try slicing along the w axis to get a +single set of facets and then slice along the x axis to look +inside. Another interesting picture is to slice away the equator +in the w dimension.</p> + +<h3><a href="#4d">»</a><a name="32">rbox 30 s D4 | qconvex s G +Pd0d1d2D3</a></h3> + +<p>This is the positive octant of the convex hull of 30 4-d +points. When looking at 4-d, it's easier to look at just a few +facets at once. If you picked a facet that was directly above +you, then that facet looks exactly the same in 3-d as it looks in +4-d. If you pick several facets, then you need to imagine that +the space of a facet is rotated relative to its neighbors. Try +Geomview's <tt>ndview</tt> on this example.</p> + +<h2><a href="#TOC">»</a>Halfspace intersections</h2> + +<h3><a href="#half">»</a><a name="33a">rbox 10 r s Z1 G0.3 | +qconvex G >eg.33a.cone </a></h3> + +<h3><a href="#half">»</a><a name="33b">rbox 10 r s Z1 G0.3 | +qconvex FV n | qhalf G >eg.33b.cone.dual</a></h3> + +<h3><a href="#half">»</a><a name="33c">rbox 10 r s Z1 G0.3 | +qconvex FV n | qhalf Fp | qconvex G >eg.33c.cone.halfspace</a></h3> + +<p>These examples illustrate halfspace intersection. The first +picture is the convex hull of two 20-gons plus an apex. The +second picture is the dual of the first. Try loading <a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/half.html">both</a> +at once. Each vertex of the second picture corresponds to a facet +or halfspace of the first. The vertices with four edges +correspond to a facet with four neighbors. Similarly the facets +correspond to vertices. A facet's normal coefficients divided by +its negative offset is the vertice's coordinates. The coordinates +are the intersection of the original halfspaces. </p> + +<p>The third picture shows how Qhull can go back and forth +between equivalent representations. It starts with a cone, +generates the halfspaces that define each facet of the cone, and +then intersects these halfspaces. Except for roundoff error, the +third picture is a duplicate of the first. </p> +<!-- Navigation links --> +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home +page for Qhull</a> <br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual: Table of Contents</a><br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To: </b><a href="#TOC">Qhull examples: Table of Contents</a> (please wait +while loading)<br> +<!-- GC common information --> +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="qh--geom.gif" +align="middle" width="40" height="40"></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: Sept. 25, 1995 --- <!-- hhmts start --> Last modified: see top <!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/qh-faq.htm b/xs/src/qhull/html/qh-faq.htm new file mode 100644 index 000000000..feda544a7 --- /dev/null +++ b/xs/src/qhull/html/qh-faq.htm @@ -0,0 +1,1547 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<meta http-equiv="Content-Type" +content="text/html; charset=iso-8859-1"> +<meta name="GENERATOR" content="Microsoft FrontPage 2.0"> +<title>Qhull FAQ</title> +<!-- Navigation links +NOTE -- verify all links by 'grep href=' 'grep name=' add # 'sort /+7' +<base href> does not work since #TOC is relative to base instead of doc +--> +</head> + +<body> + +<p><a name="TOP"><b>Up:</b></a> <a + href="http://www.qhull.org">Home page</a> for Qhull +(http://www.qhull.org)<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#TOC">FAQ: Table of Contents</a> (please +wait while loading) <br> + +<hr> +<!-- Main text of document --> +<h1><a + href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/4dcube.html"><IMG + align=middle alt ="[4-d cube]" + height=100 src="qh--4d.gif" width=100 ></a> Frequently Asked Questions about Qhull</h1><!-- +<p><i>This is the most recent FAQ. It was updated Sept. 13, 1999.</i> +--> +<p>If your question does not appear here, see: </p> + +<ul> + <li><a href="http://www.qhull.org/news">News</a> about Qhull + <li><a href="index.htm#TOC">Qhull manual:</a> table of contents + <li><a href="../README.txt">Installation</a> instructions for Qhull and rbox + + <li><a href="mailto:qhull@qhull.org">Send e-mail</a> to + qhull@qhull.org + <li><a href="mailto:qhull_bug@qhull.org">Report bugs</a> + to qhull_bug@qhull.org </li> +</ul> + +<p>Qhull is a general dimension code for computing convex hulls, +Delaunay triangulations, halfspace intersections about a point, +Voronoi diagrams, furthest-site Delaunay triangulations, and +furthest-site Voronoi diagrams. These structures have +applications in science, engineering, statistics, and +mathematics. For a detailed introduction, see O'Rourke [<a + href="index.htm#orou94" >'94</a>], <i>Computational Geometry in C</i>. +</p> + +<p>There are separate programs for each application of +Qhull. These programs disable experimental and inappropriate +options. If you prefer, you may use Qhull directly. All programs +run the same code. + +<p>Version 3.1 added triangulated output ('<a href="qh-optq.htm#Qt">Qt</a>'). +It should be used for Delaunay triangulations instead of +using joggled input ('<a href="qh-optq.htm#QJn">QJ</a>'). + +<p><i>Brad Barber, Arlington MA, +2010/01/09 <!-- +--> </i></p> + +<p><b>Copyright © 1998-2015 C.B. Barber</b></p> + +<hr> + +<h2><a href="#TOP">»</a><a name="TOC">FAQ: Table of Contents </a></h2> + +<p>Within each category, the most recently asked questions are +first. +<ul> + <li>Startup questions <ul> + <li><a href="#console">How</a> do I run Qhull from Windows? + <li><a href="#input">How</a> do I enter points for Qhull? + <li><a href="#learn">How</a> do I learn to use Qhull?</li> + </ul> + <li>Convex hull questions<ul> + <li><a href="#area">How</a> do I report just the area and volume of a + convex hull? + <li><a href="#extra">Why</a> are there extra points in a 4-d or higher + convex hull? + <li><a href="#dup">How</a> do I report duplicate + vertices? </li> + </ul> + <li>Delaunay triangulation questions<ul> + <li><a href="#flat">How</a> do I get rid of nearly flat Delaunay + triangles? + <li><a href="#vclosest">How</a> do I find the Delaunay triangle or Voronoi + region that is closest to a point? + + <li><a href="#mesh">How</a> do I compute the Delaunay triangulation of a + non-convex object? + + <li><a href="#mesh">How</a> do I mesh a volume from a set of triangulated + surface points? + + <li><a href="#constrained">Can</a> Qhull produce a triangular mesh for an + object? + + <li><a href="#dridges">For</a> 3-d Delaunay triangulations, how do I + report the triangles of each tetrahedron? + + <li><a href="#3dd">How</a> do I construct a 3-d Delaunay triangulation? + <li><a href="#2d">How</a> do I get the triangles for a 2-d Delaunay + triangulation and the vertices of its Voronoi diagram? + <li><a href="#big">Can </a>Qhull triangulate a + hundred 16-d points?</li> + </ul> + + <li>Voronoi diagram questions<ul> + <li>See also "Delaunay diagram questions". Qhull computes the Voronoi diagram from the Delaunay triagulation. + <li><a href="#volume">How</a> do I compute the volume of a Voronoi region? + <li><a href="#maxsphere">How</a> do I get the radii of the empty + spheres for each Voronoi vertex? + + <li><a href="#square">What</a> is the Voronoi diagram of a square? + + <li><a href="#vsphere">How</a> do I construct the Voronoi diagram of + cospherical points? + <li><a href="#rays">Can</a> Qhull compute the unbounded rays of the + Voronoi diagram? + </ul> + <li>Approximation questions<ul> + <li><a href="#simplex">How</a> do I approximate data + with a simplex?</li> + </ul> + <li>Halfspace questions<ul> + <li><a href="#halfspace">How</a> do I compute the + intersection of halfspaces with Qhull?</li> + </ul> + <li><a name="library">Qhull library</a> questions<ul> + <li><a href="#math">Is</a> Qhull available for Mathematica, Matlab, or + Maple? + + <li><a href="#ridges">Why</a> are there too few ridges? + <li><a href="#call">Can</a> Qhull use coordinates without placing them in + a data file? + <li><a href="#size">How</a> large are Qhull's data structures? + <li><a href="#inc">Can</a> Qhull construct convex hulls and Delaunay + triangulations one point at a time? + <li><a href="#ridges2">How</a> do I visit the ridges of a Delaunay + triangulation? + <li><a href="#listd">How</a> do I visit the Delaunay facets? + <LI><a + href="#outside">When</a> is a point outside or inside a facet? + <li><a href="#closest">How</a> do I find the facet that is closest to a + point? + <li><a href="#vclosest">How</a> do I find the Delaunay triangle or Voronoi + region that is closest to a point? + <li><a href="#vertices">How</a> do I list the vertices? + <li><a href="#test">How</a> do I test code that uses the Qhull library? + <li><a href="#orient">When</a> I compute a plane + equation from a facet, I sometimes get an + outward-pointing normal and sometimes an + inward-pointing normal</li> + </ul> + </li> +</ul> + +<hr> + +<h2><a href="#TOC">»</a><a name="startup">Startup</a> questions</h2> + +<h4><a href="#TOC">»</a><a name="console">How</a> do I run Qhull +from Windows?</h4><blockquote> + +<p>Qhull is a console program. You will first need a command window +(i.e., a "command prompt"). You can double click on +'eg\Qhull-go.bat'. </p> + +<blockquote><ul> + <li>Type 'qconvex', 'qdelaunay', 'qhalf', 'qvoronoi, + 'qhull', and 'rbox' for a synopsis of each program. + + <li>Type 'rbox c D2 | qconvex s i' to compute the + convex hull of a square. + + <li>Type 'rbox c D2 | qconvex s i TO results.txt' to + write the results to the file 'results.txt'. A summary is still printed on + the the console. + + <li>Type 'rbox c D2' to see the input format for + qconvex. + + <li>Type 'qconvex < data.txt s i TO results.txt' to + read input data from 'data.txt'. + + <li>If you want to enter data by hand, type 'qconvex s i TO + results.txt' to read input data from the console. Type in + the numbers and end with a ctrl-D. </li> +</ul></blockquote> + +</blockquote><h4><a href="#TOC">»</a><a name="input">How</a> do I enter +points for Qhull?</h4><blockquote> + +<p>Qhull takes its data from standard input. For example, create +a file named 'data.txt' with the following contents: </p> + +<blockquote> + <pre> +2 #sample 2-d input +5 #number of points +1 2 #coordinates of points +-1.1 3 +3 2.2 +4 5 +-10 -10 +</pre> +</blockquote> + +<p>Then call qconvex with 'qconvex < data.txt'. It will print a +summary of the convex hull. Use 'qconvex < data.txt o' to print +the vertices and edges. See also <a href="index.htm#input">input +format</a>. </p> + +<p>You can generate sample data with rbox, e.g., 'rbox 10' +generates 10 random points in 3-d. Use a pipe ('|') to run rbox +and qhull together, e.g., </p> + +<blockquote> + <p>rbox c | qconvex o </p> +</blockquote> + +<p>computes the convex hull of a cube. </p> + +</blockquote><h4><a href="#TOC">»</a><a name="learn">How</a> do I learn to +use Qhull?</h4><blockquote> + +<p>First read: </p> + +<ul> + <li><a href="index.htm">Introduction</a> to Qhull + <li><a href="index.htm#when">When</a> to use Qhull + <li><a href="qconvex.htm">qconvex</a> -- convex hull + <li><a href="qdelaun.htm">qdelaunay</a> -- Delaunay triangulation + <li><a href="qhalf.htm">qhalf</a> -- half-space intersection about a point + + <li><a href="qvoronoi.htm">qvoronoi</a> -- Voronoi diagram + <li><a href="rbox.htm">Rbox</a>, for sample inputs + <li><a href="qh-eg.htm">Examples</a> of Qhull</li> +</ul> + +<p>Look at Qhull's on-line documentation: </p> + +<ul> + <li>'qconvex' gives a synopsis of qconvex and its options + + <li>'rbox' lists all of the options for generating point + sets + <li>'qconvex - | more' lists the options for qconvex + <li>'qconvex .' gives a concise list of options + <li>'qdelaunay', 'qhalf', 'qvoronoi', and 'qhull' also have a synopsis and option list</li> +</ul> + +<p>Then try out the Qhull programs on small examples. </p> + +<ul> + <li>'rbox c' lists the vertices of a cube + <li>'rbox c | qconvex' is the convex hull of a cube + <li>'rbox c | qconvex o' lists the vertices and facets of + a cube + <li>'rbox c | qconvex Qt o' triangulates the cube + <li>'rbox c | qconvex QJ o' joggles the input and + triangulates the cube + <li>'rbox c D2 | qconvex' generates the convex hull of a + square + <li>'rbox c D4 | qconvex' generates the convex hull of a + hypercube + <li>'rbox 6 s D2 | qconvex p Fx' lists 6 random points in + a circle and lists the vertices of their convex hull in order + <li>'rbox c D2 c G2 | qdelaunay' computes the Delaunay + triangulation of two embedded squares. It merges the cospherical facets. + <li>'rbox c D2 c G2 | qdelaunay Qt' computes the Delaunay + triangulation of two embedded squares. It triangulates the cospherical facets. + <li>'rbox c D2 c G2 | qvoronoi o' computes the + corresponding Voronoi vertices and regions. + <li>'rbox c D2 c G2 | qvoronio Fv' shows the Voronoi diagram + for the previous example. Each line is one edge of the + diagram. The first number is 4, the next two numbers list + a pair of input sites, and the last two numbers list the + corresponding pair of Voronoi vertices. </li> +</ul> + +<p>Install <a href="http://www.geomview.org">Geomview</a> +if you are running SGI Irix, Solaris, SunOS, Linux, HP, IBM +RS/6000, DEC Alpha, or Next. You can then visualize the output of +Qhull. Qhull comes with Geomview <a href="qh-eg.htm">examples</a>. +</p> + +<p>Then try Qhull with a small example of your application. Work +out the results by hand. Then experiment with Qhull's options to +find the ones that you need. </p> + +<p>You will need to decide how Qhull should handle precision +problems. It can triangulate the output ('<a + href="qh-optq.htm#Qt" >Qt</a>'), joggle the input ('<a + href="qh-optq.htm#QJn" >QJ</a>'), or merge facets (the default). </p> + +<ul> + <li>With joggle, Qhull produces simplicial (i.e., + triangular) output by joggling the input. After joggle, + no points are cocircular or cospherical. + <li>With facet merging, Qhull produces a better + approximation and does not modify the input. + <li>With triangulated output, Qhull merges facets and triangulates + the result.</li> + <li>See <a href="qh-impre.htm#joggle">Merged facets or joggled input</a>. </li> +</ul> + +</blockquote> +<h2><a href="#TOC">»</a><a name="convex">Convex hull questions</a></h2> + +<h4><a href="#TOC">»</a><a name="area">How</a> do I report just the area + and volume of a convex hull?</h4><blockquote> + +Use option 'FS'. For example, + +<blockquote><pre> +C:\qhull>rbox 10 | qconvex FS +0 +2 2.192915621644613 0.2027867899638665 + +C:\qhull>rbox 10 | qconvex FA + +Convex hull of 10 points in 3-d: + + Number of vertices: 10 + Number of facets: 16 + +Statistics for: RBOX 10 | QCONVEX FA + + Number of points processed: 10 + Number of hyperplanes created: 28 + Number of distance tests for qhull: 44 + CPU seconds to compute hull (after input): 0 + Total facet area: 2.1929156 + Total volume: 0.20278679 +</pre></blockquote> + +</blockquote><h4><a href="#TOC">»</a><a name="extra">Why</a> are there extra +points in a 4-d or higher convex hull?</h4><blockquote> + +<p>You may see extra points if you use options '<a + href="qh-opto.htm#i" >i</a>' or '<a href="qh-optf.htm#Ft">Ft</a>' + without using triangulated output ('<a href="qh-optq.htm#Qt">Qt</a>'). +The extra points occur when a facet is non-simplicial (i.e., a +facet with more than <i>d</i> vertices). For example, Qhull +reports the following for one facet of the convex hull of a hypercube. +Option 'Pd0:0.5' returns the facet along the positive-x axis: </p> + +<blockquote> + <pre> +rbox c D4 | qconvex i Pd0:0.5 +12 +17 13 14 15 +17 13 12 14 +17 11 13 15 +17 14 11 15 +17 10 11 14 +17 14 12 8 +17 12 13 8 +17 10 14 8 +17 11 10 8 +17 13 9 8 +17 9 11 8 +17 11 9 13 +</pre> +</blockquote> + +<p>The 4-d hypercube has 16 vertices; so point "17" was +added by qconvex. Qhull adds the point in order to report a +simplicial decomposition of the facet. The point corresponds to +the "centrum" which Qhull computes to test for +convexity. </p> + +<p>Triangulate the output ('<a href="qh-optq.htm#Qt">Qt</a>') to avoid the extra points. +Since the hypercube is 4-d, each simplicial facet is a tetrahedron. +<blockquote> +<pre> +C:\qhull3.1>rbox c D4 | qconvex i Pd0:0.5 Qt +9 +9 13 14 15 +12 9 13 14 +9 11 13 15 +11 9 14 15 +9 10 11 14 +12 9 14 8 +9 12 13 8 +9 10 14 8 +10 9 11 8 +</pre> +</blockquote> + +<p>Use the '<a href="qh-optf.htm#Fv">Fv</a>' option to print the +vertices of simplicial and non-simplicial facets. For example, +here is the same hypercube facet with option 'Fv' instead of 'i': +</p> + +<blockquote> + <pre> +C:\qhull>rbox c D4 | qconvex Pd0:0.5 Fv +1 +8 9 10 12 11 13 14 15 8 +</pre> +</blockquote> + +<p>The coordinates of the extra point are printed with the '<A + href="qh-optf.htm#Ft" >Ft</a>' option. </p> + +<blockquote> + <pre> +rbox c D4 | qconvex Pd0:0.5 Ft +4 +17 12 3 + -0.5 -0.5 -0.5 -0.5 + -0.5 -0.5 -0.5 0.5 + -0.5 -0.5 0.5 -0.5 + -0.5 -0.5 0.5 0.5 + -0.5 0.5 -0.5 -0.5 + -0.5 0.5 -0.5 0.5 + -0.5 0.5 0.5 -0.5 + -0.5 0.5 0.5 0.5 + 0.5 -0.5 -0.5 -0.5 + 0.5 -0.5 -0.5 0.5 + 0.5 -0.5 0.5 -0.5 + 0.5 -0.5 0.5 0.5 + 0.5 0.5 -0.5 -0.5 + 0.5 0.5 -0.5 0.5 + 0.5 0.5 0.5 -0.5 + 0.5 0.5 0.5 0.5 + 0.5 0 0 0 +4 16 13 14 15 +4 16 13 12 14 +4 16 11 13 15 +4 16 14 11 15 +4 16 10 11 14 +4 16 14 12 8 +4 16 12 13 8 +4 16 10 14 8 +4 16 11 10 8 +4 16 13 9 8 +4 16 9 11 8 +4 16 11 9 13 +</pre> +</blockquote> + +</blockquote><h4><a href="#TOC">»</a><a name="dup">How</a> do I report +duplicate vertices?</h4><blockquote> + +<p>There's no direct way. You can use option +'<a href="qh-optf.htm#FP">FP</a>' to +report the distance to the nearest vertex for coplanar input +points. Select the minimum distance for a duplicated vertex, and +locate all input sites less than this distance. </p> + +<p>For Delaunay triangulations, all coplanar points are nearly +incident to a vertex. If you want a report of coincident input +sites, do not use option '<a href="qh-optq.htm#QJn">QJ</a>'. By +adding a small random quantity to each input coordinate, it +prevents coincident input sites. </p> + +</blockquote> +<h2><a href="#TOC">»</a><a name="delaunay">Delaunay triangulation questions</a></h2> + +<h4><a href="#TOC">»</a><a name="flat">How</a> do I get rid of +nearly flat Delaunay triangles?</h4><blockquote> + +<p>Nearly flat triangles occur when boundary points are nearly +collinear or coplanar. They also occur for nearly coincident +points. Both events can easily occur when using joggle. For example +(rbox 10 W0 D2 | qdelaunay QJ Fa) lists the areas of the Delaunay +triangles of 10 points on the boundary of a square. Some of +these triangles are nearly flat. This occurs when one point +is joggled inside of two other points. In this case, nearly flat +triangles do not occur with triangulated output (rbox 10 W0 D2 | qdelaunay Qt Fa). + + +<p>Another example, (rbox c P0 P0 D2 | qdelaunay QJ Fa), computes the +areas of the Delaunay triangles for the unit square and two +instances of the origin. Four of the triangles have an area +of 0.25 while two have an area of 2.0e-11. The later are due to +the duplicated origin. With triangulated output (rbox c P0 P0 D2 | qdelaunay Qt Fa) +there are four triangles of equal area. + +<p>Nearly flat triangles also occur without using joggle. For +example, (rbox c P0 P0,0.4999999999 | qdelaunay Fa), computes +the areas of the Delaunay triangles for the unit square, +a nearly collinear point, and the origin. One triangle has an +area of 3.3e-11. + +<p>Unfortunately, none of Qhull's merging options remove nearly +flat Delaunay triangles due to nearly collinear or coplanar boundary +points. +The merging options concern the empty circumsphere +property of Delaunay triangles. This is independent of the area of +the Delaunay triangles. Qhull does handle nearly coincident points. + +<p>If you are calling Qhull from a program, you can merge slivers into an adjacent facet. +In d dimensions with simplicial facets (e.g., from 'Qt'), each facet has +d+1 neighbors. Each neighbor shares d vertices of the facet's d+1 vertices. Let the +other vertex be the <i>opposite</i> vertex. For each neighboring facet, if its circumsphere +includes the opposite.vertex, the two facets can be merged. [M. Treacy] + +<p>You can handle collinear or coplanar boundary points by +enclosing the points in a box. For example, +(rbox c P0 P0,0.4999999999 c G1 | qdelaunay Fa), surrounds the +previous points with [(1,1), (1,-1), (-1,-1), (-1, 1)]. +Its Delaunay triangulation does not include a +nearly flat triangle. The box also simplifies the graphical +output from Qhull. + +<p>Without joggle, Qhull lists coincident points as "coplanar" +points. For example, (rbox c P0 P0 D2 | qdelaunay Fa), ignores +the duplicated origin and lists four triangles of size 0.25. +Use 'Fc' to list the coincident points (e.g., +rbox c P0 P0 D2 | qdelaunay Fc). + +<p>There is no easy way to determine coincident points with joggle. +Joggle removes all coincident, cocircular, and cospherical points +before running Qhull. Instead use facet merging (the default) +or triangulated output ('<a href="qh-optq.htm#Qt">Qt</a>'). + +</blockquote><h4><a href="#TOC">»</a><a name="mesh">How</a> do I compute +the Delaunay triangulation of a non-convex object?</h4><blockquote> + +<p>A similar question is +"How do I mesh a volume from a set of triangulated surface points?" + +<p>This is an instance of the constrained Delaunay Triangulation +problem. Qhull does not handle constraints. The boundary of the +Delaunay triangulation is always convex. But if the input set +contains enough points, the triangulation will include the +boundary. The number of points needed depends on the input. + +<p>Shewchuk has developed a theory of constrained Delaunay triangulations. +See his +<a href="http://www.cs.cmu.edu/~jrs/jrspapers.html#cdt">paper</a> at the +1998 Computational Geometry Conference. Using these ideas, constraints +could be added to Qhull. They would have many applications. + +<p>There is a large literature on mesh generation and many commercial +offerings. For pointers see +<a href="http://www.imr.sandia.gov/papers/topics.html">Owen's International Meshing Roundtable</a> +and <a href="http://www.robertschneiders.de/meshgeneration/meshgeneration.html">Schneiders' +Finite Element Mesh Generation page</a>.</p> + +</blockquote><h4><a href="#TOC">»</a><a name="constrained">Can</a> Qhull +produce a triangular mesh for an object?</h4><blockquote> + +<p>Yes for convex objects, no for non-convex objects. For +non-convex objects, it triangulates the concavities. Unless the +object has many points on its surface, triangles may cross the +surface. </p> + +</blockquote><h4><a href="#TOC">»</a><a name="dridges">For</a> 3-d Delaunay +triangulations, how do I report the triangles of each +tetrahedron?</h4><blockquote> + +<p>For points in general position, a 3-d Delaunay triangulation +generates tetrahedron. Each face of a tetrahedron is a triangle. +For example, the 3-d Delaunay triangulation of random points on +the surface of a cube, is a cellular structure of tetrahedron. </p> + +<p>Use triangulated output ('qdelaunay Qt i') or joggled input ('qdelaunay QJ i') +to generate the Delaunay triangulation. +Option 'i' reports each tetrahedron. The triangles are +every combination of 3 vertices. Each triangle is a +"ridge" of the Delaunay triangulation. </p> + +<p>For example, </p> + +<pre> + rbox 10 | qdelaunay Qt i + 14 + 9 5 8 7 + 0 9 8 7 + 5 3 8 7 + 3 0 8 7 + 5 4 8 1 + 4 6 8 1 + 2 9 5 8 + 4 2 5 8 + 4 2 9 5 + 6 2 4 8 + 9 2 0 8 + 2 6 0 8 + 2 4 9 1 + 2 6 4 1 +</pre> + +<p>is the Delaunay triangulation of 10 random points. Ridge 9-5-8 +occurs twice. Once for tetrahedron 9 5 8 7 and the other for +tetrahedron 2 9 5 8. </p> + +<p>You can also use the Qhull library to generate the triangles. +See "<a href="#ridges2">How</a> do I visit the ridges of a +Delaunay triangulation?"</p> + +</blockquote><h4><a href="#TOC">»</a><a name="3dd">How</a> do I construct a +3-d Delaunay triangulation?</h4><blockquote> + +<p>For 3-d Delaunay triangulations with cospherical input sites, +use triangulated output ('<a href="qh-optq.htm#Qt">Qt</a>') or +joggled input ('<a href="qh-optq.htm#QJn">QJ</a>'). Otherwise +option 'i' will +triangulate non-simplicial facets by adding a point to the facet. + +<p>If you want non-simplicial output for cospherical sites, use +option +'<a href="qh-optf.htm#Fv">Fv</a>' or '<a href="qh-opto.htm#o">o</a>'. +For option 'o', ignore the last coordinate. It is the lifted +coordinate for the corresponding convex hull in 4-d. + +<p>The following example is a cube +inside a tetrahedron. The 8-vertex facet is the cube. Ignore the +last coordinates. </p> + +<blockquote> + <pre> +C:\qhull>rbox r y c G0.1 | qdelaunay Fv +4 +12 20 44 + 0.5 0 0 0.3055555555555555 + 0 0.5 0 0.3055555555555555 + 0 0 0.5 0.3055555555555555 + -0.5 -0.5 -0.5 0.9999999999999999 + -0.1 -0.1 -0.1 -6.938893903907228e-018 + -0.1 -0.1 0.1 -6.938893903907228e-018 + -0.1 0.1 -0.1 -6.938893903907228e-018 + -0.1 0.1 0.1 -6.938893903907228e-018 + 0.1 -0.1 -0.1 -6.938893903907228e-018 + 0.1 -0.1 0.1 -6.938893903907228e-018 + 0.1 0.1 -0.1 -6.938893903907228e-018 + 0.1 0.1 0.1 -6.938893903907228e-018 +4 2 11 1 0 +4 10 1 0 3 +4 11 10 1 0 +4 2 9 0 3 +4 9 11 2 0 +4 7 2 1 3 +4 11 7 2 1 +4 8 10 0 3 +4 9 8 0 3 +5 8 9 10 11 0 +4 10 6 1 3 +4 6 7 1 3 +5 6 8 10 4 3 +5 6 7 10 11 1 +4 5 9 2 3 +4 7 5 2 3 +5 5 8 9 4 3 +5 5 6 7 4 3 +8 5 6 8 7 9 10 11 4 +5 5 7 9 11 2 +</pre> +</blockquote> + +<p>If you want simplicial output use options +'<a href="qh-optq.htm#Qt">Qt</a> <A + href="qh-optf.htm#Ft" >i</a>' or +'<a href="qh-optq.htm#QJn">QJ</a> <A + href="qh-optf.htm#Ft" >i</a>', e.g., +</p> + +<blockquote> + <pre> +rbox r y c G0.1 | qdelaunay Qt i +31 +2 11 1 0 +11 10 1 0 +9 11 2 0 +11 7 2 1 +8 10 0 3 +9 8 0 3 +10 6 1 3 +6 7 1 3 +5 9 2 3 +7 5 2 3 +9 8 10 11 +8 10 11 0 +9 8 11 0 +6 8 10 4 +8 6 10 3 +6 8 4 3 +6 7 10 11 +10 6 11 1 +6 7 11 1 +8 5 4 3 +5 8 9 3 +5 6 4 3 +6 5 7 3 +5 9 10 11 +8 5 9 10 +7 5 10 11 +5 6 7 10 +8 5 10 4 +5 6 10 4 +5 9 11 2 +7 5 11 2 +</pre> +</blockquote> + +</blockquote><h4><a href="#TOC">»</a><a name="2d">How</a> do I get the +triangles for a 2-d Delaunay triangulation and the vertices of +its Voronoi diagram?</h4><blockquote> + +<p>To compute the Delaunay triangles indexed by the indices of +the input sites, use </p> + +<blockquote> + <p>rbox 10 D2 | qdelaunay Qt i </p> +</blockquote> + +<p>To compute the Voronoi vertices and the Voronoi region for +each input site, use </p> + +<blockquote> + <p>rbox 10 D2 | qvoronoi o </p> +</blockquote> + +<p>To compute each edge ("ridge") of the Voronoi +diagram for each pair of adjacent input sites, use</p> + +<blockquote> + <p>rbox 10 D2 | qvoronoi Fv </p> +</blockquote> + +<p>To compute the area and volume of the Voronoi region for input site 5 (site 0 is the first one), +use </p> + +<blockquote> + <p>rbox 10 D2 | qvoronoi QV5 p | qconvex s FS </p> +</blockquote> + +<p>To compute the lines ("hyperplanes") that define the +Voronoi region for input site 5, use </p> + +<blockquote> + <p>rbox 10 D2 | qvoronoi QV5 p | qconvex n </p> +</blockquote> +or +<blockquote> + <p>rbox 10 D2 | qvoronoi QV5 Fi Fo</p> +</blockquote> + +<p>To list the extreme points of the input sites use </p> + +<blockquote> + <p>rbox 10 D2 | qdelaunay Fx </p> +</blockquote> + +<p>You will get the same point ids with </p> + +<blockquote> + <p>rbox 10 D2 | qconvex Fx </p> +</blockquote> + +</blockquote><h4><a href="#TOC">»</a><a name="big">Can </a>Qhull triangulate +a hundred 16-d points?</h4><blockquote> + +<p>No. This is an immense structure. A triangulation of 19, 16-d +points has 43 simplices. If you add one point at a time, the +triangulation increased as follows: 43, 189, 523, 1289, 2830, +6071, 11410, 20487. The last triangulation for 26 points used 13 +megabytes of memory. When Qhull uses virtual memory, it becomes +too slow to use. </p> + +</blockquote> +<h2><a href="#TOC">»</a><a name="voronoi">Voronoi +diagram questions</a></h2> + +<h4><a href="#TOC">»</a><a name="volume">How</a> do I compute the volume of a Voronoi region?</h4><blockquote> + +<p>For each Voronoi region, compute the convex hull of the region's Voronoi vertices. The volume of each convex hull is the volume +of the corresponding Vornoi region.</p> + +<p>For example, to compute the volume of the bounded Voronoi region about [0,0,0]: output the origin's Voronoi vertices and +compute the volume of their convex hull. The last number from option '<a href="qh-optf.htm#FS">FS</a>' is the volume.</p> +<blockquote><pre> +rbox P0 10 | qvoronoi QV0 p | qhull FS +0 +2 1.448134756744281 0.1067973560800857 +</pre></blockquote> + +<p>For another example, see <a href="#2d">How</a> do I get the triangles for a 2-d Delaunay + triangulation and the vertices of its Voronoi diagram?</p> + +<p>This approach is slow if you are using the command line. A faster approcach is to call Qhull from +a program. The fastest method is Clarkson's <a href="http://www.netlib.org/voronoi/hull.html">hull</a> program. +It computes the volume for all Voronoi regions.</p> + +<p>An unbounded Voronoi region does not have a volume.</p> + +</blockquote><h4><a href="#TOC">»</a><a name="maxsphere">How</a> do I get the radii of the empty + spheres for each Voronoi vertex?</h4><blockquote> + +Use option '<a href="qh-optf.htm#Fi">Fi</a>' to list each bisector (i.e. Delaunay ridge). Then compute the +minimum distance for each Voronoi vertex. + +<p>There's other ways to get the same information. Let me know if you +find a better method. + +</blockquote><h4><a href="#TOC">»</a><a name="square">What</a> is the Voronoi diagram + of a square?</h4><blockquote> + +<p> +Consider a square, +<blockquote><pre> +C:\qhull>rbox c D2 +2 RBOX c D2 +4 + -0.5 -0.5 + -0.5 0.5 + 0.5 -0.5 + 0.5 0.5 +</pre></blockquote> + +<p>There's two ways to compute the Voronoi diagram: with facet merging +or with joggle. With facet merging, the +result is: + +<blockquote><pre> +C:\qhull>rbox c D2 | qvoronoi Qz + +Voronoi diagram by the convex hull of 5 points in 3-d: + + Number of Voronoi regions and at-infinity: 5 + Number of Voronoi vertices: 1 + Number of facets in hull: 5 + +Statistics for: RBOX c D2 | QVORONOI Qz + + Number of points processed: 5 + Number of hyperplanes created: 7 + Number of distance tests for qhull: 8 + Number of merged facets: 1 + Number of distance tests for merging: 29 + CPU seconds to compute hull (after input): 0 + +C:\qhull>rbox c D2 | qvoronoi Qz o +2 +2 5 1 +-10.101 -10.101 + 0 0 +2 0 1 +2 0 1 +2 0 1 +2 0 1 +0 + +C:\qhull>rbox c D2 | qvoronoi Qz Fv +4 +4 0 1 0 1 +4 0 2 0 1 +4 1 3 0 1 +4 2 3 0 1 +</pre></blockquote> + +<p>There is one Voronoi vertex at the origin and rays from the origin +along each of the coordinate axes. +The last line '4 2 3 0 1' means that there is +a ray that bisects input points #2 and #3 from infinity (vertex 0) to +the origin (vertex 1). +Option 'Qz' adds an artificial point since the input is cocircular. +Coordinates -10.101 indicate the +vertex at infinity. + +<p>With triangulated output, the Voronoi vertex is +duplicated: + +<blockquote><pre> +C:\qhull3.1>rbox c D2 | qvoronoi Qt Qz + +Voronoi diagram by the convex hull of 5 points in 3-d: + + Number of Voronoi regions and at-infinity: 5 + Number of Voronoi vertices: 2 + Number of triangulated facets: 1 + +Statistics for: RBOX c D2 | QVORONOI Qt Qz + + Number of points processed: 5 + Number of hyperplanes created: 7 + Number of facets in hull: 6 + Number of distance tests for qhull: 8 + Number of distance tests for merging: 33 + Number of distance tests for checking: 30 + Number of merged facets: 1 + CPU seconds to compute hull (after input): 0.05 + +C:\qhull3.1>rbox c D2 | qvoronoi Qt Qz o +2 +3 5 1 +-10.101 -10.101 + 0 0 + 0 0 +3 2 0 1 +2 1 0 +2 2 0 +3 2 0 1 +0 + +C:\qhull3.1>rbox c D2 | qvoronoi Qt Qz Fv +4 +4 0 2 0 2 +4 0 1 0 1 +4 1 3 0 1 +4 2 3 0 2 +</pre></blockquote> + + +<p>With joggle, the input is no longer cocircular and the Voronoi vertex is +split into two: + +<blockquote><pre> +C:\qhull>rbox c D2 | qvoronoi Qt Qz + +C:\qhull>rbox c D2 | qvoronoi QJ o +2 +3 4 1 +-10.101 -10.101 +-4.71511718558304e-012 -1.775812830118184e-011 +9.020340030474472e-012 -4.02267108512433e-012 +2 0 1 +3 2 1 0 +3 2 0 1 +2 2 0 + +C:\qhull>rbox c D2 | qvoronoi QJ Fv +5 +4 0 2 0 1 +4 0 1 0 1 +4 1 2 1 2 +4 1 3 0 2 +4 2 3 0 2 +</pre></blockquote> + +<p>Note that the Voronoi diagram includes the same rays as + before plus a short edge between the two vertices.</p> + + +</blockquote><h4><a href="#TOC">»</a><a name="vsphere">How</a> do I construct +the Voronoi diagram of cospherical points?</h4><blockquote> + +<p>Three-d terrain data can be approximated with cospherical +points. The Delaunay triangulation of cospherical points is the +same as their convex hull. If the points lie on the unit sphere, +the facet normals are the Voronoi vertices [via S. Fortune]. </p> + +<p>For example, consider the points {[1,0,0], [-1,0,0], [0,1,0], +...}. Their convex hull is: </p> + +<pre> +rbox d G1 | qconvex o +3 +6 8 12 + 0 0 -1 + 0 0 1 + 0 -1 0 + 0 1 0 + -1 0 0 + 1 0 0 +3 3 1 4 +3 1 3 5 +3 0 3 4 +3 3 0 5 +3 2 1 5 +3 1 2 4 +3 2 0 4 +3 0 2 5 +</pre> + +<p>The facet normals are: </p> + +<pre> +rbox d G1 | qconvex n +4 +8 +-0.5773502691896258 0.5773502691896258 0.5773502691896258 -0.5773502691896258 + 0.5773502691896258 0.5773502691896258 0.5773502691896258 -0.5773502691896258 +-0.5773502691896258 0.5773502691896258 -0.5773502691896258 -0.5773502691896258 + 0.5773502691896258 0.5773502691896258 -0.5773502691896258 -0.5773502691896258 + 0.5773502691896258 -0.5773502691896258 0.5773502691896258 -0.5773502691896258 +-0.5773502691896258 -0.5773502691896258 0.5773502691896258 -0.5773502691896258 +-0.5773502691896258 -0.5773502691896258 -0.5773502691896258 -0.5773502691896258 + 0.5773502691896258 -0.5773502691896258 -0.5773502691896258 -0.5773502691896258 +</pre> + +<p>If you drop the offset from each line (the last number), each +line is the Voronoi vertex for the corresponding facet. The +neighboring facets for each point define the Voronoi region for +each point. For example: </p> + +<pre> +rbox d G1 | qconvex FN +6 +4 7 3 2 6 +4 5 0 1 4 +4 7 4 5 6 +4 3 1 0 2 +4 6 2 0 5 +4 7 3 1 4 +</pre> + +<p>The Voronoi vertices {7, 3, 2, 6} define the Voronoi region +for point 0. Point 0 is [0,0,-1]. Its Voronoi vertices are </p> + +<pre> +-0.5773502691896258 0.5773502691896258 -0.5773502691896258 + 0.5773502691896258 0.5773502691896258 -0.5773502691896258 +-0.5773502691896258 -0.5773502691896258 -0.5773502691896258 + 0.5773502691896258 -0.5773502691896258 -0.5773502691896258 +</pre> + +<p>In this case, the Voronoi vertices are oriented, but in +general they are unordered. </p> + +<p>By taking the dual of the Delaunay triangulation, you can +construct the Voronoi diagram. For cospherical points, the convex +hull vertices for each facet, define the input sites for each +Voronoi vertex. In 3-d, the input sites are oriented. For +example: </p> + +<pre> +rbox d G1 | qconvex i +8 +3 1 4 +1 3 5 +0 3 4 +3 0 5 +2 1 5 +1 2 4 +2 0 4 +0 2 5 +</pre> + +<p>The convex hull vertices for facet 0 are {3, 1, 4}. So Voronoi +vertex 0 (i.e., [-0.577, 0.577, 0.577]) is the Voronoi vertex for +input sites {3, 1, 4} (i.e., {[0,1,0], [0,0,1], [-1,0,0]}). </p> + +</blockquote><h4><a href="#TOC">»</a><a name="rays">Can</a> Qhull compute the +unbounded rays of the Voronoi diagram?</h4><blockquote> + +<p>Use '<a href="qh-optf.htm#Fo2">Fo</a>' to compute the separating +hyperplanes for unbounded Voronoi regions. The corresponding ray +goes to infinity from the Voronoi vertices. If you enclose the +input sites in a large enough box, the outermost bounded regions +will represent the unbounded regions of the original points. </p> + +<p>If you do not box the input sites, you can identify the +unbounded regions. They list '0' as a vertex. Vertex 0 represents +"infinity". Each unbounded ray includes vertex 0 in +option '<a href="qh-optf.htm#Fv2">Fv</a>. See <A + href="qvoronoi.htm#graphics" >Voronoi graphics</a> and <A + href="qvoronoi.htm#notes" >Voronoi notes</a>. </p> + +</blockquote> +<h2><a href="#TOC">»</a>Approximation questions</h2> + +<h4><a href="#TOC">»</a><a name="simplex">How</a> do I +approximate data with a simplex</h4><blockquote> + +<p>Qhull may be used to help select a simplex that approximates a +data set. It will take experimentation. Geomview will help to +visualize the results. This task may be difficult to do in 5-d +and higher. Use rbox options 'x' and 'y' to produce random +distributions within a simplex. Your methods work if you can +recover the simplex. </p> + +<p>Use Qhull's precision options to get a first approximation to +the hull, say with 10 to 50 facets. For example, try 'C0.05' to +remove small facets after constructing the hull. Use 'W0.05' to +ignore points within 0.05 of a facet. Use 'PA5' to print the five +largest facets by area. </p> + +<p>Then use other methods to fit a simplex to this data. Remove +outlying vertices with few nearby points. Look for large facets +in different quadrants. You can use option 'Pd0d1d2' to print all +the facets in a quadrant. </p> + +<p>In 4-d and higher, use the outer planes (option 'Fo' or +'facet->maxoutside') since the hyperplane of an approximate +facet may be below many of the input points. </p> + +<p>For example, consider fitting a cube to 1000 uniformly random +points in the unit cube. In this case, the first try was good: </p> + +<blockquote> + <pre> +rbox 1000 | qconvex W0.05 C0.05 PA6 Fo +4 +6 +0.35715408374381 0.08706467018177928 -0.9299788727015564 -0.5985514741284483 +0.995841591359023 -0.02512604712761577 0.08756829720435189 -0.5258834069202866 +0.02448099521570909 -0.02685210459017302 0.9993396046151313 -0.5158104982631999 +-0.9990223929415094 -0.01261133513150079 0.04236994958247349 -0.509218270408407 +-0.0128069014364698 -0.9998380680115362 0.01264203427283151 -0.5002512653670584 +0.01120895057872914 0.01803671994177704 -0.9997744926535512 -0.5056824072956361 +</pre> +</blockquote> + +</blockquote> +<h2><a href="#TOC">»</a>Halfspace questions</h2> + +<h4><a href="#TOC">»</a><a name="halfspace">How</a> do I compute the + intersection of halfspaces with Qhull?</h4><blockquote> + +<p>Qhull computes the halfspace intersection about a point. The +point must be inside all of the halfspaces. Given a point, a +duality turns a halfspace intersection problem into a convex +hull problem. + +<p>Use linear programming if you +do not know a point in the interior of the halfspaces. +See the <a href="qhalf.htm#notes">notes</a> for qhalf. You will need + a linear programming code. This may require a fair amount of work to + implement.</p> + + + +</blockquote> +<h2><a href="#TOC">»</a><a name="library">Qhull library +questions</a></h2> + +<h4><a href="#TOC">»</a><a name="math">Is</a> Qhull available for Mathematica, Matlab, or Maple?</h4><blockquote> + +<p><b>MATLAB</b> + +<p>Z. You of <a href="http://www.mathworks.com">MathWorks</a> added qhull to MATLAB 6. +See functions <a href="http://www.mathworks.com/help/techdoc/ref/convhulln.html" + >convhulln</a>, + <a href="http://www.mathworks.com/help/techdoc/ref/delaunayn.html" + >delaunayn</a>, + <a href="http://www.mathworks.com/help/techdoc/ref/griddata3.html" + >griddata3</a>, + <a href="http://www.mathworks.com/help/techdoc/ref/griddatan.html" + >griddatan</a>, + <a href="http://www.mathworks.com/help/techdoc/ref/tsearch.html" + >tsearch</a>, + <a href="http://www.mathworks.com/help/techdoc/ref/tsearchn.html" + >tsearchn</a>, and + <a href="http://www.mathworks.com/help/techdoc/ref/voronoin.html" + >voronoin</a>. V. Brumberg update MATLAB R14 for Qhull 2003.1 and triangulated output. + +<p>Engwirda wrote <a href="http://www.mathworks.com/matlabcentral/fileexchange/loadFile.do?objectId=10307&objectType=file">mesh2d</a> for unstructured mesh generation in MATLAB. +It is based on the iterative method of Persson and generally results in better quality meshes than delaunay refinement. + + +<p><b>Mathematica and Maple</b> + +<p>See <a href="http://library.wolfram.com/infocenter/MathSource/1160/" + >qh-math</a> +for a Delaunay interface to Mathematica. It includes projects for CodeWarrior +on the Macintosh and Visual C++ on Win32 PCs. + +<p>See Mathematica ('<a +href="qh-opto.htm#m">m</a>') and Maple ('<a +href="qh-optf.htm#FM">FM</a>') output options. + +<p></p> +</blockquote><h4><a href="#TOC">»</a><a name="ridges">Why</a> are there too few ridges?</h4><blockquote> + +The following sample code may produce fewer ridges than expected: + +<blockquote><pre> + facetT *facetp; + ridgeT *ridge, **ridgep; + + FORALLfacets { + printf("facet f%d\n", facet->id); + FOREACHridge_(facet->ridges) { + printf(" ridge r%d between f%d and f%d\n", ridge->id, ridge->top->id, ridge->bottom->id); + } + } +</pre></blockquote> + +<p> Qhull does not create ridges for simplicial facets. +Instead it computes ridges from facet->neighbors. To make ridges for a +simplicial facet, use qh_makeridges() in merge.c. Usefacet->visit_id to visit +each ridge once (instead of twice). For example, + +<blockquote><pre> + facetT *facet, *neighbor; + ridgeT *ridge, **ridgep; + + qh visit_id++; + FORALLfacets { + printf("facet f%d\n", facet->id); + qh_makeridges(facet); + facet->visitId= qh visit_id; + FOREACHridge_(facet->ridges) { + neighbor= otherfacet_(ridge, visible); + if (neighbor->visitid != qh visit_id) + printf(" ridge r%d between f%d and f%d\n", ridge->id, ridge->top->id, ridge->bottom->id); + } + } +</pre></blockquote> + +</blockquote><h4><a href="#TOC">»</a><a name="call">Can</a> Qhull use coordinates without placing + them in a data file?</h4><blockquote> + +<p>You may call Qhull from a program. Please use the reentrant Qhull library (libqhullstatic_r.a, libqhull_r.so, or qhull_r.dll). + +See user_eg.c and "Qhull-template" in user_r.c for examples.. + +See <a href="qh-code.htm">Qhull internals</a> for an introduction to Qhull's reentrant library and its C++ interface. + +<p>Hint: Start with a small example for which you know the + answer.</p> + +</blockquote><h4><a href="#TOC">»</a><a name="size">How</a> large are Qhull's data structures?</h4><blockquote> + +<p>Qhull uses a general-dimension data structure. +The size depends on the dimension. Use option 'Ts' to print +out the memory statistics [e.g., 'rbox D2 10 | qconvex Ts']. + + +</blockquote><h4><a href="#TOC">»</a><a name="inc">Can</a> Qhull construct +convex hulls and Delaunay triangulations one point at a time?</h4><blockquote> + +<p>The Qhull library may be used to construct convex hulls and +Delaunay triangulations one point at a time. It may not be used +for deleting points or moving points. </p> + +<p>Qhull is designed for batch processing. Neither Clarkson's +randomized incremental algorithm nor Qhull are designed for +on-line operation. For many applications, it is better to +reconstruct the convex hull or Delaunay triangulation from +scratch for each new point. </p> + +<p>With random point sets and on-line processing, Clarkson's +algorithm should run faster than Qhull. Clarkson uses the +intermediate facets to reject new, interior points, while Qhull, +when used on-line, visits every facet to reject such points. If +used on-line for n points, Clarkson may take O(n) times as much +memory as the average off-line case, while Qhull's space +requirement does not change. </p> + +<p>If you triangulate the output before adding all the points +(option 'Qt' and procedure qh_triangulate), you must set +option '<a href="qh-optq.htm#Q11">Q11</a>'. It duplicates the +normals of triangulated facets and recomputes the centrums. +This should be avoided for regular use since triangulated facets +are not clearly convex with their neighbors. It appears to +work most of the time, but fails for cases that Qhull normally +handles well [see the test call to qh_triangulate in qh_addpoint]. + +</blockquote><h4><a href="#TOC">»</a><a name="ridges2">How</a> do I visit the +ridges of a Delaunay triangulation?</h4><blockquote> + +<p>To visit the ridges of a Delaunay triangulation, visit each +facet. Each ridge will appear twice since it belongs to two +facets. In pseudo-code: </p> + +<pre> + for each facet of the triangulation + if the facet is Delaunay (i.e., part of the lower convex hull) + for each ridge of the facet + if the ridge's neighboring facet has not been visited + ... process a ridge of the Delaunay triangulation ... +</pre> + +<p>In undebugged, C code: </p> + +<pre> + qh visit_id++; + FORALLfacets_(facetlist) + if (!facet->upperdelaunay) { + facet->visitid= qh visit_id; + qh_makeridges(facet); + FOREACHridge_(facet->ridges) { + neighbor= otherfacet_(ridge, facet); + if (neighbor->visitid != qh visit_id) { + /* Print ridge here with facet-id and neighbor-id */ + /*fprintf(fp, "f%d\tf%d\t",facet->id,neighbor->ID);*/ + FOREACHvertex_(ridge->vertices) + fprintf(fp,"%d ",qh_pointid (vertex->point) ); + qh_printfacetNvertex_simplicial (fp, facet, format); + fprintf(fp," "); + if(neighbor->upperdelaunay) + fprintf(fp," -1 -1 -1 -1 "); + else + qh_printfacetNvertex_simplicial (fp, neighbor, format); + fprintf(fp,"\n"); + } + } + } + } +</pre> + +<p>Qhull should be redesigned as a class library, or at least as +an API. It currently provides everything needed, but the +programmer has to do a lot of work. Hopefully someone will write +C++ wrapper classes or a Python module for Qhull. </p> + +</blockquote><h4><a href="#TOC">»</a><a name="listd">How</a> do I visit the +Delaunay regions?</h4><blockquote> + +<p>Qhull constructs a Delaunay triangulation by lifting the +input sites to a paraboloid. The Delaunay triangulation +corresponds to the lower convex hull of the lifted points. To +visit each facet of the lower convex hull, use: </p> + +<pre> + facetT *facet; + + ... + FORALLfacets { + if (!facet->upperdelaunay) { + ... only facets for Delaunay regions ... + } + } +</pre> + +</blockquote><h4><a href="#TOC">»</a><a name="outside">When</a> is a point +outside or inside a facet?</h4><blockquote> + +<p>A point is outside of a facet if it is clearly outside the +facet's outer plane. The outer plane is defined by an offset +(facet->maxoutside) from the facet's hyperplane. </p> + +<pre> + facetT *facet; + pointT *point; + realT dist; + + ... + qh_distplane(point, facet, &dist); + if (dist > facet->maxoutside + 2 * qh DISTround) { + /* point is clearly outside of facet */ + } +</pre> + +<p>A point is inside of a facet if it is clearly inside the +facet's inner plane. The inner plane is computed as the maximum +distance of a vertex to the facet. It may be computed for an +individual facet, or you may use the maximum over all facets. For +example: </p> + +<pre> + facetT *facet; + pointT *point; + realT dist; + + ... + qh_distplane(point, facet, &dist); + if (dist < qh min_vertex - 2 * qh DISTround) { + /* point is clearly inside of facet */ + } +</pre> + +<p>Both tests include two qh.DISTrounds because the computation +of the furthest point from a facet may be off by qh.DISTround and +the computation of the current distance to the facet may be off +by qh.DISTround. </p> + +</blockquote><h4><a href="#TOC">»</a><a name="closest">How</a> do I find the +facet that is closest to a point?</h4><blockquote> + +<p>Use qh_findbestfacet(). For example, </p> + +<pre> + coordT point[ DIM ]; + boolT isoutside; + realT bestdist; + facetT *facet; + + ... set coordinates for point ... + + facet= qh_findbestfacet (point, qh_ALL, &bestdist, &isoutside); + + /* 'facet' is the closest facet to 'point' */ +</pre> + +<p>qh_findbestfacet() performs a directed search for the facet +furthest below the point. If the point lies inside this facet, +qh_findbestfacet() performs an exhaustive search of all facets. +An exhaustive search may be needed because a facet on the far +side of a lens-shaped distribution may be closer to a point than +all of the facet's neighbors. The exhaustive search may be +skipped for spherical distributions. </p> + +<p>Also see, "<a href="#vclosest">How</a> do I find the +Delaunay triangle that is closest to a +point?" </p> + +</blockquote><h4><a href="#TOC">»</a><a name="vclosest">How</a> do I find the +Delaunay triangle or Voronoi region that is closest to a point?</h4><blockquote> + +<p>A Delaunay triangulation subdivides the plane, or in general +dimension, subdivides space. Given a point, how do you determine +the subdivision containing the point? Or, given a set of points, +how do you determine the subdivision containing each point of the set? +Efficiency is important -- an exhaustive search of the subdivision +is too slow. + +<p>First compute the Delaunay triangle with qh_new_qhull() in user_r.c or Qhull::runQhull(). +Lift the point to the paraboloid by summing the squares of the +coordinates. Use qh_findbestfacet() [poly2.c] to find the closest Delaunay +triangle. Determine the closest vertex to find the corresponding +Voronoi region. Do not use options +'<a href="qh-optq.htm#Qbb">Qbb</a>', '<a href="qh-optq.htm#QbB">QbB</a>', +'<a href="qh-optq.htm#Qbk">Qbk:n</a>', or '<A + href="qh-optq.htm#QBk" >QBk:n</a>' since these scale the last +coordinate. Optimizations of qh_findbestfacet() should +be possible for Delaunay triangulations.</p> + +<p>You first need to lift the point to the paraboloid (i.e., the +last coordinate is the sum of the squares of the point's coordinates). +The +routine, qh_setdelaunay() [geom2.c], lifts an array of points to the +paraboloid. The following excerpt is from findclosest() in +user_eg.c. </p> + +<pre> + coordT point[ DIM + 1]; /* one extra coordinate for lifting the point */ + boolT isoutside; + realT bestdist; + facetT *facet; + + ... set coordinates for point[] ... + + qh_setdelaunay (DIM+1, 1, point); + facet= qh_findbestfacet (point, qh_ALL, &bestdist, &isoutside); + /* 'facet' is the closest Delaunay triangle to 'point' */ +</pre> + +<p>The returned facet either contains the point or it is the +closest Delaunay triangle along the convex hull of the input set. + +<p>Point location is an active research area in Computational +Geometry. For a practical approach, see Mucke, et al, "Fast randomized +point location without preprocessing in two- and +three-dimensional Delaunay triangulations," <i>Computational +Geometry '96</i>, p. 274-283, May 1996. +For an introduction to planar point location see [O'Rourke '93]. +Also see, "<A + href="#closest" >How</a> do I find the facet that is closest to a +point?" </p> + +<p>To locate the closest Voronoi region, determine the closest +vertex of the closest Delaunay triangle. </p> + +<pre> + realT dist, bestdist= REALmax; + vertexT *bestvertex= NULL, *vertex, **vertexp; + + /* 'facet' is the closest Delaunay triangle to 'point' */ + + FOREACHvertex_( facet->vertices ) { + dist= qh_pointdist( point, vertex->point, DIM ); + if (dist < bestdist) { + bestdist= dist; + bestvertex= vertex; + } + } + /* 'bestvertex' represents the Voronoi region closest to 'point'. The corresponding + input site is 'bestvertex->point' */ +</pre> + +</blockquote><h4><a href="#TOC">»</a><a name="vertices">How</a> do I list the +vertices?</h4><blockquote> + +<p>To list the vertices (i.e., extreme points) of the convex hull +use </p> + +<blockquote> + <pre> + vertexT *vertex; + + FORALLvertices { + ... + // vertex->point is the coordinates of the vertex + // qh_pointid(vertex->point) is the point ID of the vertex + ... + } + </pre> +</blockquote> + +</blockquote><h4><a href="#TOC">»</a><a name="test">How</a> do I test code +that uses the Qhull library?</h4><blockquote> + +<p>Compare the output from your program with the output from the +Qhull program. Use option 'T1' or 'T4' to trace what Qhull is +doing. Prepare a <i>small</i> example for which you know the +output. Run the example through the Qhull program and your code. +Compare the trace outputs. If you do everything right, the two +trace outputs should be almost the same. The trace output will +also guide you to the functions that you need to review. </p> + +</blockquote><h4><a href="#TOC">»</a><a name="orient">When</a> I compute a +plane equation from a facet, I sometimes get an outward-pointing +normal and sometimes an inward-pointing normal</h4><blockquote> + +<p>Qhull orients simplicial facets, and prints oriented output +for 'i', 'Ft', and other options. The orientation depends on <i>both</i> +the vertex order and the flag facet->toporient.</p> + +<p>Qhull does not orient + non-simplicial facets. Instead it orients the facet's ridges. These are + printed with the 'Qt' and 'Ft' option. The facet's hyperplane is oriented. </p> + +</blockquote> +<hr><!-- Navigation links --> + +<p><a><b>Up:</b> </a><a + href="http://www.qhull.org">Home page for Qhull</a><br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents <br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#TOC">FAQ: Table of Contents</a><br><!-- GC common information --> + +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><IMG align=middle + height=40 src="qh--geom.gif" width=40 ></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: +Sept. 25, 1995 --- <!-- hhmts start -->Last modified: see top +<!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/qh-get.htm b/xs/src/qhull/html/qh-get.htm new file mode 100644 index 000000000..c39ed2256 --- /dev/null +++ b/xs/src/qhull/html/qh-get.htm @@ -0,0 +1,106 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<title>Qhull Downloads</title> +</head> + +<body> +<!-- Navigation links --> +<p><b>Up:</b> <a href="http://www.qhull.org"><i>Qhull Home Page</i></a><br> +</p> + +<hr> + +<h1><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/cone.html"><img +src="../html/qh--cone.gif" alt="[CONE]" align="middle" +width="100" height="100"></a> Qhull Downloads</h1> + +<ul> + <li><a href="http://www.qhull.org">Qhull Home Page</a> <p>Qhull + computes the convex hull, Delaunay triangulation, Voronoi diagram, halfspace + intersection about a point, furthest-site Delaunay + triangulation, and furthest-site Voronoi diagram. It + runs in 2-d, 3-d, 4-d, and higher dimensions. It + implements the Quickhull algorithm for computing the + convex hull. Qhull handles roundoff errors from floating + point arithmetic. It can approximate a convex hull. </p> + + <p>Visit <a href="http://www.qhull.org/news">Qhull News</a> + for news, bug reports, change history, and users. + If you use Qhull 2003.1 or 2009.1, please upgrade to 2015.2 or apply + <a href="http://www.qhull.org/download/poly.c-qh_gethash.patch">poly.c-qh_gethash.patch</a>.</p> + </li> + <li><a + href="http://www.qhull.org/download/qhull-2015.2.zip">Download: + Qhull 2015.2 for Windows 10, 8, 7, XP, and NT</a> (2.6 MB, + <a href="http://www.qhull.org/README.txt">readme</a>, + <a href="http://www.qhull.org/download/qhull-2015.2.md5sum">md5sum</a>, + <a href="http://www.qhull.org/download/qhull-2015.2.zip.md5sum">contents</a>) + <p>Type: console programs for Windows (32- or 64-bit)</p> + <p>Includes 32-bit executables, documentation, and sources files. It runs in a + command window. Qhull may be compiled for 64-bits.</p> + </li> + <li><a href="http://github.com/qhull/qhull/wiki">GitHub Qhull</a> (git@github.com:qhull/qhull.git) + <p>Type: git repository for Qhull. See recent <a href="https://github.com/qhull/qhull/blob/master/src/Changes.txt">Changes.txt</a></p> + <p>Includes documentation, source files, C++ interface, and test programs. It builds with gcc, mingw, + CMake, DevStudio, and Qt Creator. + </p> + </li> + <li><a href="http://www.qhull.org/download/qhull-2015-src-7.2.0.tgz">Download: Qhull 2015.2 for Unix</a> (1.0 MB, + <a href="http://www.qhull.org/README.txt">readme</a>, + <a href="http://www.qhull.org/download/qhull-2015.2.md5sum">md5sum</a>, + <a href="http://www.qhull.org/download/qhull-2015-src-7.2.0.tgz.md5sum">contents</a>) + <p>Type: C/C++ source code for 32-bit and 64-bit architectures. See <a href="http://www.qhull.org/src/Changes.txt">Changes.txt</a></p> + <p>Includes documentation, source files, Makefiles, CMakeLists.txt, DevStudio projects, and Qt projects. + Includes preliminary C++ support.</p> + <p>Download and search sites for pre-built packages include + <ul> + <li><a href="https://launchpad.net/ubuntu/+source/qhull">https://launchpad.net/ubuntu/+source/qhull</a> + <li><a href="http://software.opensuse.org/download.html?project=openSUSE%3AFactory&package=qhull">http://software.opensuse.org/download.html?project=openSUSE%3AFactory&package=qhull</a> + <li><a href="https://www.archlinux.org/packages/extra/i686/qhull/">https://www.archlinux.org/packages/extra/i686/qhull/</a> + <li><a href="http://rpmfind.net/linux/rpm2html/search.php?query=qhull">http://rpmfind.net/linux/rpm2html/search.php?query=qhull</a> + <li><a href="http://rpm.pbone.net/index.php3/stat/3/srodzaj/1/search/qhull">http://rpm.pbone.net/index.php3/stat/3/srodzaj/1/search/qhull</a> + </ul></p> + </li> + + <li><a + href="http://dl.acm.org/author_page.cfm?id=81100129162">Download: + Article about Qhull</a> (307K) + <p>Type: PDF on ACM Digital Library (from this page only)</p> + <p>Barber, C.B., Dobkin, D.P., and Huhdanpaa, H.T., + "The Quickhull algorithm for convex hulls," <i>ACM + Transactions on Mathematical Software</i>, 22(4):469-483, Dec 1996 [<a + href="http://portal.acm.org/citation.cfm?doid=235815.235821">abstract</a>].</p> + </li> + + <li><a + href="http://www.qhull.org/download/qhull-1.0.tar.gz">Download: + Qhull version 1.0</a> (92K) <p>Type: C source code for + 32-bit architectures </p> + <p>Version 1.0 is a fifth the size of version 2.4. It + computes convex hulls and Delaunay triangulations. If a + precision error occurs, it stops with an error message. + It reports an initialization error for inputs made with + 0/1 coordinates. </p> + <p>Version 1.0 compiles on a PC with Borland C++ 4.02 for + Win32 and DOS Power Pack. The options for rbox are + "bcc32 -WX -w- -O2-e -erbox -lc rbox.c". The + options for qhull are the same. [D. Zwick] </p> + </li> +</ul> +<!-- Navigation links --> +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org"><i>Qhull Home Page</i></a><br> +<!-- GC common information --></p> + +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="../html/qh--geom.gif" alt="[HOME]" +align="middle"></a> <i>The Geometry Center Home Page</i> </p> + +<p>Comments to: <a href="mailto:qhull@qhull.org">qhull@qhull.org</a><br> +</body> +</html> diff --git a/xs/src/qhull/html/qh-impre.htm b/xs/src/qhull/html/qh-impre.htm new file mode 100644 index 000000000..cfbe0acb8 --- /dev/null +++ b/xs/src/qhull/html/qh-impre.htm @@ -0,0 +1,826 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<title>Imprecision in Qhull</title> +</head> + +<body> +<!-- Navigation links --> +<p><a name="TOP"><b>Up:</b></a> <a href="http://www.qhull.org">Home +page</a> for Qhull <br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of +Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To: </b><a href="#TOC">Qhull imprecision</a>: Table of Contents +(please wait while loading) + +<hr> +<!-- Main text of document --> +<h1><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/4dcube.html"><img +src="qh--4d.gif" alt="[4-d cube]" align="middle" width="100" +height="100"></a> Imprecision in Qhull</h1> + +<p>This section of the Qhull manual discusses the problems caused +by coplanar points and why Qhull uses options '<a +href="qh-optc.htm#C0">C-0</a>' or '<a href="qh-optq.htm#Qx">Qx</a>' +by default. If you ignore precision issues with option '<a +href="qh-optq.htm#Q0">Q0</a>', the output from Qhull can be +arbitrarily bad. Qhull avoids precision problems if you merge facets (the default) or joggle +the input ('<a +href="qh-optq.htm#QJn">QJ</a>'). </p> + +<p>Use option '<a href="qh-optt.htm#Tv">Tv</a>' to verify the +output from Qhull. It verifies that adjacent facets are clearly +convex. It verifies that all points are on or below all facets. </p> + +<p>Qhull automatically tests for convexity if it detects +precision errors while constructing the hull. </p> + +<p><b>Copyright © 1995-2015 C.B. Barber</b></p> + +<hr> + +<h2><a href="#TOP">»</a><a name="TOC">Qhull +imprecision: Table of Contents </a></h2> + +<ul> + <li><a href="#prec">Precision problems</a></li> + <li><a href="#joggle">Merged facets or joggled input</a></li> + <li><a href="#delaunay">Delaunay triangulations</a></li> + <li><a href="#halfspace">Halfspace intersection/a></li> + <li><a href="#imprecise">Merged facets</a></li> + <li><a href="#how">How Qhull merges facets</a></li> + <li><a href="#limit">Limitations of merged facets</a></li> + <li><a href="#injoggle">Joggled input</a></li> + <li><a href="#exact">Exact arithmetic</a></li> + <li><a href="#approximate">Approximating a convex hull</a></li> +</ul> + +<hr> + +<h2><a href="#TOC">»</a><a name="prec">Precision problems</a></h2> + +<p>Since Qhull uses floating point arithmetic, roundoff error +occurs with each calculation. This causes problems for +geometric algorithms. Other floating point codes for convex +hulls, Delaunay triangulations, and Voronoi diagrams also suffer +from these problems. Qhull handles most of them.</p> + +<p>There are several kinds of precision errors:</p> + +<ul> + <li>Representation error occurs when there are not enough + digits to represent a number, e.g., 1/3.</li> + <li>Measurement error occurs when the input coordinates are + from measurements. </li> + <li>Roundoff error occurs when a calculation is rounded to a + fixed number of digits, e.g., a floating point + calculation.</li> + <li>Approximation error occurs when the user wants an + approximate result because the exact result contains too + much detail.</li> +</ul> + +<p>Under imprecision, calculations may return erroneous results. +For example, roundoff error can turn a small, positive number +into a small, negative number. See Milenkovic [<a +href="index.htm#mile93">'93</a>] for a discussion of <em>strict +robust geometry</em>. Qhull does not meet Milenkovic's criterion +for accuracy. Qhull's error bound is empirical instead of +theoretical.</p> + +<p>Qhull 1.0 checked for precision errors but did not handle +them. The output could contain concave facets, facets with +inverted orientation ("flipped" facets), more than two +facets adjacent to a ridge, and two facets with exactly the same +set of vertices.</p> + +<p>Qhull 2.4 and later automatically handles errors due to +machine round-off. Option '<a href="qh-optc.htm#C0">C-0</a>' or '<a +href="qh-optq.htm#Qx">Qx</a>' is set by default. In 5-d and +higher, the output is clearly convex but an input point could be +outside of the hull. This may be corrected by using option '<a +href="qh-optc.htm#C0">C-0</a>', but then the output may contain +wide facets.</p> + +<p>Qhull 2.5 and later provides option '<a href="qh-optq.htm#QJn">QJ</a>' +to joggled input. Each input coordinate is modified by a +small, random quantity. If a precision error occurs, a larger +modification is tried. When no precision errors occur, Qhull is +done. </p> + +<p>Qhull 3.1 and later provides option '<a href="qh-optq.htm#Qt">Qt</a>' +for triangulated output. This removes the need for +joggled input ('<a href="qh-optq.htm#QJn">QJ</a>'). +Non-simplicial facets are triangulated. +The facets may have zero area. +Triangulated output is particularly useful for Delaunay triangulations.</p> + +<p>By handling round-off errors, Qhull can provide a variety of +output formats. For example, it can return the halfspace that +defines each facet ('<a href="qh-opto.htm#n">n</a>'). The +halfspaces include roundoff error. If the halfspaces were exact, +their intersection would return the original extreme points. With +imprecise halfspaces and exact arithmetic, nearly incident points +may be returned for an original extreme point. By handling +roundoff error, Qhull returns one intersection point for each of +the original extreme points. Qhull may split or merge an extreme +point, but this appears to be unlikely.</p> + +<p>The following pipe implements the identity function for +extreme points (with roundoff): +<blockquote> + qconvex <a href="qh-optf.htm#FV">FV</a> <a + href="qh-opto.htm#n">n</a> | qhalf <a href="qh-optf.htm#Fp">Fp</a> +</blockquote> + +<p>Bernd Gartner published his +<a href=http://www.inf.ethz.ch/personal/gaertner/miniball.html>Miniball</a> +algorithm ["Fast and robust smallest enclosing balls", <i>Algorithms - ESA '99</i>, LNCS 1643]. +It uses floating point arithmetic and a carefully designed primitive operation. +It is practical to 20-D or higher, and identifies at least two points on the +convex hull of the input set. Like Qhull, it is an incremental algorithm that +processes points furthest from the intermediate result and ignores +points that are close to the intermediate result. + +<h2><a href="#TOC">»</a><a name="joggle">Merged facets or joggled input</a></h2> + +<p>This section discusses the choice between merged facets and joggled input. +By default, Qhull uses merged facets to handle +precision problems. With option '<a href="qh-optq.htm#QJn">QJ</a>', +the input is joggled. See <a href="qh-eg.htm#joggle">examples</a> +of joggled input and triangulated output. +<ul> +<li>Use merged facets (the default) +when you want non-simplicial output (e.g., the faces of a cube). +<li>Use merged facets and triangulated output ('<a href="qh-optq.htm#Qt">Qt</a>') when +you want simplicial output and coplanar facets (e.g., triangles for a Delaunay triangulation). +<li>Use joggled input ('<a href="qh-optq.htm#QJn">QJ</a>') when you need clearly-convex, +simplicial output. +</ul> + +<p>The choice between merged facets and joggled input depends on +the application. Both run about the same speed. Joggled input may +be faster if the initial joggle is sufficiently large to avoid +precision errors. + +<p>Most applications should used merged facets +with triangulated output. </p> + +<p>Use merged facets (the +default, '<a href="qh-optc.htm#C0">C-0</a>') +or triangulated output ('<a href="qh-optq.htm#Qt">Qt</a>') if </p> + +<ul> + <li>Your application supports non-simplicial facets, or + it allows degenerate, simplicial facets (option '<a href="qh-optq.htm#Qt">Qt</a>'). </li> + <li>You do not want the input modified. </li> + <li>You want to set additional options for approximating the + hull. </li> + <li>You use single precision arithmetic (<a href="../src/libqhull/user.h#realT">realT</a>). + </li> +</ul> + +<p>Use joggled input ('<a href="qh-optq.htm#QJn">QJ</a>') if </p> + +<ul> + <li>Your application needs clearly convex, simplicial output</li> + <li>Your application supports perturbed input points and narrow triangles.</li> + <li>Seven significant digits is sufficient accuracy.</li> +</ul> + +<p>You may use both techniques or combine joggle with +post-merging ('<a href="qh-optc.htm#Cn2">Cn</a>'). </p> + +<p>Other researchers have used techniques similar to joggled +input. Sullivan and Beichel [ref?] randomly perturb the input +before computing the Delaunay triangulation. Corkum and Wyllie +[news://comp.graphics, 1990] randomly rotate a polytope before +testing point inclusion. Edelsbrunner and Mucke [Symp. Comp. +Geo., 1988] and Yap [J. Comp. Sys. Sci., 1990] symbolically +perturb the input to remove singularities. </p> + +<p>Merged facets ('<a href="qh-optc.htm#C0">C-0</a>') handles +precision problems directly. If a precision problem occurs, Qhull +merges one of the offending facets into one of its neighbors. +Since all precision problems in Qhull are associated with one or +more facets, Qhull will either fix the problem or attempt to merge the +last remaining facets. </p> + +<h2><a href="#TOC">»</a><a name="delaunay">Delaunay +triangulations </a></h2> + +<p>Programs that use Delaunay triangulations traditionally assume +a triangulated input. By default, <a href=qdelaun.htm>qdelaunay</a> +merges regions with cocircular or cospherical input sites. +If you want a simplicial triangulation +use triangulated output ('<a href="qh-optq.htm#Qt">Qt</a>') or joggled +input ('<a href="qh-optq.htm#QJn">QJ</a>'). + +<p>For Delaunay triangulations, triangulated +output should produce good results. All points are within roundoff error of +a paraboloid. If two points are nearly incident, one will be a +coplanar point. So all points are clearly separated and convex. +If qhull reports deleted vertices, the triangulation +may contain serious precision faults. Deleted vertices are reported +in the summary ('<a href="qh-opto.htm#s">s</a>', '<a href="qh-optf.htm#Fs">Fs</a>'</p> + +<p>You should use option '<a href="qh-optq.htm#Qbb">Qbb</a>' with Delaunay +triangulations. It scales the last coordinate and may reduce +roundoff error. It is automatically set for <a href=qdelaun.htm>qdelaunay</a>, +<a href=qvoronoi.htm>qvoronoi</a>, and option '<a +href="qh-optq.htm#QJn">QJ</a>'.</p> + +<p>Edelsbrunner, H, <i>Geometry and Topology for Mesh Generation</i>, Cambridge University Press, 2001. +Good mathematical treatise on Delaunay triangulation and mesh generation for 2-d +and 3-d surfaces. The chapter on surface simplification is +particularly interesting. It is similar to facet merging in Qhull. + +<p>Veron and Leon published an algorithm for shape preserving polyhedral +simplification with bounded error [<i>Computers and Graphics</i>, 22.5:565-585, 1998]. +It remove nodes using front propagation and multiple remeshing. + +<h2><a href="#TOC">»</a><a name="halfspace">Halfspace intersection</a></h2> + +<p> +The identity pipe for Qhull reveals some precision questions for +halfspace intersections. The identity pipe creates the convex hull of +a set of points and intersects the facets' hyperplanes. It should return the input +points, but narrow distributions may drop points while offset distributions may add +points. It may be better to normalize the input set about the origin. +For example, compare the first results with the later two results: [T. Abraham] +<blockquote> + rbox 100 s t | tee r | qconvex FV n | qhalf Fp | cat - r | /bin/sort -n | tail +<br> + rbox 100 L1e5 t | tee r | qconvex FV n | qhalf Fp | cat - r | /bin/sort -n | tail +<br> + rbox 100 s O10 t | tee r | qconvex FV n | qhalf Fp | cat - r | /bin/sort -n | tail +</blockquote> + + +<h2><a href="#TOC">»</a><a name="imprecise">Merged facets </a></h2> + +<p>Qhull detects precision +problems when computing distances. A precision problem occurs if +the distance computation is less than the maximum roundoff error. +Qhull treats the result of a hyperplane computation as if it +were exact.</p> + +<p>Qhull handles precision problems by merging non-convex facets. +The result of merging two facets is a thick facet defined by an <i>inner +plane</i> and an <i>outer plane</i>. The inner and outer planes +are offsets from the facet's hyperplane. The inner plane is +clearly below the facet's vertices. At the end of Qhull, the +outer planes are clearly above all input points. Any exact convex +hull must lie between the inner and outer planes.</p> + +<p>Qhull tests for convexity by computing a point for each facet. +This point is called the facet's <i>centrum</i>. It is the +arithmetic center of the facet's vertices projected to the +facet's hyperplane. For simplicial facets with <em>d</em> +vertices, the centrum is equivalent to the centroid or center of +gravity. </p> + +<p>Two neighboring facets are convex if each centrum is clearly +below the other hyperplane. The '<a href="qh-optc.htm#Cn2">Cn</a>' +or '<a href="qh-optc.htm#Cn">C-n</a>' options sets the centrum's +radius to <i>n </i>. A centrum is clearly below a hyperplane if +the computed distance from the centrum to the hyperplane is +greater than the centrum's radius plus two maximum roundoff +errors. Two are required because the centrum can be the maximum +roundoff error above its hyperplane and the distance computation +can be high by the maximum roundoff error.</p> + +<p>With the '<a href="qh-optc.htm#Cn">C-n</a>' or '<a +href="qh-optc.htm#An">A-n </a>' options, Qhull merges non-convex +facets while constructing the hull. The remaining facets are +clearly convex. With the '<a href="qh-optq.htm#Qx">Qx </a>' +option, Qhull merges coplanar facets after constructing the hull. +While constructing the hull, it merges coplanar horizon facets, +flipped facets, concave facets and duplicated ridges. With '<a +href="qh-optq.htm#Qx">Qx</a>', coplanar points may be missed, but +it appears to be unlikely.</p> + +<p>If the user sets the '<a href="qh-optc.htm#An2">An</a>' or '<a +href="qh-optc.htm#An">A-n</a>' option, then all neighboring +facets are clearly convex and the maximum (exact) cosine of an +angle is <i>n</i>.</p> + +<p>If '<a href="qh-optc.htm#C0">C-0</a>' or '<a +href="qh-optq.htm#Qx">Qx</a>' is used without other precision +options (default), Qhull tests vertices instead of centrums for +adjacent simplices. In 3-d, if simplex <i>abc</i> is adjacent to +simplex <i>bcd</i>, Qhull tests that vertex <i>a</i> is clearly +below simplex <i>bcd </i>, and vertex <i>d</i> is clearly below +simplex <i>abc</i>. When building the hull, Qhull tests vertices +if the horizon is simplicial and no merges occur. </p> + +<h2><a href="#TOC">»</a><a name="how">How Qhull merges facets</a></h2> + +<p>If two facets are not clearly convex, then Qhull removes one +or the other facet by merging the facet into a neighbor. It +selects the merge which minimizes the distance from the +neighboring hyperplane to the facet's vertices. Qhull also +performs merges when a facet has fewer than <i>d</i> neighbors (called a +degenerate facet), when a facet's vertices are included in a +neighboring facet's vertices (called a redundant facet), when a +facet's orientation is flipped, or when a ridge occurs between +more than two facets.</p> + +<p>Qhull performs merges in a series of passes sorted by merge +angle. Each pass merges those facets which haven't already been +merged in that pass. After a pass, Qhull checks for redundant +vertices. For example, if a vertex has only two neighbors in 3-d, +the vertex is redundant and Qhull merges it into an adjacent +vertex.</p> + +<p>Merging two simplicial facets creates a non-simplicial facet +of <em>d+1</em> vertices. Additional merges create larger facets. +When merging facet A into facet B, Qhull retains facet B's +hyperplane. It merges the vertices, neighbors, and ridges of both +facets. It recomputes the centrum if a wide merge has not +occurred (qh_WIDEcoplanar) and the number of extra vertices is +smaller than a constant (qh_MAXnewcentrum).</p> + + +<h2><a href="#TOC">»</a><a name="limit">Limitations of merged +facets</a></h2> + +<ul> +<li><b>Uneven dimensions</b> -- +If one coordinate has a larger absolute value than other +coordinates, it may dominate the effect of roundoff errors on +distance computations. You may use option '<a +href="qh-optq.htm#QbB">QbB</a>' to scale points to the unit cube. +For Delaunay triangulations and Voronoi diagrams, <a href=qdelaun.htm>qdelaunay</a> +and <a href=qvoronoi.htm>qvoronoi</a> always set +option '<a href="qh-optq.htm#Qbb">Qbb</a>'. It scales the last +coordinate to [0,m] where <i>m</i> is the maximum width of the +other coordinates. Option '<a href="qh-optq.htm#Qbb">Qbb</a>' is +needed for Delaunay triangulations of integer coordinates +and nearly cocircular points. + +<p>For example, compare +<pre> + rbox 1000 W0 t | qconvex Qb2:-1e-14B2:1e-14 +</pre> +with +<pre> + rbox 1000 W0 t | qconvex +</pre> +The distributions are the same but the first is compressed to a 2e-14 slab. +<p> +<li><b>Post-merging of coplanar facets</b> -- In 5-d and higher, option '<a href="qh-optq.htm#Qx">Qx</a>' +(default) delays merging of coplanar facets until post-merging. +This may allow "dents" to occur in the intermediate +convex hulls. A point may be poorly partitioned and force a poor +approximation. See option '<a href="qh-optq.htm#Qx">Qx</a>' for +further discussion.</p> + +<p>This is difficult to produce in 5-d and higher. Option '<a href="qh-optq.htm#Q6">Q6</a>' turns off merging of concave +facets. This is similar to 'Qx'. It may lead to serious precision errors, +for example, +<pre> + rbox 10000 W1e-13 | qhull Q6 Tv +</pre> + +<p> +<li><b>Maximum facet width</b> -- +Qhull reports the maximum outer plane and inner planes (if +more than roundoff error apart). There is no upper bound +for either figure. This is an area for further research. Qhull +does a good job of post-merging in all dimensions. Qhull does a +good job of pre-merging in 2-d, 3-d, and 4-d. With the '<a +href="qh-optq.htm#Qx">Qx</a>' option, it does a good job in +higher dimensions. In 5-d and higher, Qhull does poorly at +detecting redundant vertices. </p> + +<p>In the summary ('<a href="qh-opto.htm#s">s</a>'), look at the +ratio between the maximum facet width and the maximum width of a +single merge, e.g., "(3.4x)". Qhull usually reports a +ratio of four or lower in 3-d and six or lower in 4-d. If it +reports a ratio greater than 10, this may indicate an +implementation error. Narrow distributions (see following) may +produce wide facets. + +<p>For example, if special processing for narrow distributions is +turned off ('<a href="qh-optq.htm#Q10">Q10</a>'), qhull may produce +a wide facet:</p> +<pre> + rbox 1000 L100000 s G1e-16 t1002074964 | qhull Tv Q10 +</pre> + +<p> +<li><b>Narrow distribution</b> -- In 3-d, a narrow distribution may result in a poor +approximation. For example, if you do not use qdelaunay nor option +'<a href="qh-optq.htm#Qbb">Qbb</a>', the furthest-site +Delaunay triangulation of nearly cocircular points may produce a poor +approximation: +<pre> + rbox s 5000 W1e-13 D2 t1002151341 | qhull d Qt + rbox 1000 s W1e-13 t1002231672 | qhull d Tv +</pre> + +<p>During +construction of the hull, a point may be above two +facets with opposite orientations that span the input +set. Even though the point may be nearly coplanar with both +facets, and can be distant from the precise convex +hull of the input sites. Additional facets leave the point distant from +a facet. To fix this problem, add option '<a href="qh-optq.htm#Qbb">Qbb</a>' +(it scales the last coordinate). Option '<a href="qh-optq.htm#Qbb">Qbb</a>' +is automatically set for <a href=qdelaun.htm>qdelaunay</a> and <a href=qvoronoi.htm>qvoronoi</a>. + +<p>Qhull generates a warning if the initial simplex is narrow. +For narrow distributions, Qhull changes how it processes coplanar +points -- it does not make a point coplanar until the hull is +finished. +Use option '<a href="qh-optq.htm#Q10">Q10</a>' to try Qhull without +special processing for narrow distributions. +For example, special processing is needed for: +<pre> + rbox 1000 L100000 s G1e-16 t1002074964 | qhull Tv Q10 +</pre> + +<p>You may turn off the warning message by reducing +qh_WARNnarrow in <tt>user.h</tt> or by setting option +'<a href="qh-optp.htm#Pp">Pp</a>'. </p> + +<p>Similar problems occur for distributions with a large flat facet surrounded +with many small facet at a sharp angle to the large facet. +Qhull 3.1 fixes most of these problems, but a poor approximation can occur. +A point may be left outside of the convex hull ('<a href="qh-optt.htm#Tv">Tv</a>'). +Examples include +the furthest-site Delaunay triangulation of nearly cocircular points plus the origin, and the convex hull of a cone of nearly cocircular points. The width of the band is 10^-13. +<pre> + rbox s 1000 W1e-13 P0 D2 t996799242 | qhull d Tv + rbox 1000 s Z1 G1e-13 t1002152123 | qhull Tv + rbox 1000 s Z1 G1e-13 t1002231668 | qhull Tv +</pre> + +<p> +<li><b>Quadratic running time</b> -- If the output contains large, non-simplicial +facets, the running time for Qhull may be quadratic in the size of the triangulated +output. For example, <tt>rbox 1000 s W1e-13 c G2 | qhull d</tt> is 4 times +faster for 500 points. The convex hull contains two large nearly spherical facets and +many nearly coplanar facets. Each new point retriangulates the spherical facet and repartitions the remaining points into all of the nearly coplanar facets. +In this case, quadratic running time is avoided if you use qdelaunay, +add option '<a href="qh-optq.htm#Qbb">Qbb</a>', +or add the origin ('P0') to the input. +<p> +<li><b>Nearly coincident points within 1e-13</b> -- +Multiple, nearly coincident points within a 1e-13 ball of points in the unit cube +may lead to wide facets or quadratic running time. +For example, the convex hull a 1000 coincident, cospherical points in 4-D, +or the 3-D Delaunay triangulation of nearly coincident points, may lead to very +wide facets (e.g., 2267021951.3x). + +<p>For Delaunay triangulations, the problem typically occurs for extreme points of the input +set (i.e., on the edge between the upper and lower convex hull). After multiple facet merges, four +facets may share the same, duplicate ridge and must be merged. +Some of these facets may be long and narrow, leading to a very wide merged facet. +If so, error QH6271 is reported. It may be overriden with option '<a href="qh-optq.htm#Q12">Q12</a>'. + +<p>Duplicate ridges occur when the horizon facets for a new point is "pinched". +In a duplicate ridge, a subridge (e.g., a line segment in 3-d) is shared by two horizon facets. +At least two of its vertices are nearly coincident. It is easy to generate coincident points with +option 'Cn,r,m' of rbox. It generates n points within an r ball for each of m input sites. For example, +every point of the following distributions has a nearly coincident point within a 1e-13 ball. +Substantially smaller or larger balls do not lead to pinched horizons. +<pre> + rbox 1000 C1,1e-13 D4 s t | qhull + rbox 75 C1,1e-13 t | qhull d +</pre> +For Delaunay triangulations, a bounding box may alleviate this error (e.g., <tt>rbox 500 C1,1E-13 t c G1 | qhull d</tt>). +A later release of qhull will avoid pinched horizons by merging duplicate subridges. A subridge is +merged by merging adjacent vertices. +<p> +<li><b>Facet with zero-area</b> -- +It is possible for a zero-area facet to be convex with its +neighbors. This can occur if the hyperplanes of neighboring +facets are above the facet's centrum, and the facet's hyperplane +is above the neighboring centrums. Qhull computes the facet's +hyperplane so that it passes through the facet's vertices. The +vertices can be collinear. </p> + +<p> +<li><b>No more facets</b> -- Qhull reports an error if there are <em>d+1</em> facets left +and two of the facets are not clearly convex. This typically +occurs when the convexity constraints are too strong or the input +points are degenerate. The former is more likely in 5-d and +higher -- especially with option '<a href="qh-optc.htm#Cn">C-n</a>'.</p> + +<p> +<li><b>Deleted cone</b> -- Lots of merging can end up deleting all +of the new facets for a point. This is a rare event that has +only been seen while debugging the code. + +<p> +<li><b>Triangulated output leads to precision problems</b> -- With sufficient +merging, the ridges of a non-simplicial facet may have serious topological +and geometric problems. A ridge may be between more than two +neighboring facets. If so, their triangulation ('<a href="qh-optq.htm#Qt">Qt</a>') +will fail since two facets have the same vertex set. Furthermore, +a triangulated facet may have flipped orientation compared to its +neighbors.</li> + +<p>The triangulation process detects degenerate facets with +only two neighbors. These are marked degenerate. They have +zero area. + +<p> +<li><b>Coplanar points</b> -- +Option '<a href="qh-optq.htm#Qc">Qc</a>' is determined by +qh_check_maxout() after constructing the hull. Qhull needs to +retain all possible coplanar points in the facets' coplanar sets. +This depends on qh_RATIOnearInside in <tt>user.h.</tt> +Furthermore, the cutoff for a coplanar point is arbitrarily set +at the minimum vertex. If coplanar points are important to your +application, remove the interior points by hand (set '<a +href="qh-optq.htm#Qc">Qc</a> <a href="qh-optq.htm#Qi">Qi</a>') or +make qh_RATIOnearInside sufficiently large.</p> + +<p> +<li><b>Maximum roundoff error</b> -- Qhull computes the maximum roundoff error from the maximum +coordinates of the point set. Usually the maximum roundoff error +is a reasonable choice for all distance computations. The maximum +roundoff error could be computed separately for each point or for +each distance computation. This is expensive and it conflicts +with option '<a href="qh-optc.htm#Cn">C-n</a>'. + +<p> +<li><b>All flipped or upper Delaunay</b> -- When a lot of merging occurs for +Delaunay triangulations, a new point may lead to no good facets. For example, +try a strong convexity constraint: +<pre> + rbox 1000 s t993602376 | qdelaunay C-1e-3 +</pre> + +</ul> + +<h2><a href="#TOC">»</a><a name="injoggle">Joggled input</a></h2> + +<p>Joggled input is a simple work-around for precision problems +in computational geometry ["joggle: to shake or jar +slightly," Amer. Heritage Dictionary]. Other names are +<i>jostled input</i> or <i>random perturbation</i>. +Qhull joggles the +input by modifying each coordinate by a small random quantity. If +a precision problem occurs, Qhull joggles the input with a larger +quantity and the algorithm is restarted. This process continues +until no precision problems occur. Unless all inputs incur +precision problems, Qhull will terminate. Qhull adjusts the inner +and outer planes to account for the joggled input. </p> + +<p>Neither joggle nor merged facets has an upper bound for the width of the output +facets, but both methods work well in practice. Joggled input is +easier to justify. Precision errors occur when the points are +nearly singular. For example, four points may be coplanar or +three points may be collinear. Consider a line and an incident +point. A precision error occurs if the point is within some +epsilon of the line. Now joggle the point away from the line by a +small, uniformly distributed, random quantity. If the point is +changed by more than epsilon, the precision error is avoided. The +probability of this event depends on the maximum joggle. Once the +maximum joggle is larger than epsilon, doubling the maximum +joggle will halve the probability of a precision error. </p> + +<p>With actual data, an analysis would need to account for each +point changing independently and other computations. It is easier +to determine the probabilities empirically ('<a href="qh-optt.htm#TRn">TRn</a>') . For example, consider +computing the convex hull of the unit cube centered on the +origin. The arithmetic has 16 significant decimal digits. </p> + +<blockquote> + <p><b>Convex hull of unit cube</b> </p> + <table border="1"> + <tr> + <th align="left">joggle</th> + <th align="right">error prob. </th> + </tr> + <tr> + <td align="right">1.0e-15</td> + <td align="center">0.983 </td> + </tr> + <tr> + <td align="right">2.0e-15</td> + <td align="center">0.830 </td> + </tr> + <tr> + <td align="right">4.0e-15</td> + <td align="center">0.561 </td> + </tr> + <tr> + <td align="right">8.0e-15</td> + <td align="center">0.325 </td> + </tr> + <tr> + <td align="right">1.6e-14</td> + <td align="center">0.185 </td> + </tr> + <tr> + <td align="right">3.2e-14</td> + <td align="center">0.099 </td> + </tr> + <tr> + <td align="right">6.4e-14</td> + <td align="center">0.051 </td> + </tr> + <tr> + <td align="right">1.3e-13</td> + <td align="center">0.025 </td> + </tr> + <tr> + <td align="right">2.6e-13</td> + <td align="center">0.010 </td> + </tr> + <tr> + <td align="right">5.1e-13</td> + <td align="center">0.004 </td> + </tr> + <tr> + <td align="right">1.0e-12</td> + <td align="center">0.002 </td> + </tr> + <tr> + <td align="right">2.0e-12</td> + <td align="center">0.001 </td> + </tr> + </table> +</blockquote> + +<p>A larger joggle is needed for multiple points. Since the +number of potential singularities increases, the probability of +one or more precision errors increases. Here is an example. </p> + +<blockquote> + <p><b>Convex hull of 1000 points on unit cube</b> </p> + <table border="1"> + <tr> + <th align="left">joggle</th> + <th align="right">error prob. </th> + </tr> + <tr> + <td align="right">1.0e-12</td> + <td align="center">0.870 </td> + </tr> + <tr> + <td align="right">2.0e-12</td> + <td align="center">0.700 </td> + </tr> + <tr> + <td align="right">4.0e-12</td> + <td align="center">0.450 </td> + </tr> + <tr> + <td align="right">8.0e-12</td> + <td align="center">0.250 </td> + </tr> + <tr> + <td align="right">1.6e-11</td> + <td align="center">0.110 </td> + </tr> + <tr> + <td align="right">3.2e-11</td> + <td align="center">0.065 </td> + </tr> + <tr> + <td align="right">6.4e-11</td> + <td align="center">0.030 </td> + </tr> + <tr> + <td align="right">1.3e-10</td> + <td align="center">0.010 </td> + </tr> + <tr> + <td align="right">2.6e-10</td> + <td align="center">0.008 </td> + </tr> + <tr> + <td align="right">5.1e-09</td> + <td align="center">0.003 </td> + </tr> + </table> +</blockquote> + +<p>Other distributions behave similarly. No distribution should +behave significantly worse. In Euclidean space, the probability +measure of all singularities is zero. With floating point +numbers, the probability of a singularity is non-zero. With +sufficient digits, the probability of a singularity is extremely +small for random data. For a sufficiently large joggle, all data +is nearly random data. </p> + +<p>Qhull uses an initial joggle of 30,000 times the maximum +roundoff error for a distance computation. This avoids most +potential singularities. If a failure occurs, Qhull retries at +the initial joggle (in case bad luck occurred). If it occurs +again, Qhull increases the joggle by ten-fold and tries again. +This process repeats until the joggle is a hundredth of the width +of the input points. Qhull reports an error after 100 attempts. +This should never happen with double-precision arithmetic. Once +the probability of success is non-zero, the probability of +success increases about ten-fold at each iteration. The +probability of repeated failures becomes extremely small. </p> + +<p>Merged facets produces a significantly better approximation. +Empirically, the maximum separation between inner and outer +facets is about 30 times the maximum roundoff error for a +distance computation. This is about 2,000 times better than +joggled input. Most applications though will not notice the +difference. </p> + +<h2><a href="#TOC">»</a><a name="exact">Exact arithmetic</a></h2> + +<p>Exact arithmetic may be used instead of floating point. +Singularities such as coplanar points can either be handled +directly or the input can be symbolically perturbed. Using exact +arithmetic is slower than using floating point arithmetic and the +output may take more space. Chaining a sequence of operations +increases the time and space required. Some operations are +difficult to do.</p> + +<p>Clarkson's <a +href="http://www.netlib.org/voronoi/hull.html">hull +program</a> and Shewchuk's <a +href="http://www.cs.cmu.edu/~quake/triangle.html">triangle +program</a> are practical implementations of exact arithmetic.</p> + +<p>Clarkson limits the input precision to about fifteen digits. +This reduces the number of nearly singular computations. When a +determinant is nearly singular, he uses exact arithmetic to +compute a precise result.</p> + +<h2><a href="#TOC">»</a><a name="approximate">Approximating a +convex hull</a></h2> + +<p>Qhull may be used for approximating a convex hull. This is +particularly valuable in 5-d and higher where hulls can be +immense. You can use '<a href="qh-optq.htm#Qx">Qx</a> <a +href="qh-optc.htm#Cn">C-n</a>' to merge facets as the hull is +being constructed. Then use '<a href="qh-optc.htm#Cn2">Cn</a>' +and/or '<a href="qh-optc.htm#An2">An</a>' to merge small facets +during post-processing. You can print the <i>n</i> largest facets +with option '<a href="qh-optp.htm#PAn">PAn</a>'. You can print +facets whose area is at least <i>n</i> with option '<a +href="qh-optp.htm#PFn">PFn</a>'. You can output the outer planes +and an interior point with '<a href="qh-optf.htm#FV">FV</a> <a +href="qh-optf.htm#Fo">Fo</a>' and then compute their intersection +with 'qhalf'. </p> + +<p>To approximate a convex hull in 6-d and higher, use +post-merging with '<a href="qh-optc.htm#Wn">Wn</a>' (e.g., qhull +W1e-1 C1e-2 TF2000). Pre-merging with a convexity constraint +(e.g., qhull Qx C-1e-2) often produces a poor approximation or +terminates with a simplex. Option '<a href="qh-optq.htm#QbB">QbB</a>' +may help to spread out the data.</p> + +<p>You will need to experiment to determine a satisfactory set of +options. Use <a href="rbox.htm">rbox</a> to generate test sets +quickly and <a href="index.htm#geomview">Geomview</a> to view +the results. You will probably want to write your own driver for +Qhull using the Qhull library. For example, you could select the +largest facet in each quadrant.</p> + +<!-- Navigation links --> +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home +page</a> for Qhull <br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of +Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#TOC">Qhull imprecision: Table of Contents</a> + +<!-- GC common information --> +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="qh--geom.gif" +align="middle" width="40" height="40"></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: Sept. 25, 1995 --- <!-- hhmts start --> Last modified: see top <!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/qh-optc.htm b/xs/src/qhull/html/qh-optc.htm new file mode 100644 index 000000000..87308180d --- /dev/null +++ b/xs/src/qhull/html/qh-optc.htm @@ -0,0 +1,292 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<title>Qhull precision options</title> +</head> + +<body> +<!-- Navigation links --> +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> + +<hr> +<!-- Main text of document --> +<h1><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/delaunay.html"><img +src="qh--dt.gif" alt="[delaunay]" align="middle" width="100" +height="100"></a> Qhull precision options</h1> + +This section lists the precision options for Qhull. These options are +indicated by an upper-case letter followed by a number. + +<p><b>Copyright © 1995-2015 C.B. Barber</b></p> + +<hr> + +<p><a href="index.htm#TOC">»</a> <a href="qh-quick.htm#programs">Programs</a> +<a name="prec">•</a> <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> + +<h2>Precision options</h2> + +<p>Most users will not need to set these options. They are best +used for <a href="qh-impre.htm#approximate">approximating</a> a +convex hull. They may also be used for testing Qhull's handling +of precision errors.</p> + +<p>By default, Qhull uses options '<a href="#C0">C-0</a>' for +2-d, 3-d and 4-d, and '<a href="qh-optq.htm#Qx">Qx</a>' for 5-d +and higher. These options use facet merging to handle precision +errors. You may also use joggled input '<a href="qh-optq.htm#QJn">QJ</a>' +to avoid precision problems. +For more information see <a +href="qh-impre.htm">Imprecision in Qhull</a>.</p> + +<dl compact> + <dt> </dt> + <dd><b>General</b></dd> + <dt><a href="#Cn2">Cn</a></dt> + <dd>centrum radius for post-merging</dd> + <dt><a href="#Cn">C-n</a></dt> + <dd>centrum radius for pre-merging</dd> + <dt><a href="#An2">An</a></dt> + <dd>cosine of maximum angle for post-merging</dd> + <dt><a href="#An">A-n</a></dt> + <dd>cosine of maximum angle for pre-merging</dd> + <dt><a href="qh-optq.htm#Qx">Qx</a></dt> + <dd>exact pre-merges (allows coplanar facets)</dd> + <dt><a href="#C0">C-0</a></dt> + <dd>handle all precision errors</dd> + <dt><a href="#Wn">Wn</a></dt> + <dd>min distance above plane for outside points</dd> +</dl> + +<dl compact> + <dt> </dt> + <dd><b>Experimental</b></dd> + <dt><a href="#Un">Un</a></dt> + <dd>max distance below plane for a new, coplanar point</dd> + <dt><a href="#En">En</a></dt> + <dd>max roundoff error for distance computation</dd> + <dt><a href="#Vn">Vn</a></dt> + <dd>min distance above plane for a visible facet</dd> + <dt><a href="#Rn">Rn</a></dt> + <dd>randomly perturb computations by a factor of [1-n,1+n]</dd> +</dl> + +<dl compact> +</dl> + +<hr> + +<h3><a href="#prec">»</a><a name="An">A-n - cosine of maximum +angle for pre-merging.</a></h3> + +<p>Pre-merging occurs while Qhull constructs the hull. It is +indicated by '<a href="#Cn">C-n</a>', 'A-n', or '<a +href="qh-optq.htm#Qx">Qx</a>'.</p> + +<p>If the angle between a pair of facet normals is greater than <i>n</i>, +Qhull merges one of the facets into a neighbor. It selects the +facet that is closest to a neighboring facet.</p> + +<p>For example, option 'A-0.99' merges facets during the +construction of the hull. If the cosine of the angle between +facets is greater than 0.99, one or the other facet is merged. +Qhull accounts for the maximum roundoff error.</p> + +<p>If 'A-n' is set without '<a href="#Cn">C-n</a>', then '<a +href="#C0">C-0</a>' is automatically set. </p> + +<p>In 5-d and higher, you should set '<a href="qh-optq.htm#Qx">Qx</a>' +along with 'A-n'. It skips merges of coplanar facets until after +the hull is constructed and before '<a href="#An2">An</a>' and '<a +href="#Cn2">Cn</a>' are checked. </p> + +<h3><a href="#prec">»</a><a name="An2">An - cosine of maximum angle for +post-merging.</a></h3> + +<p>Post merging occurs after the hull is constructed. For +example, option 'A0.99' merges a facet if the cosine of the angle +between facets is greater than 0.99. Qhull accounts for the +maximum roundoff error.</p> + +<p>If 'An' is set without '<a href="#Cn2">Cn</a>', then '<a +href="#Cn2">C0</a>' is automatically set. </p> + +<h3><a href="#prec">»</a><a name="C0">C-0 - handle all precision +errors </a></h3> + +<p>Qhull handles precision errors by merging facets. The 'C-0' +option handles all precision errors in 2-d, 3-d, and 4-d. It is +set by default. It may be used in higher dimensions, but +sometimes the facet width grows rapidly. It is usually better to +use '<a href="qh-optq.htm#Qx">Qx</a>' in 5-d and higher. +Use '<a href="qh-optq.htm#QJn">QJ</a>' to joggle the input +instead of merging facets. +Use '<a +href="qh-optq.htm#Q0">Q0</a>' to turn both options off.</p> + +<p>Qhull optimizes 'C-0' ("_zero-centrum") by testing +vertices instead of centrums for adjacent simplices. This may be +slower in higher dimensions if merges decrease the number of +processed points. The optimization may be turned off by setting a +small value such as 'C-1e-30'. See <a href="qh-impre.htm">How +Qhull handles imprecision</a>.</p> + +<h3><a href="#prec">»</a><a name="Cn">C-n - centrum radius for +pre-merging</a></h3> + +<p>Pre-merging occurs while Qhull constructs the hull. It is +indicated by 'C-n', '<a href="#An">A-n</a>', or '<a +href="qh-optq.htm#Qx">Qx</a>'.</p> + +<p>The <i>centrum</i> of a facet is a point on the facet for +testing facet convexity. It is the average of the vertices +projected to the facet's hyperplane. Two adjacent facets are +convex if each centrum is clearly below the other facet. </p> + +<p>If adjacent facets are non-convex, one of the facets is merged +into a neighboring facet. Qhull merges the facet that is closest +to a neighboring facet. </p> + +<p>For option 'C-n', <i>n</i> is the centrum radius. For example, +'C-0.001' merges facets whenever the centrum is less than 0.001 +from a neighboring hyperplane. Qhull accounts for roundoff error +when testing the centrum.</p> + +<p>In 5-d and higher, you should set '<a href="qh-optq.htm#Qx">Qx</a>' +along with 'C-n'. It skips merges of coplanar facets until after +the hull is constructed and before '<a href="#An2">An</a>' and '<a +href="#Cn2">Cn</a>' are checked. </p> + +<h3><a href="#prec">»</a><a name="Cn2">Cn - centrum radius for +post-merging</a></h3> + +<p>Post-merging occurs after Qhull constructs the hull. It is +indicated by '<a href="#Cn2">Cn</a>' or '<a href="#An2">An</a>'. </p> + +<p>For option '<a href="#Cn2">Cn</a>', <i>n</i> is the centrum +radius. For example, 'C0.001' merges facets when the centrum is +less than 0.001 from a neighboring hyperplane. Qhull accounts for +roundoff error when testing the centrum.</p> + +<p>Both pre-merging and post-merging may be defined. If only +post-merging is used ('<a href="qh-optq.htm#Q0">Q0</a>' with +'Cn'), Qhull may fail to produce a hull due to precision errors +during the hull's construction.</p> + +<h3><a href="#prec">»</a><a name="En">En - max roundoff error +for distance computations</a></h3> + +<p>This allows the user to change the maximum roundoff error +computed by Qhull. The value computed by Qhull may be overly +pessimistic. If 'En' is set too small, then the output may not be +convex. The statistic "max. distance of a new vertex to a +facet" (from option '<a href="qh-optt.htm#Ts">Ts</a>') is a +reasonable upper bound for the actual roundoff error. </p> + +<h3><a href="#prec">»</a><a name="Rn">Rn - randomly perturb +computations </a></h3> + +<p>This option perturbs every distance, hyperplane, and angle +computation by up to <i>(+/- n * max_coord)</i>. It simulates the +effect of roundoff errors. Unless '<a href="#En">En</a>' is +explicitly set, it is adjusted for 'Rn'. The command 'qhull Rn' +will generate a convex hull despite the perturbations. See the <a +href="qh-eg.htm#merge">Examples </a>section for an example.</p> + +<p>Options 'Rn C-n' have the effect of '<a href="#Wn">W2n</a>' +and '<a href="#Cn">C-2n</a>'. To use time as the random number +seed, use option '<a href="qh-optq.htm#QRn">QR-1</a>'.</p> + +<h3><a href="#prec">»</a><a name="Un">Un - max distance for a +new, coplanar point </a></h3> + +<p>This allows the user to set coplanarity. When pre-merging ('<a +href="#Cn">C-n </a>', '<a href="#An">A-n</a>' or '<a +href="qh-optq.htm#Qx">Qx</a>'), Qhull merges a new point into any +coplanar facets. The default value for 'Un' is '<a href="#Vn">Vn</a>'.</p> + +<h3><a href="#prec">»</a><a name="Vn">Vn - min distance for a +visible facet </a></h3> + +<p>This allows the user to set facet visibility. When adding a +point to the convex hull, Qhull determines all facets that are +visible from the point. A facet is visible if the distance from +the point to the facet is greater than 'Vn'.</p> + +<p>Without merging, the default value for 'Vn' is the roundoff +error ('<a href="#En">En</a>'). With merging, the default value +is the pre-merge centrum ('<a href="#Cn">C-n</a>') in 2-d or 3-d, +or three times that in other dimensions. If the outside width is +specified with option '<a href="#Wn">Wn </a>', the maximum, +default value for 'Vn' is '<a href="#Wn">Wn</a>'.</p> + +<p>Qhull warns if 'Vn' is greater than '<a href="#Wn">Wn</a>' and +furthest outside ('<a href="qh-optq.htm#Qf">Qf</a>') is not +selected; this combination usually results in flipped facets +(i.e., reversed normals).</p> + +<h3><a href="#prec">»</a><a name="Wn">Wn - min distance above +plane for outside points</a></h3> + +<p>Points are added to the convex hull only if they are clearly +outside of a facet. A point is outside of a facet if its distance +to the facet is greater than 'Wn'. Without pre-merging, the +default value for 'Wn' is '<a href="#En">En </a>'. If the user +specifies pre-merging and does not set 'Wn', than 'Wn' is set to +the maximum of '<a href="#Cn">C-n</a>' and <i>maxcoord*(1 - </i><a +href="#An"><i>A-n</i></a><i>)</i>.</p> + +<p>This option is good for <a href="qh-impre.htm#approximate">approximating</a> +a convex hull.</p> + +<p>Options '<a href="qh-optq.htm#Qc">Qc</a>' and '<a +href="qh-optq.htm#Qi">Qi</a>' use the minimum vertex to +distinguish coplanar points from interior points.</p> +<!-- Navigation links --> +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> +<!-- GC common information --> +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="qh--geom.gif" +align="middle" width="40" height="40"></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: Sept. 25, 1995 --- <!-- hhmts start --> Last modified: see top <!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/qh-optf.htm b/xs/src/qhull/html/qh-optf.htm new file mode 100644 index 000000000..3c7a2b1db --- /dev/null +++ b/xs/src/qhull/html/qh-optf.htm @@ -0,0 +1,736 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<title>Qhull format options (F)</title> +</head> + +<body><!-- Navigation links --> +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> +<hr> +<!-- Main text of document --> +<h1><a + href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/delaunay.html"><IMG + align=middle alt=[delaunay] height=100 + src="qh--dt.gif" width=100 ></a> Qhull format options (F)</h1> + +<p>This section lists the format options for Qhull. These options +are indicated by 'F' followed by a letter. See <A + href="qh-opto.htm#output" >Output</a>, <a href="qh-optp.htm#print">Print</a>, +and <a href="qh-optg.htm#geomview">Geomview</a> for other output +options. </p> + +<p><b>Copyright © 1995-2015 C.B. Barber</b></p> + +<hr> + +<p><a href="index.htm#TOC">»</a> <a href="qh-quick.htm#programs">Programs</a> +<a name="format">•</a> <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> + +<h2>Additional input & output formats</h2> + +<p>These options allow for automatic processing of Qhull output. +Options '<a href="qh-opto.htm#i">i</a>', '<a href="qh-opto.htm#o">o</a>', +'<a href="qh-opto.htm#n">n</a>', and '<a href="qh-opto.htm#p">p</a>' +may also be used.</p> + +<dl compact> + <dt> + <dd><b>Summary and control</b> + <dt><a href="#FA">FA</a> + <dd>compute total area and volume for option '<A + href="qh-opto.htm#s">s</a>' + + <dt><a href="#FV">FV</a> + <dd>print average vertex (interior point for '<A + href="qhalf.htm">qhalf</a>') + <dt><a href="#FQ">FQ</a> + <dd>print command for qhull and input + <dt><a href="#FO">FO</a> + <dd>print options to stderr or stdout + <dt><a href="#FS">FS</a> + <dd>print sizes: total area and volume + <dt><a href="#Fs">Fs</a> + <dd>print summary: dim, #points, total vertices and + facets, #vertices, #facets, max outer and inner plane + <dt><a href="#Fd">Fd</a> + <dd>use format for input (offset first) + <dt><a href="#FD">FD</a> + <dd>use cdd format for normals (offset first) + <dt><a href="#FM">FM</a> + <dd>print Maple output (2-d and 3-d) + <dt> + <dt> + <dd><b>Facets, points, and vertices</b> + <dt><a href="#Fa">Fa</a> + <dd>print area for each facet + <dt><a href="#FC">FC</a> + <dd>print centrum for each facet + <dt><a href="#Fc">Fc</a> + <dd>print coplanar points for each facet + <dt><a href="#Fx">Fx</a> + <dd>print extreme points (i.e., vertices) of convex hull. + + <dt><a href="#FF">FF</a> + <dd>print facets w/o ridges + <dt><a href="#FI">FI</a> + <dd>print ID for each facet + <dt><a href="#Fi">Fi</a> + <dd>print inner planes for each facet + <dt><a href="#Fm">Fm</a> + <dd>print merge count for each facet (511 max) + <dt><a href="#FP">FP</a> + <dd>print nearest vertex for coplanar points + <dt><a href="#Fn">Fn</a> + <dd>print neighboring facets for each facet + <dt><a href="#FN">FN</a> + <dd>print neighboring facets for each point + <dt><a href="#Fo">Fo</a> + <dd>print outer planes for each facet + <dt><a href="#Ft">Ft</a> + <dd>print triangulation with added points + <dt><a href="#Fv">Fv</a> + <dd>print vertices for each facet + <dt> + <dt> + <dd><b>Delaunay, Voronoi, and halfspace</b> + <dt><a href="#Fx">Fx</a> + <dd>print extreme input sites of Delaunay triangulation + or Voronoi diagram. + <dt><a href="#Fp">Fp</a> + <dd>print points at halfspace intersections + <dt><a href="#Fi2">Fi</a> + <dd>print separating hyperplanes for inner, bounded + Voronoi regions + <dt><a href="#Fo2">Fo</a> + <dd>print separating hyperplanes for outer, unbounded + Voronoi regions + <dt><a href="#Fv2">Fv</a> + <dd>print Voronoi diagram as ridges for each input pair + <dt><a href="#FC">FC</a> + <dd>print Voronoi vertex ("center") for each facet</dd> +</dl> + +<hr> + +<h3><a href="#format">»</a><a name="Fa">Fa - print area for each +facet </a></h3> + +<p>The first line is the number of facets. The remaining lines +are the area for each facet, one facet per line. See '<A + href="#FA" >FA</a>' and '<a href="#FS">FS</a>' for computing the total area and volume.</p> + +<p>Use '<a href="qh-optp.htm#PAn">PAn</a>' for printing the n +largest facets. Use option '<a href="qh-optp.htm#PFn">PFn</a>' +for printing facets larger than <i>n</i>.</p> + +<p>For Delaunay triangulations, the area is the area of each +Delaunay triangle. For Voronoi vertices, the area is the area of +the dual facet to each vertex. </p> + +<p>Qhull uses the centrum and ridges to triangulate +non-simplicial facets. The area for non-simplicial facets is the +sum of the areas for each triangle. It is an approximation of the +actual area. The ridge's vertices are projected to the facet's +hyperplane. If a vertex is far below a facet (qh_WIDEcoplanar in <tt>user.h</tt>), +the corresponding triangles are ignored.</p> + +<p>For non-simplicial facets, vertices are often below the +facet's hyperplane. If so, the approximation is less than the +actual value and it may be significantly less. </p> + +<h3><a href="#format">»</a><a name="FA">FA - compute total area +and volume for option 's' </a></h3> + +<p>With option 'FA', Qhull includes the total area and volume in +the summary ('<a href="qh-opto.htm#s">s</a>'). Option '<a href="#FS">FS</a>' also includes the total area and volume. +If facets are +merged, the area and volume are approximations. Option 'FA' is +automatically set for options '<a href="#Fa">Fa</a>', '<A + href="qh-optp.htm#PAn" >PAn</a>', and '<a href="qh-optp.htm#PFn">PFn</a>'. +</p> + +<p>With '<a href="qdelaun.htm">qdelaunay</a> <A + href="qh-opto.htm#s" >s</a> FA', Qhull computes the total area of +the Delaunay triangulation. This equals the volume of the convex +hull of the data points. With options '<a href="qdelau_f.htm">qdelaunay Qu</a> +<a href="qh-opto.htm#s">s</a> FA', Qhull computes the +total area of the furthest-site Delaunay triangulation. This +equals of the total area of the Delaunay triangulation. </p> + +<p>See '<a href="#Fa">Fa</a>' for further details. Option '<a href="#FS">FS</a>' also computes the total area and volume.</p> + +<h3><a href="#format">»</a><a name="Fc">Fc - print coplanar +points for each facet </a></h3> + +<p>The output starts with the number of facets. Then each facet +is printed one per line. Each line is the number of coplanar +points followed by the point ids. </p> + +<p>By default, option 'Fc' reports coplanar points +('<a href="qh-optq.htm#Qc">Qc</a>'). You may also use +option '<a href="qh-optq.htm#Qi">Qi</a>'. Options 'Qi Fc' prints +interior points while 'Qci Fc' prints both coplanar and interior +points. + +<p>Each coplanar point or interior point is assigned to the +facet it is furthest above (resp., least below). </p> + +<p>Use 'Qc <a href="qh-opto.htm#p">p</a>' to print vertex and +coplanar point coordinates. Use '<a href="qh-optf.htm#Fv">Fv</a>' +to print vertices. </p> + +<h3><a href="#format">»</a><a name="FC">FC - print centrum or +Voronoi vertex for each facet </a></h3> + +<p>The output starts with the dimension followed by the number of +facets. Then each facet centrum is printed, one per line. For +<a href="qvoronoi.htm">qvoronoi</a>, Voronoi vertices are +printed instead. </p> + +<h3><a href="#format">»</a><a name="Fd">Fd - use cdd format for +input </a></h3> + +<p>The input starts with comments. The first comment is reported +in the summary. Data starts after a "begin" line. The +next line is the number of points followed by the dimension plus +one and "real" or "integer". Then the points +are listed with a leading "1" or "1.0". The +data ends with an "end" line.</p> + +<p>For halfspaces ('<a href="qhalf.htm">qhalf</a> Fd'), +the input format is the same. Each halfspace starts with its +offset. The signs of the offset and coefficients are the +opposite of Qhull's +convention. The first two lines of the input may be an interior +point in '<a href="#FV">FV</a>' format.</p> + +<h3><a href="#format">»</a><a name="FD">FD - use cdd format for +normals </a></h3> + +<p>Option 'FD' prints normals ('<a href="qh-opto.htm#n">n</a>', '<A + href="#Fo" >Fo</a>', '<a href="#Fi">Fi</a>') or points ('<A + href="qh-opto.htm#p" >p</a>') in cdd format. The first line is the +command line that invoked Qhull. Data starts with a +"begin" line. The next line is the number of normals or +points followed by the dimension plus one and "real". +Then the normals or points are listed with the offset before the +coefficients. The offset for points is 1.0. For normals, +the offset and coefficients use the opposite sign from Qhull. +The data ends with an "end" line.</p> + +<h3><a href="#format">»</a><a name="FF">FF - print facets w/o +ridges </a></h3> + +<p>Option 'FF' prints all fields of all facets (as in '<A + href="qh-opto.htm#f" >f</a>') without printing the ridges. This is +useful in higher dimensions where a facet may have many ridges. +For simplicial facets, options 'FF' and '<a href="qh-opto.htm#f">f +</a>' are equivalent.</p> + +<h3><a href="#format">»</a><a name="Fi">Fi - print inner planes +for each facet </a></h3> + +<p>The first line is the dimension plus one. The second line is +the number of facets. The remainder is one inner plane per line. +The format is the same as option '<a href="qh-opto.htm#n">n</a>'.</p> + +<p>The inner plane is a plane that is below the facet's vertices. +It is an offset from the facet's hyperplane. It includes a +roundoff error for computing the vertex distance.</p> + +<p>Note that the inner planes for Geomview output ('<A + href="qh-optg.htm#Gi" >Gi</a>') include an additional offset for +vertex visualization and roundoff error. </p> + +<h3><a href="#format">»</a><a name="Fi2">Fi - print separating +hyperplanes for inner, bounded Voronoi regions</a></h3> + +<p>With <a href="qvoronoi.htm" >qvoronoi</a>, 'Fi' prints the +separating hyperplanes for inner, bounded regions of the Voronoi +diagram. The first line is the number of ridges. Then each +hyperplane is printed, one per line. A line starts with the +number of indices and floats. The first pair of indices indicates +an adjacent pair of input sites. The next <i>d</i> floats are the +normalized coefficients for the hyperplane, and the last float is +the offset. The hyperplane is oriented toward '<A + href="qh-optq.htm#QVn" >QVn</a>' (if defined), or the first input +site of the pair. </p> + +<p>Use '<a href="qh-optf.htm#Fo2">Fo</a>' for unbounded regions, +and '<a href="qh-optf.htm#Fv2">Fv</a>' for the corresponding +Voronoi vertices. </p> + +<p>Use '<a href="qh-optt.htm#Tv">Tv</a>' to verify that the +hyperplanes are perpendicular bisectors. It will list relevant +statistics to stderr. The hyperplane is a perpendicular bisector +if the midpoint of the input sites lies on the plane, all Voronoi +vertices in the ridge lie on the plane, and the angle between the +input sites and the plane is ninety degrees. This is true if all +statistics are zero. Roundoff and computation errors make these +non-zero. The deviations appear to be largest when the +corresponding Delaunay triangles are large and thin; for example, +the Voronoi diagram of nearly cospherical points. </p> + +<h3><a href="#format">»</a><a name="FI">FI - print ID for each +facet </a></h3> + +<p>Print facet identifiers. These are used internally and listed +with options '<a href="qh-opto.htm#f">f</a>' and '<a href="#FF">FF</a>'. +Options '<a href="#Fn">Fn </a>' and '<a href="#FN">FN</a>' use +facet identifiers for negative indices. </p> + +<h3><a href="#format">»</a><a name="Fm">Fm - print merge count +for each facet </a></h3> + +<p>The first line is the number of facets. The remainder is the +number of merges for each facet, one per line. At most 511 merges +are reported for a facet. See '<a href="qh-optp.htm#PMn">PMn</a>' +for printing the facets with the most merges. </p> + +<h3><a href="#format">»</a><a name="FM">FM - print Maple +output </a></h3> + +<p>Qhull writes a Maple file for 2-d and 3-d convex hulls, +2-d and 3-d halfspace intersections, +and 2-d Delaunay triangulations. Qhull produces a 2-d +or 3-d plot. + +<p><i>Warning</i>: This option has not been tested in Maple. + +<p>[From T. K. Abraham with help from M. R. Feinberg and N. Platinova.] +The following steps apply while working within the +Maple worksheet environment : +<ol> +<li>Generate the data and store it as an array . For example, in 3-d, data generated +in Maple is of the form : x[i],y[i],z[i] +<p> +<li>Create a single variable and assign the entire array of data points to this variable. +Use the "seq" command within square brackets as shown in the following example. +(The square brackets are essential for the rest of the steps to work.) +<p> +>data:=[seq([x[i],y[i],z[i]],i=1..n)]:# here n is the number of data points + +<li>Next we need to write the data to a file to be read by qhull. Before +writing the data to a file, make sure that the qhull executable files and +the data file lie in the same subdirectory. If the executable files are +stored in the "C:\qhull3.1\" subdirectory, then save the file in the same +subdirectory, say "C:\qhull3.1\datafile.txt". For the sake of integrity of +the data file , it is best to first ensure that the data file does not +exist before writing into the data file. This can be done by running a +delete command first . To write the data to the file, use the "writedata" +and the "writedata[APPEND]" commands as illustrated in the following example : +<p> +>system("del c:\\qhull3.1\\datafile.txt");#To erase any previous versions of the file +<br>>writedata("c:\\qhull3.1\\datafile.txt ",[3, nops(data)]);#writing in qhull format +<br>>writedata[APPEND]("c:\\ qhull3.1\\datafile.txt ", data);#writing the data points +<li> +Use the 'FM' option to produce Maple output. Store the output as a ".mpl" file. +For example, using the file we created above, we type the following (in DOS environment) +<p> +qconvex s FM <datafile.txt >dataplot.mpl + +<li> +To read 3-d output in Maple, we use the 'read' command followed by +a 'display3d' command. For example (in Maple environment): +<p> +>with (plots): +<br>>read `c:\\qhull3.1\\dataplot.mpl`:#IMPORTANT - Note that the punctuation mark used is ' and NOT '. The correct punctuation mark is the one next to the key for "1" (not the punctuation mark near the enter key) +<br>> qhullplot:=%: +<br>> display3d(qhullplot); +</ol> + +<p>For Delaunay triangulation orthogonal projection is better. + +<p>For halfspace intersections, Qhull produces the dual +convex hull. + +<p>See <a href="qh-faq.htm#math">Is Qhull available for Maple?</a> +for other URLs. + +<h3><a href="#format">»</a><a name="Fn">Fn - print neighboring +facets for each facet </a></h3> + +<p>The output starts with the number of facets. Then each facet +is printed one per line. Each line is the number of neighbors +followed by an index for each neighbor. The indices match the +other facet output formats.</p> + +<p>For simplicial facets, each neighbor is opposite +the corresponding vertex (option '<a href="#Fv">Fv</a>'). +Do not compare to option '<a href="qh-opto.htm#i">i</a>'. Option 'i' +orients facets by reversing the order of two vertices. For non-simplicial facets, +the neighbors are unordered. + +<p>A negative index indicates an unprinted facet due to printing +only good facets ('<a href="qh-optp.htm#Pg">Pg</a>', <a href="qdelaun.htm" >qdelaunay</a>, +<a href="qvoronoi.htm" >qvoronoi</a>). It +is the negation of the facet's ID (option '<a href="#FI">FI</a>'). +For example, negative indices are used for facets "at +infinity" in the Delaunay triangulation.</p> + +<h3><a href="#format">»</a><a name="FN">FN - print neighboring +facets for each point </a></h3> + +<p>The first line is the number of points. Then each point is +printed, one per line. For unassigned points (either interior or +coplanar), the line is "0". For assigned coplanar +points ('<a href="qh-optq.htm#Qc">Qc</a>'), the line is +"1" followed by the index of the facet that is furthest +below the point. For assigned interior points ('<A + href="qh-optq.htm#Qi" >Qi</a>'), the line is "1" +followed by the index of the facet that is least above the point. +For vertices that do not belong to good facet, the line is +"0"</p> + +<p>For vertices of good facets, the line is the number of +neighboring facets followed by the facet indices. The indices +correspond to the other '<a href="#format">F</a>' formats. In 4-d +and higher, the facets are sorted by index. In 3-d, the facets +are in adjacency order (not oriented).</p> + +<p>A negative index indicates an unprinted facet due to printing +only good facets (<a href="qdelaun.htm" >qdelaunay</a>, +<a href="qvoronoi.htm" >qvoronoi</a>, '<a href="qh-optp.htm#Pdk">Pdk</a>', +'<a href="qh-optp.htm#Pg">Pg</a>'). It is the negation of the +facet's ID ('<a href="#FI"> FI</a>'). For example, negative +indices are used for facets "at infinity" in the +Delaunay triangulation.</p> + +<p>For Voronoi vertices, option 'FN' lists the vertices of the +Voronoi region for each input site. Option 'FN' lists the regions +in site ID order. Option 'FN' corresponds to the second half of +option '<a href="qh-opto.htm#o">o</a>'. To convert from 'FN' to '<A + href="qh-opto.htm#o" >o</a>', replace negative indices with zero +and increment non-negative indices by one. </p> + +<p>If you are using the <a href="qh-code.htm#library">Qhull +library</a> or <a href="qh-code.htm#cpp">C++ interface</a>, option 'FN' has the side effect of reordering the +neighbors for a vertex </p> + +<h3><a href="#format">»</a><a name="Fo">Fo - print outer planes +for each facet </a></h3> + +<p>The first line is the dimension plus one. The second line is +the number of facets. The remainder is one outer plane per line. +The format is the same as option '<a href="qh-opto.htm#n">n</a>'.</p> + +<p>The outer plane is a plane that is above all points. It is an +offset from the facet's hyperplane. It includes a roundoff error +for computing the point distance. When testing the outer plane +(e.g., '<a href="qh-optt.htm#Tv">Tv</a>'), another roundoff error +should be added for the tested point.</p> + +<p>If outer planes are not checked ('<a href="qh-optq.htm#Q5">Q5</a>') +or not computed (!qh_MAXoutside), the maximum, computed outside +distance is used instead. This can be much larger than the actual +outer planes.</p> + +<p>Note that the outer planes for Geomview output ('<A + href="qh-optg.htm#G" >G</a>') include an additional offset for +vertex/point visualization, 'lines closer,' and roundoff error.</p> + +<h3><a href="#format">»</a><a name="Fo2">Fo - print separating +hyperplanes for outer, unbounded Voronoi regions</a></h3> + +<p>With <a href="qvoronoi.htm" >qvoronoi</a>, 'Fo' prints the +separating hyperplanes for outer, unbounded regions of the +Voronoi diagram. The first line is the number of ridges. Then +each hyperplane is printed, one per line. A line starts with the +number of indices and floats. The first pair of indices indicates +an adjacent pair of input sites. The next <i>d</i> floats are the +normalized coefficients for the hyperplane, and the last float is +the offset. The hyperplane is oriented toward '<A + href="qh-optq.htm#QVn" >QVn</a>' (if defined), or the first input +site of the pair. </p> + +<p>Option 'Fo' gives the hyperplanes for the unbounded rays of +the unbounded regions of the Voronoi diagram. Each hyperplane +goes through the midpoint of the corresponding input sites. The +rays are directed away from the input sites. </p> + +<p>Use '<a href="qh-optf.htm#Fi2">Fi</a>' for bounded regions, +and '<a href="qh-optf.htm#Fv2">Fv</a>' for the corresponding +Voronoi vertices. Use '<a href="qh-optt.htm#Tv">Tv</a>' to verify +that the corresponding Voronoi vertices lie on the hyperplane. </p> + +<h3><a href="#format">»</a><a name="FO">FO - print list of +selected options </a></h3> + +<p>Lists selected options and default values to stderr. +Additional 'FO's are printed to stdout. </p> + +<h3><a href="#format">»</a><a name="Fp">Fp - print points at +halfspace intersections</a></h3> + +<p>The first line is the number of intersection points. The +remainder is one intersection point per line. A intersection +point is the intersection of <i>d</i> or more halfspaces from +'<a href="qhalf.htm">qhalf</a>'. It corresponds to a +facet of the dual polytope. The "infinity" point +[-10.101,-10.101,...] indicates an unbounded intersection.</p> + +<p>If [x,y,z] are the dual facet's normal coefficients and <i>b<0</i> +is its offset, the halfspace intersection occurs at +[x/-b,y/-b,z/-b] plus the interior point. If <i>b>=0</i>, the +halfspace intersection is unbounded. </p> + +<h3><a href="#format">»</a><a name="FP">FP - print nearest +vertex for coplanar points </a></h3> + +<p>The output starts with the number of coplanar points. Then +each coplanar point is printed one per line. Each line is the +point ID of the closest vertex, the point ID of the coplanar +point, the corresponding facet ID, and the distance. Sort the +lines to list the coplanar points nearest to each vertex. </p> + +<p>Use options '<a href="qh-optq.htm#Qc">Qc</a>' and/or '<A + href="qh-optq.htm#Qi" >Qi</a>' with 'FP'. Options 'Qc FP' prints +coplanar points while 'Qci FP' prints coplanar and interior +points. Option 'Qc' is automatically selected if 'Qi' is not +selected. + +<p>For Delaunay triangulations (<a href="qdelaun.htm" >qdelaunay</a> +or <a href="qvoronoi.htm" >qvoronoi</a>), a coplanar point is nearly +incident to a vertex. The distance is the distance in the +original point set.</p> + +<p>If imprecision problems are severe, Qhull will delete input +sites when constructing the Delaunay triangulation. Option 'FP' will +list these points along with coincident points.</p> + +<p>If there are many coplanar or coincident points and non-simplicial +facets are triangulated ('<a href="qh-optq.htm#Qt">Qt</a>'), option +'FP' may be inefficient. It redetermines the original vertex set +for each coplanar point.</p> + +<h3><a href="#format">»</a><a name="FQ">FQ - print command for +qhull and input </a></h3> + +<p>Prints qhull and input command, e.g., "rbox 10 s | qhull +FQ". Option 'FQ' may be repeated multiple times.</p> + +<h3><a href="#format">»</a><a name="Fs">Fs - print summary</a></h3> + +<p>The first line consists of number of integers ("10") +followed by the: +<ul> +<li>dimension +<li>number of points +<li>number of vertices +<li>number of facets +<li>number of vertices selected for output +<li>number of facets selected for output +<li>number of coplanar points for selected facets +<li>number of nonsimplicial or merged facets selected for + output +<LI>number of deleted vertices</LI> +<LI>number of triangulated facets ('<a href="qh-optq.htm#Qt">Qt</a>')</LI> +</ul> + +<p>The second line consists of the number of reals +("2") followed by the: +<ul> +<li>maximum offset to an outer plane +<li>minimum offset to an inner plane.</li> +</ul> +Roundoff and joggle are included. +<P></P> + +<p>For Delaunay triangulations and Voronoi diagrams, the +number of deleted vertices should be zero. If greater than zero, then the +input is highly degenerate and coplanar points are not necessarily coincident +points. For example, <tt>'RBOX 1000 s W1e-13 t995138628 | QHULL d Qbb'</tt> reports +deleted vertices; the input is nearly cospherical.</p> + +<P>Later versions of Qhull may produce additional integers or reals.</P> + +<h3><a href="#format">»</a><a name="FS">FS - print sizes</a></h3> + +<p>The first line consists of the number of integers +("0"). The second line consists of the number of reals +("2"), followed by the total facet area, and the total +volume. Later versions of Qhull may produce additional integers +or reals.</p> + +<p>The total volume measures the volume of the intersection of +the halfspaces defined by each facet. It is computed from the +facet area. Both area and volume are approximations for +non-simplicial facets. See option '<a href="#Fa">Fa </a>' for +further notes. Option '<a href="#FA">FA </a>' also computes the total area and volume. </p> + +<h3><a href="#format">»</a><a name="Ft">Ft - print triangulation</a></h3> + +<p>Prints a triangulation with added points for non-simplicial +facets. The output is </p> + +<ul> + <li>The first line is the dimension + <li>The second line is the number of points, the number + of facets, and the number of ridges. + <li>All of the input points follow, one per line. + <li>The centrums follow, one per non-simplicial facet + <li>Then the facets follow as a list of point indices + preceded by the number of points. The simplices are + oriented. </li> +</ul> + +<p>For convex hulls with simplicial facets, the output is the +same as option '<a href="qh-opto.htm#o">o</a>'.</p> + +<p>The added points are the centrums of the non-simplicial +facets. Except for large facets, the centrum is the average +vertex coordinate projected to the facet's hyperplane. Large +facets may use an old centrum to avoid recomputing the centrum +after each merge. In either case, the centrum is clearly below +neighboring facets. See <a href="qh-impre.htm">Precision issues</a>. +</p> + +<p>The new simplices will not be clearly convex with their +neighbors and they will not satisfy the Delaunay property. They +may even have a flipped orientation. Use triangulated input ('<A + href="qh-optq.htm#Qt">Qt</a>') for Delaunay triangulations. + +<p>For Delaunay triangulations with simplicial facets, the output is the +same as option '<a href="qh-opto.htm#o">o</a>' without the lifted +coordinate. Since 'Ft' is invalid for merged Delaunay facets, option +'Ft' is not available for qdelaunay or qvoronoi. It may be used with +joggled input ('<a href="qh-optq.htm#QJn" >QJ</a>') or triangulated output ('<A + href="qh-optq.htm#Qt" >Qt</a>'), for example, rbox 10 c G 0.01 | qhull d QJ Ft</p> + +<p>If you add a point-at-infinity with '<a href="qh-optq.htm#Qz">Qz</a>', +it is printed after the input sites and before any centrums. It +will not be used in a Delaunay facet.</p> + +<h3><a href="#format">»</a><a name="Fv">Fv - print vertices for +each facet</a></h3> + +<p>The first line is the number of facets. Then each facet is +printed, one per line. Each line is the number of vertices +followed by the corresponding point ids. Vertices are listed in +the order they were added to the hull (the last one added is the +first listed). +</p> +<p>Option '<a href="qh-opto.htm#i">i</a>' also lists the vertices, +but it orients facets by reversing the order of two +vertices. Option 'i' triangulates non-simplicial, 4-d and higher facets by +adding vertices for the centrums. +</p> + +<h3><a href="#format">»</a><a name="Fv2">Fv - print Voronoi +diagram</a></h3> + +<p>With <a href="qvoronoi.htm" >qvoronoi</a>, 'Fv' prints the +Voronoi diagram or furthest-site Voronoi diagram. The first line +is the number of ridges. Then each ridge is printed, one per +line. The first number is the count of indices. The second pair +of indices indicates a pair of input sites. The remaining indices +list the corresponding ridge of Voronoi vertices. Vertex 0 is the +vertex-at-infinity. It indicates an unbounded ray. </p> + +<p>All vertices of a ridge are coplanar. If the ridge is +unbounded, add the midpoint of the pair of input sites. The +unbounded ray is directed from the Voronoi vertices to infinity. </p> + +<p>Use '<a href="qh-optf.htm#Fo2">Fo</a>' for separating +hyperplanes of outer, unbounded regions. Use '<A + href="qh-optf.htm#Fi2" >Fi</a>' for separating hyperplanes of +inner, bounded regions. </p> + +<p>Option 'Fv' does not list ridges that require more than one +midpoint. For example, the Voronoi diagram of cospherical points +lists zero ridges (e.g., 'rbox 10 s | qvoronoi Fv Qz'). +Other examples are the Voronoi diagrams of a rectangular mesh +(e.g., 'rbox 27 M1,0 | qvoronoi Fv') or a point set with +a rectangular corner (e.g., +'rbox P4,4,4 P4,2,4 P2,4,4 P4,4,2 10 | qvoronoi Fv'). +Both cases miss unbounded rays at the corners. +To determine these ridges, surround the points with a +large cube (e.g., 'rbox 10 s c G2.0 | qvoronoi Fv Qz'). +The cube needs to be large enough to bound all Voronoi regions of the original point set. +Please report any other cases that are missed. If you +can formally describe these cases or +write code to handle them, please send email to <A + href="mailto:qhull@qhull.org" >qhull@qhull.org</a>. </p> + +<h3><a href="#format">»</a><a name="FV">FV - print average +vertex </a></h3> + +<p>The average vertex is the average of all vertex coordinates. +It is an interior point for halfspace intersection. The first +line is the dimension and "1"; the second line is the +coordinates. For example,</p> + +<blockquote> + <p>qconvex FV <A + href="qh-opto.htm#n">n</a> | qhalf <a href="#Fp">Fp</a></p> +</blockquote> + +<p>prints the extreme points of the original point set (roundoff +included). </p> + +<h3><a href="#format">»</a><a name="Fx">Fx - print extreme +points (vertices) of convex hulls and Delaunay triangulations</a></h3> + +<p>The first line is the number of points. The following lines +give the index of the corresponding points. The first point is +'0'. </p> + +<p>In 2-d, the extreme points (vertices) are listed in +counterclockwise order (by qh_ORIENTclock in user.h). </p> + +<p>In 3-d and higher convex hulls, the extreme points (vertices) +are sorted by index. This is the same order as option '<A + href="qh-opto.htm#p" >p</a>' when it doesn't include coplanar or +interior points. </p> + +<p>For Delaunay triangulations, 'Fx' lists the extreme +points of the input sites (i.e., the vertices of their convex hull). The points +are unordered. <!-- Navigation links --> </p> + +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p><!-- GC common information --> +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><IMG align=middle + height=40 src="qh--geom.gif" width=40 ></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: +Sept. 25, 1995 --- <!-- hhmts start -->Last modified: see top +<!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/qh-optg.htm b/xs/src/qhull/html/qh-optg.htm new file mode 100644 index 000000000..a56e29df1 --- /dev/null +++ b/xs/src/qhull/html/qh-optg.htm @@ -0,0 +1,274 @@ +<html> + +<head> +<title>Qhull Geomview options (G)</title> +</head> + +<body> +<!-- Navigation links --> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> + +<hr> +<!-- Main text of document --> + +<h1><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/delaunay.html"><img +src="qh--dt.gif" alt="[delaunay]" align="middle" width="100" +height="100"></a> Qhull Geomview options (G)</h1> + +This section lists the Geomview options for Qhull. These options are +indicated by 'G' followed by a letter. See +<a href="qh-opto.htm#output">Output</a>, <a href="qh-optp.htm#print">Print</a>, +and <a href="qh-optf.htm#format">Format</a> for other output options. + + +<p><b>Copyright © 1995-2015 C.B. Barber</b></p> + +<hr> + +<p><a href="index.htm#TOC">»</a> <a href="qh-quick.htm#programs">Programs</a> +<a name="geomview">•</a> <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> + +<h2>Geomview output options</h2> + +<p><a href="http://www.geomview.org">Geomview</a> is the graphical +viewer for visualizing Qhull output in 2-d, 3-d and 4-d.</p> + +<p>Geomview displays each facet of the convex hull. The color of +a facet is determined by the coefficients of the facet's normal +equation. For imprecise hulls, Geomview displays the inner and +outer hull. Geomview can also display points, ridges, vertices, +coplanar points, and facet intersections. </p> + +<p>For 2-d Delaunay triangulations, Geomview displays the +corresponding paraboloid. Geomview displays the 2-d Voronoi +diagram. For halfspace intersections, it displays the +dual convex hull. </p> + +<dl compact> + <dt> </dt> + <dd><b>General</b></dd> + <dt><a href="#G">G</a></dt> + <dd>display Geomview output</dd> + <dt><a href="#Gt">Gt</a></dt> + <dd>display transparent 3-d Delaunay triangulation</dd> + <dt><a href="#GDn">GDn</a></dt> + <dd>drop dimension n in 3-d and 4-d output </dd> + + <dt> </dt> + <dt> </dt> + <dd><b>Specific</b></dd> + <dt><a href="#Ga">Ga</a></dt> + <dd>display all points as dots</dd> + <dt><a href="#Gc">Gc</a></dt> + <dd>display centrums (2-d, 3-d)</dd> + <dt><a href="#Gp">Gp</a></dt> + <dd>display coplanar points and vertices as radii</dd> + <dt><a href="#Gh">Gh</a></dt> + <dd>display hyperplane intersections</dd> + <dt><a href="#Gi">Gi</a></dt> + <dd>display inner planes only (2-d, 3-d)</dd> + <dt><a href="#Go">Go</a></dt> + <dd>display outer planes only (2-d, 3-d)</dd> + <dt><a href="#Gr">Gr</a></dt> + <dd>display ridges (3-d)</dd> + <dt><a href="#Gv">Gv</a></dt> + <dd>display vertices as spheres</dd> + <dt><a href="#Gn">Gn</a></dt> + <dd>do not display planes</dd> + +</dl> + +<hr> + +<h3><a href="#geomview">»</a><a name="G">G - produce output for +viewing with Geomview</a></h3> + +<p>By default, option 'G' displays edges in 2-d, outer planes in +3-d, and ridges in 4-d.</p> + +<p>A ridge can be explicit or implicit. An explicit ridge is a <i>(d-1)</i>-dimensional +simplex between two facets. In 4-d, the explicit ridges are +triangles. An implicit ridge is the topological intersection of +two neighboring facets. It is the union of explicit ridges.</p> + +<p>For non-simplicial 4-d facets, the explicit ridges can be +quite complex. When displaying a ridge in 4-d, Qhull projects the +ridge's vertices to one of its facets' hyperplanes. Use '<a +href="#Gh">Gh</a>' to project ridges to the intersection of both +hyperplanes. This usually results in a cleaner display. </p> + +<p>For 2-d Delaunay triangulations, Geomview displays the +corresponding paraboloid. Geomview displays the 2-d Voronoi +diagram. For halfspace intersections, it displays the +dual convex hull. + +<h3><a href="#geomview">»</a><a name="Ga">Ga - display all +points as dots </a></h3> + +<p>Each input point is displayed as a green dot.</p> + +<h3><a href="#geomview">»</a><a name="Gc">Gc - display centrums +(3-d) </a></h3> + +<p>The centrum is defined by a green radius sitting on a blue +plane. The plane corresponds to the facet's hyperplane. If you +sight along a facet's hyperplane, you will see that all +neighboring centrums are below the facet. The radius is defined +by '<a href="qh-optc.htm#Cn">C-n</a>' or '<a +href="qh-optc.htm#Cn2">Cn</a>'.</p> + +<h3><a href="#geomview">»</a><a name="GDn">GDn - drop dimension +n in 3-d and 4-d output </a></h3> + +<p>The result is a 2-d or 3-d object. In 4-d, this corresponds to +viewing the 4-d object from the nth axis without perspective. +It's best to view 4-d objects in pieces. Use the '<a +href="qh-optp.htm#Pdk">Pdk</a>' '<a href="qh-optp.htm#Pg">Pg</a>' +'<a href="qh-optp.htm#PG">PG</a>' '<a href="qh-optq.htm#QGn">QGn</a>' +and '<a href="qh-optq.htm#QVn">QVn</a>' options to select a few +facets. If one of the facets is perpendicular to an axis, then +projecting along that axis will show the facet exactly as it is +in 4-d. If you generate many facets, use Geomview's <tt>ginsu</tt> +module to view the interior</p> + +<p>To view multiple 4-d dimensions at once, output the object +without 'GDn' and read it with Geomview's <tt>ndview</tt>. As you +rotate the object in one set of dimensions, you can see how it +changes in other sets of dimensions.</p> + +<p>For additional control over 4-d objects, output the object +without 'GDn' and read it with Geomview's <tt>4dview</tt>. You +can slice the object along any 4-d plane. You can also flip the +halfspace that's deleted when slicing. By combining these +features, you can get some interesting cross sections.</p> + +<h3><a href="#geomview">»</a><a name="Gh">Gh - display +hyperplane intersections (3-d, 4-d)</a></h3> + +<p>In 3-d, the intersection is a black line. It lies on two +neighboring hyperplanes, c.f., the blue squares associated with +centrums ('<a href="#Gc">Gc </a>'). In 4-d, the ridges are +projected to the intersection of both hyperplanes. If you turn on +edges (Geomview's 'appearances' menu), each triangle corresponds +to one ridge. The ridges may overlap each other.</p> + +<h3><a href="#geomview">»</a><a name="Gi">Gi - display inner +planes only (2-d, 3-d)</a></h3> + +<p>The inner plane of a facet is below all of its vertices. It is +parallel to the facet's hyperplane. The inner plane's color is +the opposite of the outer plane's color, i.e., <i>[1-r,1-g,1-b] </i>. +Its edges are determined by the vertices.</p> + +<h3><a href="#geomview">»</a><a name="Gn">Gn - do not display +planes </a></h3> + +<p>By default, Geomview displays the precise plane (no merging) +or both inner and output planes (if merging). If merging, +Geomview does not display the inner plane if the the difference +between inner and outer is too small.</p> + +<h3><a href="#geomview">»</a><a name="Go">Go - display outer +planes only (2-d, 3-d)</a></h3> + +<p>The outer plane of a facet is above all input points. It is +parallel to the facet's hyperplane. Its color is determined by +the facet's normal, and its edges are determined by the vertices.</p> + +<h3><a href="#geomview">»</a><a name="Gp">Gp - display coplanar +points and vertices as radii </a></h3> + +<p>Coplanar points ('<a href="qh-optq.htm#Qc">Qc</a>'), interior +points ('<a href="qh-optq.htm#Qi">Qi</a>'), outside points ('<a +href="qh-optt.htm#TCn">TCn</a>' or '<a href="qh-optt.htm#TVn">TVn</a>'), +and vertices are displayed as red and yellow radii. The radii are +perpendicular to the corresponding facet. Vertices are aligned +with an interior point. The radii define a ball which corresponds +to the imprecision of the point. The imprecision is the maximum +of the roundoff error, the centrum radius, and <i>maxcoord * (1 - +</i><a href="qh-optc.htm#An"><i>A-n</i></a><i>)</i>. It is at +least 1/20'th of the maximum coordinate, and ignores post merging +if pre-merging is done.</p> + +<p>If '<a href="qh-optg.htm#Gv">Gv</a>' (print vertices as +spheres) is also selected, option 'Gp' displays coplanar +points as radii. Select options <a href="qh-optq.htm#Qc">Qc</a>' +and/or '<a href="qh-optq.htm#Qi">Qi</a>'. Options 'Qc Gpv' displays +coplanar points while 'Qci Gpv' displays coplanar and interior +points. Option 'Qc' is automatically selected if 'Qi' is not +selected with options 'Gpv'. + +<h3><a href="#geomview">»</a><a name="Gr">Gr - display ridges +(3-d) </a></h3> + +<p>A ridge connects the two vertices that are shared by +neighboring facets. It is displayed in green. A ridge is the +topological edge between two facets while the hyperplane +intersection is the geometric edge between two facets. Ridges are +always displayed in 4-d.</p> + +<h3><a href="#geomview">»</a><a name="Gt">Gt - transparent 3-d +Delaunay </a></h3> + +<p>A 3-d Delaunay triangulation looks like a convex hull with +interior facets. Option 'Gt' removes the outside ridges to reveal +the outermost facets. It automatically sets options '<a +href="#Gr">Gr</a>' and '<a href="#GDn">GDn</a>'. See example <a +href="qh-eg.htm#17f">eg.17f.delaunay.3</a>.</p> + +<h3><a href="#geomview">»</a><a name="Gv">Gv - display vertices +as spheres (2-d, 3-d)</a></h3> + +<p>The radius of the sphere corresponds to the imprecision of the +data. See '<a href="#Gp">Gp</a>' for determining the radius.</p> + +<!-- Navigation links --> + +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> +<!-- GC common information --> + +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="qh--geom.gif" +align="middle" width="40" height="40"></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: Sept. 25, 1995 --- <!-- hhmts start --> Last modified: see top <!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/qh-opto.htm b/xs/src/qhull/html/qh-opto.htm new file mode 100644 index 000000000..e7b21745c --- /dev/null +++ b/xs/src/qhull/html/qh-opto.htm @@ -0,0 +1,353 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<title>Qhull output options</title> +</head> + +<body> +<!-- Navigation links --> +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> + +<hr> +<!-- Main text of document --> +<h1><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/delaunay.html"><img +src="qh--dt.gif" alt="[delaunay]" align="middle" width="100" +height="100"></a> Qhull output options</h1> + +<p>This section lists the output options for Qhull. These options +are indicated by lower case characters. See <a +href="qh-optf.htm#format">Formats</a>, <a +href="qh-optp.htm#print">Print</a>, and <a +href="qh-optg.htm#geomview">Geomview</a> for other output +options. </p> + +<p><b>Copyright © 1995-2015 C.B. Barber</b></p> + +<hr> + +<p><a href="index.htm#TOC">»</a> <a href="qh-quick.htm#programs">Programs</a> +<a name="output">•</a> <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> + +<h2>Output options</h2> + +<p>Qhull prints its output to standard out. All output is printed +text. The default output is a summary (option '<a href="#s">s</a>'). +Other outputs may be specified as follows. </p> + +<dl compact> + <dt><a href="#f">f</a></dt> + <dd>print all fields of all facets</dd> + <dt><a href="#n">n</a></dt> + <dd>print hyperplane normals with offsets</dd> + <dt><a href="#m">m</a></dt> + <dd>print Mathematica output (2-d and 3-d)</dd> + <dt><a href="#o">o</a></dt> + <dd>print OFF file format (dim, points and facets)</dd> + <dt><a href="#s">s</a></dt> + <dd>print summary to stderr</dd> + <dt><a href="#p">p</a></dt> + <dd>print vertex and point coordinates</dd> + <dt><a href="#i">i</a></dt> + <dd>print vertices incident to each facet </dd> + <dt> </dt> + <dt> </dt> + <dd><b>Related options</b></dd> + <dt><a href="qh-optf.htm#format">F</a></dt> + <dd>additional input/output formats</dd> + <dt><a href="qh-optg.htm#geomview">G</a></dt> + <dd>Geomview output</dd> + <dt><a href="qh-optp.htm#print">P</a></dt> + <dd>Print options</dd> + <dt><a href="qh-optf.htm#Ft">Ft</a></dt> + <dd>print triangulation with added points</dd> + <dt> </dt> +</dl> + +<hr> + +<h3><a href="#output">»</a><a name="f">f - print all fields of +all facets </a></h3> + +<p>Print <a href=../src/libqhull.h#facetT>all fields</a> of all facets. +The facet is the primary <a href=index.htm#structure>data structure</a> for +Qhull. + +<p>Option 'f' is for +debugging. Most of the fields are available via the '<a +href="qh-optf.htm#format">F</a>' options. If you need specialized +information from Qhull, you can use the <a +href="qh-code.htm#library">Qhull library</a> or <a +href="qh-code.htm#cpp">C++ interface</a>.</p> + +<p>Use the '<a href="qh-optf.htm#FF">FF</a>' option to print the +facets but not the ridges. </p> + +<h3><a href="#output">»</a><a name="i">i - print vertices +incident to each facet </a></h3> + +<p>The first line is the number of facets. The remaining lines +list the vertices for each facet, one facet per line. The indices +are 0-relative indices of the corresponding input points. The +facets are oriented. Option '<a href="qh-optf.htm#Fv">Fv</a>' +displays an unoriented list of vertices with a vertex count per +line. Options '<a href="qh-opto.htm#o">o</a>' and '<a +href="qh-optf.htm#Ft">Ft</a>' displays coordinates for each +vertex prior to the vertices for each facet. </p> + +<p>Simplicial facets (e.g., triangles in 3-d) consist of <i>d</i> +vertices. Non-simplicial facets in 3-d consist of 4 or more +vertices. For example, a facet of a cube consists of 4 vertices. +Use option '<a href="qh-optq.htm#Qt">Qt</a>' to triangulate non-simplicial facets.</p> + +<p>For 4-d and higher convex hulls and 3-d and higher Delaunay +triangulations, <i>d</i> vertices are listed for all facets. A +non-simplicial facet is triangulated with its centrum and each +ridge. The index of the centrum is higher than any input point. +Use option '<a href="qh-optf.htm#Fv">Fv</a>' to list the vertices +of non-simplicial facets as is. Use option '<a +href="qh-optf.htm#Ft">Ft</a>' to print the coordinates of the +centrums as well as those of the input points. </p> + +<h3><a href="#output">»</a><a name="m">m - print Mathematica +output </a></h3> + +<p>Qhull writes a Mathematica file for 2-d and 3-d convex hulls, +2-d and 3-d halfspace intersections, +and 2-d Delaunay triangulations. Qhull produces a list of +objects that you can assign to a variable in Mathematica, for +example: "<tt>list= << <outputfilename> </tt>". +If the object is 2-d, it can be visualized by "<tt>Show[Graphics[list]] +</tt>". For 3-d objects the command is "<tt>Show[Graphics3D[list]] +</tt>". Now the object can be manipulated by commands of the +form <tt>"Show[%, <parametername> -> +<newvalue>]</tt>". </p> + +<p>For Delaunay triangulation orthogonal projection is better. +This can be specified, for example, by "<tt>BoxRatios: +Show[%, BoxRatios -> {1, 1, 1e-8}]</tt>". To see the +meaningful side of the 3-d object used to visualize 2-d Delaunay, +you need to change the viewpoint: "<tt>Show[%, ViewPoint +-> {0, 0, -1}]</tt>". By specifying different viewpoints +you can slowly rotate objects. </p> + +<p>For halfspace intersections, Qhull produces the dual +convex hull. + +<p>See <a href="qh-faq.htm#math">Is Qhull available for Mathematica?</a> +for URLs. + +<h3><a href="#output">»</a><a name="n">n - print hyperplane +normals with offsets </a></h3> + +<p>The first line is the dimension plus one. The second line is +the number of facets. The remaining lines are the normals for +each facet, one normal per line. The facet's offset follows its +normal coefficients.</p> + +<p>The normals point outward, i.e., the convex hull satisfies <i>Ax +<= -b </i>where <i>A</i> is the matrix of coefficients and <i>b</i> +is the vector of offsets.</p> + +<p>A point is <i>inside</i> or <i>below</i> a hyperplane if its distance +to the hyperplane is negative. A point is <i>outside</i> or <i>above</i> a hyperplane +if its distance to the hyperplane is positive. Otherwise a point is <i>on</i> or +<i>coplanar to</i> the hyperplane. + +<p>If cdd output is specified ('<a href="qh-optf.htm#FD">FD</a>'), +Qhull prints the command line, the keyword "begin", the +number of facets, the dimension (plus one), the keyword +"real", and the normals for each facet. The facet's +negative offset precedes its normal coefficients (i.e., if the +origin is an interior point, the offset is positive). Qhull ends +the output with the keyword "end". </p> + +<h3><a href="#output">»</a><a name="o">o - print OFF file format +</a></h3> + +<p>The output is: </p> + +<ul> + <li>The first line is the dimension </li> + <li>The second line is the number of points, the number of + facets, and the number of ridges. </li> + <li>All of the input points follow, one per line. </li> + <li>Then Qhull prints the vertices for each facet. Each facet + is on a separate line. The first number is the number of + vertices. The remainder is the indices of the + corresponding points. The vertices are oriented in 2-d, + 3-d, and in simplicial facets. </li> +</ul> + +<p>Option '<a href="qh-optf.htm#Ft">Ft</a>' prints the same +information with added points for non-simplicial facets.</p> + +<p>Option '<a href="qh-opto.htm#i">i</a>' displays vertices +without the point coordinates. Option '<a href="qh-opto.htm#p">p</a>' +displays the point coordinates without vertex and facet information.</p> + +<p>In 3-d, Geomview can load the file directly if you delete the +first line (e.g., by piping through '<tt>tail +2</tt>').</p> + +<p>For Voronoi diagrams (<a href=qvoronoi.htm>qvoronoi</a>), option +'o' prints Voronoi vertices and Voronoi regions instead of input +points and facets. The first vertex is the infinity vertex +[-10.101, -10.101, ...]. Then, option 'o' lists the vertices in +the Voronoi region for each input site. The regions appear in +site ID order. In 2-d, the vertices of a Voronoi region are +sorted by adjacency (non-oriented). In 3-d and higher, the +Voronoi vertices are sorted by index. See the '<a +href="qh-optf.htm#FN">FN</a>' option for listing Voronoi regions +without listing Voronoi vertices.</p> + +<p>If you are using the Qhull library, options 'v o' have the +side effect of reordering the neighbors for a vertex.</p> + +<h3><a href="#output">»</a><a name="p">p - print vertex and +point coordinates </a></h3> + +<p>The first line is the dimension. The second line is the number +of vertices. The remaining lines are the vertices, one vertex per +line. A vertex consists of its point coordinates</p> + +<p>With the '<a href="qh-optg.htm#Gc">Gc</a>' and '<a +href="qh-optg.htm#Gi">Gi</a>' options, option 'p' also prints +coplanar and interior points respectively.</p> + +<p>For <a href=qvoronoi.htm>qvoronoi</a>, it prints the +coordinates of each Voronoi vertex.</p> + +<p>For <a href=qdelaun.htm>qdelaunay</a>, it prints the +input sites as lifted to a paraboloid. For <a href=qhalf.htm>qhalf</a> +it prints the dual points. For both, option 'p' is the same as the first +section of option '<a href="qh-opto.htm#o">o</a>'.</p> + +<p>Use '<a href="qh-optf.htm#Fx">Fx</a>' to list the point ids of +the extreme points (i.e., vertices). </p> + +<p>If a subset of the facets is selected ('<a +href="qh-optp.htm#Pdk">Pdk</a>', '<a href="qh-optp.htm#PDk">PDk</a>', +'<a href="qh-optp.htm#Pg">Pg</a>' options), option 'p' only +prints vertices and points associated with those facets.</p> + +<p>If cdd-output format is selected ('<a href="qh-optf.htm#FD">FD</a>'), +the first line is "begin". The second line is the +number of vertices, the dimension plus one, and "real". +The vertices follow with a leading "1". Output ends +with "end". </p> + +<h3><a href="#output">»</a><a name="s">s - print summary to +stderr </a></h3> + +<p>The default output of Qhull is a summary to stderr. Options '<a +href="qh-optf.htm#FS">FS</a>' and '<a href="qh-optf.htm#Fs">Fs</a>' +produce the same information for programs. <b>Note</b>: Windows 95 and 98 +treats stderr the same as stdout. Use option '<a href="qh-optt.htm#TO">TO file</a>' to separate +stderr and stdout.</p> + +<p>The summary lists the number of input points, the dimension, +the number of vertices in the convex hull, and the number of +facets in the convex hull. It lists the number of selected +("good") facets for options '<a href="qh-optp.htm#Pg">Pg</a>', +'<a href="qh-optp.htm#Pdk">Pdk</a>', <a href=qdelaun.htm>qdelaunay</a>, +or <a href=qvoronoi.htm>qvoronoi</a> (Delaunay triangulations only +use the lower half of a convex hull). It lists the number of +coplanar points. For Delaunay triangulations without '<a +href="qh-optq.htm#Qc">Qc</a>', it lists the total number of +coplanar points. It lists the number of simplicial facets in +the output.</p> + +<p>The terminology depends on the output structure. </p> + +<p>The summary lists these statistics:</p> + +<ul> + <li>number of points processed by Qhull </li> + <li>number of hyperplanes created</li> + <li>number of distance tests (not counting statistics, + summary, and checking) </li> + <li>number of merged facets (if any)</li> + <li>number of distance tests for merging (if any)</li> + <li>CPU seconds to compute the hull</li> + <li>the maximum joggle for '<a href="qh-optq.htm#QJn">QJ</a>'<br> + or, the probability of precision errors for '<a + href="qh-optq.htm#QJn">QJ</a> <a href="qh-optt.htm#TRn">TRn</a>' + </li> + <li>total area and volume (if computed, see '<a + href="qh-optf.htm#FS">FS</a>' '<a href="qh-optf.htm#FA">FA</a>' + '<a href="qh-optf.htm#Fa">Fa</a>' '<a + href="qh-optp.htm#PAn">PAn</a>')</li> + <li>max. distance of a point above a facet (if non-zero)</li> + <li>max. distance of a vertex below a facet (if non-zero)</li> +</ul> + +<p>The statistics include intermediate hulls. For example 'rbox d +D4 | qhull' reports merged facets even though the final hull is +simplicial. </p> + +<p>Qhull starts counting CPU seconds after it has read and +projected the input points. It stops counting before producing +output. In the code, CPU seconds measures the execution time of +function qhull() in <tt>libqhull.c</tt>. If the number of CPU +seconds is clearly wrong, check qh_SECticks in <tt>user.h</tt>. </p> + +<p>The last two figures measure the maximum distance from a point +or vertex to a facet. They are not printed if less than roundoff +or if not merging. They account for roundoff error in computing +the distance (c.f., option '<a href="qh-optc.htm#Rn">Rn</a>'). +Use '<a href="qh-optf.htm#Fs">Fs</a>' to report the maximum outer +and inner plane. </p> + +<p>A number may appear in parentheses after the maximum distance +(e.g., 2.1x). It is the ratio between the maximum distance and +the worst-case distance due to merging two simplicial facets. It +should be small for 2-d, 3-d, and 4-d, and for higher dimensions +with '<a href="qh-optq.htm#Qx">Qx</a>'. It is not printed if less +than 0.05. </p> +<!-- Navigation links --> +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> +<!-- GC common information --> +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="qh--geom.gif" +align="middle" width="40" height="40"></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: Sept. 25, 1995 --- <!-- hhmts start --> Last modified: see top <!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/qh-optp.htm b/xs/src/qhull/html/qh-optp.htm new file mode 100644 index 000000000..9c6df90f5 --- /dev/null +++ b/xs/src/qhull/html/qh-optp.htm @@ -0,0 +1,253 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<title>Qhull print options (P)</title> +</head> + +<body> +<!-- Navigation links --> +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> + +<hr> +<!-- Main text of document --> +<h1><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/delaunay.html"><img +src="qh--dt.gif" alt="[delaunay]" align="middle" width="100" +height="100"></a> Qhull print options (P)</h1> + +This section lists the print options for Qhull. These options are +indicated by 'P' followed by a letter. See +<a href="qh-opto.htm#output">Output</a>, <a href="qh-optg.htm#geomview">Geomview</a>, +and <a href="qh-optf.htm#format">Format</a> for other output options. + + +<p><b>Copyright © 1995-2015 C.B. Barber</b></p> + +<hr> + +<p><a href="index.htm#TOC">»</a> <a href="qh-quick.htm#programs">Programs</a> +<a name="format">•</a> <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> + +<h2>Print options</h2> +<blockquote> +<dl compact> + <dt> </dt> + <dd><b>General</b></dd> + <dt><a href="#Pp">Pp</a></dt> + <dd>do not report precision problems </dd> + <dt><a href="#Po">Po</a></dt> + <dd>force output despite precision problems</dd> + <dt><a href="#Po2">Po</a></dt> + <dd>if error, output neighborhood of facet</dd> + <dt> </dt> + <dt> </dt> + <dd><b>Select</b></dd> + <dt><a href="#Pdk">Pdk:n</a></dt> + <dd>print facets with normal[k] >= n (default 0.0)</dd> + <dt><a href="#PDk">PDk:n</a></dt> + <dd>print facets with normal[k] <= n </dd> + <dt><a href="#PFn">PFn</a></dt> + <dd>print facets whose area is at least n</dd> + <dt><a href="#Pg">Pg</a></dt> + <dd>print good facets only (needs '<a href="qh-optq.htm#QGn">QGn</a>' + or '<a href="qh-optq.htm#QVn">QVn </a>')</dd> + <dt><a href="#PMn">PMn</a></dt> + <dd>print n facets with most merges</dd> + <dt><a href="#PAn">PAn</a></dt> + <dd>print n largest facets by area</dd> + <dt><a href="#PG">PG</a></dt> + <dd>print neighbors of good facets</dd> +</dl> +</blockquote> +<hr> + +<h3><a href="#print">»</a><a name="PAn">PAn - keep n largest +facets by area</a></h3> + +<p>The <i>n</i> largest facets are marked good for printing. This +may be useful for <a href="qh-impre.htm#approximate">approximating +a hull</a>. Unless '<a href="#PG">PG</a>' is set, '<a href="#Pg">Pg</a>' +is automatically set. </p> + +<h3><a href="#print">»</a><a name="Pdk">Pdk:n - print facet if +normal[k] >= n </a></h3> + +<p>For a given output, print only those facets with <i>normal[k] >= n</i> +and <i>drop</i> the others. For example, 'Pd0:0.5' prints facets with <i>normal[0] +>= 0.5 </i>. The default value of <i>n</i> is zero. For +example in 3-d, 'Pd0d1d2' prints facets in the positive octant. +<p> +If no facets match, the closest facet is returned.</p> +<p> +On Windows 95, do not combine multiple options. A 'd' is considered +part of a number. For example, use 'Pd0:0.5 Pd1:0.5' instead of +'Pd0:0.5d1:0.5'. + +<h3><a href="#print">»</a><a name="PDk">PDk:n - print facet if +normal[k] <= n</a></h3> + +<p>For a given output, print only those facets with <i>normal[k] <= n</i> +and <i>drop</i> the others. +For example, 'PD0:0.5' prints facets with <i>normal[0] +<= 0.5 </i>. The default value of <i>n</i> is zero. For +example in 3-d, 'PD0D1D2' displays facets in the negative octant. +<p> +If no facets match, the closest facet is returned.</p> + +<p>In 2-d, 'd G PD2' displays the Delaunay triangulation instead +of the corresponding paraboloid. </p> + +<p>Be careful of placing 'Dk' or 'dk' immediately after a real +number. Some compilers treat the 'D' as a double precision +exponent. </p> + +<h3><a href="#print">»</a><a name="PFn">PFn - keep facets whose +area is at least n</a></h3> + +<p>The facets with area at least <i>n</i> are marked good for +printing. This may be useful for <a +href="qh-impre.htm#approximate">approximating a hull</a>. Unless +'<a href="#PG">PG</a>' is set, '<a href="#Pg">Pg</a>' is +automatically set. </p> + +<h3><a href="#print">»</a><a name="Pg">Pg - print good facets </a></h3> + +<p>Qhull can mark facets as "good". This is used to</p> + +<ul> + <li>mark the lower convex hull for Delaunay triangulations + and Voronoi diagrams</li> + <li>mark the facets that are visible from a point (the '<a + href="qh-optq.htm#QGn">QGn </a>' option)</li> + <li>mark the facets that contain a point (the '<a + href="qh-optq.htm#QVn">QVn</a>' option).</li> + <li>indicate facets with a large enough area (options '<a + href="#PAn">PAn</a>' and '<a href="#PFn">PFn</a>')</li> +</ul> + +<p>Option '<a href="#Pg">Pg</a>' only prints good facets that +also meet '<a href="#Pdk">Pdk</a>' and '<a href="#PDk">PDk</a>' +options. It is automatically set for options '<a href="#PAn">PAn</a>', +'<a href="#PFn">PFn </a>', '<a href="qh-optq.htm#QGn">QGn</a>', +and '<a href="qh-optq.htm#QVn">QVn</a>'.</p> + +<h3><a href="#print">»</a><a name="PG">PG - print neighbors of +good facets</a></h3> + +<p>Option 'PG' can be used with or without option '<a href="#Pg">Pg</a>' +to print the neighbors of good facets. For example, options '<a +href="qh-optq.htm#QGn">QGn</a>' and '<a href="qh-optq.htm#QVn">QVn</a>' +print the horizon facets for point <i>n. </i></p> + +<h3><a href="#print">»</a><a name="PMn">PMn - keep n facets with +most merges</a></h3> + +<p>The n facets with the most merges are marked good for +printing. This may be useful for <a +href="qh-impre.htm#approximate">approximating a hull</a>. Unless +'<a href="#PG">PG</a>' is set, '<a href="#Pg">Pg</a>' is +automatically set. </p> + +<p>Use option '<a href="qh-optf.htm#Fm">Fm</a>' to print merges +per facet. + +<h3><a href="#print">»</a><a name="Po">Po - force output despite +precision problems</a></h3> + +<p>Use options 'Po' and '<a href="qh-optq.htm#Q0">Q0</a>' if you +can not merge facets, triangulate the output ('<a href="qh-optq.htm#Qt">Qt</a>'), +or joggle the input (<a href="qh-optq.htm#QJn">QJ</a>). + +<p>Option 'Po' can not force output when +duplicate ridges or duplicate facets occur. It may produce +erroneous results. For these reasons, merged facets, joggled input, or <a +href="qh-impre.htm#exact">exact arithmetic</a> are better.</p> + +<p>If you need a simplicial Delaunay triangulation, use +joggled input '<a href="qh-optq.htm#QJn">QJ</a>' or triangulated +output '<a +href="qh-optf.htm#Ft">Ft</a>'. + +<p>Option 'Po' may be used without '<a href="qh-optq.htm#Q0">Q0</a>' +to remove some steps from Qhull or to output the neighborhood of +an error.</p> + +<p>Option 'Po' may be used with option '<a href="qh-optq.htm#Q5">Q5</a>') +to skip qh_check_maxout (i.e., do not determine the maximum outside distance). +This can save a significant amount of time. + +<p>If option 'Po' is used,</p> + +<ul> + <li>most precision errors allow Qhull to continue. </li> + <li>verify ('<a href="qh-optt.htm#Tv">Tv</a>') does not check + coplanar points.</li> + <li>points are not partitioned into flipped facets and a + flipped facet is always visible to a point. This may + delete flipped facets from the output. </li> +</ul> + +<h3><a href="#print">»</a><a name="Po2">Po - if error, output +neighborhood of facet</a></h3> + +<p>If an error occurs before the completion of Qhull and tracing +is not active, 'Po' outputs a neighborhood of the erroneous +facets (if any). It uses the current output options.</p> + +<p>See '<a href="qh-optp.htm#Po">Po</a>' - force output despite +precision problems. + +<h3><a href="#print">»</a><a name="Pp">Pp - do not report +precision problems </a></h3> + +<p>With option 'Pp', Qhull does not print statistics about +precision problems, and it removes some of the warnings. It +removes the narrow hull warning.</p> + +<!-- Navigation links --> +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> +<!-- GC common information --> +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="qh--geom.gif" +align="middle" width="40" height="40"></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: Sept. 25, 1995 --- <!-- hhmts start --> Last modified: see top <!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/qh-optq.htm b/xs/src/qhull/html/qh-optq.htm new file mode 100644 index 000000000..2edbb1fd4 --- /dev/null +++ b/xs/src/qhull/html/qh-optq.htm @@ -0,0 +1,731 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<title>Qhull control options (Q)</title> +</head> + +<body> +<!-- Navigation links --> +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> + +<hr> +<!-- Main text of document --> +<h1><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/delaunay.html"><img +src="qh--dt.gif" alt="[delaunay]" align="middle" width="100" +height="100"></a> Qhull control options (Q)</h1> + +<p>This section lists the control options for Qhull. These +options are indicated by 'Q' followed by a letter. </p> + +<p><b>Copyright © 1995-2015 C.B. Barber</b></p> + +<hr> + +<p><a href="index.htm#TOC">»</a> <a href="qh-quick.htm#programs">Programs</a> +<a name="qhull">•</a> <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> + +<h2>Qhull control options</h2> + +<dl compact> + <dt> </dt> + <dd><b>General</b></dd> + <dt><a href="#Qu">Qu</a></dt> + <dd>compute upper hull for furthest-site Delaunay + triangulation </dd> + <dt><a href="#Qc">Qc</a></dt> + <dd>keep coplanar points with nearest facet</dd> + <dt><a href="#Qi">Qi</a></dt> + <dd>keep interior points with nearest facet</dd> + <dt><a href="#QJn">QJ</a></dt> + <dd>joggled input to avoid precision problems</dd> + <dt><a href="#Qt">Qt</a></dt> + <dd>triangulated output</dd> + <dt> </dt> + <dt> </dt> + <dd><b>Precision handling</b></dd> + <dt><a href="#Qz">Qz</a></dt> + <dd>add a point-at-infinity for Delaunay triangulations</dd> + <dt><a href="#Qx">Qx</a></dt> + <dd>exact pre-merges (allows coplanar facets)</dd> + <dt><a href="#Qs">Qs</a></dt> + <dd>search all points for the initial simplex</dd> + <dt><a href="#Qbb">Qbb</a></dt> + <dd>scale last coordinate to [0,m] for Delaunay</dd> + <dt><a href="#Qv">Qv</a></dt> + <dd>test vertex neighbors for convexity</dd> + <dt> </dt> + <dt> </dt> + <dd><b>Transform input</b></dd> + <dt><a href="#Qb0">Qbk:0Bk:0</a></dt> + <dd>drop dimension k from input</dd> + <dt><a href="#QRn">QRn</a></dt> + <dd>random rotation (n=seed, n=0 time, n=-1 time/no rotate)</dd> + <dt><a href="#Qbk">Qbk:n</a></dt> + <dd>scale coord[k] to low bound of n (default -0.5)</dd> + <dt><a href="#QBk">QBk:n</a></dt> + <dd>scale coord[k] to upper bound of n (default 0.5)</dd> + <dt><a href="#QbB">QbB</a></dt> + <dd>scale input to fit the unit cube</dd> + <dt> </dt> + <dt> </dt> + <dd><b>Select facets</b></dd> + <dt><a href="#QVn">QVn</a></dt> + <dd>good facet if it includes point n, -n if not</dd> + <dt><a href="#QGn">QGn</a></dt> + <dd>good facet if visible from point n, -n for not visible</dd> + <dt><a href="#Qg">Qg</a></dt> + <dd>only build good facets (needs '<a href="#QGn">QGn</a>', '<a + href="#QVn">QVn </a>', or '<a href="qh-optp.htm#Pdk">Pdk</a>')</dd> + <dt> </dt> + <dt> </dt> + <dd><b>Experimental</b></dd> + <dt><a href="#Q4">Q4</a></dt> + <dd>avoid merging old facets into new facets</dd> + <dt><a href="#Q5">Q5</a></dt> + <dd>do not correct outer planes at end of qhull</dd> + <dt><a href="#Q3">Q3</a></dt> + <dd>do not merge redundant vertices</dd> + <dt><a href="#Q6">Q6</a></dt> + <dd>do not pre-merge concave or coplanar facets</dd> + <dt><a href="#Q0">Q0</a></dt> + <dd>do not pre-merge facets with 'C-0' or 'Qx'</dd> + <dt><a href="#Q8">Q8</a></dt> + <dd>ignore near-interior points</dd> + <dt><a href="#Q2">Q2</a></dt> + <dd>merge all non-convex at once instead of independent sets</dd> + <dt><a href="#Qf">Qf</a></dt> + <dd>partition point to furthest outside facet</dd> + <dt><a href="#Q7">Q7</a></dt> + <dd>process facets depth-first instead of breadth-first</dd> + <dt><a href="#Q9">Q9</a></dt> + <dd>process furthest of furthest points</dd> + <dt><a href="#Q10">Q10</a></dt> + <dd>no special processing for narrow distributions</dd> + <dt><a href="#Q11">Q11</a></dt> + <dd>copy normals and recompute centrums for tricoplanar facets</dd> + <dt><a href="#Q12">Q12</a></dt> + <dd>do not error on wide merge due to duplicate ridge and nearly coincident points</dd> + <dt><a href="#Qm">Qm</a></dt> + <dd>process points only if they would increase the max. outer + plane </dd> + <dt><a href="#Qr">Qr</a></dt> + <dd>process random outside points instead of furthest one</dd> + <dt><a href="#Q1">Q1</a></dt> + <dd>sort merges by type instead of angle</dd> +</dl> + +<hr> + +<h3><a href="#qhull">»</a><a name="Qbb">Qbb - scale the last +coordinate to [0,m] for Delaunay</a></h3> + +<p>After scaling with option 'Qbb', the lower bound of the last +coordinate will be 0 and the upper bound will be the maximum +width of the other coordinates. Scaling happens after projecting +the points to a paraboloid and scaling other coordinates. </p> + +<p>Option 'Qbb' is automatically set for <a href=qdelaun.htm>qdelaunay</a> +and <a href=qvoronoi.htm>qvoronoi</a>. Option 'Qbb' is automatically set for joggled input '<a +href="qh-optq.htm#QJn">QJ</a>'. </p> + +<p>Option 'Qbb' should be used for Delaunay triangulations with +integer coordinates. Since the last coordinate is the sum of +squares, it may be much larger than the other coordinates. For +example, <tt>rbox 10000 D2 B1e8 | qhull d</tt> has precision +problems while <tt>rbox 10000 D2 B1e8 | qhull d Qbb</tt> is OK. </p> + +<h3><a href="#qhull">»</a><a name="QbB">QbB - scale the input to +fit the unit cube</a></h3> + +<p>After scaling with option 'QbB', the lower bound will be -0.5 +and the upper bound +0.5 in all dimensions. For different bounds +change qh_DEFAULTbox in <tt>user.h</tt> (0.5 is best for <a +href="index.htm#geomview">Geomview</a>).</p> + +<p>For Delaunay and Voronoi diagrams, scaling happens after +projection to the paraboloid. Under precise arithmetic, scaling +does not change the topology of the convex hull. Scaling may +reduce precision errors if coordinate values vary widely.</p> + +<h3><a href="#qhull">»</a><a name="Qbk">Qbk:n - scale coord[k] +to low bound</a></h3> + +<p>After scaling, the lower bound for dimension k of the input +points will be n. 'Qbk' scales coord[k] to -0.5. </p> + +<h3><a href="#qhull">»</a><a name="QBk">QBk:n - scale coord[k] +to upper bound </a></h3> + +<p>After scaling, the upper bound for dimension k of the input +points will be n. 'QBk' scales coord[k] to 0.5. </p> + +<h3><a href="#qhull">»</a><a name="Qb0">Qbk:0Bk:0 - drop +dimension k from the input points</a></h3> + +<p>Drop dimension<em> k </em>from the input points. For example, +'Qb1:0B1:0' deletes the y-coordinate from all input points. This +allows the user to take convex hulls of sub-dimensional objects. +It happens before the Delaunay and Voronoi transformation. +It happens after the halfspace transformation for both the data +and the feasible point.</p> + +<h3><a href="#qhull">»</a><a name="Qc">Qc - keep coplanar points +with nearest facet </a></h3> + +<p>During construction of the hull, a point is coplanar if it is +between '<a href="qh-optc.htm#Wn">Wn</a>' above and '<a +href="qh-optc.htm#Un">Un</a>' below a facet's hyperplane. A +different definition is used for output from Qhull. </p> + +<p>For output, a coplanar point is above the minimum vertex +(i.e., above the inner plane). With joggle ('<a +href="qh-optq.htm#QJn">QJ</a>'), a coplanar point includes points +within one joggle of the inner plane. </p> + +<p>With option 'Qc', output formats '<a href="qh-opto.htm#p">p </a>', +'<a href="qh-opto.htm#f">f</a>', '<a href="qh-optg.htm#Gp">Gp</a>', +'<a href="qh-optf.htm#Fc">Fc</a>', '<a href="qh-optf.htm#FN">FN</a>', +and '<a href="qh-optf.htm#FP">FP</a>' will print the coplanar +points. With options 'Qc <a href="#Qi">Qi</a>' these outputs +include the interior points.</p> + +<p>For Delaunay triangulations (<a href=qdelaun.htm>qdelaunay</a> +or <a href=qvoronoi.htm>qvoronoi</a>), a coplanar point is a point +that is nearly incident to a vertex. All input points are either +vertices of the triangulation or coplanar.</p> + +<p>Qhull stores coplanar points with a facet. While constructing +the hull, it retains all points within qh_RATIOnearInside +(user.h) of a facet. In qh_check_maxout(), it uses these points +to determine the outer plane for each facet. With option 'Qc', +qh_check_maxout() retains points above the minimum vertex for the +hull. Other points are removed. If qh_RATIOnearInside is wrong or +if options '<a href="#Q5">Q5</a> <a href="#Q8">Q8</a>' are set, a +coplanar point may be missed in the output (see <a +href="qh-impre.htm#limit">Qhull limitations</a>).</p> + +<h3><a href="#qhull">»</a><a name="Qf">Qf - partition point to +furthest outside facet </a></h3> + +<p>After adding a new point to the convex hull, Qhull partitions +the outside points and coplanar points of the old, visible +facets. Without the '<a href="qh-opto.htm#f">f </a>' option and +merging, it assigns a point to the first facet that it is outside +('<a href="qh-optc.htm#Wn">Wn</a>'). When merging, it assigns a +point to the first facet that is more than several times outside +(see qh_DISToutside in user.h).</p> + +<p>If option 'Qf' is selected, Qhull performs a directed search +(no merging) or an exhaustive search (merging) of new facets. +Option 'Qf' may reduce precision errors if pre-merging does not +occur.</p> + +<p>Option '<a href="#Q9">Q9</a>' processes the furthest of all +furthest points.</p> + +<h3><a href="#qhull">»</a><a name="Qg">Qg - only build good +facets (needs 'QGn' 'QVn' or 'Pdk') </a></h3> + +<p>Qhull has several options for defining and printing good +facets. With the '<a href="#Qg">Qg</a>' option, Qhull will only +build those facets that it needs to determine the good facets in +the output. This may speed up Qhull in 2-d and 3-d. It is +useful for furthest-site Delaunay +triangulations (<a href=qdelau_f.htm>qdelaunay Qu</a>, +invoke with 'qhull d Qbb <a href="#Qu">Qu</a> Qg'). +It is not effective in higher +dimensions because many facets see a given point and contain a +given vertex. It is not guaranteed to work for all combinations.</p> + +<p>See '<a href="#QGn">QGn</a>', '<a href="#QVn">QVn</a>', and '<a +href="qh-optp.htm#Pdk">Pdk</a>' for defining good facets, and '<a +href="qh-optp.htm#Pg">Pg</a>' and '<a href="qh-optp.htm#PG">PG</a>' +for printing good facets and their neighbors. If pre-merging ('<a +href="qh-optc.htm#Cn">C-n</a>') is not used and there are +coplanar facets, then 'Qg Pg' may produce a different result than +'<a href="qh-optp.htm#Pg">Pg</a>'. </p> + +<h3><a href="#qhull">»</a><a name="QGn">QGn - good facet if +visible from point n, -n for not visible </a></h3> + +<p>With option 'QGn', a facet is good (see '<a href="#Qg">Qg</a>' +and '<a href="qh-optp.htm#Pg">Pg</a>') if it is visible from +point n. If <i>n < 0</i>, a facet is good if it is not visible +from point n. Point n is not added to the hull (unless '<a +href="qh-optt.htm#TCn">TCn</a>' or '<a href="qh-optt.htm#TPn">TPn</a>').</p> + +<p>With <a href="rbox.htm">rbox</a>, use the 'Pn,m,r' option +to define your point; it will be point 0 ('QG0'). </p> + +<h3><a href="#qhull">»</a><a name="Qi">Qi - keep interior points +with nearest facet </a></h3> + +<p>Normally Qhull ignores points that are clearly interior to the +convex hull. With option 'Qi', Qhull treats interior points the +same as coplanar points. Option 'Qi' does not retain coplanar +points. You will probably want '<a href="#Qc">Qc </a>' as well. </p> + +<p>Option 'Qi' is automatically set for '<a href=qdelaun.htm>qdelaunay</a> +<a href="#Qc">Qc</a>' and '<a href=qvoronoi.htm>qvoronoi</a> +<a href="#Qc">Qc</a>'. If you use +'<a href=qdelaun.htm>qdelaunay</a> Qi' or '<a href=qvoronoi.htm>qvoronoi</a> +Qi', option '<a href="qh-opto.htm#s">s</a>' reports all nearly +incident points while option '<a href="qh-optf.htm#Fs">Fs</a>' +reports the number of interior points (should always be zero).</p> + +<p>With option 'Qi', output formats '<a href="qh-opto.htm#p">p</a>', +'<a href="qh-opto.htm#f">f</a>','<a href="qh-optg.htm#Gp">Gp</a>', +'<a href="qh-optf.htm#Fc">Fc</a>', '<a href="qh-optf.htm#FN">FN</a>', +and '<a href="qh-optf.htm#FP">FP</a>' include interior points. </p> + +<h3><a href="#qhull">»</a><a name="QJ">QJ</a> or <a name="QJn">QJn</a> - joggled +input to avoid precision errors</a></h3> + +<p>Option 'QJ' or 'QJn' joggles each input coordinate by adding a +random number in the range [-n,n]. If a precision error occurs, +It tries again. If precision errors still occur, Qhull increases <i>n</i> +ten-fold and tries again. The maximum value for increasing <i>n</i> +is 0.01 times the maximum width of the input. Option 'QJ' selects +a default value for <i>n</i>. <a href="../src/user.h#JOGGLEdefault">User.h</a> +defines these parameters and a maximum number of retries. See <a +href="qh-impre.htm#joggle">Merged facets or joggled input</a>. </p> + +<p>Users of joggled input should consider converting to +triangulated output ('<a href="../html/qh-optq.htm#Qt">Qt</a>'). Triangulated output is +approximately 1000 times more accurate than joggled input. + +<p>Option 'QJ' also sets '<a href="qh-optq.htm#Qbb">Qbb</a>' for +Delaunay triangulations and Voronoi diagrams. It does not set +'Qbb' if '<a href="qh-optq.htm#Qbk">Qbk:n</a>' or '<a +href="qh-optq.htm#QBk">QBk:n</a>' are set. </p> + +<p>If 'QJn' is set, Qhull does not merge facets unless requested +to. All facets are simplicial (triangular in 2-d). This may be +important for your application. You may also use triangulated output +('<a href="qh-optq.htm#Qt">Qt</a>') or Option '<a href="qh-optf.htm#Ft">Ft</a>'. + +<p>Qhull adjusts the outer and inner planes for 'QJn' ('<a +href="qh-optf.htm#Fs">Fs</a>'). They are increased by <i>sqrt(d)*n</i> +to account for the maximum distance between a joggled point and +the corresponding input point. Coplanar points ('<a +href="qh-optq.htm#Qc">Qc</a>') require an additional <i>sqrt(d)*n</i> +since vertices and coplanar points may be joggled in opposite +directions. </p> + +<p>For Delaunay triangulations (<a href=qdelaun.htm>qdelaunay</a>), joggle +happens before lifting the input sites to a paraboloid. Instead of +'QJ', you may use triangulated output ('<a +href="qh-optq.htm#Qt">Qt</a>')</p> + +<p>This option is deprecated for Voronoi diagrams (<a href=qvoronoi.htm>qvoronoi</a>). +It triangulates cospherical points, leading to duplicated Voronoi vertices.</p> + +<p>By default, 'QJn' uses a fixed random number seed. To use time +as the random number seed, select '<a href="qh-optq.htm#QRn">QR-1</a>'. +The summary ('<a href="qh-opto.htm#s">s</a>') will show the +selected seed as 'QR-n'. + +<p>With 'QJn', Qhull does not error on degenerate hyperplane +computations. Except for Delaunay and Voronoi computations, Qhull +does not error on coplanar points. </p> + +<p>Use option '<a href="qh-optf.htm#FO">FO</a>' to display the +selected options. Option 'FO' displays the joggle and the joggle +seed. If Qhull restarts, it will redisplay the options. </p> + +<p>Use option '<a href="qh-optt.htm#TRn">TRn</a>' to estimate the +probability that Qhull will fail for a given 'QJn'. + +<h3><a href="#qhull">»</a><a name="Qm">Qm - only process points +that increase the maximum outer plane </a></h3> + +<p>Qhull reports the maximum outer plane in its summary ('<a +href="qh-opto.htm#s">s</a>'). With option 'Qm', Qhull does not +process points that are below the current, maximum outer plane. +This is equivalent to always adjusting '<a href="qh-optc.htm#Wn">Wn +</a>' to the maximum distance of a coplanar point to a facet. It +is ignored for points above the upper convex hull of a Delaunay +triangulation. Option 'Qm' is no longer important for merging.</p> + +<h3><a href="#qhull">»</a><a name="Qr">Qr - process random +outside points instead of furthest ones </a></h3> + +<p>Normally, Qhull processes the furthest point of a facet's +outside points. Option 'Qr' instead selects a random outside +point for processing. This makes Qhull equivalent to the +randomized incremental algorithms.</p> + +<p>The original randomization algorithm by Clarkson and Shor [<a +href="index.htm#cla-sho89">'89</a>] used a conflict list which +is equivalent to Qhull's outside set. Later randomized algorithms +retained the previously constructed facets. </p> + +<p>To compare Qhull to the randomized algorithms with option +'Qr', compare "hyperplanes constructed" and +"distance tests". Qhull does not report CPU time +because the randomization is inefficient. </p> + +<h3><a href="#qhull">»</a><a name="QRn">QRn - random rotation </a></h3> + +<p>Option 'QRn' randomly rotates the input. For Delaunay +triangulations (<a href=qdelaun.htm>qdelaunay</a> or <a href=qvoronoi.htm>qvoronoi</a>), +it rotates the lifted points about +the last axis. </p> + +<p>If <em>n=0</em>, use time as the random number seed. If <em>n>0</em>, +use n as the random number seed. If <em>n=-1</em>, don't rotate +but use time as the random number seed. If <em>n<-1</em>, +don't rotate but use <em>n</em> as the random number seed. </p> + +<h3><a href="#qhull">»</a><a name="Qs">Qs - search all points +for the initial simplex </a></h3> + +<p>Qhull constructs an initial simplex from <i>d+1</i> points. It +selects points with the maximum and minimum coordinates and +non-zero determinants. If this fails, it searches all other +points. In 8-d and higher, Qhull selects points with the minimum +x or maximum coordinate (see qh_initialvertices in <tt>poly2.c </tt>). +It rejects points with nearly zero determinants. This should work +for almost all input sets.</p> + +<p>If Qhull can not construct an initial simplex, it reports a +descriptive message. Usually, the point set is degenerate and one +or more dimensions should be removed ('<a href="#Qb0">Qbk:0Bk:0</a>'). +If not, use option 'Qs'. It performs an exhaustive search for the +best initial simplex. This is expensive is high dimensions. </p> + +<h3><a href="#qhull">»</a><a name="Qt">Qt - triangulated output</a></h3> + +<p>By default, qhull merges facets to handle precision errors. This +produces non-simplicial facets (e.g., the convex hull of a cube has 6 square +facets). Each facet is non-simplicial because it has four vertices. + +<p>Use option 'Qt' to triangulate all non-simplicial facets before generating +results. Alternatively, use joggled input ('<a href="#QJn">QJ</a>') to +prevent non-simplical facets. Unless '<a href="qh-optp.htm#Pp">Pp</a>' is set, +qhull produces a warning if 'QJ' and 'Qt' are used together. + +<p>For Delaunay triangulations (<a href=qdelaun.htm>qdelaunay</a>), triangulation +occurs after lifting the input sites to a paraboloid and computing the convex hull. +</p> + +<p>Option 'Qt' is deprecated for Voronoi diagrams (<a href=qvoronoi.htm>qvoronoi</a>). +It triangulates cospherical points, leading to duplicated Voronoi vertices.</p> + +<p>Option 'Qt' may produce degenerate facets with zero area.</p> + +<p>Facet area and hull volumes may differ with and without +'Qt'. The triangulations are different and different triangles +may be ignored due to precision errors. + +<p>With sufficient merging, the ridges of a non-simplicial facet may share more than two neighboring facets. If so, their triangulation ('<a href="#Qt">Qt</a>') will fail since two facets have the same vertex set. </p> + +<h3><a href="#qhull">»</a><a name="Qu">Qu - compute upper hull +for furthest-site Delaunay triangulation </a></h3> + +<p>When computing a Delaunay triangulation (<a href=qdelaun.htm>qdelaunay</a> +or <a href=qvoronoi.htm>qvoronoi</a>), +Qhull computes both the the convex hull of points on a +paraboloid. It normally prints facets of the lower hull. These +correspond to the Delaunay triangulation. With option 'Qu', Qhull +prints facets of the upper hull. These correspond to the <a +href="qdelau_f.htm">furthest-site Delaunay triangulation</a> +and the <a href="qvoron_f.htm">furthest-site Voronoi diagram</a>.</p> + +<p>Option 'qhull d Qbb Qu <a href="#Qg">Qg</a>' may improve the speed of option +'Qu'. If you use the Qhull library, a faster method is 1) use +Qhull to compute the convex hull of the input sites; 2) take the +extreme points (vertices) of the convex hull; 3) add one interior +point (e.g., +'<a href="qh-optf.htm#FV">FV</a>', the average of <em>d</em> extreme points); 4) run +'qhull d Qbb Qu' or 'qhull v Qbb Qu' on these points.</p> + +<h3><a href="#qhull">»</a><a name="Qv">Qv - test vertex +neighbors for convexity </a></h3> + +<p>Normally, Qhull tests all facet neighbors for convexity. +Non-neighboring facets which share a vertex may not satisfy the +convexity constraint. This occurs when a facet undercuts the +centrum of another facet. They should still be convex. Option +'Qv' extends Qhull's convexity testing to all neighboring facets +of each vertex. The extra testing occurs after the hull is +constructed.. </p> + +<h3><a href="#qhull">»</a><a name="QVn">QVn - good facet if it +includes point n, -n if not </a></h3> + +<p>With option 'QVn', a facet is good ('<a href="#Qg">Qg</a>', +'<a href="qh-optp.htm#Pg">Pg</a>') if one of its vertices is +point n. If <i>n<0</i>, a good facet does not include point n. + +<p>If options '<a href="qh-optp.htm#PG">PG</a>' +and '<a href="#Qg">Qg</a>' are not set, option '<a href="qh-optp.htm#Pg">Pg</a>' +(print only good) +is automatically set. +</p> + +<p>Option 'QVn' behaves oddly with options '<a href="qh-optf.htm#Fx">Fx</a>' +and '<a href=qvoronoi.htm>qvoronoi</a> <a href="qh-optf.htm#Fv2">Fv</a>'. + +<p>If used with option '<a href="#Qg">Qg</a>' (only process good facets), point n is +either in the initial simplex or it is the first +point added to the hull. Options 'QVn Qg' require either '<a href="#QJn">QJ</a>' or +'<a href="#Q0">Q0</a>' (no merging).</p> + +<h3><a href="#qhull">»</a><a name="Qx">Qx - exact pre-merges +(allows coplanar facets) </a></h3> + +<p>Option 'Qx' performs exact merges while building the hull. +Option 'Qx' is set by default in 5-d and higher. Use option '<a +href="#Q0">Q0</a>' to not use 'Qx' by default. Unless otherwise +specified, option 'Qx' sets option '<a href="qh-optc.htm#C0">C-0</a>'. +</p> + +<p>The "exact" merges are merging a point into a +coplanar facet (defined by '<a href="qh-optc.htm#Vn">Vn </a>', '<a +href="qh-optc.htm#Un">Un</a>', and '<a href="qh-optc.htm#Cn">C-n</a>'), +merging concave facets, merging duplicate ridges, and merging +flipped facets. Coplanar merges and angle coplanar merges ('<a +href="qh-optc.htm#An">A-n</a>') are not performed. Concavity +testing is delayed until a merge occurs.</p> + +<p>After the hull is built, all coplanar merges are performed +(defined by '<a href="qh-optc.htm#Cn">C-n</a>' and '<a +href="qh-optc.htm#An">A-n</a>'), then post-merges are performed +(defined by '<a href="qh-optc.htm#Cn2">Cn</a>' and '<a +href="qh-optc.htm#An2">An</a>'). If facet progress is logged ('<a +href="qh-optt.htm#TFn">TFn</a>'), Qhull reports each phase and +prints intermediate summaries and statistics ('<a +href="qh-optt.htm#Ts">Ts</a>'). </p> + +<p>Without 'Qx' in 5-d and higher, options '<a +href="qh-optc.htm#Cn">C-n</a>' and '<a href="qh-optc.htm#An">A-n</a>' +may merge too many facets. Since redundant vertices are not +removed effectively, facets become increasingly wide. </p> + +<p>Option 'Qx' may report a wide facet. With 'Qx', coplanar +facets are not merged. This can produce a "dent" in an +intermediate hull. If a point is partitioned into a dent and it +is below the surrounding facets but above other facets, one or +more wide facets will occur. In practice, this is unlikely. To +observe this effect, run Qhull with option '<a href="#Q6">Q6</a>' +which doesn't pre-merge concave facets. A concave facet makes a +large dent in the intermediate hull.</p> + +<p>Option 'Qx' may set an outer plane below one of the input +points. A coplanar point may be assigned to the wrong facet +because of a "dent" in an intermediate hull. After +constructing the hull, Qhull double checks all outer planes with +qh_check_maxout in <tt>poly2.c </tt>. If a coplanar point is +assigned to the wrong facet, qh_check_maxout may reach a local +maximum instead of locating all coplanar facets. This appears to +be unlikely.</p> + +<h3><a href="#qhull">»</a><a name="Qz">Qz - add a +point-at-infinity for Delaunay triangulations</a></h3> + +<p>Option 'Qz' adds a point above the paraboloid of lifted sites +for a Delaunay triangulation. It allows the Delaunay +triangulation of cospherical sites. It reduces precision errors +for nearly cospherical sites.</p> + +<h3><a href="#qhull">»</a><a name="Q0">Q0 - no merging with C-0 +and Qx</a></h3> + +<p>Turn off default merge options '<a href="qh-optc.htm#C0">C-0</a>' +and '<a href="#Qx">Qx</a>'. </p> + +<p>With 'Q0' and without other pre-merge options, Qhull ignores +precision issues while constructing the convex hull. This may +lead to precision errors. If so, a descriptive warning is +generated. See <a href="qh-impre.htm">Precision issues</a>.</p> + +<h3><a href="#qhull">»</a><a name="Q1">Q1 - sort merges by type +instead of angle </a></h3> + +<p>Qhull sorts the coplanar facets before picking a subset of the +facets to merge. It merges concave and flipped facets first. Then +it merges facets that meet at a steep angle. With 'Q1', Qhull +sorts merges by type (coplanar, angle coplanar, concave) instead +of by angle. This may make the facets wider. </p> + +<h3><a href="#qhull">»</a><a name="Q2">Q2 - merge all non-convex +at once instead of independent sets </a></h3> + +<p>With 'Q2', Qhull merges all facets at once instead of +performing merges in independent sets. This may make the facets +wider. </p> + +<h3><a href="#qhull">»</a><a name="Q3">Q3 - do not merge +redundant vertices </a></h3> + +<p>With 'Q3', Qhull does not remove redundant vertices. In 6-d +and higher, Qhull never removes redundant vertices (since +vertices are highly interconnected). Option 'Q3' may be faster, +but it may result in wider facets. Its effect is easiest to see +in 3-d and 4-d.</p> + +<h3><a href="#qhull">»</a><a name="Q4">Q4 - avoid merging </a>old +facets into new facets</h3> + +<p>With 'Q4', Qhull avoids merges of an old facet into a new +facet. This sometimes improves facet width and sometimes makes it +worse. </p> + +<h3><a href="#qhull">»</a><a name="Q5">Q5 - do not correct outer +planes at end of qhull </a></h3> + +<p>When merging facets or approximating a hull, Qhull tests +coplanar points and outer planes after constructing the hull. It +does this by performing a directed search (qh_findbest in <tt>geom.c</tt>). +It includes points that are just inside the hull. </p> + +<p>With options 'Q5' or '<a href="qh-optp.htm#Po">Po</a>', Qhull +does not test outer planes. The maximum outer plane is used +instead. Coplanar points ('<a href="#Qc">Qc</a>') are defined by +'<a href="qh-optc.htm#Un">Un</a>'. An input point may be outside +of the maximum outer plane (this appears to be unlikely). An +interior point may be above '<a href="qh-optc.htm#Un">Un</a>' +from a hyperplane.</p> + +<p>Option 'Q5' may be used if outer planes are not needed. Outer +planes are needed for options '<a href="qh-opto.htm#s">s</a>', '<a +href="qh-optg.htm#G">G</a>', '<a href="qh-optg.htm#Go">Go </a>', +'<a href="qh-optf.htm#Fs">Fs</a>', '<a href="qh-optf.htm#Fo">Fo</a>', +'<a href="qh-optf.htm#FF">FF</a>', and '<a href="qh-opto.htm#f">f</a>'.</p> + +<h3><a href="#qhull">»</a><a name="Q6">Q6 - do not pre-merge +concave or coplanar facets </a></h3> + +<p>With 'Q6', Qhull does not pre-merge concave or coplanar +facets. This demonstrates the effect of "dents" when +using '<a href="#Qx">Qx</a>'. </p> + +<h3><a href="#qhull">»</a><a name="Q7">Q7 - depth-first +processing instead of breadth-first </a></h3> + +<p>With 'Q7', Qhull processes facets in depth-first order instead +of breadth-first order. This may increase the locality of +reference in low dimensions. If so, Qhull may be able to use +virtual memory effectively. </p> + +<p>In 5-d and higher, many facets are visible from each +unprocessed point. So each iteration may access a large +proportion of allocated memory. This makes virtual memory +ineffectual. Once real memory is used up, Qhull will spend most +of its time waiting for I/O.</p> + +<p>Under 'Q7', Qhull runs slower and the facets may be wider. </p> + +<h3><a href="#qhull">»</a><a name="Q8">Q8 - ignore near-interior +points </a></h3> + +<p>With 'Q8' and merging, Qhull does not process interior points +that are near to a facet (as defined by qh_RATIOnearInside in +user.h). This avoids partitioning steps. It may miss a coplanar +point when adjusting outer hulls in qh_check_maxout(). The best +value for qh_RATIOnearInside is not known. Options 'Q8 <a +href="#Qc">Qc</a>' may be sufficient. </p> + +<h3><a href="#qhull">»</a><a name="Q9">Q9 - process furthest of +furthest points </a></h3> + +<p>With 'Q9', Qhull processes the furthest point of all outside +sets. This may reduce precision problems. The furthest point of +all outside sets is not necessarily the furthest point from the +convex hull.</p> + +<h3><a href="#qhull">»</a><a name="Q10">Q10 - no special processing +for narrow distributions</a></h3> + +<p>With 'Q10', Qhull does not special-case narrow distributions. +See <a href=qh-impre.htm#limit>Limitations of merged facets</a> for +more information. + +<h3><a href="#qhull">»</a><a name="Q11">Q11 - copy normals and recompute +centrums for +tricoplanar facets</a></h3> + +Option '<a href="#Qt">Qt</a>' triangulates non-simplicial facets +into "tricoplanar" facets. +Normally tricoplanar facets share the same normal, centrum, and +Voronoi vertex. They can not be merged or replaced. With +option 'Q11', Qhull duplicates the normal and Voronoi vertex. +It recomputes the centrum. + +<p>Use 'Q11' if you use the Qhull library to add points +incrementally and call qh_triangulate() after each point. +Otherwise, Qhull will report an error when it tries to +merge and replace a tricoplanar facet. + +<p>With sufficient merging and new points, option 'Q11' may +lead to precision problems such +as duplicate ridges and concave facets. For example, if qh_triangulate() +is added to qh_addpoint(), RBOX 1000 s W1e-12 t1001813667 P0 | QHULL d Q11 Tv, +reports an error due to a duplicate ridge. + +<h3><a href="#qhull">»</a><a name="Q12">Q12 - do not error +on wide merge due to duplicate ridge and nearly coincident points</a></h3> + +<p>In 3-d and higher Delaunay Triangulations or 4-d and higher convex hulls, multiple, +nearly coincident points may lead to very wide facets. An error is reported if a +merge across a duplicate ridge would increase the facet width by 100x or more. + +<p>Use option 'Q12' to log a warning instead of throwing an error. + +<p>For Delaunay triangulations, a bounding box may alleviate this error (e.g., <tt>rbox 500 C1,1E-13 t c G1 | qhull d</tt>). +This avoids the ill-defined edge between upper and lower convex hulls. +The problem will be fixed in a future release of Qhull. + +<p>To demonstrate the problem, use rbox option 'Cn,r,m' to generate nearly coincident points. +For more information, see "Nearly coincident points on an edge" +in <a href="qh-impre.htm#limit"</a>Nearly coincident points on an edge</a>. + +<!-- Navigation links --> +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> +<!-- GC common information --> +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="qh--geom.gif" +align="middle" width="40" height="40"></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: Sept. 25, 1995 --- <!-- hhmts start --> Last modified: see top <!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/qh-optt.htm b/xs/src/qhull/html/qh-optt.htm new file mode 100644 index 000000000..0709f58c6 --- /dev/null +++ b/xs/src/qhull/html/qh-optt.htm @@ -0,0 +1,278 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<title>Qhull trace options (T)</title> +</head> + +<body> +<!-- Navigation links --> +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> + +<hr> +<!-- Main text of document --> +<h1><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/delaunay.html"><img +src="qh--dt.gif" alt="[delaunay]" align="middle" width="100" +height="100"></a> Qhull trace options (T)</h1> + +This section lists the trace options for Qhull. These options are +indicated by 'T' followed by a letter. + +<p><b>Copyright © 1995-2015 C.B. Barber</b></p> + +<hr> + +<p><a href="index.htm#TOC">»</a> <a href="qh-quick.htm#programs">Programs</a> +<a name="trace">•</a> <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> + +<h2>Trace options</h2> + +<dl compact> + <dt> </dt> + <dd><b>General</b></dd> + <dt><a href="#Tz">Tz</a></dt> + <dd>output error information to stdout instead of stderr</dd> + <dt><a href="#TI">TI file</a></dt> + <dd>input data from a file</dd> + <dt><a href="#TO">TO file</a></dt> + <dd>output results to a file</dd> + <dt><a href="#Ts">Ts</a></dt> + <dd>print statistics</dd> + <dt><a href="#TFn">TFn</a></dt> + <dd>report progress whenever n or more facets created</dd> + <dt><a href="#TRn">TRn</a></dt> + <dd>rerun qhull n times</dd> + <dt><a href="#Tv">Tv</a></dt> + <dd>verify result: structure, convexity, and point inclusion</dd> + + <dt> </dt> + <dt> </dt> + <dd><b>Debugging</b></dd> + <dt><a href="#Tc">Tc</a></dt> + <dd>check frequently during execution</dd> + <dt><a href="#TVn2">TVn</a></dt> + <dd>stop qhull after adding point n </dd> + <dt><a href="#TCn">TCn</a></dt> + <dd>stop qhull after building cone for point n</dd> + <dt><a href="#TVn">TV-n</a></dt> + <dd>stop qhull before adding point n</dd> + <dt><a href="#Tn">T4</a></dt> + <dd>trace at level n, 4=all, 5=mem/gauss, -1= events</dd> + <dt><a href="#TWn">TWn</a></dt> + <dd>trace merge facets when width > n</dd> + <dt><a href="#TMn">TMn</a></dt> + <dd>turn on tracing at merge n</dd> + <dt><a href="#TPn">TPn</a></dt> + <dd>turn on tracing when point n added to hull</dd> +</dl> + +<hr> + +<h3><a href="#trace">»</a><a name="Tc">Tc - check frequently +during execution </a></h3> + +<p>Qhull includes frequent checks of its data structures. Option +'Tc' will catch most inconsistency errors. It is slow and should +not be used for production runs. Option '<a href="#Tv">Tv</a>' +performs the same checks after the hull is constructed.</p> + +<h3><a href="#trace">»</a><a name="TCn">TCn - stop qhull after +building cone for point n</a></h3> + +<p>Qhull builds a cone from the point to its horizon facets. +Option 'TCn' stops Qhull just after building the cone. The output +for '<a href="qh-opto.htm#f">f</a>' includes the cone and the old +hull.'. </p> + +<h3><a href="#trace">»</a><a name="TFn">TFn - report summary +whenever n or more facets created </a></h3> + +<p>Option 'TFn' reports progress whenever more than n facets are +created. The test occurs just before adding a new point to the +hull. During post-merging, 'TFn' reports progress after more than +<i>n/2</i> merges. </p> + +<h3><a href="#trace">»</a><a name="TI">TI file - input data from file</a></h3> + +<p>Input data from 'file' instead of stdin. The filename may not +contain spaces or use single quotes. +You may use I/O redirection +instead (e.g., 'rbox 10 | qdelaunay >results').</P> + +<h3><a href="#trace">»</a><a name="TMn">TMn - turn on tracing at +merge n </a></h3> + +<p>Turn on tracing at n'th merge. </p> + +<h3><a href="#trace">»</a><a name="Tn">Tn - trace at level n</a></h3> + +<p>Qhull includes full execution tracing. 'T-1' traces events. +'T1' traces the overall execution of the program. 'T2' and 'T3' +trace overall execution and geometric and topological events. +'T4' traces the algorithm. 'T5' includes information about memory +allocation and Gaussian elimination. 'T1' is useful for logging +progress of Qhull in high dimensions.</p> + +<p>Option 'Tn' can produce large amounts of output. Use options '<a +href="#TPn">TPn</a>', '<a href="#TWn">TWn</a>', and '<a href="#TMn">TMn</a>' to selectively +turn on tracing. Since all errors report the last processed +point, option '<a href="#TPn">TPn</a>' is particularly useful.</p> + +<p>Different executions of the same program may produce different +traces and different results. The reason is that Qhull uses hashing +to match ridges of non-simplicial facets. For performance reasons, +the hash computation uses +memory addresses which may change across executions. + +<h3><a href="#trace">»</a><a name="TO">TO file - output results to file</a></h3> + +<p>Redirect stdout to 'file'. The filename may be enclosed in +single quotes. Unix and Windows NT users may use I/O redirection +instead (e.g., 'rbox 10 | qdelaunay >results').</P> +<p> +Windows95 users should always use 'TO file'. If they use I/O redirection, +error output is not sent to the console. Qhull uses single quotes instead +of double quotes because a missing double quote can +freeze Windows95 (e.g., do not run, rbox 10 | qhull TO "x)</p> +<p> + +<h3><a href="#trace">»</a><a name="TPn">TPn - turn on tracing +when point n added to hull </a></h3> + +<p>Option 'TPn' turns on tracing when point n is added to +the hull. It also traces partitions of point n. This option +reduces the output size when tracing. It is the normal +method to determine the cause of a Qhull error. All Qhull errors +report the last point added. + +<p>Use options 'TPn <a href="qh-optt.htm#TVn">TVn</a>' to +trace the addition of point n to the convex hull and stop when done.</p> + +<p>If used with option '<a href="qh-optt.htm#TWn">TWn</a>', +'TPn' turns off tracing after adding point n to the hull. +Use options 'TPn TWn' to +trace the addition of point n to the convex hull, partitions +of point n, and wide merges.</p> + +<h3><a href="#trace">»</a><a name="TRn">TRn - rerun qhull n times</a></h3> + +<p>Option 'TRn' reruns Qhull n times. It is usually used +with '<a href="qh-optq.htm#QJn">QJn</a>' to determine the probability +that a given joggle will fail. The summary +('<a href="qh-opto.htm#s">s</a>') lists the failure +rate and the precision errors that occurred. +Option '<a href="#Ts">Ts</a>' will report statistics for +all of the runs. Trace and output options only apply to the last +run. An event trace, '<a href="#Tn">T-1</a>' reports events for all runs. + +<p>Tracing applies to the last run of Qhull. If an error +is reported, the options list the run number as "_run". +To trace this run, set 'TRn' to the same value.</p> + +<h3><a href="#trace">»</a><a name="Ts">Ts - print statistics </a></h3> + +<p>Option 'Ts' collects statistics and prints them to stderr. For +Delaunay triangulations, the angle statistics are restricted to +the lower or upper envelope.</p> + +<h3><a href="#trace">»</a><a name="Tv">Tv - verify result: +structure, convexity, and point inclusion </a></h3> + +<p>Option 'Tv' checks the topological structure, convexity, and +point inclusion. If precision problems occurred, facet convexity +is tested whether or not 'Tv' is selected. Option 'Tv' does not +check point inclusion if forcing output with '<a +href="qh-optp.htm#Po">Po</a>', or if '<a href="qh-optq.htm#Q5">Q5</a>' +is set. </p> + +<p>The convex hull of a set of points is the smallest polytope +that includes the points. Option 'Tv' tests point inclusion. +Qhull verifies that all points are below all outer planes +(facet->maxoutside). Point inclusion is exhaustive if merging +or if the facet-point product is small enough; otherwise Qhull +verifies each point with a directed search (qh_findbest). To +force an exhaustive test when using option '<a +href="qh-optc.htm#C0">C-0</a>' (default), use 'C-1e-30' instead. </p> + +<p>Point inclusion testing occurs after producing output. It +prints a message to stderr unless option '<a +href="qh-optp.htm#Pp">Pp</a>' is used. This allows the user to +interrupt Qhull without changing the output. </p> + +<p>With '<a href=qvoronoi.htm>qvoronoi</a> <a href="qh-optf.htm#Fi2">Fi</a>' +and '<a href=qvoronoi.htm>qvoronoi</a> <a href="qh-optf.htm#Fo2">Fo</a>', +option 'Tv' collects statistics that verify all Voronoi vertices lie +on the separating hyperplane, and for bounded regions, all +separating hyperplanes are perpendicular bisectors. + +<h3><a href="#trace">»</a><a name="TVn">TV-n - stop qhull before +adding point n</a></h3> + +<p>Qhull adds one point at a time to the convex hull. See <a +href="qh-eg.htm#how">how Qhull adds a point</a>. Option 'TV-n' +stops Qhull just before adding a new point. Output shows the hull +at this time.</p> + +<h3><a href="#trace">»</a><a name="TVn2">TVn - stop qhull after +adding point n</a></h3> + +<p>Option 'TVn' stops Qhull after it has added point n. Output +shows the hull at this time.</p> + +<h3><a href="#trace">»</a><a name="TWn">TWn - trace merge facets +when width > n </a></h3> + +<p>Along with TMn, this option allows the user to determine the +cause of a wide merge.</p> +<h3><a href="#trace">»</a><a name="Tz">Tz - send all output to +stdout </a></h3> + +<p>Redirect stderr to stdout. </p> + +<!-- Navigation links --> +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> +<!-- GC common information --> +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="qh--geom.gif" +align="middle" width="40" height="40"></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: Sept. 25, 1995 --- <!-- hhmts start --> Last modified: see top <!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/qh-quick.htm b/xs/src/qhull/html/qh-quick.htm new file mode 100644 index 000000000..9d52e7d75 --- /dev/null +++ b/xs/src/qhull/html/qh-quick.htm @@ -0,0 +1,495 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<title>Qhull quick reference</title> +</head> + +<body> +<!-- Navigation links --> +<p><a name="TOC"><b>Up:</b></a> <a href="http://www.qhull.org">Home +page for Qhull</a> <br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a> <br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="qh-code.htm#TOC">Qhull internals</a><br> +<b>To:</b> <a href="../src/libqhull/index.htm">Qhull functions</a>, macros, and data structures<br> +<b>To:</b> <a href="../src/libqhull/index.htm#TOC">Qhull files</a><br> +<b>To:</b> <a href="../src/libqhull/qh-geom.htm">Geom</a> • <a href="../src/libqhull/qh-globa.htm">Global</a> +• <a href="../src/libqhull/qh-io.htm">Io</a> • <a href="../src/libqhull/qh-mem.htm">Mem</a> +• <a href="../src/libqhull/qh-merge.htm">Merge</a> • <a href="../src/libqhull/qh-poly.htm">Poly</a> +• <a href="../src/libqhull/qh-qhull.htm">Qhull</a> • <a href="../src/libqhull/qh-set.htm">Set</a> +• <a href="../src/libqhull/qh-stat.htm">Stat</a> • <a href="../src/libqhull/qh-user.htm">User</a> +</p> + +<hr> +<!-- Main text of document --> +<h1><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/cone.html"><img +src="qh--cone.gif" alt="[cone]" align="middle" width="100" +height="100"></a> Qhull quick reference</h1> + +This section lists all programs and options in Qhull. + +<p><b>Copyright © 1995-2015 C.B. Barber</b></p> + +<p> +<a name="programs"> </a> +<hr> +<b>Qhull programs</b> +<p><a href="#TOC">»</a> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> + +<dl> + <dt><a href="qconvex.htm">qconvex</a> -- convex hull</dt> + <dd><a href="qconvex.htm#synopsis">sy</a>nopsis • <a + href="qconvex.htm#input">in</a>put • <a + href="qconvex.htm#outputs">ou</a>tputs • <a + href="qconvex.htm#controls">co</a>ntrols • <a + href="qconvex.htm#graphics">gr</a>aphics • <a + href="qconvex.htm#notes">no</a>tes • <a + href="qconvex.htm#conventions">co</a>nventions • <a + href="qconvex.htm#options">op</a>tions</dd> + <dt> </dt> + <dt><a href="qdelaun.htm">qdelaunay</a> -- Delaunay triangulation</dt> + <dd><a href="qdelaun.htm#synopsis">sy</a>nopsis • <a + href="qdelaun.htm#input">in</a>put • <a + href="qdelaun.htm#outputs">ou</a>tputs • <a + href="qdelaun.htm#controls">co</a>ntrols • <a + href="qdelaun.htm#graphics">gr</a>aphics • <a + href="qdelaun.htm#notes">no</a>tes • <a + href="qdelaun.htm#conventions">co</a>nventions • <a + href="qdelaun.htm#options">op</a>tions</dd> + <dt> </dt> + <dt><a href="qdelau_f.htm">qdelaunay Qu</a> -- furthest-site Delaunay triangulation</dt> + <dd><a href="qdelau_f.htm#synopsis">sy</a>nopsis • <a + href="qdelau_f.htm#input">in</a>put • <a + href="qdelau_f.htm#outputs">ou</a>tputs • <a + href="qdelau_f.htm#controls">co</a>ntrols • <a + href="qdelau_f.htm#graphics">gr</a>aphics • <a + href="qdelau_f.htm#notes">no</a>tes • <a + href="qdelau_f.htm#conventions">co</a>nventions • <a + href="qdelau_f.htm#options">op</a>tions</dd> + <dt> </dt> + <dt><a href="qhalf.htm">qhalf</a> -- halfspace intersection about a point</dt> + <dd><a href="qhalf.htm#synopsis">sy</a>nopsis • <a + href="qhalf.htm#input">in</a>put • <a + href="qhalf.htm#outputs">ou</a>tputs • <a + href="qhalf.htm#controls">co</a>ntrols • <a + href="qhalf.htm#graphics">gr</a>aphics • <a + href="qhalf.htm#notes">no</a>tes • <a + href="qhalf.htm#conventions">co</a>nventions • <a + href="qhalf.htm#options">op</a>tions</dd> + <dt> </dt> + <dt><a href="qvoronoi.htm">qvoronoi</a> -- Voronoi diagram</dt> + <dd><a href="qvoronoi.htm#synopsis">sy</a>nopsis • <a + href="qvoronoi.htm#input">in</a>put • <a + href="qvoronoi.htm#outputs">ou</a>tputs • + <a href="qvoronoi.htm#controls">co</a>ntrols • <a + href="qvoronoi.htm#graphics">gr</a>aphics • <a + href="qvoronoi.htm#notes">no</a>tes • <a + href="qvoronoi.htm#conventions">co</a>nventions • <a + href="qvoronoi.htm#options">op</a>tions</dd> + <dt> </dt> + <dt><a href="qvoron_f.htm">qvoronoi Qu</a> -- furthest-site Voronoi diagram</dt> + <dd><a href="qvoron_f.htm#synopsis">sy</a>nopsis • <a + href="qvoron_f.htm#input">in</a>put • <a + href="qvoron_f.htm#outputs">ou</a>tputs • <a + href="qvoron_f.htm#controls">co</a>ntrols • <a + href="qvoron_f.htm#graphics">gr</a>aphics • <a + href="qvoron_f.htm#notes">no</a>tes • <a + href="qvoron_f.htm#conventions">co</a>nventions • <a + href="qvoron_f.htm#options">op</a>tions</dd> + <dt> </dt> + <dt><a href="rbox.htm">rbox</a> -- generate point distributions for qhull</dt> + <dd><a href="rbox.htm#synopsis">sy</a>nopsis • <a + href="rbox.htm#outputs">ou</a>tputs • <a + href="rbox.htm#examples">ex</a>amples • <a + href="rbox.htm#notes">no</a>tes • <a + href="rbox.htm#options">op</a>tions</dd> + <dt> </dt> + <dt><a href="qhull.htm">qhull</a> -- convex hull and related structures</dt> + <dd><a href="qhull.htm#synopsis">sy</a>nopsis • <a + href="qhull.htm#input">in</a>put • <a + href="qhull.htm#outputs">ou</a>tputs • <a + href="qhull.htm#controls">co</a>ntrols • <a + href="qhull.htm#options">op</a>tions</dd> + </dl> +<a name="options"> </a> +<hr> +<b>Qhull options</b> + +<p><a href="#TOC">»</a> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a></p> + +<p><table> +<!-- Note: keep all lines the same for easy reorganization --> +<tr> +<td><nobr>'<a href=qh-optf.htm#Fa>Fa</a>' +Farea +</nobr></td><td><nobr>'<a href=qh-optf.htm#Fa>FA</a>' +FArea-total +</nobr></td><td><nobr>'<a href=qh-optf.htm#Fc>Fc</a>' +Fcoplanars +</nobr></td><td><nobr>'<a href=qh-optf.htm#FC>FC</a>' +FCentrums + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optf.htm#Fd>Fd</a>' +Fd-cdd-in +</nobr></td><td><nobr>'<a href=qh-optf.htm#FD>FD</a>' +FD-cdd-out +</nobr></td><td><nobr>'<a href=qh-optf.htm#FF>FF</a>' +FF-dump-xridge +</nobr></td><td><nobr>'<a href=qh-optf.htm#Fi>Fi</a>' +Finner + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optf.htm#Fi2>Fi</a>' +Finner_bounded +</nobr></td><td><nobr>'<a href=qh-optf.htm#FI>FI</a>' +FIDs +</nobr></td><td><nobr>'<a href=qh-optf.htm#Fm>Fm</a>' +Fmerges +</nobr></td><td><nobr>'<a href=qh-optf.htm#FM>FM</a>' +FMaple + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optf.htm#Fn>Fn</a>' +Fneighbors +</nobr></td><td><nobr>'<a href=qh-optf.htm#FN>FN</a>' +FNeigh-vertex +</nobr></td><td><nobr>'<a href=qh-optf.htm#Fo>Fo</a>' +Fouter +</nobr></td><td><nobr>'<a href=qh-optf.htm#Fo2>Fo</a>' +Fouter_unbounded + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optf.htm#FO>FO</a>' +FOptions +</nobr></td><td><nobr>'<a href=qh-optf.htm#Fp>Fp</a>' +Fpoint-intersect +</nobr></td><td><nobr>'<a href=qh-optf.htm#FP>FP</a>' +FPoint_near +</nobr></td><td><nobr>'<a href=qh-optf.htm#FQ>FQ</a>' +FQhull + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optf.htm#Fs>Fs</a>' +Fsummary +</nobr></td><td><nobr>'<a href=qh-optf.htm#FS>FS</a>' +FSize +</nobr></td><td><nobr>'<a href=qh-optf.htm#Ft>Ft</a>' +Ftriangles +</nobr></td><td><nobr>'<a href=qh-optf.htm#Fv>Fv</a>' +Fvertices + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optf.htm#Fv2>Fv</a>' +Fvoronoi +</nobr></td><td><nobr>'<a href=qh-optf.htm#FV>FV</a>' +FVertex-ave +</nobr></td><td><nobr>'<a href=qh-optf.htm#Fx>Fx</a>' +Fxtremes +</nobr></td><td colspan=2><nobr> +<a href=qh-impre.htm#joggle>Merged facets or joggled input</a> + +</nobr></td></tr> +<tr><td> </td></tr><tr> +<td><nobr>'<a href=qh-optp.htm#PAn>PAn</a>' +PArea-keep +</nobr></td><td><nobr>'<a href=qh-optp.htm#Pdk>Pdk:n</a>' +Pdrop_low +</nobr></td><td><nobr>'<a href=qh-optp.htm#PDk>PDk:n</a>' +Pdrop_high +</nobr></td><td><nobr>'<a href=qh-optp.htm#Pg>Pg</a>' +Pgood + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optp.htm#PFn>PFn</a>' +PFacet_area_keep +</nobr></td><td><nobr>'<a href=qh-optp.htm#PG>PG</a>' +PGood_neighbors +</nobr></td><td><nobr>'<a href=qh-optp.htm#PMn>PMn</a>' +PMerge-keep +</nobr></td><td><nobr>'<a href=qh-optp.htm#Po>Po</a>' +Poutput_forced + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optp.htm#Po2>Po</a>' +Poutput_error +</nobr></td><td><nobr>'<a href=qh-optp.htm#Pp>Pp</a>' +Pprecision_not + +</nobr></td></tr> +<tr><td> </td></tr><tr> +<td><nobr>'<a href=qhull.htm#outputs>d</a>' +delaunay +</nobr></td><td><nobr>'<a href=qhull.htm#outputs>v</a>' +voronoi +</nobr></td><td><nobr>'<a href=qh-optg.htm>G</a>' +Geomview +</nobr></td><td><nobr>'<a href=qhull.htm#outputs>H</a>' +Halfspace + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-opto.htm#f>f</a>' +facet_dump +</nobr></td><td><nobr>'<a href=qh-opto.htm#i>i</a>' +incidences +</nobr></td><td><nobr>'<a href=qh-opto.htm#m>m</a>' +mathematica +</nobr></td><td><nobr>'<a href=qh-opto.htm#n>n</a>' +normals + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-opto.htm#o>o</a>' +OFF_format +</nobr></td><td><nobr>'<a href=qh-opto.htm#p>p</a>' +points +</nobr></td><td><nobr>'<a href=qh-opto.htm#s>s</a>' +summary + +</nobr></td></tr> +<tr><td> </td></tr><tr> +<td><nobr>'<a href=qh-optg.htm#Gv>Gv</a>' +Gvertices +</nobr></td><td><nobr>'<a href=qh-optg.htm#Gp>Gp</a>' +Gpoints +</nobr></td><td><nobr>'<a href=qh-optg.htm#Ga>Ga</a>' +Gall_points +</nobr></td><td><nobr>'<a href=qh-optg.htm#Gn>Gn</a>' +Gno_planes + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optg.htm#Gi>Gi</a>' +Ginner +</nobr></td><td><nobr>'<a href=qh-optg.htm#Gc>Gc</a>' +Gcentrums +</nobr></td><td><nobr>'<a href=qh-optg.htm#Gh>Gh</a>' +Ghyperplanes +</nobr></td><td><nobr>'<a href=qh-optg.htm#Gr>Gr</a>' +Gridges + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optg.htm#Go>Go</a>' +Gouter +</nobr></td><td><nobr>'<a href=qh-optg.htm#GDn>GDn</a>' +GDrop_dim +</nobr></td><td><nobr>'<a href=qh-optg.htm#Gt>Gt</a>' +Gtransparent + +</nobr></td></tr> +<tr><td> </td></tr><tr> +<td><nobr>'<a href=qh-optt.htm#Tn>T4</a>' +T4_trace +</nobr></td><td><nobr>'<a href=qh-optt.htm#Tc>Tc</a>' +Tcheck_often +</nobr></td><td><nobr>'<a href=qh-optt.htm#Ts>Ts</a>' +Tstatistics +</nobr></td><td><nobr>'<a href=qh-optt.htm#Tv>Tv</a>' +Tverify + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optt.htm#Tz>Tz</a>' +Tz_stdout +</nobr></td><td><nobr>'<a href=qh-optt.htm#TFn>TFn</a>' +TFacet_log +<td><nobr>'<a href=qh-optt.htm#TI>TI file</a>' +TInput_file +</nobr></td><td><nobr>'<a href=qh-optt.htm#TPn>TPn</a>' +TPoint_trace + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optt.htm#TMn>TMn</a>' +TMerge_trace +</nobr></td><td><nobr>'<a href=qh-optt.htm#TO>TO file</a>' +TOutput_file +</nobr></td><td><nobr>'<a href=qh-optt.htm#TRn>TRn</a>' +TRerun +</nobr></td><td><nobr>'<a href=qh-optt.htm#TWn>TWn</a>' +TWide_trace + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optt.htm#TVn>TV-n</a>' +TVertex_stop_before +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optt.htm#TVn2>TVn</a>' +TVertex_stop_after +</nobr></td><td><nobr>'<a href=qh-optt.htm#TCn>TCn</a>' +TCone_stop_after + +</nobr></td></tr> +<tr><td> </td></tr><tr> +<td><nobr>'<a href=qh-optc.htm#An>A-n</a>' +Angle_max_pre +</nobr></td><td><nobr>'<a href=qh-optc.htm#An2>An</a>' +Angle_max_post +</nobr></td><td><nobr>'<a href=qh-optc.htm#C0>C-0</a>' +Centrum_roundoff +</nobr></td><td><nobr>'<a href=qh-optc.htm#Cn>C-n</a>' +Centrum_size_pre + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optc.htm#Cn2>Cn</a>' +Centrum_size_post +</nobr></td><td><nobr>'<a href=qh-optc.htm#En>En</a>' +Error_round +</nobr></td><td><nobr>'<a href=qh-optc.htm#Rn>Rn</a>' +Random_dist +</nobr></td><td><nobr>'<a href=qh-optc.htm#Vn>Vn</a>' +Visible_min + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optc.htm#Un>Un</a>' +Ucoplanar_max +</nobr></td><td><nobr>'<a href=qh-optc.htm#Wn>Wn</a>' +Wide_outside + +</nobr></td></tr> +<tr><td> </td></tr><tr> +<td><nobr>'<a href=qh-optq.htm#Qbk>Qbk:n</a>' +Qbound_low +</nobr></td><td><nobr>'<a href=qh-optq.htm#QBk>QBk:n</a>' +QBound_high +</nobr></td><td><nobr>'<a href=qh-optq.htm#Qb0>Qbk:0Bk:0</a>' +Qbound_drop +</nobr></td><td><nobr>'<a href=qh-optq.htm#QbB>QbB</a>' +QbB-scale-box + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optq.htm#Qbb>Qbb</a>' +Qbb-scale-last +</nobr></td><td><nobr>'<a href=qh-optq.htm#Qc>Qc</a>' +Qcoplanar +</nobr></td><td><nobr>'<a href=qh-optq.htm#Qf>Qf</a>' +Qfurthest +</nobr></td><td><nobr>'<a href=qh-optq.htm#Qg>Qg</a>' +Qgood_only + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optq.htm#QGn>QGn</a>' +QGood_point +</nobr></td><td><nobr>'<a href=qh-optq.htm#Qi>Qi</a>' +Qinterior +</nobr></td><td><nobr>'<a href=qh-optq.htm#Qm>Qm</a>' +Qmax_out +</nobr></td><td><nobr>'<a href=qh-optq.htm#QJn>QJn</a>' +QJoggle + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optq.htm#Qr>Qr</a>' +Qrandom +</nobr></td><td><nobr>'<a href=qh-optq.htm#QRn>QRn</a>' +QRotate +</nobr></td><td><nobr>'<a href=qh-optq.htm#Qs>Qs</a>' +Qsearch_1st +</nobr></td><td><nobr>'<a href=qh-optq.htm#Qt>Qt</a>' +Qtriangulate + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optq.htm#Qu>Qu</a>' +QupperDelaunay +</nobr><td><nobr>'<a href=qh-optq.htm#QVn>QVn</a>' +QVertex_good +</nobr></td><td><nobr>'<a href=qh-optq.htm#Qv>Qv</a>' +Qvneighbors +</nobr></td><td><nobr>'<a href=qh-optq.htm#Qx>Qx</a>' +Qxact_merge + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optq.htm#Qz>Qz</a>' +Qzinfinite + +</nobr></td></tr> +<tr><td> </td></tr><tr> +<td><nobr>'<a href=qh-optq.htm#Q0>Q0</a>' +Q0_no_premerge +</nobr></td><td><nobr>'<a href=qh-optq.htm#Q1>Q1</a>' +Q1_no_angle +</nobr></td><td><nobr>'<a href=qh-optq.htm#Q2>Q2</a>' +Q2_no_independ +</nobr></td><td><nobr>'<a href=qh-optq.htm#Q3>Q3</a>' +Q3_no_redundant + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optq.htm#Q4>Q4</a>' +Q4_no_old +</nobr></td><td><nobr>'<a href=qh-optq.htm#Q5>Q5</a>' +Q5_no_check_out +</nobr></td><td><nobr>'<a href=qh-optq.htm#Q6>Q6</a>' +Q6_no_concave +</nobr></td><td><nobr>'<a href=qh-optq.htm#Q7>Q7</a>' +Q7_depth_first + +</nobr></td></tr><tr> +<td><nobr>'<a href=qh-optq.htm#Q8>Q8</a>' +Q8_no_near_in +</nobr></td><td><nobr>'<a href=qh-optq.htm#Q9>Q9</a>' +Q9_pick_furthest +</nobr></td><td><nobr>'<a href=qh-optq.htm#Q10>Q10</a>' +Q10_no_narrow +</nobr></td><td><nobr>'<a href=qh-optq.htm#Q11>Q11</a>' +Q11_trinormals +</td></tr></table> + +<!-- Navigation links --> +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home +page for Qhull</a> <br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a> <br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="qh-code.htm#TOC">Qhull internals</a><br> +<b>To:</b> <a href="../src/libqhull/index.htm">Qhull functions</a>, macros, and data structures<br> +<b>To:</b> <a href="../src/libqhull/index.htm#TOC">Qhull files</a><br> +<b>To:</b> <a href="../src/libqhull/qh-geom.htm">Geom</a> • <a href="../src/libqhull/qh-globa.htm">Global</a> +• <a href="../src/libqhull/qh-io.htm">Io</a> • <a href="../src/libqhull/qh-mem.htm">Mem</a> +• <a href="../src/libqhull/qh-merge.htm">Merge</a> • <a href="../src/libqhull/qh-poly.htm">Poly</a> +• <a href="../src/libqhull/qh-qhull.htm">Qhull</a> • <a href="../src/libqhull/qh-set.htm">Set</a> +• <a href="../src/libqhull/qh-stat.htm">Stat</a> • <a href="../src/libqhull/qh-user.htm">User</a><br> +<!-- GC common information --> +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="qh--geom.gif" +align="middle" width="40" height="40"></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: Sept. 25, 1995 --- <!-- hhmts start --> Last modified: see top <!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/qhalf.htm b/xs/src/qhull/html/qhalf.htm new file mode 100644 index 000000000..c87fe719e --- /dev/null +++ b/xs/src/qhull/html/qhalf.htm @@ -0,0 +1,626 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<title>qhalf -- halfspace intersection about a point</title> +</head> + +<body> +<!-- Navigation links --> +<p><a name="TOP"><b>Up</b></a><b>:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#synopsis">sy</a>nopsis +• <a href="#input">in</a>put • <a href="#outputs">ou</a>tputs +• <a href="#controls">co</a>ntrols • <a href="#graphics">gr</a>aphics +• <a href="#notes">no</a>tes • <a href="#conventions">co</a>nventions +• <a href="#options">op</a>tions + +<hr> +<!-- Main text of document --> +<h1><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/half.html"><img +src="qh--half.gif" alt="[halfspace]" align="middle" width="100" +height="100"></a>qhalf -- halfspace intersection about a point</h1> + +<p>The intersection of a set of halfspaces is a polytope. The +polytope may be unbounded. See Preparata & Shamos [<a +href="index.htm#pre-sha85">'85</a>] for a discussion. In low +dimensions, halfspace intersection may be used for linear +programming. + +<blockquote> +<dl compact> + <dt><p><b>Example:</b> rbox c | qconvex <a href="qh-optf.htm#FQ">FQ</a> <a href="qh-optf.htm#FV">FV</a> + <a href="qh-opto.htm#n">n</a> | qhalf <a + href="qh-optf.htm#Fp">Fp</a></dt> + <dd>Print the intersection of the facets of a cube. <tt>rbox c</tt> + generates the vertices of a cube. <tt>qconvex FV n</tt> returns of average + of the cube's vertices (in this case, the origin) and the halfspaces + that define the cube. <tt>qhalf Fp</tt> computes the intersection of + the halfspaces about the origin. The intersection is the vertices + of the original cube.</dd> + + <dt><p><b>Example:</b> rbox c d G0.55 | qconvex <a href="qh-optf.htm#FQ">FQ</a> <a href="qh-optf.htm#FV">FV</a> + <a href="qh-opto.htm#n">n</a> | qhalf <a + href="qh-optf.htm#Fp">Fp</a></dt> + <dd>Print the intersection of the facets of a cube and a diamond. There + are 24 facets and 14 intersection points. Four facets define each diamond + vertex. Six facets define each cube vertex. + </dd> + + <dt><p><b>Example:</b> rbox c d G0.55 | qconvex <a href="qh-optf.htm#FQ">FQ</a> <a href="qh-optf.htm#FV">FV</a> + <a href="qh-opto.htm#n">n</a> | qhalf <a + href="qh-optf.htm#Fp">Fp</a> + <a href="qh-optq.htm#Qt">Qt</a></dt> + <dd>Same as above except triangulate before computing + the intersection points. Three facets define each intersection + point. There are two duplicates of the diamond and four duplicates of the cube. + </dd> + + <dt><p><b>Example:</b> rbox 10 s t10 | qconvex <a href="qh-optf.htm#FQ">FQ</a> <a href="qh-optf.htm#FV">FV</a> + <a href="qh-opto.htm#n">n</a> | qhalf <a + href="qh-optf.htm#Fp">Fp</a> <a + href="qh-optf.htm#Fn">Fn</a></dt> + <dd>Print the intersection of the facets of the convex hull of 10 cospherical points. + Include the intersection points and the neighboring intersections. + As in the previous examples, the intersection points are nearly the same as the + original input points. + </dd> +</dl> +</blockquote> + +<p>In Qhull, a <i>halfspace</i> is defined by the points on or below a hyperplane. +The distance of each point to the hyperplane is less than or equal to zero. + +<p>Qhull computes a halfspace intersection by the geometric +duality between points and halfspaces. +See <a href="qh-eg.htm#half">halfspace examples</a>, +<a href="#notes">qhalf notes</a>, and +option 'p' of <a href="#outputs">qhalf outputs</a>. </p> + +<p>Qhalf's <a href="#outputs">outputs</a> are the intersection +points (<a href="qh-optf.htm#Fp">Fp</a>) and +the neighboring intersection points (<a href="qh-optf.htm#Fn">Fn</a>). +For random inputs, halfspace +intersections are usually defined by more than <i>d</i> halfspaces. See the sphere example. + +<p>You can try triangulated output ('<a href="qh-optq.htm#Qt">Qt</a>') and joggled input ('<a href="qh-optq.htm#QJn">QJ</a>'). +It demonstrates that triangulated output is more accurate than joggled input. + +<p>If you use '<a href="qh-optq.htm#Qt">Qt</a>' (triangulated output), all +halfspace intersections are simplicial (e.g., three halfspaces per +intersection in 3-d). In 3-d, if more than three halfspaces intersect +at the same point, triangulated output will produce +duplicate intersections, one for each additional halfspace. See the third example, or +add 'Qt' to the sphere example.</p> + +<p>If you use '<a href="qh-optq.htm#QJn">QJ</a>' (joggled input), all halfspace +intersections are simplicial. This may lead to nearly identical +intersections. For example, either replace 'Qt' with 'QJ' above, or add +'QJ' to the sphere example. +See <a +href="qh-impre.htm#joggle">Merged facets or joggled input</a>. </p> + +<p>The 'qhalf' program is equivalent to +'<a href=qhull.htm#outputs>qhull H</a>' in 2-d to 4-d, and +'<a href=qhull.htm#outputs>qhull H</a> <a href=qh-optq.htm#Qx>Qx</a>' +in 5-d and higher. It disables the following Qhull +<a href=qh-quick.htm#options>options</a>: <i>d n v Qbb QbB Qf Qg Qm +Qr QR Qv Qx Qz TR E V Fa FA FC FD FS Ft FV Gt Q0,etc</i>. + + +<p><b>Copyright © 1995-2015 C.B. Barber</b></p> +<hr> + +<h3><a href="#TOP">»</a><a name="synopsis">qhalf synopsis</a></h3> +<pre> +qhalf- halfspace intersection about a point. + input (stdin): [dim, 1, interior point] + dim+1, n + halfspace coefficients + offset + comments start with a non-numeric character + +options (qhalf.htm): + Hn,n - specify coordinates of interior point + Qt - triangulated output + QJ - joggle input instead of merging facets + Tv - verify result: structure, convexity, and redundancy + . - concise list of all options + - - one-line description of all options + +output options (subset): + s - summary of results (default) + Fp - intersection coordinates + Fv - non-redundant halfspaces incident to each intersection + Fx - non-redundant halfspaces + o - OFF file format (dual convex hull) + G - Geomview output (dual convex hull) + m - Mathematica output (dual convex hull) + QVn - print intersections for halfspace n, -n if not + TO file - output results to file, may be enclosed in single quotes + +examples: + rbox d | qconvex n | qhalf s H0,0,0 Fp + rbox c | qconvex FV n | qhalf s i + rbox c | qconvex FV n | qhalf s o +</pre> + +<h3><a href="#TOP">»</a><a name="input">qhalf input</a></h3> + +<blockquote> +<p>The input data on <tt>stdin</tt> consists of:</p> +<ul> + <li>[optional] interior point + <ul> + <li>dimension + <li>1 + <li>coordinates of interior point + </ul> + <li>dimension + 1 + <li>number of halfspaces</li> + <li>halfspace coefficients followed by offset</li> +</ul> + +<p>Use I/O redirection (e.g., qhalf < data.txt), a pipe (e.g., rbox c | qconvex FV n | qhalf), +or the '<a href=qh-optt.htm#TI>TI</a>' option (e.g., qhalf TI data.txt). + +<p>Qhull needs an interior point to compute the halfspace +intersection. An interior point is clearly inside all of the halfspaces. +A point is <i>inside</i> a halfspace if its distance to the corresponding hyperplane is negative. + +<p>The interior point may be listed at the beginning of the input (as shown above). +If not, option +'Hn,n' defines the interior point as +[n,n,0,...] where <em>0</em> is the default coordinate (e.g., +'H0' is the origin). Use linear programming if you do not know +the interior point (see <a href="#notes">halfspace notes</a>),</p> + +<p>The input to qhalf is a set of halfspaces that are defined by their hyperplanes. +Each halfspace is defined by +<em>d</em> coefficients followed by a signed offset. This defines +a linear inequality. The coefficients define a vector that is +normal to the halfspace. +The vector may have any length. If it +has length one, the offset is the distance from the origin to the +halfspace's boundary. Points in the halfspace have a negative distance to the hyperplane. +The distance from the interior point to each +halfspace is likewise negative.</p> + +<p>The halfspace format is the same as Qhull's output options '<a +href="qh-opto.htm#n">n</a>', '<a href="qh-optf.htm#Fo">Fo</a>', +and '<a href="qh-optf.htm#Fi">Fi</a>'. Use option '<a +href="qh-optf.htm#Fd">Fd</a>' to use cdd format for the +halfspaces.</p> + +<p>For example, here is the input for computing the intersection +of halfplanes that form a cube.</p> + +<blockquote> + <p>rbox c | qconvex FQ FV n TO data </p> + <pre> +RBOX c | QCONVEX FQ FV n +3 1 + 0 0 0 +4 +6 + 0 0 -1 -0.5 + 0 -1 0 -0.5 + 1 0 0 -0.5 + -1 0 0 -0.5 + 0 1 0 -0.5 + 0 0 1 -0.5 +</pre> + <p>qhalf s Fp < data </p> + <pre> + +Halfspace intersection by the convex hull of 6 points in 3-d: + + Number of halfspaces: 6 + Number of non-redundant halfspaces: 6 + Number of intersection points: 8 + +Statistics for: RBOX c | QCONVEX FQ FV n | QHALF s Fp + + Number of points processed: 6 + Number of hyperplanes created: 11 + Number of distance tests for qhull: 11 + Number of merged facets: 1 + Number of distance tests for merging: 45 + CPU seconds to compute hull (after input): 0 + +3 +3 +8 + -0.5 0.5 0.5 + 0.5 0.5 0.5 + -0.5 0.5 -0.5 + 0.5 0.5 -0.5 + 0.5 -0.5 0.5 + -0.5 -0.5 0.5 + -0.5 -0.5 -0.5 + 0.5 -0.5 -0.5 +</pre> +</blockquote> + +</blockquote> +<h3><a href="#TOP">»</a><a name="outputs">qhalf outputs</a></h3> +<blockquote> + +<p>The following options control the output for halfspace +intersection.</p> +<blockquote> +<dl compact> + <dt> </dt> + <dd><b>Intersections</b></dd> + <dt><a href="qh-optf.htm#FN">FN</a></dt> + <dd>list intersection points for each non-redundant + halfspace. The first line + is the number of non-redundant halfspaces. Each remaining + lines starts with the number of intersection points. For the cube + example, each halfspace has four intersection points.</dd> + <dt><a href="qh-optf.htm#Fn">Fn</a></dt> + <dd>list neighboring intersections for each intersection point. The first line + is the number of intersection points. Each remaining line + starts with the number of neighboring intersections. For the cube + example, each intersection point has three neighboring intersections. + <p> + In 3-d, a non-simplicial intersection has more than three neighboring + intersections. For random data (e.g., the sphere example), non-simplicial intersections are the norm. + Option '<a href="qh-optq.htm#Qt">Qt</a>' produces three + neighboring intersections per intersection by duplicating the intersection + points. Option <a href="qh-optq.htm#QJn">QJ</a>' produces three + neighboring intersections per intersection by joggling the hyperplanes and + hence their intersections. + </dd> + <dt><a href="qh-optf.htm#Fp">Fp</a></dt> + <dd>print intersection coordinates. The first line is the dimension and the + second line is the number of intersection points. The following lines are the + coordinates of each intersection.</dd> + <dt><a href="qh-optf.htm#FI">FI</a></dt> + <dd>list intersection IDs. The first line is the number of + intersections. The IDs follow, one per line.</dd> + <dt> </dt> + <dt> </dt> + <dd><b>Halfspaces</b></dd> + <dt><a href="qh-optf.htm#Fx">Fx</a></dt> + <dd>list non-redundant halfspaces. The first line is the number of + non-redundant halfspaces. The other lines list one halfspace per line. + A halfspace is <i>non-redundant</i> if it + defines a facet of the intersection. Redundant halfspaces are ignored. For + the cube example, all of the halfspaces are non-redundant. + </dd> + <dt><a href="qh-optf.htm#Fv">Fv</a></dt> + <dd>list non-redundant halfspaces incident to each intersection point. + The first line is the number of + non-redundant halfspaces. Each remaining line starts with the number + of non-redundant halfspaces. For the + cube example, each intersection is incident to three halfspaces.</dd> + <dt><a href="qh-opto.htm#i">i</a></dt> + <dd>list non-redundant halfspaces incident to each intersection point. The first + line is the number of intersection points. Each remaining line + lists the incident, non-redundant halfspaces. For the + cube example, each intersection is incident to three halfspaces. + </dd> + <dt><a href="qh-optf.htm#Fc">Fc</a></dt> + <dd>list coplanar halfspaces for each intersection point. The first line is + the number of intersection points. Each remaining line starts with + the number of coplanar halfspaces. A coplanar halfspace is listed for + one intersection point even though it is coplanar to multiple intersection + points.</dd> + <dt><a href="qh-optq.htm#Qc">Qi</a> <a href="qh-optf.htm#Fc">Fc</a></dt> + <dd>list redundant halfspaces for each intersection point. The first line is + the number of intersection points. Each remaining line starts with + the number of redundant halfspaces. Use options '<a href="qh-optq.htm#Qc">Qc</a> Qi Fc' to list + coplanar and redundant halfspaces.</dd> + + <dt> </dt> + <dt> </dt> + <dd><b>General</b></dd> + <dt><a href="qh-opto.htm#s">s</a></dt> + <dd>print summary for the halfspace intersection. Use '<a + href="qh-optf.htm#Fs">Fs</a>' if you need numeric data.</dd> + <dt><a href="qh-opto.htm#o">o</a></dt> + <dd>print vertices and facets of the dual convex hull. The + first line is the dimension. The second line is the number of + vertices, facets, and ridges. The vertex + coordinates are next, followed by the facets, one per line.</dd> + <dt><a href="qh-opto.htm#p">p</a></dt> + <dd>print vertex coordinates of the dual convex hull. Each vertex corresponds + to a non-redundant halfspace. Its coordinates are the negative of the hyperplane's coefficients + divided by the offset plus the inner product of the coefficients and + the interior point (-c/(b+a.p). + Options 'p <a href="qh-optq.htm#Qc">Qc</a>' includes coplanar halfspaces. + Options 'p <a href="qh-optq.htm#Qi">Qi</a>' includes redundant halfspaces.</dd> + <dt><a href="qh-opto.htm#m">m</a></dt> + <dd>Mathematica output for the dual convex hull in 2-d or 3-d.</dd> + <dt><a href="qh-optf.htm#FM">FM</a></dt> + <dd>Maple output for the dual convex hull in 2-d or 3-d.</dd> + <dt><a href="qh-optg.htm#G">G</a></dt> + <dd>Geomview output for the dual convex hull in 2-d, 3-d, or 4-d.</dd> + </dl> +</blockquote> + +</blockquote> +<h3><a href="#TOP">»</a><a name="controls">qhalf controls</a></h3> +<blockquote> + +<p>These options provide additional control:</p> + +<blockquote> +<dl compact> + <dt><a href="qh-optq.htm#Qt">Qt</a></dt> + <dd>triangulated output. If a 3-d intersection is defined by more than + three hyperplanes, Qhull produces duplicate intersections -- one for + each extra hyperplane.</dd> + <dt><a href="qh-optq.htm#QJn">QJ</a></dt> + <dd>joggle the input instead of merging facets. In 3-d, this guarantees that + each intersection is defined by three hyperplanes.</dd> + <dt><a href="qh-opto.htm#f">f </a></dt> + <dd>facet dump. Print the data structure for each intersection (i.e., + facet)</dd> + <dt><a href="qh-optt.htm#TFn">TFn</a></dt> + <dd>report summary after constructing <em>n</em> + intersections</dd> + <dt><a href="qh-optq.htm#QVn">QVn</a></dt> + <dd>select intersection points for halfspace <em>n</em> + (marked 'good')</dd> + <dt><a href="qh-optq.htm#QGn">QGn</a></dt> + <dd>select intersection points that are visible to halfspace <em>n</em> + (marked 'good'). Use <em>-n</em> for the remainder.</dd> + <dt><a href="qh-optq.htm#Qb0">Qbk:0Bk:0</a></dt> + <dd>remove the k-th coordinate from the input. This computes the + halfspace intersection in one lower dimension.</dd> + <dt><a href="qh-optt.htm#Tv">Tv</a></dt> + <dd>verify result</dd> + <dt><a href="qh-optt.htm#TO">TI file</a></dt> + <dd>input data from file. The filename may not use spaces or quotes.</dd> + <dt><a href="qh-optt.htm#TO">TO file</a></dt> + <dd>output results to file. Use single quotes if the filename + contains spaces (e.g., <tt>TO 'file with spaces.txt'</tt></dd> + <dt><a href="qh-optq.htm#Qs">Qs</a></dt> + <dd>search all points for the initial simplex. If Qhull can + not construct an initial simplex, it reports a +descriptive message. Usually, the point set is degenerate and one +or more dimensions should be removed ('<a href="qh-optq.htm#Qb0">Qbk:0Bk:0</a>'). +If not, use option 'Qs'. It performs an exhaustive search for the +best initial simplex. This is expensive is high dimensions.</dd> +</dl> +</blockquote> + + +</blockquote> +<h3><a href="#TOP">»</a><a name="graphics">qhalf graphics</a></h3> +<blockquote> + +<p>To view the results with Geomview, compute the convex hull of +the intersection points ('qhull FQ H0 Fp | qhull G'). See <a +href="qh-eg.htm#half">Halfspace examples</a>.</p> + +</blockquote> +<h3><a href="#TOP">»</a><a name="notes">qhalf notes</a></h3> +<blockquote> + +<p>See <a href="qh-impre.htm#halfspace">halfspace intersection</a> for precision issues related to qhalf.</p> + +<p>If you do not know an interior point for the halfspaces, use +linear programming to find one. Assume, <em>n</em> halfspaces +defined by: <em>aj*x1+bj*x2+cj*x3+dj<=0, j=1..n</em>. Perform +the following linear program: </p> + +<blockquote> + <p>max(x5) aj*x1+bj*x2+cj*x3+dj*x4+x5<=0, j=1..n</p> +</blockquote> + +<p>Then, if <em>[x1,x2,x3,x4,x5]</em> is an optimal solution with +<em>x4>0</em> and <em>x5>0</em> we get: </p> + +<blockquote> + <p>aj*(x1/x4)+bj*(x2/x4)+cj*(x3/x4)+dj<=(-x5/x4) j=1..n and (-x5/x4)<0, + </p> +</blockquote> + +<p>and conclude that the point <em>[x1/x4,x2/x4,x3/x4]</em> is in +the interior of all the halfspaces. Since <em>x5</em> is +optimal, this point is "way in" the interior (good +for precision errors).</p> + +<p>After finding an interior point, the rest of the intersection +algorithm is from Preparata & Shamos [<a +href="index.htm#pre-sha85">'85</a>, p. 316, "A simple case +..."]. Translate the halfspaces so that the interior point +is the origin. Calculate the dual polytope. The dual polytope is +the convex hull of the vertices dual to the original faces in +regard to the unit sphere (i.e., halfspaces at distance <em>d</em> +from the origin are dual to vertices at distance <em>1/d</em>). +Then calculate the resulting polytope, which is the dual of the +dual polytope, and translate the origin back to the interior +point [S. Spitz, S. Teller, D. Strawn].</p> + + +</blockquote> +<h3><a href="#TOP">»</a><a name="conventions">qhalf +conventions</a></h3> +<blockquote> + +<p>The following terminology is used for halfspace intersection +in Qhull. This is the hardest structure to understand. The +underlying structure is a convex hull with one vertex per +non-redundant halfspace. See <a href="#conventions">convex hull +conventions</a> and <a href="index.htm#structure">Qhull's data structures</a>.</p> + +<ul> + <li><em>interior point</em> - a point in the intersection of + the halfspaces. Qhull needs an interior point to compute + the intersection. See <a href="#input">halfspace input</a>.</li> + <li><em>halfspace</em> - <em>d</em> coordinates for the + normal and a signed offset. The distance to an interior + point is negative.</li> + <li><em>non-redundant halfspace</em> - a halfspace that + defines an output facet</li> + <li><em>vertex</em> - a dual vertex in the convex hull + corresponding to a non-redundant halfspace</li> + <li><em>coplanar point</em> - the dual point corresponding to + a similar halfspace</li> + <li><em>interior point</em> - the dual point corresponding to + a redundant halfspace</li> + <li><em>intersection point</em>- the intersection of <em>d</em> + or more non-redundant halfspaces</li> + <li><em>facet</em> - a dual facet in the convex hull + corresponding to an intersection point</li> + <li><em>non-simplicial facet</em> - more than <em>d</em> + halfspaces intersect at a point</li> + <li><em>good facet</em> - an intersection point that + satisfies restriction '<a href="qh-optq.htm#QVn">QVn</a>', + etc.</li> +</ul> + +</blockquote> +<h3><a href="#TOP">»</a><a name="options">qhalf options</a></h3> + +<pre> +qhalf- compute the intersection of halfspaces about a point + http://www.qhull.org + +input (stdin): + optional interior point: dimension, 1, coordinates + first lines: dimension+1 and number of halfspaces + other lines: halfspace coefficients followed by offset + comments: start with a non-numeric character + +options: + Hn,n - specify coordinates of interior point + Qt - triangulated ouput + QJ - joggle input instead of merging facets + Qc - keep coplanar halfspaces + Qi - keep other redundant halfspaces + +Qhull control options: + QJn - randomly joggle input in range [-n,n] + Qbk:0Bk:0 - remove k-th coordinate from input + Qs - search all halfspaces for the initial simplex + QGn - print intersection if redundant to halfspace n, -n for not + QVn - print intersections for halfspace n, -n if not + +Trace options: + T4 - trace at level n, 4=all, 5=mem/gauss, -1= events + Tc - check frequently during execution + Ts - print statistics + Tv - verify result: structure, convexity, and redundancy + Tz - send all output to stdout + TFn - report summary when n or more facets created + TI file - input data from file, no spaces or single quotes + TO file - output results to file, may be enclosed in single quotes + TPn - turn on tracing when halfspace n added to intersection + TMn - turn on tracing at merge n + TWn - trace merge facets when width > n + TVn - stop qhull after adding halfspace n, -n for before (see TCn) + TCn - stop qhull after building cone for halfspace n (see TVn) + +Precision options: + Cn - radius of centrum (roundoff added). Merge facets if non-convex + An - cosine of maximum angle. Merge facets if cosine > n or non-convex + C-0 roundoff, A-0.99/C-0.01 pre-merge, A0.99/C0.01 post-merge + Rn - randomly perturb computations by a factor of [1-n,1+n] + Un - max distance below plane for a new, coplanar halfspace + Wn - min facet width for outside halfspace (before roundoff) + +Output formats (may be combined; if none, produces a summary to stdout): + f - facet dump + G - Geomview output (dual convex hull) + i - non-redundant halfspaces incident to each intersection + m - Mathematica output (dual convex hull) + o - OFF format (dual convex hull: dimension, points, and facets) + p - vertex coordinates of dual convex hull (coplanars if 'Qc' or 'Qi') + s - summary (stderr) + +More formats: + Fc - count plus redundant halfspaces for each intersection + - Qc (default) for coplanar and Qi for other redundant + Fd - use cdd format for input (homogeneous with offset first) + FF - facet dump without ridges + FI - ID of each intersection + Fm - merge count for each intersection (511 max) + FM - Maple output (dual convex hull) + Fn - count plus neighboring intersections for each intersection + FN - count plus intersections for each non-redundant halfspace + FO - options and precision constants + Fp - dim, count, and intersection coordinates + FP - nearest halfspace and distance for each redundant halfspace + FQ - command used for qhalf + Fs - summary: #int (8), dim, #halfspaces, #non-redundant, #intersections + for output: #non-redundant, #intersections, #coplanar + halfspaces, #non-simplicial intersections + #real (2), max outer plane, min vertex + Fv - count plus non-redundant halfspaces for each intersection + Fx - non-redundant halfspaces + +Geomview output (2-d, 3-d and 4-d; dual convex hull) + Ga - all points (i.e., transformed halfspaces) as dots + Gp - coplanar points and vertices as radii + Gv - vertices (i.e., non-redundant halfspaces) as spheres + Gi - inner planes (i.e., halfspace intersections) only + Gn - no planes + Go - outer planes only + Gc - centrums + Gh - hyperplane intersections + Gr - ridges + GDn - drop dimension n in 3-d and 4-d output + +Print options: + PAn - keep n largest facets (i.e., intersections) by area + Pdk:n- drop facet if normal[k] <= n (default 0.0) + PDk:n- drop facet if normal[k] >= n + Pg - print good facets (needs 'QGn' or 'QVn') + PFn - keep facets whose area is at least n + PG - print neighbors of good facets + PMn - keep n facets with most merges + Po - force output. If error, output neighborhood of facet + Pp - do not report precision problems + + . - list of all options + - - one line descriptions of all options +</pre> + +<!-- Navigation links --> +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#synopsis">sy</a>nopsis +• <a href="#input">in</a>put • <a href="#outputs">ou</a>tputs +• <a href="#controls">co</a>ntrols • <a href="#graphics">gr</a>aphics +• <a href="#notes">no</a>tes • <a href="#conventions">co</a>nventions +• <a href="#options">op</a>tions +<!-- GC common information --> +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="qh--geom.gif" +align="middle" width="40" height="40"></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: Sept. 25, 1995 --- <!-- hhmts start --> Last modified: see top <!-- hhmts end --> </p> +</body> +</html> + diff --git a/xs/src/qhull/html/qhull-cpp.xml b/xs/src/qhull/html/qhull-cpp.xml new file mode 100644 index 000000000..ae755e826 --- /dev/null +++ b/xs/src/qhull/html/qhull-cpp.xml @@ -0,0 +1,214 @@ +<?xml version="1.0" encoding="utf-8"?> +<?xml-stylesheet type="text/xsl" href="../../road-faq/xsl/road-faq.xsl"?> + +<rf:topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://schemas.roadintranet.org/road-faq-1 /road/road-faq/xsl/road-faq.xsd" + xmlns:rf="http://schemas.roadintranet.org/road-faq-1" + title=" C++ interface to Qhull" + file="qhull-cpp.xml" + fileid="$Id: //main/2015/qhull/html/qhull-cpp.xml#2 $$Change: 2027 $" + fileChange="$DateTime: 2015/11/09 23:18:11 $$Author: bbarber $"> + <div><h4>Qhull C++ -- C++ interface to Qhull</h4></div> + <rf:copyright> + <a href="../cpp/COPYING.txt">Copyright</a> (c) 2009-2015, C.B. Barber + </rf:copyright> + <rf:section id="cpp-cpp-links" title="Useful Links for Qhull C++"> + <div> + <p> This draft + document records some of the design decisions for Qhull C++. Convert it to HTML by road-faq.xsl from <a href="http://www.qhull.org/road/road-faq/road-faq.html">road-faq</a>. + + Please send comments and suggestions to <a + href="mailto:bradb@shore.net">bradb@shore.net</a> + </p> + </div> + <div class="twocol"> + <div class="col leftcol"> + Help + <ul><li> + </li><li> + </li><li> + </li></ul> + </div> + <div class="col rightcol"> + <ul><li> + </li><li> + </li></ul> + </div> + </div> + <div> + . <!-- clear the two column display --> + </div> + + </rf:section> + <rf:section id="qhull-api" title="Qhull's collection classes"> + + <rf:item id="collection-api" title="API for Qhull collections" date="Feb 2009" author="bbarber"> + Qhull's collection APIs are modeled on Qt's collection API (QList, QVector, QHash) w/o QT_STRICT_ITERATORS. They support STL and Qt programming. + + <p>Some of Qhull's collection classes derive from STL classes. If so, + please avoid additional STL functions and operators added by inheritance. + These collection classes may be rewritten to derive from Qt classes instead. + See Road's <rf:iref item="cpp-collection-api"/>. + </p> + + + Qhull's collection API (where applicable). For documentation, see Qt's QList, QMap, QListIterator, QMapIterator, QMutableListIterator, and QMutableMapIterator + <ul><li> + STL types [list, qlinkedlist, qlist, qvector, vector] -- const_iterator, iterator + </li><li> + STL types describing iterators [list, qlinkedlist, qlist, qvector, vector] -- const_pointer, const_reference, difference_type, + pointer, reference, size_type, value_type. + Pointer and reference types not defined if unavailable (not needed for <algorithm>) + </li><li> + const_iterator, iterator types -- difference_type, iterator_category, pointer, reference, value_type + </li><li> + Qt types [qlinkedlist, qlist, qvector] -- ConstIterator, Iterator, QhullclassIterator, MutableQhullclassIterator. + Qt's foreach requires const_iterator. + </li><li> + Types for sets/maps [hash_map, QHash] -- key_compare, key_type, mapped_type + </li><li> + Constructor -- default constructor, copy constructor, assignment operator, destructor + </li><li> + Conversion -- to/from/as corresponding C, STL, and Qt constructs. Include toQList and toStdVector (may be filtered, e.g., QhullFacetSet). + Do not define fromStdList and fromQList if container is not reference counted (i.e., acts like a value) + </li><li> + Get/set -- configuration options for class + </li><li> + STL-style iterator - begin, constBegin, constEnd, end, key, value, =, *, [], ->, ++, --, +, -, ==, !=, <, + <=, >, >=, const_iterator(iterator), iterator COMPARE const_iterator. + An iterator is an abstraction of a pointer. It is not aware of its container. + </li><li> + Java-style iterator [qiterator.h] - countRemaining, findNext, findPrevious, hasNext, hasPrevious, next, peekNext, peekPrevious, previous, toBack, toFront, = Coordinates + </li><li> + Mutable Java-style iterator adds - insert, remove, setValue, value + </li><li> + Element access -- back, first, front, last + </li><li> + Element access w/ index -- [], at (const& only), constData, data, mid, value + </li><li> + Read-only - (int)count, empty, isEmpty, (size_t)size. Count() and size() may be filtered. If so, they may be zero when !empty(). + </li><li> + Read-only for sets/maps - capacity, key, keys, reserve, resize, values + </li><li> + Operator - ==, !=, +, +=, << + </li><li> + Read-write -- append, clear, erase, insert, move, prepend, pop_back, pop_front, push_back, push_front, removeAll, removeAt, removeFirst, removeLast, replace, + swap, takeAt, takeFirst, takeLast + </li><li> + Read-write for sets/maps -- insertMulti, squeeze, take, unite + </li><li> + Search -- contains(const T &), count(const T &), indexOf, lastIndexOf + </li><li> + Search for sets/maps -- constFind, lowerBound, upperBound + </li><li> + Stream I/O -- stream << + </li></ul> + + STL list and vector -- For unfiltered access to each element. + <ul><li> + <a href="http://stdcxx.apache.org/doc/stdlibug/16-3.html">Apache: Creating your own containers</a> -- requirements for STL containers. Iterators should define the types from 'iterator_traits'. + </li><li> + STL types -- allocator_type, const_iterator, const_pointer, const_reference, const_reverse_iterator, difference_type, iterator, iterator_category, pointer, reference, reverse_iterator, size_type, value_type + </li><li> + STL constructors -- MyType(), MyType(count), MyType(count, value), MyType(first, last), + MyType(MyType&), + </li><li> + STL getter/setters -- at (random_access only), back, begin, capacity, end, front, rbegin, rend, size, max_size + </li><li> + STL predicates -- empty + </li><li> + STL iterator types -- const_pointer, const_reference, difference_type, iterator_category, pointer, reference, value_type + </li><li> + STL iterator operators -- *, -<, ++, --, +=, -=, +, -, [], ==, !=, <, >, >=, <= + </li><li> + STL operators -- =, [] (random_access only), ==, !=, <, >, <=, >= + </li><li> + STL modifiers -- assign, clear, erase, insert, pop_back, push_back, reserve, resize, swap + </li><li> + </li></ul> + + Qt Qlist -- For unfiltered access to each element + <ul><li> + </li><li> + Additional Qt types -- ConstIterator, Iterator, QListIterator, QMutableListIterator + </li><li> + Additional Qt get/set -- constBegin, constEnd, count, first, last, value (random_access only) + </li><li> + Additional Qt predicates -- isEmpty + </li><li> + Additional Qt -- mid (random_access only) + </li><li> + Additional Qt search -- contains, count(T&), indexOf (random_access only), lastIndeOf (random_access only) + </li><li> + Additional Qt modifiers -- append, insert(index,value) (random_access only), move (random_access only), pop_front, prepend, push_front, removeAll, removeAt (random_access only), removeFirst, removeLast, replace, swap by index, takeAt, takeFirst, takeLast + </li><li> + Additional Qt operators -- +, <<, +=, + stream << and >> + </li><li> + Unsupported types by Qt -- allocator_type, const_reverse_iterator, reverse_iterator + </li><li> + Unsupported accessors by Qt -- max_size, rbegin, rend + </li><li> + Unsupported constructors by Qt -- multi-value constructors + </li><li> + unsupported modifiers by Qt -- assign, muli-value inserts, STL's swaps + </li><li> + </li></ul> + + STL map and Qt QMap. These use nearly the same API as list and vector classes. They add the following. + <ul><li> + STL types -- key_compare, key_type, mapped_type + </li><li> + STL search -- equal_range, find, lower_bound, upper_bound + </li><li> + Qt removes -- equal_range, key_compare + </li><li> + Qt renames -- lowerBound, upperBound + </li><li> + Qt adds -- constFind, insertMulti, key, keys, take, uniqueKeys, unite, values + </li><li> + Not applicable to map and QMap -- at, back, pop_back, pop_front, push_back, push_front, swap + </li><li> + Not applicable to QMap -- append, first, last, lastIndexOf, mid, move, prepend, removeAll, removeAt, removeFirst, removeLast, replace, squeeze, takeAt, takeFirst, takeLast + </li><li> + Not applicable to map -- assign + </li></ul> + + Qt QHash. STL extensions provide similar classes, e.g., Microsoft's stdext::hash_set. THey are nearly the same as QMap + <ul><li> + </li><li> + </li><li> + Not applicable to Qhash -- lowerBound, unite, upperBound, + </li><li> + Qt adds -- squeeze + </li></ul> + </rf:item> + <rf:item id="class-api" title="API for Qhull collections" date="Feb 2009" author="bbarber"> + <ul><li> + check... -- Throw error on failure + </li><li> + try... -- Return false on failure. Do not throw errors. + </li><li> + ...Temporarily -- lifetime depends on source. e.g., toByteArrayTemporarily + </li><li> + ...p -- indicates pointer-to. + </li><li> + end... -- points to one beyond the last available + </li><li> + private functions -- No syntactic indication. They may become public later on. + </li><li> + Error messages -- Preceed error messages with the name of the class throwing the error (e.g. "ClassName: ..."). If this is an internal error, use "ClassName inconsistent: ..." + </li><li> + parameter order -- qhRunId, dimension, coordinates, count. + </li><li> + toClass -- Convert into a Class object (makes a deep copy) + </li><li> + qRunId -- Requires Qh installed. Some routines allow 0 for limited info (e.g., operator<<) + </li><li> + Disable methods in derived classes -- If the default constructor, copy constructor, or copy assignment is disabled, it should be also disabled in derived classes (better error messages). + </li><li> + Constructor order -- default constructor, other constructors, copy constructor, copy assignment, destructor + </li></ul> + </rf:item> + </rf:section> +</rf:topic> diff --git a/xs/src/qhull/html/qhull.htm b/xs/src/qhull/html/qhull.htm new file mode 100644 index 000000000..0a2aa75e0 --- /dev/null +++ b/xs/src/qhull/html/qhull.htm @@ -0,0 +1,473 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<title>qhull -- convex hull and related structures</title> +</head> + +<body> +<!-- Navigation links --> +<p><b><a name="TOP">Up</a></b><b>:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#synopsis">sy</a>nopsis • <a href="#input">in</a>put +• <a href="#outputs">ou</a>tputs • <a href="#controls">co</a>ntrols +• <a href="#options">op</a>tions +<hr> +<!-- Main text of document --> +<h1><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/cone.html"><img +src="qh--cone.gif" alt="[cone]" align="middle" width="100" +height="100"></a>qhull -- convex hull and related structures</h1> + +<p>The convex hull of a set of points is the smallest convex set +containing the points. The Delaunay triangulation and furthest-site +Delaunay triangulation are equivalent to a convex hull in one +higher dimension. Halfspace intersection about a point is +equivalent to a convex hull by polar duality. + +<p>The <tt>qhull</tt> program provides options to build these +structures and to experiment with the process. Use the +<a href=qconvex.htm>qconvex</a>, +<a href=qdelaun.htm>qdelaunay</a>, <a href=qhalf.htm>qhalf</a>, +and <a href=qvoronoi.htm>qvoronoi</a> programs +to build specific structures. You may use <tt>qhull</tt> instead. +It takes the same options and uses the same code. +<blockquote> +<dl> + <dt><b>Example:</b> rbox 1000 D3 | qhull + <a href="qh-optc.htm#Cn">C-1e-4</a> + <a href="qh-optf.htm#FO">FO</a> + <a href="qh-optt.htm#Ts">Ts</a> + </dt> + <dd>Compute the 3-d convex hull of 1000 random + points. + Centrums must be 10^-4 below neighboring + hyperplanes. Print the options and precision constants. + When done, print statistics. These options may be + used with any of the Qhull programs.</dd> + <dt> </dt> + <dt><b>Example:</b> rbox 1000 D3 | qhull <a href=qhull.htm#outputs>d</a> + <a href="qh-optq.htm#Qbb">Qbb</a> + <a href="qh-optc.htm#Rn">R1e-4</a> + <a href="qh-optq.htm#Q0">Q0</a></dt> + <dd>Compute the 3-d Delaunay triangulation of 1000 random + points. Randomly perturb all calculations by + [0.9999,1.0001]. Do not correct precision problems. + This leads to serious precision errors.</dd> +</dl> +</blockquote> +<p>Use the following equivalences when calling <tt>qhull</tt> in 2-d to 4-d (a 3-d +Delaunay triangulation is a 4-d convex hull): +<blockquote> +<ul> +<li> +<a href="qconvex.htm">qconvex</a> == qhull +<li> +<a href=qdelaun.htm>qdelaunay</a> == qhull d <a href="qh-optq.htm#Qbb">Qbb</a> +<li> +<a href=qhalf.htm>qhalf</a> == qhull H +<li> +<a href=qvoronoi.htm>qvoronoi</a> == qhull v <a href="qh-optq.htm#Qbb">Qbb</a> +</ul> +</blockquote> + +<p>Use the following equivalences when calling <tt>qhull</tt> in 5-d and higher (a 4-d +Delaunay triangulation is a 5-d convex hull): +<blockquote> +<ul> +<li> +<a href="qconvex.htm">qconvex</a> == qhull <a href="qh-optq.htm#Qx">Qx</a> +<li> +<a href=qdelaun.htm>qdelaunay</a> == qhull d <a href="qh-optq.htm#Qbb">Qbb</a> <a href="qh-optq.htm#Qx">Qx</a> +<li> +<a href=qhalf.htm>qhalf</a> == qhull H <a href="qh-optq.htm#Qx">Qx</a> +<li> +<a href=qvoronoi.htm>qvoronoi</a> == qhull v <a href="qh-optq.htm#Qbb">Qbb</a> <a href="qh-optq.htm#Qx">Qx</a> +</ul> +</blockquote> + + +<p>By default, Qhull merges coplanar facets. For example, the convex +hull of a cube's vertices has six facets. + +<p>If you use '<a href="qh-optq.htm#Qt">Qt</a>' (triangulated output), +all facets will be simplicial (e.g., triangles in 2-d). For the cube +example, it will have 12 facets. Some facets may be +degenerate and have zero area. + +<p>If you use '<a href="qh-optq.htm#QJn">QJ</a>' (joggled input), +all facets will be simplicial. The corresponding vertices will be +slightly perturbed. Joggled input is less accurate that triangulated +output.See <a +href="qh-impre.htm#joggle">Merged facets or joggled input</a>. </p> + +<p>The output for 4-d convex hulls may be confusing if the convex +hull contains non-simplicial facets (e.g., a hypercube). See +<a href=qh-faq.htm#extra>Why +are there extra points in a 4-d or higher convex hull?</a><br> +</p> + +<p><b>Copyright © 1995-2015 C.B. Barber</b></p> + +<hr> + +<h3><a href="#TOP">»</a><a name="synopsis">qhull synopsis</a></h3> +<pre> +qhull- compute convex hulls and related structures. + input (stdin): dimension, n, point coordinates + comments start with a non-numeric character + halfspace: use dim+1 and put offsets after coefficients + +options (qh-quick.htm): + d - Delaunay triangulation by lifting points to a paraboloid + d Qu - furthest-site Delaunay triangulation (upper convex hull) + v - Voronoi diagram as the dual of the Delaunay triangulation + v Qu - furthest-site Voronoi diagram + H1,1 - Halfspace intersection about [1,1,0,...] via polar duality + Qt - triangulated output + QJ - joggle input instead of merging facets + Tv - verify result: structure, convexity, and point inclusion + . - concise list of all options + - - one-line description of all options + +Output options (subset): + s - summary of results (default) + i - vertices incident to each facet + n - normals with offsets + p - vertex coordinates (if 'Qc', includes coplanar points) + if 'v', Voronoi vertices + Fp - halfspace intersections + Fx - extreme points (convex hull vertices) + FA - compute total area and volume + o - OFF format (if 'v', outputs Voronoi regions) + G - Geomview output (2-d, 3-d and 4-d) + m - Mathematica output (2-d and 3-d) + QVn - print facets that include point n, -n if not + TO file- output results to file, may be enclosed in single quotes + +examples: + rbox c d D2 | qhull Qc s f Fx | more rbox 1000 s | qhull Tv s FA + rbox 10 D2 | qhull d QJ s i TO result rbox 10 D2 | qhull v Qbb Qt p + rbox 10 D2 | qhull d Qu QJ m rbox 10 D2 | qhull v Qu QJ o + rbox c | qhull n rbox c | qhull FV n | qhull H Fp + rbox d D12 | qhull QR0 FA rbox c D7 | qhull FA TF1000 + rbox y 1000 W0 | qhull rbox 10 | qhull v QJ o Fv +</pre> + +<h3><a href="#TOP">»</a><a name="input">qhull input</a></h3> +<blockquote> + +<p>The input data on <tt>stdin</tt> consists of:</p> +<ul> + <li>dimension + <li>number of points</li> + <li>point coordinates</li> +</ul> + +<p>Use I/O redirection (e.g., qhull < data.txt), a pipe (e.g., rbox 10 | qhull), +or the '<a href=qh-optt.htm#TI>TI</a>' option (e.g., qhull TI data.txt). + +<p>Comments start with a non-numeric character. Error reporting is +simpler if there is one point per line. Dimension +and number of points may be reversed. For halfspace intersection, +an interior point may be prepended (see <a href=qhalf.htm#input>qhalf input</a>). + +<p>Here is the input for computing the convex +hull of the unit cube. The output is the normals, one +per facet.</p> + +<blockquote> + <p>rbox c > data </p> + <pre> +3 RBOX c +8 + -0.5 -0.5 -0.5 + -0.5 -0.5 0.5 + -0.5 0.5 -0.5 + -0.5 0.5 0.5 + 0.5 -0.5 -0.5 + 0.5 -0.5 0.5 + 0.5 0.5 -0.5 + 0.5 0.5 0.5 +</pre> + <p>qhull s n < data</p> + <pre> + +Convex hull of 8 points in 3-d: + + Number of vertices: 8 + Number of facets: 6 + Number of non-simplicial facets: 6 + +Statistics for: RBOX c | QHULL s n + + Number of points processed: 8 + Number of hyperplanes created: 11 + Number of distance tests for qhull: 35 + Number of merged facets: 6 + Number of distance tests for merging: 84 + CPU seconds to compute hull (after input): 0.081 + +4 +6 + 0 0 -1 -0.5 + 0 -1 0 -0.5 + 1 0 0 -0.5 + -1 0 0 -0.5 + 0 1 0 -0.5 + 0 0 1 -0.5 +</pre> +</blockquote> + +</blockquote> +<h3><a href="#TOP">»</a><a name="outputs">qhull outputs</a></h3> +<blockquote> + +<p>These options control the output of qhull. They may be used +individually or together.</p> +<blockquote> +<dl compact> + <dt> </dt> + <dd><b>General</b></dd> + <dt><a>qhull</a></dt> + <dd>compute the convex hull of the input points. + See <a href=qconvex.htm>qconvex</a>.</dd> + <dt><a name="d">qhull d Qbb</a></dt> + <dd>compute the Delaunay triangulation by lifting the points + to a paraboloid. Use option '<a href="qh-optq.htm#Qbb">Qbb</a>' + to scale the paraboloid and improve numeric precision. + See <a href=qdelaun.htm>qdelaunay</a>.</dd> + <dt><a name="v">qhull v Qbb</a></dt> + <dd>compute the Voronoi diagram by computing the Delaunay + triangulation. Use option '<a href="qh-optq.htm#Qbb">Qbb</a>' + to scale the paraboloid and improve numeric precision. + See <a href=qvoronoi.htm>qvoronoi</a>.</dd> + <dt><a name="H">qhull H</a></dt> + <dd>compute the halfspace intersection about a point via polar + duality. The point is below the hyperplane that defines the halfspace. + See <a href=qhalf.htm>qhalf</a>.</dd> +</dl> +</blockquote> + +<p>For a full list of output options see +<blockquote> +<ul> + <li><a href="qh-opto.htm#output">Output</a> formats</li> + <li><a href="qh-optf.htm#format">Additional</a> I/O + formats</li> + <li><a href="qh-optg.htm#geomview">Geomview</a> + output options</li> + <li><a href="qh-optp.htm#print">Print</a> options</li> +</ul> +</blockquote> + +</blockquote> +<h3><a href="#TOP">»</a><a name="controls">qhull controls</a></h3> +<blockquote> + +<p>For a full list of control options see +<blockquote> +<ul> + <li><a href="qh-optq.htm#qhull">Qhull</a> control + options</li> + <li><a href="qh-optc.htm#prec">Precision</a> options</li> + <li><a href="qh-optt.htm#trace">Trace</a> options</li> +</ul> +</blockquote> + +</blockquote> +<h3><a href="#TOP">»</a><a name="options">qhull options</a></h3> + +<pre> +qhull- compute convex hulls and related structures. + http://www.qhull.org + +input (stdin): + first lines: dimension and number of points (or vice-versa). + other lines: point coordinates, best if one point per line + comments: start with a non-numeric character + halfspaces: use dim plus one and put offset after coefficients. + May be preceded by a single interior point ('H'). + +options: + d - Delaunay triangulation by lifting points to a paraboloid + d Qu - furthest-site Delaunay triangulation (upper convex hull) + v - Voronoi diagram (dual of the Delaunay triangulation) + v Qu - furthest-site Voronoi diagram + Hn,n,... - halfspace intersection about point [n,n,0,...] + Qt - triangulated output + QJ - joggle input instead of merging facets + Qc - keep coplanar points with nearest facet + Qi - keep interior points with nearest facet + +Qhull control options: + Qbk:n - scale coord k so that low bound is n + QBk:n - scale coord k so that upper bound is n (QBk is 0.5) + QbB - scale input to unit cube centered at the origin + Qbb - scale last coordinate to [0,m] for Delaunay triangulations + Qbk:0Bk:0 - remove k-th coordinate from input + QJn - randomly joggle input in range [-n,n] + QRn - random rotation (n=seed, n=0 time, n=-1 time/no rotate) + Qf - partition point to furthest outside facet + Qg - only build good facets (needs 'QGn', 'QVn', or 'PdD') + Qm - only process points that would increase max_outside + Qr - process random outside points instead of furthest ones + Qs - search all points for the initial simplex + Qu - for 'd' or 'v', compute upper hull without point at-infinity + returns furthest-site Delaunay triangulation + Qv - test vertex neighbors for convexity + Qx - exact pre-merges (skips coplanar and anglomaniacs facets) + Qz - add point-at-infinity to Delaunay triangulation + QGn - good facet if visible from point n, -n for not visible + QVn - good facet if it includes point n, -n if not + Q0 - turn off default p remerge with 'C-0'/'Qx' + Q1 - sort merges by type instead of angle + Q2 - merge all non-convex at once instead of independent sets + Q3 - do not merge redundant vertices + Q4 - avoid old>new merges + Q5 - do not correct outer planes at end of qhull + Q6 - do not pre-merge concave or coplanar facets + Q7 - depth-first processing instead of breadth-first + Q8 - do not process near-inside points + Q9 - process furthest of furthest points + Q10 - no special processing for narrow distributions + Q11 - copy normals and recompute centrums for tricoplanar facets + Q12 - do not error on wide merge due to duplicate ridge and nearly coincident points + +Towpaths Trace options: + T4 - trace at level n, 4=all, 5=mem/gauss, -1= events + Tc - check frequently during execution + Ts - print statistics + Tv - verify result: structure, convexity, and point inclusion + Tz - send all output to stdout + TFn - report summary when n or more facets created + TI file - input data from file, no spaces or single quotes + TO file - output results to file, may be enclosed in single quotes + TPn - turn on tracing when point n added to hull + TMn - turn on tracing at merge n + TWn - trace merge facets when width > n + TRn - rerun qhull n times. Use with 'QJn' + TVn - stop qhull after adding point n, -n for before (see TCn) + TCn - stop qhull after building cone for point n (see TVn) + +Precision options: + Cn - radius of centrum (roundoff added). Merge facets if non-convex + An - cosine of maximum angle. Merge facets if cosine > n or non-convex + C-0 roundoff, A-0.99/C-0.01 pre-merge, A0.99/C0.01 post-merge + En - max roundoff error for distance computation + Rn - randomly perturb computations by a factor of [1-n,1+n] + Vn - min distance above plane for a visible facet (default 3C-n or En) + Un - max distance below plane for a new, coplanar point (default Vn) + Wn - min facet width for outside point (before roundoff, default 2Vn) + +Output formats (may be combined; if none, produces a summary to stdout): + f - facet dump + G - Geomview output (see below) + i - vertices incident to each facet + m - Mathematica output (2-d and 3-d) + o - OFF format (dim, points and facets; Voronoi regions) + n - normals with offsets + p - vertex coordinates or Voronoi vertices (coplanar points if 'Qc') + s - summary (stderr) + +More formats: + Fa - area for each facet + FA - compute total area and volume for option 's' + Fc - count plus coplanar points for each facet + use 'Qc' (default) for coplanar and 'Qi' for interior + FC - centrum or Voronoi center for each facet + Fd - use cdd format for input (homogeneous with offset first) + FD - use cdd format for numeric output (offset first) + FF - facet dump without ridges + Fi - inner plane for each facet + for 'v', separating hyperplanes for bounded Voronoi regions + FI - ID of each facet + Fm - merge count for each facet (511 max) + FM - Maple output (2-d and 3-d) + Fn - count plus neighboring facets for each facet + FN - count plus neighboring facets for each point + Fo - outer plane (or max_outside) for each facet + for 'v', separating hyperplanes for unbounded Voronoi regions + FO - options and precision constants + Fp - dim, count, and intersection coordinates (halfspace only) + FP - nearest vertex and distance for each coplanar point + FQ - command used for qhull + Fs - summary: #int (8), dimension, #points, tot vertices, tot facets, + output: #vertices, #facets, #coplanars, #nonsimplicial + #real (2), max outer plane, min vertex + FS - sizes: #int (0) + #real(2) tot area, tot volume + Ft - triangulation with centrums for non-simplicial facets (OFF format) + Fv - count plus vertices for each facet + for 'v', Voronoi diagram as Voronoi vertices for pairs of sites + FV - average of vertices (a feasible point for 'H') + Fx - extreme points (in order for 2-d) + +Geomview options (2-d, 3-d, and 4-d; 2-d Voronoi) + Ga - all points as dots + Gp - coplanar points and vertices as radii + Gv - vertices as spheres + Gi - inner planes only + Gn - no planes + Go - outer planes only + Gc - centrums + Gh - hyperplane intersections + Gr - ridges + GDn - drop dimension n in 3-d and 4-d output + Gt - for 3-d 'd', transparent outer ridges + +Print options: + PAn - keep n largest facets by area + Pdk:n - drop facet if normal[k] <= n (default 0.0) + PDk:n - drop facet if normal[k] >= n + Pg - print good facets (needs 'QGn' or 'QVn') + PFn - keep facets whose area is at least n + PG - print neighbors of good facets + PMn - keep n facets with most merges + Po - force output. If error, output neighborhood of facet + Pp - do not report precision problems + + . - list of all options + - - one line descriptions of all options +</pre> + +<!-- Navigation links --> +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#synopsis">sy</a>nopsis • <a href="#input">in</a>put +• <a href="#outputs">ou</a>tputs • <a href="#controls">co</a>ntrols +• <a href="#options">op</a>tions +<!-- GC common information --> +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="qh--geom.gif" +align="middle" width="40" height="40"></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: Sept. 25, 1995 --- <!-- hhmts start --> Last modified: see top <!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/qhull.man b/xs/src/qhull/html/qhull.man new file mode 100644 index 000000000..8d1dc08ac --- /dev/null +++ b/xs/src/qhull/html/qhull.man @@ -0,0 +1,1008 @@ +.\" This is the Unix manual page for qhull, written in nroff, the standard +.\" manual formatter for Unix systems. To format it, type +.\" +.\" nroff -man qhull.man +.\" +.\" This will print a formatted copy to standard output. If you want +.\" to ensure that the output is plain ASCII, free of any control +.\" characters that nroff uses for underlining etc, pipe the output +.\" through "col -b": +.\" +.\" nroff -man qhull.man | col -b +.\" +.\" Warning: a leading quote "'" or dot "." will not format correctly +.\" +.TH qhull 1 "2003/12/30" "Geometry Center" +.SH NAME +qhull \- convex hull, Delaunay triangulation, Voronoi diagram, +halfspace intersection about a point, hull volume, facet area +.SH SYNOPSIS +.nf +qhull- compute convex hulls and related structures + input (stdin): dimension, #points, point coordinates + first comment (non-numeric) is listed in the summary + halfspace: use dim plus one with offsets after coefficients + +options (qh-quick.htm): + d - Delaunay triangulation by lifting points to a paraboloid + v - Voronoi diagram via the Delaunay triangulation + H1,1 - Halfspace intersection about [1,1,0,...] + d Qu - Furthest-site Delaunay triangulation (upper convex hull) + v Qu - Furthest-site Voronoi diagram + Qt - triangulated output + QJ - Joggle the input to avoid precision problems + . - concise list of all options + - - one-line description of all options + +Output options (subset): + FA - compute total area and volume + Fx - extreme points (convex hull vertices) + G - Geomview output (2-d, 3-d and 4-d) + Fp - halfspace intersection coordinates + m - Mathematica output (2-d and 3-d) + n - normals with offsets + o - OFF file format (if Voronoi, outputs regions) + TO file- output results to file, may be enclosed in single quotes + f - print all fields of all facets + s - summary of results (default) + Tv - verify result: structure, convexity, and point inclusion + p - vertex coordinates (centers for Voronoi) + i - vertices incident to each facet + +example: + rbox 1000 s | qhull Tv s FA +.fi + + - html manual: index.htm + - installation: README.txt + - see also: COPYING.txt, REGISTER.txt, Changes.txt + - WWW: <http://www.qhull.org> + - GIT: <git@github.com:qhull/qhull.git> + - mirror: <http://www6.uniovi.es/ftp/pub/mirrors/geom.umn.edu/software/ghindex.html> + - news: <http://www.qhull.org/news> + - Geomview: <http://www.geomview.org> + - news group: <news:comp.graphics.algorithms> + - FAQ: <http://www.faqs.org/faqs/graphics/algorithms-faq/> + - email: qhull@qhull.org + - bug reports: qhull_bug@qhull.org + +The sections are: + - INTRODUCTION + - DESCRIPTION, a description of Qhull + - IMPRECISION, how Qhull handles imprecision + - OPTIONS + - Input and output options + - Additional input/output formats + - Precision options + - Geomview options + - Print options + - Qhull options + - Trace options + - BUGS + - E-MAIL + - SEE ALSO + - AUTHORS + - ACKNOWLEGEMENTS + +This man page briefly describes all Qhull options. Please report +any mismatches with Qhull's html manual (index.htm). + +.PP +.SH INTRODUCTION +Qhull is a general dimension code for computing convex hulls, Delaunay +triangulations, Voronoi diagram, furthest\[hy]site Voronoi diagram, +furthest\[hy]site Delaunay triangulations, and +halfspace intersections about a point. It implements the Quickhull algorithm for +computing the convex hull. Qhull handles round\[hy]off errors from floating +point arithmetic. It can approximate a convex hull. + +The program includes options for hull volume, facet area, partial hulls, +input transformations, randomization, tracing, multiple output formats, and +execution statistics. The program can be called from within your application. +You can view the results in 2\[hy]d, 3\[hy]d and 4\[hy]d with Geomview. +.PP +.SH DESCRIPTION +.PP +The format of input is the following: first line contains the dimension, +second line contains the number of input points, and point coordinates follow. +The dimension and number of points can be reversed. +Comments and line breaks are ignored. A comment starts with a +non\[hy]numeric character and continues to the end of line. The first comment +is reported in summaries and statistics. +Error reporting is +better if there is one point per line. +.PP +The default printout option is a short summary. There are many +other output formats. +.PP +Qhull implements the Quickhull algorithm for convex hull. This algorithm combines +the 2\[hy]d Quickhull algorithm with the n\[hy]d beneath\[hy]beyond algorithm +[c.f., Preparata & Shamos '85]. +It is similar to the randomized algorithms of Clarkson and +others [Clarkson et al. '93]. The main +advantages of Quickhull are output sensitive performance, reduced +space requirements, and automatic handling of precision problems. +.PP +The data structure produced by Qhull consists of vertices, ridges, and facets. +A vertex is a point of the input set. A ridge is a set of d vertices +and two neighboring facets. For example in 3\[hy]d, a ridge is an edge of the +polyhedron. A facet is a set of ridges, a set of neighboring facets, a set +of incident vertices, and a hyperplane equation. For simplicial facets, the +ridges are defined by the vertices and neighboring facets. When Qhull +merges two facets, it produces a non\[hy]simplicial +facet. A non\[hy]simplicial facet has more than d neighbors and may share more than +one ridge with a neighbor. +.PP +.SH IMPRECISION +.PP +Since Qhull uses floating point arithmetic, roundoff error may occur for each +calculation. This causes problems +for most geometric algorithms. +.PP +Qhull automatically sets option 'C\-0' in 2\[hy]d, 3\[hy]d, and 4\[hy]d, or +option 'Qx' in 5\[hy]d and higher. These options handle precision problems +by merging facets. Alternatively, use option 'QJ' to joggle the +input. +.PP +With 'C\-0', Qhull merges non\[hy]convex +facets while constructing the hull. The remaining facets are +clearly convex. With 'Qx', Qhull merges +coplanar horizon facets, flipped facets, concave facets and +duplicated ridges. It merges coplanar facets after constructing +the hull. +With 'Qx', coplanar points may be missed, but it +appears to be unlikely. +.PP +To guarantee triangular output, joggle the input with option 'QJ'. Facet +merging will not occur. +.SH OPTIONS +.PP +To get a list of the most important options, execute 'qhull' by itself. +To get a complete list of options, +execute 'qhull \-'. +To get a complete, concise list of options, execute 'qhull .'. + +Options can be in any order. +Capitalized options take an argument (except 'PG' and 'F' options). +Single letters are used for output formats and precision constants. The +other options are grouped into menus for other output formats ('F'), +Geomview output ('G'), +printing ('P'), Qhull control ('Q'), and tracing ('T'). +.TP +Main options: +.TP +default +Compute the convex hull of the input points. Report a summary of +the result. +.TP +d +Compute the Delaunay triangulation by lifting the input points to a +paraboloid. The 'o' option prints the input points and facets. +The 'QJ' option guarantees triangular output. The 'Ft' +option prints a triangulation. It adds points (the centrums) to non\[hy]simplicial +facets. +.TP +v +Compute the Voronoi diagram from the Delaunay triangulation. +The 'p' option prints the Voronoi vertices. +The 'o' option prints the Voronoi vertices and the +vertices in each Voronoi region. It lists regions in +site ID order. +The 'Fv' option prints each ridge of the Voronoi diagram. +The first or zero'th vertex +indicates the infinity vertex. Its coordinates are +qh_INFINITE (\-10.101). It indicates unbounded Voronoi +regions or degenerate Delaunay triangles. +.TP +Hn,n,... +Compute halfspace intersection about [n,n,0,...]. +The input is a set of halfspaces +defined in the same format as 'n', 'Fo', and 'Fi'. +Use 'Fp' to print the intersection points. Use 'Fv' +to list the intersection points for each halfspace. The +other output formats display the dual convex hull. + +The point [n,n,n,...] is a feasible point for the halfspaces, i.e., +a point that is inside all +of the halfspaces (Hx+b <= 0). The default coordinate value is 0. + +The input may start with a feasible point. If so, use 'H' by itself. +The input starts with a feasible point when the first number is the dimension, +the second number is "1", and the coordinates complete a line. The 'FV' +option produces a feasible point for a convex hull. +.TP +d Qu +Compute the furthest\[hy]site Delaunay triangulation from the upper +convex hull. The 'o' option prints the input points and facets. +The 'QJ' option guarantees triangular otuput. You can also use 'Ft' +to triangulate via the centrums of non\[hy]simplicial +facets. +.TP +v Qu +Compute the furthest\[hy]site Voronoi diagram. +The 'p' option prints the Voronoi vertices. +The 'o' option prints the Voronoi vertices and the +vertices in each Voronoi region. +The 'Fv' option prints each ridge of the Voronoi diagram. +The first or zero'th vertex +indicates the infinity vertex at infinity. Its coordinates are +qh_INFINITE (\-10.101). It indicates unbounded Voronoi regions +and degenerate Delaunay triangles. +.PP +.TP +Input/Output options: +.TP +f +Print out all facets and all fields of each facet. +.TP +G +Output the hull in Geomview format. For imprecise hulls, +Geomview displays the inner and outer hull. Geomview can also +display points, ridges, vertices, coplanar points, and +facet intersections. See below for a list of options. + +For Delaunay triangulations, 'G' displays the +corresponding paraboloid. For halfspace intersection, 'G' displays the +dual polytope. +.TP +i +Output the incident vertices for each facet. +Qhull prints the number of facets followed by the +vertices of each facet. One facet is printed per line. The numbers +are the 0\[hy]relative indices of the corresponding input points. +The facets +are oriented. + +In 4d and higher, +Qhull triangulates non\[hy]simplicial facets. Each apex (the first vertex) is +a created point that corresponds to the facet's centrum. Its index is greater +than the indices of the input points. Each base +corresponds to a simplicial ridge between two facets. +To print the vertices without triangulation, use option 'Fv'. +.TP +m +Output the hull in Mathematica format. Qhull writes a Mathematica file for 2\[hy]d and 3\[hy]d +convex hulls and for 2\[hy]d Delaunay triangulations. Qhull produces a list of objects +that you can assign to a variable in Mathematica, for example: +"list= << <outputfilename> ". If the object is 2\[hy]d, it can be +visualized by "Show[Graphics[list]] ". For 3\[hy]d objects the command is +"Show[Graphics3D[list]]". +.TP +n +Output the normal equation for each facet. +Qhull prints the dimension (plus one), the number of facets, +and the normals for each facet. The facet's offset follows its +normal coefficients. +.TP +o +Output the facets in OFF file format. +Qhull prints the dimension, number of points, number +of facets, and number of ridges. Then it prints the coordinates of +the input points and the vertices for each facet. Each facet is on +a separate line. The first number is the number of vertices. The +remainder are the indices of the corresponding points. The vertices are +oriented in 2\[hy]d, 3\[hy]d, and in simplicial facets. + +For 2\[hy]d Voronoi diagrams, +the vertices are sorted by adjacency, but not oriented. In 3\[hy]d and higher, +the Voronoi vertices are sorted by index. +See the 'v' option for more information. +.TP +p +Output the coordinates of each vertex point. +Qhull prints the dimension, the number of points, +and the coordinates for each vertex. +With the 'Gc' and 'Gi' options, it also prints coplanar +and interior points. For Voronoi diagrams, it prints the coordinates +of each Voronoi vertex. +.TP +s +Print a summary to stderr. If no output options +are specified at all, a summary goes to stdout. The summary lists +the number of input points, the dimension, the number of vertices +in the convex hull, the number of facets in the convex hull, the +number of good facets (if 'Pg'), and statistics. + +The last two statistics (if needed) measure the maximum distance +from a point or vertex to a +facet. The number in parenthesis (e.g., 2.1x) is the ratio between the +maximum distance and the worst\[hy]case distance due to merging +two simplicial facets. +.PP +.TP +Precision options +.TP +An +Maximum angle given as a cosine. If the angle between a pair of facet +normals +is greater than n, Qhull merges one of the facets into a neighbor. +If 'n' is negative, Qhull tests angles after adding +each point to the hull (pre\[hy]merging). +If 'n' is positive, Qhull tests angles after +constructing the hull (post\[hy]merging). +Both pre\[hy] and post\[hy]merging can be defined. + +Option 'C0' or 'C\-0' is set if the corresponding 'Cn' or 'C\-n' +is not set. If 'Qx' +is set, then 'A\-n' and 'C\-n' are checked after the hull is constructed +and before 'An' and 'Cn' are checked. +.TP +Cn +Centrum radius. +If a centrum is less than n below a neighboring facet, Qhull merges one +of the facets. +If 'n' is negative or '\-0', Qhull tests and merges facets after adding +each point to the hull. This is called "pre\[hy]merging". If 'n' is positive, +Qhull tests for convexity after constructing the hull ("post\[hy]merging"). +Both pre\[hy] and post\[hy]merging can be defined. + +For 5\[hy]d and higher, 'Qx' should be used +instead of 'C\-n'. Otherwise, most or all facets may be merged +together. +.TP +En +Maximum roundoff error for distance computations. +.TP +Rn +Randomly perturb distance computations up to +/\- n * max_coord. +This option perturbs every distance, hyperplane, and angle computation. +To use time as the random number seed, use option 'QR\-1'. +.TP +Vn +Minimum distance for a facet to be visible. +A facet is visible if the distance from the point to the +facet is greater than 'Vn'. + +Without merging, the default value for 'Vn' is the round\[hy]off error ('En'). +With merging, the default value is the pre\[hy]merge centrum ('C\-n') in 2\[hy]d or +3\[hy]d, or three times that in other dimensions. If the outside width +is specified ('Wn'), the maximum, default value for 'Vn' is 'Wn'. +.TP +Un +Maximum distance below a facet for a point to be coplanar to the facet. The +default value is 'Vn'. +.TP +Wn +Minimum outside width of the hull. Points are added to the convex hull +only if they are clearly outside of a facet. A point is outside of a +facet if its distance to the facet is greater than 'Wn'. The normal +value for 'Wn' is 'En'. If the user specifies pre\[hy]merging and +does not set 'Wn', than 'Wn' is set +to the premerge 'Cn' and maxcoord*(1\-An). +.PP +.TP +Additional input/output formats +.TP +Fa +Print area for each facet. +For Delaunay triangulations, the area is the area of the triangle. +For Voronoi diagrams, the area is the area of the dual facet. +Use 'PAn' for printing the n largest facets, and option 'PFn' for +printing facets larger than 'n'. + +The area for non\[hy]simplicial facets is the sum of the +areas for each ridge to the centrum. Vertices far below +the facet's hyperplane are ignored. +The reported area may be significantly less than the actual area. +.TP +FA +Compute the total area and volume for option 's'. It is an approximation +for non\[hy]simplicial facets (see 'Fa'). +.TP +Fc +Print coplanar points for each facet. The output starts with the +number of facets. Then each facet is printed one per line. Each line +is the number of coplanar points followed by the point ids. +Option 'Qi' includes the interior points. Each coplanar point (interior point) is +assigned to the facet it is furthest above (resp., least below). +.TP +FC +Print centrums for each facet. The output starts with the +dimension followed by the number of facets. +Then each facet centrum is printed, one per line. +.TP +Fd +Read input in cdd format with homogeneous points. +The input starts with comments. The first comment is reported in +the summary. +Data starts after a "begin" line. The next line is the number of points +followed by the dimension+1 and "real" or "integer". Then the points +are listed with a leading "1" or "1.0". The data ends with an "end" line. + +For halfspaces ('Fd Hn,n,...'), the input format is the same. Each halfspace +starts with its offset. The sign of the offset is the opposite of Qhull's +convention. +.TP +FD +Print normals ('n', 'Fo', 'Fi') or points ('p') in cdd format. +The first line is the command line that invoked Qhull. +Data starts with a "begin" line. The next line is the number of normals or points +followed by the dimension+1 and "real". Then the normals or points +are listed with the offset before the coefficients. The offset for points is +1.0. The offset for normals has the opposite sign. +The data ends with an "end" line. +.TP +FF +Print facets (as in 'f') without printing the ridges. +.TP +Fi +Print inner planes for each facet. The inner plane is below all vertices. +.TP +Fi +Print separating hyperplanes for bounded, inner regions of the Voronoi +diagram. The first line is the number +of ridges. Then each hyperplane is printed, one per line. A line starts +with the number of indices and floats. The first pair lists +adjacent input +sites, the next d floats are the normalized coefficients for the hyperplane, +and the last float is the offset. The hyperplane is oriented toward 'QVn' +(if defined), or the first input site of the pair. Use 'Tv' to +verify that the hyperplanes are perpendicular bisectors. Use 'Fo' for +unbounded regions, and 'Fv' for the corresponding Voronoi vertices. +.TP +FI +Print facet identifiers. +.TP +Fm +Print number of merges for each facet. At most 511 merges are reported for +a facet. See 'PMn' for printing the facets with the most merges. +.TP +FM +Output the hull in Maple format. Qhull writes a Maple +file for 2\[hy]d and 3\[hy]d +convex hulls and for 2\[hy]d Delaunay triangulations. Qhull produces a '.mpl' +file for displaying with display3d(). +.TP +Fn +Print neighbors for each facet. The output starts with the number of facets. +Then each facet is printed one per line. Each line +is the number of neighbors followed by an index for each neighbor. The indices +match the other facet output formats. + +A negative index indicates an unprinted +facet due to printing only good facets ('Pg'). It is the negation of the facet's +ID (option 'FI'). +For example, negative indices are used for facets +"at infinity" in the Delaunay triangulation. +.TP +FN +Print vertex neighbors or coplanar facet for each point. +The first line is the number +of points. Then each point is printed, one per line. If the +point is coplanar, the line is "1" followed by the facet's ID. +If the point is +not a selected vertex, the line is "0". +Otherwise, each line is the number of +neighbors followed by the corresponding facet indices (see 'Fn'). +.TP +Fo +Print outer planes for each facet in the same format as 'n'. +The outer plane is above all points. +.TP +Fo +Print separating hyperplanes for unbounded, outer regions of the Voronoi +diagram. The first line is the number +of ridges. Then each hyperplane is printed, one per line. A line starts +with the number of indices and floats. The first pair lists +adjacent input +sites, the next d floats are the normalized coefficients for the hyperplane, +and the last float is the offset. The hyperplane is oriented toward 'QVn' +(if defined), or the first input site of the pair. Use 'Tv' to +verify that the hyperplanes are perpendicular bisectors. Use 'Fi' for +bounded regions, and 'Fv' for the corresponding Voronoi vertices. +.TP +FO +List all options to stderr, including the default values. Additional 'FO's +are printed to stdout. +.TP +Fp +Print points for halfspace intersections (option 'Hn,n,...'). Each +intersection corresponds to a facet of the dual polytope. +The "infinity" point [\-10.101,\-10.101,...] +indicates an unbounded intersection. +.TP +FP +For each coplanar point ('Qc') print the point ID of the nearest vertex, +the point ID, the facet ID, and the distance. +.TP +FQ +Print command used for qhull and input. +.TP +Fs +Print a summary. The first line consists of the number of integers ("8"), +followed by the dimension, the number of points, the number of vertices, +the number of facets, the number of vertices selected for output, the +number of facets selected for output, the number of coplanar points selected +for output, number of simplicial, unmerged facets in output + +The second line consists of the number of reals ("2"), +followed by the maxmimum offset to an outer plane and and minimum offset to +an inner plane. Roundoff is included. Later +versions of Qhull may produce additional integers or reals. +.TP +FS +Print the size of the hull. The first line consists of the number of integers ("0"). +The second line consists of the number of reals ("2"), +followed by the total facet area, and the total volume. +Later +versions of Qhull may produce additional integers or reals. + +The total volume measures the volume +of the intersection of the halfspaces defined by each facet. +Both area and volume are +approximations for non\[hy]simplicial facets. See option 'Fa'. +.TP +Ft +Print a triangulation with added points for non\[hy]simplicial +facets. The first line is the dimension and the second line is the +number of points and the number of facets. The points follow, one +per line, then the facets follow as a list of point indices. With option 'Qz', the +points include the point\[hy]at\[hy]infinity. +.TP +Fv +Print vertices for each facet. The first line is the number +of facets. Then each facet is printed, one per line. Each line is +the number of vertices followed by the corresponding point ids. Vertices +are listed in the order they were added to the hull (the last one is first). +.TP +Fv +Print all ridges of a Voronoi diagram. The first line is the number +of ridges. Then each ridge is printed, one per line. A line starts +with the number of indices. The first pair lists adjacent input +sites, the remaining indices list Voronoi vertices. Vertex '0' indicates +the vertex\[hy]at\[hy]infinity (i.e., an unbounded ray). In 3\[hy]d, the vertices +are listed in order. See 'Fi' and 'Fo' for separating hyperplanes. +.TP +FV +Print average vertex. The average vertex is a feasible point +for halfspace intersection. +.TP +Fx +List extreme points (vertices) of the convex hull. The first line +is the number of points. The other lines give the indices of the +corresponding points. The first point is '0'. In 2\[hy]d, the points +occur in counter\[hy]clockwise order; otherwise they occur in input order. +For Delaunay triangulations, 'Fx' lists the extreme points of the +input sites. The points are unordered. +.PP +.TP +Geomview options +.TP +G +Produce a file for viewing with Geomview. Without other options, +Qhull displays edges in 2\[hy]d, outer planes in 3\[hy]d, and ridges in 4\[hy]d. +A ridge can be +explicit or implicit. An explicit ridge is a dim\-1 dimensional simplex +between two facets. +In 4\[hy]d, the explicit ridges are triangles. +When displaying a ridge in 4\[hy]d, Qhull projects the ridge's vertices to +one of its facets' hyperplanes. +Use 'Gh' to +project ridges to the intersection of both hyperplanes. +.TP +Ga +Display all input points as dots. +.TP +Gc +Display the centrum for each facet in 3\[hy]d. The centrum is defined by a +green radius sitting on a blue plane. The plane corresponds to the +facet's hyperplane. +The radius is defined by 'C\-n' or 'Cn'. +.TP +GDn +Drop dimension n in 3\[hy]d or 4\[hy]d. The result is a 2\[hy]d or 3\[hy]d object. +.TP +Gh +Display hyperplane intersections in 3\[hy]d and 4\[hy]d. In 3\[hy]d, the +intersection is a black line. It lies on two neighboring hyperplanes +(c.f., the blue squares associated with centrums ('Gc')). In 4\[hy]d, +the ridges are projected to the intersection of both hyperplanes. +.TP +Gi +Display inner planes in 2\[hy]d and 3\[hy]d. The inner plane of a facet +is below all of its vertices. It is parallel to the facet's hyperplane. +The inner plane's color is the opposite (1\-r,1\-g,1\-b) of the outer +plane. Its edges are determined by the vertices. +.TP +Gn +Do not display inner or outer planes. By default, +Geomview displays the precise plane (no merging) or both +inner and output planes (merging). Under merging, Geomview does +not display the inner plane if the +the difference between inner and outer is too small. +.TP +Go +Display outer planes in 2\[hy]d and 3\[hy]d. The outer plane of a facet +is above all input points. It is parallel to the facet's hyperplane. +Its color is determined by the facet's normal, and its +edges are determined by the vertices. +.TP +Gp +Display coplanar points and vertices as radii. A radius defines a ball +which corresponds to the imprecision of the point. The imprecision is +the maximum of the roundoff error, the centrum radius, and maxcoord * +(1\-An). It is at least 1/20'th of the maximum coordinate, +and ignores post\[hy]merging if pre\[hy]merging is done. +.TP +Gr +Display ridges in 3\[hy]d. A ridge connects the two vertices that are shared +by neighboring facets. Ridges are always displayed in 4\[hy]d. +.TP +Gt +A 3\[hy]d Delaunay triangulation looks like a convex hull with interior +facets. Option 'Gt' removes the outside ridges to reveal the outermost +facets. It automatically sets options 'Gr' and 'GDn'. +.TP +Gv +Display vertices as spheres. The radius of the sphere corresponds to +the imprecision of the data. See 'Gp' for determining the radius. +.PP +.TP +Print options +.TP +PAn +Only the n largest facets are marked good for printing. +Unless 'PG' is set, 'Pg' is automatically set. +.TP +Pdk:n +Drop facet from output if normal[k] <= n. The option 'Pdk' uses the +default value of 0 for n. +.TP +PDk:n +Drop facet from output if normal[k] >= n. The option 'PDk' uses the +default value of 0 for n. +.TP +PFn +Only facets with area at least 'n' are marked good for printing. +Unless 'PG' is set, 'Pg' is automatically set. +.TP +Pg +Print only good facets. A good facet is either visible from a point +(the 'QGn' option) or includes a point (the 'QVn' option). It also meets the +requirements of 'Pdk' and 'PDk' options. Option 'Pg' is automatically +set for options 'PAn' and 'PFn'. +.TP +PG +Print neighbors of good facets. +.TP +PMn +Only the n facets with the most merges are marked good for printing. +Unless 'PG' is set, 'Pg' is automatically set. +.TP +Po +Force output despite precision problems. Verify ('Tv') does not check +coplanar points. +Flipped facets are reported and concave facets are counted. +If 'Po' is used, points are not +partitioned into flipped facets and a flipped facet is always visible +to a point. +Also, if an error occurs before the completion of Qhull and tracing is +not active, 'Po' outputs a neighborhood of the erroneous facets +(if any). +.TP +Pp +Do not report precision problems. +.PP +.TP +Qhull control options +.TP +Qbk:0Bk:0 +Drop dimension k from the input points. This allows the user to +take convex hulls of sub\[hy]dimensional objects. It happens before +the Delaunay and Voronoi transformation. +.TP +QbB +Scale the input points to fit the unit cube. After scaling, the lower +bound will be \-0.5 and the upper bound +0.5 in all dimensions. +For Delaunay and +Voronoi diagrams, scaling happens after projection to the paraboloid. +Under precise +arithmetic, scaling does not change the topology of the convex hull. +.TP +Qbb +Scale the last coordinate to [0, m] where m is the maximum absolute +value of the other coordinates. For Delaunay and +Voronoi diagrams, scaling happens after projection to the paraboloid. +It reduces roundoff error for inputs with integer coordinates. +Under precise +arithmetic, scaling does not change the topology of the convex hull. +.TP +Qbk:n +Scale the k'th coordinate of the input points. After scaling, the lower +bound of the input points will be n. 'Qbk' scales to \-0.5. +.TP +QBk:n +Scale the k'th coordinate of the input points. After scaling, the upper +bound will be n. 'QBk' scales to +0.5. +.TP +Qc +Keep coplanar points with the nearest facet. Output +formats 'p', 'f', 'Gp', 'Fc', 'FN', and 'FP' will print the points. +.TP +Qf +Partition points to the furthest outside facet. +.TP +Qg +Only build good facets. With the 'Qg' option, Qhull will only build +those facets that it needs to determine the good facets in the output. +See 'QGn', 'QVn', and 'PdD' for defining good facets, and 'Pg' and 'PG' +for printing good facets and their neighbors. +.TP +QGn +A facet is good (see 'Qg' and 'Pg') if it is visible from point n. If n < 0, a facet is +good if it is not visible from point n. Point n is not added to the +hull (unless 'TCn' or 'TPn'). +With rbox, use the 'Pn,m,r' option to define your point; it +will be point 0 (QG0). +.TP +Qi +Keep interior points with the nearest facet. +Output formats 'p', 'f', 'Gp', 'FN', 'FP', and 'Fc' will print the points. +.TP +QJn +Joggle each input coordinate by adding a random number in [\-n,n]. If a +precision error occurs, then qhull increases n and tries again. It does +not increase n beyond a certain value, and it stops after a certain number +of attempts [see user.h]. Option 'QJ' +selects a default value for n. The output will be simplicial. For +Delaunay triangulations, 'QJn' sets 'Qbb' to scale the last coordinate +(not if 'Qbk:n' or 'QBk:n' is set). +\'QJn' is deprecated for Voronoi diagrams. See also 'Qt'. +.TP +Qm +Only process points that would otherwise increase max_outside. Other +points are treated as coplanar or interior points. +.TP +Qr +Process random outside points instead of furthest ones. This makes +Qhull equivalent to the randomized incremental algorithms. CPU time +is not reported since the randomization is inefficient. +.TP +QRn +Randomly rotate the input points. If n=0, use time as the random number seed. +If n>0, use n as the random number seed. If n=\-1, don't rotate but use +time as the random number seed. For Delaunay triangulations ('d' and 'v'), +rotate about the last axis. +.TP +Qs +Search all points for the initial simplex. +.TP +Qt +Triangulated output. Triangulate all non\[hy]simplicial facets. +\'Qt' is deprecated for Voronoi diagrams. See also 'Qt'. +.TP +Qv +Test vertex neighbors for convexity after post\[hy]merging. +To use the 'Qv' option, you also need to set a merge option +(e.g., 'Qx' or 'C\-0'). +.TP +QVn +A good facet (see 'Qg' and 'Pg') includes point n. If n<0, then a good facet does not +include point n. The point is either in the initial simplex or it +is the first point added to the hull. Option 'QVn' may not be used with merging. +.TP +Qx +Perform exact merges while building the hull. The "exact" merges +are merging a point into a coplanar facet (defined by 'Vn', 'Un', +and 'C\-n'), merging concave facets, merging duplicate ridges, and +merging flipped facets. Coplanar merges and angle coplanar merges ('A\-n') +are not performed. Concavity testing is delayed until a merge occurs. + +After +the hull is built, all coplanar merges are performed (defined by 'C\-n' +and 'A\-n'), then post\[hy]merges are performed +(defined by 'Cn' and 'An'). +.TP +Qz +Add a point "at infinity" that is above the paraboloid for Delaunay triangulations +and Voronoi diagrams. This reduces precision problems and allows the triangulation +of cospherical points. +.PP +.TP +Qhull experiments and speedups +.TP +Q0 +Turn off pre\[hy]merging as a default option. +With 'Q0'/'Qx' and without explicit pre\[hy]merge options, Qhull +ignores precision issues while constructing the convex hull. This +may lead to precision errors. If so, a descriptive warning is +generated. +.TP +Q1 +With 'Q1', Qhull sorts merges by type (coplanar, angle coplanar, concave) +instead of by angle. +.TP +Q2 +With 'Q2', Qhull merges all facets at once instead of using +independent sets of merges and then retesting. +.TP +Q3 +With 'Q3', Qhull does not remove redundant vertices. +.TP +Q4 +With 'Q4', Qhull avoids merges of an old facet into a new facet. +.TP +Q5 +With 'Q5', Qhull does not correct outer planes at the end. The +maximum outer plane is used instead. +.TP +Q6 +With 'Q6', Qhull does not pre\[hy]merge concave or coplanar facets. +.TP +Q7 +With 'Q7', Qhull processes facets in depth\[hy]first order instead of +breadth\[hy]first order. +.TP +Q8 +With 'Q8' and merging, Qhull does not retain near\[hy]interior points for adjusting +outer planes. 'Qc' will probably retain +all points that adjust outer planes. +.TP +Q9 +With 'Q9', Qhull processes the furthest of all outside sets at each iteration. +.TP +Q10 +With 'Q10', Qhull does not use special processing for narrow distributions. +.TP +Q11 +With 'Q11', Qhull copies normals and recompute centrums for tricoplanar facets. +.TP +Q12 +With 'Q12', Qhull does not report a very wide merge due to a duplicated ridge with nearly coincident vertices +.PP +.TP +Trace options +.TP +Tn +Trace at level n. Qhull includes full execution tracing. 'T\-1' +traces events. 'T1' traces +the overall execution of the program. 'T2' and 'T3' trace overall +execution and geometric and topological events. 'T4' traces the +algorithm. 'T5' includes information about memory allocation and +Gaussian elimination. +.TP +Ta +Annotate output with codes that identify the +corresponding qh_fprintf() statement. +.TP +Tc +Check frequently during execution. This will catch most inconsistency +errors. +.TP +TCn +Stop Qhull after building the cone of new facets for point n. The +output for 'f' includes the cone and the old hull. +See also 'TVn'. +.TP +TFn +Report progress whenever more than n facets are created +During post\[hy]merging, 'TFn' +reports progress after more than n/2 merges. +.TP +TI file +Input data from 'file'. The filename may not include spaces or +quotes. +.TP +TO file +Output results to 'file'. The name may be enclosed in single +quotes. +.TP +TPn +Turn on tracing when point n is added to the hull. Trace +partitions of point n. If used with TWn, turn off +tracing after adding point n to the hull. +.TP +TRn +Rerun qhull n times. Usually used with 'QJn' to determine the +probability that a given joggle will fail. +.TP +Ts +Collect statistics and print to stderr at the end of execution. +.TP +Tv +Verify the convex hull. This checks the topological structure, facet +convexity, and point inclusion. +If precision problems occurred, facet convexity is tested whether or +not 'Tv' is selected. +Option 'Tv' does not check point inclusion if forcing output with 'Po', +or if 'Q5' is set. + +For point inclusion testing, Qhull verifies that all points are below +all outer planes (facet\->maxoutside). Point inclusion is exhaustive +if merging or if the facet\[hy]point product is small enough; +otherwise Qhull verifies each point with a directed +search (qh_findbest). + +Point inclusion testing occurs after producing output. It prints +a message to stderr unless option 'Pp' is used. This +allows the user to interrupt Qhull without changing the output. +.TP +TVn +Stop Qhull after adding point n. If n < 0, stop Qhull before adding +point n. Output shows the hull at this time. See also 'TCn' +.TP +TMn +Turn on tracing at n'th merge. +.TP +TWn +Trace merge facets when the width is greater than n. +.TP +Tz +Redirect stderr to stdout. +.PP +.SH BUGS +Please report bugs to Brad Barber at qhull_bug@qhull.org. + +If Qhull does not compile, it is due to an incompatibility between your +system and ours. The first thing to check is that your compiler is +ANSI standard. If it is, check the man page for the best options, or +find someone to help you. If you locate the cause of your problem, +please send email since it might help others. + +If Qhull compiles but crashes on the test case (rbox D4), there's +still incompatibility between your system and ours. Typically it's +been due to mem.c and memory alignment. You can use qh_NOmem in mem.h +to turn off memory management. Please let us know if you figure out +how to fix these problems. + +If you do find a problem, try to simplify it before reporting the +error. Try different size inputs to locate the smallest one that +causes an error. You're welcome to hunt through the code using the +execution trace as a guide. This is especially true if you're +incorporating Qhull into your own program. + +When you do report an error, please attach a data set to the +end of your message. This allows us to see the error for ourselves. +Qhull is maintained part\[hy]time. +.PP +.SH E\[hy]MAIL +Please send correspondence to qhull@qhull.org and report bugs to +qhull_bug@qhull.org. Let us know how you use Qhull. If you +mention it in a paper, please send the reference and an abstract. + +If you would like to get Qhull announcements (e.g., a new version) +and news (any bugs that get fixed, etc.), let us know and we will add you to +our mailing list. If you would like to communicate with other +Qhull users, we will add you to the qhull_users alias. +For Internet news about geometric algorithms and convex hulls, look at +comp.graphics.algorithms and sci.math.num\-analysis + +.SH SEE ALSO +rbox(1) + +Barber, C. B., D.P. Dobkin, and H.T. Huhdanpaa, +"The Quickhull Algorithm for Convex Hulls," ACM +Trans. on Mathematical Software, 22(4):469\[en]483, Dec. 1996. +http://portal.acm.org/citation.cfm?doid=235815.235821 +http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.117.405 + +Clarkson, K.L., K. Mehlhorn, and R. Seidel, "Four results on randomized +incremental construction," Computational Geometry: Theory and Applications, +vol. 3, p. 185\[en]211, 1993. + +Preparata, F. and M. Shamos, Computational +Geometry, Springer\[hy]Verlag, New York, 1985. + +.PP +.SH AUTHORS +.nf + C. Bradford Barber Hannu Huhdanpaa + bradb@shore.net hannu@qhull.org + + .fi + +.SH ACKNOWLEDGEMENTS + +A special thanks to Albert Marden, Victor Milenkovic, the Geometry Center, +Harvard University, and Endocardial Solutions, Inc. for supporting this work. + +Qhull 1.0 and 2.0 were developed under National Science Foundation +grants NSF/DMS\[hy]8920161 and NSF\[hy]CCR\[hy]91\[hy]15793 750\[hy]7504. David Dobkin +guided the original work at Princeton University. +If you find it useful, please let us know. + +The Geometry Center is supported by grant DMS\[hy]8920161 from the National +Science Foundation, by grant DOE/DE\[hy]FG02\[hy]92ER25137 from the Department +of Energy, by the University of Minnesota, and by Minnesota Technology, Inc. + +Qhull is available from http://www.qhull.org diff --git a/xs/src/qhull/html/qhull.txt b/xs/src/qhull/html/qhull.txt new file mode 100644 index 000000000..03753547e --- /dev/null +++ b/xs/src/qhull/html/qhull.txt @@ -0,0 +1,1263 @@ + + + +qhull(1) qhull(1) + + +NAME + qhull - convex hull, Delaunay triangulation, Voronoi dia- + gram, halfspace intersection about a point, hull volume, facet area + +SYNOPSIS + qhull- compute convex hulls and related structures + input (stdin): dimension, #points, point coordinates + first comment (non-numeric) is listed in the summary + halfspace: use dim plus one with offsets after coefficients + + options (qh-quick.htm): + d - Delaunay triangulation by lifting points to a paraboloid + v - Voronoi diagram via the Delaunay triangulation + H1,1 - Halfspace intersection about [1,1,0,...] + d Qu - Furthest-site Delaunay triangulation (upper convex hull) + v Qu - Furthest-site Voronoi diagram + QJ - Joggle the input to avoid precision problems + . - concise list of all options + - - one-line description of all options + + Output options (subset): + FA - compute total area and volume + Fx - extreme points (convex hull vertices) + G - Geomview output (2-d, 3-d and 4-d) + Fp - halfspace intersection coordinates + m - Mathematica output (2-d and 3-d) + n - normals with offsets + o - OFF file format (if Voronoi, outputs regions) + TO file- output results to file, may be enclosed in single quotes + f - print all fields of all facets + s - summary of results (default) + Tv - verify result: structure, convexity, and point inclusion + p - vertex coordinates + i - vertices incident to each facet + + example: + rbox 1000 s | qhull Tv s FA + + - html manual: index.htm + - installation: README.txt + - see also: COPYING.txt, REGISTER.txt, Changes.txt + - WWW: <http://www.qhull.org> + - GIT: <git@github.com:qhull/qhull.git> + - mirror: <http://www6.uniovi.es/ftp/pub/mirrors/geom.umn.edu/software/ghindex.html> + - news: <http://www.qhull.org/news> + - Geomview: <http://www.geomview.org> + - news group: <news:comp.graphics.algorithms> + - FAQ: <http://www.faqs.org/faqs/graphics/algorithms-faq/> + - email: qhull@qhull.org + - bug reports: qhull_bug@qhull.org + + + + +Geometry Center 2003/12/30 1 + + + + + +qhull(1) qhull(1) + + + The sections are: + - INTRODUCTION + - DESCRIPTION, a description of Qhull + - IMPRECISION, how Qhull handles imprecision + - OPTIONS + - Input and output options + - Additional input/output formats + - Precision options + - Geomview options + - Print options + - Qhull options + - Trace options + - BUGS + - E-MAIL + - SEE ALSO + - AUTHORS + - ACKNOWLEGEMENTS + + This man page briefly describes all Qhull options. Please + report any mismatches with Qhull's html manual (qh- + man.htm). + + + +INTRODUCTION + Qhull is a general dimension code for computing convex + hulls, Delaunay triangulations, Voronoi diagram, furthest- + site Voronoi diagram, furthest-site Delaunay triangula- + tions, and halfspace intersections about a point. It + implements the Quickhull algorithm for computing the con- + vex hull. Qhull handles round-off errors from floating + point arithmetic. It can approximate a convex hull. + + The program includes options for hull volume, facet area, + partial hulls, input transformations, randomization, trac- + ing, multiple output formats, and execution statistics. + The program can be called from within your application. + You can view the results in 2-d, 3-d and 4-d with + Geomview. + + +DESCRIPTION + The format of input is the following: first line contains + the dimension, second line contains the number of input + points, and point coordinates follow. The dimension and + number of points can be reversed. Comments and line + breaks are ignored. A comment starts with a non-numeric + character and continues to the end of line. The first + comment is reported in summaries and statistics. Error + reporting is better if there is one point per line. + + The default printout option is a short summary. There are + many other output formats. + + + + +Geometry Center 2003/12/30 2 + + + + + +qhull(1) qhull(1) + + + Qhull implements the Quickhull algorithm for convex hull. + This algorithm combines the 2-d Quickhull algorithm with + the n-d beneath-beyond algorithm [c.f., Preparata & Shamos + '85]. It is similar to the randomized algorithms of + Clarkson and others [Clarkson et al. '93]. The main + advantages of Quickhull are output sensitive performance, + reduced space requirements, and automatic handling of pre- + cision problems. + + The data structure produced by Qhull consists of vertices, + ridges, and facets. A vertex is a point of the input set. + A ridge is a set of d vertices and two neighboring facets. + For example in 3-d, a ridge is an edge of the polyhedron. + A facet is a set of ridges, a set of neighboring facets, a + set of incident vertices, and a hyperplane equation. For + simplicial facets, the ridges are defined by the vertices + and neighboring facets. When Qhull merges two facets, it + produces a non-simplicial facet. A non-simplicial facet + has more than d neighbors and may share more than one + ridge with a neighbor. + + +IMPRECISION + Since Qhull uses floating point arithmetic, roundoff error + may occur for each calculation. This causes problems for + most geometric algorithms. + + Qhull automatically sets option 'C-0' in 2-d, 3-d, and + 4-d, or option 'Qx' in 5-d and higher. These options han- + dle precision problems by merging facets. Alternatively, + use option 'QJ' to joggle the input. + + With 'C-0', Qhull merges non-convex facets while con- + structing the hull. The remaining facets are clearly con- + vex. With 'Qx', Qhull merges coplanar horizon facets, + flipped facets, concave facets and duplicated ridges. It + merges coplanar facets after constructing the hull. With + 'Qx', coplanar points may be missed, but it appears to be + unlikely. + + To guarantee triangular output, joggle the input with + option 'QJ'. Facet merging will not occur. + +OPTIONS + To get a list of the most important options, execute + 'qhull' by itself. To get a complete list of options, + execute 'qhull -'. To get a complete, concise list of + options, execute 'qhull .'. + + Options can be in any order. Capitalized options take an + argument (except 'PG' and 'F' options). Single letters + are used for output formats and precision constants. The + other options are grouped into menus for other output for- + mats ('F'), Geomview output ('G'), printing ('P'), Qhull + + + +Geometry Center 2003/12/30 3 + + + + + +qhull(1) qhull(1) + + + control ('Q'), and tracing ('T'). + + Main options: + + default + Compute the convex hull of the input points. + Report a summary of the result. + + d Compute the Delaunay triangulation by lifting the + input points to a paraboloid. The 'o' option + prints the input points and facets. The 'QJ' + option guarantees triangular output. The 'Ft' + option prints a triangulation. It adds points (the + centrums) to non-simplicial facets. + + v Compute the Voronoi diagram from the Delaunay tri- + angulation. The 'p' option prints the Voronoi ver- + tices. The 'o' option prints the Voronoi vertices + and the vertices in each Voronoi region. It lists + regions in site id order. The 'Fv' option prints + each ridge of the Voronoi diagram. The first or + zero'th vertex indicates the infinity vertex. Its + coordinates are qh_INFINITE (-10.101). It indi- + cates unbounded Voronoi regions or degenerate + Delaunay triangles. + + Hn,n,... + Compute halfspace intersection about [n,n,0,...]. + The input is a set of halfspaces defined in the + same format as 'n', 'Fo', and 'Fi'. Use 'Fp' to + print the intersection points. Use 'Fv' to list + the intersection points for each halfspace. The + other output formats display the dual convex hull. + + The point [n,n,n,...] is a feasible point for the + halfspaces, i.e., a point that is inside all of the + halfspaces (Hx+b <= 0). The default coordinate + value is 0. + + The input may start with a feasible point. If so, + use 'H' by itself. The input starts with a feasi- + ble point when the first number is the dimension, + the second number is "1", and the coordinates com- + plete a line. The 'FV' option produces a feasible + point for a convex hull. + + d Qu Compute the furthest-site Delaunay triangulation + from the upper convex hull. The 'o' option prints + the input points and facets. The 'QJ' option guar- + antees triangular otuput. You can also use facets. + + v Qu Compute the furthest-site Voronoi diagram. The 'p' + option prints the Voronoi vertices. The 'o' option + prints the Voronoi vertices and the vertices in + + + +Geometry Center 2003/12/30 4 + + + + + +qhull(1) qhull(1) + + + each Voronoi region. The 'Fv' option prints each + ridge of the Voronoi diagram. The first or zero'th + vertex indicates the infinity vertex at infinity. + Its coordinates are qh_INFINITE (-10.101). It + indicates unbounded Voronoi regions and degenerate + Delaunay triangles. + + Qt Triangulated output. + + + Input/Output options: + + f Print out all facets and all fields of each facet. + + G Output the hull in Geomview format. For imprecise + hulls, Geomview displays the inner and outer hull. + Geomview can also display points, ridges, vertices, + coplanar points, and facet intersections. See + below for a list of options. + + For Delaunay triangulations, 'G' displays the cor- + responding paraboloid. For halfspace intersection, + 'G' displays the dual polytope. + + i Output the incident vertices for each facet. Qhull + prints the number of facets followed by the ver- + tices of each facet. One facet is printed per + line. The numbers are the 0-relative indices of + the corresponding input points. The facets are + oriented. + + In 4-d and higher, Qhull triangulates non-simpli- + cial facets. Each apex (the first vertex) is a + created point that corresponds to the facet's cen- + trum. Its index is greater than the indices of the + input points. Each base corresponds to a simpli- + cial ridge between two facets. To print the ver- + tices without triangulation, use option 'Fv'. + + m Output the hull in Mathematica format. Qhull + writes a Mathematica file for 2-d and 3-d convex + hulls and for 2-d Delaunay triangulations. Qhull + produces a list of objects that you can assign to a + variable in Mathematica, for example: "list= << + <outputfilename> ". If the object is 2-d, it can be + visualized by "Show[Graphics[list]] ". For 3-d + objects the command is "Show[Graphics3D[list]]". + + n Output the normal equation for each facet. Qhull + prints the dimension (plus one), the number of + facets, and the normals for each facet. The + facet's offset follows its normal coefficients. + + o Output the facets in OFF file format. Qhull prints + the dimension, number of points, number of facets, + and number of ridges. Then it prints the + + + +Geometry Center 2003/12/30 5 + + + + + +qhull(1) qhull(1) + + + coordinates of the input points and the vertices + for each facet. Each facet is on a separate line. + The first number is the number of vertices. The + remainder are the indices of the corresponding + points. The vertices are oriented in 2-d, 3-d, and + in simplicial facets. + + For 2-d Voronoi diagrams, the vertices are sorted + by adjacency, but not oriented. In 3-d and higher, + the Voronoi vertices are sorted by index. See the + 'v' option for more information. + + p Output the coordinates of each vertex point. Qhull + prints the dimension, the number of points, and the + coordinates for each vertex. With the 'Gc' and + 'Gi' options, it also prints coplanar and interior + points. For Voronoi diagrams, it prints the coor- + dinates of each Voronoi vertex. + + s Print a summary to stderr. If no output options + are specified at all, a summary goes to stdout. + The summary lists the number of input points, the + dimension, the number of vertices in the convex + hull, the number of facets in the convex hull, the + number of good facets (if 'Pg'), and statistics. + + The last two statistics (if needed) measure the + maximum distance from a point or vertex to a facet. + The number in parenthesis (e.g., 2.1x) is the ratio + between the maximum distance and the worst-case + distance due to merging two simplicial facets. + + + Precision options + + An Maximum angle given as a cosine. If the angle + between a pair of facet normals is greater than n, Qhull + merges one of the facets into a neighbor. If 'n' + is negative, Qhull tests angles after adding each + point to the hull (pre-merging). If 'n' is posi- + tive, Qhull tests angles after constructing the + hull (post-merging). Both pre- and post-merging + can be defined. + + Option 'C0' or 'C-0' is set if the corresponding + 'Cn' or 'C-n' is not set. If 'Qx' is set, then 'A- + n' and 'C-n' are checked after the hull is con- + structed and before 'An' and 'Cn' are checked. + + Cn Centrum radius. If a centrum is less than n below + a neighboring facet, Qhull merges one of the + facets. If 'n' is negative or '-0', Qhull tests + and merges facets after adding each point to the + hull. This is called "pre-merging". If 'n' is + + + +Geometry Center 2003/12/30 6 + + + + + +qhull(1) qhull(1) + + + positive, Qhull tests for convexity after con- + structing the hull ("post-merging"). Both pre- and + post-merging can be defined. + + For 5-d and higher, 'Qx' should be used instead of + 'C-n'. Otherwise, most or all facets may be merged + together. + + En Maximum roundoff error for distance computations. + + Rn Randomly perturb distance computations up to +/- n + * max_coord. This option perturbs every distance, + hyperplane, and angle computation. To use time as + the random number seed, use option 'QR-1'. + + Vn Minimum distance for a facet to be visible. A + facet is visible if the distance from the point to + the facet is greater than 'Vn'. + + Without merging, the default value for 'Vn' is the + round-off error ('En'). With merging, the default + value is the pre-merge centrum ('C-n') in 2-d or + 3--d, or three times that in other dimensions. If + the outside width is specified ('Wn'), the maximum, + default value for 'Vn' is 'Wn'. + + Un Maximum distance below a facet for a point to be + coplanar to the facet. The default value is 'Vn'. + + Wn Minimum outside width of the hull. Points are + added to the convex hull only if they are clearly + outside of a facet. A point is outside of a facet + if its distance to the facet is greater than 'Wn'. + The normal value for 'Wn' is 'En'. If the user + specifies pre-merging and does not set 'Wn', than + 'Wn' is set to the premerge 'Cn' and maxco- + ord*(1-An). + + + Additional input/output formats + + Fa Print area for each facet. For Delaunay triangula- + tions, the area is the area of the triangle. For + Voronoi diagrams, the area is the area of the dual + facet. Use 'PAn' for printing the n largest + facets, and option 'PFn' for printing facets larger + than 'n'. + + The area for non-simplicial facets is the sum of + the areas for each ridge to the centrum. Vertices + far below the facet's hyperplane are ignored. The + reported area may be significantly less than the + actual area. + + + + +Geometry Center 2003/12/30 7 + + + + + +qhull(1) qhull(1) + + + FA Compute the total area and volume for option 's'. + It is an approximation for non-simplicial facets + (see 'Fa'). + + Fc Print coplanar points for each facet. The output + starts with the number of facets. Then each facet + is printed one per line. Each line is the number + of coplanar points followed by the point ids. + Option 'Qi' includes the interior points. Each + coplanar point (interior point) is assigned to the + facet it is furthest above (resp., least below). + + FC Print centrums for each facet. The output starts + with the dimension followed by the number of + facets. Then each facet centrum is printed, one + per line. + + Fd Read input in cdd format with homogeneous points. + The input starts with comments. The first comment + is reported in the summary. Data starts after a + "begin" line. The next line is the number of + points followed by the dimension+1 and "real" or + "integer". Then the points are listed with a + leading "1" or "1.0". The data ends with an "end" + line. + + For halfspaces ('Fd Hn,n,...'), the input format is + the same. Each halfspace starts with its offset. + The sign of the offset is the opposite of Qhull's + convention. + + FD Print normals ('n', 'Fo', 'Fi') or points ('p') in + cdd format. The first line is the command line + that invoked Qhull. Data starts with a "begin" + line. The next line is the number of normals or + points followed by the dimension+1 and "real". + Then the normals or points are listed with the + offset before the coefficients. The offset for + points is 1.0. The offset for normals has the + opposite sign. The data ends with an "end" line. + + FF Print facets (as in 'f') without printing the + ridges. + + Fi Print inner planes for each facet. The inner plane + is below all vertices. + + Fi Print separating hyperplanes for bounded, inner + regions of the Voronoi diagram. The first line is + the number of ridges. Then each hyperplane is + printed, one per line. A line starts with the num- + ber of indices and floats. The first pair lists + adjacent input sites, the next d floats are the + normalized coefficients for the hyperplane, and the + + + +Geometry Center 2003/12/30 8 + + + + + +qhull(1) qhull(1) + + + last float is the offset. The hyperplane is ori- + ented toward verify that the hyperplanes are per- + pendicular bisectors. Use 'Fo' for unbounded + regions, and 'Fv' for the corresponding Voronoi + vertices. + + FI Print facet identifiers. + + Fm Print number of merges for each facet. At most 511 + merges are reported for a facet. See 'PMn' for + printing the facets with the most merges. + + FM Output the hull in Maple format. See 'm' + + Fn Print neighbors for each facet. The output starts + with the number of facets. Then each facet is + printed one per line. Each line is the number of + neighbors followed by an index for each neighbor. + The indices match the other facet output formats. + + A negative index indicates an unprinted facet due + to printing only good facets ('Pg'). It is the + negation of the facet's id (option 'FI'). For + example, negative indices are used for facets "at + infinity" in the Delaunay triangulation. + + FN Print vertex neighbors or coplanar facet for each + point. The first line is the number of points. + Then each point is printed, one per line. If the + point is coplanar, the line is "1" followed by the + facet's id. If the point is not a selected vertex, + the line is "0". Otherwise, each line is the num- + ber of neighbors followed by the corresponding + facet indices (see 'Fn'). + + Fo Print outer planes for each facet in the same for- + mat as 'n'. The outer plane is above all points. + + Fo Print separating hyperplanes for unbounded, outer + regions of the Voronoi diagram. The first line is + the number of ridges. Then each hyperplane is + printed, one per line. A line starts with the num- + ber of indices and floats. The first pair lists + adjacent input sites, the next d floats are the + normalized coefficients for the hyperplane, and the + last float is the offset. The hyperplane is ori- + ented toward verify that the hyperplanes are per- + pendicular bisectors. Use 'Fi' for bounded + regions, and 'Fv' for the corresponding Voronoi + vertices. + + FO List all options to stderr, including the default + values. Additional 'FO's are printed to stdout. + + Fp Print points for halfspace intersections (option + 'Hn,n,...'). Each intersection corresponds to a + + + +Geometry Center 2003/12/30 9 + + + +qhull(1) qhull(1) + + + facet of the dual polytope. The "infinity" point + [-10.101,-10.101,...] indicates an unbounded + intersection. + + FP For each coplanar point ('Qc') print the point id + of the nearest vertex, the point id, the facet id, + and the distance. + + FQ Print command used for qhull and input. + + Fs Print a summary. The first line consists of the + number of integers ("7"), followed by the dimen- + sion, the number of points, the number of vertices, + the number of facets, the number of vertices + selected for output, the number of facets selected + for output, the number of coplanar points selected + for output. + + The second line consists of the number of reals + ("2"), followed by the maxmimum offset to an outer + plane and and minimum offset to an inner plane. + Roundoff is included. Later versions of Qhull may + produce additional integers or reals. + + FS Print the size of the hull. The first line con- + sists of the number of integers ("0"). The second + line consists of the number of reals ("2"), fol- + lowed by the total facet area, and the total vol- + ume. Later versions of Qhull may produce addi- + tional integers or reals. + + The total volume measures the volume of the inter- + section of the halfspaces defined by each facet. + Both area and volume are approximations for non- + simplicial facets. See option 'Fa'. + + Ft Print a triangulation with added points for non- + simplicial facets. The first line is the dimension + and the second line is the number of points and the + number of facets. The points follow, one per line, + then the facets follow as a list of point indices. + With option points include the point-at-infinity. + + Fv Print vertices for each facet. The first line is + the number of facets. Then each facet is printed, + one per line. Each line is the number of vertices + followed by the corresponding point ids. Vertices + are listed in the order they were added to the hull + (the last one is first). + + Fv Print all ridges of a Voronoi diagram. The first + line is the number of ridges. Then each ridge is + printed, one per line. A line starts with the num- + ber of indices. The first pair lists adjacent + + + +Geometry Center 2003/12/30 10 + + + + + +qhull(1) qhull(1) + + + input sites, the remaining indices list Voronoi + vertices. Vertex '0' indicates the vertex-at- + infinity (i.e., an unbounded ray). In 3-d, the + vertices are listed in order. See 'Fi' and 'Fo' + for separating hyperplanes. + + FV Print average vertex. The average vertex is a fea- + sible point for halfspace intersection. + + Fx List extreme points (vertices) of the convex hull. + The first line is the number of points. The other + lines give the indices of the corresponding points. + The first point is '0'. In 2-d, the points occur + in counter-clockwise order; otherwise they occur in + input order. For Delaunay triangulations, 'Fx' + lists the extreme points of the input sites. The + points are unordered. + + + Geomview options + + G Produce a file for viewing with Geomview. Without + other options, Qhull displays edges in 2-d, outer + planes in 3-d, and ridges in 4-d. A ridge can be + explicit or implicit. An explicit ridge is a dim-1 + dimensional simplex between two facets. In 4-d, + the explicit ridges are triangles. When displaying + a ridge in 4-d, Qhull projects the ridge's vertices + to one of its facets' hyperplanes. Use 'Gh' to + project ridges to the intersection of both hyper- + planes. + + Ga Display all input points as dots. + + Gc Display the centrum for each facet in 3-d. The + centrum is defined by a green radius sitting on a + blue plane. The plane corresponds to the facet's + hyperplane. The radius is defined by 'C-n' or + 'Cn'. + + GDn Drop dimension n in 3-d or 4-d. The result is a + 2-d or 3-d object. + + Gh Display hyperplane intersections in 3-d and 4-d. + In 3-d, the intersection is a black line. It lies + on two neighboring hyperplanes (c.f., the blue + squares associated with centrums ('Gc')). In 4-d, + the ridges are projected to the intersection of + both hyperplanes. + + Gi Display inner planes in 2-d and 3-d. The inner + plane of a facet is below all of its vertices. It + is parallel to the facet's hyperplane. The inner + plane's color is the opposite (1-r,1-g,1-b) of the + + + +Geometry Center 2003/12/30 11 + + + + + +qhull(1) qhull(1) + + + outer plane. Its edges are determined by the ver- + tices. + + Gn Do not display inner or outer planes. By default, + Geomview displays the precise plane (no merging) or + both inner and output planes (merging). Under + merging, Geomview does not display the inner plane + if the the difference between inner and outer is + too small. + + Go Display outer planes in 2-d and 3-d. The outer + plane of a facet is above all input points. It is + parallel to the facet's hyperplane. Its color is + determined by the facet's normal, and its edges are + determined by the vertices. + + Gp Display coplanar points and vertices as radii. A + radius defines a ball which corresponds to the + imprecision of the point. The imprecision is the + maximum of the roundoff error, the centrum radius, + and maxcoord * (1-An). It is at least 1/20'th of + the maximum coordinate, and ignores post-merging if + pre-merging is done. + + Gr Display ridges in 3-d. A ridge connects the two + vertices that are shared by neighboring facets. + Ridges are always displayed in 4-d. + + Gt A 3-d Delaunay triangulation looks like a convex + hull with interior facets. Option 'Gt' removes the + outside ridges to reveal the outermost facets. It + automatically sets options 'Gr' and 'GDn'. + + Gv Display vertices as spheres. The radius of the + sphere corresponds to the imprecision of the data. + See 'Gp' for determining the radius. + + + Print options + + PAn Only the n largest facets are marked good for + printing. Unless 'PG' is set, 'Pg' is automati- + cally set. + + Pdk:n Drop facet from output if normal[k] <= n. The + option 'Pdk' uses the default value of 0 for n. + + PDk:n Drop facet from output if normal[k] >= n. The + option 'PDk' uses the default value of 0 for n. + + PFn Only facets with area at least 'n' are marked good + for printing. Unless 'PG' is set, 'Pg' is automat- + ically set. + + + + +Geometry Center 2003/12/30 12 + + + + + +qhull(1) qhull(1) + + + Pg Print only good facets. A good facet is either + visible from a point (the 'QGn' option) or includes + a point (the 'QVn' option). It also meets the + requirements of 'Pdk' and 'PDk' options. Option + 'Pg' is automatically set for options 'PAn' and + 'PFn'. + + PG Print neighbors of good facets. + + PMn Only the n facets with the most merges are marked + good for printing. Unless 'PG' is set, 'Pg' is + automatically set. + + Po Force output despite precision problems. Verify ('Tv') does not check + coplanar points. Flipped facets are reported and + concave facets are counted. If 'Po' is used, + points are not partitioned into flipped facets and + a flipped facet is always visible to a point. + Also, if an error occurs before the completion of + Qhull and tracing is not active, 'Po' outputs a + neighborhood of the erroneous facets (if any). + + Pp Do not report precision problems. + + + Qhull control options + + Qbk:0Bk:0 + Drop dimension k from the input points. This + allows the user to take convex hulls of sub-dimen- + sional objects. It happens before the Delaunay and + Voronoi transformation. + + QbB Scale the input points to fit the unit cube. After + scaling, the lower bound will be -0.5 and the upper + bound +0.5 in all dimensions. For Delaunay and + Voronoi diagrams, scaling happens after projection + to the paraboloid. Under precise arithmetic, scal- + ing does not change the topology of the convex + hull. + + Qbb Scale the last coordinate to [0, m] where m is the + maximum absolute value of the other coordinates. + For Delaunay and Voronoi diagrams, scaling happens + after projection to the paraboloid. It reduces + roundoff error for inputs with integer coordinates. + Under precise arithmetic, scaling does not change + the topology of the convex hull. + + Qbk:n Scale the k'th coordinate of the input points. + After scaling, the lower bound of the input points + will be n. 'Qbk' scales to -0.5. + + + +Geometry Center 2003/12/30 13 + + + + + +qhull(1) qhull(1) + + + QBk:n Scale the k'th coordinate of the input points. + After scaling, the upper bound will be n. 'QBk' + scales to +0.5. + + Qc Keep coplanar points with the nearest facet. Out- + put formats 'p', 'f', 'Gp', 'Fc', 'FN', and 'FP' + will print the points. + + Qf Partition points to the furthest outside facet. + + Qg Only build good facets. With the 'Qg' option, + Qhull will only build those facets that it needs to + determine the good facets in the output. See + 'QGn', 'QVn', and 'PdD' for defining good facets, + and 'Pg' and 'PG' for printing good facets and + their neighbors. + + QGn A facet is good (see 'Qg' and 'Pg') if it is visi- + ble from point n. If n < 0, a facet is good if it + is not visible from point n. Point n is not added + to the hull (unless 'TCn' or 'TPn'). With rbox, + use the 'Pn,m,r' option to define your point; it + will be point 0 (QG0). + + Qi Keep interior points with the nearest facet. Out- + put formats 'p', 'f', 'Gp', 'FN', 'FP', and 'Fc' + will print the points. + + QJn Joggle each input coordinate by adding a random + number in [-n,n]. If a precision error occurs, + then qhull increases n and tries again. It does + not increase n beyond a certain value, and it stops + after a certain number of attempts [see user.h]. + Option 'QJ' selects a default value for n. The + output will be simplicial. For Delaunay triangula- + tions, 'QJn' sets 'Qbb' to scale the last coordi- + nate (not if 'Qbk:n' or 'QBk:n' is set). 'QJn' is + deprecated for Voronoi diagrams. See also 'Qt'. + + Qm Only process points that would otherwise increase + max_outside. Other points are treated as coplanar + or interior points. + + Qr Process random outside points instead of furthest + ones. This makes Qhull equivalent to the random- + ized incremental algorithms. CPU time is not + reported since the randomization is inefficient. + + QRn Randomly rotate the input points. If n=0, use time + as the random number seed. If n>0, use n as the + random number seed. If n=-1, don't rotate but use + time as the random number seed. For Delaunay tri- + angulations ('d' and 'v'), rotate about the last + axis. + + + + +Geometry Center 2003/12/30 14 + + + + + +qhull(1) qhull(1) + + + Qs Search all points for the initial simplex. + + Qt Triangulated output. Triangulate non-simplicial + facets. 'Qt' is deprecated for Voronoi diagrams. + See also 'QJn' + + Qv Test vertex neighbors for convexity after post- + merging. To use the 'Qv' option, you also need to + set a merge option (e.g., 'Qx' or 'C-0'). + + QVn A good facet (see 'Qg' and 'Pg') includes point n. + If n<0, then a good facet does not include point n. + The point is either in the initial simplex or it is + the first point added to the hull. Option 'QVn' + may not be used with merging. + + Qx Perform exact merges while building the hull. The + "exact" merges are merging a point into a coplanar + facet (defined by 'Vn', 'Un', and 'C-n'), merging + concave facets, merging duplicate ridges, and merg- + ing flipped facets. Coplanar merges and angle + coplanar merges ('A-n') are not performed. Concav- + ity testing is delayed until a merge occurs. + + After the hull is built, all coplanar merges are + performed (defined by 'C-n' and 'A-n'), then post- + merges are performed (defined by 'Cn' and 'An'). + + Qz Add a point "at infinity" that is above the + paraboloid for Delaunay triangulations and Voronoi + diagrams. This reduces precision problems and + allows the triangulation of cospherical points. + + + Qhull experiments and speedups + + Q0 Turn off pre-merging as a default option. With + 'Q0'/'Qx' and without explicit pre-merge options, + Qhull ignores precision issues while constructing + the convex hull. This may lead to precision + errors. If so, a descriptive warning is generated. + + Q1 With 'Q1', Qhull sorts merges by type (coplanar, + angle coplanar, concave) instead of by angle. + + Q2 With 'Q2', Qhull merges all facets at once instead + of using independent sets of merges and then + retesting. + + Q3 With 'Q3', Qhull does not remove redundant ver- + tices. + + Q4 With 'Q4', Qhull avoids merges of an old facet into + a new facet. + + Q5 With 'Q5', Qhull does not correct outer planes at + the end. The maximum outer plane is used instead. + + + + +Geometry Center 2003/12/30 15 + + + + + +qhull(1) qhull(1) + + + Q6 With 'Q6', Qhull does not pre-merge concave or + coplanar facets. + + Q7 With 'Q7', Qhull processes facets in depth-first + order instead of breadth-first order. + + Q8 With 'Q8' and merging, Qhull does not retain near- + interior points for adjusting outer planes. 'Qc' + will probably retain all points that adjust outer + planes. + + Q9 With 'Q9', Qhull processes the furthest of all out- + side sets at each iteration. + + Q10 With 'Q10', Qhull does not use special processing + for narrow distributions. + + Q11 With 'Q11', Qhull copies normals and recomputes + centrums for tricoplanar facets. + + Q12 With 'Q12', Qhull does not report a very wide merge due + to a duplicated ridge with nearly coincident vertices + + Trace options + + Tn Trace at level n. Qhull includes full execution + tracing. 'T-1' traces events. 'T1' traces the + overall execution of the program. 'T2' and 'T3' + trace overall execution and geometric and topologi- + cal events. 'T4' traces the algorithm. 'T5' + includes information about memory allocation and + Gaussian elimination. + + Ta Annotate output with codes that identify the + corresponding qh_fprintf() statement. + + Tc Check frequently during execution. This will catch + most inconsistency errors. + + TCn Stop Qhull after building the cone of new facets + for point n. The output for 'f' includes the cone + and the old hull. See also 'TVn'. + + TFn Report progress whenever more than n facets are + created During post-merging, 'TFn' reports progress + after more than n/2 merges. + + TI file + Input data from 'file'. The filename may not include + spaces or quotes. + + TO file + Output results to 'file'. The name may be enclosed + in single quotes. + + TPn Turn on tracing when point n is added to the hull. + Trace partitions of point n. If used with TWn, turn off + tracing after adding point n to the hull. + + TRn Rerun qhull n times. Usually used with 'QJn' to + determine the probability that a given joggle will + fail. + + Ts Collect statistics and print to stderr at the end + of execution. + + Tv Verify the convex hull. This checks the topologi- + cal structure, facet convexity, and point inclu- + sion. If precision problems occurred, facet con- + vexity is tested whether or not 'Tv' is selected. + Option 'Tv' does not check point inclusion if + + + +Geometry Center 2003/12/30 16 + + + + + +qhull(1) qhull(1) + + + forcing output with 'Po', or if 'Q5' is set. + + For point inclusion testing, Qhull verifies that + all points are below all outer planes (facet->max- + outside). Point inclusion is exhaustive if merging + or if the facet-point product is small enough; oth- + erwise Qhull verifies each point with a directed + search (qh_findbest). + + Point inclusion testing occurs after producing out- + put. It prints a message to stderr unless option + 'Pp' is used. This allows the user to interrupt + Qhull without changing the output. + + TVn Stop Qhull after adding point n. If n < 0, stop + Qhull before adding point n. Output shows the hull + at this time. See also 'TCn' + + TMn Turn on tracing at n'th merge. + + TWn Trace merge facets when the width is greater than + n. + + Tz Redirect stderr to stdout. + + +BUGS + Please report bugs to Brad Barber at + qhull_bug@qhull.org. + + If Qhull does not compile, it is due to an incompatibility + between your system and ours. The first thing to check is + that your compiler is ANSI standard. If it is, check the + man page for the best options, or find someone to help + you. If you locate the cause of your problem, please send + email since it might help others. + + If Qhull compiles but crashes on the test case (rbox D4), + there's still incompatibility between your system and + ours. Typically it's been due to mem.c and memory align- + ment. You can use qh_NOmem in mem.h to turn off memory + management. Please let us know if you figure out how to + fix these problems. + + If you do find a problem, try to simplify it before + reporting the error. Try different size inputs to locate + the smallest one that causes an error. You're welcome to + hunt through the code using the execution trace as a + guide. This is especially true if you're incorporating + Qhull into your own program. + + When you do report an error, please attach a data set to + the end of your message. This allows us to see the error + for ourselves. Qhull is maintained part-time. + + + +Geometry Center 2003/12/30 17 + + + + + +qhull(1) qhull(1) + + +E-MAIL + Please send correspondence to qhull@qhull.org and + report bugs to qhull_bug@qhull.org. Let us know how + you use Qhull. If you mention it in a paper, please send + the reference and an abstract. + + If you would like to get Qhull announcements (e.g., a new + version) and news (any bugs that get fixed, etc.), let us + know and we will add you to our mailing list. If you + would like to communicate with other Qhull users, we will + add you to the qhull_users alias. For Internet news about + geometric algorithms and convex hulls, look at comp.graph- + ics.algorithms and sci.math.num-analysis + + +SEE ALSO + rbox(1) + + Barber, C. B., D.P. Dobkin, and H.T. Huhdanpaa, "The + Quickhull Algorithm for Convex Hulls," ACM Trans. on Math- + ematical Software, 22(4):469-483, Dec. 1996. + http://portal.acm.org/citation.cfm?doid=235815.235821 + http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.117.405 + + + Clarkson, K.L., K. Mehlhorn, and R. Seidel, "Four results + on randomized incremental construction," Computational + Geometry: Theory and Applications, vol. 3, p. 185-211, + 1993. + + Preparata, F. and M. Shamos, Computational Geometry, + Springer-Verlag, New York, 1985. + + + +AUTHORS + C. Bradford Barber Hannu Huhdanpaa + bradb@shore.net hannu@qhull.org + + + +ACKNOWLEDGEMENTS + A special thanks to Albert Marden, Victor Milenkovic, the + Geometry Center, Harvard University, and Endocardial Solu- + tions, Inc. for supporting this work. + + Qhull 1.0 and 2.0 were developed under National Science Foundation + grants NSF/DMS-8920161 and NSF-CCR-91-15793 750-7504. David Dobkin + + + +Geometry Center 2003/12/30 18 + + + + + +qhull(1) qhull(1) + + + guided the original work at Princeton University. If you find it + useful, please let us know. + + The Geometry Center was supported by grant DMS-8920161 from the National + Science Foundation, by grant DOE/DE-FG02-92ER25137 from the Department + of Energy, by the University of Minnesota, and by Minnesota Technology, Inc. + + Qhull is available from http://www.qhull.org + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Geometry Center 2003/12/30 19 + + diff --git a/xs/src/qhull/html/qvoron_f.htm b/xs/src/qhull/html/qvoron_f.htm new file mode 100644 index 000000000..db538b5ab --- /dev/null +++ b/xs/src/qhull/html/qvoron_f.htm @@ -0,0 +1,396 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<title>qvoronoi Qu -- furthest-site Voronoi diagram</title> +</head> + +<body> +<!-- Navigation links --> +<a name="TOP"><b>Up</b></a><b>:</b> +<a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#synopsis">sy</a>nopsis +• <a href="#input">in</a>put • <a href="#outputs">ou</a>tputs +• <a href="#controls">co</a>ntrols • <a href="#graphics">gr</a>aphics +• <a href="#notes">no</a>tes • <a href="#conventions">co</a>nventions +• <a href="#options">op</a>tions + +<hr> +<!-- Main text of document --> +<h1><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/delaunay.html"><img +src="qh--dt.gif" alt="[delaunay]" align="middle" width="100" +height="100"></a>qvoronoi Qu -- furthest-site Voronoi diagram</h1> + +<p>The furthest-site Voronoi diagram is the furthest-neighbor map for a set of +points. Each region contains those points that are further +from one input site than any other input site. See the +survey article by Aurenhammer [<a href="index.htm#aure91">'91</a>] +and the brief introduction by O'Rourke [<a +href="index.htm#orou94">'94</a>]. The furthest-site Voronoi diagram is the dual of the <a +href="qdelau_f.htm">furthest-site Delaunay triangulation</a>. +</p> + +<blockquote> +<dl> + <dt><b>Example:</b> rbox 10 D2 | qvoronoi <a + href="qh-optq.htm#Qu">Qu</a> <a href="qh-opto.htm#s">s</a> + <a href="qh-opto.htm#o">o</a> <a href="qh-optt.htm#TO">TO + result</a></dt> + <dd>Compute the 2-d, furthest-site Voronoi diagram of 10 + random points. Write a summary to the console and the Voronoi + regions and vertices to 'result'. The first vertex of the + result indicates unbounded regions. Almost all regions + are unbounded.</dd> +</dl> + +<dl> + <dt><b>Example:</b> rbox r y c G1 D2 | qvoronoi <a + href="qh-optq.htm#Qu">Qu</a> + <a href="qh-opto.htm#s">s</a> + <a href="qh-optf.htm#Fn">Fn</a> <a href="qh-optt.htm#TO">TO + result</a></dt> + <dd>Compute the 2-d furthest-site Voronoi diagram of a square + and a small triangle. Write a summary to the console and the Voronoi + vertices for each input site to 'result'. + The origin is the only furthest-site Voronoi vertex. The + negative indices indicate vertices-at-infinity.</dd> +</dl> +</blockquote> + +<p> +Qhull computes the furthest-site Voronoi diagram via the <a href="qdelau_f.htm"> +furthest-site Delaunay triangulation</a>. +Each furthest-site Voronoi vertex is the circumcenter of an upper +facet of the Delaunay triangulation. Each furthest-site Voronoi +region corresponds to a vertex of the Delaunay triangulation +(i.e., an input site).</p> + +<p>See <a href="http://www.qhull.org/html/qh-faq.htm#TOC">Qhull FAQ</a> - Delaunay and +Voronoi diagram questions.</p> + +<p>The 'qvonoroi' program is equivalent to +'<a href=qhull.htm#outputs>qhull v</a> <a href=qh-optq.htm#Qbb>Qbb</a>' in 2-d to 3-d, and +'<a href=qhull.htm#outputs>qhull v</a> <a href=qh-optq.htm#Qbb>Qbb</a> <a href=qh-optq.htm#Qx>Qx</a>' +in 4-d and higher. It disables the following Qhull +<a href=qh-quick.htm#options>options</a>: <i>d n m v H U Qb +QB Qc Qf Qg Qi Qm Qr QR Qv Qx TR E V Fa FA FC Fp FS Ft FV Gt Q0,etc</i>. + + +<p><b>Copyright © 1995-2015 C.B. Barber</b></p> + +<hr> +<h3><a href="#TOP">»</a><a name="synopsis">furthest-site qvoronoi synopsis</a></h3> +<blockquote> + +See <a href="qvoronoi.htm#synopsis">qvoronoi synopsis</a>. The same +program is used for both constructions. Use option '<a href="qh-optq.htm#Qu">Qu</a>' +for furthest-site Voronoi diagrams. + + +</blockquote> +<h3><a href="#TOP">»</a><a name="input">furthest-site qvoronoi +input</a></h3> +<blockquote> +<p>The input data on <tt>stdin</tt> consists of:</p> +<ul> + <li>dimension + <li>number of points</li> + <li>point coordinates</li> +</ul> + +<p>Use I/O redirection (e.g., qvoronoi Qu < data.txt), a pipe (e.g., rbox 10 | qvoronoi Qu), +or the '<a href=qh-optt.htm#TI>TI</a>' option (e.g., qvoronoi TI data.txt Qu). + +<p>For example, this is a square containing four random points. +Its furthest-site Voronoi diagram has on vertex and four unbounded, +separating hyperplanes (i.e., the coordinate axes) +<p> +<blockquote> +<tt>rbox c 4 D2 > data</tt> +<blockquote><pre> +2 RBOX c 4 D2 +8 +-0.4999921736307369 -0.3684622117955817 +0.2556053225468894 -0.0413498678629751 +0.0327672376602583 -0.2810408135699488 +-0.452955383763607 0.17886471718444 + -0.5 -0.5 + -0.5 0.5 + 0.5 -0.5 + 0.5 0.5 +</pre></blockquote> + +<p><tt>qvoronoi Qu s Fo < data</tt> +<blockquote><pre> + +Furthest-site Voronoi vertices by the convex hull of 8 points in 3-d: + + Number of Voronoi regions: 8 + Number of Voronoi vertices: 1 + Number of non-simplicial Voronoi vertices: 1 + +Statistics for: RBOX c 4 D2 | QVORONOI Qu s Fo + + Number of points processed: 8 + Number of hyperplanes created: 20 + Number of facets in hull: 11 + Number of distance tests for qhull: 34 + Number of merged facets: 1 + Number of distance tests for merging: 107 + CPU seconds to compute hull (after input): 0 + +4 +5 4 5 0 1 0 +5 4 6 1 0 0 +5 5 7 1 0 0 +5 6 7 0 1 0 +</pre></blockquote> +</blockquote> + +</blockquote> +<h3><a href="#TOP">»</a> <a name="outputs">furthest-site qvoronoi +outputs</a></h3> +<blockquote> + +<p>These options control the output of furthest-site Voronoi diagrams.</p> +<blockquote> + +<dl compact> + <dt> </dt> + <dd><b>furthest-site Voronoi vertices</b></dd> + <dt><a href="qh-opto.htm#p">p</a></dt> + <dd>print the coordinates of the furthest-site Voronoi vertices. The first line + is the dimension. The second line is the number of vertices. Each + remaining line is a furthest-site Voronoi vertex. The points-in-square example + has one furthest-site Voronoi vertex at the origin.</dd> + <dt><a href="qh-optf.htm#Fn">Fn</a></dt> + <dd>list the neighboring furthest-site Voronoi vertices for each furthest-site Voronoi + vertex. The first line is the number of Voronoi vertices. Each + remaining line starts with the number of neighboring vertices. Negative indices (e.g., <em>-1</em>) indicate vertices + outside of the Voronoi diagram. In the points-in-square example, the + Voronoi vertex at the origin has four neighbors-at-infinity.</dd> + <dt><a href="qh-optf.htm#FN">FN</a></dt> + <dd>list the furthest-site Voronoi vertices for each furthest-site Voronoi region. The first line is + the number of Voronoi regions. Each remaining line starts with the + number of Voronoi vertices. Negative indices (e.g., <em>-1</em>) indicate vertices + outside of the Voronoi diagram. + In the points-in-square example, all regions share the Voronoi vertex + at the origin.</dd> + + <dt> </dt> + <dt> </dt> + <dd><b>furthest-site Voronoi regions</b></dd> + <dt><a href="qh-opto.htm#o">o</a></dt> + <dd>print the furthest-site Voronoi regions in OFF format. The first line is the + dimension. The second line is the number of vertices, the number + of input sites, and "1". The third line represents the vertex-at-infinity. + Its coordinates are "-10.101". The next lines are the coordinates + of the furthest-site Voronoi vertices. Each remaining line starts with the number + of Voronoi vertices in a Voronoi region. In 2-d, the vertices are +listed in adjacency order (unoriented). In 3-d and higher, the +vertices are listed in numeric order. In the points-in-square + example, each unbounded region includes the Voronoi vertex at + the origin. Lines consisting of <em>0</em> indicate + interior input sites. </dd> + <dt><a href="qh-optf.htm#Fi2">Fi</a></dt> + <dd>print separating hyperplanes for inner, bounded furthest-site Voronoi + regions. The first number is the number of separating + hyperplanes. Each remaining line starts with <i>3+dim</i>. The + next two numbers are adjacent input sites. The next <i>dim</i> + numbers are the coefficients of the separating hyperplane. The + last number is its offset. The are no bounded, separating hyperplanes + for the points-in-square example.</dd> + <dt><a href="qh-optf.htm#Fo2">Fo</a></dt> + <dd>print separating hyperplanes for outer, unbounded furthest-site Voronoi + regions. The first number is the number of separating + hyperplanes. Each remaining line starts with <i>3+dim</i>. The + next two numbers are adjacent input sites on the convex hull. The + next <i>dim</i> + numbers are the coefficients of the separating hyperplane. The + last number is its offset. The points-in-square example has four + unbounded, separating hyperplanes.</dd> + <dt> </dt> + <dt> </dt> + <dd><b>Input sites</b></dd> + <dt><a href="qh-optf.htm#Fv2">Fv</a></dt> + <dd>list ridges of furthest-site Voronoi vertices for pairs of input sites. The + first line is the number of ridges. Each remaining line starts with + two plus the number of Voronoi vertices in the ridge. The next + two numbers are two adjacent input sites. The remaining numbers list + the Voronoi vertices. As with option 'o', a <em>0</em> indicates + the vertex-at-infinity + and an unbounded, separating hyperplane. + The perpendicular bisector (separating hyperplane) + of the input sites is a flat through these vertices. + In the points-in-square example, the ridge for each edge of the square + is unbounded.</dd> + <dt> </dt> + <dt> </dt> + <dd><b>General</b></dd> + <dt><a href="qh-opto.htm#s">s</a></dt> + <dd>print summary of the furthest-site Voronoi diagram. Use '<a + href="qh-optf.htm#Fs">Fs</a>' for numeric data.</dd> + <dt><a href="qh-opto.htm#i">i</a></dt> + <dd>list input sites for each <a href=qdelau_f.htm>furthest-site Delaunay region</a>. Use option '<a href="qh-optp.htm#Pp">Pp</a>' + to avoid the warning. The first line is the number of regions. The + remaining lines list the input sites for each region. The regions are + oriented. In the points-in-square example, the square region has four + input sites. In 3-d and higher, report cospherical sites by adding extra points. + </dd> + <dt><a href="qh-optg.htm#G">G</a></dt> + <dd>Geomview output for 2-d furthest-site Voronoi diagrams.</dd> + </dl> +</blockquote> + +</blockquote> +<h3><a href="#TOP">»</a> <a name="controls">furthest-site qvoronoi +controls</a></h3> +<blockquote> + +<p>These options provide additional control:</p> +<blockquote> + +<dl compact> + <dt><a href="qh-optq.htm#Qu">Qu</a></dt> + <dd>must be used.</dd> + <dt><a href="qh-optq.htm#QVn">QVn</a></dt> + <dd>select furthest-site Voronoi vertices for input site <em>n</em> </dd> + <dt><a href="qh-optt.htm#Tv">Tv</a></dt> + <dd>verify result</dd> + <dt><a href="qh-optt.htm#TO">TI file</a></dt> + <dd>input data from file. The filename may not use spaces or quotes.</dd> + <dt><a href="qh-optt.htm#TO">TO file</a></dt> + <dd>output results to file. Use single quotes if the filename + contains spaces (e.g., <tt>TO 'file with spaces.txt'</tt></dd> + <dt><a href="qh-optt.htm#TFn">TFn</a></dt> + <dd>report progress after constructing <em>n</em> facets</dd> + <dt><a href="qh-optp.htm#PDk">PDk:1</a></dt> + <dd>include upper and lower facets in the output. Set <em>k</em> + to the last dimension (e.g., 'PD2:1' for 2-d inputs). </dd> + <dt><a href="qh-opto.htm#f">f </a></dt> + <dd>facet dump. Print the data structure for each facet (i.e., + furthest-site Voronoi vertex).</dd> +</dl> + +</blockquote> +</blockquote> +<h3><a href="#TOP">»</a> <a name="graphics">furthest-site qvoronoi +graphics</a></h3> +<blockquote> +<p>In 2-d, Geomview output ('<a href="qh-optg.htm#G">G</a>') +displays a furthest-site Voronoi diagram with extra edges to +close the unbounded furthest-site Voronoi regions. All regions +will be unbounded. Since the points-in-box example has only +one furthest-site Voronoi vertex, the Geomview output is one +point.</p> + +<p>See the <a href="qh-eg.htm#delaunay">Delaunay and Voronoi +examples</a> for a 2-d example. Turn off normalization (on +Geomview's 'obscure' menu) when comparing the furthest-site +Voronoi diagram with the corresponding Voronoi diagram. </p> + +</blockquote> +<h3><a href="#TOP">»</a><a name="notes">furthest-site qvoronoi +notes</a></h3> +<blockquote> + +<p>See <a href="qvoronoi.htm#notes">Voronoi notes</a>.</p> + +</blockquote> +<h3><a href="#TOP">»</a><a name="conventions">furthest-site qvoronoi conventions</a></h3> +<blockquote> + +<p>The following terminology is used for furthest-site Voronoi +diagrams in Qhull. The underlying structure is a furthest-site +Delaunay triangulation from a convex hull in one higher +dimension. Upper facets of the Delaunay triangulation correspond +to vertices of the furthest-site Voronoi diagram. Vertices of the +furthest-site Delaunay triangulation correspond to input sites. +They also define regions of the furthest-site Voronoi diagram. +All vertices are extreme points of the input sites. See <a +href="qconvex.htm#conventions">qconvex conventions</a>, <a +href="qdelau_f.htm#conventions">furthest-site delaunay +conventions</a>, and <a href="index.htm#structure">Qhull's data structures</a>.</p> + +<ul> + <li><em>input site</em> - a point in the input (one dimension + lower than a point on the convex hull)</li> + <li><em>point</em> - a point has <i>d+1</i> coordinates. The + last coordinate is the sum of the squares of the input + site's coordinates</li> + <li><em>vertex</em> - a point on the upper facets of the + paraboloid. It corresponds to a unique input site. </li> + <li><em>furthest-site Delaunay facet</em> - an upper facet of the + paraboloid. The last coefficient of its normal is + clearly positive.</li> + <li><em>furthest-site Voronoi vertex</em> - the circumcenter + of a furthest-site Delaunay facet</li> + <li><em>furthest-site Voronoi region</em> - the region of + Euclidean space further from an input site than any other + input site. Qhull lists the furthest-site Voronoi + vertices that define each furthest-site Voronoi region.</li> + <li><em>furthest-site Voronoi diagram</em> - the graph of the + furthest-site Voronoi regions with the ridges (edges) + between the regions.</li> + <li><em>infinity vertex</em> - the Voronoi vertex for + unbounded furthest-site Voronoi regions in '<a + href="qh-opto.htm#o">o</a>' output format. Its + coordinates are <em>-10.101</em>.</li> + <li><em>good facet</em> - an furthest-site Voronoi vertex with + optional restrictions by '<a href="qh-optq.htm#QVn">QVn</a>', + etc.</li> +</ul> + +</blockquote> +<h3><a href="#TOP">»</a><a name="options">furthest-site qvoronoi options</a></h3> +<blockquote> + +See <a href="qvoronoi.htm#options">qvoronoi options</a>. The same +program is used for both constructions. Use option '<a href="qh-optq.htm#Qu">Qu</a>' +for furthest-site Voronoi diagrams. +</blockquote> + +<!-- Navigation links --> +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#synopsis">sy</a>nopsis +• <a href="#input">in</a>put • <a href="#outputs">ou</a>tputs +• <a href="#controls">co</a>ntrols • <a href="#graphics">gr</a>aphics +• <a href="#notes">no</a>tes • <a href="#conventions">co</a>nventions +• <a href="#options">op</a>tions +<!-- GC common information --> +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="qh--geom.gif" +align="middle" width="40" height="40"></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: Sept. 25, 1995 --- <!-- hhmts start --> Last modified: see top <!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/qvoronoi.htm b/xs/src/qhull/html/qvoronoi.htm new file mode 100644 index 000000000..6d81d48c1 --- /dev/null +++ b/xs/src/qhull/html/qvoronoi.htm @@ -0,0 +1,667 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<title>qvoronoi -- Voronoi diagram</title> +</head> + +<body> +<!-- Navigation links --> +<a name="TOP"><b>Up</b></a><b>:</b> +<a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#synopsis">sy</a>nopsis +• <a href="#input">in</a>put • <a href="#outputs">ou</a>tputs +• <a href="#controls">co</a>ntrols • <a href="#graphics">gr</a>aphics +• <a href="#notes">no</a>tes • <a href="#conventions">co</a>nventions +• <a href="#options">op</a>tions + +<hr> +<!-- Main text of document --> +<h1><a +href="http://www.archinect.com/gallery/displayimage.php?pos=-4658"><img +src="normal_voronoi_knauss_oesterle.jpg" alt="[voronoi]" align="middle" +height="100"></a>qvoronoi -- Voronoi diagram</h1> + +<p>The Voronoi diagram is the nearest-neighbor map for a set of +points. Each region contains those points that are nearer +one input site than any other input site. It has many useful properties and applications. See the +survey article by Aurenhammer [<a href="index.htm#aure91">'91</a>] +and the detailed introduction by O'Rourke [<a +href="index.htm#orou94">'94</a>]. The Voronoi diagram is the +dual of the <a href=qdelaun.htm>Delaunay triangulation</a>. </p> + +<blockquote> +<dl> + <dt><b>Example:</b> rbox 10 D3 | qvoronoi <a href="qh-opto.htm#s">s</a> + <a href="qh-opto.htm#o">o</a> <a href="qh-optt.htm#TO">TO + result</a></dt> + <dd>Compute the 3-d Voronoi diagram of 10 random points. Write a + summary to the console and the Voronoi vertices and + regions to 'result'. The first vertex of the result + indicates unbounded regions.</dd> + + <dt> </dt> + <dt><b>Example:</b> rbox r y c G0.1 D2 | qvoronoi + <a href="qh-opto.htm#s">s</a> + <a href="qh-opto.htm#o">o</a> <a href="qh-optt.htm#TO">TO + result</a></dt> + <dd>Compute the 2-d Voronoi diagram of a triangle and a small + square. Write a + summary to the console and Voronoi vertices and regions + to 'result'. Report a single Voronoi vertex for + cocircular input sites. The first vertex of the result + indicates unbounded regions. The origin is the Voronoi + vertex for the square.</dd> + + <dt> </dt> + <dt><b>Example:</b> rbox r y c G0.1 D2 | qvoronoi <a href="qh-optf.htm#Fv2">Fv</a> + <a href="qh-optt.htm#TO">TO result</a></dt> + <dd>Compute the 2-d Voronoi diagram of a triangle and a small + square. Write a + summary to the console and the Voronoi ridges to + 'result'. Each ridge is the perpendicular bisector of a + pair of input sites. Vertex "0" indicates + unbounded ridges. Vertex "8" is the Voronoi + vertex for the square.</dd> + + <dt> </dt> + <dt><b>Example:</b> rbox r y c G0.1 D2 | qvoronoi <a href="qh-optf.htm#Fi2">Fi</a></dt> + <dd>Print the bounded, separating hyperplanes for the 2-d Voronoi diagram of a + triangle and a small + square. Note the four hyperplanes (i.e., lines) for Voronoi vertex + "8". It is at the origin. + </dd> +</dl> +</blockquote> + +<p>Qhull computes the Voronoi diagram via the <a href="qdelaun.htm">Delaunay +triangulation</a>. Each Voronoi +vertex is the circumcenter of a facet of the Delaunay +triangulation. Each Voronoi region corresponds to a vertex (i.e., input site) of the +Delaunay triangulation. </p> + +<p>Qhull outputs the Voronoi vertices for each Voronoi region. With +option '<a href="qh-optf.htm#Fv2">Fv</a>', +it lists all ridges of the Voronoi diagram with the corresponding +pairs of input sites. With +options '<a href="qh-optf.htm#Fi2">Fi</a>' and '<a href="qh-optf.htm#Fo2">Fo</a>', +it lists the bounded and unbounded separating hyperplanes. +You can also output a single Voronoi region +for further processing [see <a href="#graphics">graphics</a>].</p> + +<p>Use option '<a href="qh-optq.htm#Qz">Qz</a>' if the input is circular, cospherical, or +nearly so. It improves precision by adding a point "at infinity," above the corresponding paraboloid. + +<p>See <a href="http://www.qhull.org/html/qh-faq.htm#TOC">Qhull FAQ</a> - Delaunay and +Voronoi diagram questions.</p> + +<p>The 'qvonoroi' program is equivalent to +'<a href=qhull.htm#outputs>qhull v</a> <a href=qh-optq.htm#Qbb>Qbb</a>' in 2-d to 3-d, and +'<a href=qhull.htm#outputs>qhull v</a> <a href=qh-optq.htm#Qbb>Qbb</a> <a href=qh-optq.htm#Qx>Qx</a>' +in 4-d and higher. It disables the following Qhull +<a href=qh-quick.htm#options>options</a>: <i>d n v Qbb QbB Qf Qg Qm +Qr QR Qv Qx Qz TR E V Fa FA FC FD FS Ft FV Gt Q0,etc</i>. + +<p><b>Copyright © 1995-2015 C.B. Barber</b></p> + +<p>Voronoi image by KOOK Architecture, Silvan Oesterle and Michael Knauss. + +<hr> +<h3><a href="#TOP">»</a><a name="synopsis">qvoronoi synopsis</a></h3> + +<pre> +qvoronoi- compute the Voronoi diagram. + input (stdin): dimension, number of points, point coordinates + comments start with a non-numeric character + +options (qh-voron.htm): + Qu - compute furthest-site Voronoi diagram + Tv - verify result: structure, convexity, and in-circle test + . - concise list of all options + - - one-line description of all options + +output options (subset): + s - summary of results (default) + p - Voronoi vertices + o - OFF file format (dim, Voronoi vertices, and Voronoi regions) + FN - count and Voronoi vertices for each Voronoi region + Fv - Voronoi diagram as Voronoi vertices between adjacent input sites + Fi - separating hyperplanes for bounded regions, 'Fo' for unbounded + G - Geomview output (2-d only) + QVn - Voronoi vertices for input point n, -n if not + TO file- output results to file, may be enclosed in single quotes + +examples: +rbox c P0 D2 | qvoronoi s o rbox c P0 D2 | qvoronoi Fi +rbox c P0 D2 | qvoronoi Fo rbox c P0 D2 | qvoronoi Fv +rbox c P0 D2 | qvoronoi s Qu Fv rbox c P0 D2 | qvoronoi Qu Fo +rbox c G1 d D2 | qvoronoi s p rbox c P0 D2 | qvoronoi s Fv QV0 +</pre> + +<h3><a href="#TOP">»</a><a name="input">qvoronoi input</a></h3> +<blockquote> +The input data on <tt>stdin</tt> consists of: +<ul> + <li>dimension + <li>number of points</li> + <li>point coordinates</li> +</ul> + +<p>Use I/O redirection (e.g., qvoronoi < data.txt), a pipe (e.g., rbox 10 | qvoronoi), +or the '<a href=qh-optt.htm#TI>TI</a>' option (e.g., qvoronoi TI data.txt). + +<p>For example, this is four cocircular points inside a square. Their Voronoi +diagram has nine vertices and eight regions. Notice the Voronoi vertex +at the origin, and the Voronoi vertices (on each axis) for the four +sides of the square. +<p> +<blockquote> +<tt>rbox s 4 W0 c G1 D2 > data</tt> +<blockquote><pre> +2 RBOX s 4 W0 c D2 +8 +-0.4941988586954018 -0.07594397977563715 +-0.06448037284989526 0.4958248496365813 +0.4911154367094632 0.09383830681375946 +-0.348353580869097 -0.3586778257652367 + -1 -1 + -1 1 + 1 -1 + 1 1 +</pre></blockquote> + +<p><tt>qvoronoi s p < data</tt> +<blockquote><pre> + +Voronoi diagram by the convex hull of 8 points in 3-d: + + Number of Voronoi regions: 8 + Number of Voronoi vertices: 9 + Number of non-simplicial Voronoi vertices: 1 + +Statistics for: RBOX s 4 W0 c D2 | QVORONOI s p + + Number of points processed: 8 + Number of hyperplanes created: 18 + Number of facets in hull: 10 + Number of distance tests for qhull: 33 + Number of merged facets: 2 + Number of distance tests for merging: 102 + CPU seconds to compute hull (after input): 0.094 + +2 +9 +4.217546450968612e-17 1.735507986399734 +-8.402566836762659e-17 -1.364368854147395 +0.3447488772716865 -0.6395484723719818 +1.719446929853986 2.136555906154247e-17 +0.4967882915039657 0.68662371396699 +-1.729928876283549 1.343733067524222e-17 +-0.8906163241424728 -0.4594150543829102 +-0.6656840313875723 0.5003013793414868 +-7.318364664277155e-19 -1.188217818408333e-16 +</pre></blockquote> +</blockquote> + +</blockquote> +<h3><a href="#TOP">»</a> <a name="outputs">qvoronoi +outputs</a></h3> +<blockquote> + +<p>These options control the output of Voronoi diagrams.</p> +<blockquote> + +<dl compact> + <dt> </dt> + <dd><b>Voronoi vertices</b></dd> + <dt><a href="qh-opto.htm#p">p</a></dt> + <dd>print the coordinates of the Voronoi vertices. The first line + is the dimension. The second line is the number of vertices. Each + remaining line is a Voronoi vertex.</dd> + <dt><a href="qh-optf.htm#Fn">Fn</a></dt> + <dd>list the neighboring Voronoi vertices for each Voronoi + vertex. The first line is the number of Voronoi vertices. Each + remaining line starts with the number of neighboring vertices. + Negative vertices (e.g., <em>-1</em>) indicate vertices + outside of the Voronoi diagram. + In the circle-in-box example, the + Voronoi vertex at the origin has four neighbors.</dd> + <dt><a href="qh-optf.htm#FN">FN</a></dt> + <dd>list the Voronoi vertices for each Voronoi region. The first line is + the number of Voronoi regions. Each remaining line starts with the + number of Voronoi vertices. Negative indices (e.g., <em>-1</em>) indicate vertices + outside of the Voronoi diagram. + In the circle-in-box example, the four bounded regions are defined by four + Voronoi vertices.</dd> + + <dt> </dt> + <dt> </dt> + <dd><b>Voronoi regions</b></dd> + <dt><a href="qh-opto.htm#o">o</a></dt> + <dd>print the Voronoi regions in OFF format. The first line is the + dimension. The second line is the number of vertices, the number + of input sites, and "1". The third line represents the vertex-at-infinity. + Its coordinates are "-10.101". The next lines are the coordinates + of the Voronoi vertices. Each remaining line starts with the number + of Voronoi vertices in a Voronoi region. In 2-d, the vertices are +listed in adjacency order (unoriented). In 3-d and higher, the +vertices are listed in numeric order. In the circle-in-square + example, each bounded region includes the Voronoi vertex at + the origin. Lines consisting of <em>0</em> indicate + coplanar input sites or '<a href="qh-optq.htm#Qz">Qz</a>'. </dd> + <dt><a href="qh-optf.htm#Fi2">Fi</a></dt> + <dd>print separating hyperplanes for inner, bounded Voronoi + regions. The first number is the number of separating + hyperplanes. Each remaining line starts with <i>3+dim</i>. The + next two numbers are adjacent input sites. The next <i>dim</i> + numbers are the coefficients of the separating hyperplane. The + last number is its offset. Use '<a href="qh-optt.htm#Tv">Tv</a>' to verify that the +hyperplanes are perpendicular bisectors. It will list relevant +statistics to stderr. </dd> + <dt><a href="qh-optf.htm#Fo2">Fo</a></dt> + <dd>print separating hyperplanes for outer, unbounded Voronoi + regions. The first number is the number of separating + hyperplanes. Each remaining line starts with <i>3+dim</i>. The + next two numbers are adjacent input sites on the convex hull. The + next <i>dim</i> + numbers are the coefficients of the separating hyperplane. The + last number is its offset. Use '<a href="qh-optt.htm#Tv">Tv</a>' to verify that the +hyperplanes are perpendicular bisectors. It will list relevant +statistics to stderr,</dd> + <dt> </dt> + <dt> </dt> + <dd><b>Input sites</b></dd> + <dt><a href="qh-optf.htm#Fv2">Fv</a></dt> + <dd>list ridges of Voronoi vertices for pairs of input sites. The + first line is the number of ridges. Each remaining line starts with + two plus the number of Voronoi vertices in the ridge. The next + two numbers are two adjacent input sites. The remaining numbers list + the Voronoi vertices. As with option 'o', a <em>0</em> indicates + the vertex-at-infinity + and an unbounded, separating hyperplane. + The perpendicular bisector (separating hyperplane) + of the input sites is a flat through these vertices. + In the circle-in-square example, the ridge for each edge of the square + is unbounded.</dd> + <dt><a href="qh-optf.htm#Fc">Fc</a></dt> + <dd>list coincident input sites for each Voronoi vertex. + The first line is the number of vertices. The remaining lines start with + the number of coincident sites and deleted vertices. Deleted vertices + indicate highly degenerate input (see'<a href="qh-optf.htm#Fs">Fs</a>'). + A coincident site is assigned to one Voronoi + vertex. Do not use '<a href="qh-optq.htm#QJn">QJ</a>' with 'Fc'; the joggle will separate + coincident sites.</dd> + <dt><a href="qh-optf.htm#FP">FP</a></dt> + <dd>print coincident input sites with distance to + nearest site (i.e., vertex). The first line is the + number of coincident sites. Each remaining line starts with the point ID of + an input site, followed by the point ID of a coincident point, its vertex, and distance. + Includes deleted vertices which + indicate highly degenerate input (see'<a href="qh-optf.htm#Fs">Fs</a>'). + Do not use '<a href="qh-optq.htm#QJn">QJ</a>' with 'FP'; the joggle will separate + coincident sites.</dd> + <dt> </dt> + <dt> </dt> + <dd><b>General</b></dd> + <dt><a href="qh-opto.htm#s">s</a></dt> + <dd>print summary of the Voronoi diagram. Use '<a + href="qh-optf.htm#Fs">Fs</a>' for numeric data.</dd> + <dt><a href="qh-opto.htm#i">i</a></dt> + <dd>list input sites for each <a href=qdelaun.htm>Delaunay region</a>. Use option '<a href="qh-optp.htm#Pp">Pp</a>' + to avoid the warning. The first line is the number of regions. The + remaining lines list the input sites for each region. The regions are + oriented. In the circle-in-square example, the cocircular region has four + edges. In 3-d and higher, report cospherical sites by adding extra points. + </dd> + <dt><a href="qh-optg.htm#G">G</a></dt> + <dd>Geomview output for 2-d Voronoi diagrams.</dd> + </dl> +</blockquote> +</blockquote> +<h3><a href="#TOP">»</a> <a name="controls">qvoronoi +controls</a></h3> +<blockquote> + +<p>These options provide additional control:</p> +<blockquote> + +<dl compact> + <dt><a href="qh-optq.htm#Qu">Qu</a></dt> + <dd>compute the <a href="qvoron_f.htm">furthest-site Voronoi diagram</a>.</dd> + <dt><a href="qh-optq.htm#QVn">QVn</a></dt> + <dd>select Voronoi vertices for input site <em>n</em> </dd> + <dt><a href="qh-optq.htm#Qz">Qz</a></dt> + <dd>add a point above the paraboloid to reduce precision + errors. Use it for nearly cocircular/cospherical input + (e.g., 'rbox c | qvoronoi Qz').</dd> + <dt><a href="qh-optt.htm#Tv">Tv</a></dt> + <dd>verify result</dd> + <dt><a href="qh-optt.htm#TO">TI file</a></dt> + <dd>input data from file. The filename may not use spaces or quotes.</dd> + <dt><a href="qh-optt.htm#TO">TO file</a></dt> + <dd>output results to file. Use single quotes if the filename + contains spaces (e.g., <tt>TO 'file with spaces.txt'</tt></dd> + <dt><a href="qh-optt.htm#TFn">TFn</a></dt> + <dd>report progress after constructing <em>n</em> facets</dd> + <dt><a href="qh-optp.htm#PDk">PDk:1</a></dt> + <dd>include upper and lower facets in the output. Set <em>k</em> + to the last dimension (e.g., 'PD2:1' for 2-d inputs). </dd> + <dt><a href="qh-opto.htm#f">f </a></dt> + <dd>facet dump. Print the data structure for each facet (i.e., + Voronoi vertex).</dd> +</dl> + +</blockquote> +</blockquote> +<h3><a href="#TOP">»</a> <a name="graphics">qvoronoi +graphics</a></h3> +<blockquote> + +<p>In 2-d, Geomview output ('<a href="qh-optg.htm#G">G</a>') +displays a Voronoi diagram with extra edges to close the +unbounded Voronoi regions. To view the unbounded rays, enclose +the input points in a square.</p> + +<p>You can also view <i>individual</i> Voronoi regions in 3-d. To +view the Voronoi region for site 3 in Geomview, execute</p> + +<blockquote> + <p>qvoronoi <data <a href="qh-optq.htm#QVn">QV3</a> <a + href="qh-opto.htm#p">p</a> | qconvex s G >output</p> +</blockquote> + +<p>The <tt>qvoronoi</tt> command returns the Voronoi vertices +for input site 3. The <tt>qconvex</tt> command computes their convex hull. +This is the Voronoi region for input site 3. Its +hyperplane normals (qconvex 'n') are the same as the separating hyperplanes +from options '<a href="qh-optf.htm#Fi">Fi</a>' +and '<a href="qh-optf.htm#Fo">Fo</a>' (up to roundoff error). + +<p>See the <a href="qh-eg.htm#delaunay">Delaunay and Voronoi +examples</a> for 2-d and 3-d examples. Turn off normalization (on +Geomview's 'obscure' menu) when comparing the Voronoi diagram +with the corresponding Delaunay triangulation. </p> + +</blockquote> +<h3><a href="#TOP">»</a><a name="notes">qvoronoi +notes</a></h3> +<blockquote> + +<p>You can simplify the Voronoi diagram by enclosing the input +sites in a large square or cube. This is particularly recommended +for cocircular or cospherical input data.</p> + +<p>See <a href="#graphics">Voronoi graphics</a> for computing +the convex hull of a Voronoi region. </p> + +<p>Voronoi diagrams do not include facets that are +coplanar with the convex hull of the input sites. A facet is +coplanar if the last coefficient of its normal is +nearly zero (see <a href="../src/user.h#ZEROdelaunay">qh_ZEROdelaunay</a>). + +<p>Unbounded regions can be confusing. For example, '<tt>rbox c | +qvoronoi Qz o</tt>' produces the Voronoi regions for the vertices +of a cube centered at the origin. All regions are unbounded. The +output is </p> + +<blockquote> + <pre>3 +2 9 1 +-10.101 -10.101 -10.101 + 0 0 0 +2 0 1 +2 0 1 +2 0 1 +2 0 1 +2 0 1 +2 0 1 +2 0 1 +2 0 1 +0 +</pre> +</blockquote> + +<p>The first line is the dimension. The second line is the number +of vertices and the number of regions. There is one region per +input point plus a region for the point-at-infinity added by +option '<a href="qh-optq.htm#Qz">Qz</a>'. The next two lines +lists the Voronoi vertices. The first vertex is the infinity +vertex. It is indicate by the coordinates <em>-10.101</em>. The +second vertex is the origin. The next nine lines list the +regions. Each region lists two vertices -- the infinity vertex +and the origin. The last line is "0" because no region +is associated with the point-at-infinity. A "0" would +also be listed for nearly incident input sites. </p> + +<p>To use option '<a href="qh-optf.htm#Fv">Fv</a>', add an +interior point. For example, </p> + +<blockquote> + <pre> +rbox c P0 | qvoronoi Fv +20 +5 0 7 1 3 5 +5 0 3 1 4 5 +5 0 5 1 2 3 +5 0 1 1 2 4 +5 0 6 2 3 6 +5 0 2 2 4 6 +5 0 4 4 5 6 +5 0 8 5 3 6 +5 1 2 0 2 4 +5 1 3 0 1 4 +5 1 5 0 1 2 +5 2 4 0 4 6 +5 2 6 0 2 6 +5 3 4 0 4 5 +5 3 7 0 1 5 +5 4 8 0 6 5 +5 5 6 0 2 3 +5 5 7 0 1 3 +5 6 8 0 6 3 +5 7 8 0 3 5 +</pre> +</blockquote> + +<p>The output consists of 20 ridges and each ridge lists a pair +of input sites and a triplet of Voronoi vertices. The first eight +ridges connect the origin ('P0'). The remainder list the edges of +the cube. Each edge generates an unbounded ray through the +midpoint. The corresponding separating planes ('Fo') follow each +pair of coordinate axes. </p> + +<p>Options '<a href="qh-optq.htm#Qt">Qt</a>' (triangulated output) +and '<a href="qh-optq.htm#QJn">QJ</a>' (joggled input) are deprecated. They may produce +unexpected results. If you use these options, cocircular and cospherical input sites will +produce duplicate or nearly duplicate Voronoi vertices. See also <a +href="qh-impre.htm#joggle">Merged facets or joggled input</a>. </p> + +</blockquote> +<h3><a href="#TOP">»</a><a name="conventions">qvoronoi conventions</a></h3> +<blockquote> + +<p>The following terminology is used for Voronoi diagrams in +Qhull. The underlying structure is a Delaunay triangulation from +a convex hull in one higher dimension. Facets of the Delaunay +triangulation correspond to vertices of the Voronoi diagram. +Vertices of the Delaunay triangulation correspond to input sites. +They also correspond to regions of the Voronoi diagram. See <a +href="qconvex.htm#conventions">convex hull conventions</a>, <a +href="qdelaun.htm#conventions">Delaunay conventions</a>, and +<a href="index.htm#structure">Qhull's data structures</a>.</p> +<blockquote> + +<ul> + <li><em>input site</em> - a point in the input (one dimension + lower than a point on the convex hull)</li> + <li><em>point</em> - a point has <i>d+1</i> coordinates. The + last coordinate is the sum of the squares of the input + site's coordinates</li> + <li><em>coplanar point</em> - a <em>nearly incident</em> + input site</li> + <li><em>vertex</em> - a point on the paraboloid. It + corresponds to a unique input site. </li> + <li><em>point-at-infinity</em> - a point added above the + paraboloid by option '<a href="qh-optq.htm#Qz">Qz</a>'</li> + <li><em>Delaunay facet</em> - a lower facet of the + paraboloid. The last coefficient of its normal is + clearly negative.</li> + <li><em>Voronoi vertex</em> - the circumcenter of a Delaunay + facet</li> + <li><em>Voronoi region</em> - the Voronoi vertices for an + input site. The region of Euclidean space nearest to an + input site.</li> + <li><em>Voronoi diagram</em> - the graph of the Voronoi + regions. It includes the ridges (i.e., edges) between the + regions.</li> + <li><em>vertex-at-infinity</em> - the Voronoi vertex that + indicates unbounded Voronoi regions in '<a + href="qh-opto.htm#o">o</a>' output format. Its + coordinates are <em>-10.101</em>.</li> + <li><em>good facet</em> - a Voronoi vertex with optional + restrictions by '<a href="qh-optq.htm#QVn">QVn</a>', etc.</li> +</ul> + +</blockquote> +</blockquote> +<h3><a href="#TOP">»</a><a name="options">qvoronoi options</a></h3> + +<pre> +qvoronoi- compute the Voronoi diagram + http://www.qhull.org + +input (stdin): + first lines: dimension and number of points (or vice-versa). + other lines: point coordinates, best if one point per line + comments: start with a non-numeric character + +options: + Qu - compute furthest-site Voronoi diagram + +Qhull control options: + QJn - randomly joggle input in range [-n,n] + Qs - search all points for the initial simplex + Qz - add point-at-infinity to Voronoi diagram + QGn - Voronoi vertices if visible from point n, -n if not + QVn - Voronoi vertices for input point n, -n if not + +Trace options: + T4 - trace at level n, 4=all, 5=mem/gauss, -1= events + Tc - check frequently during execution + Ts - statistics + Tv - verify result: structure, convexity, and in-circle test + Tz - send all output to stdout + TFn - report summary when n or more facets created + TI file - input data from file, no spaces or single quotes + TO file - output results to file, may be enclosed in single quotes + TPn - turn on tracing when point n added to hull + TMn - turn on tracing at merge n + TWn - trace merge facets when width > n + TVn - stop qhull after adding point n, -n for before (see TCn) + TCn - stop qhull after building cone for point n (see TVn) + +Precision options: + Cn - radius of centrum (roundoff added). Merge facets if non-convex + An - cosine of maximum angle. Merge facets if cosine > n or non-convex + C-0 roundoff, A-0.99/C-0.01 pre-merge, A0.99/C0.01 post-merge + Rn - randomly perturb computations by a factor of [1-n,1+n] + Wn - min facet width for non-coincident point (before roundoff) + +Output formats (may be combined; if none, produces a summary to stdout): + s - summary to stderr + p - Voronoi vertices + o - OFF format (dim, Voronoi vertices, and Voronoi regions) + i - Delaunay regions (use 'Pp' to avoid warning) + f - facet dump + +More formats: + Fc - count plus coincident points (by Voronoi vertex) + Fd - use cdd format for input (homogeneous with offset first) + FD - use cdd format for output (offset first) + FF - facet dump without ridges + Fi - separating hyperplanes for bounded Voronoi regions + FI - ID for each Voronoi vertex + Fm - merge count for each Voronoi vertex (511 max) + Fn - count plus neighboring Voronoi vertices for each Voronoi vertex + FN - count and Voronoi vertices for each Voronoi region + Fo - separating hyperplanes for unbounded Voronoi regions + FO - options and precision constants + FP - nearest point and distance for each coincident point + FQ - command used for qvoronoi + Fs - summary: #int (8), dimension, #points, tot vertices, tot facets, + for output: #Voronoi regions, #Voronoi vertices, + #coincident points, #non-simplicial regions + #real (2), max outer plane and min vertex + Fv - Voronoi diagram as Voronoi vertices between adjacent input sites + Fx - extreme points of Delaunay triangulation (on convex hull) + +Geomview options (2-d only) + Ga - all points as dots + Gp - coplanar points and vertices as radii + Gv - vertices as spheres + Gi - inner planes only + Gn - no planes + Go - outer planes only + Gc - centrums + Gh - hyperplane intersections + Gr - ridges + GDn - drop dimension n in 3-d and 4-d output + +Print options: + PAn - keep n largest Voronoi vertices by 'area' + Pdk:n - drop facet if normal[k] <= n (default 0.0) + PDk:n - drop facet if normal[k] >= n + Pg - print good Voronoi vertices (needs 'QGn' or 'QVn') + PFn - keep Voronoi vertices whose 'area' is at least n + PG - print neighbors of good Voronoi vertices + PMn - keep n Voronoi vertices with most merges + Po - force output. If error, output neighborhood of facet + Pp - do not report precision problems + + . - list of all options + - - one line descriptions of all options +</pre> + +<!-- Navigation links --> +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#synopsis">sy</a>nopsis +• <a href="#input">in</a>put • <a href="#outputs">ou</a>tputs +• <a href="#controls">co</a>ntrols • <a href="#graphics">gr</a>aphics +• <a href="#notes">no</a>tes • <a href="#conventions">co</a>nventions +• <a href="#options">op</a>tions +<!-- GC common information --> +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="qh--geom.gif" +align="middle" width="40" height="40"></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +</a><br> +Created: Sept. 25, 1995 --- <!-- hhmts start --> Last modified: see top <!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/rbox.htm b/xs/src/qhull/html/rbox.htm new file mode 100644 index 000000000..9c28face5 --- /dev/null +++ b/xs/src/qhull/html/rbox.htm @@ -0,0 +1,277 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + +<head> +<title>rbox -- generate point distributions</title> +</head> + +<body> +<!-- Navigation links --> +<p><b><a name="TOP">Up:</a></b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#synopsis">sy</a>nopsis • <a href="#outputs">ou</a>tputs +• <a href="#examples">ex</a>amples • <a href="#notes">no</a>tes +• <a href="#options">op</a>tions +<hr> +<!-- Main text of document --> +<h1><a +href="http://www.geom.uiuc.edu/graphics/pix/Special_Topics/Computational_Geometry/cone.html"><img +src="qh--cone.gif" alt="[CONE]" align="middle" width="100" +height="100"></a>rbox -- generate point distributions</h1> + +<blockquote> + rbox generates random or regular points according to the + options given, and outputs the points to stdout. The + points are generated in a cube, unless 's', 'x', or 'y' + are given. + +</blockquote> +<h3><a href="#TOP">»</a><a name="synopsis">rbox synopsis</a></h3> +<pre> +rbox- generate various point distributions. Default is random in cube. + +args (any order, space separated): + 3000 number of random points in cube, lens, spiral, sphere or grid + D3 dimension 3-d + c add a unit cube to the output ('c G2.0' sets size) + d add a unit diamond to the output ('d G2.0' sets size) + l generate a regular 3-d spiral + r generate a regular polygon, ('r s Z1 G0.1' makes a cone) + s generate cospherical points + x generate random points in simplex, may use 'r' or 'Wn' + y same as 'x', plus simplex + Cn,r,m add n nearly coincident points within radius r of m points + Pn,m,r add point [n,m,r] first, pads with 0 + + Ln lens distribution of radius n. Also 's', 'r', 'G', 'W'. + Mn,m,r lattice (Mesh) rotated by [n,-m,0], [m,n,0], [0,0,r], ... + '27 M1,0,1' is {0,1,2} x {0,1,2} x {0,1,2}. Try 'M3,4 z'. + W0.1 random distribution within 0.1 of the cube's or sphere's surface + Z0.5 s random points in a 0.5 disk projected to a sphere + Z0.5 s G0.6 same as Z0.5 within a 0.6 gap + + Bn bounding box coordinates, default 0.5 + h output as homogeneous coordinates for cdd + n remove command line from the first line of output + On offset coordinates by n + t use time as the random number seed (default is command line) + tn use n as the random number seed + z print integer coordinates, default 'Bn' is 1e+06 +</pre> + +<h3><a href="#TOP">»</a><a name="outputs">rbox outputs</a></h3> +<blockquote> + +The format of the output is the following: first line contains + the dimension and a comment, second line contains the + number of points, and the following lines contain the points, + one point per line. Points are represented by their coordinate values. + +<p>For example, <tt>rbox c 10 D2</tt> generates +<blockquote> +<pre> +2 RBOX c 10 D2 +14 +-0.4999921736307369 -0.3684622117955817 +0.2556053225468894 -0.0413498678629751 +0.0327672376602583 -0.2810408135699488 +-0.452955383763607 0.17886471718444 +0.1792964061529342 0.4346928963760779 +-0.1164979223315585 0.01941637230982666 +0.3309653464993139 -0.4654278894564396 +-0.4465383649305798 0.02970019358182344 +0.1711493843897706 -0.4923018137852678 +-0.1165843490665633 -0.433157762450313 + -0.5 -0.5 + -0.5 0.5 + 0.5 -0.5 + 0.5 0.5 +</pre> + +</blockquote> + +</blockquote> +<h3><a href="#TOP">»</a><a name="examples">rbox examples</a></h3> + +<pre> + rbox 10 + 10 random points in the unit cube centered at the + origin. + + rbox 10 s D2 + 10 random points on a 2-d circle. + + rbox 100 W0 + 100 random points on the surface of a cube. + + rbox 1000 s D4 + 1000 random points on a 4-d sphere. + + rbox c D5 O0.5 + a 5-d hypercube with one corner at the origin. + + rbox d D10 + a 10-d diamond. + + rbox x 1000 r W0 + 100 random points on the surface of a fixed simplex + + rbox y D12 + a 12-d simplex. + + rbox l 10 + 10 random points along a spiral + + rbox l 10 r + 10 regular points along a spiral plus two end + points + + rbox 1000 L10000 D4 s + 1000 random points on the surface of a narrow lens. + + rbox 1000 L100000 s G1e-6 + 1000 random points near the edge of a narrow lens + + rbox c G2 d G3 + a cube with coordinates +2/-2 and a diamond with + coordinates +3/-3. + + rbox 64 M3,4 z + a rotated, {0,1,2,3} x {0,1,2,3} x {0,1,2,3} lat- + tice (Mesh) of integer points. + + rbox P0 P0 P0 P0 P0 + 5 copies of the origin in 3-d. Try 'rbox P0 P0 P0 + P0 P0 | qhull QJ'. + + r 100 s Z1 G0.1 + two cospherical 100-gons plus another cospherical + point. + + 100 s Z1 + a cone of points. + + 100 s Z1e-7 + a narrow cone of points with many precision errors. +</pre> + +<h3><a href="#TOP">»</a><a name="notes">rbox notes</a></h3> +<blockquote> +Some combinations of arguments generate odd results. + +</blockquote> +<h3><a href="#TOP">»</a><a name="options">rbox options</a></h3> + +<pre> + n number of points + + Dn dimension n-d (default 3-d) + + Bn bounding box coordinates (default 0.5) + + l spiral distribution, available only in 3-d + + Ln lens distribution of radius n. May be used with + 's', 'r', 'G', and 'W'. + + Mn,m,r lattice (Mesh) rotated by {[n,-m,0], [m,n,0], + [0,0,r], ...}. Use 'Mm,n' for a rigid rotation + with r = sqrt(n^2+m^2). 'M1,0' is an orthogonal + lattice. For example, '27 M1,0' is {0,1,2} x + {0,1,2} x {0,1,2}. + + s cospherical points randomly generated in a cube and + projected to the unit sphere + + x simplicial distribution. It is fixed for option + 'r'. May be used with 'W'. + + y simplicial distribution plus a simplex. Both 'x' + and 'y' generate the same points. + + Wn restrict points to distance n of the surface of a + sphere or a cube + + c add a unit cube to the output + + c Gm add a cube with all combinations of +m and -m to + the output + + d add a unit diamond to the output. + + d Gm add a diamond made of 0, +m and -m to the output + + Cn,r,m add n nearly coincident points within radius r of m points + + Pn,m,r add point [n,m,r] to the output first. Pad coordi- + nates with 0.0. + + n Remove the command line from the first line of out- + put. + + On offset the data by adding n to each coordinate. + + t use time in seconds as the random number seed + (default is command line). + + tn set the random number seed to n. + + z generate integer coordinates. Use 'Bn' to change + the range. The default is 'B1e6' for six-digit + coordinates. In R^4, seven-digit coordinates will + overflow hyperplane normalization. + + Zn s restrict points to a disk about the z+ axis and the + sphere (default Z1.0). Includes the opposite pole. + 'Z1e-6' generates degenerate points under single + precision. + + Zn Gm s + same as Zn with an empty center (default G0.5). + + r s D2 generate a regular polygon + + r s Z1 G0.1 + generate a regular cone +</pre> + +<!-- Navigation links --> +<hr> + +<p><b>Up:</b> <a href="http://www.qhull.org">Home page</a> for Qhull<br> +<b>Up:</b> <a href="index.htm#TOC">Qhull manual</a>: Table of Contents<br> +<b>To:</b> <a href="qh-quick.htm#programs">Programs</a> +• <a href="qh-quick.htm#options">Options</a> +• <a href="qh-opto.htm#output">Output</a> +• <a href="qh-optf.htm#format">Formats</a> +• <a href="qh-optg.htm#geomview">Geomview</a> +• <a href="qh-optp.htm#print">Print</a> +• <a href="qh-optq.htm#qhull">Qhull</a> +• <a href="qh-optc.htm#prec">Precision</a> +• <a href="qh-optt.htm#trace">Trace</a> +• <a href="../src/libqhull_r/index.htm">Functions</a><br> +<b>To:</b> <a href="#synopsis">sy</a>nopsis • <a href="#outputs">ou</a>tputs +• <a href="#examples">ex</a>amples • <a href="#notes">no</a>tes +• <a href="#options">op</a>tions +<!-- GC common information --> +<hr> + +<p><a href="http://www.geom.uiuc.edu/"><img src="qh--geom.gif" +align="middle" width="40" height="40"></a><i>The Geometry Center +Home Page </i></p> + +<p>Comments to: <a href=mailto:qhull@qhull.org>qhull@qhull.org</a> +<br> +Created: Sept. 25, 1995 --- <!-- hhmts start --> Last modified: August 12, 1998 <!-- hhmts end --> </p> +</body> +</html> diff --git a/xs/src/qhull/html/rbox.man b/xs/src/qhull/html/rbox.man new file mode 100644 index 000000000..3ea6395e6 --- /dev/null +++ b/xs/src/qhull/html/rbox.man @@ -0,0 +1,176 @@ +.\" This is the Unix manual page for rbox, written in nroff, the standard +.\" manual formatter for Unix systems. To format it, type +.\" +.\" nroff -man rbox.man +.\" +.\" This will print a formatted copy to standard output. If you want +.\" to ensure that the output is plain ascii, free of any control +.\" characters that nroff uses for underlining etc, pipe the output +.\" through "col -b": +.\" +.\" nroff -man rbox.man | col -b +.\" +.TH rbox 1 "August 10, 1998" "Geometry Center" +.SH NAME +rbox \- generate point distributions for qhull +.SH SYNOPSIS +Command "rbox" (w/o arguments) lists the options. +.SH DESCRIPTION +.PP +rbox generates random or regular points according to the options given, and +outputs +the points to stdout. The points are generated in a cube, unless 's' or 'k' +option is +given. The format of the output is the following: first line +contains the dimension and a comment, +second line contains the number of points, and the +following lines contain the points, one point per line. Points are represented +by their coordinate values. +.SH EXAMPLES +.TP +rbox 10 +10 random points in the unit cube centered at the origin. +.TP +rbox 10 s D2 +10 random points on a 2\[hy]d circle. +.TP +rbox 100 W0 +100 random points on the surface of a cube. +.TP +rbox 1000 s D4 +1000 random points on a 4\[hy]d sphere. +.TP +rbox c D5 O0.5 +a 5\[hy]d hypercube with one corner at the origin. +.TP +rbox d D10 +a 10\[hy]d diamond. +.TP +rbox x 1000 r W0 +100 random points on the surface of a fixed simplex +.TP +rbox y D12 +a 12\[hy]d simplex. +.TP +rbox l 10 +10 random points along a spiral +.TP +rbox l 10 r +10 regular points along a spiral plus two end points +.TP +rbox 1000 L10000 D4 s +1000 random points on the surface of a narrow lens. +.TP +rbox c G2 d G3 +a cube with coordinates +2/\-2 and a diamond with coordinates +3/\-3. +.TP +rbox 64 M3,4 z +a rotated, {0,1,2,3} x {0,1,2,3} x {0,1,2,3} lattice (Mesh) of integer +points. 'rbox 64 M1,0' is orthogonal. +.TP +rbox P0 P0 P0 P0 P0 +5 copies of the origin in 3\-d. Try 'rbox P0 P0 P0 P0 P0 | qhull QJ'. +.TP +r 100 s Z1 G0.1 +two cospherical 100\-gons plus another cospherical point. +.TP +100 s Z1 +a cone of points. +.TP +100 s Z1e\-7 +a narrow cone of points with many precision errors. +.SH OPTIONS +.TP +n +number of points +.TP +Dn +dimension n\[hy]d (default 3\[hy]d) +.TP +Bn +bounding box coordinates (default 0.5) +.TP +l +spiral distribution, available only in 3\[hy]d +.TP +Ln +lens distribution of radius n. May be used with 's', 'r', 'G', and 'W'. +.TP +Mn,m,r +lattice (Mesh) rotated by {[n,\-m,0], [m,n,0], [0,0,r], ...}. +Use 'Mm,n' for a rigid rotation with r = sqrt(n^2+m^2). 'M1,0' is an +orthogonal lattice. For example, '27 M1,0' is {0,1,2} x {0,1,2} x +{0,1,2}. '27 M3,4 z' is a rotated integer lattice. +.TP +s +cospherical points randomly generated in a cube and projected to the unit sphere +.TP +x +simplicial distribution. It is fixed for option 'r'. May be used with 'W'. +.TP +y +simplicial distribution plus a simplex. Both 'x' and 'y' generate the same points. +.TP +Wn +restrict points to distance n of the surface of a sphere or a cube +.TP +c +add a unit cube to the output +.TP +c Gm +add a cube with all combinations of +m and \-m to the output +.TP +d +add a unit diamond to the output. +.TP +d Gm +add a diamond made of 0, +m and \-m to the output +.TP +Cn,r,m +add n nearly coincident points within radius r of m points +.TP +Pn,m,r +add point [n,m,r] to the output first. Pad coordinates with 0.0. +.TP +n +Remove the command line from the first line of output. +.TP +On +offset the data by adding n to each coordinate. +.TP +t +use time in seconds as the random number seed (default is command line). +.TP +tn +set the random number seed to n. +.TP +z +generate integer coordinates. Use 'Bn' to change the range. +The default is 'B1e6' for six\[hy]digit coordinates. In R^4, seven\[hy]digit +coordinates will overflow hyperplane normalization. +.TP +Zn s +restrict points to a disk about the z+ axis and the sphere (default Z1.0). +Includes the opposite pole. 'Z1e\-6' generates degenerate points under +single precision. +.TP +Zn Gm s +same as Zn with an empty center (default G0.5). +.TP +r s D2 +generate a regular polygon +.TP +r s Z1 G0.1 +generate a regular cone +.SH BUGS +Some combinations of arguments generate odd results. + +Report bugs to qhull_bug@qhull.org, other correspondence to qhull@qhull.org +.SH SEE ALSO +qhull(1) +.SH AUTHOR +.nf +C. Bradford Barber +bradb@shore.net +.fi + diff --git a/xs/src/qhull/html/rbox.txt b/xs/src/qhull/html/rbox.txt new file mode 100644 index 000000000..e3cf72189 --- /dev/null +++ b/xs/src/qhull/html/rbox.txt @@ -0,0 +1,195 @@ + + + +rbox(1) rbox(1) + + +NAME + rbox - generate point distributions for qhull + +SYNOPSIS + Command "rbox" (w/o arguments) lists the options. + +DESCRIPTION + rbox generates random or regular points according to the + options given, and outputs the points to stdout. The + points are generated in a cube, unless 's' or given. The + format of the output is the following: first line contains + the dimension and a comment, second line contains the num- + ber of points, and the following lines contain the points, + one point per line. Points are represented by their coor- + dinate values. + +EXAMPLES + rbox 10 + 10 random points in the unit cube centered at the + origin. + + rbox 10 s D2 + 10 random points on a 2-d circle. + + rbox 100 W0 + 100 random points on the surface of a cube. + + rbox 1000 s D4 + 1000 random points on a 4-d sphere. + + rbox c D5 O0.5 + a 5-d hypercube with one corner at the origin. + + rbox d D10 + a 10-d diamond. + + rbox x 1000 r W0 + 100 random points on the surface of a fixed simplex + + rbox y D12 + a 12-d simplex. + + rbox l 10 + 10 random points along a spiral + + rbox l 10 r + 10 regular points along a spiral plus two end + points + + rbox 1000 L10000 D4 s + 1000 random points on the surface of a narrow lens. + + rbox c G2 d G3 + a cube with coordinates +2/-2 and a diamond with + + + +Geometry Center August 10, 1998 1 + + + + + +rbox(1) rbox(1) + + + coordinates +3/-3. + + rbox 64 M3,4 z + a rotated, {0,1,2,3} x {0,1,2,3} x {0,1,2,3} lat- + tice (Mesh) of integer points. + + rbox P0 P0 P0 P0 P0 + 5 copies of the origin in 3-d. Try 'rbox P0 P0 P0 + P0 P0 | qhull QJ'. + + r 100 s Z1 G0.1 + two cospherical 100-gons plus another cospherical + point. + + 100 s Z1 + a cone of points. + + 100 s Z1e-7 + a narrow cone of points with many precision errors. + +OPTIONS + n number of points + + Dn dimension n-d (default 3-d) + + Bn bounding box coordinates (default 0.5) + + l spiral distribution, available only in 3-d + + Ln lens distribution of radius n. May be used with + 's', 'r', 'G', and 'W'. + + Mn,m,r lattice (Mesh) rotated by {[n,-m,0], [m,n,0], + [0,0,r], ...}. Use 'Mm,n' for a rigid rotation + with r = sqrt(n^2+m^2). 'M1,0' is an orthogonal + lattice. For example, '27 M1,0' is {0,1,2} x + {0,1,2} x {0,1,2}. + + s cospherical points randomly generated in a cube and + projected to the unit sphere + + x simplicial distribution. It is fixed for option + 'r'. May be used with 'W'. + + y simplicial distribution plus a simplex. Both 'x' + and 'y' generate the same points. + + Wn restrict points to distance n of the surface of a + sphere or a cube + + c add a unit cube to the output + + c Gm add a cube with all combinations of +m and -m to + the output + + + +Geometry Center August 10, 1998 2 + + + + + +rbox(1) rbox(1) + + + d add a unit diamond to the output. + + d Gm add a diamond made of 0, +m and -m to the output + + Cn,r,m add n nearly coincident points within radius r of m points + + Pn,m,r add point [n,m,r] to the output first. Pad coordi- + nates with 0.0. + + n Remove the command line from the first line of out- + put. + + On offset the data by adding n to each coordinate. + + t use time in seconds as the random number seed + (default is command line). + + tn set the random number seed to n. + + z generate integer coordinates. Use 'Bn' to change + the range. The default is 'B1e6' for six-digit + coordinates. In R^4, seven-digit coordinates will + overflow hyperplane normalization. + + Zn s restrict points to a disk about the z+ axis and the + sphere (default Z1.0). Includes the opposite pole. + 'Z1e-6' generates degenerate points under single + precision. + + Zn Gm s + same as Zn with an empty center (default G0.5). + + r s D2 generate a regular polygon + + r s Z1 G0.1 + generate a regular cone + +BUGS + Some combinations of arguments generate odd results. + + Report bugs to qhull_bug@qhull.org, other correspon- + dence to qhull@qhull.org + +SEE ALSO + qhull(1) + +AUTHOR + C. Bradford Barber + bradb@shore.net + + + + + +Geometry Center August 10, 1998 3 + + |
