Mari Extension Pack Python API |
General information:
The following subclasses of the mari.ExtensionPack() class have been exposed.
Some classes contain subclasses such as "__epGUI__" for UI Calls and "__epSystem__" for less useful system calls
Use your Browsers built in search (F3) to search through this document.
Base Class & Alias:
The base class is mari.ExtensionPack(). An alias is defined as mari.ep()so
mari.ep.nodegraphSelection.deselectAllNodes()
is the same as ..
mari.ExtensionPack.nodegraphSelection.deselectAllNodes()
Offline Version:
You can find an offline version of this help inside Mari under the Python/Documentation Submenu
Available Change Tags:
|
|
"Introduced" and "Modified" Tags
|
•EP6R1, EP6R1v2
•EP6R2, EP6R2v2
•EPRR3
|
Classes |
mari.ExtensionPack.appstyle()
Mari UI Style related methodsgetApplicationStyleSheet(custom_theme=None, prefix_with_qdialog=True)
Convenience method to get the currently set Application Stylesheet.
By default it checks the currently active theme in Mari's Preferences / Misc Tab / Style.
So even though usually a theme change requires a Mari Restart, using this method you
already get the full application stylesheet that will be applied after the Mari restart.
You can use this to rapid test your dialogs during development with different styles.
If you provide the custom_theme argument you can also test different styles without having to switch them
via Mari's Preferences. E.g. custom_theme="Mari Default" will show you the vanilla style sheet,
"Extension Pack Steel" will show you the EP Steel Theme etc.
custom_theme (str or None): Optional. Defaults to None. A Theme to get the stylesheet for.
prefix_with_qdialog (bool): Optional. Defaults to True. If True, prefixes all Q... widget selectors with
"QDialog " so when applied to your Dialog, it takes precedence over the
application stylesheet
(str): A CSS Stylesheet
ValueError: Raises a Value Error if the specified color name doesn't exist in the Appearance.conf filegetCurrentTheme()
Method to figure out what UI theme is currently active in Mari.
This is done by checking the existence of the DefaultStyleSheet.qss in the Mari User Settings.
Valid returns are:
- Mari Default
- Extension Pack Steel
- Extension Pack Steel (Desaturated)
Themes can be switched in Mari's Preferences Misc Tab.
(string): A string description of the theme that is currently active.getWidgetColorDefinition(color_name, fallback_color_name=None)
Returns a Widget Color defined in the Mari "Appearance.conf" file which can be either
found in the Mari User Settings ..
- C:/Users/../.mari/TheFoundry
or in the Mari Install Directory.
- C:/Program Files/Mari../Bundle/Media/Settings
color_name (str): A valid Widget Color name found in the Appearance.conf file
fallback_color_name (str): Optional. A second Color Name to look for if the first one doesn't exist.
You can also specify a rgba() or hex (#) color directly
(str): A color string like rgba(255,255,255,255)
ValueError: Raises a Value Error if the specified color name doesn't exist in the Appearance.conf filethemeBasedOnDefault()
Returns True or False depending on if the current theme is based on Mari's Default stylesheet (True)
or Extension Pack's Custom Stylesheets (False)
As Users can configure their own stylesheet via the Preferences, it is sometimes important to know
what the original theme was that was modified (e.g. to se widget sizes)
(bool): True if the current theme is or is based on Mari's Default stylesheet.applicationStyleEditor()
Launches a dialog to customize the Mari AppearancecreateMariStylePreference()
Adds Mari Style (brightness) Settings to the PreferencespauseThemeTriggers(state)
Pauses or unpauses any Dialog Triggering (e.g. the Style Editor)
when the UI Theme Preference is changedsaveMariStylePreference(preview=False)
Saves the Mari Style (brightness) settings in the PreferencesupdateThemePreference()
Updates the Mari Theme settings in the Preferencesmari.ExtensionPack.archive()
project archiving related toolsarchiveCurrentProject(path)
Archives the current project WHILE the project is open.
path (string): the target path (e.g. c:/temp/archive.mra)archiveUpToDate(cur_project, outOfDate=False)
Sets the ArchiveUpToDate Metadata on a Project
cur_project (mari.project): a mari.Project
outOfDate (bool): Sets the 'Out of Date' Metadata to True of FalsemarkProjectAsArchived(UUID)
Adds information about Archive Status and Archive Date to the Project Tooltip
and marks the Project Screenshot with a visual indicator
UUID (string): The UUID of the project to processmari.ExtensionPack.autosave()
Autosave related methodsautosavePaused()
Returns True if autosave has been Paused, False otherwise
(bool): True if autosave has been Paused, False otherwisesetPauseAutosave(state)
Pauses or unpauses autosave
state (bool): True if autosave should be paused, False if it should be unpausedmari.ExtensionPack.bake()
Baking related methodsrefreshModoBakePresetsList()
refreshes the QComboBox inside the Modo Bake Palette
to reload Modo Bake Presets from all available locations
including locations set by the Environment Variable
MARI_MODO_BAKE_PRESETSSubstanceAutomationBakeBridgeUI()
launch the Substance Baker Bridge UIaddBakePresetsDefaultPaths()
Appends the Mari Extension Pack Modo Bake Presets
location to the MARI_MODO_BAKE_PRESETS Environment
variable path.addSubstanceBakerPreference()
Adds a Preference to the Mari 7 Preferences in the Bakery Tab, allowing you to hide
the Substance Baker Bridge Icon from the UIresetTemporaryPreferences()
When the Substance baker Bridge runs low on GPU Memory, we attempt
to free up memory by reducing Mari settings temporarily, while
the Baker Bridge Dialog is open.
After the Baker Bridge closes, the preferences are reset to their original values.
In order to account for any Mari crashes, we store the preferences
in a temporary file. Whenever Mari opens we check if the temporary file
still exists, indicating Extension pack wasn't able to reapply the settings
(e.g. the Baker Bridge or Mari crashed) and in this case we reapply them.saveSubstanceBakerPreference()
Saves a Preference from the Mari 7 Preferences/ Bakery Tab, allowing you to hide
the Substance Baker Bridge Icon from the UImari.ExtensionPack.bakePoints()
Bake Point related methodsbakeAcrossGeoVersions(node=None)
Baking of Bake Points or Multi Channel Bake Points across geo versions
node (mari.MultiChannelBakePoint | mari.BakePointNode): Optional. A node to bake. Otherwise selectionbakeSelectedBakePoints()
Bakes all selected Bake Points in the NodegraphoptimizeMultiChannelBakePointStreams(node=None)
Checks the given multi channel bake point node's downstream connections (spanning
nodegraphs e.g. also works inside groups) for channel nodes.
Any stream with a connected channel node will be enabled, any stream without disabled.
Mari does this usually automatically when you create a new MCBP and attach it to a
network however this function allows you to trigger it manually.
node (mari.MultiChannelBakePoint): Optional. The Node to optimize.
If None (default), the current Node
selection will be usedremoveAllBakes()
Removes all Bake Point Bakes from your ProjectsmartBakeAndUpdateAcrossGeoVersions()
Baking of all out of date or unbaked Bake Points or Multi Channel Bake Points across geo versions,
in a hierarchical mannersmartBakeHierarchy()
From the currently selected node upstream, refresh all bake points that are empty or out of date including in groupsuseBake(bool)
This method is deprecated and will be removed in the future
`
Sets the "use Bake" checkbox in selected bake points to on or off
bool (bool): True/Falsemari.ExtensionPack.benchmark()
Performance Optimization and Test MethodscreateTimer()
Creates a timer object that can be used to time operations.
Use as follows:
timer = createTimer()
timer.start()
print(timer.end())
timerObject: a class for controlling a timer
------------------------------------------------------------------------------------------
timer.start(): starts a timer
timer.end(): completes the previously started timer.
Returns a tuple (convertedTime,timeInSeconds)
------------------------------------------------------------------------------------------getAverageFPS(wedgeCount=100000, ID=None)
Samples the average Viewport FPS.
The average is defined by the number of wedges
wedgeCount (int): The number of iterations to run.
Defaults to 100000
ident (string): Optional Identifier to store the FPS Count under.
Extension Pack uses this option to associate measured FPS
to preference combinations
(float): Returns the average FPS on the canvasgpuMemoryUsage(subtract_mari_usage=True)
Returns the total and free GPU memory.
On Windows the free GPU Memory is the currently free memory, on linux
if "subtract_mari_usage" argument is True, Mari's own memory usage is re-added to the free memory.
This does not work on Windows.
subtract_mari_usage (bool): LINUX ONLY. Factors out Mari's own Memory Usage in the returned free Memory
(list): [Total Memory in MB, Free Memory in MB]ramMemoryUsage()
Returns the total and free RAM memory.
(list): [Total Memory in MB, Free Memory in MB]mari.ExtensionPack.brush()
Brush related methodsgetDynamicBrushSize(tool=None)
Gets the set dynamic brushsize for a given tool to a state (on/off)
If no tool argument is given, the current tool is used.
tool (mari.Tool): The Tool object e.g. mari.tools.currentTool()
If no tool is given, the current tool is used.setDynamicBrushSize(state, tool=None)
Sets the dynamic brushsize for a given tool to a state (on/off)
If no tool argument is given, the current tool is used.
state (bool): True or False to de/activate dynamic brushsize
tool (mari.Tool): The Tool object e.g. mari.tools.currentTool()
If no tool is given, the current tool is used.toggleDynamicBrushSize(tool=None)
Toggles the dynamic brushsize for a given tool on if it is off,
and off if it is on.
If no tool argument is given, the current tool is used.
If no tool is given, the current tool is used.toggleSteadyStroke()
Toggles the Steady Stroke Brush Otpion on and off
When toggling on, the last used Mode is restored.
Modes are stores per Toolsetup_dynamic_brushsize(action_path=None)
Utility Function to setup the dynamic brushsize system
on Mari Startupmari.ExtensionPack.camera()
Camera/View related toolsswitch_to_ortho_view()
Switch the active tab to the Ortho Viewswitch_to_persp_view()
Switch the active tab to the Perspective Viewswitch_to_split_view()
Switch the active tab to the Split Viewswitch_to_uv_view()
Switch the active tab to the UV Viewunproject_channel_to_imagemanager()
Unproject Channel to Image Manager toolunproject_layer_to_imagemanager()
Unproject Layer to Image Manager toolunproject_view_to_imagemanager()
Unproject View to Image Manager toolmari.ExtensionPack.channel()
Channel related toolschannelFromChannelNode(geo, channelNode)
Returns a mari.channel from a mari.bakePointNode (a channel node)
geo (mari.geoEntity): The geo to look for a channel
channelNode (mari.BakePoint): The channelNode
mari.Channel or None: Returns a Mari Channel or None if nothing is foundcreateChannelFromUDIMTemplate()
This method is deprecated and will be removed in a future version
Create a new Channel with the UDIM Size Configuration
stored via channel_template_getduplicate_channel()
Duplicate selected channel with all sharing intactduplicate_nodeNetwork(geo, inputNode, inputNodeNodeGraph, StopAfterRadioNodes=True, RenameChannelIncremental=True, RenameChannel=False, newChannelName='Renamed Channel', offsetX=50, offsetY=50)
Duplicatas a Node Network such as a channel while cleanign up and rebuilding shared connections in the graph.
Please be aware the same method exists in the Nodegraph Class
geo (mari.geoEntity): Geo, inputNode lives on
inputNode (mari.Node): The node which to use as a base to duplicate the network
(upstream connections). Should be a channel node but doesn't have
to be
inputNodeNodeGraph (mari.Nodegraph): The Nodegraph the input Node belongs to
StopAfterRadioNodes (bool): If true (default value) connections upstream of a radio node will
not be duplicated and the original Radio Node Connection is
maintained if the first node upstream of a radio has connections
to other channels.
RenameChannelIncremental (bool): If true (default value) and the inputNode is a Channel, the
resulting duplicated channel will be renamed incrementally (1,2,3 etc.)
RenameChannel (bool): If RenameChannelIncremental=False and RenameChannel=True, and the inputNode
is a channel, the resulting duplicate channel will be renamed with the name
specified under newChannelName
newChannelName (string): if RenameChannel=True and the inputNode is a channel, the resulting
duplicate Channel will be renamed with this name
offsetX,offsetY (int): The offsetX and offsetY specify the offset of the duplicated nodes
from their original nodegraph position
mari.Node(): Returns the new Node with intact connectionsfocusChannelContentInGraph(stopAfterRadios=False)
Selects the corresponding Nodes of a Channel in the Nodegraph and focuses the view on it
stopAfterRadios (boolean): If True, only nodes up to and including a radio node will be selected and focused.
Radio Node Connections will not be included. Default = FalsefocusChannelInGraph()
Selects the corresponding Node of a Channel in the Nodegraph and focuses the view on itlockAllChannels()
Lock all ChannelslockChannel()
Lock a ChannelresizeChannelToUDIMTemplate(geo=None, channel=None)
This method is deprecated and will be removed in a future version
Sets the currently selected Channel to the UDIM resolutions
stored via channel_template_get.
geo and channel can optionally be supplied as arguments
geo (mari.geoEntity): Pass in the Geometry the Channel lives on. If None (default) the selected object is used
channel (mari.Channel): Pass in the Channnel to get the resolution off. If None (default) the selected channel is usedsaveChannelUDIMTemplate(geo=None, channel=None)
This method is deprecated and will be removed in a future version
Samples the currently selected Channel and stores its resolutions per UDIM.
geo and channel can optionally be supplied as arguments
geo (mari.geoEntity): Pass in the Geometry the Channel lives on. If None (default) the selected object is used
channel (mari.Channel): Pass in the Channnel to get the resolution off. If None (default) the selected channel is usedsyncCurrentChannel(sourceObject=None, targetObject=None, channelName=None)
Syncs the channel selection between objects
sourceObject (mari.geo): optional object to specify the source channel to sync with
targetObject (mari.geo): optional target object to sync the channel selection on. If None, all objects are synced
channelName (string): optional Channel Name to sync all objects with.unlockAllChannels()
unlock all channelsunlockChannel()
Unlock a channelchannelsFromNode_UI()
Create Channels from a selected Nodecreate_packed_channel()
Launch Pack Channel UIduplicateFlattenChannels()
Launches Duplicate/Flatten Channel Dialogmari.ExtensionPack.channelLayer()
Channel Layer related methodschannelLayer_AddLayer()
Launches the "Add Channel Layer" UIchannelLayer_AddLayerMask()
Launches the "Add Channel Mask" UIchannelLayer_AddMaskGroup()
Launches the "Add grouped Channel Mask" UImari.ExtensionPack.content()
Install ContentcheckIfShelvesAreUpToDate(progressDialog=None)
Compares if Shelf Content is the latest and installs any new ones
progressDialog (obj): This allows you to pass in a progress dialog to be used.
If this is None it will spawn its own progress Dialog but otherwise
use the given one. This is to avoid progress Dialogs randomly open
and closing on EP Startup, when several things will be installed
success (bool): Returns true if the checking process finished. It always returns True
and the return is just a method to have sequential processes running via
"if true" check.
progressDialog (obj): Returns the Progress Dialog used by this process. This can be exactly
the same progress dialog that was passed in via the Args or the new one
created by the processinstallHDRIs(progressDialog=None)
Will install content to the Mari shelf under an "Environment Group"
1) Mari HDRIs will be installed in appropriate directories
2) Substance Painter common Install Locations will be checked and if found,
added to the Environment Image Path Preferences in Preferences / Paths
3) Additional HDRIs will be installed from any folder specified in Preferences / Paths / Environment
progressDialog (obj): This allows you to pass in a progress dialog to be used.
If this is None it will spawn its own progress Dialog but otherwise
use the given one. This is to avoid progress Dialogs randomly open
and closing on EP Startup, when several things will be installed
success (bool): Returns true if the checking process finished. It always returns True
and the return is just a method to have sequential processes running via
"if true" check.
progressDialog (obj): Returns the Progress Dialog used by this process. This can be exactly
the same progress dialog that was passed in via the Args or the new one
created by the processinstallMaterialPresets(closeDialogAfter=False)
Installs standard empty material presets to a new shelf.
This method is also called directly from the Mari Preferences when checking and unchecking
Material Presets. In these cases "closeDialogAfter" is set to True
closeDialogAfter (bool): If true the Progress Dialog that will spawn will be force closed and not passed onto other dialogs
success (bool): Returns true if the checking process finished. It always returns True
and the return is just a method to have sequential processes running via
"if true" check.
progressDialog (obj): Returns the Progress Dialog used by this process. Please be aware of the
closeDialogAfter Argument, as the progress dialog might have been closed by
that argument and therefore None is returnedrendermanForMariInstalled()
Check if Renderman for Mari is installed
(bool) True if Renderman for Mari is installedaddMaterialTemplatePreferences()
Add Template Preferences to the Mari PreferencesloadMaterialTemplatePreference()
load the Material Template Preferences from the Config fileloadMaterialTemplatePreferenceFromEnvVar()
load the material template preferences from Env VariablessaveMaterialTemplatePreference()
Save the Material Template Preferences to the Config filemari.ExtensionPack.dev()
A number of tools and dialogs to
easily find classes, methods, actions and menu pathsaction_finder()
Launches Dialog to search through Mari Actionsclass_method_finder()
Launches Dialog to search through available classes and methodsmenu_path_finder()
Launches Dialog to search through Mari Menu PathsmimeTypeInspector()
A simpel dialog accepting Drag and Drop events and returning the Mime Typenode_path_finder()
Launches Dialog to search through available node paths. Requires open Projectmari.ExtensionPack.dragAndDrop()
Drag and Drop Callback Related methodsgetLastLayerStackRefLayer()
Returns the Layer (mari.Layer) that was below
the last Drag & Drop Action to the Layerstack containing text/plain mime data
This is the positional Reference Layer that can be used
to set the position of a new layer object in the Target Layerstack
mari.Layer: A Mari Layer ObjectgetLastLayerstackDropTarget()
Returns the last Layerstack (mari.Layerstack) that was the target
of the last Drag & Drop Action containing text/plain mime data
mari.Layerstack: A Mari Layerstack ObjectgetLastNodegraphDropNodeGraph()
Returns the Nodegraph (mari.Nodegraph()) that was the target
of the last Drag & Drop Action containing text/plain mime data
mari.NodeGraph: A Mari Nodegraph ObjectgetLastNodegraphDropPosition()
Returns the node graph position coordinates
from the last drag & drop action to the Nodegraph Palette
containing text/plain mime data
QPointF: X and Y Position in the NodegraphresetLastDropTargets()
Resets/removes all saved data from the last dropactions.
This means the other methods of this class e.g. getLastLayerStackRefLayer()
will return None.add_DragAndDrop_Callback_Preferences()
Adds Preferences to Mari Misc Preferences to turn Callbacks on and offload_DragAndDrop_Callback_Preferences()
Loads Callback Preferences in Mari Misc Preferences from the config fileregister_DragAndDrop_Callbacks()
Registers Extension Pack Callbacks for Drag and Drop
Mari 4.7 and higher onlyregister_PresetBrowser_DragAndDrop_Callbacks()
Registers Preset Browser Drag and Drop Actionssave_DragAndDrop_Callback_Preferences()
Saves Callback Preferences in Mari Misc Preferences to the config filemari.ExtensionPack.exceptions()
Handles Extension Pack's Global Exception LoggergetExceptionHandlerClass()
Returns Extension Pack's global Exception Handler that is attached to
sys.excepthook.
Whenever an exception occurs there are two class' internal signals emitted:
_exception_caught_log(str)
_exception_caught_raw(exc_type, exc_value, exc_traceback)
You can use the class to attach other uses to those signals.
The _exception_caught_log() signal is containing the log message that gets
written to Extension Pack's own Log Files under /Mari/Logs/, while the
_exception_caught_raw() contains the unaltered data from sys.excepthook
Please note, that Extension Pack's Exception Handler is set up in a way that it
still calls previous methods that were attached to sys.excepthook before Extension Pack
attached its own.
Whenever Extension pack's Exception handler gets triggered the previous Exception handler gets
called as well via
self.old_excepthook(exc_type, exc_value, exc_traceback)
If you want to completely prevent Extension Pack from registering its own excepthook, you can
set the Environment Variable MARI_EP_PREVENT_EXCEPTION_LOGGING. This will stop Extension Pack
from modifying sys.excepthook on startup.
write Messages to Extension pack's own log
_exception_caught_raw(o,o,o): The signal forwards the original data from sys.excepthook
e.g. exc_type, exc_value, exc_tracebacklog_error(message)
Logs an error to extension packs own error logs
This can be used to log "hidden exceptions" or unusual application behaviormari.ExtensionPack.exportChannel()
Export related toolsexportLast()
Runs the last Export from Export Custom Channel SelectionexportSelectedChannels()
Launches Export Custom Channel Selection Dialog with the
"Flattened" CHeckbox turned offexportSelectedChannelsFlattened()
Launches Export Custom Channel Selection Dialog with the
"Flattened" CHeckbox turned onrestoreExportLastBehavior()
Sets the Checkbox for "Export Last" Patch Selection Behavior
back to the way it was when Mari was last openedsetExportLastBehavior()
Sets the Checkbox for how "Export Last" is to deal
with Selected Patch Export - using the original selection
or the current onemari.ExtensionPack.gizmo()
Gizmo methodslauchMaskPresetUI(nodelist, ReplaceExisting=False, ForceConnectionDialog=False, parent=None)
Launches the Mask Preset Setup UI
scanning the nodelist for ports that can be setup.
This is the system used to auto setup Smart Masks.
nodelist (list): a list [] of mari.Node Objects
ReplaceExisting (bool): if the tool is executed with Replace Existing, it will replace existing connections
on a preset. Otherwise it will only create new connections on empty node ports
ForceConnectionDialog (bool): Usually a Connection Dialog won't be shown if the Tool finds all necessary channels
in your Project. Running it with ForceConnetionDialog=True will always show the
connection dialog
parent: The parent for the dialog. If left at None the parent will be the mari main windowlaunchMaskPresetUIPreferences()
Launches the Mask Preset Setup Preferences UI.
This is the system used to auto setup Smart Masks.launchMaskPresetUI_BakingMode(parent=None)
Launches the Mask Preset Setup UI
This is the system used to auto setup Smart Masks.
In the Baking mode it doesn't require a node but shows Curvature Baking options
so users can create the frequently used channels without already having a preset
parent: The parent for the dialog. If left at None the parent will be the mari main windowlaunchMaskPresetUI_RefreshMode(nodelist, parent=None)
Launches the Mask Preset Setup UI
scanning the nodelist for ports that can be setup.
This is the system used to auto setup Smart Masks.
In the refresh mode all ports are considered even if they already have something
attached
nodelist (list): a list [] of mari.Node Objects
parent: The parent for the dialog. If left at None the parent will be the mari main windowlaunchMaskPresetUI_SelectedNodes(ReplaceExisting=False, ForceConnectionDialog=False, parent=None)
Launches the Mask Preset Setup UI
with the current Node Selection as processing base
This is the system used to auto setup Smart Masks.
ReplaceExisting (bool): if the tool is executed with Replace Existing, it will replace existing connections
on a preset. Otherwise it will only create new connections on empty node ports
ForceConnectionDialog (bool): Usually a Connection Dialog won't be shown if the Tool finds all necessary channels
in your Project. Running it with ForceConnetionDialog=True will always show the
connection dialog
parent: The parent for the dialog. If left at None the parent will be the mari main windowmari.ExtensionPack.help()
Access to Help and TutorialscontactFoundrySupport()
Opens a webbrowser to the Foundry Support PortalcreateSmartMaskProject()
Creates a Project with the Smart Mask Icon Geo and some Bakesopen_LogFile()
Opens the Mari Log Fileopen_MariUserSettingsFolder()
Opens the Mari User Settings Folderopen_online_help()
Launch Extension Pack Online Helpopen_pyAPI_help()
Launch Extension Pack Local Py API Helpopen_releaseNotes()
Launch the Release Notesopen_shortcut_help()
Generates a on-the fly overview of the current shortcut mappings as html
and opens the page in a browseropen_tutorials()
Launch Youtube Extension Pack Tutorialssend_bug_report()
Opens an email form to report an Extension Pack IssuedocumentationEditor(noDialog=False)
The documentation editor runs over the documentation
and builds accordion style menus as well as replacing
header colors
Accordions are built based on the following syntax within the Online help.
The ids are used to generate unique items within the page that the stylesheet
can react to.
Example of an accordion with 2 tabs:
#--[ACC-START,UNIQUE_ID1,UNIQUE_ID2,Label]--#
#--[ACC,UNIQUE_ID1,UNIQUE_ID2,Label]--#
#--[ACC-END]--#
Example of an accordion with two tabs,expanded by default.
#--[ACC-START-EXPANDED,UNIQUE_ID1,UNIQUE_ID2,Label]--#
#--[ACC-EXPANDED,UNIQUE_ID1,UNIQUE_ID2,Label]--#
#--[ACC-END]--#PyAPIHelpURL()
returns the local python help pathPythonAPI_HelpBuilder(TargetFolder='', CustomMarkerTargetUrl='extPack_PythonAPI_Doc.html', OnePagePerClass=False)
Builds an HTML Documentation of the Extension Pack Classes and Method
TargetFolder (string): The Target Folder to build the HTML Help in.
If left empty ('') the HTML Docs will be built under
Extension Packs /Tools/Help Folder
CustomMarkerTargetUrl (string): When building all of the HTML help within a single HTML page
the HTML Builder will add markers to each class and a link list
of classes linking to those markers at the top of the page.
The CustomMarkerTargetUrl is the Filename of the HTML Page
so the Anchor linking works (e.g )
OnePagePerClass (bool): If true, a single HTML page per class will be created.
If False (Default), then all classes will be documented within a single page
with a table of content at the top of the page.activationIssuesHelp()
returns the URL to the steps to debug ativation issuesemail()
Returns the Extension Pack Contact Emailfacebook()
returns the online url to the Extension Pack Facebook PagelocalWebServerFilePath()
Returns the path to the local webserver python script fileonlineHelpBasePath()
returns the online help base domain (without HTML page)onlineHelpURL()
returns the online help urlopenResourceMoveTutorial()
Opens a tutorial in a web browser
how to move Extension Pack Resource Files
out of the Install FolderopenTdrTutorial()
Opens a tutorial in the webbrowser how to adjust TDR ValuesreleaseNotesURL()
returns the local release notes text file pathresourceMovingTutorialURL()
returns the online help URL to the Tutorial for moving Extension Pack
Resources out of the main foldertdrTutorialURL()
returns the online help URL to the Tutorial for adjusting TDR Valuestwitter()
returns the online url to the Extension Pack Twitter PageupdateOnlineHelpBaseIdent()
This sets the global variable ONLINE_HELP_BASE_IDENT.
It parses the MARI_EP_HELP_LOCATION Environment Variable
first and if this one is empty/non-existent defaults
to what is defined in ONLINE_HELP_BASEyoutubeURL_AllTutorials()
returns the online url to the youtube playlist containing
all Extension Pack TutorialsyoutubeURL_VersionSpecificTutorials()
returns the online url to the youtube playlist containing
Extension Pack Tutorials for this particular Versionmari.ExtensionPack.history()
Undo Related MethodsclearHistory()
Saves project and clears the history after a dialog asking to confirmresumeHistory()
closes any active macro in case the history recordng has been interrupted due to a bugmari.ExtensionPack.hotbox()
Hotbox related methodscloseHotboxInstances()
Force closes any open hotbox instancecurrentHotboxInstance()
Returns the currently open Hotbox InstanceshowHotbox(path='', SubmenuBackLink=None, force=False, resetPosition=True, parent_widget=None, isNodeContextMenu=False)
General Method to launch a hotbox
path (str): The Path to the Hotbox Configuration Folder
SubmenuBackLink (str): The Path to the Hotbox Configuration Folder the Submenu should link back to
force (bool): Force Open a new Instance of the Hotbox
resetPosition (bool): Reset the Cursor Position (Hotbox Center on Launch) to cursor position
parent_widget (QWidget | None): Optional. The widget to parent the Hotbox to
isNodeContextMenu (bool): If True, the hotbox will be treated as a node
context menu. Node Context Menu appear over a node
if CTRL+SPACE is pressed in the Nodegraph.
The boolean flag ignores the cursor position and
places the menu over the selected node.
The size of the menu is dynamically adjusted based
on nodegraph zoom levelhotboxManagerUI()
Launches the Hotbox Designer UIinstallEPHotboxes()
Installs Extension Pack Hotboxes into the Hotbox Folder
if they don't exist yet/are the same versionsetupEPHotboxesOnStartup()
Sets up Extension Pack Hotboxes on Mari startup
in a way that I am removing pre existing mari hotkeys for certain actions
if they are mappedsetupHotboxesOnStartup()
Sets up existing User Hotboxes on Mari startupmari.ExtensionPack.imageAnnotation()
Class to handle all aspects of sticky notes with imagescreateNewImagNote(customPosition=None)
Creates a new visual note in the currently active graph
customPosition (QPoint): A custom position to create the node at. Otherwise
the nodegraph center of the active graph tab
node (mari.Node): Returns the newly created Note or NonegetImagePath(node)
Retrieves the image path from a visual Note
node (mari.Node): the node to get the image path from
(string): the image pathgetImageSize(imagePath)
Returns the image size of a given image on disc
imagePath (string): path to an image on dic
(int),(int): Returns two integers (width,height) or None,None if path not foundgetLastImageNote()
Returns the last created Visual Note.
This can be useful since certain actions internally create a new stickyNote
(mari.Node): Returns a Mari Sticky Note or NonegetProjectThumbnailPath()
Returns the path to the directory where image notes are saved.
The path is within the current project directory
(string): Path to snapshot directoryimageNoteFromFile(filePath=None, initialScale='100%', forceNewNote=False, customPosition=None, colorizeImage=False, color=[255, 255, 255], blendMode='Multiply', stickyNoteToReplace=None)
Set a visual Note from an chosen file from disc.
If the action is performed with a sticky note selected and forceNewNote is False (Default)
the selected sticky note will be modified.
Otherwise a new sticky note will be created
if a filePath argument is given that path will be used,
otherwise a file dialog will be shown
filePath (string): An optional file path. If given no dialog will be shown
initialScale (string): A percentage as a string to set the new scale factor to.
Vaid strings are:
'5%' '10%' '20%' '30%' '40%''50%' '60%' '70%' '80%' '90%' '100%''110%'
'120%''130%''140%''150%''160%''170%''180%''190%''200%'
Defaults to 100%
forceNewNote (bool): Optional argument if to force a new Note at all times.
Defaults to False. If False a new note will only be created if no
existing visual Note is selected. Otherwise the existing one will be replaced.
customPosition (QPoint): An optional custom position for the node. This might be required because
the function internally replaces the original node.
While the original node position should be maintained, sometimes you might
want to specify a new position.
Default to None,which in turn will use the center of the current nodegraph tab
colorizeImge (bool): If True, allows you to colorize the Image before use. Defaults to False.
Coloriziation will be done within the Mari Project. E.g. if you supply an imagePath
in a Location outside of the Mari Project Cache, the file will be copied over to the
project and then colorized. The original file remains unchanged.
color (list): The color values to use when colorizeImage Parameter is true. Defaults to [255,255,255]
blendMode (string): The Blend Mode to use when colorizing an Image.
Available option are "Multiply","Soft Light","Screen","Overlay".
Defaults to "Multiply"
stickyNoteToReplace (mari.Node): If forceNewNote is False and a node is provided on this argument, the given node
will be replaced with a new image note
(mari.Node): Returns a StickyNoteimageNoteFromNode(graph=None, nodelist=None)
Creates a visual note for given nodes by attaching a viewer to nodes
and placing the note directly next to the given node
If the graph and nodelist argument are None, then the currently open
graph tab and the selected nodes within it are used.
graph (mari.NodeGraph): A optional Mari Nodegraph to work with. Defaults to None.
If this is None, the currently open Nodegraph is used
nodelist (list): A list of nodes to process. Defaults to None.
If this is None, the selected Nodes of the currently open
Nodegraph are used.
The nodes of the given Nodelist need to be part of the
give graph (graph argument)imageNoteFromView(scaleFactor='100%')
Creates a visual Note from the current viewport
If the action is performed with a sticky note selected
the selected sticky note will be modified.
Otherwise a new sticky note will be created
scaleFactor (string): A percentage as a string to set the default scale factor to.
Vaid strings are:
'5%' '10%' '20%' '30%' '40%''50%' '60%' '70%' '80%' '90%' '100%''110%'
'120%''130%''140%''150%''160%''170%''180%''190%''200%'
Defaults to 100%
(mari.Node): Returns a StickyNotenodeIsImageNote(node)
Returns True if the given Node is a visualNote
node (mari.Node): the node to test
(bool): True if the Node is a visualNoterelinkImageNotePathToProject(node)
Relinks a path of a given visual note to the current projets
Visual Note Folder. If the file does not exist inside the folder
it will be copied.
(mari.Node): a mari Node of type Sticky NoteremoveAllImageNotes(graph=None, silent=False)
will remove all visual Notes from the given Graph
If the Graph Argument is None (default),
the currenty active Graph Tab will be considered
graph (mari.Nodegraph): The mari.nodegraph to apply the action to.
Defaults to None, in which case the currenty active
graph tab will be considered.
silent (bool): if true, no warning dialog will be shownsetImageOnNote(stickyNote, imagePath, sizeX=512, sizeY=512)
Sets an image onto a sticky note.
stickyNote (mari.Node): A Mari Sticky Note
imagePath (string): Path to an image file
sizeX (int): An optional initial width for the image
sizeY (int): An optional initial height for the image
(bool): Returns True if the action was successfulupdateImagePath(node, newPath, original_path=None)
Replace the current stickyNotes image path with a new one
node (mari.Node): a mari sticky note
newPath (string): a path to an image on disc
original_path (string): Optional. The Original Path is the Path an image was import from on disc.
This acts like a fallback if the main path inside the Project no longer exists.
Added in EP 6R3. Defaults to None.updateImageSize(node, newWidth=512, newHeight=512, customPosition=None)
Updates the given nodes core image size settng in the html attribute
node (mari.Node): a mari sticky note
newWidth (int): the new width of the image
newHeight (int): the new height of the image
customPosition (QPoint): An optional custom position for the node. This might be required because
the function internally replaces the original node.
While the original node position should be maintained, sometimes you might
want to specify a new position.
Default to None.
mari.Node: Returns a sticky NoteupdateScaleFactor(node, newFactorPercent, customPosition=None)
Updates a visual Notes "Scale Factor" Setting.
Please note, this internally creates a new instance of the stickyNote which
replaces the old given node
node (mari.Node): a mari sticky Note
newFactorPercent (string): A percentage as a string to set the new scale factor to.
Vaid strings are:
'5%' '10%' '20%' '30%' '40%''50%' '60%' '70%' '80%' '90%' '100%''110%'
'120%''130%''140%''150%''160%''170%''180%''190%''200%'
customPosition (QPoint): An optional custom position for the node. This might be required because
the function internally replaces the original node.
While the original node position should be maintained, sometimes you might
want to specify a new position.
Default to None.
(mari.Node): Returns a StickyNotecloseIconShelfInstance()
Closes any Icon Shelf running in the BackgroundimageNoteFromCustomView()
Opens a snapshot dialog showing the current view and allowing
cropping and default scale factorlaunchIconShelf()
Opens the icon shelfresetIconShelfPositionAndSize()
Closes any currently active instance of the Icon Shelf
then resets the size and position to defaultstickerDesigner()
Opens the Sticker Designer in the NodegraphimageSizeChanged(name, value, node)
a signal connection when the image size dropdown in an image note gets triggered
name (string): A Metadata Name
value (variant): Metadata Value
node (mari.Node): The Mari Node that needs updatinginherit_image_from_backup(node)
If the main image does not exist we check the original import path of the image
and transfer it onto the node
node (mari.Node): A EP Image Notemari.ExtensionPack.imageManager()
Image Manager related methodsactivateAutoReloadingOnSelectedImages()
Sets the Auto Reloading on selected images in the image manager
to oncleanImageManager()
Checks if an Image is used in the project by comparing the Image Path
in the Image Manager to Image Path Metadata on all nodes in projectdeactivateAllImageAutoReloading()
Sets the "Auto Reload" CHeckbox on all images in the Image Manager to "Off"
This is an action called from the Right Mouse Click Menu of the
Image Manager / Auto Reload MenudeactivateAutoReloadingOnSelectedImages()
Sets the Auto Reloading on selected images in the image manager
to offdisableReferenceImage_onSelectedImages()
Disables the IsReferenceImage Checkbox on selected imagesenableImageAutoReloadOnImageManagerFiles(imageList=None)
Enables the "Auto Reload" behavior on loaded Images Manager Images
imageList (list): an optional list of images to limit the auto reload metadata additon toenableReferenceImage_onSelectedImages()
Enables the IsReferenceImage Checkbox on selected imagesfindImage(filePath, is_raw=None, is_scalar=None)
Checks if a given filepath is already imported into the Image Manager with optional checks for
raw and scalar mode
filePath (str): path to an image file
is_raw (bool): Optional. If the files colorspace config should be RAW
is_scalar (bool): Optional. If the files colorspace config should be Scalar
mari.Image: Returns the mari.Image Object or None if not foundimagesInUse()
Returns a list of all mari.Image Objects currently in use anywhere in the project (any node)
list: Returns a list of mari.Image ObjectsopenImageInApplication(applicationExecutable)
Opens the last selected image in the application provided
applicationExecutable (str): A path to an executable applictionopenImageInDefaultApplication()
Opens the last selected image in the default application
associated with the image formatopenImageInFileBrowser()
Opens the last selected image in your OS FilebrowserrasterizeVectorImage(filePath, colorSpaceConfig, size)
Imports an SVG file into the Image Manager, rasterized at a given
size
filePath (str): path to a .svg file on disc
colorSpaceConfig (mari.ColorspaceConfig): The Colorspace Config File to use for opening
size (tuple): A tuple defining width and height of the final
rasterized vector image
mari.Image: Returns the mari.Image Object added to the Image ManagerreloadImage(imageObject)
Reloads a given image Object.
Returns the image object
imageObject: the mari.image object to reload
mari.Image: the new image objectreloadSelectedImages(svgMode=False)
Reloads selected images in the image manager from disc and updates
their occurences inside of the project (tiled, triplanar etc.)
svgMode (bool): Optional. If True and the selected File originates from a
.svg file (as detected by metadta "svgSourceFile"
a dialog will spawn to be able to chnage the resolution
of the rasterized image. If False (default) the svg file
will be reloaed at previous resolution.
Argument Has no effect on other file formats.reloadSelectedSVGFiles()
Reloads selected images in the image manager from disc and updates
their occurences inside of the project (tiled, triplanar etc.).
If the selected file originates from an SVG File a dialog will prompt for the new resolutionremoveEmptyImageManagerGroups()
Removes any empty Groups from the Image Manager
Mari 7.5 and above only.removeEmptyImageManagerTabs()
This method will be deprecated in a future version.
Mari 7.5 removes Image Manager Tabs as a feature and replaces it with Groups
Removes any empty Categories/Tabs from the Image ManagerremoveImageManagerTabs()
This method will be deprecated in a future version.
Mari 7.5 removes Image Manager Tabs as a feature and replaces it with Groups
Removes all User created Image Manager TabssetAutoReloading_onSelectedImages(mode)
Sets the Auto Reloading on selected images in the image manager
to on or off
mode (bool): True/False to enable/disable the Auto ReloaduseImageAsBrushtip()
Uses the currently selecte image as the brushtip on the current toolconfigureApplications()
Launch UI to configure Applications to open images inexportSelected()
Export the selected images in the image manager to a foldersvgRasterizer(filePath, originalImage=None, noCancel=False)
Opens a SVG Rasterization Dialog
filePath (str): a path to a svg file
originalImage (mari.image): a mari image object to replace (optional, defaults to None)
noCancel (bool): if True, the Cancel Button in the SVG Loader is disabled
mari.Image: a rasterized Mari Image ObjectaddImageManagerDefaultApplications()
Adds some standard applications (Photoshop,Krita) to the list of application
available in "Open with" if found on your sytemconnectSVGLoader()
Creates a Signalo Connection to mari.images.imageLoaded(),
testing the file format of loaded images.
If a .svg file is loaded a dialog will spawn with rasterizaton
optionsdisableAllImageAutoReloadingOnProjectClose()
Removes all paths in the "File Change Watcher" so no
image changes are detected anymore
This is usually only called once a project is closed. For individual
turning off of the feature on selected images, you can use deactivateAutoReloadingOnSelectedImages()disconnectSVGLoader()
Disconnects Signal Connection to mari.images.imageLoaded(),
testing the file format of loaded images for .svg filesmari.ExtensionPack.imageUtils()
Various Python Helper Methods to deal with QIcons, QPixmaps etc.darken_image(pathImageIconOrPixmap, factor=100, desaturate=False, return_QImage=False)
Darkens or brightens an Image
factor (int): Determines if to brighten or darken the image.Defaults to 100, which means
no change. Values above 100 darken, values below 100 brighten
desaturate (bool): Defaults to False. If True, the input image is desaturated first.
return_QImage (bool): By default the same format as the pathImageIconOrPixmap input
is returned. However if this argument is a string (path), then
by default a pixmap is returned unless the return_QImage is set to True.
pathImageIconOrPixmap. However if this argument is a string (path)
then by default a pixmap is returned unless the return_QImage Argument
is set to Truedesaturate_pixmap(original_pixmap)
Returns a desaturated QPixmap object fron a Input QPixmap objectdesaturate_qimage(original_qimage)
Returns a desaturated QImage object fron a Input QImage objectget_ep_icon(icon_name, scaledTo=None, stateAware=False)
Returns a QIcon from an Extension Pack Image located in its resources/icon folder
the filename is case-insensitive.
scaledTo (list): [width, height] to scale the icon to. Optional. Leave at default None to ignore
stateAware (bool): If True, the Icon is aware of checked and unchecked states and will desaturate when
unchecked. Defaults to Falseget_ep_pixmap(icon_name, scaledTo=None)
Returns a QPixmap from an Extension Pack Image located in its resources/icon folder
the filename is case-insensitive.
scaledTo (list): [width, height] to scale the icon to. Optional. Leave at default None to ignoreget_mari_icon(icon_name, scaledTo=None, stateAware=False)
Returns a QIcon from an Image located in the mari icon folder
the filename is case-insensitive.
scaledTo (list): [width, height] to scale the icon to. Optional. Leave at default None to ignore
stateAware (bool): If True, the Icon is aware of checked and unchecked states and will desaturate when
unchecked. Defaults to Falseget_mari_pixmap(icon_name, scaledTo=None)
Returns a QPixmap from an Image located in the mari icon folder
the filename is case-insensitive.
scaledTo (list): [width, height] to scale the icon to. Optional. Leave at default None to ignoremari.ExtensionPack.layer()
Layer related methodsaddMask(mode)
The Add Mask Tools in Extension Pack are replacements for the existing Mari Add Mask functionality
Reveal All
Hide All
From Alpha
From Selection
From Selection Group
They act identical to the default Mari functionality in most cases however the Add Mask Tools
will no longer be disabled/greyed out when a mask or mask stack already exists on the layer
When executed on a layer with a pre-existing mask, the mask will be removed and a new one added
depending on the tool executed
When executed on a layer with a pre-existing mask stack, the mask stack will be removed and a new one added
depending on the tool executed
mode (str): available options are "reveal","hide","from Alpha","from Selection","from Selection Group"cloneMergeSelectedLayers()
Executes layer Clone & MergeconvertToPaintable()
Extension Pack Version of standard Mari Layer Convert to Paintable
Supports multi selection and channel layerscopyLayerAttributes()
Copies selected Layer Attributes to a ClipboardcopyWithShared()
Executes "Copy with Shared Connections"
Shared Layers will always be relinked to their original source,
including in Mask Stacks
Pasted Channel Layers will be relinked to the original channel,
without unnecessary channel duplicationfindActiveLayerSelection(includeAdjustmentStacks=True, includeMaskStacks=True, includeGroupLayers=True, includeChannelLayers=True, silentFail=False)
The following are used to find layerselections no matter where in the Mari Interface
(Floating Palettes, Mask Stacks etc.)
This is to support a) Layered Shader Stacks b) deeply nested stacks (maskstack,adjustment stacks),
as well as cases where users are working in pinned or docked channels without it being the current channel
includeAdjustmentStacks (bool): Determines if to include this StackType into the search
includeMaskStacks (bool): Determines if to include this StackType into the search
includeGroupLayers (bool): Determines if to include this StackType into the search
includeChannelLayers (bool): Determines if to include this StackType into the search
silentFail (bool): If true, no warnings are returned if nothing is found
curGeo: The current Geo or NONE
curChannel: The current Channel or NONE
curStack: The current Layerstack (NOT the same necessary as the channel) or NONE
curLayer: The 'current' layer as in the current paint target or NONE
curSelList: A list of all selected layers or NONElayerCopy()
Standard Mari Layer COPY Action,however since extension pack
moves the action in the UI it is declared here againlayerCut()
Standard Mari Layer CUT Action,however since extension pack
moves the action in the UI it is declared here againlayerPaste()
Standard Mari Layer PASTE Action,however since extension pack
moves the action in the UI it is declared here againpasteLayerAttributes()
paste Layer Attributes onto selected layer from a ClipboardpasteWithShared()
Executes "Paste with Shared Connections"
Shared Layers will always be relinked to their original source,
including in Mask Stacks
Pasted Channel Layers will be relinked to the original channel,
without unnecessary channel duplicationtoggleSelectionLock()
toggles the locking of selected layerstoggleSelectionVisibility()
toggles the visibility of selected layerstoggleUnselectedLock()
toggles the locking of unselected layerstoggleUnselectedVisibility()
toggles the visibility of unselected layersswapLayerType()
Dialog Call.
Allows you to swap out any Layer type for another Layer type.
If possible, settings are transfered between nodesmari.ExtensionPack.layout()
View Layout related methodsloadLayoutFromPath(Path, LayoutName=None)
Load an mws layout file from a given path.
Path (string): The Path to a mws layout file or folder where a mws layout file is located.
LayoutName (string): Optional Argument. The Layout File Name without extension.
This is required if the Folder the file sits in is named differently then the Layout filerestoreDefaultLayout()
Restore the Mar Default LayoutsaveLayout(layoutName, Description='')
Saves a layout to the folder specified in Mari Preferences / Path / Layout Tab.
Also adds the layout to View / Saved Layouts Menu
layoutName (string): The name of the layout
Description (string): An Optional Description. Defaults to ""
(string): Returns a cleaned Layoutname, that has been sanitized from invalid characterssetLayoutFolderPreference(path)
Sets the Layout Folder in the Preference.
This is the location where layouts are loaded from.
path (string): A path where Layouts should be stored
bool: True if path could be setsetPaletteOrientationHorizontal()
Set the Preference Window Corner Dock Areas to a valuesetPaletteOrientationSplitBottom()
Set the Preference Window Corner Dock Areas to a valuesetPaletteOrientationSplitLeft()
Set the Preference Window Corner Dock Areas to a valuesetPaletteOrientationSplitRight()
Set the Preference Window Corner Dock Areas to a valuesetPaletteOrientationSplitTop()
Set the Preference Window Corner Dock Areas to a valuesetPaletteOrientationVertical()
Set the Preference Window Corner Dock Areas to a valueexportLayout()
Export a Layout to Disc via a File DialogimportLayout()
Import a Layout from Disc via a fileDialoglayoutManager()
Open the Layout Manager UIsaveLayoutUI()
Open a dialog to specify a name and description for a layout.
The Layout gets saved into the location specified in Mari Preferences / Path / LayoutaddLayoutFolderPreference()
Adds Preferences to the Mari Preference Dialog
to set a Path where Layouts should be stored
/Preferences/Paths/LayoutsgetLayoutDebugInfo()
Utility method returning the current mws layout info
which can be useful to find edge cases where EP utility functions such as "findNodegraphTabwidget"
are not workingloadLayoutFolderPreference()
Load theLayout Preference Path from the config
and set it in the /Preferences/Paths/LayoutsreinstallCustomUIElements()
Readds custom UI Elements previously added by EP on Startup
(View / extPack_layoutChange)restoreSavedLayouts()
Restores all previously saved layouts to Menu
View / Saved Layouts. This is called on Mari OpensaveLayoutFolderPreference()
Saves the layout Folder to the configmari.ExtensionPack.lights()
Light related methodsrotateEnvironmentLight(mode, multiplier)
Rotates the Environment Light.
Mode is either "slow","medium" or "fast"
The multiplier is usually 1 or -1 to rotate clockwise or
counterclockwise
mode (string): The mode determines the rotation angles per step as defined in the Mari Preferences
Options are "slow","medium","fast"
multiplier (int): The Multiplier defines the direction of rotation .. clock wise or counter-clockwise.
Usual settings are 1 for clockwise, -1 for counter clockwiserotateLightsByAngle(angle=1)
Rotate all lights byt he given angle
angle (int) angle to rotate bycreateEnvLightPreference()
Adds ENV Light Rotation Settings to the PreferencessaveEnvLightPreference()
Saves the Setting of the ENV Light Rotation in the Preferencesmari.ExtensionPack.materialIngest()
Methods to deal with Material Ingestion from ImagesingestImageManagerImagesIntoLayer()
Ingests the currently selected image manager images into the active layeringestImageManagerImagesIntoNode(nodelist=None, imagelist=None)
Ingests the currently selected image manager images into the active node
By default this will use your selected node and selected images in the image manager.
However you can overwrite this via arguments
nodelist (list): List of mari.Nodes
imagelist (list): List of mari.ImageslaunchMaterialIngester()
A wrapper around the standard mari material ingester.
All it does is turn the ingester into a mari action to be able
to get its action.triggered() signaladdEPNodes_to_MaterialIngester()
Adds Extension Pack Nodes with Image Attributes to the list of compatible nodes in
the Mari Material IngesteraddEPPresets_to_MaterialIngester()
Adds Material Preset to the Material Template History DropdownextendMaterialIngestPresets()
Adds Unreal Advanced to MaterialIngest Presets
and extends aliases for material ingest presetsmari.ExtensionPack.matrix()
Matrix related methodsdecomposeMatrix(matrix)
Returns the Translation,Scale and Rotation Values from a given Matrix
matrix (mari.Matrix): a Mari Transform Matrix
Tuple: a tuple comprised of 3 sets of:
( Scale X, Scale Y, Scale Z)
( Angle X, Angle Y, Angle Z)
( Translation X, Translation Y, Translation Z)decomposeMatrixEulerAngles(matrix)
Returns the Rotation Values from a given Matrix
matrix (mari.Matrix): a Mari Transform Matrix
Tuple: a tuple of 3 values corresponding to X,Y and ZdecomposeMatrixScale(matrix)
Returns the Scale Values from a given Matrix
matrix (mari.Matrix): a Mari Transform Matrix
Tuple: a tuple of 3 values corresponding to X,Y and ZdecomposeMatrixTranslation(matrix)
Returns the Translation Values from a given Matrix
matrix (mari.Matrix): a Mari Transform Matrix
Tuple: a tuple of 3 values corresponding to X,Y and ZinvertMatrix(matrix)
Return the Inverse MatrixmatrixFromVectors(rotation=(0, 0, 0), translation=(0, 0, 0), scale=(1, 1, 1))
This method will be deprecated in a future version.
Use toScaleEulerAnglesTranslationMatrix() instead
Creates a 4x4 Matrix from given Vectors
rotation (List): A list of 3 values XYZ
translate (List): A list of 3 values XYZ
scale (List): A list of 3 values XYZ
Tuple: a list of 16 items that can be fed into a mari.MatrixobjectTransformToWorldSpaceMatrix(object_scale, object_angles, object_translation)
Convert Object Space XYZ Values for scale, angles and translation to World Space Matrix
world_angles (list): List of 3 floats, X, Y, Z, representing rotation in world space
world_translation (list): List of 3 floats, X, Y, Z, representing translation in world spacesetTransform(obj, transform_matrix, clock_frame=0)
This method is a stable workaround for mari's buggy
- geoEntity.setTransform(matrix, clockframe)
- locatorEntity.setTransform(matrix, clockframe)
methods. When using mari's native methods the object receives updated transforms however the next time
the user interacts with the Object outside of python via the "Transform Selected Object" Tools, the
Python changes are discarded.
The reason for this is that the setTransform() methods do not update metadata on the active object related
to the Viewport Gizmo:
The following Metadata exists:
LocatorScale
LocatorTranslation
LocatorRotation
Each one of those accepts a string version of a custom matrix, e.g. LocatorScale needs to be given a pure Scale
Matrix.
This method first runs a regular setTransform() with the provided transform_matrix, then handles the metadata.
obj (mari.geoEntity or locator): The Mari Geo or Locator to apply transforms to
transform_matrix (Matrix): The Full 4x4 Transformation Matrix to apply to the Object
clock_frame (int): Optional. Frame to apply Transform to. Defaults to 0toEulerAnglesMatrix(values)
Returns a Euler angle Matrix from given Scale X,Y,Z Values
values (tuple): a tuple (x,y,z)
mari.Matrix: A MatrixtoScaleEulerAnglesTranslationMatrix(scale, angles, translation)
Returns a 4x4 Transform Matrix
scale (tuple): a tuple (x,y,z) for scale values
angles (tuple): a tuple (x,y,z) for rotation values
translation (tuple): a tuple (x,y,z) for translation values
mari.Matrix: A MatrixtoScaleMatrix(values)
Returns a Scale Matrix from given Scale X,Y,Z Values
values (tuple): a tuple (x,y,z)
mari.Matrix: A MatrixtoTranslationMatrix(values)
Returns a Translation Matrix from given Scale X,Y,Z Values
values (tuple): a tuple (x,y,z)
mari.Matrix: A MatrixworldToObjectTransform(world_scale, world_angles, world_translation)
Convert Worldspace XYZ Values for scale, angles and translation to Object Space
world_angles (list): List of 3 floats, X, Y, Z, representing rotation in world space
world_translation (list): List of 3 floats, X, Y, Z, representing translation in world space
object_angles (list): List of 3 floats, X, Y, Z, representing rotation in object space
object_translation (list): List of 3 floats, X, Y, Z, representing translation in object spacemari.ExtensionPack.node()
Node methods contain all methods that make changes to a node or sample infochannelsNodeBelongsTo(node_to_find, geo, excludeChannelLayer=True)
Returns a Dictionary of Channels [UUID:CHANNEL]
that a given node belongs to
node_to_find (mari.Node): A Node (mari.Node) you want to determine which channel(s) are using it
geo (mari.geoEntity): Which Object in your scene you want to check for channels
excludeChannelLayer (bool): If true only Channels will be returned that use the node in their own channel stream
but not as part of a 'channel layer' stream
{dict}: Returns a Dictionary of Channels with key= ChannelUUID, value=ChannelObjectconnectNodeToLastNode(overwriteExistingConnections=False)
will connect the currently selected node to the previous selected node
Repeated execution of the command will cycle the connection through the
inputs of the currently selected node
overwriteExistingConnections (bool): Determines if the connection overwrites existing connections
from other nodes. If True, the previous node will replace
the existing node connection on a port, if false, it will
find the first empty input port to connect tocopyNodeConnections(nodeToCopyFrom, nodeToCopyTo, RemoveSourceNode=False)
Copies Input and Output Connections fromt the Source Node to the Target Node
nodeToCopyFrom (mari.Node): The source node from which to copy connections
nodeToCopyTo (mari.Node): The target node to which to copy connections
RemoveSourceNode (bool): If to remove the source Node after copying. Defaults to False
None:current(returnFirstSelectedNode=True)
Convenience method to get the current node selection.
Returns the first selected node or all selected nodes of the current nodegraph
returnFirstSelectedNode (bool): if True, only the first selected node is returned
(list): The list of selected Nodes if returnFirstSelectedNode is False
(mari.Node): The first selected Node if returnFirstSelectedNode is True and a Node is selected
None if no node is selected.disconnectAllInputConnections(nodelist=None)
Disconnects all node connections feeding into the given nodes.
If no nodes are specified in the argument, the selected nodes are used instead
nodelist (list): Optional. A List of Mari Nodes to run the command on.
Defaults to None. If None, the selected Nodes will be used insteaddisconnectAllOutputConnections(nodelist=None)
Disconnects all node connections feeding out of the given nodes.
If no nodes are specified in the argument, the selected nodes are used instead
nodelist (list): Optional. A List of Mari Nodes to run the command on.
Defaults to None. If None, the selected Nodes will be used insteadfindConnectedNodeOutput(graph, node_to_find, skipDots=False, SpecificOutput=None)
Returns the Nodes that are connected to the Output of the supplied Node
With Skip Dots turned on, the return will contain the node connected to a dotNode
if there is one inbetween
Please note as of Mari 4.5 there is additional standard Python API mari.node().outputNodes()
that may be better suited for the task in some cases
graph (mari.nodeGraph): The Graph to search in
node_to_find (mari.Node): The node you want to check for, which other nodes are connected to
its output(s)
skipDots (bool): If to ignore dot nodes as output and proceed to next node
specificOutput (string): If to check a Specific Output Port Name of node_to_find
(list): A list of pairs ([mari.Node,Output Port Node is connected to on node_to_find)getAllNodesConnectedToNode(targetNode, nodeGraph, GroupContentMode='Include Group Node Contents', returnBakePointUpstream=True, includeTargetNode=True, GraphGroup_TraverseConnectedOutputOnly=False, MainGraph_TraverseStreamOnly=False, IncludeGraphGroupNode=False, IncludeMaterials=False, StartStream=None)
Given a Target Node (and the nodeGraph it lives in) this will return all Nodes
that are connected to the targetNode + optionally targetNode again as well.
targetNode (mari.Node): The Node you want to find all connected nodes for
nodeGraph (mari.nodeGraph): The Nodegraph the targetNode lives in
GroupContentMode (str): If "Include Group Node Contents" all Nodes inside of Graph Groups will be returned as well.
Otherwise just the nodes fromt he target Node Nodegaph will be returned
returnBakePointUpstream (bool): If "False" nodes upstream from bake points will only be returned if the bake point
is disabled or does not useBake(). If "True" all nodes upstream of Bakepoints will be returned
includeTargetNode (bool): If "True" the given targetNode will be includes in the returned list
GraphGroup_TraverseConnectedOutputOnly (bool): If 'True' and GroupContentMode = Inlcude Group Node Content,
only group content will be evaluated that is connected to an output that
is part of the topological sorting of the main input node given to the function
MainGraph_TraverseStreamOnly (bool): If 'True' the given Nodegraph will only return upstream nodes that are part of the
specified StartStream. The StartStream will only be evaluated from the first MultiChannel
Node onwards, before that all upstream nodes are included
IncludeGraphGroupNode (bool): If True Graph Group Nodes are included in the returned Node List. Otherwise only the
CONTENTS of the Graph Group Nodes are returned (given that groupContentMode is set to
'Include Group Node Contents')
If IncludeGraphGroupNode is False and includeMaterials is True, normal GraphGroups
are not returned while material multiChannels nodes are returned.
IncludeMaterials (bool): If True Material MultiChannelNodes are included. This will include Materials even if
IncludeGraphGroupNode is off
StartStram (string or None): Optionally, you can provide a stream name to evaluate along. You should have
GraphGroup_TraverseConnectedOutputOnly turned on for this
(list): A list of nodes (mari.Node)getAllNodesDownstream(targetNode, includeTargetNode=False, traverse_groups=True)
Returns a list of all nodes connected to the given targetNode downstream (to the right)
includeTargetNode (bool): Optional. Defaults to False
If True, the given Target Node will be part of the
returned list
traverse_groups (bool): Optional. Defaults to True.
If True, the connections are tracked even if it exits
a subgraph meaning that if you give it a node inside
a group as targetNode, you will even get connected nodes
outsisde that groupnode
(list): Returns a list of mari.NodesgetMaterialStreamNamesConnectedToChannels(node)
Returns a list of Material Stream Names the given (multi channel)node is connected to via
channel nodes.
E.g. if a Material's Streams "Base" and "Rgh" are connected to channel nodes (e.g. DIF
and Roughness), and all other material outputs are not connected to channels, the returned
list will be ["Base", "Rgh']
node (mari.Node): The Node to test for a stream
(list): List of stream names
TypeError: Raised if the given node is not a MultiChannel NodegetNodeCategory(node)
Returns the Node Category of a Node, as it is listed in the UI
node: A Node Object (mari.Node)
(string): Returns the Node Category as a StringgetNodeMaterialStreamName(graph, inputNode)
If the given inputNode is part of a node stream that has multiChannel Nodes,
this method will return the Material Stream Name this Node is part of. E.g. 'Base Color', 'Metallic' etc.
This can the be used in other methods to filter nodestreams based on stream name e.g. in
mari.ExtensionPack.nodegraph.getNodesonStream()
graph (mari.NodeGraph): The Graph the inputNode belongs to
inputNode (mari.Node): The Node to test for a stream name
(bool): Returns True if the Node is part of a Material Stream, False if not
(string): Returns the Stream Name if Node os part of a Material Stream, 'None' (as string) if notgetNodePosition(graph, node)
Returns the Node Position as a list and a string
graph: The nodegraph the node belongs to (mari.NodeGraph)
node: A Node Object (mari.Node)
(list): Returns a list with the coordinates [x,y]getNodePrettyName(node)
Returns the pretty Name of a Node, as it is listed in the UI
node: A Node Object (mari.Node)
(string): Returns a StringinputNode(node, nodeport)
A wrapper method around mari.node.inputNode() to deal with differences
between mari versions.
The method will return pairs of [inputNode,outputPortOnInputNode] for mari 4.5
and above and [inputNode,''] for versions below mari 4.5
node: The node to check for connections on (mari.Node)
port: The Input Port Name to check for connections (string)
(list): Returns a list with the pair [inputNode, outputPortOnInputNode]moveNodesToPosition(graph, nodes, positionList)
Moves Nodes to a specific position
graph: The nodegraph the node belongs to (mari.NodeGraph)
nodes: A list of mari nodes
positionList: A list of coordinates [x,y]
(list): Returns a list of mari.NodesnodeName(node)
Wrapper for differences in node name functions between Mari 4.x and Mari 4.8
node (mari.Node): The Node to get the name from
(string): The Node namereloadSelected_PaintAndImages(silent=False)
Reload Paint and Images will work on the current Nodegraph's Node Selection. It will
a) reload Paint Nodes with Images according the the per-Image-in-Imageset Path
b) reload any image manager nodes used in selected nodes
c) re-export and reload Bake Point Image Data
silent (bool): if silent is True, no message boxes will appear asking to confirm. Defaults is FalsesaveNodeAttributes(selectedNode)
Save the given Nodes Node Attributes to a File
Similar to what is in the Nodepgraph Class, but this one can use a given node instead of a selection
selectedNode (mari.Node): A Mari NodesetInputNode(node, portname, NodeToConnect, OutputPortName='')
A wrapper method around mari.node.setInputNode() to deal with differences between mari versions.
The method allows the same code for both Mari 4.5+ and below
On mari 4.5+ this supports multiOutput Nodes, below it doesn't so the OutputPortName is ignored then.
node: The node to connect something to (mari.Node)
portname: The Input Port Name to connect something to (string)
NodeToConnect: The Node to Connect to the Port
OutputPortName: The OutputPort of the NodetoConnect to connect to
None:setNodeAttributes(selectedNode)
Apply a saved set of Node Attributes the given Node
Similar to what is in the Nodepgraph Class, but this one can use a given node instead of a selection
selectedNode (mari.Node): A Mari NodesetNodeName(node, newName)
Wrapper for differences in node name functions between Mari 4.x and Mari 4.8
node (mari.Node): The Node to set a new name on
newName (string): The new Node name
None:smartRenameNode(graph, node)
Smart rename Nodes. Renames node based on upstream connection
graph (mari.Nodegraph): A mari Nodegraph obkect
node (mari.Node): Node to renamemari.ExtensionPack.nodeLayout()
Nodegraph Node Layout and Distribution MethodsalignNodes_HorizontallyBottom(nodelist=[], defaultToSelection=True, streamBased=True, preventAnimation=False)
Align nodes horizontally Bottom
Requires Mari 4.7 or higher
nodelist (list): A list of Mari Nodes. If not provided defaults to selected nodes
defaultToSelection (bool): If true and nodelist is empty, the graph selection will be used
streamBased (bool): If true (default), nodes will be aligned based on their node streams.
This means nodes of a stream will align to the bottom position of the node
with the highest Y coordinate in your selection, that shares the same neighbouring nodes.
preventAnimation (bool): If true, nodes will directly jump to a position instead of having animated movement
None:alignNodes_HorizontallyTop(nodelist=[], defaultToSelection=True, streamBased=True, preventAnimation=False)
Align nodes horizontally top
Requires Mari 4.7 or higher
nodelist (list): A list of Mari Nodes. If not provided defaults to selected nodes
defaultToSelection (bool): If true and nodelist is empty, the graph selection will be used
streamBased (bool): If true (default), nodes will be aligned based on their node streams.
This means nodes of a stream will align to the top position of the node
with the highest Y coordinate in your selection, that shares the same neighbouring nodes.
preventAnimation (bool): If true, nodes will directly jump to a position instead of having animated movement
None:alignNodes_VerticallyLeft(nodelist=[], defaultToSelection=True, preventAnimation=False)
Align nodes vertically left
Requires Mari 4.7 or higher
nodelist (list): A list of Mari Nodes. If not provided defaults to selected nodes
defaultToSelection (bool): If true and nodelist is empty, the graph selection will be used
preventAnimation (bool): If true, nodes will directly jump to a position instead of having animated movement
None:alignNodes_VerticallyRight(nodelist=[], defaultToSelection=True, preventAnimation=False)
Align nodes vertically right
Requires Mari 4.7 or higher
nodelist (list): A list of Mari Nodes. If not provided defaults to selected nodes
defaultToSelection (bool): If true and nodelist is empty, the graph selection will be used
preventAnimation (bool): If true, nodes will directly jump to a position instead of having animated movement
None:distributeBetweenNodes_Horizontally(nodelist)
Given a list of nodes, the method will determine the farthest left and right node position
and distribute the other nodes of the list inbetween evenly
nodelist (list): A List of Mari NodesdistributeBetweenNodes_Vertically(nodelist)
Given a list of nodes, the method will determine the highest and lowest node position
and distribute the other nodes of the list inbetween evenly
nodelist (list): A List of Mari NodesdistributeBetweenSelectedNodes_Horizontally()
Using the list of curently selected nodes, the method will determine the farthest left and right node position
and distribute the other nodes of the list inbetween evenlydistributeBetweenSelectedNodes_Vertically()
Using the list of curently selected nodes, the method will determine the highest and lowest node position
and distribute the other nodes of the list inbetween evenlydistributeNodesHorizontally(nodelist=None, specificXDistance=1, backdropOffsetLimit=True)
Distribute Nodes horizontally with a given Distance between Nodes starting from the first node on the left
nodelist (list): A List of Mari Nodes. If 'None' is handed in, it uses the current selection
specificXDistance (float/int): The distance between nodes
backDropOffsetLimit (bool): when true, nodes will now be allowed to go outside of their parent backdrop
(bool): Returns if the node distance was artificially constrained by the backdropOffsetLimitdistributeNodesVertically(nodelist=None, specificYDistance=1, backdropOffsetLimit=True)
Distribute Nodes vertically with a given Distance between Nodes starting from the first node at the top
nodelist (list): A List of Mari Nodes. If 'None' is handed in, it uses the current selection
specificYDistance (float/int): The distance between nodes
backDropOffsetLimit (bool): when true, nodes will now be allowed to go outside of their parent backdrop
(bool): Returns true if the node distance was artificially constrained by the backdropOffsetLimitlayoutNodes(graph=None, nodelist=[])
This method is a modification of Mari's own nodegraph.autoLayoutNodes() method.
It works either with the given arguments or without them, in which case
the currently open Nodegraph and its selected nodes are used.
When a single node is selected and layoutNodes is called, Mari's own
autoLayoutNodes() is called with the selected Node as its root.
If multiple nodes are selected only the selected nodes will be laid out,
which is the main difference to mari's autoLayout, which always lays out the
entire connected stream
graph (mari.Nodegraph): Optional argument to give a parent nodegraph. Defaults to None
nodelist (list of mari.Nodes): Optional argument to give a list of nodes to operate on.
If the nodelist is empty but the graph argument is not None,
the selected nodes in the given graph are used.
If the list is not empty, the given nodes need to be part of
the given graph given as argument.
If both graph and nodelist args are not given, the method will always
run on the currently open graph and its selected nodesdistributeNodeUI()
Opens a UI to distribute ndoesmari.ExtensionPack.nodeNavigation()
Methods to jump from and to nodescycleBookmarkNodesBackwards()
Cycle backwards through the available node graph bookmark nodes in the current graphcycleBookmarkNodesForward()
Cycle forward through the available node graph bookmark nodes in the current graphjumpToNextInStream(typeIDToFind='MRI_Misc_Channel_Input', customSearch=None)
jump to the next downstream node (based on current node selection) that matches
either the typeIDtoFind or a special customSearch parameter.
If a customSearch is defined, this supercedes the typeIDtoFind
typeIDToFind (string): A Type ID to find (node.typeID())
customSearch (string): If a custom search is defined,this supercedes any typeIDToFind.
Possible custom searches are:
"paint","bakePoint","geoChannel","groupNode","channelNode","shader","material"jumpToNextSimilarInStream()
jump to the next downstream node in the stream that is matching
the current noe selection typejumpToNodeInput()
Jumps to the connected Node of the currently selected node input
If a node has multiple inputs a dialog will showjumpToNodeOutput()
Jumps to the connected Node of the currently selected node output
If multiple Nodes are connected to the Output a dialog will showjumpToPreviousInStream(typeIDToFind='MRI_Misc_Channel_Input', customSearch=None)
jump to the next upstream node (based on current node selection) that matches
either the typeIDtoFind or a special customSearch parameter.
If a customSearch is defined, this supercedes the typeIDtoFind
typeIDToFind (string): A Type ID to find (node.typeID())
customSearch (string): If a custom search is defined,this supercedes any typeIDToFind.
Possible custom searches are:
"paint","bakePoint","geoChannel","groupNode","channelNode","shader","material"jumpToPreviousSimilarInStream()
jump to the next upstream node in the stream that is matching
the current noe selection typejumpViewToRadioNodeConnection()
Focuses your Nodegraph on connected Nodes from the currently selected Radio Node or
Radio Transmitter Node. This method is also available inside the main radioNodes() calssjumpToBookmark()
Launches the "Jump to Bookmark" UImari.ExtensionPack.nodeProperties()
Node Properties methods to handle single click node properties viewingclearNodePropertiesOnSingleClick_Connections()
removes all connections previously made to enable single click node propertiesgetPauseNodePropertiesState()
Returns true if the Auto Property Loading on single selection has been paused
bool: True if the Auto Loadin of Node Properties on selection
has been pausedinitializeNodePropertiesOnSingleClick()
a method called on Mari Project startup to create signal connections for one-click
node properties changing.
The method will connect to all Nodegraphs in the Project.
Only has an effect if Preference /Node Graph/Node Properties/SingleClickPropertiesLoading
is TrueinitializeNodePropertiesOnSingleClick_onSpecificGeo()
Generates a signal connection from nodegraph.nodeSelectionChanged()
to updateNodePropertiesOnSelection() for a newly added Geometry
Only has an effect if Preference /Node Graph/Node Properties/SingleClickPropertiesLoading
is TruepauseNodePropertiesUpdate(mode=False)
Pauses or unpauses the automatic loading of Node Properties
on single click on a node.
This only has an effect if in the Mari preferences / Nodegraph Tab
the Node Properties on Single Click Pref is checked
mode (bool): If True, the automatic updating of Node Properties is paused.
Defaults to False.updateNodePropertiesOnSelection(force=False, forceOpenPalette=False)
Updates the Node Properties based on the current node selection.
This method is usually called by the nodegraph.nodeSelectionChanged() signal.
force (bool): if true, the node properties get updated even if they are paused via the api.
If the Node Properties Palette is hidden, nothing happens
forceOpenPalette (bool): if true, the node properties palette gets forced openaddNodePropertiesPreference()
Adds a Preference to Mari Preferences / Nodegraph Tab
to change the open Behavior of Node Properties from double click
to single clickloadNodePropertiesPreference()
Loads a Preference from Mari Preferences / Nodegraph Tab
to change the open Behavior of Node Properties from double click
to single clicksaveNodePropertiesPreference()
Saves a Preference from Mari Preferences / Nodegraph Tab
to change the open Behavior of Node Properties from double click
to single clickmari.ExtensionPack.nodeStyle()
Methods related to look and style of NodesrevertNodeStyle(inputNodeList)
Reverts a previously modifed Node Style back to Mari default
inputNodeList (if of mari.Node): The Nodes to revertsetNodeStyle(inputNodeList, setColor=True, setShape=False, setPixmap=False, topColor='1.0,0.0,0.0,1', bottomColor='1.0,0.0,0.0,1', NodeShape=3, pixMapPath='')
Allows you to change the style of a Node, e.g. the color, shape and pixmap icon.
The method works by writing a new node instance and removing the old one.
Certain Node Types are not supported such as Paint Nodes and Bake Point Nodes.
inputNodeList(list of mari.Node): The Nodes to change the Style on
setColor(bool): Boolean to define if to change the color
setShape(bool): Boolean to define if to change the shape
setPixmap(bool): Boolean to define if to change the icon
topColor (string): If setColor is True, this defines the top color of the node.
Colors are set in 0-1 range per channel e.g. "1.0,0.0,0.0,1.0"
bottomColor (string): If setColor is True, this defines the bottom color of the node.
Colors are set in 0-1 range per channel e.g. "1.0,0.0,0.0,1.0"
nodeShape(int): if setShape arg is True, this defines the shape of the node.
At the time of writing this Mari supported 8 shape types.
Therefore valid integers are 0-7 (again at the time of documenting this)
pixMapPath(string): A path to an icon file (png or svg) if setPixmap is TrueshowNodeStyles()
Direct action to launch the Nodestyle UI Hotboxmari.ExtensionPack.nodeUtilities()
Node Utility methodsautoDotInputConnections(graph=None, nodelist=None)
Creates dot nodes automatically for the input ports of the selected nodes.
Several rules determine if or where the dot nodes are placed
graph (mari.Nodegraph) (optional): The Mari Nodegraph to process auto-dot nodes in.
Defaults to None, in which case the currently open Graph
is used.
nodelist (list of mari.Nodes) (optional): A list of mari nodes to process Inputs for Auto-dots.
Defaults to None in which case the selected nodes of the
current graph are used.
If a list is supplied, a graph also needs to be supplied with
the graph argument.createMaskFromSelection()
Creates a Black and White Mask from the current viewport selection as a Paint Node.
The Resolution can be set in a popup dialog.
The new paint node will be created in the currently active graph tab and created at cursor positioncreateSmartCompareMask()
Creates a AB Compare Mask node and hooks it up to the selectioncreateSmartHeightBlend()
Creates a Height Blend node and hooks it up to the selectioncreateSmartMergeNode()
Creates a Multi Channel Merge Node if the selected Nodes contain Materials
or a regular Merge Node otherwisecreateStickyNoteWithNodeChanges(graph=None, nodelist=None)
Creates a sticky Note and adds all non-default values from a node
to it, then places the sticky note under the source node.
Repeatedly executing it on a node that already has a sticky note,
will update the existing sticky note.
If no changes are made in a node, existing sticky notes will be deleted.
While you can supply a nodelist as an argument, if just executed by default,
it will use the current node selection in the currently open graph tab.
graph (mari.Nodegraph): Optional. The graph the nodes in the nodelist belong to.
if None which is the default, the currently open graph is used
nodelist (list of mari.Nodes): Optional. A list of nodes. If None (default), the currently
selected nodes in the graph (other arg) are used.deregisterNodeContextMenu(nodeTypeID)
Removes a Node Context Menu from a specific Node Type
Node Context Menus appear when a node is selected and CTRL is pressed.
nodeTypeID (str): a valid Mari Node typeID, class name or tagname that should
have its context menu removed.
bool: Returns True if the nodeTypeID was deregistered.
Returns False if the nodeTypeID didn't existdisableBlendColorspaceOnNode(node)
Ensures that the given node (regardless if merge node or multi channel) has its Blend Mode Colorspace
disabled
node (mari.Node): the node to modify the setting ongetRegisteredNodeContextMenus()
Returns a dictionary containing {NodeTypeID : [Path to Context Menu, class instance}.
Node Context Menus appear when a node is selected and CTRL is pressed.
dict: A dictionary of registered Node Context Menus against
node.typeIDs, classes or tagsoptimizeMultiChannelNodes(nodelist=None)
Disconnects or reconnects MultiChannel Node Connections based on assigned channels to a shader.
With any node upstream from a shader selected, the tool will detect the shader, then check what ports
a channel is assigned to.
Any port that has no channel assigned will be added to an exclusion list, any port with a channel node
to an inclusion list.
Multi Channel Nodes (Materials, Multi Channel Merge, Multi Channel Bake Points) of the same shader model
as the shader will then be processed and have any connection severed that is on the exclusion list, while
any non-existent connection that is part of the inclusion list will be rebuild
nodelist (list of mari.Node): Optional. A list of shader nodes to use as base for optimization.
If not provided, the currently selected shader will be usedregisterNodeContextMenu(target, contextMenuPath, classInstance=None)
Registers a Node Context Menu to a specific Node Type
Node Context Menus appear when a node is selected and CTRL is pressed.
For detailed step by step help please consult the online help at
https://www.mariextensionpack.org/docs/6R3v1/CreatingyourownContextMenus.html
target (str):
The target is usually a Mari Node typeID, which can be retrieved using node.typeID().
There are however several special cases that can be used to target specific Nodes:
Targeting Classes:
If you are supplying a classInstance Argument the given target arg should be a
stringified version of the class name e.g. "mari.MultiChannelBakePointNode".
Targeting Tags:
Some Mari nodes cannot be identified via ids or class.
You can try and identify them using tags. Currently the following tags are supported
which should be given as such into the target argument:
"_shader" , "_material", "_group", "_channel", "_bakepoint", "_multiChannelMerge"
Targeting TypeIDs via Startswith:
Node Type IDs can also be identified by a matching "startswith".
For example "MRI_" as a type argument would catch ANY Mari Node with a type ID
"MRI_Something"
Targeting Metadata:
Sometimes it may be necessary to target nodes via their Metadata, for example if you
wish to add context menus to specific material templates.
To do so prefix the Metadata Name with a "$" and pass it as a target.
E.g. "$EP_MaterialTemplate" would target any node with the EP_MaterialTemplate Metadata.
The Metadata test runs before any other test so it would supercede for example any
context menu assignment done via the _material tag.
Targeting Metadata Dictionary Entries:
A special case of Node Metadata are Dictionaries. You can compare directly a dictionary
value by giving the something like the following into the target argument:
"$EP_MaterialTemplate{key:value}". This will spawn the Context menu only if:
- The node has the Metadata "EP_MaterialTemplate"
- The Value of the Metadata is a dictionary with one key/value pair being
"key" and "value" (only strings are supported.
contextMenuPath (str):
A path to a directory containing a Ext.Pack Hotbox. Use TIE_TO_NODEGRAPH_ZOOM setting
to let the hotbox scale up and down dynamically based on zoom level.
classInstance (mari.Class)
Some Mari nodes do not have a clear type ID.
An example of this is a multi Channel Bake Point which is just a mari.groupNode().
To still reliably access them specificially, you can provide a class instance to
compare against.
It is necessary in this case to set the target argument to a "stringified" version of
the class e.g."mari.MultiChannelBakePoint" to keep consistency.||.
If the target starts with "mari." we will automatically assume that you wish
to compare against a Class instance.removeAllStickyNotesWithNodeChanges(graph=None)
Removes all automatically generated sticky notes, containing
information about what node value has changed
graph (mari.Nodegraph): Optional.The graph to search for these kind of
Sticky Notes. If None (default), the currently open
graph will be searchedreplaceMergeNodesWithBlendNodes(useSelection=False, ignoreColorSpaceBlend=False, ignoreSwizzle=False, ignoreAdvnacedBlend=False, surpressPopup=False)
This method replaces Merge Nodes with corresponding Extension Pack
Blend Mode Nodes.
Blend Mode Nodes will be swapped in, matching the set Blend Mode on
the Merge Node to Replace.
Opacity Settings, input and output connections will be transferred.
If the node to replace is a MergeNoAlpha Node, the "Keep Alpha" Option
inside the BlendMode Node will be activated.
As BlendMode Nodes have less options than Merge Nodes, some arguments are
available to determine when to leave a Merge Node in place and not replace it
A UI version of this method is available under __epGUI__.replaceMergeNodesWithBlendNodesUI()
useSelection (bool): if true, only merge nodes within the current
nodegraph selection will be replaced.
If false (default), all Merge Nodes within
the current Nodegraph Tab will be checked if they
can be replaced.
ignoreColorSpaceBlend (bool): if true, the "Use Blending Color Space"
dropdown in Merge Nodes will be ignored when
checking if a Merge Node can be replaced.
By default (if False), Merge Nodes will only be replaced
if "Use Blending Color Space" is set to "Disabled"
ignoreSwizzle (bool): if true, the "Swizzle" Otpions
in Merge Nodes will be ignored when
checking if a Merge Node can be replaced.
By default (if False), Merge Nodes will only be replaced
if the Swizzle options are set to default values.
ignoreAdvnacedBlend (bool): if true, the "Advanced Blend Mode" Otpions
in Merge Nodes will be ignored when
checking if a Merge Node can be replaced.
By default (if False), Merge Nodes will only be replaced
if the Advanced Blend Mode Setting is either Disabled or
the "Blendif" and "BlendIfBelow" settings are at default settings.
surpressPopup (bool): By default Extension Pack will give a report window
with information how many merge nodes were replaced and
which ones couldn't be replaced.
Use this argument to surpress this popup.setMergeNodeColorSpaceToDisabled(node)
This method is deprecated and will be removed in a later version.
Use SetMergeNodeColorspace() Option instead.
Sets the currently selected merge node "Color Space Enabled"
Setting to Disabled
node (mari.Node): the merge node to modify the setting onsetMergeNodeColorspace(node, setTo='Disable')
Set Merge Nodes ColorSpaceEnabled option
node (mari.Node): the merge node to modify the setting on
setTo (string): The setting to set the dropdown to.
The names here correspond with the available
Settings in the Merge Node Color Space Enabled
DropdownreplaceMergeNodesWithBlendNodesUI()
Opens a dialog to allow you to replace Merge Nodes with Blend Mode NodesaddNodeSlidePreference()
Adds a preference in the Nodegraph Tab to activate and deactive the Node SLide Widget
that shows when pressing and holding CTRL+SHIFTautoUpdateBakeLookupOnExistingNodes()
Builds a signal connection (for any node in your project)
for nodes that have an inputPort 'BakedData'
on shader recompilation the nodes Image Attribute
gets autopopulated with the UDIM 1001 of an attached
BP NodegetNodeGraphEventFilter()
Returns a Event Filter on the QGraphicsView that is the Nodegraph
self.ctrl_pressed (bool) - returns if CTRL is Pressed
self.shift_pressed (bool) - returns if SHIFT is Pressed
self.alt_pressed (bool) - returns if ALT is Pressed
self.set_ctrl_pressed (bool) - Allows setting the state of CTRL pressed
self.set_shift_pressed (bool) - Allows setting the state of SHIFT pressed
self.set_alt_pressed (bool) - Allows setting the state of ALT pressed
self.graph (QGraphicsView) - The Graphics View of the Nodegraph
self.cursor_position (QPos) - The Position of a click event
CTRL_key(bool) (SIGNAL) - Emits if CTRL Key is Pressed/Released
SHIFT_key(bool) (SIGNAL) - Emits if SHIFT Key is Pressed/Released
ALT_key(bool) (SIGNAL) - Emits if ALT Key is Pressed/Released
resized(QSize) (SIGNAL) - Emitted if the Nodegraph is being resized.installNodeGraphEventFilter()
Installs a Event Filter on the QGraphicsView that is the NodegraphlockBackdropColorsInProject()
This method gets called on project launch and locks the backdrop colors so they don't get randomized by mistakenodeChangesToStickyNoteConnections(stickynote)
Utility method that gets called when a project is opened
It rebuilds the given stick notes connection to its source node
stickynote (mari.Node): A sticky nodenodeCreatedConnect()
Builds Signal connect to mari.nodes.nodeCreated collecting all method executions when this is callednodeCreatedDisconnect()
Kills Signal connect to mari.nodes.nodeCreated collecting all method executions when this is calledpauseNodeCreatedProcessing(pause)
Pauses and unpauses Extension Pack's processing of Nodes
that happen on the mari.nodes.nodeCreated Signal.
Useful if you need to temporarily pause everything without
disconnecting
pause (bool): True to Pause processing, False to restart itreceiverCreated(node)
checks if a brodcast node was selected when a receiver node was created.
If a broacast node was the previous node selection, the broadcast nodes
channel Name gets set on the receiver
node (mari.Node): a receiver noderegisterEPNodeContextMenus()
Registers the standard Extension Pack Node Context Menus
Node context menus can be brought up by selecting a supported Node type
and pressing CTRL+SPACE.
Some examples of supported nodes are:
- Tiled
- Multi Channel Merge
- Bake Points and Multi Channel Bake Points
and many moresaveNodeSlidePreference()
Saves a preference in the Nodegraph Tab to activate and deactive the Node SLide Widget
that shows when pressing and holding CTRL+SHIFTsetAllowNodeGraphEventFilterInstall(state)
Set if the Nodegraph Event Filter is allowed to be installed or reinstalledsetDynamicNodeGraphTabManager()
Creates a signal connection to mari.geo.entityMadeCurrent
to dynamically open and close Nodegraph Tabs that do not belong
to the current object.
If the Object is reselected, the last open NG Tabs are restoredsetMergeNodeColorspace_PreferenceChanged(saveSetting=True)
This method is deprecated and will be removed in a later version.
Part of a system to automatically turn of "Color Space Enabled"
on newly created Merge Nodes in the Nodegraph.
This method is used to update signal connects when the preference
"Set Color Space Enabled" is changed by the user
saveSetting (bool): if true the setting gets instantly saved to the mari configsetMergeNodeColorspace_createPreference()
This method is deprecated and will be removed in a later version.
Part of a system to automatically turn of "Color Space Enabled"
on newly created Merge Nodes in the Nodegraph.
This method is used to create a preference
"Set Color Space Enabled" int he Nodegraph section of the Mari Preferencesmari.ExtensionPack.nodegraph()
Nodegraph methods contain all methods that add or change the nodegraph or run over entire graphsclearNodegraph(currentGeoOnly=True)
CAREFUL ! Deletes all nodes, without prior warning
currentGeoOnly (bool): if true ony the current geo will be evaluatedcopyNodeAttributes(node=None)
Save the currently selected Node Attributes to a File.
Also exists as mari.ExtensionPack.node.saveNodeAttributes()
If no node is provided (None, default), the current Node selection is used.createNodeAtPosition(graph, nodeString, positionList)
Creates a new node at a specific position
graph: The nodegraph the node belongs to (mari.NodeGraph)
nodesString: A standard mari node string (same as mari.Nodegraph.createNode() )
positionList: A list of coordinates [x,y]
(mari.Node): Returns a mari.NodecreateNodeDuplicateAtPosition(graph, nodes, PositionList, removeOriginalNode=False)
Create duplicates of given nodes at a position
graph: The nodegraph the node belongs to (mari.NodeGraph)
nodes: A list of Node Objects (list(mari.Node))
offsetList: A list of offset coordinates [x,y]
removeOrigNodes: If True the original nodes are removed
(list): Returns a list of nodescreateNodeDuplicateWithOffset(graph, nodes, offsetList, removeOriginalNode=False)
Create duplicates of given nodes with a position offset
graph: The nodegraph the node belongs to (mari.NodeGraph)
nodes: A list of Node Objects (list(mari.Node))
offsetList: A list of offset coordinates [x,y]
removeOrigNodes: If True the original nodes are removed
(list): Returns a list of nodescurrent()
this is a method to find the active nodegraph based on the open tab.
mari.Nodegraph: The currently active and open Mari NodegraphduplicateNodesWithConnections(offsetX=50, offsetY=50)
Duplicate selected Nodes while maintaining their connections
offsetX: Specifies the offset of the duplicated nodes from their original position
offsetY: Specifies the offset of the duplicated nodes from their original position
(list): a list of duplicated mari.Nodesduplicate_nodeNetwork(geo, inputNode, inputNodeNodeGraph, StopAfterRadioNodes=True, RenameChannelIncremental=True, RenameChannel=False, newChannelName='Renamed Channel', offsetX=50, offsetY=50)
Duplicatas a Node Network such as a channel while cleanign up and rebuilding shared connections in the graph
Please be aware the same method exists in the mari.ExtensionPack.channel() Class
geo (mari.geoEntity): Geo, inputNode lives on
inputNode (mari.Node): The node which to use as a base to duplicate the network
(upstream connections). Should be a channel node but doesn't have
to be
inputNodeNodeGraph (mari.Nodegraph): The Nodegraph the input Node belongs to
:StopAfterRadioNodes (bool): If true (default value) connections upstream of a radio node will
not be duplicated and the original Radio Node Connection is
maintained if the first node upstream of a radio has connections
to other channels.
RenameChannelIncremental (bool): If true (default value) and the inputNode is a Channel, the
resulting duplicated channel will be renamed incrementally (1,2,3 etc.)
RenameChannel (bool): If RenameChannelIncremental=False and RenameChannel=True, and the inputNode
is a channel, the resulting duplicate channel will be renamed with the name
specified under newChannelName
newChannelName (string): if RenameChannel=True and the inputNode is a channel, the resulting
duplicate Channel will be renamed with this name
offsetX,offsetY (int): The offsetX and offsetY specify the offset of the duplicated nodes
from their original nodegraph position
(mari.Node): Returns the new Node with intact connectionsgetAllNodesInProject(classFilter=None)
Returns a list of all nodes across all geos in your project
classFilter (class): Optional Class to filter for. Defaults to None.
To filter for backdropNodeClass for example use
mari.BackdropNode
NodeList (list)getAllNodesOnGeo(geo, classFilter=None)
Returns all nodes for the given geo
geo (mari.Geo) geo to return nodes for
classFilter (class): Optional Class to filter for. Defaults to None.
To filter for backdropNodeClass for example use
mari.BackdropNode
NodeList (list): list of nodesgetNodesonStream(targetNode, includeGroupNode=True, stream='None')
Returns a filtered topological sorting to the target node, however with only
nodes that are part of the specified stream
targetNode (mari.Node): The target Node of the Stream
includeGroupNode (bool): If to include any GroupNodes in the return. Defaults to True
stream (string): The Stream Name to check for
(list): Returns list of Mari NodesgetUpstreamNodes(graph, destination_node)
A wrapper method for mari.Nodegraph.getUpstreamNodes() (which didn't used to work so well)
graph (mari.Nodegraph): The Graph to check against
destination_node (mari.Node): The Target Node
(list): A list comprised of mari.Node ObjectslastCreatedNode()
returns the last created node
(mari.Node): the last created Node. This might be a node created by Mari internally
as this does not differentiate between user created nodes and mari created nodesrecursiveGroupNodeList(node_list)
Returns all Group Nodes including Groups in Groups based on initial list provided
For example given a nodelist you will get all Group Nodes inside this Nodelist
including all Group Nodes inside of Group Nodes
node_list (list): A list of nodes (mari.Node)recursiveNodeList(node_list)
Returns all Nodes including Group Contents based on initial list provided
For example if you give a nodelist containing a group node, the return
will include all nodes from the initial nodelist plus all nodes from within the group
node_list (list): A list containing mari.Node objects
(list): A list containing mari.Node objectsrepeatLastNodeCreation()
repeats the creation of the last node at the current cursor positionsetNodeAttributes(nodelist=None)
Set the currently selected Node Attributes from a Clipboard File
Also exists as mari.ExtensionPack.node.setNodeAttributes()
nodelist (list): If a nodelist is provided the clipboard is applied to those nodes
If no nodelist is provided (None, default), the current Node selection is used.smartRenameNodes()
Smart rename selected Nodes based on a some given rules
A method running based on a node argument is available in the nodes() classviewerNode(graph=None)
Returns the Viewer node of a Graph
This is a replacement for Mari's own nodeGraph.viewerNode()
method that only works in Root Nodegraphs (Mari 6).
graph (mari.nodeGraph): (Optional) A Mari Nodegraph objet to check for a viewer.
If None or not provided, the currently open Nodegraph will
be used
mari.Node: The Viewer Node if found or NoneimportNodes()
Launches the Import Nodes dialog.
This is a wrapper for mari's own Import Nodes.
This version of it prevents certain Extension Pack
Node Actions such as Randomizing of Backdrop Colors to take
effect.nodeMetaDataEditor(Force=False)
A editor to edit and compare node metadata
Force (bool): By default the Node Editor can only work with Group Nodes, Materials
Custom Procedurals and a small set of other Nodes such as
Item List Nodes. If you launch the dialog in Forced Mode (True)
the Dialog will open for any selected Node, showing the Node Metadata.
Please note that Force Mode is experimental. There is no guarantee that
that editing functionalities will work with non-supported Nodes.rampEditor()
A editor to edit data as ramps.
Works with curve nodes such as Brightness Lookups, Color Lookups, RGBA Lookup and Gradient Map X8renameNodesUI()
Launch the "Multi Rename Nodes" Tool UIswapNodeType()
Allows you to swap out any node type for another node type.
If possible, settings are transfered between nodesmari.ExtensionPack.nodegraphGrid()
Controls for the Nodegraph Background GriddecreaseGridHeight()
Decrease the Height of grid cells in the NodegraphdecreaseGridLineOpacity()
Decrease the Opacity of Grid Lines in the NodegraphdecreaseGridLineWidth()
Decrease the Width of Grid Lines in the NodegraphdecreaseGridWidth()
Decrease the Width of grid cells in the NodegraphincreaseGridHeight()
Increases the Height of grid cells in the NodegraphincreaseGridLineOpacity()
Increase the Opacity of Grid Lines in the NodegraphincreaseGridLineWidth()
Increase the Width of Grid Lines in the NodegraphincreaseGridWidth()
Increases the Width of grid cells in the NodegraphtoggleGridSnap()
Toggles Grid Snap on and offtoggleShowGrid()
Toggles the showing of the Grid in the NodegraphsetNodegraphGridDefaults()
Sets new defaults for the Nodegraph Grid ColorssyncGridSnapStates()
Gets run on project open to sync the action triggered states to the state of the prefsmari.ExtensionPack.nodegraphPalette()
Methods relaed to the Nodegraph Palette and Palette TabscloseCurrentGraphNotification()
Closes the currently active graph notificationcursorPositionInNodegraphSpace()
returns the user cursor position in nodegraph space
(QPointF): the position of the cursor in nodegraph spacecycleNodegraphTabs()
Cycle through the open Nodegraph TabsenterSubgraph()
'
Opens a subgraph (e.g. selected roupnode)findNodeAbstractGraphicsView()
this method returns the QGraphicsView of the Nodegraph
(QGraphicsView): The Graphical View Widget of the NodegraphfindNodeGraphContext()
this is a method to find the active nodegraph based on the open tab.
A more direct method has been added under mari.ExtenionPack.nodegraph().current()
mari.Nodegraph: The currently active and open Mari NodegraphfindNodeGraphTabWidget(returnNoneIfRootGraph=False)
this is a method to find the active nodegraph Tab widget
returnNoneIfRootGraph (bool): If true the return is always None if the active tab widget is the root graph
(QTabbedWidget): Returns the QTabbedWidget or NonegetCurrentGraphNotification()
Returns the currently active Graph Notificaion or None
QWidget | None:getNodeGraphEventFilter()
Returns a Event Filter on the QGraphicsView that is the Nodegraph
self.ctrl_pressed (bool)
self.shift_pressed (bool)
self.alt_pressed (bool)
self.graph (QGraphicsView)
self.cursor_position (QPos)
CTRL_key(bool) (SIGNAL)
SHIFT_key(bool) (SIGNAL)
ALT_key(bool) (SIGNAL)get_alt_pressed()
Returns True or False depending if the ALT Key is pressed in the Nodegraph
If instead of a static function you want to attach to a Signal for the Key Press Event,
use mari.ExtensionPack.nodegraphPalette.getNodeGraphEventFilter() to get the event Filter Class,
then attach to the ALT_key(bool) signalget_ctrl_pressed()
Returns True or False depending if the CTRL Key is pressed in the Nodegraph
If instead of a static function you want to attach to a Signal for the Key Press Event,
use mari.ExtensionPack.nodegraphPalette.getNodeGraphEventFilter() to get the event Filter Class,
then attach to the CTRL_key(bool) signalget_shift_pressed()
Returns True or False depending if the SHIFT Key is pressed in the Nodegraph
If instead of a static function you want to attach to a Signal for the Key Press Event,
use mari.ExtensionPack.nodegraphPalette.getNodeGraphEventFilter() to get the event Filter Class,
then attach to the SHIFT_key(bool) signalgraphNotification(text='Graph Notification', auto_close_seconds=2, width=None, height=None, background_color='rgba(100, 100, 100, 200)', border='2px solid orange', font_size=12)
Notification Widget to display info to the user directly in the nodegraph without blocking Mari.
Only one Notification can at any time be shown. If a new Notification is triggered, the previously
shown one will first be hidden.
text (str): The notification text to display
auto_close_seconds (int | float): The time the notification stays open before closing.
Defaults to 2 seconds
width (int | None): The width of the Notification in Pixels. Defaults to 350.
If None the size is auto adjusted to its contents
height (int | None): The height of the notificaiton in Pixels. If None (default),
the size if auto adjusted to its contents
background_color (str): The Stylesheet for the background color of the frame.
Defaults to "rgba(0, 0, 0, 200)"
border (str): The Stylesheet for the border of the frame.
Defaults to "2px solid orange"
font_size (int): The font size of the Text in the notification in px.
Defaults to 12
QWidget: Returns the Nodegraph Notification Widget
getCurrentGraphNotification(): Get currently open Notification widget
closeCurrentGraphNotification(): Close currently open Notification widgetleaveSubgraph()
'
Leaves a subgraph (e.g. selected groupnode)setNodegraphContext()
this sets the context focus inside of mari to the Nodegraph.
This is useful to return focus to the Nodegraph after a dialog was opened/closedsetNodegraphTabIndex(index)
set the active open Nodegraph Tab
index (int): The Index Number of the Tabmari.ExtensionPack.nodegraphSelection()
Controls for the Nodegraph SelectiondeselectAllNodes()
deselect all Nodes in the current Graph TabdeselectAllNodesExceptBackdrops()
deselect all Nodes except backdrops in the current Graph TabgetLastNodeSelection()
Returns the last made node selection.
This might be the currently selected node(s)
(list): a list of nodesgetPreviousNodeSelection()
Returns the last made node selection before the current one.
(list): a list of nodesgetSelectedNodesOnCurrentGeoRootGraph(FirstOnly=False)
A quick and easy way to get the selected Nodes from the current geo root graph
FirstOnly (bool): If "True" only the first found selected node willl be returned,
otherwise all selected ones
(list): A list of nodes (mari.Node) if FirstOnly=False
(mari.Node) A single mari.Node if FirstOnly=TruegetSelectedNodesOnCurrentGraph(FirstOnly=False)
A quick and easy way to get the selected Nodes from the currently open graph
FirstOnly (bool): If "True" only the first found selected node willl be returned,
otherwise all selected ones
(list): A list of nodes (mari.Node) if FirstOnly=False
(mari.Node) A single mari.Node if FirstOnly=TruegetSeparateNodeStreams(nodelist)
Takes a given nodelist from e.g. a selection [Node1,Node2,Node3,Node4,Node5,Node6]
and checks what nodes are connected to each other, then splits it into lists.
For example for two node streams:
Node1->Node2->Node3
Node4->Node5->Node6
... a nested list is returned [ [Node1,Node2,Node3],[Node4,Node5,Node6]]selectAllNodes()
Select all Nodes in the current Graph TabselectClosestNodeToCursoAndView(viewNodeProperties=True)
Selects the closest node to the cursor in the current nodegraph
and attach a viewer.
By default it will also view the Node Properties
viewNodeProperties (bool): If true, the nodes node properties will be shown.
if false, the node will only be selected
Defaults to True
mari.Node The selected Node or NoneselectClosestNodeToCursor(viewNodeProperties=True)
Selects the closest node to the cursor in the current nodegraph.
By default it will also view the Node Properties
viewNodeProperties (bool): If true, the nodes node properties will be shown.
if false, the node will only be selected
Defaults to True
(mari.Node): The selected Node or NoneselectCustomNodes(showReport=True)
Selects all Custom Nodes (non mari default ones) in current Graph Tab
and provides a message with information about the node types
showReport (bool): By default the method will show a report of all custom node types on top of selecting them
Set to False to prevent that and just select custom nodesselectNodesByType(typeOfNode='Paint', nodegraph=None, referenceNode=None)
Selects all Nodes of a given type
typeOfNode (string): Specifies the type of Node to select.
Available Options are:
"Paint" , "BakePoint","GeoChannel",
"Channel","Shader","Material",
"Same Type", "Same Category'
"Same Type" will run off the typeID() of a node
"Same Category" will run off the Path of the Node
found in the Node Information Dialog (hotkey I)
nodegraph (mari.nodeGraph): Optional Nodegraph Argument to use as the reference graph
to select nodes in. If None, the currently open Nodegraph Tab
will be used.
Defaults to None
referenceNode (mari.Node): Optional Single Node Argument to use as the reference Node.
This node will be used when running in "Same Category" &
"Same Type" Mode to determine what Type or Category to select
Defaults to None, in which case the first selected node of the
given graph will be used. The graph will be the currently open
Nodegraph tab or the given graph provided via the nodegraph argumentselectUpstreamNodes(Stream='None')
select all upstream nodes from the current node selection
Stream (string): optional Material Stream Name to limit the upstream Selection toselectUpstreamNodes_ignoreRadios(Stream='None')
select all upstream nodes from the current node selection but stop
BEFORE a radio node or receiver node
Stream (string): optional Material Stream Name to limit the upstream Selection toselectUpstreamNodes_stopAfterRadios(Stream='None')
select all upstream nodes from the current node selection but stop
AFTER a radio node or receiver node
Stream (string): optional Material Stream Name to limit the upstream Selection toclearNodeGraphSelectionTrackingData()
Clears the cache for Nodegraph SelectionsdiscontinueNodeGraphSelectionTracking()
disconnects nodegraph selectiont rackinginitializeNodeGraphSelectionTracking()
a method called on Mari Project startup to create signal connections
to track nodegraph selection changes on all geosinitializeNodeGraphSelectionTracking_onSpecificGeo(entity='')
Generates a signal connection from nodegraph.nodeSelectionChanged()
to the Selection Tracking Cache for a newly added Geometry
Args:
entity (mari.geoEntity): The Entity addedmari.ExtensionPack.nodegraphStyle()
Handles custom Nodegraph Stylesheet editstoggleAllowAutoInsert()
Toggles on/off if Auto Insert it allowed
if dragging a Node onto a wiretoggleAllowShakeToExtract()
Toggles on/off if Nodes can be extracted via a Mouse Shake
Requires Mari 7.0v1 or higher.addStyleSheetPreferences()
Adds preferences to control the Mari internal Nodegraph Stylesheet to Nodegraph Tab of PrefsgetStyleData(group, key, value, fromTempFile=True)
Retrieves Nodegraph Stylesheet data from disc
group (str): The group is the section in the Nodegraph Stylesheet to change
key (str): The key in the Nodegraph Stylesheet you wish to edit
value (str,int) The value to set the key to
fromTempFile (bool) Determines if to fetch from a temporary file that gets transferred into the
Nodegraph Stylesheet on exit of Mari. This is necessary because Mari keeps
internal Stylesheet data in memory and otherwise data would get lost and overwritten
with old data on mari exit. Defaults to TruesyncAutoInsert()
Syncs the state of Auto Insert on / off
(if dragging a Node onto a wire) to the
UI option in the Nodegraph / Connection MenuupdateStylesheetFromPref(group, key, asTempFile=True)
Singal Attachment as changeScript when a preference in the Nodegraph/Nodegraph Style sheet
section is edited.
group (str): The group is the section in the Nodegraph Stylesheet to change
key (str): The key in the Nodegraph Stylesheet you wish to edit
asTempFile (bool) Determines if to write to a temporary file that gets transferred into the
Nodegraph Stylesheet on exit of Mari. This is necessary because Mari keeps
internal Stylesheet data in memory and otherwise data would get lost and overwritten
with old data on mari exit. Defaults to TruewriteMemoryStylesheetToDisc()
Mari keeps a stylesheet for the nodegraph in memory.
This methods writes the stylesheet values from memory to discwriteStyleData(group, key, value, asTempFile=True)
Writes nodegraph Stylesheet data
group (str): The group is the section in the Nodegraph Stylesheet to change
key (str): The key in the Nodegraph Stylesheet you wish to edit
value (str,int) The value to set the key to
asTempFile (bool) Determines if to write to a temporary file that gets transferred into the
Nodegraph Stylesheet on exit of Mari. This is necessary because Mari keeps
internal Stylesheet data in memory and otherwise data would get lost and overwritten
with old data on mari exit. Defaults to Truemari.ExtensionPack.object()
Object related methodsgeoUVIndices(currentGeoOnly=True)
Builds a UV Index Dictionary of your current geo or all geos
currentGeoOnly (bool): Determines if to build the Indices for current Geo or all Geos
dict
listlist(include_2D_objects=False)
Returns a list of Mari geos.
This is similar to mari.geo.list() however includes an argument to filter out 2D Paint Objects.
2D Paint Objects were included in Mari 7.1 as part of the 2D Canvas. Unfortunately mari's default
geo.list() also includes those 2D Objects.
This wrapper function allows you to get the old functionality of the the api call in Mari 7.1+
include_2D_objects (bool): If to include 2D Objects in the list. Defaults to False
list: A list of mari.geoEntity objectsremoveAllGeoChannels(geo=None, silent=False)
Removes Geo Channels from a given geo
geo (mari.geoEntity): Optional.The Mari Geo to remove Geo Channels from.
If None (default), the current selection is used
silent (bool): Optional. If a pop up will appear to let the user confirm
None:removeObjectVersion()
Remove the currently set object version on the geo in the object palettesetAllSUBDToHigh()
Set all objects to highest available subdivisionsetAllSUBDToLow()
Set all objects to level 0setVisibleSUBDToHigh()
Set all visible objects to highest available subdivisionsetVisibleSUBDToLow()
Set all visible objects to level 0unsubdiveGeo(geo=None)
Remove the subdivision from a given geometry, which can make a scene lighter
(mari.current.geo()) is usedaddDefaultObject(asObjectVersion=True)
Launches the "Add Default Objects" dialog
where you can add a number of primitive objects to your Mari scene (plane, tiling plane, cube etc.)
asObjectVersion (bool): determines if the AS OBJECT VERSION Checkbox is ticked on startupexportGeometry()
Launches a full Export dialog where you can export your Geometry from your projectexportGeometry_selectionOnly()
Launches a Export dialog where you can export your SELECTED objectexportUVMasks()
Launches a full Export UV Mask dialog where you can export UV Masks from
multiple objectsexportUVMasks_selectionOnly()
Launches a Export UV Mask dialog where you can export UV Masks from the SELECTED Objectsubdivide()
Launches the subdivide dialog, where you can batch subdivide multiple objectsaddDefaultObjectsToRecentMeshes()
Adds the Extension Pack Default Objects
to the list of recent meshes in the CREATE NEW PROJECT
DialogaddGeoRenamePreference()
Adds the Preference "Geo Vesion Naming" to the Misc Preference TabcreateGeoRenameSignals()
called on project open, this creates signal connections to
mari.geo.entityAdded and geometryVersionAdded.
Depending on the Preference setting "Geo Version Naming" in Prefs/Misc/ added Object Versions are
auto-renamed.saveGeoRenamePreference()
Saves the Preference "Geo Vesion Naming" from the Misc Preference Tabmari.ExtensionPack.ocio()
Colorspace MethodsgetAvailableColorspaces(ocio_filepath, colorspace_defaults)
Returns two separate lists, one with Colorspace Roles, one with Colorspaces
colorspace_defaults (mari.ColorspaceDefaults): An instance of the Project's Colorspace Defaults
[RoleName, Rssolved colorspaceName, Colorspace Pretty Name]
spaces (list): A list of colorspaces as nested lists
[colorspaceName, pretty Name]getOCIOandDefaults()
Returns the OCIO Filepath as well as the project colorspace defaults
ocio_filename (str): The fully resolved filepath to the OCIO config file
colorspace_defaults (mari.ColorspaceDefaults) The projects colorspace defaultsmari.ExtensionPack.patch()
Patch related toolsapplyPatchResolutionTemplate(geo=None, channel=None, node=None, forceModeTo=None)
Restores the configuration / resolutions of the UDIMs from a saved template
If geo is None, the current geo will be used (mari.current.geo())
if chan is None and/or Node is None, a dialog will ask the user which
to save from (if both channel and a paint node are selected)
geo (mari.Geo): A mari geo to save against. If None, current geo is used
channel (mari.Channel): A mari channel to save from. If None, current Channel is used
node (mari.Node): A mari node with an imageSet (e.g. Paint Node). If None, currently selected node is used
forceModeTo (string): Allows you to force the Mode the method is run in to a certain way, either 'Channel' or 'Node'
This will circumvent dialog popups and allows using this method via API Calls. Defaults to NonepatchBake_to_imagemanager()
Launches Patch Bake to Image ManagerresizePatches_onChannelsOrNodes(size)
Resizes selected patches on either channels or nodes
size (string or integer): An integer for a fixed size 256,512,1024,2048,4096,8192 etc.
A string for double,half size or null size double, half, nullsavePatchResolutionTemplate(geo=None, channel=None, node=None, forceModeTo=None)
Saves the configuration / resolutions of the UDIMs to a template
that can be applied to other patches.
If geo is None, the current geo will be used (mari.current.geo())
if chan is None and/or Node is None, a dialog will ask the user which
to save from (if both channel and a paint node are selected)
geo (mari.Geo): A mari geo to save against. If None, current geo is used
channel (mari.Channel): A mari channel to save from. If None, current Channel is used
node (mari.Node): A mari node with an imageSet (e.g. Paint Node). If None, currently selected node is used
forceModeTo (string): Allows you to force the Mode the method is run in to a certain way, either 'Channel' or 'Node'
This will circumvent dialog popups and allows using this method via API Calls.Defaults to Nonemari.ExtensionPack.pinnedLayers()
Pinned Layers/Channels SystemcollectionPin(mode)
Adds a collection Pin
mode (str): "0" for layers, "1" for channel layersemptyPin()
Executed if no layer has been pinned but user triggers quick pinquickPin(mode)
Adds a Layer selection to the Quick Pin
mode (str): 'channel' wil add a pinned Channel, else automatically use layerstriggerCollectionPin(layerType, layerName, project_uuid, layer_uuid)
Adds shared layers from a collection pin
layerType (str): "0" for layers, "1" for channel layers
layerName (str): The Name of the Layer the Pin references
project (str): The Project Name the Quick Pin was added
project_uuid (str): The Project UUID the Quick pin was added
layer_uuid (str): The UUID of the Layer(s) the Quick Pin should addtriggerQuickPin(layerType, layerName, project_uuid, layer_uuid)
Adds shared layers from the Quick Pin
layerType (str): "0" for layers, "1" for channel layers
layerName (str): The Name of the Layer the Pin references
project (str): The Project Name the Quick Pin was added
project_uuid (str): The Project UUID the Quick pin was added
layer_uuid (str): The UUID of the Layer(s) the Quick Pin should addmanageCollectionPins()
Launches Manage Collection Pins UIclearCollectionPins()
Removes all Collection Pins in a ProjectrestoreProjectPins()
Used to restore any Pins stored in a project, so they appear in the UImari.ExtensionPack.presetBrowser()
Preset Browser MethodscloseSmartMaskShelfInstance()
Closes any Preset Browser running in the BackgroundresetSmartMaskShelfPositionAndSize()
Closes any currently active instance of the Preset Browser
then resets the size and position to defaultlaunchSmartMaskShelf(mode)
Opens the Preset Browser shelf
mode (str): 'Layer' or 'Nodegraph'createMaskShelfPreferences()
Creates Preferences inside the Mari PreferencessaveMaskShelfPreference()
Saves Preset Browser Specific Preferencesmari.ExtensionPack.project()
project related tools such as cleanup toolscleanUpData()
Runs a Garbage Collect in a way that Mari force collects garbage data, which is different from
normal garbage collect which needs a few project open and saves to start collectinggetCurrentProjectFolder()
Returns the Mari Project Folder for the current Project
(string): Path to the project specific FoldergetEPProjectDataFolder(create_if_not_exist=True)
Returns the Folder where Extension Pack stores Project specific
JSON Files
create_if_not_exist (bool): If True (default) the folder will be auto-created if it does not exist
(string): Path to the project specific Folder where Extension Pack
stores JSON DatamariProjectIsOpen()
A utility function that returns if a project is fully open.
Mari fires many signals on project open that might produce
unintended results when processed by 3rd party scripts
if the project is not yet fully opened.
This method can be used to check if the project is fully open
(bool): True if a Project is opened, False otherwiseopenCurrentProjectFolder()
Opens your Project Directoy (currently open project) in a File BrowserremoveAllSnapshots()
Remove all Layer and Channel Snapshotsinitialize_project_open_tracking()
A utility function that returns if a project is fully open.
Mari fires many signals on project open that might produce
unintended results when processed by 3rd party scripts
if the project is not yet fully opened.
This method initializes signal connections to track
the project open stateloadAdditionalProjectSettings()
Certain states are not automatically saved by mari
with your project, e.g. the current Selection Mode,
Mirror Painting Mode chosen etc.
This will read the states of those actions from a saved
json file in your project directoryprojectOpenNodeProcesing()
Combines multiple actions that need to happen on
project open into one loop
This will iterate over all nodes in a project and perform
certain actions required by Extension Pack
This is called on project open and serves as a "one stop"
function for every action that needs to happen on project open.
Some examples of actions run are:
- Locking of Backdrop Colors so they don't get re-randomized
- Updating of Radio Nodes
- Updating of Bake Point Image Port Data
- Updating of Visual Notes FilesprojectSaveNodeProcesing()
Combines multiple actions that need to happen on
project close into one loop
This will iterate over all nodes in a project and perform
certain actions required by Extension Pack
This is called on project close and serves as a "one stop"
function for every action that needs to happen on project close.
Some examples of actions run are:
- Cleaning of unused Image Annotation files in project directorysaveAdditionalProjectSettings()
Certain states are not automatically saved by mari
with your project, e.g. the current Selection Mode,
Mirror Painting Mode chosen etc.
This will write the states of those actions into a json
file into your project directorymari.ExtensionPack.projectCollections()
project collection related tools allowing you to filter the Project TabactivateCollection(name, hideOthers=True, filter_text=None)
- Also see "setCurrentCollection()"
This method triggers the evaluation of what projects should be visible in the Mari Projects Tab List Widget.
This is mostly an internal function call but exposed here for convenience.
The method does NOT set the active collection name in the Dropdown menu. You can use setCurrentCollection()
for this one. Instead this method only compares the given name (collection name) with all projects
in the Mari Projects Tab and hides any project that doesn't have the specified Collection Name set.
hideOther(bool): If True (default), projects not assigned to the given collection "name" will be
hidden
filter_text (str|None): A optional, additional text filter or None (default).
Text Filters can run on Project Names or Project Metadata and support basic
expressions:
Basic: ProjectName - matches project names
OR: ProjectA,ProjectB - matches either project A or B
AND: Project+Final - matches both terms
NOT: Project+!Draft - matches Project but not Draft
Metadata Search:
$Value - searches all metadata for "Value"
$Name:Value - searches specific Metadata (Name) for Value
!$Draft - excludes projects with Draft in metadata
addCollection(name, color=None)
Adds a new collection to the Project Collections dropdown in the
Project Tab
Note that empty Collections without any projects assigned will be auto removed on each Mari Restart.
name (str): The Name of the new collection
color (str|None): Optional. The Color coding for the new collection as a hex color string
(e.g. "#ffffff").
If None (default), a "random" color will be chosen. The "random" color will be
consistent though every time, based on the given name of the collection.
A collection name "My Collection" will therefore always generate the exact same
"random" color if the color arg is None.
ValueError: Raises a Value Error if the specified name already exists
RunTimeError: Raises a RunTimeError if the Collections widget is inaccessibleassignProjectsToCollection(name, projects=None)
Assigns the provided projects to a collection specified with "name".
If the collection name doesn't exist, it will be created.
If no projects argument is given or None, the current Project Selection is used.
A project can belong to multiple collections. If you want to remove a project from a collection
you need to remove it via removeProjectsFromCollection()
name (str): The name of the collection to assign projects to.
projects (list[mari.ProjectInfo] | None): A list of mari projects or None.
If None (default), the currently selected projects are used.batchAddCollections(collections_definitions)
Convenience method to batch add multiple collection names
Note that empty Collections without any projects assigned will be auto removed on each Mari Restart.
collections_definitions (dict): Dictionary defining collections. The key should be the collection
name. Value can be None or a string representing the color code
of the collection e.g. '#ffffff'||.
If the collection name already exists, it will be ignored
ValueError: Raises a Value Error if the specified name already exists
RunTimeError: Raises a RunTimeError if the Collections widget is inaccessibleclearFilter()
Convenience method to clear the contents of the Filter LineeditcollectionNameExists(name)
Checks if a given collection name already exists
name (str): The Name of the new collection you want to test if it already exists
RunTimeError: Raises a RunTimeError if the Collections widget is inaccessiblefilterEnabled()
Returns if the filter is enabled or notfilterText()
Returns the currently set filter text
(str): The currentlys set stringgetAllProjectCollections()
Returns a dictionary of {"CollectionName" : [mari.project.uuid(),mari.project.uuid()] } for all
Collections that currently exists. This covers all Projects in the Project Tab (mari.projects.list())
Projects without any assigned Collection are listed in the "No Collection" key of the dict.
of project uuids as values.
{"CollectionName" : [mari.project.uuid(),mari.project.uuid()] }getCollectionMetadataID()
Returns the name of the Metadata we use to store Project Collections on a Mari Project.
You can use this to directly query Project Collections on mari.Project Objects.
e.g. mari.Project.metadata(getCollectionMetadataID())getCollectionsComboBox()
Returns the QComboBox Widget of the Collections Widget for low level QT accessgetCollectionsWidget()
Returns the Collections Widget for low level QT access
The dropdown menu is called "category_dropdown".getCurrentCollection()
Returns the name of the currently set collectiongetProjectCollections(projects, includeWithoutAssignment=False)
Returns a list of all Project Collections the given mari projects belong to
projects (list[mari.ProjectInfo]): A list of Mari Project Objects (e.g. mari.projects.selected())
includeWithoutAssignment (bool): Optional. Defaults to False. If True, projects without any collection
assignments will be included in the returned list with a Collection Name
"No Collection"projectIsPartOfCollection(project, name)
Checks if a given project is part of the collection specified via "name"
project (mari.ProjectInfo): the Mari Project to check
name (str): the name of the collection to test.
(bool): Returns True if the given Project is part of the collection specified
with "name"refreshCollectionsComboBox()
Convenience Method to reinitialize the QComboBox used to switch between Project Collections
This can be useful to call if you want to enforce alphabetical sorting of the ComboBox at runtime
after a new collection has been added.
Usually the combobox is only sorted on Mari Start and after that new collections are appended as items.
Using this method you can resort the AbstractView of the combobox even while Mari already is open
Please note that during the refresh, empty collections without any projects assigned will be removed.removeCollection(name)
Removes the collection with the given name.
Projects assigned to that collection will have the name from their ProjectGroups Metadata removed
name (str): The Name of the collection to remove
ValueError: Raises a Value Error if the specified name does not exist
RunTimeError: Raises a RunTimeError if the Collections widget is inaccessibleremoveProjectsFromCollection(name, projects=None)
Removes the provided projects from a collection specified with "name".
If a project isn't part of the provided collection name, it will be ignored
If no projects argument is given or None, the current Project Selection is used.
name (str): The name of the collection to remove projects from
projects (list[mari.ProjectInfo] | None): A list of mari projects or None.
If None (default), the currently selected projects are used.setAllowDefaultChange(state)
Determines if users are allowed to set their own default collection that is shown when mari starts.
Using this method you can prevent users from changing the default for example for the purpose of
enforcing a default collection in a pipeline.
Please note in the end all this method is doing is setting the Mari Preference
'/Misc./Project/AllowDefaultCollection' so users can change it afterwards if they are inclined to.
dropdown menu. If False, the Button is hiddensetCollectionColor(name, color)
Adds a new collection to the Project Collections dropdown in the
Project Tab
name (str): The Name of the collection to update
color (str): The Color coding for collection as a hex color string (e.g. "#ffffff").
ValueError: Raises a Value Error if the specified name already exists
RunTimeError: Raises a RunTimeError if the Collections widget is inaccessiblesetCurrentCollection(name)
Convenience Function to set the collection dropdown menu to a given collection name
name (str): The name of the collection to set as active
RunTimeError: Raises a Runtime error if the Collection Widget is inaccessiblesetFilterEnabled(state)
Toggles the Filtering on or off
state (bool): True to toggle filter on, False to toggle it offsetFilterText(filter_text)
Set a filter text.
filter_text (str): Text Filters can run on Project Names or Project Metadata and support basic
expressions:
Basic: ProjectName - matches project names
OR: ProjectA,ProjectB - matches either project A or B
AND: Project+Final - matches both terms
NOT: Project+!Draft - matches Project but not Draft
Metadata Search:
$Value - searches all metadata for "Value"
$Name:Value - searches specific Metadata (Name) for Value
!$Draft - excludes projects with Draft in metadatashowAllProjects(filter_text=None)
Convenience Function to set the current Collection to "All Projects"
filter_text (str|None): A optional, additional text filter or None (default).
Text Filters can run on Project Names or Project Metadata and support basic
expressions:
Basic: ProjectName - matches project names
OR: ProjectA,ProjectB - matches either project A or B
AND: Project+Final - matches both terms
NOT: Project+!Draft - matches Project but not Draft
Metadata Search:
$Value - searches all metadata for "Value"
$Name:Value - searches specific Metadata (Name) for Value
!$Draft - excludes projects with Draft in metadataaddCollectionWidget()
Adds a Project Collection Widget to the top of the Mari Projects TabcreateCollectionPreference()
Add preferences to configure display and behavior of the Project collections
to the Mari preference dialog under /Misc./ProjectdeleteCollectionWidget()
Removes the Project Collection Widget from the UIsaveCollectionPreference()
Saves preferences to configure display and behavior of the Project collections
from the Mari preference dialog under /Misc./ProjectsetAllowDefaultCollectionIcon()
Internal method to update the "Pin default collection" display of the button at runtime.
Called by the AllowDefaultCollection preference in the Misc Tab.mari.ExtensionPack.project_paths()
Set Project Path Toolget_projectPath_jsonFile()
Returns the per project path to the json file
Used to store project path settings such as export paths etc.setProjectPathVariable(variable_name, variable_data, set_active=True)
Sets a variable "variable_name" to "variable_data" on the current project.
The Variables being set are default variables such as mari.resources.DEFAULT_IMPORT
which determines what Folder a Browse Dialog should open in by default.
Different Variables are available.
This function is an API call for what usually can be done via the Extension Pack Tool
"Set Project Path" found in the File Menu. A set Project Path is restored on Project Open.
The following variable names are available:
'MARI_DEFAULT_IMPORT_PATH' - sets the default Path for Texture Importing
'MARI_DEFAULT_EXPORT_PATH' - sets the default Path for Texture Exporting
'MARI_DEFAULT_GEOMETRY_PATH' - sets the default path for Geometry Importing and Exporting
'MARI_DEFAULT_IMAGE_PATH' - sets the default path when using "Open" in the image manager
'MARI_DEFAULT_RENDER_PATH' - sets the default path when rendering a turntable or screenshot
'MARI_DEFAULT_ARCHIVE_PATH' - sets the default path when archiving
'MARI_DEFAULT_SHELF_PATH' - sets the default path when importing an item into the shelf
'MARI_DEFAULT_CAMERA_PATH' - sets the default path when loading cameras or projectors
'Sequence_Flat' - sets the default file template for flattened textures e.g. $CHANNEL.$UDIM.tif
'Sequence' - sets the default file template for non-flattened textures e.g. $CHANNEL.$LAYER.$UDIM.tif
'PTEXSequence_Flat' - sets the default file template for flattened ptex textures e.g. $CHANNEL.$UDIM.ptex
'PTEXSequence' - sets the default file template for non-flattened textures e.g. $CHANNEL.$LAYER.$UDIM.tif
Variable Data is written into a file called 'MEP_ProjectPaths_' + EPVersion + '.json' inside the
Project Cache Folder in a subfolder EP_Project_Data.
variable_data (str): The Variable data to set, either a path or file template.
set_active (bool): If True (default), the new Path or file template will be immediately
activated. If False it will only be activated when the project is reopened.set_project_paths()
Launches the Set Project Path DialogcheckProjectPaths()
restore_project_paths()
Restores set project paths on Project Loadmari.ExtensionPack.project_template()
Project Template ToolsapplyLightInfoFromTemplate(templateFilePath)
Applies Light info to your project from a template
templatePath (string): A path to a template jsonapplyPrefsFromTemplate(templateFilePath, excludeList=[], includeList=[])
Applies Preferences to a project from a template
templatePath (string): A path to a template json
excludeList (list): A list of preference paths to ignore
includelist (list): A list of preference paths to include.
Ignored if empty.Partial matches are allows
since it searches for each item in the list
if a preference path starts with it.applyProjectorInfoFromTemplate(templatePathFile, projectorFolderLocation)
Applies Projector info to your project from a template
templatePathFile (string): A path to a template Json
projectorFolderLocation (string): A path to a folder containing projector filesapplyViewportInfoFromTemplate(templateFilePath)
Applies Viewport info to your project from a template
templateFilePath (string): A path to a template JSONimportLastLightInfoTemplate()
Reimports the last used Light Info Template again
This is a temporary method to work around a mari issue
on new projects where mari changes the lights AFTER the project
has already been setup and saved after creationimportNodesFromTemplate(templateFolderPath, clearExisting=True, currentGeoOnly=True)
Imports Nodes from a Template
templateFolderPath (string): A path to a template directory
clearExisting (bool): if True, all channels and nodes from the geo will be removed before importing
currentGeoOnly (bool): Specify if nodes should only be imported onto current geo
bool: True or False if SuccessfulsaveLightInfoAsTemplate(templateName)
Saves a light info template json
templateName (string): A Name of a Template to Save
string: The path of the saved light template filesaveNodesFromCurrentGraph(templateName, selectedOnly=False, skipImageData=False)
Saves Nodes from the current Graph to an archive
templateName: The template Name to store the archive under
selectedOnly: If you only want to include selected nodes
skipImageData: If Image Data should be exported as well
bool: Returns if export was a success
string Returns a export status message
string Returns the export pathsavePrefsAsTemplate(templateName)
Saves a prefs info template json
templateName (string): A Name of a Template to Save
string: The path of the saved light template filesaveProjectInfoAsTemplate(templateName)
Saves a projector info template json and projector files
templateName (string): A Name of a Template to Save
bool (string): If Successfull,the path of the saved light template filesaveViewportInfoAsTemplate(templateName)
Saves a viewport info template json
templateName (string): A Name of a Template to Save
string The path of the saved light template filecreateTemplateUI()
Opens the createTemplate UIimportTemplateUI()
Opens the importTemplate UImanageTemplateUI()
Opens the manageTemplate UIaddTemplateFolderPreference()
Adds Preferences to the Mari Preference Dialog
to set a Path where Templates should be stored
/Preferences/Paths/Project TemplatesautoImportTemplateOnNewProject()
Automatically imports a template into a newly created project
The process never is called when in Terminal Mode (on purpose)loadTemplateFolderPreference()
Load the Project Template Preference Path from the config
and set it in the /Preferences/Paths/Project TemplatessaveTemplateFolderPreference()
Saves the Project Template Preference to the configsetTemplateFolderPreference(path)
Sets the Project Template Folder in the Preference.
This is the location where templates are loaded from.
You can also add templates via Environment Variables
path (string): A path
bool: True if path could be setmari.ExtensionPack.projectors()
Projector related toolsmoveScanProjectionBlock_left()
Part of the Projection Wizard Toolset.
With a Mix Node from a 3D Scan Projection Group selected,
will move the entire block to the leftmoveScanProjectionBlock_right()
Part of the Projection Wizard Toolset.
With a Mix Node from a 3D Scan Projection Group selected,
will move the entire block to the rightremoveAllProjectors(silent=False)
removes all Projectors
silent (bool): if True, no confirmation dialog will be showntoggleCameraType()
toggles the selected projector between Orthographic and PerspectiveupdateProjectorCamera()
updates the currently active projector with the camera settings from the active viewportupdateProjectorClippingPlanes(projector=None, geo=None)
Adjusts the given Projector's near and far clipping planes to the
given geo's bounding sphere
projector (mari.projector): If a projector is provided, this will
be the projector that will be adjusted.
If no projector is provided (None), which is the default
the method will fall back to the currently selected projector
geo (mari.geoEntity): If a geometry is provided, its bounding sphere will
be the source of the near and far cliping plane for the projector.
If no geometry is provided (None), which is the default
the method will fall back to the currently selected objectmultiRenameProjectors()
Launches a UI to rename ProjectorsprojectionWizard()
Launches the 3D Scan Projection Wizard UIrevertCameraClippingPlaneSettings()
A method called by the mari.projectors.projectorMadeCurrent() signal.
It will check the new, current projector for the existence of metdata
oldNearClip & oldFarClip.
If the metadata exists, the current view camera will be reverted back to these
clipping plane settings and the metadata will be removed from the projectorsetClippingPlaneMetadataOnProjector(projector)
When a Pojector is created directly from a node via the + button in
the node properties (for example via a Camera Projection Node),
this will auto-trigger an adjustment of the clipping plane on the
newly created projector.
To not interfer with the actual view, the view clipping plane will
immediately revert back to the original after and just the Projector
clipping plane will remain changed.
This particular method is a signal connection called by
mari.projectors.projectorAdded(). It will receive the newly created
projector as an argument. The method will then add the current clipping
plane data onto the projector as metadata, then adjust the metadata on
the actual camera of the projector to be a tight fit to the current object.
This is done via mari.ExtensionPack.projectors.updateProjectorClippingPlanes().
A secondary method "revertCameraClippingPlaneSettings" is called by the
mari.projectors.projectorMadeCurrent() signal. That method then takes care
of reverting the active view camera back.
projector (mari.projector): If a projector is provided, this will
be the projector that will be adjusted.mari.ExtensionPack.quickmarks()
Nodegraph quickmark related toolsloadQuickMark(ID)
Load a Nodegraph Quickmark
ID (int): The Number of the Quickmark to loadremoveQuickMark(ID)
Remove a Nodegraph Quickmark
ID (int): The Number of the Quickmark to deletesetQuickMark(ID)
Define a new Nodegraph Quickmark
ID (int): The Number to which to assign the quickmark toaddQuickMarksToGUI()
Adds Quickmark Buttons to top of NodegraphcheckQuickMarks()
Remove unused quickmarks that point to a non-existent location (geo or graph)
and update Button statedeactivateQuickMarkButtons()
Sets all Quickmark Buttons to disabledmari.ExtensionPack.radioNodes()
radio Node and transmitter related MethodsconvertInputConnectionsToRadios(nodelist=None, minimum_node_distance=800)
Auto converts input connections on given nodes to a Radio Transmitter / Radio Node Setup.
If no nodelist is supplied, the current selection will be used.
nodelist (list of mari.Node): A optional list of mari nodes to process input connections for.
If no nodelist is given (None, default value), the current selection
is used.
minimum_node_distance (int): An optional integer value defining the minimum distance, the input
nodes need to be away from the source node in order to be converted
to a radio transmitter/radio node connection pair. Defaults to 800.convertInputConnectionsToTeleporters(nodelist=None, minimum_node_distance=800)
Auto converts input connections on given nodes to a Teleport Broadcast/Receiver Node Setup.
If no nodelist is supplied, the current selection will be used.
nodelist (list of mari.Node): A optional list of mari nodes to process input connections for.
If no nodelist is given (None, default value), the current selection
is used.
minimum_node_distance (int): An optional integer value defining the minimum distance, the input
nodes need to be away from the source node in order to be converted
to a broadcast/receiver node connection pair. Defaults to 800.convertOutputConnectionsToRadios(nodelist=None, minimum_node_distance=800)
Auto converts output connections on given nodes to a Radio Transmitter / Radio Node Setup.
If no nodelist is supplied, the current selection will be used.
nodelist (list of mari.Node): A optional list of mari nodes to process output connections for.
If no nodelist is given (None, default value), the current selection
is used.
minimum_node_distance (int): An optional integer value defining the minimum distance, the output
nodes need to be away from the source node in order to be converted
to a radio transmitter/radio node connection pair. Defaults to 800.convertOutputConnectionsToTeleporters(nodelist=None, minimum_node_distance=800)
Auto converts output connections on given nodes to a Broadcast/Receiver Node Setup.
If no nodelist is supplied, the current selection will be used.
nodelist (list of mari.Node): A optional list of mari nodes to process output connections for.
If no nodelist is given (None, default value), the current selection
is used.
minimum_node_distance (int): An optional integer value defining the minimum distance, the output
nodes need to be away from the source node in order to be converted
to a radio broadcast/receiver node connection pair. Defaults to 800.cycleRadioNodeConnections()
This is a special way to cycle through the modes of radio nodes
1) If any Radio Nodes are selected it will toggle them
2) If no Radio Nodes are selected it will toggle ALL of them first
to show, then hidehideAllRadioNodeConnections()
Hides all Radio Connections in the current Graph TabjumpViewToRadioNodeConnection()
Focuses your Nodegraph on connected Nodes from the currently selected Radio Node or
Radio Transmitter NodeshowAllRadioNodeConnections()
Shows all Radio Connections in the current Graph TabtoggleRadioNodes(node, Force=False, ForceMode='')
A Python API method to toggle a Radio node, so it doesn't require UI interaction like
selections.
By using Force and Force Mode "Show" or "Hide" you can show all or hide all
node (mari.Node): The node to set
Force (bool): By setting a Force Boolean you can force a mode such as Hide or show otherwise it just toggles
ForceMode (string): 'Show' or 'Hide to show or hide a connectiontoggleSelectedRadioNodesConnection()
Toggle Selected Radio Nodes between "Show Connection" and "Hide Connection"updateRadioNodes(portName, node)
Updates the Label of the Radio node and Radio Transmtiters based on the current connections
portName (string): Unused: An optional portname. This is here to work with nodeInputChanged signal payloads
node (mari.Node): A Mari Node.connectRadioNodeToTransmitter()
Launches the "Connect to Transmitter" dialogconvertConnection()
Launches a dialog that allows you to convert the inputs or outputs on selected nodes into a
radio/transmitter connection or a teleport broadcast/receiver connectionconnectRadioNodeCreationSignal()
This method is deprecated and will be removed in a future version.
Monitors if a created Node is a Radio NodecreateRadioNodePreference()
Adds Radio Node Preferences to the Mari PreferencesdisconnectRadioNodeCreationSignal()
This method is deprecated and will be removed in a future version.
Turns off monitoring of Nodecreation in your project for Radio NodesreconnectRadioNodeToTransmitter(radionode)
This reconnects a Radio Node to a Transmitter based on previously
connected Radio Node Connection.
Given a Radio Node this method will search your nodegraph
for a Transmitter Node matching the name of a Transmitter Node
that was previously connected to that radio node and reconnect it.
Part of a system of reconnecting parts of your nodenetwork on import
to project specific parts of your graph such as Ambient occlusion etc.
radionode (mari.Node): The Radio Node to sample.saveRadioNodePreference()
Saves the On/Off State of Radio Node Preferences in the Mari PreferencesupdateAllRadioNodes()
Builds a signal connection to update all Radio Nodes and Radio Transmitter names, if the input changesmari.ExtensionPack.resources()
Path resources such as extension pack icon paths and extension pack
default object pathsextPack_3rdParty_path()
Path to 3rd Party ModulesextPack_archives_path()
The path to Extension Pack ArchivesextPack_baseShapes_path()
The path to Extension Pack Shape TexturesextPack_contextMenus_path()
Path to extension pack context menusextPack_gradients_path()
Path to Gradient presets for the Gradient EditorextPack_grunges_path()
The path to Extension Pack Grunge TexturesextPack_hdris_path()
The path to Extension Pack HDRI TexturesextPack_hotboxes_path()
The path to Extension Pack Hotboxes inside of the Resources FolderextPack_icon_path()
The path to Extension Pack IconsextPack_imageNotes_anatomy_path()
Path to icons for the "Image Notes" ShelfextPack_imageNotes_materials_path()
Path to icons for the "Image Notes" ShelfextPack_imageNotes_path()
Path to icons for the "Image Notes" ShelfextPack_imageNotes_shaderStreams_path()
Path to icons for the "Image Notes" ShelfextPack_imageNotes_utilities_path()
Path to icons for the "Image Notes" ShelfextPack_industrySurfaces_path()
The path to Extension Pack Industry Surfaces TexturesextPack_materialpreset_path()
The path to Extension Pack Material PresetsextPack_modoBakePresets_path()
The path to Extension Pack Modo Bake PresetsextPack_nodeContextMenu_path()
Path to extension pack standard node context menus
Node context menus appear when pressing CTRL+SPACE on a supported NodeextPack_object_path()
The path to Extension Pack Default ObjectsextPack_offlineSplashContent_path()
returns the folder where content is stored that is used in te splash screen
if the internet cannot be accessedextPack_procedurals_path()
The path to Extension Pack Procedural Masks for the Mask shelfextPack_resource_locator(alwaysReturnAPath=False)
Returns the custom paths specified via the 'Resources.json' file
The Resources Json File can be used to move the large Extension Pack
Resources out of the Mari Script Folder
alwaysReturnAsPath (bool): If true, the method will always return a string, never None
string or None: The resolved pathextPack_settings_path()
The path to Extension Pack Settings inside of the Resources folderextPack_shelf_data_path()
Path to Extension Pack's shared Image Data FolderextPack_smartmasks_path()
The path to Extension Pack Smart Masks for the Mask ShelfextPack_styles_path()
The path to Extension Pack Styles inside of the Resources FolderextPack_textures_path()
The path to Extension Pack TexturesextPack_tools_path()
Returns the Base Path of the Tools Directorymari_settings_locator()
Returns the Mari Settings directory setting:
Auto-Detect means EP will auto-detect based on common Settings Files
A Full Path
or a Mari Variable mari.resources.path( mari.resources.settingsPathKey() )mari.ExtensionPack.selection()
Selection related toolsisolateSelect()
Isolates visibility of the selectionshowLastHidden()
Unhides the last hidden bit of geometryconnect_last_hidden_signals()
Connects to mari standard actions to record the last component that was hiddenmari.ExtensionPack.selection_group()
selection group related methodscombineSelectionGroups(groupList, newName, removeOld=False)
Combines given selection groups into a combined one.
SPECIAL GROUP REQUIREMENTS:
Please note you cannot freely mix Selection Group Types for
Combining. You can mix:
- Face & Object Selection Groups
- Patch & Object Selection Groups
However you cannot mix:
- Face & Patch Selection Groups
groupList (tuple): a list of mari.SelectionGroups to combine
newName (string): the new name of the combined selection group
removeOld (bool): Optional. If True,the original groups from the groupList will
be deleted after combining. Defaults to False.
mari.SelectionGroup: returns the newly created, combined selection groupcomplexSearch(search, group_list, default_groupmode_list=None, default_visibility_modelist=None, limit_visibility_modifier=None, default_active_modelist=None, setData=None, forceInPathSearch=False, forceInObjectSearch=False, emptySearchReturnsTrue=False)
The search algorithm parses a given list of Selection Groups
against a search string with complex filtering options.
It returns a dictionary in format {SelectioGroupUUID : boolean},
with True, if the Search produces a matching result.
The search string offers a variety of operators:
SIMPLE WORD FILTER OPERATORS
+ (plus) , (comma) and ! (except) act as modifiers for words and
can be combined e.g. "wheel+cart+!horse" or "wheel+cart+!horse,car"
Both produce True for Selection Group Names containing "wheel" and "cart"
but not "horse", while the second option also produces True for elements
containing "car"
SUBTRACTIVE SETS
You can subtract word or word groups by prefixing them with a minus (-)
.E.g. roof-top of
The subtract operation will first run the quick visibility based on the other search terms, then as a last step'
turn off visibility for all Selection Groups matching the subtractive Word Group.
'
GLOBAL VARIABLES VS LOCAL VARIABLES
The search offers a variety of variables to further fine tune the search,
e.g. $vis filters only for visible selection groups.
Variables can exist in a global scope or a local scope.
$vis,wheel,cart,horse
applies the visibility filter to all search words - wheel, cart and horse.
$vis,wheel,cart+$invis,horse
applies the global visibility filter to "wheel" and horse, while "cart" has its
own local variable, filtering for Invisible groups instead.
AVAILABLE VARIABLES
Selection Group Types filter for the type of Selection Group e.g. a Face Group.
The inverse (!) excludes this one Type:
$face,!$face,$patch,!$patch,$obj,!$obj
The visibility Types filter for the visibility state of a selection group.
The inverted option (!) act like their counterpart e.g. !$vis == $invis
$vis,!$vis,$invis,!$invis
Set Filters filter against visible groups in a given "Visibility Set"
(defined in the Quick vis toolbar in the Selection Group Palette)
$inset:SETNAME,!$inset:SETNAME
"Active" Filters are a special Argument that can be fed in as part of the
provided selection group list. If instead of a list with Selection groups
e.g. [grp1,grp2,grp3] you feed in a nested list [[grp1,True],[grp2,False]]
the boolean argument is tested against with the "Active" Filter.
$act,!$act
Path Filters allow for precise positioning of a Filter within a selection
group name that has a hierarchy e.g. /Carriage/Cart/Wheel/spoke
By specifying the number of forward slashes in the Variable, you will limit
the search to parts of the selection group name that appear after the specified
slash number. E.g. for "/Carriage/Cart/Wheel/spoke", $/// will evaluate the Group
Name as "/Wheel/spoke"
$/,$//,$///,$//// etc.
You can invert the search by counting the slashes backwards.
E.g. for "/Carriage/Cart/Wheel/spoke", !$/ will evaluate the Group name as "spoke"
All variables can be mixed and matched, in local and global scope.
GENERIC VARIABLES
Generic variables can only be used in isolation. No other characters can appear in search string
* -- The star character (*) will show all Selection Groups'
!* -- The exclamation mark (!) followed by a star character (*) will hide all Selection Groups
| or ` -- The Pipe Character (|) or Backtick Character (`) will invert the visibility states of selection groups.
search (str):
The Search String to test group names from the Group list against
group_list (list):
A list of mari.SelectionGroups.
(GroupA,GroupB,GroupC)
If you sublist groups with an additional Boolean Argument
( (GroupA,True),(GroupB,False),(GroupC,True))
you can test against the boolean using the $act and !$act variables
default_groupmode_list (list):
Optional. Defaults to ['Face','Patch','Object'].
The defaults are used when no specific Type Variable
was supplied in the search string. You can use this
to limit the search to certain Types of Selection Groups
even when no Type Argument was given
default_visibility_modelist (list):
Optional. Defaults to ['visible','hidden'].
The defaults are used when no specific Visibility Variable
was supplied in the search string. You can use this
to limit the search to visibilities of Selection Groups
even when no Visibility Argument was given
limit_visibility_modifier (bool):
Optional. Defaults to False.
If True any visibility query works as a limiter to
what selection groups are processed.
When True and an invisible Group is encountered,
further processing of Group arguments stops.
This can work like an 'additive mode'.
default_active_modelist (list):
Optional. Defaults to ['active','disabled'].
The defaults are used when no specific Active State Variable
was supplied in the search string. You can use this
to limit the search to Active States of Selection Groups
even when no Active Argument was given.
The Active States can be supplied as part of the group_list
argument. Refer to that one for more information.
default_materialID_list (tuple):
Optional. e.g. ( (0.0,0.0,0.0,1.0), (1.0,0.0,0.0,1.0) )
The default Material ID list allows you to specify one or multiple sets of Material ID Colors
to search for. All other search operations will still be in effect however the end result
will only return true if the "ID_Override_Color" Metadata matches at least one of the
provided colors.
setData (dict):
Optional.Defaults to None
The setData is necessary if you want to use any of the $inset:SETNAME variables.
In order to not read Visibility Set Data in on any search, you need to provide
the set data through this argument.
You can fetch Visibility Set Data for your Project by calling
mari.ExtensionPack.selection_group.getVisibilitySets()
forceInPathSearch (bool):
Optional.Defaults to False.
If turned on a Selection Group Name containing a hierarchy (e.g /car/wheel/rims)
will be split for processing to contain only the "groups".
With this option turned on the selection group name that will be processed
for searching in this example is /car/wheel
forceInObjectSearch (bool):
Optional.Defaults to False.
If turned on a Selection Group Name containing a hierarchy (e.g /car/wheel/rims)
will be split for processing to the last part.
With this option turned on the selection group name that will be processed
for searching is /rims
emptySearchReturnsTrue (bool):
Optional. Defaults to False
If the user provides an empty string, usually this automatically returns False
Which this flag set, the return Value is True (if other flags such as Selection Mode
etc. also match)
The dictionary contains two additonal Keys
"Subtractive":
It's value being a list of UUIDs that are matched by the
minus (-) operator
"Globals":
Globals contains a dictionary of modified global default values.
Global default values are for example the arguments,
default_groupmode_list,default_visibility_modelist,
default_active_modelist and default_materialID_list.
As these defaults can be modified by search strings,
for additional processing the new defaults are returned as well.deleteAll()
Delete All Selection Groups matching type (object, patch etc.)deleteUnused()
Will delete any Face Selection Group that does not belong to any
Object or Object Version in your Project (greyed out selection group).
If the parent object exists anywhere iny our scene (e.g. as an object version)
the Selection Group will be keptgetVisibilitySets()
Retuns a dictionary with defined Visibility Sets in the
current project
dict: Returns a Dictionary with all Visibility Sets (lowercase)
Each Dictionary Key contains the Pretty Name and
a List with all Selection Groups of the Visibility Set.
Each Selection Group has a list with [Name,GroupType,Visibility]hideAll()
Hide All Selection GroupshideUnselected()
Hide unselected Selection GroupsinvertVisibility()
Inverts the visibility of selection groupslockAll()
Lock All Selection GroupsremoveMaterialIDOverride(SelectionGroups)
Removes a Material ID Override on the provided Selection Group(s)
SelectionGroups (list): A list of selection Groups to apply the override tosetMaterialIDOverride(SelectionGroups, color)
Sets a Material ID Override on the provided Selection Group(s)
Other than setMaterialIDColorByDialog this works via API
SelectionGroups (list): A list of selection Groups to apply the override to
color (list): A list of 4 values - [R,G,B,A] - from 0 to 1showAll()
Show All Selection GroupsunlockAll()
Unlock All Selection GroupscombineSelectionGroups()
Launches the "Combine Selection Groups" DialogdeleteAll_containingName()
Delete All Selection Groups matching or containing a stringmaterialID()
Launches the "Material ID from Selection Groups" DialogmultiRenameSelectionGroups()
Opens a Dialog to rename Selection Groups with multiple optionssearchAndReplaceNames()
Rename selection groups with a search and replacesetMaterialIDColorByDialog(selGroups=None)
Spawns a dialog that lets the user set custom ID Colors for Selection Groups
selGroups (list): A list of optional selection Groups, otherwise the current selected one is useddeleteQuickVisibilityToolbar()
Removes the Quick Visibility Toolbar from the Selection Group PalettedisableQuickVisToolbar()
Disable all UI Elements of the Quick Vis ToolbarenableQuickVisToolbar()
Enable all UI Elements of the Quick Vis ToolbarinitializeQuickVisToolbar()
Reinitializes the Quick Visibility Toolbar.
with Project specific Search History and Visibility Sets.
Get's called on Project openinstallQuickVisibilityToolbar()
Adds a Quick Visibility Toolbar to the Selection Group PalettequickVisibilityWidget()
Returns the Main Widget of the Quick Visibility Toolbar in the Selection
Group Palette
QHBoxLayout: the main Layout of the new Quick Vis Toolbar
or None.saveQuickVisSettings()
Saves the settings of the Quick Vis Toolbar e.g.
Combobox History, Material ID Filters, Visibility Sets
Triggered usually on Project saveupdateMaterialIDFilters()
Updates the Material ID Filter List
in the Quick Vis Toolbar based on existing
Material ID Overrides on Selection Groupsmari.ExtensionPack.shader()
Shader related methodsselectLastShader()
Tries to toggle to the last used shadersyncObjectShaderSelection()
Syncs all shader selections on all objects in a project to the current shader nameselectLastShader_monitorShaderChangesOnGeoAdded()
Sets up a signal to monitor shader changes when a new piece of geo is addedselectLastShader_monitorShaderChangesOnProjectOpen()
Sets up a signal to monitor shader changes when a project is oppenedmari.ExtensionPack.shaderPreset()
Methods related to the Shader Preset systemremoveShaderPreset()
Removes a shader preset based on the selected shader.
This removes any prese that is saved for the current shader typerestoreShaderChannelInputsFromPreset()
If a preset matching the type of the selected shader is found, this will restore
all shader inputs to the saved preset based on channel names
If a channel matching the channel name in the preset is found, it will be assigned to the
corresponding shader inputrestoreShaderDefaultInputs()
With a shader selected in the Shader Palette, this will restore the shader to the state
it was before "setNodesToShader" method was first usedrestoreShaderParametersFromPreset()
If a preset matching the type of the selected shader is found, this will restore
all shader attributes to the saved presetsaveShaderPreset()
Stores a shader preset from the selected shader
Shader presets contain all settings and channel input assingments of the selected shader.
The preset is saved based on the currently selected shader type (e.g. arnold, vray etc.)setNodesToShader()
With a shader selected in the Shader Palette, selected Nodes in the Nodegraph will be checked
if they contain any names of channels that have been previously saved in a shader preset.
If a channel name is part of the Nodename the Node will be assigned to the corresponding channel inputmonitorShadersOnGeoAdded()
Adds a signal monitoring to a new object in a project so we can detect if a new shader is added
and compare it on creation if a preset needs to be appliedmonitorShadersOnProjectOpened()
Adds a signal monitoring to each object in a project so we can detect if a new shader is added
and compare it on creation if a preset needs to be appliedmari.ExtensionPack.shading()
Shading related methodsdisableViewport(mode)
Turns the spinning wheel on in the Mari viewport to pause viewport updates
mode (str): "iconOnly" will only set the action icon to enabed/disabled (toggle) without actually launching anything.
This is to handle any python action that doesn't directly call the disableViewport Action.mari.ExtensionPack.shelf()
Shelf methods for standard Mari Shelf SystemcreateItem(shelf, item_type, item, ForceImmediateLoad=False)
Wrapper for Mari's createItem and createItemType Functions
Mari 6 overloaded the shelf.createItem() function and going forward
Mari will use shelf.createItemType() instead.
This Wrapper deals with the differences for one single function call within
tools
shelf (mari.shelf): The Shelf to create the Item in
item_type (ShelfManager.ItemType): The type of the item to create a shelf item for.
Valid Items currently are:
- mari.shelves.SHELF_ITEM_MATERIAL
- mari.shelves.SHELF_ITEM_IMAGE
- mari.shelves.SHELF_ITEM_COLOR
- mari.shelves.SHELF_ITEM_BRUSH
- mari.shelves.SHELF_ITEM_COLOR_PROCEDURAL
- mari.shelves.SHELF_ITEM_PROCEDURAL_MASK
- mari.shelves.SHELF_ITEM_SCALAR_PROCEDURAL
- mari.shelves.SHELF_ITEM_SCRIPT
- mari.shelves.SHELF_ITEM_UNKNOWN
Please see Mari Python Documentation as more item types
might have been added in the meantime.
item (variant): A valid path to a file, a mari.Image Object,a mriColor, Script or
Brush XML. Depending on Type different file extensions
are supported. See Python Help createShelfItemType() for more info
forceImmediateLoad (bool): Force loading custom procedural and material items in a foreground
process. Defaults to False.
ShelfItem: The newly created shelf item or NonedeleteAllUserMariShelves()
Deletes all custom Shelf Tabs inside the Standard Mari Shelf SystemgroupShelf(shelf, groupname)
This method will be deprecated in a future version.
It is a temporary wrapper to restore support for Mari 7.5 Beta 1 which has issues
with grouping shelves
Wrapper for mari.shelves.groupShelf()
groupname (str): The Name of the Group to put the shelf undercreateShelfFromFolder_UI()
Launches a UI to create Shelves from FolderscreateAdditionalShelfUIElements()
Modifies the standard Mari Shelves UI and adds new buttonsmari.ExtensionPack.splashScreen()
Splash ScreensplashScreenConnectionTimeOut()
Returns the Connection Timeout for loading Splash Screen Content
from the Mari Preferences (Misc/Internet)
This can be overwritten with the Environment Variable
MARI_EP_SPLASHSCREEN_CONNECTION_TIMEOUT
The value is set to 0.5 by default
This setting controls the timeout before Extension Pack
a) forces the Splash Screen to Offline Content Mode
b) how long it waits to retrieve content if not in offline modeshowSplashScreen()
Launches the Splash ScreenshowSplashScreen_ifAllowed(Force=False)
Launches the Splash Screen if the user allows it / checkbox is set
Force (bool): If True the Splash Screen will always be shown,
even if the user deactivated the "Show On Startup" OptionaddSplashScreenTimeoutPreference()
Adds a Connection Timeout Preference to
the Mari Preferences Misc Tab.
This setting controls the timeout before Extension Pack
a) forces the Splash Screen to Offline Content Mode
b) how long it waits to retrieve content if not in offline modechangeSplashScreenTimeoutPreference()
Updates stored settings for the Connection Time Out Preference in
the Mari Preferences Misc Tab.
This setting controls the timeout before Extension Pack
a) forces the Splash Screen to Offline Content Mode
b) how long it waits to retrieve content if not in offline modecreateOfflineThumbnailsFromJson()
Will download Thumbnails into Resources/Spash
for use with the Splash Screen if no internet is availablemari.ExtensionPack.symmetry()
This class is deprecated and will be removed in the future
Symmetry related methodsactivateSymmetryX()
This method is deprecated and will be removed in the future
Activates Symmetry Bake in Mari X AxisactivateSymmetryY()
This method is deprecated and will be removed in the future
Activates Symmetry Bake in Mari Y AxisactivateSymmetryZ()
This method is deprecated and will be removed in the future
Activates Symmetry Bake in Mari Z AxissetSymmetryMode()
This method is deprecated and will be removed in the future
Toggles between different Symmetry Modesmari.ExtensionPack.text()
Text Tool related methodstextGenerator()
Launch the EP Text Generatormari.ExtensionPack.textureSet()
Texture Set Palette related toolscreateHardRef()
This fixes a bug in the Mari own texture set palette
Inside the MegascanWidget() class that can be found at
..puppetshare/software/Mari/extracted/$VERSION/Media/Scripts/Mari/system
/megascans.py
is a variable defined:
controlLayout = FlowingVerticalLayout()
The variable is not defined as a class variable (self.controlLayout).
Sometimes when resizing palettes, mari "looses" the top layout controlling
Filterelements and Categories, because elements of the FlowingVerticalLayout()
are being garbage collected.
We grab it directly from the MegascanWidget Layout (it's at position 0),
then reassign it to a class variable inside the MegascanWidget.
This in theory should be enough to establish a proper parent relationship,
preventing it from being garbage collected
Another issue is the __del__ function inside the FlowingVerticalLayout() class
which recursively deletes items from
an internal class variable (item_list).
Instead of the takeAt() method applied at the moment we directly assign an empty
list to the class variablemari.ExtensionPack.toolbar()
methods that get called from toolbarsalignLocatorToView()
aligns a locator to the current camera viewflipPaintThroughImage_Horizontally()
Flips a PaintThrough Image HorizontallyflipPaintThroughImage_Vertically()
Flips a PaintThrough Image HorizontallyforceActivateTransformTool()
Activates the "Transform Selected Objects" Tool in a way that it skips any potential dialog pop-upsscaleAndCenterLocator()
Scales the current locator to fit the object it belongs to and center on objectaddOptionsToPaintThroughToolbar()
Adds Extension Pack Options to the Paint Through Toolbar.
This is not building signal connections and is safe for repeated
execution.
This method is mostly called by drag and drop events where the
classic tool switch signal is not fired.addProjectionModeOptions(addSeparator=True)
Adds UI elements for Projection Mode and Target
addSeparator (bool): if to separate the new UI elements with a separator linechangeProjectionModePreference()
Executes a change in Preferences from the Painting Tab of the Preferences to display Projection ModeschangeToolsToolbarPreference()
Launches an operation to edit the DefaultToolbars.conf file when the setting is changedcreateProjectionModePreference()
Adds Preferences to the Painting Tab of the Preferences to display Projection ModescreateToolsToolbarPreference()
Adds Settings to the Preferences to control the appearance of the Mari Tools Toolbardelete_quick_transform()
Force deletes any open quick transform toolforce_update_quick_transform_ui()
Can be used to force update the "Quick Transform" Widget
with current Object or Locator Transformations.
The Quick Transform Widget is shown while the "Transform Selected Object" Tool is active.
The Method should be called from any external tool that applies python based transforms to
tools, in order to keep the Widget Data shown to the user (Translation,Scale,Rotation) in sync
with what the user sees.
If you use mari.ExtensionPack.matrix.setTransform() or setTransformFast(), this is called automaticallyhideProjectThroughWarning()
Forces the Projection "Through" Warning (a red box around the viewport) to offinitialize_Locator()
If a Node or Layer supporting Locators is selected while the Transform Object Tool
is activated, I jump to a locator. If none exists a new one is created with the existing
transforms of the Locator List
This method sets up the necessary Signalsinitialize_PaintThroughToolbar()
Adds Extension Pack Options to the Paint Through Toolbar when
Paint Through Tool is activated. It buils a signal connection, so should
not be executed repeatedlyinitialize_SyncedBufferDepth()
Turns on Buffer BitDepth Syncing on a new session if it was active on previous session close
Buffer BitDepth Syncinc will constantly switch the paint buffer bit depth to the
bit depth of the currently selected paint target.
It buils a signal connection, so should
not be executed repeatedlyinitialize_TransformPaintToolbar()
Adds Extension Pack Options to the Transform Paint Toolbar.
It buils a signal connection, so should
not be executed repeatedlyinitialize_quicktransform_signals()
Creates Signal Connections to Tools
to trigger hide/show of the quick transform widget in the viewport depending on which tool is activeinitialize_transformObjectToolbar()
Adds Extension Pack Options to the Transform Object Toolbar.
It buils a signal connection, so should
not be executed repeatedlyloadProjectionModePreference()
Loads Preferences from the Painting Tab of the Preferences to display Projection ModesloadTransformObjectToolbar()
Manually load Extension Pack Items into the transform object toolbar
without building additional signal connections.
Useful in caes where the toolbar is opened without having been the result
of an action triggersaveProjectionModePreference()
Saves Preferences from the Painting Tab of the Preferences to display Projection ModessaveToolsToolbarPreference()
Saves the State of preferences to control the appearance of the Mari Tools Toolbarsetup_object_transform_reset_signal()
Creates a signal connection to mari's "Reset Object Transformation" Action.
If called the "Quick Transform UI" is (Visible when the Transform Selected Objects Tool is active)
gets refreshedsyncProjectionModeOptions()
Can be called to sync the state of the Projection Mode (Front,Through) and Target (all, selectedOnlu)
to the state of the properties in the Painting Palette
Returns:
Nonemari.ExtensionPack.utils()
Various Python Helper MethodsTDRCheck()
Runs a TDR Check on windows system and shows a warning to the user if the settings are not recommended
Doesn't do anything if settings are ok or on Linux or Mac
(bool): Returns True if the Dialog was accepted or False if the Dialog was rejectedchangeFileOwnership(path)
Linux Only: changes a file ownership to the current user
path (str): A path to a file or foldercloseAllOpenProgressDialogs()
Closes any open progress Dialogs from the utils.progressDialog() methodcopytree(src, dst, symlinks=False, ignore=None, copy_function=
Recursively copy a directory tree.
Reimplementation due to permission copy issue
The destination directory must not already exist.
If exception(s) occur, an Error is raised with a list of reasons.
If the optional symlinks flag is true, symbolic links in the
source tree result in symbolic links in the destination tree; if
it is false, the contents of the files pointed to by symbolic
links are copied. If the file pointed by the symlink doesn't
exist, an exception will be added in the list of errors raised in
an Error exception at the end of the copy process.
You can set the optional ignore_dangling_symlinks flag to true if you
want to silence this exception. Notice that this has no effect on
platforms that don't support os.symlink.
The optional ignore argument is a callable. If given, it
is called with the `src` parameter, which is the directory
being visited by copytree(), and `names` which is the list of
`src` contents, as returned by os.listdir():
callable(src, names) -> ignored_names
Since copytree() is called recursively, the callable will be
called once for each directory that is copied. It returns a
list of names relative to the `src` directory that should
not be copied.
The optional copy_function argument is a callable that will be used
to copy each file. It will be called with the source path and the
destination path as arguments. By default, copy2() is used, but any
function that supports the same signature (like copy()) can be used.correctPath(path)
fixes common path slash issues.
Also accounts for server paths.current_notification()
Retrieves the current notification widget or None
QFrame Returns the Notification Class or Nonedelete_current_notification(do_not_animate=False)
Deletes the currently open notification
do_not_animate Optional,defaults to False.
If True, the open Notification will be deleted immediately
instead of sliding out of viewfindTriggerAction(actionpath)
Given a Mari Action path, this command will find and trigger the action
actionpath (string): a mari action path to triggerforceFocusReturn()
Returns the Focus to Mari and the Widget the Cursor is over
Other than standard qt setFocus(), this also ensures that the correct
Hotkey Context is set, so Mari is accepting shortcuts again without delay.
This is useful if you have launched a modal dialog and after it closes Mari is not
accepting Key Presses until a second or so later the focus system returns the focus
and activates correct contexts.
By calling this method you save the 1 second delaygetChildren(obj)
Returns all children of a given object recursively
obj (dict): a parent object
list: a list of all childrengetImageAttributeNames()
Returns a list of Image Attributes used in Mari Nodes.
Useful if you need to check for Images on Nodes
(list): a list of attribute names for nodes that use those names for image attributesgetMariSettingsFolder()
Returns the Location of the Mari config file.
The path is detected based on the existence of the unpremultiplyAlpha file
in the settings folder, since mari by default does not have an option to
detect that setting folder via API
(string): Path the the Mari User Settings FoldergetStyle(stylefile_name, **style_options)
Returns a stylesheet from a specified filename.
It adds support for tokenreplacement while allowing for specifying default values
inside the loaded qss file.
Example:
>> border: {border_width:2}px solid {border_color:#3498db};
tokens are border_width and border_color.
>> getStyle("qss_name", border_width=10)
will return the stylesheet as
>> border: 10px solid #3498db;
-------------------------------------
Usage:
checkable_button = mari.ep.utils.getStyle(
"QPushButton",
border_style="solid",
border_color="#5f636a",
font_size="11",
font_weight="bold",
border_width="1",
border_radius="10",
background_color="#333333",
hover_background="#666666",
hover_border_color="#a3aab6",
pressed_background="#333333",
pressed_border_color="#5f636a",
checked_background="rgba(180,0,0,255)",
checked_hover_background="rgba(200,30,0,255)",
)
stylefile_name (str): The pure name of the style file, without extension
style_options: Override default styling parameters
(string): The stylesheet from the file with tokens replacedgetUIScaleFactor()
returns a scale factor for UIs based on Maris Custom Font Size Setting
(float): A Scale FactormariIsShuttingDown()
Returns True or False if Mari has entered its shutdown procedure.
This can be useful to prevent "patched on" widgets that are not native to Mari's UI from having their functions
called (e.g. size hints) during the shutdown procedure which has caused non-clean mari exits
(python errors on exit) before
bool: True if mari.app.exiting has been initiatedmariMainWindowObject()
This returns the Mari Main Window Object or None if not found
(QDialog): Returns the Mari Main Window Object if found
or None if not foundmariViewport()
This returns the current Mari Viewport
WARNING: You MUST call stopViewportTracking() when you are done with the viewport
to prevent garbage Collect issues !
(QOpenGlWidget): Returns the Mari Viewport Widget if found
or None if not foundmessage(text, title='[EP] ', buttons=PySide2.QtWidgets.QMessageBox.StandardButton.Ok, icon=PySide2.QtWidgets.QMessageBox.Icon.Information, details=None, defaultButton=None, parent=None)
Wrapper for mari.ExtensionPack.utils.message that prefixes [EP] to the Title BarmessageResult(text, title='[EP] ', buttons=PySide2.QtWidgets.QMessageBox.StandardButton.Ok, icon=PySide2.QtWidgets.QMessageBox.Icon.Information, details=None, defaultButton=None, parent=None)
Wrapper for mari.ExtensionPack.utils.messageResult that prefixes [EP] to the Title Barnotification(buttons=None, header_text='Header', info_text='Info', detail_text='Detail', min_notifier_width=400, min_notifier_height=170, allow_dynamic_notifier_size=True, header_pointsize=10, info_pointsize=9, detail_pointsize=9, btn_pointsize=8, notification_type='message', custom_notification_color=None, custom_text_color=None, custom_button_color=None, notification_color_width=24, notification_position='bottom left', notification_animation_type='horizontal', animation_show_duration=300, animation_hide_duration=300, timeout_notification=False, notification_timeout_length=5000, timeout_progress_color=None, background_color='rgba(60, 60, 60, 80%)', distance_from_edge=5, always_remove_previous_notification=True)
Notification Widget to display info to the user directly in the viewport without blocking Mari.
The Notification Widget allows adding QPushButtons with Callback Functions to execute operations.
Only one Notification can at any time be shown. If a new Notification is triggered, the previously
shown one will first be hidden.
Please refer to /Extension Pack/Resources/PythonExamples/Notification.py for a full example
buttons (dict): Optional. Defaults to None
Allows you to add buttons to the Notification that can
execute callback functions.
Below is an example Dictionary:
{"Btn with callback+tooltip" : ["print(
'test')", "Load new Model Version"],
"Stretch" : [],
"Btn with tooltip+icon" : ["None",
"iconToolTip","iconPath"],
"SpacerItem01" : [],
"SpacerItem02" : [],
"Ignore": ["Close"] }
The dictionary entries are formatted as:
BUTTON_NAME :
[stringified_callback,tooltip,icon]
Instead of a callback functions you can also provide one of the
following words (case-insensitive to execute a "Notification close":
close, abort, cancel
To give an empty callback pass in
"None" (as string)
A tooltip is optional.
However if you provide an icon path, a
tooltip is expected (even if empty string)
header_text (str): Optional. Defaults to None. The Header Text is displayed as a bold
headline on the Notification. If None, no Header is displayed
info_text (str): Optional. Defaults to None. The Info Text is displayed as normal
text below the headline.If None, it is not displayed
detail_text (str): Optional. Defaults to None. The Detail Text is displayed as italic
text below the info_text.If None, it is not displayed
min_notifier_width (int): Optional.Defines the minimum width in pixels of the Notification
widget. Defaults to 400.
min_notifier_height (int): Optional. Defines the minimum height in pixels of the Notification
widget. Defaults to 170
allow_dynamic_notifier_size (bool): Optional. Defaults to True. If False, then the size of the widget
is 100% determined by the min_notifier_width and height arguments.
If True (Default), then the widget is allowed to upscale past
these minimum values. The amount of horizontal and vertical scaling
is determined by the Font Metrics of the supplied text (e.g.
Header, info text and detail text)
header_pointsize (int): Optional. The Font Pointsize of the Header. Defaults to 10
info_pointsize (int): Optional. The Font Pointsize of the Info Text. Defaults to 9
detail_pointsize (int): Optional. The Font Pointsize of the Detail Text. Defaults to 9
btn_pointsize (int): Optional. The Font Pointsize of any button Text. Defaults to 8
notification_type (str or None): Optional.The notification type adds a color coded vertical bar
on the left side of the widget. The color can be overwritten with
the custom_notification_color argument still. Defaults to "message"
We have three presets by default:
"info: a yellow vertical bar
"error: a red vertical bar
"message: a blue vertical bar
None: The vertical bar is not displayed
custom_notification_color (str or None): Optional. Defaults to None. If not None and the notification_type
argument is something different than None, then this argument
allows you to define a custom color for the vertical color bar
of th widget. The color is supplied as a stylesheet value e.g
"#2d64e0" or "rgba(0,0,0,255)"
custom_text_color (str or None): Optional. Defaults to None. If not None then this argument
allows you to define a custom color for the text
(header,info,detail) of the widget.
The color is supplied as a stylesheet value e.g
"#2d64e0" or "rgba(0,0,0,255)". If None,then a neutral gray is used.
custom_button_color (str or None): Optional. Defaults to None. If not None then this argument
allows you to define a custom color for the callback buttons
of the widget.
The color is supplied as a stylesheet value e.g
"#2d64e0" or "rgba(0,0,0,255)". If None,then a neutral gray is used.
notification_color_width (int): Optional. Determines the width of the vertical color bar indicating
the type of Notification (e.g error, info etc.). Defaults to 24.
notification_position (str): The position where the Notification should appear. Valid options are
"top left","top right","bottom left","bottom right","top center",
"bottom center"
notification_animation_type (str): Optional. Determines the way the notification appears e.g.
sliding into the view vertically or horizontally.
The two options are "horizontal" or "vertical". Defaults to
"horizontal"
animation_show_duration (int): Optional.The time in ms it takes for the animation of the Widget
show process to complete. Defaults to 300.
animation_hide_duration (int): Optional. The time in ms it takes for the animation of the Widget
hide process to complete. Defaults to 300.
timeout_notification (bool): Optional. If True, the notification will auto-hide after the time
specified in the notification_timeout_length argument.
A circular progress bar will be displayed around the "X" close btn.
If False (default), the notification will not auto-disappear unless
a second notification is triggered somewhere.
notification_timeout_length (int): Optional. If timeout_notification is True, this specifies the time
in ms until the Notification auto-disappears. Defaults to 5000
timeout_progress_color (tuple): Optional. Color of the timeout progress wheel.
Defaults to None, which will result in a default
Value (45, 100, 224)
background_color (str): Optional. The Stylesheet Background color of the Widget
Defaults to "rgba(60, 60, 60, 80%)"
distance_from_edge (int): Optional. The distance of the notification from the viewport edge.
Defaults to 5.
always_remove_previous_notification (bool): Optional. If to delete any previously open notifcation first
before showing a new one.
Defaults to True.
QFrame: Returns the Notification WidgetopenFileBrowser(path, directoryOnly=True, iteratePathUntilFound=True)
open file browser in path location or run file if path is a file name
path (string): A path to a file or folder
directoryOnly (bool): If True,only allows to open paths that are directories
iteratePathUntilFound (bool): If true, the method will step up the file folder structure if
the provided path does not exist, until a valid path is foundprogressDialog(maxStepsPrimary, showSecondaryBar=False, maxStepsSecondary=0, windowTitle='Progress', initialInfoMsg='', initialStatusMsg='', autoClose=True, showAbortMessage=False, AbortMsg='', AbortTitle='', MinWidth=400, parent=None)
Returns a progress Dialog than can be shown with object.exec_() or object.show().
maxStepsPrimary (int): The Maximum Number of Steps of the Primary Progress bar
showSecondaryBar (bool): Optional: If True, a secondary Progress Bar will be shown
maxStepsSecondary (int): Optional: The Maximum Number of Steps of the Secondary Progress bar
windowTitle (str): Optional: The Title of the Progress Bar Window
initialInfoMsg (str): Optional: The Info Message set when the dialog starts
initialStatusMsg (str): Optional: The Status Message set when the dialog starts
autoClose (bool): Optional: If True, when the Max steps are reached, the dialog will close
showAbortMessage (bool): Optional: If True, if the dialog is aborted a message will be displayed
AbortMsg (string): Optional: The Message in the Abort Dialog
AbortTitle (string): Optional: the title of the Abort Dialog
MinWidth (int): Optional: Dialog Width
parent : Optional: Window Parent
QDialog: Returns the Progress Dialog Window
------------------------------------------------------------------------------------------
dialog.evaluatePrimaryProgress(): checks if current Progess Bar Steps are equivalent to max steps
If they are the progress bar is closed if autoClose parameter is set
dialog.evaluateSecondaryProgress(): checks if current Progess Bar Steps are equivalent to max steps
If they are the progress bar is closed if autoClose parameter is set
dialog.closeProgressBar(): Will close the Progress Bar
dialog.nextPrimaryStep(): Adds +1 to the Progress Bar Steps processed
dialog.nextSecondaryStep(): Adds +1 to the Progress Bar Steps processed
dialog.setNewMaxPrimaryStep(value): Sets a new Maximum Range for the dialog
dialog.setNewMaxSecondaryStep(value): Sets a new Maximum Range for the dialog
dialog.setPrimaryStepsTaken(value): Sets the current Steps Taken Value. You can also use nextStep()
dialog.setSecondaryStepsTaken(value): Sets the current Steps Taken Value. You can also use nextStep()
dialog.updateStatusMessage(msg): Changes the Status Message
dialog.updateInfoMessage(msg): Changes the Info Message
dialog.updateAbortMessage(msg): Change the Abort Message
dialog.updateAbortWindowTitle(msg): Update the title of the Abort Message
dialog.isAborted(): Returns if the Dialog has been aborted by the user
dialog.cancelDialog(): Closes the Progress Bar.sanitizeText(text, sanitizeSlashes=False, removeWhiteSpace=True, customCharacters=None)
Removes invalid characters from given text.
Invalid Characters are by default: #$%^&*{|}:!?
If sanitizeSlashes Argument is given this also includes \/
text (str): a string to sanitize
sanitizeSlashes (bool): Defaults to false.
if True, \/ will also be removed.
removeWhiteSpace (bool): Defaults to True.
If True, trailing and leading white spaces
are removed
customCharacters (str|None): If not None, the given characters will be used to clean
the text, instead of the internally defined ones.
string: Returns the sanitized textsearchInString(search_for, search_in)
The search algorithm parses a given string
against a search string with complex filtering options.
The search string offers a variety of operators:
SIMPLE WORD FILTER OPERATORS
+ (plus) , (comma) and ! (except) act as modifiers for words and
can be combined e.g. "wheel+cart+!horse" or "wheel+cart+!horse,car"
Both produce True for Selection Group Names containing "wheel" and "cart"
but not "horse", while the second option also produces True for elements
containing "car"
SUBTRACTION:
- (minus) acts like a global subtraction. E.g. -blue,yellow,green will be the same
as yellow+!blue,green+!blue
search_for (str): The Search String to search the tags against
search_in (str): the string to search in
emptySearchReturnsTrue (bool): Optional. Defaults to False
If the user provides an empty string, usually this automatically returns False
With this flag set, the return Value is Truesetting_str_to_bool(settings_value, invalid_defaults_to=False)
Converts a value from the Mari Settings from a String to a boolean value
settings_value (str): The string read out from an init or config file
invalid_defaults_to (bool): Optional. Defaults to False. Determines what the "invalid"
or None value should be converted to
bool Returns True or FalseshortenText(text, characterLimit=50, shortenStart=False, short=' ... ')
Shortens a given text so it doesn't exceed the specified characterLimit.
Excess characters are replaced by three dots e.g. "this is a ..." or
"... long text" (if shortStart is True)
text (str): the text you want to shorten
characterLimit (int): Optional. The maximum number of characters in the given text
after which the shortening should kick in
shortStart (bool): Optional. By default the shortening happens at the end of the text
e.g. "this is a very long text" becomes "this is a very ...".
If this argument is True, instead the shortening happens at the
start e.g. "this is a very long text" becomes "... very long text"
short (str): Optional. The string to substitude excess characters with.
Defaults to " ... ".
(string): Returns the shortened textstopViewportTracking()
Releases an instance of the Mari Viewport aquired my mariViewport()
so it can be properly garbageCollected.
WARNING: This method MUST be called when you are done with the Mari ViewportwindowOffsetPosition(useSafeMargin=True, paddingList=None, offsetList=None)
Returns positional coordinates to move a window to the cursor to.
By default with a safe area from the corners of the application,
as to prevent dialog opening half off screen.
useSafeMargin (bool): if true, a safe margin is used to move the window away from
paddingList (List): A list of 4 float values to define the pading
around the corners if useSafeMargin in on.
If the cursor is within the Padding, the Offset from
the OffsetList will kick in.
[fromLeft,fromTop,fromRight,fromBottom]
If NONE, will default to [200.0,150.0,150.0,150.0]
offsetList (List): A list of 4 int values to define the offset
from the corners if useSafeMargin in on.
If NONE, will default to [200,150,-200,-150]
offsetlist = [fromLeft,fromTop,fromRight,fromBottom]
tuple (int,int): The Offset CoordinatesquickCommandLauncher()
Opens a Maya style Quick Launcher dialog allowing you to execute
any mari actionshortcutResolveDialog(mode='help')
Opens a Dialog to resolve Mari vs EP Shortcut conflicts.
Mari 7.1 or higher only.
mode (str): Determines the mode this dialog is launched in.
"startup" : This is for when the dialog is called after Mari Launch.
A series of checks is run if and what do display in the Dialog.
"help": This (or any other string) triggers the dialog to launch in "full"
mode displaying all possible options. This is called when launching
it from the help menu.mari.ExtensionPack.version()
Methods to determine Extension Pack VersionsbuildVersion()
returns the build Version
(int): The Build Version of the current EP VersioncheckResourceVersion()
Checks if the currently loaded Resources are the right ones to use with this EP VersiondevToolsVisible()
Returns if the current Version should show Dev Tools
(bool): True if Dev Tools should be shownisAlphaVersion()
Returns if the current Version is marked as an Alpha Version
(bool): True if it is an Alpha VersionisBetaVersion()
Returns if the current Version is marked as a Beta Version
(bool): True if it is a Beta VersionisDevVersion()
Returns if the current Version is marked as a Dev Version
(bool): True if it is a Dev VersionisNewVersionAvailable(debugMode=False)
Runs an online check if a new version is available
debugMode (bool): Ability to Locally test a Version File under Tools/Dev/Splash_Dev_Content/
(dict): A Dictionary containing the following info:
versionDict['newVersionAvailable'] (bool)
versionDict['patchAvailable'] (bool)
versionDict['CurrentVersion']
versionDict['CurrentVersionAsInt']
versionDict['CurrentVersionPretty']
versionDict['RichText_Release_Notes_Link']
versionDict['HelpFile_ReleaseNotes_Link']
versionDict['ReleaseVideo_Link']
versionDict['IsPaidVersionUpgrade'] (bool)
versionDict['UpgradeInfo_HelpLink']
versionDict['ExtraInfo']isReleaseCandidateVersion()
Returns if the current Version is marked as a Release Candidate Version
(bool): True if it is a Release Candidate VersionlaunchVersionCheck()
Checks if a new Version of Extension Pack is available
and returns a messagemajorVersion()
returns the Major Version
(int): The Major Version of the current EP Versionmari45OrAbove(invert=False)
This method will be deprecated in a future version.
Returns true if Mari 4.5 or higher
invert (bool): Inverts the result
bool: True or False if version is highermari46OrAbove(invert=False)
This method will be deprecated in a future version.
Returns true if Mari 4.6 or higher
invert (bool): Inverts the result
bool: True or False if version is highermari46v4orAbove(invert=False)
This method will be deprecated in a future version.
Returns true if Mari 4.6v4 or higher
invert (bool): Inverts the result
bool: True or False if version is highermari47OrAbove(invert=False)
This method will be deprecated in a future version.
Returns true if Mari 4.7 or higher
invert (bool): Inverts the result
bool: True or False if version is highermari47Ov2rAbove(invert=False)
This method will be deprecated in a future version.
Returns true if Mari 4.7 or higher
invert (bool): Inverts the result
bool: True or False if version is highermari48OrAbove(invert=False)
This method will be deprecated in a future version.
Returns true if Mari 4.8 or higher
invert (bool): Inverts the result
bool: True or False if version is highermari48v2OrAbove(invert=False)
This method will be deprecated in a future version.
Returns true if Mari 4.8 or higher
invert (bool): Inverts the result
bool: True or False if version is highermari70v1orAbove(invert=False)
Returns true if Mari 7.0 or higher
invert (bool): Inverts the result
bool: True or False if version is highermari70v2orAbove(invert=False)
Returns true if Mari 7.0v2 or higher
invert (bool): Inverts the result
bool: True or False if version is highermari71v1orAbove(invert=False)
Returns true if Mari 7.1v1 or higher
invert (bool): Inverts the result
bool: True or False if version is highermari75v1orAbove(invert=False)
Returns true if Mari 7.5v1 or higher
invert (bool): Inverts the result
bool: True or False if version is higher
minorVersion()
returns the Minor Version
(int): The minor Version of the current EP VersionpatchVersion()
returns the patch Version
(int): The patch Version of the current EP VersionrecommendedEPResourceVersion()
Returns the Resource Version associated to this Install of Extension Pack
(int): The Version Number of the Resources that neds to correspond
to the Version Number of the Resources found in Resources/ResourceVersion.epversion()
returns the full version consisting of major,minor and patch
(int): A full version number of EP as integer e.g. 6001versionAsJson(jsonfile=None)
returns Path to Json file containing current Version Info
jsonfile (string): A custom file name to search for,
otherwise (if None) it defaults to the
predefined version json name in use by EP
(string): The path to the Json FileversionPrettyName()
returns the Pretty Version Name
(string): The full written out, nice version of EPmari.ExtensionPack.view()
View related methodssetViewBackgroundTheme(theme='Default')
Set a View Background Preset
theme (string): the name of the preset.
Available options are:
"Default"
"NeutralGray"
"NeutralGray_Gradient"
"DarkGray"
"Dark"
"Dark_Gradient"
"HighContrast_Gradient"
"Steel"checkProjectionLocks(ignore_settings=False)
Runs a check if
- No Object is selected
- An Object is selected but it is locked
- Selection Groups on the current Object are locked
- Patches on the current Object are locked
- Current Layer is locked
If any of those return True, a notification will be shown in the viewport
allowing the user to unlock.
The checks can be disabled one by one or all together via the Mari Preferences /
Painting Tab / Projection Warnings Group.
If the ignore_settings argument is True , those settings will be ignored
and all checks are run. If False (default), only the checks are run that are turned on in the
preferences
regardless if they are enabled in the Mari Preferences.
If False (Default), then only checks are run that are
enabled in the Preferences.screenshot_all_channels()
Screenshot all channelscreateViewportNotifierPreferences()
We add adjustable Preferences to the Mari Preferences / Painting Tab / Projection Warning
where users can adjust what kind of warnings they wish to see.
These warnings pop up in the Viewport if Paint cannot be projected because of a lock state
being present on the Geo (Object, Patches, Selection Groups, Layers etc.)
This method creates those Preference settings on Mari startdisconnectProjectionWarnings()
Breaks signal connections for the Projection Warning system
These warnings pop up in the Viewport if Paint cannot be projected because of a lock state
being present on the Geo (Object, Patches, Selection Groups, Layers etc.)resetProjectionWarnings()
Resets any temporarily paused Projection Warnings.
These warnings pop up in the Viewport if Paint cannot be projected because of a lock state
being present on the Geo (Object, Patches, Selection Groups, Layers etc.)
Users have the choice to "pause" a Projection Warning for the duration of their Mari
SessionsaveViewportNotifierPreferences()
Saves the current settings of the Viewport Notification Warnings
e.g "Object is locked", "Selection Group is locked" etc.
These warnings pop up in the Viewport if Paint cannot be projected because of a lock state
being present on the Geo (Object, Patches, Selection Groups, Layers etc.)
We add adjustable Preferences to the Mari Preferences / Painting Tab / Projection Warning
where users can adjust what kind of warnings they wish to see.
This method saves the current state of those settings so they can be restored on the
next mari startsetupProjectionWarnings()
Setup signal connections for the Projection Warning system
These warnings pop up in the Viewport if Paint cannot be projected because of a lock state
being present on the Geo (Object, Patches, Selection Groups, Layers etc.)mari.ExtensionPack.web()
Internet related methodsdownloadImageFromWeb(url)
Downloads an image from the web, saves it as a temporary file,
and returns the filepath
url (string) a path to an image file on the web
path (string) a path on disc to the downloaded filegetYouTubeThumbnail(url)
Downloads a thumbnail from youtube, saves it as a temporary file,
and returns the filepath
url (string): a path to a youtube video
path (string): a path on disc to the downloaded thumbnail image