Find
|
|
findSoftWish's find command works on Softimage elements in a way similar to the way the find utility on Unix systems works on files and directories. It returns a list of element-names or element-identifiers based upon specified criteria. Find also caches data about these elements, so that one may rapidly access additional information about the found elements. Contents1 Loading the package 2 Syntax of the command 3 Predicates 3.1 Built-in predicates 3.1.1 -guiprefix 3.1.2 -guiname 3.1.3 -putname 3.1.4 -puttype 3.1.5 -name pattern 3.1.6 -hasudata 3.1.7 -udkey pattern 3.1.8 -guiud 3.1.9 -clickcb callback 3.1.10 -globud pattern 3.1.11 -regexp regular-expression 3.1.12 -returnname 3.2 Caller-supplied predicates 3.2.1 Input list 3.2.2 Output list 3.2.3 args 3.2.4 Return value Returning an error Normal return Number of consumed arguments List modified List unchanged 4 Additional information about elements 4.1 Find-getSceneN elemN 4.2 Find-getPrefix elemN 4.3 Find-getName elemN 4.4 Find-getType elemN 4.5 Find-tmpPath 4.6 Find-udName elemN 4.7 Find-CleanUp 4.8 Find's data 4.8.1 Array of scenes 4.8.2 Array of elements 4.8.3 The toplevel widget of find's GUI 1 Loading the packageThe find functionality is encapsulated in the package findElement. The latest version of the package is 1.0. You must load the package into the interpreter before you can use it. You do this by:
2 Syntax of the commandThe find command looks like this:
The scene(s) are where find looks for elements. Currently only the current scene, denoted by ".", may be specified. The predicate(s) (if any) filter out the elements that do not satisfy certain conditions. Predicates are applied one after the other, so the order matters. As an example: to find all the elements in the current scene, which have notes attached to them, and see those elements in the GUI tree, you would call find like this:
To get the list of elements with user data used by Video Collage plug-ins, and have the names of the elements printed, you would call find like this:
Find can return a list of element names. To do this the last predicate must be -returnnames, otherwise it will return a list of internal indices. These indices can be used to retrieve additional information about the elements. 3 PredicatesFind builds the list of elements in the scene and then filters it, removing those that do not satisfy the predicates. The reason they are called predicates is that the whole package (including its terminology) was inspired by the Unix's find utility. 3.1 Built-in predicatesThe findElement package comes with the following built-in predicates: 3.1.1 -guiprefixDoes not affect the list. Causes the prefixes of elements to appear in the GUI window. 3.1.2 -guinameDoes not affect the list. Causes the names of elements to appear in the GUI window. Calls guiprefix (see 3.1.1) internally. 3.1.3 -putnameDoes not affect the list. Causes the names of elements to be printed out. 3.1.4 -puttypeDoes not affect the list. Causes the types of elements to be printed out. 3.1.5 -name patternRemoves the elements whose names do not match the globe-style pattern from the list. 3.1.6 -hasudataRemoves the elements which do not have any user data attached to them from the list. 3.1.7 -udkey patternRemoves the elements which do not have user data attached at all, or do not have a user data tag matching the globe-style pattern. 3.1.8 -guiudDoes not affect the list. Causes the user data tags to appear in the GUI window as leaves of the element branches. 3.1.9 -clickcb callbackDoes not affect the list. Causes the specified callback to become the -command of the GUI tree widget. The specified callback will be called every time the user double-clicks on a tree-entry. The procedure is called by Tix (or Tk) with one argument - the name of the entry. 3.1.10 -globud patternRemoves elements which do not have any user data. Removes elements which have user data but without the specified tag. Also removes elements which have user data with the specified tag but whose appropriately tagged data does not match the given globe-style pattern. For example:
will find all elements which have notes attached and with the word "Interesting" followed by a space and something else in the notes. Note that this predicate must be preceded by -udkey pattern in order to know among which elements to look. 3.1.11 -regexp regular-expressionThis predicate is similar to -globud above, except that it uses regular expressions instead of globe-style pattern matching. For example:
will return elements with the words "Interesting" or "interesting" in the user data chunks corresponding to MNOT tags. 3.1.12 -returnnameIf used, this must be the last predicate in the sequence. It causes find to return a list of element names instead of the internal element numbers. Element names are the same as those used by Softimage. Element numbers are internal indexes which you can specify to succeeding find invocations in order to get additional information. find . -udkey MNOT -regexpud {[Ii]nteresting} -returnnames will return the names of those scene elements with words "Interesting" or "interesting" in the user data chunks with MNOT tags. SWN_select+ [ find . -udkey MNOT -regexpud {[Ii]nteresting} -returnnames ] will add all the elements in the scene with the word "Interesting" or "interesting" in their user data (in chunks tagged with "MNOT" ) to the selected elements. Note that this makes for a an easy and flexible way to build selection groups. 3.1.13 -swnname patternRemoves the elements whose pefixes and names do not match the swn file praradigm pattern from the list. So find . -swnname monster:*hand/ -returnnames ] returns the the internal element numbers of all elements of the current scene which are in the heirarchy perfixed monster and are descendants of elements whose names end with hand. We can select all these elements by using the -returnnames predicate and passing the resulting list of names to SWN_select+, like this: SWN_select+ [ find . -swnname monster:*hand/ -returnnames ] 3.2 Caller-supplied predicatesIt is time to take the mystery away. Find searches for the predicates by prepending the name of the predicate with prefix find.(remember that Tcl is case-sensitive,so it must be find, not Find or FIND). For example, the procedure that handles -name is called find-name. The caller application can provide its own predicates by defining new procedures find-*. The procedures must have the following signature:
Here are the requirements the procedures need to follow: 3.2.1 Input listThe find-procedures receives the name of the list of elements they are to operate on as the first argument (iListName). The typical way of processing the list would be:
3.2.2 Output listThe find-procedures receive the name of the output list as the second argument (oListName). If the procedure does not change the list, it does not need to touch it. Predicates (so-called for their side-effects, such as the puts and gui built-in predicates), do not modify the output list. If, however, the procedure wishes to modify the list, it should access the list like this:
The change to the list gets signaled to find's engine using by the predicate procedures return value. 3.2.3 argsThe find engine passes all the not-yet-processed arguments to the predicates. For example, if find was called as:
the find-guiprefix procedure will receive the entire {-name cube* -guiname} as args, but the find-name procedure will only see the remaining {cube* -guiname}. Every procedure is free to interpret the list as it pleases, but it must tell the engine how many arguments were processed, so that it can call the next predicate properly. 3.2.4 Return valueTo signal an error, such as missing pattern, the predicate must return 0. It can do whatever it pleases before returning, however. If the procedure worked normally, it must tell the engine two things. The first is how many arguments from the not-yet-processed list of arguments were consumed by this procedure. The second is whether or not the list of elements was modified by the procedure. These 2 pieces of information are combined into a single value by using signed values. The find engine determines the number of consumed arguments by taking the absolute value of the procedure's result. For example, the procedure that handles the "-name pattern" predicate returns 2. One for "-name" and one for the "pattern". Predicates that take no arguments (like "-guiname") return 1. If the output list is different from the input list then the procedure actually did some filtering. In this case the return value must be negative (otherwise the engine will discard the changes without looking at them). This is done for performance - the procedure that did the changes to the list already knows about them, so why waste time comparing the input and output lists? For example, the "-name cube*" will only put elements whose name starts with "cube" on the output list. If the list contained any other elements, the predicate should return negative value. If all the elements on the list satisfied the condition, the result should be positive (see below). If the output list is the same as the input list, the find-procedure should return a positive number. This will tell the engine that it does not need to bother with lists and save some time. Note, that if you are lazy you can write your predicate handling procedures to always return a negative number. 4 Additional information about elementsFind caches a lot of information and, by default, returns a list of indexes you can use to retrieve this information. A list of all of the procedures accessing this info can be obtained by
The most important and useful ones are described in this section. Most of them take the element number (as returned by find) as the single argument. Note that the information is retained between calls to find. Succeeding find calls will overwite it, however. The same element number will probably correspond to different Softimage elements after 2 different find calls. 4.1 Find-getSceneN elemNReturns the scene number the element belongs to. The scene structure itself can then be accessed as in:
Currently find only operates on the current scene, so this procedure always returns 0. 4.2 Find-getPrefix elemNReturns the prefix of the element. 4.3 Find-getName elemNReturns the name of the element. For example:
Will print out the prefix-name pairs for all elements of the current scene. 4.4 Find-getType elemNReturns the type of the element - one of the Cameras, Texture2D, Texture3D, Waves, Models, Materials, Expressions, Clusters, Lights. 4.5 Find-tmpPathReturns the path to the temporary directory based on the environment variables TMPDIR, TMP, TEMP and the operating system. For example:
This can be used to find a place for a temporary file. 4.6 Find-udName elemNReturns a file name unique for the element and the current hostname. Use this if you need a name of a temporary file which will not conflict with names for other elements. 4.7 Find-CleanUpThis function cleans up all of find's internal data. This is normally retained until the next find call. Use this explicitly to free up resources when you will not be calling find again. 4.8 Find's dataAccessors have not been implemented for all of the cached data. This data is stored in the global array FindData. Among the elements of this array are: 4.8.1 Array of scenesThe array of all the scenes find searched, as allocated by SAA_AllocScene - referenced by FindData(Scenes). See also 4.1 above. 4.8.2 Array of elementsThe array of all elements of the scene, as allocated with SAA_AllocElement - referenced by FindData(Elements). The element numbers as returned by find are indices into this array. 4.8.3 The toplevel widget of find's GUIThe toplevel widget's name is referenced by FindData(TheTop). |
|
copyright Video-Collage Inc. |