Documentation for AdaptivePolygons mk2.

b625a606 · Ilya Portnov · fbaab83b · b625a606 · b625a606 · b625a606
--- a/docs/nodes/modifier_make/adaptive_polygons_mk2.rst
+++ b/docs/nodes/modifier_make/adaptive_polygons_mk2.rst
+Adaptive Polygons Mk2
+=====================
+Functionality
+-------------
+This node puts a (transformed) copy of one object, called **donor**, along each
+face of another object, called **recipient**. Copies of donor objects are
+deformed (adapted) to match the shape and normals of recipient's face.
+This node works primarily with Quads and Tris; if you ask it to work with NGons
+(N > 4), it can produce weird resuls.
+One can pass recipient object through **Inset Special** node to achieve results
+similar to Tissue's "Fan" or "Frame" modes.
+In many cases it is good idea to pass the output of this node through **Remove
+Doubles** node.
+This node is based on original code taken with permission from
+https://sketchesofcode.wordpress.com/2013/11/11/ by Alessandro Zomparelli
+(sketchesofcode). Further features were developed after the Tissue addon by
+Alessandro.
+Inputs
+------
+This node has the following inputs:
+- **VersR**. Vertices of the recipient object. This input is mandatory.
+- **PolsR**. Faces of the recipient object. Please have in mind that order of
+  indices in each face affect donor object rotation; for example, `[0, 1, 2,
+  3]` is one rotation, `[3, 0, 1, 2]` is the same turned by 90 degrees. This
+  input is mandatory. 
+- **VersD**. Vertices of the donor object. This input is mandatory.
+- **PolsD**. Faces of the donor object.
+- **Width coeff**. Coefficient for donor object width (size along X,Y axis,
+  usually). Default value is 1.0. The input expects one number per each
+  recipient object face.
+- **Z coeff**. Coefficient for donor object size along recipient object face
+  normal. Exact meaning depends on **Z Scale** parameter (see below). The
+  default value is 1.0. The input expects one number per each recipient object face.
+- **Z offset**. Offset of donor objects along the normal of recipient object
+  face. Default value is 0.0. The input expects one number per each recipient
+  object face.
+- **Z Rotation**. Rotation of donor objects along the normal of recipient
+  object face, in radians. Default value is 0.0. The input expects one number
+  per each recipient object face.
+- **PolyMask**. Mask for recipient object faces processing. What exactly will
+  be done with faces which are masked out is defined by **Mask Mode** parameter
+  (see below).
+Parameters
+----------
+This node has some number of parameters, and most of them are accessible only in the N panel:
+- **Join**. If checked, then all procuced copies of donor object will be merged
+  into one mesh. Unchecked by default.
+- **Normal axis**. Axis of the donor object to be aligned with recipient object
+  face normal. Available values are X, Y, and Z. Default value is Z.
+- **Z Scale**. This defines how donor object size along recipient face normal
+  is calculated. Available values are:
+  - **Proportional**. Donor object size along recipient face normal is
+    calculated by it's size along Z axis (or other one, defined by **Normal
+    axis** parameter) multiplyed by value from **Z coeff** input.
+  - **Constant**. Donor object size along recipient face normal is taken from
+    **Z Coeff** input.
+  The default value is **Proportional**.
+- **Use normals**. This defines how recipient object normals will be used to
+  transform the donor objects. Available values are:
+  - **Map**. Interpolation between recipient object's vertex normals will be
+    used to deform the donor object. While this procuces smoother results, this
+    gives more deformation of donor object.
+  - **Face**. Recipient object's face normal will be used to orient the donor
+    object. While this gives less deformation of donor object, it can give gaps
+    between copies.
+  The default value is **Map**.
+- **Interpolate normals**. This parameter is available only if **Use normals**
+  is set to **Map**. This defines the method of interpolation between recipient
+  object's vertex normals. Available values are:
+  - **Linear**. Linear interpolation will be used.
+  - **Unit length**. Linear interpolation will be used, but the resulting
+    normal will be resized to length of 1.0. This can give more smooth results
+    in some cases.
+  The default value is **Linear**.
+- **Coordinates**. This defines the method of calculation of donor object's
+  coordinates along two axes orthogonal to recipient's face normal. In any
+  case, the location is defined by transforming some area of XOY plane (or
+  other plane, according to **Normal axis** paramter), called *source area*, to
+  the recipient object face. The question is what is the source area. The
+  available values are:
+  - **Bounds**. The source area is defined as follows:
+    - For Quad recipient object faces, the bounding rectangle of donor object is taken.
+    - For Tris recipient object faces, the bounding triangle of donor object is
+      taken. The "bounding triangle" is defined as the smallest triangle with
+      equal sides, which covers all donor vertices while having bottom side
+      parallel to X axis (or other axis according to **Normal axis** parameter).
+  - **As Is**. The source area is defined as follows:
+    - For Quad faces, the `[-1/2; 1/2] x [-1/2; 1/2]` unit square is taken.
+    - For Tris faces, the unit triangle is taken, i.e. the triangle with all
+      sides equal to 1 with center at (0,0,0).
+  Note that by definition of **Bounds** mode, the donor object always lies
+  within the *source area*.
+  The **As Is** mode allows one to manually transform the donor object before
+  passing it to this node; interesting results may be achieved by making the
+  donor object smaller than *source area**, or bigger than it, or even outside
+  of it.
+- **Faces mode**. This defines how deformations of donor object will be
+  calculated for Quad and Tris recipient faces. Available values are:
+  - **Quads / Tris Auto**. For Quad faces, the linear transformation will be
+    used. For Tris faces, the barycentric transformation will be used to
+    transform source triangle into the recipient triangle. This method gives
+    good and smooth results for both Quads and Tris.
+  - **Quads Always**. In this mode, Tris faces are processed as if they were
+    (degenerated) Quads with third and fourth vertices coinciding. Such
+    transformation can make one corner of donor object sharper than others, and
+    in some cases produce weird results for Tris. But such results can be
+    interesting in some cases. Note that at the moment the Tissue addon always
+    uses this mode.
+  The default value is **Quads / Tris Auto**.
+- **Mask mode**. This defines what to do with recipient objectfaces excluded by the
+  **PolyMask** input. Available values are:
+  - **Skip**. Such faces will be skipped completely, i.e. will not produce any
+    vertices and faces.
+  - **As Is**. Such faces will be output as they were, i.e. one face will be
+    output for each recipient face.
+  The default value is **Skip**.
+- **NGons**. This defines what to do with NGon recipient object faces (i.e.
+  faces with number of vertices more than 4). Available values are:
+  - **As Quads**. Such faces will be processed as if they were quads; only
+    first three and the last vertex of the NGon will be used to form a Quad.
+    This can give weird results for such faces. 
+  - **Skip**. Such faces will be skipped completely, i.e. will not produce any
+    vertices and faces.
+  - **As Is**. Such faces will be output as they were, i.e. one face will be
+    output for each recipient face.
+  The default value is **As Quads**.
+Outputs
+-------
+This node hsa the following outputs:
+- **Vertices**
+- **Polygons**
+The outputs will contain one object, if **Join** flag is checked, or one object
+per recipient object face, otherwise.
+Examples of usage
+-----------------
+Example of **Z coeff** input usage:
+.. image:: https://user-images.githubusercontent.com/284644/68081971-5473a700-fe38-11e9-8f8a-dbd204bafadd.png
+Demonstration of how this node works with Tris recipient faces by default (in **Quads / Tris Auto** mode):
+.. image:: https://user-images.githubusercontent.com/284644/68081972-5473a700-fe38-11e9-8604-018e7b59996d.png
+The same setup but with **Faces mode** set to **Quads Always**:
+.. image:: https://user-images.githubusercontent.com/284644/68081973-5473a700-fe38-11e9-89f6-8e4b4330772a.png
+In some cases iterative application can give interesting results:
+.. image:: https://user-images.githubusercontent.com/284644/68075234-ee027080-fdc6-11e9-8192-61d0917d45f7.png
+You can also find some more examples `in the development thread <https://github.com/nortikin/sverchok/pull/2651>`_.
--- a/docs/nodes/modifier_make/modifier_make_index.rst
+++ b/docs/nodes/modifier_make/modifier_make_index.rst
@@ -12,6 +12,7 @@ Modifier Make
   matrix_tube
   pipe_tubes
   polygons_adaptative
+   adaptive_polygons_mk2
   solidify
   uv_connect
   voronoi_2d

--- a/nodes/modifier_make/adaptive_polygons_mk2.py
+++ b/nodes/modifier_make/adaptive_polygons_mk2.py
@@ -42,6 +42,10 @@ sqrt_3_3 = sqrt_3/3
 sqrt_3_2 = sqrt_3/2
 class SvAdaptivePolygonsNodeMk2(bpy.types.Node, SverchCustomTreeNode):
+    """
+    Triggers: Adaptive Polygons Tessellate Tissue
+    Tooltip: Generate an adapted copy of donor object along each face of recipient object.
+    """
    bl_idname = 'SvAdaptivePolygonsNodeMk2'
    bl_label = 'Adaptive Polygons Mk2'
    bl_icon = 'OUTLINER_OB_EMPTY'
@@ -501,7 +505,7 @@ class SvAdaptivePolygonsNodeMk2(bpy.types.Node, SverchCustomTreeNode):
        verts_donor_s = self.inputs['VersR'].sv_get()
        faces_donor_s = self.inputs['PolsR'].sv_get()
        verts_recpt_s = self.inputs['VersD'].sv_get()
-        faces_recpt_s = self.inputs['PolsD'].sv_get()
+        faces_recpt_s = self.inputs['PolsD'].sv_get(default=[[]])
        zcoefs_s = self.inputs['Z_Coef'].sv_get()
        zoffsets_s = self.inputs['Z_Offset'].sv_get()
        zrotations_s = self.inputs['Z_Rotation'].sv_get()