sampledSurfaces: Added documentation

src/sampling/sampledSurface/distanceSurface/distanceSurface.H

@@ -2,7 +2,7 @@
   =========                 |
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     | Website:  https://openfoam.org
-    \\  /    A nd           | Copyright (C) 2011-2019 OpenFOAM Foundation
+    \\  /    A nd           | Copyright (C) 2011-2020 OpenFOAM Foundation
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
 License
@@ -27,6 +27,35 @@ Class
 Description
     A sampledSurface defined by a distance to a surface.
 
+    Example:
+    \verbatim
+    {
+        type        distanceSurface;
+        surfaceType searchableBox;
+        min         (-1 -1 -1);
+        max         (1 1 1);
+        distance    0.1;
+        signed      yes;
+        filter      full;
+        interpolate yes;
+    }
+    \endverbatim
+
+Usage
+    \table
+        Property     | Description             | Required    | Default value
+        surfaceType  | the type of surface to sample from | yes |
+        distance     | the distance from which to sample the surface | yes |
+        signed       | sample only on one side of the surface, specified by \\
+                       the sign of the distance | yes |
+        filter       | the level of filtering to perform on the iso-surface \\
+                                               | no          | full
+        interpolate  | interpolate values to the surface points | no | no
+    \endtable
+
+See also
+    Foam::isoSurface
+
 SourceFiles
     distanceSurface.C
 

src/sampling/sampledSurface/isoSurface/isoSurface.H

@@ -2,7 +2,7 @@
   =========                 |
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     | Website:  https://openfoam.org
-    \\  /    A nd           | Copyright (C) 2011-2019 OpenFOAM Foundation
+    \\  /    A nd           | Copyright (C) 2011-2020 OpenFOAM Foundation
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
 License
@@ -25,8 +25,22 @@ Class
     Foam::isoSurface
 
 Description
-    Marching tet iso surface algorithm with optional filtering to keep only
+    Marching tet iso surface algorithm with filtering to remove unnecessary
-    points originating from mesh edges.
+    topology.
+
+    Three levels of filtering are possible:
+
+    - none:
+        Don't filter; the full intersection between the iso surface and the
+        tetrahedral decomposition of the mesh is generated
+
+    - partial:
+        Remove points from vertex to cell-centre edges and merge triangles that
+        form a contiguous cut through a single cell
+
+    - full:
+        As partial, but also remove points from face-diagonals and merge edges
+        that originate from the same face
 
 SourceFiles
     isoSurface.C
@@ -63,12 +77,9 @@ public:
 
         enum class filterType
         {
-            none,       // No filtering
+            none,
-            partial,    // Remove points from vertex to cell-centre edges and
+            partial,
-                        // merge triangles that form a contiguous cut through a
+            full
-                        // single cell
-            full        // Also remove points from face-diagonals and merge
-                        // edges that originate from the same face
         };
 
         static const NamedEnum<filterType, 3> filterTypeNames_;

src/sampling/sampledSurface/isoSurface/sampledIsoSurface.H

@@ -2,7 +2,7 @@
   =========                 |
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     | Website:  https://openfoam.org
-    \\  /    A nd           | Copyright (C) 2011-2019 OpenFOAM Foundation
+    \\  /    A nd           | Copyright (C) 2011-2020 OpenFOAM Foundation
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
 License
@@ -26,8 +26,30 @@ Class
 
 Description
     A sampledSurface defined by a surface of iso value.
-    To be used in sampleSurfaces / functionObjects. Recalculates iso surface
+
-    only if time changes.
+    Example:
+    \verbatim
+    {
+        type        isoSurface;
+        isoField    p;
+        isoValue    1e5;
+        filter      full;
+        interpolate yes;
+    }
+    \endverbatim
+
+Usage
+    \table
+        Property     | Description             | Required    | Default value
+        isoField     | the field to get an iso-surface of | yes |
+        isoValue     | the iso-surface value   | yes         |
+        filter       | the level of filtering to perform on the iso-surface \\
+                                               | no          | full
+        interpolate  | interpolate values to the surface points | no | no
+    \endtable
+
+See also
+    Foam::isoSurface
 
 SourceFiles
     sampledIsoSurface.C

src/sampling/sampledSurface/sampledCuttingPlane/sampledCuttingPlane.H

@@ -2,7 +2,7 @@
   =========                 |
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     | Website:  https://openfoam.org
-    \\  /    A nd           | Copyright (C) 2011-2019 OpenFOAM Foundation
+    \\  /    A nd           | Copyright (C) 2011-2020 OpenFOAM Foundation
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
 License
@@ -28,6 +28,31 @@ Description
     A sampledSurface defined by a plane using the iso-surface algorithm
     to 'cut' the mesh.
 
+    Example:
+    \verbatim
+    {
+        type        cuttingPlane;
+        planeType   pointAndNormal;
+        basePoint   (0 0 0);
+        normalVector (0 0 1);
+        filter      full;
+        interpolate yes;
+    }
+    \endverbatim
+
+Usage
+    \table
+        Property     | Description             | Required    | Default value
+        planeType    | the method of specification of the plane | yes |
+        filter       | the level of filtering to perform on the iso-surface \\
+                                               | no          | full
+        interpolate  | interpolate values to the surface points | no | no
+    \endtable
+
+See also
+    Foam::plane
+    Foam::isoSurface
+
 SourceFiles
     sampledCuttingPlane.C
 

src/sampling/sampledSurface/sampledPatch/sampledPatch.H

@@ -2,7 +2,7 @@
   =========                 |
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     | Website:  https://openfoam.org
-    \\  /    A nd           | Copyright (C) 2011-2019 OpenFOAM Foundation
+    \\  /    A nd           | Copyright (C) 2011-2020 OpenFOAM Foundation
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
 License
@@ -27,6 +27,24 @@ Class
 Description
     A sampledSurface on patches. Non-triangulated by default.
 
+    Example:
+    \verbatim
+    {
+        type        patch;
+        patches     (walls);
+        triangulate no;
+        interpolate yes;
+    }
+    \endverbatim
+
+Usage
+    \table
+        Property     | Description             | Required    | Default value
+        patches      | the names of patches on which to sample | yes |
+        triangulate  | triangulate the output  | no          | no
+        interpolate  | interpolate values to the surface points | no | no
+    \endtable
+
 SourceFiles
     sampledPatch.C
 

src/sampling/sampledSurface/sampledPlane/sampledPlane.H

@@ -28,8 +28,27 @@ Description
     A sampledSurface defined by a plane which 'cuts' the mesh using the
     cuttingPlane algorithm. The plane is triangulated by default.
 
-Note
+    Example:
-    Does not actually cut until update() called.
+    \verbatim
+    {
+        type        plane;
+        planeType   pointAndNormal;
+        basePoint   (0 0 0);
+        normalVector (0 0 1);
+        interpolate yes;
+    }
+    \endverbatim
+
+Usage
+    \table
+        Property     | Description             | Required    | Default value
+        planeType    | the method of specification of the plane | yes |
+        triangulate  | triangulate the output  | no          | yes
+        interpolate  | interpolate values to the surface points | no | no
+    \endtable
+
+See also
+    Foam::plane
 
 SourceFiles
     sampledPlane.C

src/sampling/sampledSurface/sampledSurfaces/sampledSurfaces.H

@@ -2,7 +2,7 @@
   =========                 |
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     | Website:  https://openfoam.org
-    \\  /    A nd           | Copyright (C) 2011-2019 OpenFOAM Foundation
+    \\  /    A nd           | Copyright (C) 2011-2020 OpenFOAM Foundation
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
 License
@@ -25,9 +25,53 @@ Class
     Foam::sampledSurfaces
 
 Description
-    Set of surfaces to sample.
+    Set of surfaces to sample
 
-    The write() method is used to sample and write files.
+    Example of function object specification:
+    \verbatim
+    surfaces1
+    {
+        type            surfaces;
+        libs            ("libsampling.so");
+
+        writeControl    writeTime;
+
+        fields          (p U);
+
+        surfaceFormat   vtk;
+        interpolationScheme cellPoint;
+
+        surfaces
+        (
+            p1e5
+            {
+                type            isoSurface;
+                isoField        p;
+                isoValue        1e5;
+                interpolate     yes;
+            }
+        );
+    }
+    \endverbatim
+
+Usage
+    \table
+        Property     | Description             | Required    | Default value
+        type         | type name: surfaces     | yes         |
+        surfaceFormat | the format in which to write the surface file | yes   |
+        interpolationScheme | the method by which values are interpolated \\
+                              from the mesh to the surface | yes
+        surfaces     | the list of surfaces    | yes         |
+    \endtable
+
+See also
+    Foam::sampledSurfaces::distanceSurface
+    Foam::sampledSurfaces::isoSurface
+    Foam::sampledSurfaces::cuttingPlane
+    Foam::sampledSurfaces::patch
+    Foam::sampledSurfaces::plane
+    Foam::sampledSurfaces::triSurfaceMesh
+    Foam::sampledSurfaces::thresholdCellFaces
 
 SourceFiles
     sampledSurfaces.C

src/sampling/sampledSurface/sampledTriSurfaceMesh/sampledTriSurfaceMesh.H

@@ -2,7 +2,7 @@
   =========                 |
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     | Website:  https://openfoam.org
-    \\  /    A nd           | Copyright (C) 2011-2019 OpenFOAM Foundation
+    \\  /    A nd           | Copyright (C) 2011-2020 OpenFOAM Foundation
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
 License
@@ -26,39 +26,57 @@ Class
 
 Description
     A sampledSurface from a triSurfaceMesh. It samples on the points/triangles
-    of the triSurface.
+    of the triSurface. It either samples cells or (non-coupled) boundary faces.
 
-    - it either samples cells or (non-coupled) boundary faces
+    There are 6 possible modes:
 
-    - 6 different modes:
     - source=cells, interpolate=false:
-            finds per triangle centre the nearest cell centre and uses its value
+        Finds per triangle centre the nearest cell centre and uses its value.
+
     - source=cells, interpolate=true
-            finds per triangle centre the nearest cell centre.
+        Finds per triangle centre the nearest cell centre. Per surface point
-            Per surface point checks if this nearest cell is the one containing
+        checks if this nearest cell is the one containing point; otherwise
-            point; otherwise projects the point onto the nearest point on
+        projects the point onto the nearest point on the boundary of the cell
-            the boundary of the cell (to make sure interpolateCellPoint
+        (to make sure interpolateCellPoint gets a valid location)
-            gets a valid location)
 
     - source=insideCells, interpolate=false:
-            finds per triangle centre the cell containing it and uses its value.
+        Finds per triangle centre the cell containing it and uses its value.
         Trims triangles outside mesh.
+
     - source=insideCells, interpolate=true
         Per surface point interpolate cell containing it.
 
     - source=boundaryFaces, interpolate=false:
-            finds per triangle centre the nearest point on the boundary
+        Finds per triangle centre the nearest point on the boundary (uncoupled
-            (uncoupled faces only) and uses the value (or 0 if the nearest
+        faces only) and uses the value (or 0 if the nearest is on an empty
-            is on an empty boundary)
+        boundary).
-        - source=boundaryFaces, interpolate=true:
-            finds per triangle centre the nearest point on the boundary
-            (uncoupled faces only).
-            Per surface point projects the point onto this boundary face
-            (to make sure interpolateCellPoint gets a valid location)
 
-    - since it finds a nearest per triangle each triangle is guaranteed
+    - source=boundaryFaces, interpolate=true:
-    to be on one processor only. So after stitching (by sampledSurfaces)
+        Finds per triangle centre the nearest point on the boundary (uncoupled
-    the original surface should be complete.
+        faces only). Per surface point projects the point onto this boundary
+        face (to make sure interpolateCellPoint gets a valid location)
+
+    Since it finds a nearest per triangle each triangle is guaranteed to be on
+    one processor only. So after stitching (by sampledSurfaces) the original
+    surface should be complete.
+
+    Example:
+    \verbatim
+    {
+        type        triSurfaceMesh;
+        surface     "surface.stl";
+        source      cells;
+        interpolate yes;
+    }
+    \endverbatim
+
+Usage
+    \table
+        Property     | Description             | Required    | Default value
+        surface      | the surface file (within constant/triSurface) | yes |
+        source       | see above               | yes         | no
+        interpolate  | see above               | no          | no
+    \endtable
 
 SourceFiles
     sampledTriSurfaceMesh.C

src/sampling/sampledSurface/thresholdCellFaces/sampledThresholdCellFaces.H

@@ -2,7 +2,7 @@
   =========                 |
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     | Website:  https://openfoam.org
-    \\  /    A nd           | Copyright (C) 2011-2019 OpenFOAM Foundation
+    \\  /    A nd           | Copyright (C) 2011-2020 OpenFOAM Foundation
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
 License
@@ -28,6 +28,28 @@ Description
     A sampledSurface defined by the cell faces corresponding to a threshold
     value.
 
+    Example:
+    \verbatim
+    {
+        type        thresholdCellFaces;
+        field       p;
+        lowerLimit  5;
+        upperLimit  10;
+        interpolate yes;
+    }
+    \endverbatim
+
+Usage
+    \table
+        Property     | Description             | Required    | Default value
+        field        | the field to threshold  | yes         |
+        lowerLimit   | the limit below which cells are omitted \\
+                     | if no upperLimit | -vGreat
+        upperLimit   | the limit above which cells are omitted \\
+                     | if no lowerLimit | +vGreat
+        interpolate  | interpolate values to the surface points | no | no
+    \endtable
+
 SourceFiles
     sampledThresholdCellFaces.C