8.5 draw -- Create 3D graphical representations.

The draw module provides the basic user interface to the OpenGL rendering capabilities of pyFOrmex.

Warning: the draw module is still subject to regular changes. Therefore, the information given below may not be fully accurate.

closeGui( )

ask( question,choices=None,default=None)
Ask a question and present possible answers.

Return answer if accepted or default if rejected. The remaining arguments are passed to the InputDialog getResult method.

ack( question)
Show a Yes/No question and return True/False depending on answer.

error( message,actions=['OK'])
Show an error message and wait for user acknowledgement.

warning( message,actions=['OK'])
Show a warning message and wait for user acknowledgement.

showInfo( message,actions=['OK'])
Show a neutral message and wait for user acknowledgement.

showText( text,type=None,actions=['OK'])
Display a text and wait for user response.

This can display a large text and will add scrollbars when needed.

showFile( filename)

askItems( items,caption=None)
Ask the value of some items to the user.

Create an interactive widget to let the user set the value of some items. Input is a list of input items (basically [key,value] pairs). See the widgets.InputDialog class for complete description of the available input items.

The remaining arguments are keyword arguments that are passed to the InputDialog.getResult method. A timeout (in seconds) can be specified to have the input dialog interrupted automatically.

Return a dictionary with the results: for each input item there is a (key,value) pair. Returns an empty dictionary if the dialog was canceled. Sets the dialog timeout and accepted status in global variables.

dialogTimedOut( )
Returns True if the last askItems() dialog timed out.

dialogAccepted( )
Returns True if the last askItems() dialog was accepted.

askFilename( cur=None,filter="All files (*.*)",exist=False,multi=False)
Ask for a file name or multiple file names using a file dialog.

cur is a directory or filename. All the files matching the filter in that directory (or that file's directory) will be shown. If cur is a file, it will be selected as the current filename.

askDirname( cur=None)
Ask for an existing directory name.

cur is a directory. All the directories in that directory will initially be shown.

log( s)
Display a message in the cmdlog window.

draw( F,view=None,bbox=None,color='prop',colormap=None,alpha=0.5,mode=None,linewidth=None,shrink=None,marksize=None,wait=True,clear=None,allviews=False)
Draw object(s) with specified settings and direct camera to it.

The first argument is an object to be drawn. All other arguments are settings that influence how the object is being drawn.

F is either a Formex or a TriSurface object, or a name of such object (global or exported), or a list thereof. If F is a list, the draw() function is called repeatedly with each of ithe items of the list as first argument and with the remaining arguments unchanged.

The remaining arguments are drawing options. If None, they are filled in from the current viewport drawing options.

view is either the name of a defined view or 'last' or None. Predefined views are 'front','back','top','bottom','left','right','iso'. With view=None the camera settings remain unchanged (but might be changed interactively through the user interface). This may make the drawn object out of view! With view='last', the camera angles will be set to the same camera angles as in the last draw operation, undoing any interactive changes. The initial default view is 'front' (looking in the -z direction).

bbox specifies the 3D volume at which the camera will be aimed (using the angles set by view). The camera position wil be set so that the volume comes in view using the current lens (default 45 degrees). bbox is a list of two points or compatible (array with shape (2,3)). Setting the bbox to a volume not enclosing the object may make the object invisible on the canvas. The special value bbox='auto' will use the bounding box of the objects getting drawn (object.bbox()), thus ensuring that the camera will focus on these objects. The special value bbox=None will use the bounding box of the previous drawing operation, thus ensuring that the camera's target volume remains unchanged.

color,colormap,linewidth,alpha,marksize are passed to the creation of the 3D actor.

shrink is a floating point shrink factor that will be applied to object before drawing it.

If the Formex has properties and a color list is specified, then the the properties will be used as an index in the color list and each member will be drawn with the resulting color. If color is one color value, the whole Formex will be drawn with that color. Finally, if color=None is specified, the whole Formex is drawn in black.

Each draw action activates a locking mechanism for the next draw action, which will only be allowed after drawdelay seconds have elapsed. This makes it easier to see subsequent images and is far more elegant that an explicit sleep() operation, because all script processing will continue up to the next drawing instruction. The value of drawdelay is set in the config, or 2 seconds by default. The user can disable the wait cycle for the next draw operation by specifying wait=False. Setting drawdelay=0 will disable the waiting mechanism for all subsequent draw statements (until set >0 again).

setDrawOptions( d)

showDrawOptions( )

reset( )

resetAll( )

shrink( v)

setView( name,angles=None)
Set the default view for future drawing operations.

If no angles are specified, the name should be an existing view, or the predefined value 'last'. If angles are specified, this is equivalent to createView(name,angles) followed by setView(name).

_shrink( F,factor)
Return a shrinked object.

A shrinked object is one where each element is shrinked with a factor around its own center.

drawVectors( P,v,d=1.0,color='red')

drawPlane( P,N,size)

drawMarks( X,M,color='black')
Draw a list of marks at points X.

X is an Coords array. M is a list with the same length as X. The string representation of the marks are drawn at the corresponding 3D coordinate.

drawNumbers( F,color='black',trl=None,offset=0)
Draw numbers on all elements of F.

Normally, the numbers are drawn at the centroids of the elements. A translation may be given to put the numbers out of the centroids, e.g. to put them in front of the objects to make them visible, or to allow to view a mark at the centroids. If an offset is specified, it is added to the shown numbers.

drawVertexNumbers( F,color='black',trl=None)
Draw (local) numbers on all vertices of F.

Normally, the numbers are drawn at the location of the vertices. A translation may be given to put the numbers out of the location, e.g. to put them in front of the objects to make them visible, or to allow to view a mark at the vertices.

drawText3D( P,text,color='black',font=None,size=None)
Draw a text at a 3D point P.

drawViewportAxes3D( pos,color=None)
Draw two viewport axes at a 3D position.

drawBbox( A)
Draw the bbox of the actor A.

drawActor( A)
Draw an actor and update the screen.

undraw( itemlist)
Remove an item or a number of items from the canvas.

Use the return value from one of the draw... functions to remove the item that was drawn from the canvas. A single item or a list of items may be specified.

focus( object)
Move the camera thus that object comes fully into view.

object can be anything having a bbox() method.

The camera is moved with fixed axis directions to a place where the whole object can be viewed using a 45. degrees lens opening. This technique may change in future!

view( v,wait=False)
Show a named view, either a builtin or a user defined.

setTriade( on=None,size=1.0,pos=[0.0,0.0,0.0])
Toggle the display of the global axes on or off.

If on is True, the axes triade is displayed, if False it is removed. The default (None) toggles between on and off.

drawText( text,x,y,adjust='left',font='helvetica',size=14,color=None)
Show a text at position x,y using font.

annotate( annot)
Draw an annotation.

unannotate( annot)

decorate( decor)
Draw a decoration.

undecorate( decor)

frontView( )

backView( )

leftView( )

rightView( )

topView( )

bottomView( )

isoView( )

createView( name,angles)
Create a new named view (or redefine an old).

The angles are (longitude, latitude, twist). If the view name is new, and there is a views toolbar, a view button will be added to it.

zoomBbox( bb)
Zoom thus that the specified bbox becomes visible.

zoomRectangle( )
Zoom a rectangle selected by the user.

zoomAll( )
Zoom thus that all actors become visible.

zoom( f)

bgcolor( color)
Change the background color (and redraw).

fgcolor( color)
Set the default foreground color.

renderMode( mode)

wireframe( )

flat( )

smooth( )

smoothwire( )

flatwire( )

opacity( alpha)
Set the viewports transparency.

lights( onoff)
Set the lights on or off

set_light_value( typ,val)
Set the value of one of the lighting parameters for the currrent view

typ is one of 'ambient','specular','emission','shininess' val is a value between 0.0 and 1.0

set_ambient( i)

set_specular( i)

set_emission( i)

set_shininess( i)

linewidth( wid)
Set the linewidth to be used in line drawings.

clear_canvas( )
Clear the canvas.

This is a low level function not intended for the user.

clear( )
Clear the canvas

redraw( )

pause( msg="Use the Step or Continue button to proceed")
Pause the execution until an external event occurs.

When the pause statement is executed, execution of the pyformex script is suspended until some external event forces it to proceed again. Clicking the STEP or CONTINUE button will produce such an event.

step( )
Perform one step of a script.

A step is a set of instructions until the next draw operation. If a script is running, this just releases the draw lock. Else, it starts the script in step mode.

fforward( )

delay( i)
Set the draw delay in seconds.

sleep( timeout=None)
Sleep until key/mouse press in the canvas or until timeout

wakeup( mode=0)
Wake up from the sleep function.

This is the only way to exit the sleep() function. Default is to wake up from the current sleep. A mode > 0 forces wakeup for longer period.

printbbox( )

printviewportsettings( )

layout( nvps=None,ncols=None,nrows=None)
Set the viewports layout.

addViewport( )
Add a new viewport.

removeViewport( )
Remove a new viewport.

linkViewport( vp,tovp)
Link viewport vp to viewport tovp.

Both vp and tovp should be numbers of viewports.

viewport( n)
Select the current viewport

updateGUI( )
Update the GUI.

flyAlong( path='flypath',upvector=[0.,1.,0.],sleeptime=None)
Fly through the scene along the flypath.

highlightActors( K)
Highlight a selection of actors on the canvas.

K is Collection of actors as returned by the pick() method. colormap is a list of two colors, for the actors not in, resp. in the Collection K.

highlightElements( K)
Highlight a selection of actor elements on the canvas.

K is Collection of actor elements as returned by the pick() method. colormap is a list of two colors, for the elements not in, resp. in the Collection K.

highlightEdges( K)
Highlight a selection of actor edges on the canvas.

K is Collection of TriSurface actor edges as returned by the pick() method. colormap is a list of two colors, for the edges not in, resp. in the Collection K.

highlightPoints( K)
Highlight a selection of actor elements on the canvas.

K is Collection of actor elements as returned by the pick() method.

highlightPartitions( K)
Highlight a selection of partitions on the canvas.

K is a Collection of actor elements, where each actor element is connected to a collection of property numbers, as returned by the partitionCollection() method.

set_selection_filter( i)
Set the selection filter mode

pick( mode='actor',single=False,func=None,filtr=None)
Enter interactive picking mode and return selection.

See viewport.py for more details. This function differs in that it provides default highlighting during the picking operation, a button to stop the selection operation

If no filter is given, the available filters are presented in a combobox.

pickActors( single=False,func=None,filtr=None)

pickElements( single=False,func=None,filtr=None)

pickPoints( single=False,func=None,filtr=None)

pickEdges( single=False,func=None,filtr=None)

highlight( K,mode)
Highlight a Collection of actor/elements.

K is usually the return value of a pick operation, but might also be set by the user. mode is one of the pick modes.

pickNumbers( marks=None)

set_edit_mode( i)
Set the drawing edit mode.

drawLinesInter( mode='line',single=False,func=None)
Enter interactive drawing mode and return the line drawing.

See viewport.py for more details. This function differs in that it provides default displaying during the drawing operation and a button to stop the drawing operation.

The drawing can be edited using the methods 'undo', 'clear' and 'close', which are presented in a combobox.

showLineDrawing( L)
Show a line drawing.

L is usually the return value of an interactive draw operation, but might also be set by the user.

setLocalAxes( mode=True)

setGlobalAxes( mode=True)