<?xml version="1.0" encoding="utf-8"?>
<section version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd"
         xml:id="particles.modifiers.construct_surface_mesh"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:ns="http://docbook.org/ns/docbook">
  <title>Construct surface mesh</title>

  <para>
  
    <informalfigure>
      <informaltable frame="none">
        <tgroup cols="2">
          <tbody>
            <row valign="bottom">
              <entry>Input:</entry>
              <entry>Output:</entry>
            </row>
            <row valign="top">
              <entry>
		        <mediaobject><imageobject>
		        <imagedata fileref="images/modifiers/construct_surface_example_input.png" format="PNG" />
		        </imageobject></mediaobject>
              </entry>
              <entry>
		        <mediaobject><imageobject>
		        <imagedata fileref="images/modifiers/construct_surface_example_output.png" format="PNG" />
		        </imageobject></mediaobject>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </informalfigure>
      
    <informalfigure><screenshot><mediaobject><imageobject>
       <imagedata fileref="images/modifiers/construct_surface_mesh_panel.png" format="PNG" />
    </imageobject></mediaobject></screenshot></informalfigure>
    
    This modifier constructs a polyhedral mesh around a set of particles. It can be used to generate
    a geometric representation of the outer and inner surfaces of an atomistic solid. In addition to
    visualization purposes, the geometric description of the surface is good for quantitative 
    measurements of the surface area and the solid volume or porosity of an atomistic structure. 
  </para>

  <para>
    After constructing the surface, the modifier also computes and reports the total surface area and the solid volume
    of the solid. If you are using this analysis modifier, please cite the following article, 
    which describes the algorithm implemented in OVITO: 
    <blockquote><para>
<literallayout><link xlink:href="http://dx.doi.org/10.1007/s11837-013-0827-5">A. Stukowski,
<emphasis>Computational Analysis Methods in Atomistic Modeling of Crystals</emphasis>,
JOM: Vol. 66, Issue 3 (2014), 399-407</link></literallayout>
    </para></blockquote>
  </para>
  
  <para>
    The surface construction algorithm requires considerable memory, typically up to 1 kilobyte 
    per input particle. So make sure your system has enough RAM available when applying this modifier to large datasets.
  </para>
  
  <para>    
    The visual appearance of the polyhedral mesh generated by this modifier is controlled by the attached 
    <link linkend="display_objects.surface_mesh">surface mesh display object</link>. 
  </para>
  
  <simplesect>
    <title>How it works</title>
 	<para>
 	  In classical atomistic simulations the atoms that constitute a solid are modeled as point-like objects. 
 	  Consequently, the simulated solid has no volume and no surface if it is described as such a set of zero-dimensional 
 	  points in space. This is in contrast to our perception of solids and the continuum descriptions typically used at 
 	  larger length scales, where solids always have a well-defined volume and boundaries. To bridge this gap between the 
 	  atomistic model and the continuum world, a special type of transformation method is needed. Without it, we would be 
 	  unable to properly quantify important properties of atomistic systems like their solid volume, surface area, 
 	  surface orientation and curvature, or porosity.
    </para>
    <para>
       The aim is therefore to reconstruct the geometric boundaries of a set of points in space and build a 
       two-dimensional, closed, and oriented manifold that divides space into an inner (=solid) and an outer (=open) region. 
       If we want to define the surface of an atomistic solid, an indispensable ingredient is some sort of length scale 
       parameter. How else should we discern the empty space in between atomic points of a dense solid from actual pores 
       or small cracks? A common solution to this problem is the concept of a probe sphere. The open region is here defined 
       as those parts of space that are accessible to the virtual probe sphere without touching any of the atomic points. 
       Note that this includes cavities inside the solid as long as they can accommodate the virtual sphere. The radius of 
       the probe sphere is the length scale parameter that needs to be specified by the user. It determines how many details 
       and small features of the solid's geometric shape are resolved by the method.    
    </para>
    <para>
       <informalfigure>
       <informaltable frame="none">
       <tgroup cols="1">
          <tbody>
            <row>
              <entry><screenshot><mediaobject><imageobject>
              <imagedata fileref="images/modifiers/construct_surface_mesh_alphashape.png" format="PNG" />
              </imageobject></mediaobject></screenshot></entry>
            </row>
            <row>
              <entry><para>
         (a) The Delaunay tessellation calculated from the input point set. 
         (b) Two exemplary tessellation elements are highlighted, and their circumspheres are indicated. 
         One element's circumsphere is larger than the reference probe sphere while the other is smaller. 
         The corresponding elements are classified as open and solid, respectively. (c) The union of all 
         solid Delaunay elements defines the geometric shape of the atomistic solid (bold line).
              </para></entry>
            </row>
          </tbody>
          </tgroup>
          </informaltable>
         </informalfigure>
       The algorithm developed for the <guilabel>Construct Surface Mesh</guilabel> modifier of OVITO is based on the alpha-shape method of Edelsbrunner and 
       Mücke [ACM Trans. Graph. 13:43–72, 1994]. It starts with the Delaunay tetrahedrization of the input point set 
       (figure (a)). From the resulting tetrahedra, which fill the convex hull of the point set, all elements are removed 
       whose circumsphere does not fit into the virtual probe sphere (figure (b)). The remaining tetrahedra form the solid 
       region. Now the closed surface mesh can be extracted, which consists of the triangular faces of the tessellation that 
       divide the solid from the open region (figure (c)). 
    </para>
    <para>
       <informalfigure>
       <informaltable frame="none">
       <tgroup cols="1">
          <tbody>
            <row>
              <entry><screenshot><mediaobject><imageobject>
              <imagedata fileref="images/modifiers/construct_surface_mesh_particle.png" format="PNG" />
              </imageobject></mediaobject></screenshot></entry>
            </row>
            <row>
              <entry><para>
                (a) Atomistic model of a carbon nanoparticle with an inset showing the corresponding 
                <link linkend="particles.modifiers.coordination_analysis">pair distribution 
                function</link>. The position of the first peak is used as probe sphere radius (R<subscript>&#x003B1;</subscript>=2.5 &#x212B;)
                for the alpha-shape construction. (b) The resulting triangulated surface mesh. 
                (c) Final surface model after six iterations of the smoothing algorithm were applied.
              </para></entry>
            </row>
          </tbody>
          </tgroup>
          </informaltable>
         </informalfigure>
       The resulting surface mesh reflects the atomic steps that are typically present on the surfaces of a solid. 
       This may lead to an overestimation of the macroscopic surface area. Therefore, if such detailed surface features 
       are undesired, one can subsequently apply a fairing procedure [Taubin, SIGGRAPH 95 Conf. Proc., pp. 351-358, 1995] 
       to the surface mesh to smooth it. 
    </para>
    <para>
      It needs to be emphasized that the results of the described surface reconstruction method generally depend on the selected probe 
      sphere radius parameter R<subscript>&#x003B1;</subscript>. A rule of thumb is to choose R<subscript>&#x003B1;</subscript> equal to the nearest neighbor atom 
      separation in the material at hand as demonstrated in figure (a) on the right. Definitely, the value of R<subscript>&#x003B1;</subscript> 
      should be reported in publications where the geometric surface reconstruction method is used to quantitatively measure 
      surface areas, solid volumes, or porosities.
   </para>
  </simplesect>
   
   <simplesect>
    <title>Parameters</title>

    <variablelist>
      <varlistentry>
        <term>Probe sphere radius</term>
        <listitem>
          <para>This parameter controls the radius of the probe sphere used in the surface construction algorithm, which 
          determines the level of surface details captured. A larger sphere radius leads to 
          a surface with less details, which reflects only coarser features of the surface topology. 
          A small sphere radius, on the other hand, will resolve finer surface features and small voids inside a solid.
          However, the sphere radius should not be smaller than half of the typical interatomic
          distance. Otherwise artificial holes will appear in the constructed surface.</para>
          <para>
          A rule of thumb is to choose this parameter equal to the nearest neighbor atom separation in the material at 
          hand. You can use the <link linkend="particles.modifiers.coordination_analysis">Coordination Analysis</link> modifier to determine the nearest neighbor separation, which is the
          position of the first peak in the radial pair distribution function.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Smoothing level</term>
        <listitem>
          <para>After the triangulated surface mesh has been constructed, it is further refined
          by applying a smoothing and fairing algorithm to remove atomically sharp surface steps.
          This parameter controls how many iterations of the smoothing algorithm are performed.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Use only selected particles</term>
        <listitem>
          <para>By default, the modifier constructs the surface mesh around all input particles.
          This option restricts the construction to only the selected particles.</para>
        </listitem>
      </varlistentry>
	</variablelist>
    </simplesect>
     
</section>
