Scripting

The Scripting functionality allows the user to run a custom set of scripts before and after every Pack operation. Every script can optionally be group-based (using a grouping scheme). In order to use the functionality, enable the checkbox in the Scripting subpanel header and press Allow Script Execution:

The Scripting subpanel provides two lists for defining scripts: scripts to be executed before every Pack operation and scripts to be executed after every Pack operation. In order to add a script to a list, press the Plus (+) button next to the list window:

You can add many scripts to a single list: the packer will execute every script on the list in the order corresponding to the order of the entries in the list. You can enable/disable every script individually using the checkbox to the left of the script name.

The name of the script in a list corresponds to the name of a text in the Blender Text Editor (the editor is available in the Blender Scripting tab). One defines the actual code to execute in the given text, inside the UVPM3_script function:

The UVPM3_script function must always take two arguments: context and group_name (even when the script is not group-based).

Below the list window, one can access the options of the currently selected script in the list:

• Function Name - Python function name in the script to be executed. It is always set to UVPM3_script by default but can be overridden by the user.
• Function Args - comma-separated list of additional arguments which will passed to the script function after two base arguments (context and group_name).
• Use Grouping Scheme - determines whether the script is group-based. The behavior of the packer during a script execution depends significantly on whether a script is group-based or not (read below).

Non group-based script

When a script is not group-based (Use Grouping Scheme is off), the packer simply executes UVPM3_script function from the script text, without affecting the context in any way (the object/geometry is left intact). The None value is passed to the function as the group_name argument.

Because the packer does not change the context when executing a non group-based script, such a script is allowed to modify the current object/geometry selection state. Every such a change will be visible by all scripts executed after the given script and during the operation itself.

Group-based script

When a script is group-based (Use Grouping Scheme is on) the execution logic is more complex. One needs to select a grouping scheme which will be used with the given script (select an existing scheme or create a new one):

When executing the script, first the packer will save the UV selection state in the currently selected objects. Then the packer will perform the following steps for every group defined in the selected grouping scheme:

• deselect all UVs in the currently selected objects,
• select only UVs belonging to the given group,
• execute the UVPM3_script function from the script code, passing the group name in the group_name argument.

After all groups are processed in the manner described above, the packer will restore the UV selection state saved at the very beginning of script execution.

WARNING: due to the fact that the packer works with the selection state during script execution, a group-based script must not change the object selection state. Changing selection will lead to undefined behavior.

Example: group-based UV straightening

The example shows how to configure the packer to straighten a given group of UVs before every Pack operation using a third-party addon (UV Squares or UV Toolkit).

1. Install and enable the UV Squares or UV Toolkit addon in Blender.
2. Go to the Scripting tab in Blender and add a new text in the Text Editor and name it straight:

   

3. Paste the following code into the text:

   import bpy
   
   def UVPM3_script(context, group_name):
       if group_name != 'STR':
           # We only want to perform straightening on UVs belonging to the STR group.
           # Return if the group name is different
           return
       
       # The packer already selected all UVs belonging to the STR group.
       # All we need to do is execute the straightening operator.
   
       # Select the addon which will be used for straightening
       use_uvsquares = True
       use_uvtoolkit = False
   
       if use_uvsquares:
           bpy.ops.uv.uv_squares()
       elif use_uvtoolkit:
           bpy.ops.uv.toolkit_straighten(gridify=False)
       else:
           raise RuntimeError('no addon for straightening selected')

4. In the Scripting subpanel in the Packing multi panel, add new script to the Before Operation list. Set the script to execute to straight (the text name created in the previous step) using the Set menu:

   

5. Enable the Use Grouping Scheme checkbox. Create a new grouping scheme and optionally give it an informative name (e.g. Straightening). Press Edit Scheme In Editor.

   

6. In the Grouping Editor, add a new group to the scheme and name the new group STR - note this exact name is required for the example to work properly.

   

7. Select the STR group in the list, then select all UVs which you want to be straightened before every Pack operation. Then press Assign Islands To The Group. The selected UVs will be added to the STR group.
8. Go back to the Packing multi panel in the UVPackmaster3 tab and press Pack.

You should see that all UVs assigned to the STR group are straightened before every Pack operation.