Add 'Surface Cluster' tool.

This is based on my original "surfaceCluster.py" script from 2014, but
re-written to be more modular and reusable and easier to understand.

This new version has a lot of improvements, such as:
- A tool to update the soft-selection weights for a surface cluster.
- A UI enable/disable opening the paint-weights tool, after creation.
- A tool to open the paint-weights tool for the selected surface cluster
control node.
- The ability to create multiple surface clusters from multiple selected
mesh components.

GitHub issue #111.

docs/source/mmSolver.tools.rst

@@ -65,6 +65,7 @@ mmSolver.tools
    mmSolver.tools.solver
    mmSolver.tools.sortoutlinernodes
    mmSolver.tools.subdivideline
+   mmSolver.tools.surfacecluster
    mmSolver.tools.sysinfowindow
    mmSolver.tools.togglebundlelock
    mmSolver.tools.togglecameradistort

docs/source/mmSolver.tools.surfacecluster.rst

@@ -0,0 +1,42 @@
+=============================
+mmSolver.tools.surfacecluster
+=============================
+
+.. automodule:: mmSolver.tools.surfacecluster
+    :members:
+    :undoc-members:
+
+Tools
++++++
+
+.. automodule:: mmSolver.tools.surfacecluster.tool
+    :members:
+    :undoc-members:
+
+Library
++++++++
+
+.. automodule:: mmSolver.tools.surfacecluster.lib
+    :members:
+    :undoc-members:
+
+UI - Layout
++++++++++++
+
+.. automodule:: mmSolver.tools.surfacecluster.ui.surfacecluster_layout
+    :members:
+    :undoc-members:
+
+UI - Window
++++++++++++
+
+.. automodule:: mmSolver.tools.surfacecluster.ui.surfacecluster_window
+    :members:
+    :undoc-members:
+
+Constants
++++++++++
+
+.. automodule:: mmSolver.tools.surfacecluster.constant
+    :members:
+    :undoc-members:

docs/source/tools_generaltools.rst

@@ -276,6 +276,124 @@ To run the tool, use this Python command:
 .. _rivet.mel:
    https://www.highend3d.com/maya/script/rivet-button-for-maya
 
+.. _create-rivet-tool-ref:
+
+Surface Cluster
+---------------
+
+A Surface Cluster is a "cluster" deformer that will be riveted to the
+surface of a mesh object. All movement of the underlying surface is
+inherited by the Surface Cluster, so the cluster "sits on" the
+surface, even if the underlying surface is animated/deformed.
+
+Surface Clusters can be very helpful for subtly adjusting the
+silhouette of an object, or adding a bulge, especially when the change
+needs to be animated.
+
+.. note:: This old `Surface Cluster YouTube Video`_ shows the general
+          usage of the tool, however the tool has been re-written and
+          improved with features for editing the deforming weights.
+
+.. _Surface Cluster YouTube Video:
+   https://youtu.be/7SFP4TgVbEI
+
+Create Single Surface Cluster
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create a Surface Cluster on the selected Mesh component.
+
+Usage:
+
+1) Select 1 or more components (vertices, edges, faces, etc).
+
+2) Run this tool.
+
+   - create a single surface cluster at the average position of all selected
+     components.
+
+   - (Optionally) Use current Soft Selection as default weighting - the
+     same as the "update_weights_with_soft_selection" tool.
+
+To run the tool, use this Python command:
+
+.. code:: python
+
+    import mmSolver.tools.surfacecluster.tool as tool
+    tool.create_single_surface_cluster()
+
+    # Open the UI window change settings before creation.
+    tool.open_window()
+
+Create Multiple Surface Cluster
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create multiple surface clusters, one for each component selected.
+
+Usage:
+
+1) Select 1 or more components (vertices, edges, faces, etc).
+
+2) Run this tool.
+
+   - For each component, create a surface cluster is created.
+
+To run the tool, use this Python command:
+
+.. code:: python
+
+    import mmSolver.tools.surfacecluster.tool as tool
+    tool.create_multiple_surface_clusters()
+
+    # Open the UI window change settings before creation.
+    tool.open_window()
+
+Update Weights With Soft-Selection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Update the cluster deformer weights using the current component
+soft-selection.
+
+
+Usage:
+1) Enable Soft Selection ('b' hotkey)
+
+2) Select 1 or more components (vertices, edges, faces, etc).
+
+3) Select surface cluster control.
+
+4) Run this tool.
+
+   - The weights of the surface cluster are updated with the soft
+     selection.
+
+To run the tool, use this Python command:
+
+.. code:: python
+
+    import mmSolver.tools.surfacecluster.tool as tool
+    tool.update_weights_with_soft_selection()
+
+Open Surface Cluster Paint Weights
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Open the paint weights tool for the selected surface cluster Control.
+
+Usage:
+1) Select a surface cluster control.
+
+2) Run tool.
+
+   - The paint weights tool is opened.
+
+3) User paints weights.
+
+To run the tool, use this Python command:
+
+.. code:: python
+
+    import mmSolver.tools.surfacecluster.tool as tool
+    tool.open_paint_weights_tool()
+
 .. _marker-bundle-rename-tool-ref:
 
 Marker Bundle Rename

python/CMakeLists.txt

@@ -189,6 +189,11 @@ if (MMSOLVER_BUILD_QT_UI)
             ${CMAKE_CURRENT_BINARY_DIR}/mmSolver/tools/screenspacerigbake/ui/ui_screenspacerigbake_layout.py
             )
 
+    compile_qt_ui_to_python_file("surfacecluster"
+            ${CMAKE_CURRENT_SOURCE_DIR}/mmSolver/tools/surfacecluster/ui/surfacecluster_layout.ui
+            ${CMAKE_CURRENT_BINARY_DIR}/mmSolver/tools/surfacecluster/ui/ui_surfacecluster_layout.py
+            )
+
     # Install generated Python UI files
     install(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/"
             DESTINATION "${MODULE_FULL_NAME}/python"

python/mmSolver/tools/surfacecluster/constant.py

@@ -0,0 +1,42 @@
+# Copyright (C) 2023 David Cattermole.
+#
+# This file is part of mmSolver.
+#
+# mmSolver is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Lesser General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# mmSolver is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with mmSolver.  If not, see <https://www.gnu.org/licenses/>.
+#
+"""
+Surface Cluster constants.
+"""
+
+WINDOW_TITLE = 'Create Surface Cluster'
+
+CONFIG_CREATE_MODE_KEY = 'mmSolver_surfacecluster_createMode'
+CONFIG_OPEN_PAINT_WEIGHTS_KEY = 'mmSolver_surfacecluster_openPaintWeights'
+
+CREATE_MODE_SINGLE_VALUE = 'single_surface_cluster'
+CREATE_MODE_MULTIPLE_VALUE = 'multiple_surface_cluster'
+CREATE_MODE_VALUES = [
+    CREATE_MODE_SINGLE_VALUE,
+    CREATE_MODE_MULTIPLE_VALUE,
+]
+
+CREATE_MODE_SINGLE_LABEL = 'Create Single Cluster On Components'
+CREATE_MODE_MULTIPLE_LABEL = 'Create Multiple Clusters On Each Component'
+CREATE_MODE_LABELS = [
+    CREATE_MODE_SINGLE_LABEL,
+    CREATE_MODE_MULTIPLE_LABEL,
+]
+
+DEFAULT_CREATE_MODE = CREATE_MODE_SINGLE_VALUE
+DEFAULT_OPEN_PAINT_WEIGHTS = True