poisson_disk documentation

docs/pages/docs/commands/createpts.md

@@ -16,6 +16,10 @@ This command adds points to a mesh object. For some special cases, it will also
 
 **[createpts/interp](createpts/createpts_interp.md)** Creates points by linear interpolation between two point sets.
 
+
+**[createpts/poisson_disk](createpts/createpts_poisson.md)** Create uniform or variable spaced vertices inside a pllygon using Poisson Disk sampling.
+
+
 **[createpts/sphere](createpts/cresphere.md)** Create points for a sphere.
 
 **[createpts/random](createpts/CRTPTRZRAN.md)** Add random points within region.

docs/pages/docs/commands/createpts/createpts_poisson.md

@@ -0,0 +1,191 @@
+---
+title: CREATEPTS/POISSON_DISK
+tags: createpts poisson_disk
+---
+
+# CREATEPTS/POISSON_DISK 
+
+-------
+
+Create a uniform or variable spaced points on/in a 2D planar polygon (convex or nonconvex) using Poisson Disk sampling. Optionally connect the vertices using Delaunay triangulation.
+
+
+The 3D option for poisson_disk is under development and will be available in a future release.
+
+
+## SYNTAX
+
+<pre>
+<b>createpts</b> /<b>poisson_disk</b> / [<b>2d_polygon</b> | <b>3d_box</b>] / mo_out / mo_polygon / h_spacing_scalar / [<b>connect</b> | <b>no_connect</b>] / [user_resolution.mlgi] / [ poisson_seed integer ] [ number_of_samples integer ] [ resample_sweeps integer ]
+
+</pre>
+
+### Argument 3 Geometry Options
+
+**`2d_polygon`** character type indicating geometry for a 2D planar polygon, convex or nonconvex, in the XY plane. If the polygon you wish to distribute points in is not in XY plane, user must rotate it into XY plane.If the polygon is nonconvex, the algorithm may alter some small features depending on the details of the polygon and the user controlled input parameters. See examples below.
+
+**`3d_box`** character type indicating geometry for 3D orthogonal box defined by (x,y,z) minimum and (x,y,z) maximum. (Under Development) 
+
+### Argument 4 and 5 Mesh Object Names
+
+
+`mo_out` name of output mesh object.  This user defined mesh object will contain the vertex distribution or triangulation created by the poisson_disk algorithm.
+
+
+`mo_polygon` name of input mesh object that contains a 2D planar polygon in the XY plane.
+
+### Argument 6 Spacing
+
+`h_spacing_scalar` of type real. In the case of uniform resolution, this user provided real number defines the target spacing between vertices created by the Poisson-Disk algorithm. If the mesh is connected, the triangle edges will be approximately equal to `h_spacing_scalar`. In the case of variable resolution, `h_spacing_scalar` is used as a multiplier in the function defined in `user_resolution.mlgi`.
+
+### Argument 7 Output Options
+
+**`connect`**  will connect the vertices generated by Poisson disk algorithm connected. The output mesh object `mo_out`  will be a Delaunay triangulation.
+
+
+**`no_connect`** the output mesh object  `mo_out` will contain the  vertices generated by Poisson disk algorithm  without triangle connectivity.
+
+
+### Optional Resolution Arguments 
+
+Default if this option is not used, the mesh will be uniform resolution defined by Argument 6 `h_spacing_scalar`.
+
+`user_resolution.mlgi` is the name of a LaGriT control file for user defined  resolution.
+The control file  defines a function h(x,y) that will be used to control vertex spacing in a variable resolution mesh. See examples below. 
+
+When the variable  option is utilized, internal to the module a mesh object, ** mo_poi_h_field**, with a real scalar attribute, **h_field_att**, is created. By default for uniform resolution, **h_field_att**, is set to a constant value of `h_spacing_scalar`, however, when this option is exercised, the user must fill *h_field_att* with their own scalar field h(x,y). In addition, internal to the code the command:
+```define / POI_H_FACTOR / h_spacing_scalar```
+so one can access the value of `h_spacing_scalar` by using the variable **POI_H_FACTOR** in the LaGriT control file `user_resolution.mlgi` for setting variable resolution.
+
+### Advanced Options 
+
+There are three optional parameters that are for advanced users only. They are keyword driven and can come in any order beginning as token 8 or 9. The user can specify none, one, two, or all three keyword driven parameters.
+
+
+**`poisson_seed`*** (integer default 1)  is the seed for the random number generator. If once runs this module with the same input, by default each run will give the same result. However, if the user would like to produce multiple realizations with the same input (same input polygon, same resolution, etc.) but a different output mesh, then the user can change the value of poisson_seed for each realization.
+
+
+**`number_of_samples`** (integer default:10) Number of new candidate points that are sampled around an accepted node. Lower values reduce overall sampling time, but can lead to holes in the final point distribution. Higher value lead to better density and converge but takes more time. 
+
+
+**`resample_sweeps`** (integer default:1) Number of additional sampling attempts in the domain. If there exists holes in the point distribution, increasing this value should fill in these holes.
+
+It is suggested that the user should have the minimum value of h(x,y)= `h_spacing_scalar`, and then vary resolution by setting values greater than `h_spacing_scalar`. If one intends to have high resolution near objects and features and lower resolution away from the objects, then use of the compute/distance_field is a good way to define h(x,y). 
+
+#### Advanced Option Examples
+
+<pre>
+createpts / poisson_disk / 2d_polygon / mo_poisson_pts / mo_polygon &
+      / 0.01 / connect / user_h_field_att.mlgi &
+      poisson_seed 3 / resample_sweeps 4 / number_of_samples 20
+
+createpts / poisson_disk / 2d_polygon / mo_poisson_pts / mo_polygon &
+      / 0.01 / connect / user_h_field_att.mlgi &
+      poisson_seed 3
+
+createpts / poisson_disk / 2d_polygon / mo_poisson_pts / mo_polygon &
+      / 0.01 / connect / poisson_seed 3
+</pre>
+
+<hr>
+
+## EXAMPLES for Uniform and User Defined Resolutions
+
+**Polygon input file: polygon_unit_square.poly**
+```
+4 0 0 0 0 
+1 -0.5 -0.5 0
+2  0.5 -0.5 0
+3  0.5  0.5 0
+4 -0.5  0.5 0
+```
+
+**LaGriT control file**
+```
+#
+# Mesh a unit square with uniform and variable resolution tringles.
+#
+# Read polygon from a file.
+#
+read / avs / unit_square.poly / mo_polygon
+#
+# Uniform resolution, unit square polygon, vertex spacing 0.05:
+#
+
+createpts / poisson_disk / 2d_polygon / mo_poisson_pts / mo_polygon &
+      / 0.05 / connect
+
+dump / avs / output01_unit_square_uniform.inp / mo_poisson_pts
+cmo / delete / mo_poisson_pts
+#
+# Variable resolution, unit square polygon, vertex spacing 0.01:
+#
+# WIDTH_FACTOR is used in user_h_field_att.mlgi
+#
+
+define / WIDTH_FACTOR / 10.0
+createpts / poisson_disk / 2d_polygon / mo_poisson_pts / mo_polygon &
+      / 0.01 / connect / user_h_field_att.mlgi
+
+dump / avs / output02_unit_square_var.inp / mo_poisson_pts
+cmo / delete / mo_poisson_pts
+
+define / WIDTH_FACTOR / 20.0
+createpts / poisson_disk / 2d_polygon / mo_poisson_pts / mo_polygon &
+      / 0.01 / connect / user_h_field_att.mlgi
+
+dump / avs / output03_unit_square_var.inp / mo_poisson_pts
+cmo / delete / mo_poisson_pts
+
+finish
+```
+
+**Variable resolution defined in LaGriT control file:  user_h_field_att.mlgi**
+
+Used in the example above, the resolution is set using the X coordinate (xic), the user defined POI_H_FACTOR = h_spacing_scalar = 0.01, and a floor function to ensure no values are below h_spacing_scalar.
+
+```
+#####################################################
+# User defined h field function assignment
+#####################################################
+#
+# h_field_att is already set to POI_H_FACTOR
+#
+define / MO_H_FIELD / mo_poi_h_field
+#
+# x**2
+math / power / MO_H_FIELD / h_field_att / 1,0,0 / &
+               MO_H_FIELD / xic / 2.0
+cmo/printatt/MO_H_FIELD/h_field_att/minmax
+# sqrt(x**2)
+math / power / MO_H_FIELD / h_field_att / 1,0,0 / &
+               MO_H_FIELD / h_field_att / 0.5
+cmo / printatt/MO_H_FIELD/h_field_att/minmax
+# POI_H_FACTOR*sqrt(x**2)
+math/multiply/MO_H_FIELD/h_field_att/1,0,0/ &
+              MO_H_FIELD/h_field_att/ POI_H_FACTOR
+math/multiply/MO_H_FIELD/h_field_att/1,0,0/ &
+              MO_H_FIELD/h_field_att/ WIDTH_FACTOR
+cmo / printatt/MO_H_FIELD/h_field_att/minmax
+math / floor / MO_H_FIELD/h_field_att/1,0,0/ &
+               MO_H_FIELD/h_field_att/POI_H_FACTOR
+cmo/printatt/MO_H_FIELD/h_field_att/minmax
+cmo / status / brief
+#
+# As a diagnostic one can output MO_H_FIELD and view
+# the h(x,y) attribute that will be used to set resolution.
+#
+dump / avs / h_field_out.inp / MO_H_FIELD
+#
+finish
+
+```
+
+
+
+
+
+
+
+
+