Tools/Free/uMen
From Osipa Entertainment
|
uMen.py
All page contents are © Osipa Entertainment, LLC. This page created manually
This tool is the backbone for everything OE does. uMen (Your Menu) is a tool which builds a menu in Maya that allows for easier creation, editing, sourcing and distribution of mel and python scripts. You could think of it like a partial I.D.E.. Whether you've written them yourself, or found them online, most scripts work in the system right away. The menu also creates automatic UIs inside of maya for your scripts, handles script path management cleanly and easily, has search functionality, automatic in-maya documentation as well as auto-generated wiki pages (most of this site's tool documentation is done that way). This will be one of the only pages you see on this site that was made by hand!
Dependency tracking for uMen is also available through the uMen_deps.py extension.
Features
Free autoUIs
Even if your script is not written for use with uMen's documentation style, it will most likely work just fine inside uMen, even creating an automatic UI for you, with all your variables laid out in way that is easy to read and control. This will all happen in the uMen itself, but to distribute your tool to users who may not have uMen installed (and therefore no autoUI), you can export your autoUI as a new procedure for your script, thereby "hardcoding" that autoUI in and removing uMen as a dependency. (Export is currently MEL-only)
Automatic Variable "Buttons"
No matter what your variable type is, in most cases in the autoUI, there is going to be a button next to it that allows you to use selections of scene objects or attributes to fill in your variable value. For example, if your variable is a string array, the auto-fill put in the box will be your object or attribute selections. If your variable is a number, it will read the attribute values you have selected.
Easy Documentation
By following a very simple tagging convention, your scripts pop up with help documentation built right in the tool! This exact same markup will help you with the wiki feature discussed a few paragraphs down this page...
Instant-ish Script Updates
The menu and UIs are set up to destroy and rebuild themselves every time you open them. As a result, if you add or delete a new root or script, the very next time you look in the menu all your new stuff will already be there - no manual updating or closing-and-opening of maya required. Every time you collapse and reopen a layout, it has been destroyed and rebuilt allowing any changes in your scripts to be represented as fast as can be! (Caveats)
Easy Path Management
By setting roots and only roots through uMen, managing what to include in your script, python and plugin paths becomes nearly automatic. You can create very few settings just once, and call it a day! Down any of your branches, directories with MEL scripts get added to your MAYA_SCRIPT_PATH, directories with MLL files get added to your MAYA_PLUG_IN_PATH, and directories containing PY files get added to both your PYTHONPATH and MAYA_PLUG_IN_PATH.
Simple Branching
Very often, you'll need two or more branches of code. Say you're supporting two teams and the way Team A wants their character rig set up is slightly different than that for Team B. Often, this would mean not just a different rig, but a different set of support scripts, exporters, etc. To make this easy to manage, the order you add your paths in the setup window also dictates the order in which scripts will be sourced/imported and used. This means you can have a main trunk with most of your tools, then as a project needs it's own specifics, you would just make users on that project have their project's branch appear before the main trunk in their setup. Any scripts in their branch will "override" the ones in the main trunk, and anything 'not' in their branch will still be pulled from the main trunk.
Free autoWikis!
Make it look like you slaved away all day making a familiar and functional documentation page for your tool, when really, you only marked up a few things in your script's comments (or didn't!), and then just pressed a button!
uMen autoWikis by default print out in the script editor for you to copy/paste into a page (a good way to do it if you add each tool "as you go" ) but if you want to go back through a catalog of tools, you'll probably want to batch the page creation, right? Well, the good news is that if you wrote a finished-page writer, you could just use the output of the wikiCreator function to get you all your content (it doesn't just print the content, it returns it too) Also, no promises, but we'll probably post the OE batch-wiki-creator here sometime in the future. (Since permissions, setups, and structures can be so very different, this is usually something best handled per-studio)
User customization!
If your intention is to have teams of people hooked up on uMen for your tool distribution, you can create uMen maps - simple to create files which allow you to build up a menu of just the scripts you want, not necessarily whole directories full of scripts. That means you can organize your menu several different ways. You can keep all your scripts organized by type, if you want, but then have just the ones you want to be seen by a user - say, your "animation" scripts, which are just the user-level tools for animators, and they don't have to look at your libraries and other support scripts.
Search
Ever forgotten about a procedure, or forgotten which of your project's million branches, scripts, or libraries you might have put it in? Searching all scripts not just by name, but by their contents, quickly and with lots of feedback helps solve that problem.
Setup
Installation
- Note that a few videos reference "two" mel scripts, there are now three - don't worry!
Download uMen, unpack it (it is a rar file) and then move uMen.py into a valid python directory. (You should see three other files, egDocStyle.mel, egCustomScriptUI.mel and egTrickle.mel in the .rar file - don't move either). To run uMen.py, in Maya's script editor (Python), copy and run this:
import uMen uMen.uMen()
A menu titled "osipaEntertainment" should have appeared in your top Maya toolbar. That's it! uMen is now installed.
You'll probably want to include the above lines in your userSetup.py if you want the menu to automatically load every time you open Maya.
Roots
Before uMen can be of any real use to you, you'll need to create a few script roots for it to look into. A script root is just a directory with some tools/scripts you'd like to get at. You add script roots in the setup window found at osipaEntertainment > setup. Now the setup window should be open.
Create a directory on your desktop called "examples". Unpack egDocStyle.mel, egCustomScriptUI.mel and egTrickle.mel out of the uMen.rar file, and place them all into your new "examples" desktop directory. Copy & Paste the path of your new directory (not the script, the directory) into the path area of the setup window (top left area of the setup window, under the word "Roots"), or use the path button there to browse to the new path. Note that this hasn't really done anything yet except display the path you picked. To actually add the path, press the Add button to the right. The setup window and menu will refresh itself, and the newly added directory will now be available in uMen.
You'll notice that after pressing Add the "Name" for the newly added directory has been filled in for you to the right of where the path itself is. This merely serves as the label for the directory as you'll see it in the uMen menu, and you can change it at any time. Try that - notice that changes to labels are instantaneously displayed in the menu.
You may also notice along the top of the setup window, that you can change the label for the menu itself, too. Feel free to do so. I use the name uMen (crazy, I know). It defaults to osipaEntertainment, because that sure does make for a cheap ad.
Once you add roots, the menu will recursively find sub-directories and files, and begin building those paths up as menus that are a mirror to your directory structure. Go ahead and create a new directory in your desktop/examples folder, and notice that as soon as you look in the menu, that new sub-directory is there. All the paths found will automatically be added to your script path and all scripts inside will be ready to go (this is done for the session, so there's no leftover clutter, and no digging around in your userSetup files to worry about). Additions to Roots are instant-ish. (Same caveats about "Instant-ish")
Notice that when pasting or typing a root, trailing slashes and slash direction aren't important (this is only true for ROOTS)
C:/Documents and Settings/Jason Osipa/My Documents/Production/osipaEntertainment/
C:/Documents and Settings/Jason Osipa/Desktop/testA
C:\Documents and Settings\Jason Osipa\Desktop\testB
Exclusions
- Video is slightly out of date - files besides .mel, .mll and .py can no longer be seen at all, and .mlls are not enabled (you can see them, but that's it)
Exclusions are taken as regular expressions syntax and are there to allow you to stop things from being included in the menu. As a default, the menu looks only for .mel, .py, and .mll files to display, so this lets you "black out" specific things. Note that items that are directories are excluded as an entire branch. If you have a directory called "feet", and "feet" is an exclusion, not only will the directory "feet" not appear in the menu, neither will any of it's sub-directories. The following example will exclude files and directories called "CVS" and "junk"
Separate each excluded item by comma, and don't add quotes around them.
CVS, junk
uMen Maps
The default behavior of uMen is to traverse your directories, and build up menus that mirror that structure. You can, however, control the creation of menus and menuItems another way, using what are called "uMen Maps". A uMen map is a simple text file you create with the suffix ".uMen". If you fill that file with a file name of a script per line, a menu will be built up, named for the text file, with menuItems matching the scripts you reference.
A file named 'myCustomMenu.uMen' with contents that look like this:
C:/Documents and Settings/Jason Osipa/My Documents/Production/osipaEntertainment/omen/aaa/gb3.mel C:/Documents and Settings/Jason Osipa/Desktop/testA/oeSharpWgt.mel oeBlurWgt.mel
Note that in this file, slash direction matters!
Will create a menu called myCustomMenu that branches where myCustomMenu.uMen is located, containing three menuItems, gb3.mel, oeSharpWgt.mel, and oeBlurWgt.mel. Each will open the with the same logic as that applied anything in the regular menus. This makes it easy to, for instance, create "custom" layouts for user types, or each user can create their own "favorites", and it will appear just like any other directory.
You'll notice, .uMen maps can contain full paths or just short names. This is different for MEL scripts vs Python. MEL scripts can have all three of these options, but Python tools need to be just the short, or 'module' name. For Mel, a "whatIs" is called to determine what/where the script is, and the result is what is used to build up the menuItem. If, and only if that fails, an attempt to locate the name as a Python module is attempted. This means that any MEL script in a .uMen map must be in maya's script path, and any PYTHON script needs to be in maya's python path - whether that is something you are adding yourself, or, of course anything in the sub-directories of your added roots' branches in the uMen menu setup.
uMen.flat
Add a file ( or directory ) named uMen.flat ( it can be empty, all that is looked for is the name ) into a root directory or a directory with a uMen map (or several), and instead of adding the menuItems onto a subMenu, it'll draw the contents a level "up". Say you wanted to have a bunch of uMen maps for user tools, like animation, modeling, rigging, etc. Instead of making people dig through your root, through that menu, then to the menuItems, a uMen.flat file makes everything appear a level up, or "flat".
Note: These are only really useful on a root level directories, otherwise they only draw after you select a menu.
Wiki Root
This section talks about the wiki root and local v global wiki paths. For more on setting up your scripts for proper wiki documentation, check out egDocStyle's page.
If you decide to set up a wiki and use the autoWiki feature of uMen, set a wikiRoot value, and each script will then be able to automatically "guess" a location to write and read itself to and from. If you are pickier and want there to be no guessing, you can explicitly set relative or absolute wiki paths within your script's comments to override guesses, but even if you don't, having a wikiRoot set will allow the tool to "guess" pretty effectively.
For an example wikiRoot, here's the OE one:
http://docs.osipaentertainment.com/index.php/Tools/
Wiki Message
This is copyright message (or any message really) that you want to have appear in all of your automatically generated wikis. It will appear just below the "Auto-generated by uMen.py..." line that is on every page created through uMen. Use wiki syntax if you would like any formatting. In the following example, there is a link to the OE site, and the whole message is formatted "small"
<small>All page contents are (c) [http://jasonosipa.com Osipa Entertainment, LLC]</small>
Comment Style
This is a switch used only in the scriptUI you'll see in Maya. Based on your selection here, of type of comment, you'll either see none (no documentation in the scriptUI) you'll see all comments, (literally everything after a \\ or between \* *\ ) or, \\doc which will show only uMen style documentation in the scriptUI. This can be very handy in marking up your code two ways - once as documentation for users, and once for your regular old run-of-the-mill descriptions of what your code is doing. Check out this section for more details on how to make use of this.
Custom Startup Functions
On startup, you'll always have your userSetup files, but if you want uMen to handle some other work, that's easy, too. You can search for directories by name, and then do something to everything in that directory, as soon as uMen starts up (before it even creates itself). Two examples of using a search for "plugins", which then does "loadPlugin". It just loads all plugins in that directory for you. Another is having a directory called "utils", and a command to "source". This would allow you to have a directory of scripts you always want sourced and available, like for instance, if you were making a bunch of hotkeys available from a central location, you'd need to be sure that what those hotkeys do is ready to go!
Custom ScriptUI
The automatially generated scriptUIs cover some basic functionality, but let's say you need to integrate source control, or some other meta-level connection to other aspects of your dev environment, or just like to add a button to everything you write that just says "Ficus". Well, by having the scriptUIs look for any custom work each time they load, you can customize to your heart's content. Any procedure you call will be sent the file name and the tabLayout name from the scriptUI. With that you should be able to add and manipulate pretty much anything you want, allowing you to get layers more of functionality in scriptUIs. To add more than one layer of functionality, all you would need to do is have your customScriptUI call other customScriptUIs!
As a note on what can be done with these - this is actually all that uMen's dependency tracking is!
Check out egCustomScriptUI.mel's page for a more complete tutorial regarding uMen customScriptUIs. It even talks ( on a high level ) about how you would integrate source control, which if that's on your mind - I'm sure you're curious!
Miscellaneous
Recent Files There is a "Recent" subMenu in the uMen top-level menu, that, as you probably guessed, keeps tracks of files recently opened, so if you are working with the same few, they'll always be readily accessible. Changing this number changes how many files are kept in the menu.
Documentation "light"
Well, in all reality it's probably more documentation than you usually do, but you also never got paid back so much for bothering to do it! (and you actually don't have to do anything, everything will still work if you do no commenting at all, it will just be less fancy)
There is a simple way to tag up comments in your files to make them "visible" as different information both in the in-Maya autoUIs, and in the autoWiki exporter. It is important to note that any and all of this is optional for extra functionality. Even without doing this special commenting in your tools, the autoUIs and autoWiki will work. Marking your script up this way will just mean more bells and whistles for you. You can also use as much or little of it as you like, and you don't even need to be consistent. Just because you tag one variable with documentation, not all require it. Add default values to variables that would benefit from them, and leave others alone - it won't be a problem!
Check out egDocStyle.mel's page (itself auto-generated) for a more complete tutorial regarding uMen documentation and autoWiki. What follows here is merely a "brief" run-through of the core concepts.
- Please note that for Python all tags are the same except they start with # instead of //
Script and Procedure Documentation
To create documentation for your script or procedure as opposed to just "in-the-thick-of-it" commenting, making it show up in autoUIs and autoWikis, do this:
Description:
//doc your documentation here
Examples:
//doc This script contains tools to manipulate the shapes of polygons
#doc This procedure selects and "rounds" the border edges of a polygon object
Variable Documentation
To create documentation beyond good ol' fashioned descriptive variable names for what a variable does, describe it on a line like so:
Description:
//varDoc $yourVarNameHere and your var documentation after it
Examples:
//varDoc $iterations Sets how many times the operation is run
#varDoc name The new name for the object
Variable Defaults and Drop-Downs
To create default values for your variables, which show up in the autoUIs, and wiki documentation, just tag a line like this:
Description:
//varDrp $yourVarNameHere and your default values after it
Example:
//varDrp $iterations 3, 2, 1
#varDrp iterations 3, 2, 1
(The default value would be 3 and you'd have a popupMenu with 2 and 1 also available)
Wiki Path
Whether you make your own or auto-generate a wiki, putting a path into your script is optional. If you just want a page off of your wikiRoot (if set), you don't even need to put anything in, and with the help menu and help wiki funcionality, you'll be taken to the right spot!
Description:
//hlpDoc An absolute or relative path to your wiki page.
Example (absolute):
//hlpDoc http://docs.osipaentertainment.com/index.php/Tools/Free/egDocStyle
Example (relative) (your wikiRoot will be appended to the head of this path):
#hlpDoc /Free/egDocStyle
Video Help
Made a youTube video to describe or demo your tool? Have one posted on your internal server? Just throw this tag in there for the autoWiki to pick up. (Different formats will' require different wiki syntax, youTube is pictured below)
Description:
//hlpVid your tag here
Examples:
//hlpVid {{#ev:youtube|zABTa7xrIf4}}
#hlpVid {{#ev:youtube|zABTa7xrIf4}}
For your wiki to support videos being embedded, you'll need an extension installed. For wiki setup services we recommend Hot Stove Software
Documentation "Level"
Depending on where you insert your comments they'll do slightly different things. To make sure a comment is associated with a procedure, it must appear 'inside' the procedure. Comments meant to be descriptive to the entire script, and all the tools included, should appear anywhere before the first procedure begins.
The Best Part : autoWiki!
If you tag your scripts the above described way, you not only get significantly increased functionality in-Maya for your effort, but you also have the ability to export a wiki-style documentation page from the script. Almost all tool documentation you see on this site has been created all or in part using that feature!
Export your auto-UI
When your team is hungry for a tool, and you don't have the time to spend on a pretty UI, you can export the automatic UI to give them something in a rush. When you have more time to customize and pretty it up later, just swap out the freebie for your own fancy UI! If you have uMen installed on their work station, this step isn't even necessary, but if it isn't - this will remove any uMen dependencies.
Procedure Naming Conventions
uMen allows procedures in scripts to be opened in the autoUI, with it's layout and global procedures visible. This however, is what happens when pressing the optionBox for a script. To control what happens when pressing the menuItem, the following is a simple trickle-down logic that will be attempted on your script.
Check out egTrickle.mel's page for a more complete tutorial regarding uMen Naming Convention and trickle-down logic. What follows here is merely a "brief" run-through of the core concepts.
scriptName_menuItem
If a procedure exists with this name, pressing on the menuItem will try to run it first. The idea is that you create a small procedure that is the no-options-needed, selection-based version of your tool.
scriptName_window
If a procedure exists with this name, pressing on the menuItem will load it up. The idea is that if you have a "window" you've made, this, the second step on the trickle-down logic will be run. If you only want a "window" version, and nothing that runs as described for "_menuItem", you would have no need to write a "_menuItem" procedure. On the other hand, this means that you can have both a menuItem and a window version, for different occasions. Having both is what most closely mirrors Maya's native functionality: press-and-go v show-me-my-options.
scriptName_layout
This is the recommended method to write UIs in uMen. Very similar to the description for the "_window" procedure above, but, with an important difference : don't create a window in your procedure, instead only create the layouts and controls. If a "_layout" procedure is found, the trickle-down logic will create a window automatically and then insert your layout into it. There are a couple of reasons to do things this way:
- If you write a "_window" proc, which does nothing but "create" a window, then call this "_layout" procedure from that procedure, it can load this layout up independently for anyone by running the "_window" version, but also in the optionBox version in the "layout" tab. - One chunk of code runs double-duty.
- This workflow / code style makes it very easy to create tool "palettes", where all a script does is call other script's layouts. This lets you create many task-based work environments (and individual users can create their own palettes very very easily).
- Instead of having to do it yourself, a file and help menu are created in the menu bar of the window, with some of the options available in the usual optionBox-style-menus.
- A freebie Help-doc viewer built right in. Besides the wiki help link which you'll find in the help menu, there is also a help call built in that will open a window and display the script's "header" help ( before the first proc ) as well as the _layout procedure's help. This means that if you plan to build your user-side tools this way, the _layout proc is a great place to put "instructions" for the UI that end users will have easy access to
scriptName
meaning - No suffix If your script contains a procedure of the same name, no suffix, that will be the fourth thing that a menuItem press will try to run - If there are no variables required. If this procedure requires variables to be passed into it, then it will open a window as if you opened it with the optionBox, with the frameLayout "opened" for this procedure.
If None Of These Procedures Exist
Your script has no procedures matching these names, it will a window as if you opened it with the optionBox.
Known Bugs, Limitations
As a general note, uMen, although a Python script itself, is written primarily for making work with MEL scripting easier. Python has been integrated and can use most of uMen's features, but at present has a few more bugs and limitations surrounding it.
Python Variable Buttons
Since Python uses unsigned variables, and has the inherently complicated unpredictable feature of tuples, it can be trickier to determine what an autoUI button should "do". For now, the way to get variable buttons working is to include type declarations in your definitions.
def myDef( knees, shoulder, head ):
will result in no working buttons, whereas
def myDef( knees = [], shoulder = {}, head = "" ):
will give you buttons for a list (works like string[]), an array (works like string[]), and a string. It's not nearly as robust as the MEL side of things, admittedly, but until we come up with an easy way to determine all of that automatically, or with some other tagging, this is the solution.
Python autoUI buttons don't display return values
When you press a proc's main button on a MEL autoUI, the return value will be displayed in the script editor. For Python, however, eval v exec command nonsense is currently limiting the ease with which this can be done in Python. It's on the map, a solution has yet to present itself.
Python plugins (and nested defs) don't work in scriptUIs
Their "true" functionality is perfectly intact, and they still work and run as you would expect, but for python plugins and nested functions, you just won't get the full feature-set in the scriptUIs of uMen (yet!). We haven't gotten into Python classes or nested defs with uMen yet, so at present uMen tries to look at this all as functions on a flat level and has problems with that.
Python export of UI
Currently, exporting a "shareable" MEL version of an autoUI, is available, but a Python version is not - this is on the plan to happen, it just hasn't yet.
Python Custom ScriptUIs
Currently, calling a "Custom ScriptUI" in MEL is available, but a Python Custom ScriptUI is not - this is on the plan to happen, it just hasn't yet.
Dragging to Shelves
Currently, dragging uMen menuItems to shelves creates a "working" command, but one that depends on uMen being loaded. Ideally this would create a dependency-free shelf button. In the plan, just hasn't happened yet.
MEL proc lines over multiple lines
If a mel global proc declaration occurs over multiple lines, the proc reader portions of uMen can get confused. In the plan to be fixed, just hasn't happened yet.
Too many procedures
If a script has over 25 procedures, the draw style in the autoUI changes to fit more info on the screen. It's definitely a stop-gap fix, which is the best we've come up with. A scrollLayout or scrollabel tabLayout would theoretically be a good way around this, if they weren't as unpredictable. Also, there is a window resizing feature in uMen which conflicts logically with a scrollable area. This is something we've worked a lot on, and haven't yet found a suitable solution for, so we're going stop-gap for now. Suggestions on working methods are welcome!
Too many files in a menu
Anything over 50 scripts in a single uMen directory will be visually cropped. There are two reasons this is done - first, if you have a directory with 600 files, uMen would try and build the menu up, and that can cause a crash. Second, any much more than 50 menuItems, and you won't be able to see more than 50 on the screen anyways. The cropping of menuItems displayed is just that, a display-only cropping. Paths and files are still added to script, python, and plugin paths, you just can't get to them through the menu. The only real suggestion to avoid this is to just try and have directories you plan to use inside uMen be limited to 50 files each. (Your total number of tools could be thousands just as long as there aren't more than 50 in any single directory, you shouldn't have any problems)
Mac or Linux problems
With no Mac or Linux machines inside OE just yet, it's been a tricky thing to try to test or correct any problems. Any help or suggestions are welcome!
Disclaimer
uMen.py has NOT been tested on anything but windowsXP, on Maya version 2009 so bear with us as things are tweaked to allow for other platforms to come online. Feedback on the discussion tab for this page is welcome to help expedite that process, if you want to try it in those untested waters anyways!
Legals
Osipa Entertainment, LLC makes no guarantees or warranties related to download and /or use of any tools, mel and python scripts and plugins.
Although some Osipa Entertainment tools, mel and python scripts and plugins are free and available for all to use (and alter functionally) it is prohibited to remove any of the documentation, copyright notices, and/or any references and links to Osipa Entertainment, LLC.
