Scripts and Commands - Mesh Match for Maya

The MeshMatch plugin is composed of several key components, including Python scripts for the user interface and core C++ commands for backend operations and licensing.

Plugin Python Scripts

The plugin’s user interface and supporting Python logic are organized into the following modules:

mesh_match_ui.py Houses the main UI components that form the plugin window.
mesh_match_main_widget.py The main widget displayed for each MeshMatch node selected in the scene, providing the primary interface for node interaction.
mesh_match_pins_widgets.py Contains widgets dedicated to managing pin pairs and the selection view for these pin pairs.
mesh_match_custom_widgets.py Implements subclasses of Qt widgets, providing custom behavior, styling, and enhanced functionality tailored for the plugin.
mesh_match_matrix_widgets.py Includes widgets specifically designed for managing and interpolating transformation matrices within the plugin.
mesh_match_constants.py Defines a set of string constants and other fixed values used consistently across the various Python modules, aiding in maintainability and consistency.
mesh_match_utils.py Offers various utility functions and helper classes that support the operations of other Python modules within the plugin.
qt_import.py Manages the Qt bindings import to ensure compatibility across different Maya versions, supporting both PySide2 (e.g., Maya 2023 and earlier compatible versions) and PySide6 (e.g., Maya 2024 and newer).
mesh_match_commands.py Provides a Python API with functions that wrap the core functionalities of MeshMatch nodes. This module allows for scripting interactions such as node creation, deletion, querying data, managing landmarks, and matrix operations, independently of the main plugin UI. It is distinct from the C++ based Core Plugin Commands described below.

Core Plugin Commands (Accessible via MEL/Python)

These are C++ based commands registered by the plugin that can be executed directly in Maya using MEL or Python (maya.cmds). They handle core functionalities, including data retrieval and licensing.

General:

meshMatchGetSymDict <nodeName>
- Purpose: Retrieves symmetry data for a specified MeshMatch node. This includes vertex IDs categorized as positive, negative, center, or unsymmetrical for both the reference and target meshes associated with the node.
- Arguments:
  - <nodeName> (string): The name of the MeshMatch node you want to query.
- Returns (MEL/Python): A string formatted as a Python dictionary.
  - Example Structure: "{'ref': {'pos': [id1, id2,...], 'neg': [...], 'center': [...], 'unsym': [...]}, 'tgt': {'pos': [...], 'neg': [...], 'center': [...], 'unsym': [...]}}"
- License Behavior: Requires a valid MeshMatch license to execute successfully. If the license is not valid, the command will fail and display an error.

meshMatchDetectLandmarks -mn <meshName> -pn <panelName> [-mt <modelType>] [-li <landmarkIndices>] [-sd <saveDebugImage>]
- Purpose: Performs automatic landmarks detection from viewport using AI models on faces (bodies and hands soon integrated).
- Arguments:
  - <meshName> (string): The name of the mesh transform to be captured.
  - <panelName> (string): The name of the modelPanel used for capturing the mesh.
  - <landmarksIndices> (string): A list of indices (separated with comma) to fetch from the selected model. If empty, all indices will be used
  - <modelType> (string): The type of model used for detection (ie ‘face’).
  - <saveDebugImage> (bool): When set to True, the image captured from the model with the detected points will be saved in the user tmp directory.
- Returns (MEL/Python): A JSON formatted dict containing comprehensive capture results.
  The dictionnary main keys are the indices provided as argument. For each index a result dict contains :
  - vtxId: The closest vertex of the mesh found next to the captured point
  - worldPos: The world position of the captured point.
  - viewPos: The 2d coordinate of the captured point in the model panel.
- License Behavior: Requires a valid MeshMatch license to execute successfully. If the license is not valid, the command will fail and display an error.

Licensing:

meshMatchActivateLicense <licenseKey> [-offline <boolean>]
- Purpose: Activates the MeshMatch plugin license using the provided license key. If no internet connection or if you need to use a pre-generated offline token, use the -offline flag to run the offline activation flow.
- Syntax:
  - `meshMatchActivateLicense <licenseKey>` – Attempts online activation (requires internet).
  - `meshMatchActivateLicense -offline true` – Launches offline activation workflow instead (no <licenseKey> is required here).
- Arguments:
  - <licenseKey> (string): The license key to activate. Required unless -offline is set.
  - -offline <boolean>: If true, run a guided offline activation (skips the online server call).
- Returns (MEL/Python):
  - Boolean
    - true → command syntax was valid and activation flow was dispatched.
    - false → missing or invalid arguments (e.g. no <licenseKey> given in online mode).
- Notes:
  - A return value of true does not guarantee the license is valid—any rejection (invalid key, server error, etc.) is shown by UI dialogs.
  - Online activation requires an internet connection. Offline activation does not.

meshMatchDeactivateLicense
- Purpose: Deactivates the current MeshMatch license instance online so that the slot can be used elsewhere.
- Syntax:
  - `meshMatchDeactivateLicense`
- Arguments:
  - None.
- Returns (MEL/Python):
  - Boolean
    - true → after running, no valid license remains in memory (deactivation succeeded or was already none).
    - false → the license is still valid (e.g. user canceled or deactivation error).
- Details:
  - Requires an internet connection for server-side deactivation.
  - On Windows: deletion of local credentials happens automatically if online deactivation succeeds.
  - On Linux: after online deactivation, a dialog instructs the user to run sudo rm <license_file> to remove the local file.

meshMatchGetInstanceName
- Purpose: Generates and returns a unique machine identifier (instanceName) for offline activation.
- Syntax:
  - `meshMatchGetInstanceName`
- Arguments:
  - None.
- Returns (MEL/Python):
  - String
    - The generated instance identifier (e.g. MeshMatch_MyComputer_User).
- Notes:
  - Always available (no license needed, no internet required).
  - Also prints the identifier to the script editor for easy copying.

meshMatchRefreshLicenseInfo
- Purpose: Forces an online sync with the licensing server to update local license status (e.g., if you’ve just renewed).
- Syntax:
  - `meshMatchRefreshLicenseInfo`
- Arguments:
  - None.
- Returns (MEL/Python):
  - Boolean
    - true → online sync succeeded; local license (and expiration) updated.
    - false → sync failed (e.g. no stored license to refresh, no internet). A failure does not invalidate a working offline license.
- Notes:
  - Requires internet, but will not disable a working offline license on failure—just pops up an error dialog.

meshMatchGetLicenseInfo
- Purpose: Retrieves the current in-memory license state as a JSON string.
- Syntax:
  - `meshMatchGetLicenseInfo`
- Arguments:
  - None.
- Returns (MEL/Python):
  - JSON string with keys:
    - mode : “Production” or “Developer”
    - isValid : true/false
    - statusMessage : human-readable multi-line summary (“Mode: …\nStatus: …\n…”)
    - detailedStatus : (internal status text)
    - licenseKeyMasked : masked key (e.g. “XXXX-XXXX-…-1234”) or “N/A”
    - instanceId : current instance ID if any, else “N/A”
    - expirationDate : expiry date (YYYY-MM-DD or “Perpetual”) or “N/A”
    - machineIdStored : (Linux only) stored machine ID or “N/A”
- Notes:
  - Does NOT perform any online calls; simply serializes whatever is already in memory.
  - You can call this at any time to inspect current license state.

Note: For the UI, licensing commands are wrapped within the loadPluginAndValidateLicense() function from the mesh_match_commands.py file.