ScriptQuery Interface 701 Updates

From The Foundry MODO SDK wiki
Jump to: navigation, search

This article includes updates to the SQ interfaces, mostly so that we remember to add them to the SDK wiki when 701 ships. Where possible, most of these sections should be able to be dropped right into the SDK wiki. Thus seemingly broken links to other pages may in fact be to valid pages in the SDK wiki.

CommandService

command.category

Get the path of the category that the command belongs to. The username of each component of the path can be resolved with messageservice by using the Commands:category message table. See category attributes for more information on using these message tables.

Datatype string
Example query commandservice command.category ? attr.formPopover
Result attr/display

command.argArgTypes

Get the Argument Types associated with each of the command's arguments. Argument types can be resolved into usernames and descriptions through messageservice's argtype and argtypeoption attributes. Arguments that don't use argument types have empty strings in their place.

Datatype string
Example query commandservice command.argArgTypes ? select.item
Result

select-mode


MessageService

NOTE: Also update Argument Types to point to MessageService Reference on the SDK wiki.

In modo 701, msgfind, msgsub and msgcompose have been renamed to msg.find, msg.sub and msg.compose for clarity. The old attribute names still work in order to avoid breaking old scripts.

Argument Types

In this context, argument types provide user names for command arguments that use TextValueHints when they are presented in popups. This is done automatically by the command system, but it is also possible to directly read out these user strings through this service.

Argument types each have their own usernames and descriptions, which are read with the argtype attributes. Each option also has its own username and description, which is obtained with the argtypeoption attributes.

argtype Attributes

The argtype attributes are used to get the username and description of the argument type itself. The selector is the name of the argument type, usually obtained from a TextValueHint or a command.

argtype.username

Get the username of an argument type.

Datatype string
Example query messageservice argtype.username ? select-mode
Result Selection Mode Specifier

argtype.desc

Get the description of an argument type.

Datatype string
Example query messageservice argtype.desc ? select-mode
Result Modes modify selection commands to perform different actions.

argtypeoptions Attributes

The argtypeoptions attributes are used to get the username and description of a single option in an argument type. An argument type must have been previously "selected" with an argtype attribute. The selector is the internal name of the option, and is usually an entry from a TextValueHint.

argtypoptione.username

Get the description of an argument type option.

Datatype string
Example query messageservice argtypeoption.username ? set
Result Set

argtypoptione.desc

Get the description of an argument type option.

Datatype string
Example query messageservice argtypeoption.desc ? set
Result The element becomes the primary selected element.

SceneService

New Item Queries

These new queries apply to all item types, so <item> could be 'mesh' or 'locator' or any item query or type.

<item>.isDeformer

Is item a deformer type.

Datatype integer
Example query sceneservice <item>.isDeformer ?
Result Check whether item type is a deformer

<item>.deformers

Get list of deformers and influences.

Datatype string
Example query sceneservice <item>.deformers ?
Result Return a list of deformers applied to the item (typically a mesh or locator). For deformers, this query returns the deformer hierarchy.

<item>.groups

List of groups item is a member of

Datatype string
Example query sceneservice <item>.groups ?
Result Return a list of all the group items in which the current item is a member.

Group Queries

Groups of different types are used to organize render passes, actors, assemblies, shaders, presets, and more. They can be queried like other items using the 'group' query. Type-specific group queries have also been added, so all the actor groups, for example, can be listed and queried as if they were their own item type. For these queries, the .current query does not take a type, but returns the current group of that type. These queries specific to groups have been added:

group.types

List of group types available

Datatype string
Example query sceneservice group.types ?
Result Return a list of all the group types available. Use these types for the group.current query. this overrides the standard types query for items.

group.current

Return current group of given type, if any.

Datatype string
Example query sceneservice group.current ? <type>
Result Return the current group of the given type. Use a value for <type> from the group.types query

group.isCurrent

Is this group 'current'.

Datatype integer
Example query sceneservice group.isCurrent ?
Result Check the this group is the 'current' (active, user-selected) group.

group.itemMembers

Members of this group's item graph.

Datatype string
Example query sceneservice group.itemMembers ?
Result Return the list of members of this group's item graph.

group.chanMembers

Members of this group's channel graph.

Datatype string
Example query sceneservice group.chanMembers ?
Result Return the list of members of this group's channel graph in the form <item>:<channel index>.

pass.current

Return current render pass group, if any.

Datatype string
Example query sceneservice pass.current ? <type>
Result Return the current render pass group.

pass.isCurrent

Is this group 'current'.

Datatype integer
Example query sceneservice pass.isCurrent ?
Result Check the this group is the 'current' (active, user-selected) group.

pass.itemMembers

Members of this group's item graph.

Datatype string
Example query sceneservice pass.itemMembers ?
Result Return the list of members of this group's item graph. Pass items should be actionClip type items which can be queried using the actionItem queries.

pass.chanMembers

Members of this group's channel graph.

Datatype string
Example query sceneservice pass.chanMembers ?
Result Return the list of members of this group's channel graph in the form <item>:<channel index>.


actor.current

Return current actor group, if any.

Datatype string
Example query sceneservice actor.current ? <type>
Result Return the current render pass group.

actor.isCurrent

Is this group 'current'.

Datatype integer
Example query sceneservice actor.isCurrent ?
Result Check the this group is the 'current' (active, user-selected) group.

actor.itemMembers

Members of this group's item graph.

Datatype string
Example query sceneservice actor.itemMembers ?
Result Return the list of members of this group's item graph.

actor.chanMembers

Members of this group's channel graph.

Datatype string
Example query sceneservice actor.chanMembers ?
Result Return the list of members of this group's channel graph in the form <item>:<channel name>.

ActionItem Queries

ActionItem queries provide special queries for items of type 'actionClip'. The 'actionClip' query functions as a normal item query for these items, so a different query name, 'actionItem', is needed for specialized results. Action clips contain lists of items and channels which store settings for things like render passes and poses. Use these queries on them:

actionItem.N

Number of actionClips available

Datatype string
Example query sceneservice actionItem.N ?
Result Return the number of all the actionItems.

actionItem.name

Return name of item.

Datatype string
Example query sceneservice actionItem.name ? <item>
Result Return the name of the current item.

actionItem.name

Return name of item.

Datatype string
Example query sceneservice actionItem.name ? <item>
Result Return the name of the current item.

actionItem.id

Return id of item.

Datatype string
Example query sceneservice actionItem.id ? <item>
Result Return the id of the current item.


actionItem.type

Return type of item.

Datatype string
Example query sceneservice actionItem.type ? <item>
Result Return the action type (pose or clip) of the current item.


actionItem.items

Return the list of items in the current action item.

Datatype string
Example query sceneservice actionItem.items ? <item>
Result Return the list of items in the current action item.


actionItem.channels

Return the list of channels in the current action item.

Datatype string
Example query sceneservice actionItem.channels ? <item>
Result Return the list of channels in the current action item. Channels are returned in the form <itemId>:<channelName>

actionItem.chanValue

Return value of channel.

Datatype string
Example query sceneservice actionItem.chanValue ? <itemId>:<channelName>
Result Return value of given channel.

actionItem.group

Return group containing current action item.

Datatype string
Example query sceneservice actionItem.group ? <item>
Result Return group containing current action item.

Here's a short example of these queries in action:

# python
n = lx.eval('query sceneservice group.N ? ""') 
for i in range(n):  # enumerate ALL groups in scene
	g = lx.eval('query sceneservice group.name ? %d' % i)
	t = lx.eval('query sceneservice group.type ? %d' % i)
	lx.out('%d: "%s"  %s' % (i, g, t))
 
types = lx.evalN('query sceneservice group.types ?')
for t in types: # enumerate types in scene then elements in current group of each type
	g = lx.eval('query sceneservice group.current ? %s' % t)
	lx.out('Current %s Group: %s' % (t, g))
	if (g != None):
		nm = lx.eval('query sceneservice group.name ? %s' % g)
		lx.out('Current %s Group: %s %s' % (t, g, nm))
		mems = lx.evalN('query sceneservice group.itemMembers ? %s' % g)
		for m in mems:
			t = lx.eval('query sceneservice item.type ? %s' % m)
			lx.out('      item --> %s (%s)' % (m,t))
		mems = lx.evalN('query sceneservice group.chanMembers ? %s' % g)
		for m in mems:
			lx.out('      channel --> %s' % (m))
 
n = lx.eval('query sceneservice actionItem.N ? ""') 
for i in range(n):  # enumerate ALL actionclips in scene
	g = lx.eval('query sceneservice actionItem.name ? %d' % i)
	p = lx.eval('query sceneservice actionItem.group ? %d' % i)
	s = lx.eval('query sceneservice actionItem.type ? %d' % i)
	chns = lx.evalN('query sceneservice actionItem.channels ? %d' % i)
	for c in chns:
		t = lx.eval('query sceneservice actionItem.chanValue ? "%s"' % c)
		lx.out('%d: "%s of %s: %s" %s = %s' % (i, g,p,s, c, t))

Graph Queries

Graphs are used to build and store connections between items and/or channels. For example the scene parenting hierarchy is stored in the 'parent' graph. Graph queries work on the current sceneservice item and scene. If an item is part of a graph it will have a link to another item (or channel). This is a forward link. that other item will have a link back to the original item. That is the reverse link. The forward and reverse links for an item are stored in separate lists which you can query to determine a graph's structure.


graph.N

Get the number of graphs in scene.

Datatype integer
Example query sceneservice graph.N ?
Result Number of graphs in scene

graph.name

Get the name of a graph.

Datatype string
Example query sceneservice graph.name ? i
Result Name of graph i

graph.type

Get the type of a graph.

Datatype string
Example query sceneservice graph.type ? i
Result Type of graph i, either "item" or "channel"

graph.flags

Get the flags for a graph.

Datatype integer
Example query sceneservice graph.flags ? i
Result Flags for graph i

graph

Get the possible graph queries.

Datatype string
Example query sceneservice graph ?
Result "graph.N, graph.name, graph.type,graph.flags"

Here's a small example that exercises the graph queries:

# python
n = lx.eval('query sceneservice graph.N ? ""')
for i in range(n):
	g = lx.eval('query sceneservice graph.name ? %d' % i)
	t = lx.eval('query sceneservice graph.type ? %d' % i)
	#lx.out('%d: "%s"  %s' % (i, g, t))
 
 
sel = [0,1]
# lx.evalN('query sceneservice mesh ?')
lx.out(sel)
for i in range(n):
	g = lx.eval('query sceneservice graph.name ? %d' % i)
	for item in sel:
		nm = lx.eval('query sceneservice item.name ? %d' % item)
		lx.out('%s:' % g)
		lx.out(' item %s linked to:\n' % nm)
		#t = lx.eval('query sceneservice graph.type ? parent')
		t = lx.eval('query sceneservice fwdLink.N ? ')
		for link in range(t):
			fwd = lx.eval('query sceneservice fwdLink.item ? %d' % link)
			lx.out('\t--> %s\n' % fwd)
 
lx.out('fini %d' % n)

Link Queries

Forward and reverse link queries are identical. They query the current query graph and query item.

fwdLink.N

Get the number forward links from current query item in current query graph.

Datatype integer
Example query sceneservice fwdLink.N ?
Result number or forward links

fwdLink.item

Get the item at forward link i.

Datatype string
Example query sceneservice fwdLink.item ? i
Result item for forward link i

fwdLink.channel

Get the channel at forward link i.

Datatype string
Example query sceneservice fwdLink.channel ? i
Result channel for forward link i, or nothing for "item" type graph

fwdLink

Get the possible fwdLink queries.

Datatype string
Example query sceneservice fwdLink ?
Result "fwdLink.N, fwdLink.item, fwdLink.channel"

revLink.N

Get the number reverse links from current query item in current query graph.

Datatype integer
Example query sceneservice revLink.N ?
Result number of reverse links

revLink.item

Get the item at reverse link i.

Datatype string
Example query sceneservice revLink.item ? i
Result item for reverse link i

revLink.channel

Get the channel at reverse link i.

Datatype string
Example query sceneservice revLink.channel ? i
Result channel for reverse link i, or nothing for "item" type graph

revLink

Get the possible revLink queries.

Datatype string
Example query sceneservice revLink ?
Result "revLink.N, revLink.item, revLink.channel"

Proxy Queries

Proxy item queries have also been extended with some convenient specific queries

proxy.scene

Proxy reference scene path.

Datatype string
Example query sceneservice proxy.scene ? i
Result Get the file path for the proxy's reference scene

proxy.render

Proxy render item.

Datatype string
Example query sceneservice proxy.render ? i
Result Return the proxy's render item

proxy.preview

Proxy preview item.

Datatype string
Example query sceneservice proxy.preview ? i
Result Return the proxy's preview item

proxy.bounds

Proxy's bounding box.

Datatype float
Example query sceneservice proxy.bounds ? i
Result Return the proxy's bounding box in form {minX,minY,minZ,maxX,maxY,maxZ}