Picking Scene Nodes By Hit

Picking Scene Nodes

pickObject [	message:<string> ] [	prompt:<string> ] \ 
[	count:n|#multiple ] [	filter:fn ] \ 
[	select:<boolean> ] [	pickFrozen:<boolean> ] \ 
[	rubberBand:<point3>] [	rubberBandColor:<color> ] \ 
[	forceListenerFocus:<boolean> ] 	 

The pickObject() function lets the user pick one or more scene objects in the 3ds Max viewports. It takes several optional keyword arguments. The message: argument takes a string value which is displayed in the status bar prompt line. The prompt: argument takes a string value which is displayed in the Listener window. The count: argument takes either a positive integer or the symbol #multiple to specify how many objects are to be picked (default is 1). If the count specified is greater than 1 or the value #multiple , an array is returned containing the picked objects. The symbol #multiple indicates that any number of objects can be selected and the user terminates the selection with a right mouse click or, if the Listener window has focus, any character key of the keyboard. If the ESC key is pressed while the Listener windows has focus, an #escape value will be returned. If the ESC key is pressed while a viewport has focus, selection is terminated and the selection result is returned.

If #multiple was specified, and no objects had been selected when the selection was terminated, an empty array is returned. If #multiple was not specified, and an object had not been selected when the selection was terminated, a value of undefined is returned.

The filter: function takes a MAXScript function of one argument that is called whenever the cursor is over an object in the scene and is passed that object under the cursor. It returns true if the object is eligible for picking, or false if not. Typically, the function would contain some object class testing,

fn shapeFilt o = (superClassOf o == Shape)
-- which you could use like this:
pickObject prompt:"enter a shape" filter:shapeFilt

The optional keyword argument select: controls whether the picked objects become the new current selection in the 3ds Max scene. If you supply true for that argument, the current selection is replaced with the objects that you pick. The default is false in which case the picker doesn't affect the selection set.

If the pickFrozen: keyword argument is set to false (the default), frozen nodes cannot be picked. If set to true , only frozen nodes can be picked.

The two optional keyword arguments rubberBand: and rubberBandColor: control the display of a rubber-banding line in the viewport during pick operations.

If rubberBand: is supplied on the pickObject() call, it enables rubberbanding, with the given <point3> as world-space coordinates for the start point of the rubber band. You can use the rubberBandColor: argument to override the default line color of gray (color 128 128 128).

obj2 = pickObject rubberBand:obj1.pos rubberBandColor:yellow 

The optional keyword argument forceListenerFocus: controls Listener focus forcing. It defaults to true to retain existing semantics and backward compatibility.

When picking multiple nodes and selecting by name by using the 'H' key, you need to supply forceListenerFocus:false to get the 'H' key to work consistently. If this is not specified, focus is forced back to the Listener after each pick:

pickObject count:#multiple forceListenerFocus:false

Be aware that the array returned can contain the same node multiple times.

pickObject() will exit if you switch command modes to a non-viewport command mode. For example, if you run pickObject() and then click Select and Move, pickObject will exit with its current results. If instead you went into pan or zoom, pickObject() doesn't exit, but waits for its command mode to be re-entered. If you go from a viewport command mode to another command mode, pickObject() will exit.

Picking Animatables

<animatable>pickAnimatable [message:<string>] [prompt:<string>] \
[count:n|#multiple] [filter:fn] [pickFrozen:<boolean>] \
[rubberBand:<point3>] [forceListenerFocus:<boolean>] 

NEW in 3ds Max 2015: Lets you pick an Animatable from any area of the 3ds Max User Interface.

The only difference to the pickObject() function documented earlier on this page is that there is no support for the select: parameter - selection does not really apply to non-nodes.

For the description of the other optional keyword arguments, please see the beginning of this page.

Clicking in a 3D viewport will return scene nodes.

Clicking in an Explorer will also return scene nodes.

Clicking in Schematic View will return the animatable that was clicked - scene node, base object, modifier, controller and so on.

Clicking in Track View will return the animatable that was clicked - scene node, modifier, material, map, controller, root node etc.