# 5. `gui.draw` — Create 3D graphical representations.

The draw module provides the basic user interface to the OpenGL rendering capabilities of pyFormex. The full contents of this module is available to scripts running in the pyFormex GUI without the need to import it.

## 5.1. Functions defined in module gui.draw

`gui.draw.``exitGui`(res=0)

  Terminate the GUI with a given status.

`gui.draw.``closeGui`()

  Close the GUI.

  Calling this function from a script closes the GUI and terminates pyFormex.

`gui.draw.``closeDialog`(name)

  Close the named dialog.

  Closes the InputDialog with the given name. If multiple dialogs are open with the same name, all these dialogs are closed.

  This only works for dialogs owned by the pyFormex GUI.

`gui.draw.``showMessage`(text, actions=['OK'], level='info', modal=True, align='00', **kargs)

  Show a short message widget and wait for user acknowledgement.

  There are three levels of messages: ‘info’, ‘warning’ and ‘error’. They differ only in the icon that is shown next to the test. By default, the message widget has a single button with the text ‘OK’. The dialog is closed if the user clicks a button. The return value is the button text.

`gui.draw.``showInfo`(text, actions=['OK'], modal=True)

  Show an informational message and wait for user acknowledgement.

`gui.draw.``warning`(text, actions=['OK'])

  Show a warning message and wait for user acknowledgement.

`gui.draw.``error`(text, actions=['OK'])

  Show an error message and wait for user acknowledgement.

`gui.draw.``ask`(question, choices=None, **kargs)

  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.

`gui.draw.``ack`(question, **kargs)

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

`gui.draw.``showText`(text, itemtype='text', actions=[('OK', None)], modal=True, mono=False)

  Display a text in a dialog window.

  Creates a dialog window displaying some text. The dialog can be modal (blocking user input to the main window) or modeless. Scrollbars are added if the text is too large to display at once. By default, the dialog has a single button to close the dialog.

  Parameters:

  - text: a multiline text to be displayed. It can be plain text or html or reStructuredText (starts with ‘..’).
  - itemtype: an InputItem type that can be used for text display. This should be either ‘text’ of ‘info’.
  - actions: a list of action button definitions.
  - modal: bool: if True, a modal dialog is constructed. Else, the dialog is modeless.
  - mono: if True, a monospace font will be used. This is only useful for plain text, e.g. to show the output of an external command.

  Returns:

  Modal dialog: | the result of the dialog after closing. The result is a dictionary with a single key: ‘text’ having the displayed text as a value. If an itemtype ‘text’ was used, this may be a changed text.
  Modeless dialog:
  | the open dialog window itself.

`gui.draw.``showFile`(filename, mono=True, **kargs)

  Display a text file.

  This will use the `showText()` function to display a text read from a file. By default this uses a monospaced font. Other arguments may also be passed to ShowText.

`gui.draw.``showDoc`(obj=None, rst=True, modal=False)

  Show the docstring of an object.

  Parameters:

  - obj: any object (module, class, method, function) that has a __doc__ attribute. If None is specified, the docstring of the current application is shown.
  - rst: bool. If True (default) the docstring is treated as being reStructuredText and will be nicely formatted accordingly. If False, the docstring is shown as plain text.

`gui.draw.``editFile`(fn, exist=False)

  Load a file into the editor.

  Parameters:

  - fn: filename. The corresponding file is loaded into the editor.
  - exist: bool. If True, only existing filenames will be accepted.

  Loading a file in the editor is done by executing an external command with the filename as argument. The command to be used can be set in the configuration. If none is set, pyFormex will try to lok at the EDITOR and VISUAL environment settings.

  The main author of pyFormex uses ‘emacsclient’ as editor command, to load the files in a running copy of Emacs.

`gui.draw.``askItems`(items, timeout=None, **kargs)

  Ask the value of some items to the user.

  Create an interactive widget to let the user set the value of some items. The items are specified as a list of dictionaries. Each dictionary contains the input arguments for a widgets.InputItem. It is often convenient to use one of the _I, _G, ot _T functions to create these dictionaries. These will respectively create the input for a simpleInputItem, a groupInputItem or a tabInputItem.

  For convenience, simple items can also be specified as a tuple. A tuple (key,value) will be transformed to a dict {‘key’:key, ‘value’:value}.

  See the widgets.InputDialog class for complete description of the available input items.

  A timeout (in seconds) can be specified to have the input dialog interrupted automatically and return the default values.

  The remaining arguments are keyword arguments that are passed to the widgets.InputDialog.getResult method.

  Returns 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.

`gui.draw.``currentDialog`()

  Returns the current dialog widget.

  This returns the dialog widget created by the askItems() function, while the dialog is still active. If no askItems() has been called or if the user already closed the dialog, None is returned.

`gui.draw.``dialogAccepted`()

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

`gui.draw.``dialogRejected`()

  Returns True if the last askItems() dialog was rejected.

`gui.draw.``dialogTimedOut`()

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

`gui.draw.``askFile`(cur=None, filter='all', exist=True, multi=False, compr=False, change=True, timeout=None, caption=None, sidebar=None)

  Ask for a file name or multiple file names using a file dialog.

  Parameters:

  - cur: directory or filename. Specifies the starting point of the selection dialog. All the files in the specified directory (or the file’s directory) matching the filter will be presented to the user. If cur is a file, it will be set as the initial selection.
  - filter: string or list of strings. Specifies a (set of) filter(s) to be applied on the files in the selected directory. This allows to narrow down the selection possibilities. The filter argument is passed through the `utils.fileDescription()` function to create the actual filter set. If multiple filters are included, the user can select the appropriate one from the dialog.
  - exist: bool: if True, the filename must exist. The default (False) will allow a new file to be created or an existing to be used.
  - multi: bool. If True, allows the user to pick multiple file names in a single operation.
  - compr: bool. If True, the specified pattern will be extended with the corresponding compressed file types.
  - change: bool. If True (default), the current working directory will be changed to the parent directory of the selection.
  - caption: string. This string will be displayed as the dialog title instead of the default one.
  - timeout: float. If specified, the dialog will timeout after the specified number of seconds.
  - caption: string. If specified, it will be displayed as the FileDialog title.
  - sidebar: list of paths. If specified, these will be added to the sidebar (in addition to the configured paths).

  Returns the result of the file dialog. If the user accepted the selection, this will be a Dict with at least a key ‘fn’ holding the selected filename(s): a single file name is if multi is False, or a list of file names if multi is True. If the user canceled the selection process, an empty dict is returned.

`gui.draw.``askFilename`(*args, **kargs)

  Ask for a file name or multiple file names using a file dialog.

  This functions takes the same parameters as `askFile()`, and is functionally equivalent to it. However, in case of an accepted dialog it only returns the filename(s) and in case of a canceled dialog it returns None.

`gui.draw.``askNewFilename`(cur=None, filter='All files (*.*)', compr=False, timeout=None, caption=None, sidebar=None)

  Ask a single new filename.

  This is a convenience function for calling askFilename with the arguments exist=False.

`gui.draw.``askDirname`(path=None, change=True, byfile=False, caption=None)

  Interactively select a directory and change the current workdir.

  The user is asked to select a directory through the standard file dialog. Initially, the dialog shows all the subdirectories in the specified path, or by default in the current working directory.

  The selected directory becomes the new working directory, unless the user canceled the operation, or the change parameter was set to False.

`gui.draw.``checkWorkdir`()

  Ask the user to change the current workdir if it is not writable.

  Returns True if the new workdir is writable.

`gui.draw.``printMessage`(s, **kargs)

  Print a message on the message board.

  Parameters:

  - s: string to print
  - kargs: more keyword arguments are passed to meth:MessageBpard.write.

  This function forces an update of the GUI, so that the output message is guaranteed to be visible. If a logfile was opened, the message is also written to the log file.

`gui.draw.``delay`(s=None)

  Get/Set the draw delay time.

  Returns the current setting of the draw wait time (in seconds). This drawing delay is obeyed by drawing and viewing operations.

  A parameter may be given to set the delay time to a new value. It should be convertable to a float. The function still returns the old setting. This may be practical to save that value to restore it later.

`gui.draw.``wait`(relock=True)

  Wait until the drawing lock is released.

  This uses the drawing lock mechanism to pause. The drawing lock ensures that subsequent draws are retarded to give the user the time to view. The use of this function is prefered over that of `pause()` or `sleep()`, because it allows your script to continue the numerical computations while waiting to draw the next screen.

  This function can be used to retard other functions than draw and view.

`gui.draw.``play`(refresh=False)

  Start the current script or if already running, continue it.

`gui.draw.``replay`()

  Replay the current app.

  This works pretty much like the play() function, but will reload the current application prior to running it. This function is especially interesting during development of an application. If the current application is a script, then it is equivalent with play().

`gui.draw.``fforward`()

  Releases the drawing lock mechanism indefinely.

  Releasing the drawing lock indefinely means that the lock will not be set again and your script will execute till the end.

`gui.draw.``pause`(timeout=None, msg=None)

  Pause the execution until an external event occurs or timeout.

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

  - timeout: float: if specified, the pause will only last for this many seconds. It can still be interrupted by the STEP buttons.
  - msg: string: a message to write to the board to explain the user about the pause

`gui.draw.``zoomRectangle`()

  Zoom a rectangle selected by the user.

`gui.draw.``getRectangle`()

  Zoom a rectangle selected by the user.

`gui.draw.``zoomBbox`(bb)

  Zoom thus that the specified bbox becomes visible.

`gui.draw.``zoomObj`(object)

  Zoom thus that the specified object becomes visible.

  object can be anything having a bbox() method or a list thereof.

`gui.draw.``zoomAll`()

  Zoom thus that all actors become visible.

`gui.draw.``zoom`(f)

  Zoom with a factor f

  A factor > 1.0 zooms out, a factor < 1.0 zooms in.

`gui.draw.``focus`(point)

  Move the camera focus to the specified point.

  Parameters:

  - point: float(3,) or alike

  The camera focus is set to the specified point, while keeping a parallel camera direction and same zoom factor. The specified point becomes the center of the screen and the center of camera rotations.

`gui.draw.``flyAlong`(path, upvector=[0.0, 1.0, 0.0], sleeptime=None)

  Fly through the current scene along the specified path.

  - path: a plex-2 or plex-3 Formex (or convertibel to such Formex) specifying the paths of camera eye and center (and upvector).
  - upvector: the direction of the vertical axis of the camera, in case of a 2-plex camera path.
  - sleeptime: a delay between subsequent images, to slow down the camera movement.

  This function moves the camera through the subsequent elements of the Formex. For each element the first point is used as the center of the camera and the second point as the eye (the center of the scene looked at). For a 3-plex Formex, the third point is used to define the upvector (i.e. the vertical axis of the image) of the camera. For a 2-plex Formex, the upvector is constant as specified in the arguments.

`gui.draw.``viewport`(n=None)

  Select the current viewport.

  n is an integer number in the range of the number of viewports, or is one of the viewport objects in pyformex.GUI.viewports

  if n is None, selects the current GUI viewport for drawing

`gui.draw.``nViewports`()

  Return the number of viewports.

`gui.draw.``layout`(nvps=None, ncols=None, nrows=None, pos=None, rstretch=None, cstretch=None)

  Set the viewports layout.

`gui.draw.``addViewport`()

  Add a new viewport.

`gui.draw.``removeViewport`()

  Remove the last viewport.

`gui.draw.``linkViewport`(vp, tovp)

  Link viewport vp to viewport tovp.

  Both vp and tovp should be numbers of viewports.

`gui.draw.``updateGUI`()

  Update the GUI.

`gui.draw.``highlightActor`(actor)

  Highlight an actor in the scene.

`gui.draw.``removeHighlight`()

  Remove the highlights from the current viewport

`gui.draw.``pick`(mode='actor', filter=None, oneshot=False, func=None, pickable=None, prompt=None)

  Enter interactive picking mode and return selection.

  See `Canvas.pick()` for more details. This function differs in that it provides default highlighting during the picking operation and a OK/Cancel buttons to stop the picking operation.

  Parameters:

  - mode: defines what to pick : one of ‘actor’, ‘element’, ‘face’, ‘edge’, ‘point’ or ‘prop’. ‘actor’ picks complete actors. ‘element’ picks elements from one or more actor(s). ‘face’ and ‘edge’ pick faces, resp. edges of elements (only available for Mesh objects). ‘point’ picks points of Formices or nodes of Meshes. ‘prop’ is like ‘element’, but returns the property numbers of the picked elements instead of the element numbers.
  - filter: one of the selection_filters. The default picking filter is activated on entering the pick mode. All available filters are presented in a combobox.
  - oneshot: if True, the function returns as soon as the user ends a picking operation. The default is to let the user modify his selection and only to return after an explicit cancel (ESC or right mouse button).
  - func: if specified, this function will be called after each atomic pick operation. The Collection with the currently selected objects is passed as an argument. This can e.g. be used to highlight the selected objects during picking.
  - pickable: a list of Actors to pick from. The default is to use a list with all Actors having the pickable=True attribute (which is the default for newly constructed Actors).
  - prompt: the text printed to prompt the user to start picking. If None, a default prompt is printed. Specify an empty string to avoid printing a prompt.

  Returns a (possibly empty) Collection with the picked items. After return, the value of the pf.canvas.selection_accepted variable can be tested to find how the picking operation was exited: True means accepted (right mouse click, ENTER key, or OK button), False means canceled (ESC key, or Cancel button). In the latter case, the returned Collection is always empty

`gui.draw.``pickProps`(filter=None, oneshot=False, func=None, pickable=None, prompt=None)

  Pick property numbers

  This is like pick(‘element’), but returns the (unique) property numbers of the picked elements of the actors instead.

`gui.draw.``pickNumbers`(marks=None)

  Pick drawn numbers

`gui.draw.``pickFocus`()

  Enter interactive focus setting.

  This enters interactive point picking mode and sets the focus to the center of the picked points.

`gui.draw.``set_edit_mode`(s)

  Set the drawing edit mode.

`gui.draw.``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.

`gui.draw.``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.

`gui.draw.``exportWebGL`(fn, createdby=50, **kargs)

  Export the current scene to WebGL.

  Parameters:

  - fn : string: the (relative or absolute) filename of the .html, .js and .pgf files comprising the WebGL model. It can contain a directory path and an any extension. The latter is dropped and not used.
  - createdby: int: width in pixels of the ‘Created by pyFormex’ logo appearing on the page. If < 0, the logo is displayed at its natural width. If 0, the logo is suppressed.
  - **kargs: any other keyword parameteris passed to the `WebGL` initialization. The name can not be specified: it is derived from the fn parameter.

  Returns the absolute pathname of the generated .html file.

`gui.draw.``multiWebGL`(name=None, fn=None, title=None, description=None, keywords=None, author=None, createdby=50)

  Export the current scene to WebGL.

  fn is the (relative or absolute) pathname of the .html and .js files to be created.

  When the export is finished, returns the absolute pathname of the generated .html file. Else, returns None.

`gui.draw.``showURL`(url)

  Show an URL in the browser

  - url: url to load

`gui.draw.``showHTML`(fn=None)

  Show a local .html file in the browser

  - fn: name of a local .html file. If unspecified, a FileDialog dialog is popped up to select a file.

`gui.draw.``resetGUI`()

  Reset the GUI to its default operating mode.

  When an exception is raised during the execution of a script, the GUI may be left in a non-consistent state. This function may be called to reset most of the GUI components to their default operating mode.

`gui.draw.``flatten`(objects, recurse=True)

  Flatten a list of geometric objects.

  Each item in the list should be either:

  - a drawable object,
  - a string with the name of such an object,
  - a list of any of these three.

  This function will flatten the lists and replace the string items with the object they point to. The result is a single list of drawable objects. This function does not enforce the objects to be drawable. That should be done by the caller.

`gui.draw.``drawable`(objects)

  Filters the drawable objects from a list.

  The input is a list, usually of drawable objects. For each item in the list, the following is done:

  - if the item is drawable, it is kept as is,
  - if the item is not drawable but can be converted to a Formex, it is converted,
  - if it is neither drawable nor convertible to Formex, it is removed.

  The result is a list of drawable objects (since a Formex is drawable).

`gui.draw.``draw`(F, clear=None, single=False, **kargs)

  Draw geometrical object(s) with specified drawing options and settings.

  This is the generic drawing function in pyFormex. The user can specifies the Geometry and optional drawing parameters. The function returns the Actor(s) resulting from the drawing operation. The Actors can further be used to change the rendering.

  Parameters:

  - F: specifies all geometry that will be drawn in a single argument. It can be one of the following:

    - a drawable object (a Geometry object like Formex, Mesh or TriSurface, or another object having a proper actor method),
    - the name of a global pyFormex variable refering to such an object,
    - a list or nested list of any of the above items.

    The possibility of a nested list means that any complex collections of geometry can be drawn in a single operation. The (nested) list is recursively flattened, replacing string values by the corresponding value from the pyFormex global variables dictionary, until a single list of drawable objects results. Next the undrawable items are removed from the list. The resulting list of drawable objects are drawn in a single pass, with the same options and default drawing attributes.

  - clear: clear the scene before drawing.

  - single: specifies the type of result if F is a list. If False, a flat list with all Actors for all Geometries in F is returned. If True, a single Actor is returned, corresponding with F[0] (in the flattened list). The other actors in the flattened list are set as its children.

  The remaining parameters are the default drawing parameters to be used. They will apply unless overridden by attributes set in the Geometry itself (see `geometry.Geometry.attrib()`). There is a long list of possible settings, but in most case only a few will be needed.

  Warning

  The remainder of this docstring is from the old version (<= 0.9) of pyFormex. While most of the arguments are still valid and the documentation below is useful, there might be some slight changes in the behavior.

  Note

  DEVS: TODO: THIS DOCSTRING NEEDS TO BE UPDATED !

  Settings: specify how the geometry will be drawn. These arguments will

    be passed to the corresponding Actor for the object. The Actor is the graphical representation of the geometry. Not all Actors use all of the settings that can be specified here. But they all accept specifying any setting even if unused. The settings hereafter are thus a superset of the settings used by the different Actors. Settings have a default value per viewport, and if unspecified, most Actors will use the viewport default for that value.

    - color, colormap: specifies the color of the object (see below)
    - alpha: float (0.0..1.0): alpha value to use in transparent mode
    - bkcolor, bkcolormap: color for the backside of surfaces, if different from the front side. Specification as for front color.
    - bkalpha: float (0.0..1.0): alpha value for back side.
    - linewidth: float, thickness of line drawing
    - linestipple: stipple pattern for line drawing
    - marksize: float: point size for dot drawing
    - nolight: bool: render object as unlighted in modes with lights on
    - ontop: bool: render object as if it is on top. This will make the object fully visible, even when it is hidden by other objects. If more than one objects is drawn with ontop=True the visibility of the object will depend on the order of drawing.
  Options: these arguments modify the working of the draw functions.

    If None, they are filled in from the current viewport drawing options. These can be changed with the `setDrawOptions()` function. The initial defaults are: view=’last’, bbox=’auto’, shrink=False, clear=False, shrinkfactor=0.8.

    - 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. On creation of a viewport, 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 will 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.
    - shrink: bool: if specified, each object will be transformed by the `Coords.shrink()` transformation (with the current set shrinkfactor as a parameter), thus showing all the elements of the object separately. (Some other softwares call this an ‘exploded’ view).
    - clear: bool. By default each new draw operation adds the newly drawn objects to the shown scene. Using clear=True will clear the scene before drawing and thus only show the objects of the current draw action.
    - wait: bool. If True (default) the 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 renderings and is far more efficient than adding an explicit sleep() operation, because the script processing can continue up to the next drawing instruction. The value of drawdelay can be changed in the user settings or using the `delay()` function. Setting this value to 0 will disable the waiting mechanism for all subsequent draw statements (until set > 0 again). But often the user wants to specifically disable the waiting lock for some draw operation(s). This can be done without changing the drawdelay setting by specifyin wait=False. This means that the next draw operation does not have to wait.
    - allviews: currently not used
    - highlight: bool. If True, the object(s) will not be drawn as normal geometry, but as highlight (usually on top of other geometry), making them removeable by the remove highlight functions
    - silent: bool. If True (default), non-drawable objects will be silently ignored. If set False, an error is raised if an object is not drawable.
    - **kargs: any not-recognized keyword parameters are passed to the object’s Actor constructor. This allows the user to create customized Actors with new parameters.

  Specifying color:

  Color specification can take many different forms. Some Actors recognize up to six different color modes and the draw function adds even another mode (property color)

  - no color: color=None. The object will be drawn in the current viewport foreground color.
  - single color: the whole object is drawn with the specified color.
  - element color: each element of the object has its own color. The specified color will normally contain precisely nelems colors, but will be resized to the required size if not.
  - vertex color: each vertex of each element of the object has its color. In smooth shading modes intermediate points will get an interpolated color.
  - element index color: like element color, but the color values are not specified directly, but as indices in a color table (the colormap argument).
  - vertex index color: like vertex color, but the colors are indices in a color table (the colormap argument).
  - property color: as an extra mode in the draw function, if color=’prop’ is specified, and the object has an attribute ‘prop’, that attribute will be used as a color index and the object will be drawn in element index color mode. If the object has no such attribute, the object is drawn in no color mode.

  Element and vertex color modes are usually only used with a single object in the F parameter, because they require a matching set of colors. Though the color set will be automatically resized if not matching, the result will seldomly be what the user expects. If single colors are specified as a tuple of three float values (see below), the correct size of a color array for an object with nelems elements of plexitude nplex would be: (nelems,3) in element color mode, and (nelems,nplex,3) in vertex color mode. In the index modes, color would then be an integer array with shape respectively (nelems,) and (nelems,nplex). Their values are indices in the colormap array, which could then have shape (ncolors,3), where ncolors would be larger than the highest used value in the index. If the colormap is insufficiently large, it will again be wrapped around. If no colormap is specified, the current viewport colormap is used. The default contains eight colors: black=0, red=1, green=2, blue=3, cyan=4, magenta=5, yellow=6, white=7.

  A color value can be specified in multiple ways, but should be convertible to a normalized OpenGL color using the `colors.GLcolor()` function. The normalized color value is a tuple of three values in the range 0.0..1.0. The values are the contributions of the red, green and blue components.

`gui.draw.``setDrawOptions`(kargs0={}, **kargs)

  Set default values for the draw options.

  Draw options are a set of options that hold default values for the draw() function arguments and for some canvas settings. The draw options can be specified either as a dictionary, or as keyword arguments.

`gui.draw.``reset`()

  reset the canvas

`gui.draw.``shrink`(onoff, factor=None)

  Set shrinking on or off, and optionally set shrink factor

`gui.draw.``drawVectors`(P, v, size=None, nolight=True, **drawOptions)

  Draw a set of vectors.

  If size is None, draws the vectors v at the points P. If size is specified, draws the vectors size*normalize(v) P, v and size are single points or sets of points. If sets, they should be of the same size.

  Other drawoptions can be specified and will be passed to the draw function.

`gui.draw.``drawMarks`(X, M, color='black', prefix='', ontop=True, **kargs)

  Draw a list of marks at points X.

  Parameters:

  - X: Coords.
  - M: list of length X.ncoords(). The string representation of the items in the list are drawn at the corresponding 3D coordinate of X.
  - prefix: string. If specified, it is prepended to all drawn strings.
  - ontop: bool. If True, the marks are drawn on top, meaning they will all be visible, even those drawn at points hidden by the geometry. If False, hidden marks can be hidden by the drawn geometry.

  Other parameters can be passed to the `actors.TextArray` class.

`gui.draw.``drawFreeEdges`(M, color='black')

  Draw the feature edges of a Mesh

`gui.draw.``drawNumbers`(G, numbers=None, color='black', trl=None, offset=0, prefix='', ontop=None, **kargs)

  Draw numbers on all elements of a Geometry G.

  Parameters:

  - G: Geometry like (Coords, Formex, Mesh)
  - numbers: int array of length F.nelems(). If not specified, the range from 0 to F.nelems()-1 is used.
  - color: color to be used in drawing the numbers.
  - trl: If unspecified, the numbers are drawn at the centroids of the elements. A translation (x,y,z) 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.
  - offset: int. If specified, this value is added to the numbers. This is an easy ways to compare the drawing with systems using base 1 numbering.
  - prefix: string. If specified, it is added before every drawn number.

  Other parameters are passed to the `drawMarks()` function.

`gui.draw.``drawPropNumbers`(F, **kargs)

  Draw property numbers on all elements of F.

  This calls drawNumbers to draw the property numbers on the elements. All arguments of drawNumbers except numbers may be passed. If the object F thus not have property numbers, -1 values are drawn.

`gui.draw.``drawVertexNumbers`(F, color='black', trl=None, ontop=False)

  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.

`gui.draw.``drawBbox`(F, color='black', **kargs)

  Draw the bounding box of the geometric object F.

  F is any object that has a bbox method. Returns the drawn Annotation.

`gui.draw.``drawText`(text, pos, **kargs)

  Show a text at position pos.

  Draws a text at a given position. The position can be either a 2D canvas position, specified in pixel coordinates (int), or a 3D position, specified in global world coordinates (float). In the latter case the text will be displayed on the canvas at the projected world point, and will move with that projection, while keeping the text unscaled and oriented to the viewer. The 3D mode is especially useful to annotate parts of the geometry with a label.

  Parameters:

  - text: string to be displayed.
  - pos: (2,) int or (3,) float: canvas or world position.
  - any other parameters are passed to `opengl.textext.Text`.

`gui.draw.``drawText3D`(text, pos, **kargs)

  Show a text at position pos.

  Draws a text at a given position. The position can be either a 2D canvas position, specified in pixel coordinates (int), or a 3D position, specified in global world coordinates (float). In the latter case the text will be displayed on the canvas at the projected world point, and will move with that projection, while keeping the text unscaled and oriented to the viewer. The 3D mode is especially useful to annotate parts of the geometry with a label.

  Parameters:

  - text: string to be displayed.
  - pos: (2,) int or (3,) float: canvas or world position.
  - any other parameters are passed to `opengl.textext.Text`.

`gui.draw.``drawViewportAxes3D`(pos, color=None)

  Draw two viewport axes at a 3D position.

`gui.draw.``drawAxes`(cs=None, **kargs)

  Draw the axes of a coordinate system.

  Parameters:

  - cs: a `coordsys.CoordSys` If not specified, the global coordinate system is used.

  Other arguments can be added just like in the `candy.Axes` class.

  By default this draws the positive parts of the axes in the colors R,G,B and the negative parts in C,M,Y.

`gui.draw.``drawPrincipal`(F, weight=None, **kargs)

  Draw the principal axes of the geometric object F.

  F is Coords or Geometry. If weight is specified, it is an array of weights attributed to the points of F. It should have the same length as F.coords. Other parameter are drawing attributes passed to `drawAxes()`.

`gui.draw.``drawImage3D`(image, nx=0, ny=0, pixel='dot')

  Draw an image as a colored Formex

  Draws a raster image as a colored Formex. While there are other and better ways to display an image in pyFormex (such as using the imageView widget), this function allows for interactive handling the image using the OpenGL infrastructure.

  Parameters:

  - image: a QImage or any data that can be converted to a QImage, e.g. the name of a raster image file.
  - nx,`ny`: width and height (in cells) of the Formex grid. If the supplied image has a different size, it will be rescaled. Values <= 0 will be replaced with the corresponding actual size of the image.
  - pixel: the Formex representing a single pixel. It should be either a single element Formex, or one of the strings ‘dot’ or ‘quad’. If ‘dot’ a single point will be used, if ‘quad’ a unit square. The difference will be important when zooming in. The default is ‘dot’.

  Returns the drawn Actor.

  See also `drawImage()`.

`gui.draw.``drawImage`(image, w=0, h=0, x=-1, y=-1, color=(1.0, 1.0, 1.0), ontop=False)

  Draws an image as a viewport decoration.

  Parameters:

  - image: a QImage or any data that can be converted to a QImage, e.g. the name of a raster image file. See also the `loadImage()` function.
  - w,`h`: width and height (in pixels) of the displayed image. If the supplied image has a different size, it will be rescaled. A value <= 0 will be replaced with the corresponding actual size of the image.
  - x,`y`: position of the lower left corner of the image. If negative, the image will be centered on the current viewport.
  - color: the color to mix in (AND) with the image. The default (white) will make all pixels appear as in the image.
  - ontop: determines whether the image will appear as a background (default) or at the front of the 3D scene (as on the camera glass).

  Returns the Decoration drawn.

  Note that the Decoration has a fixed size (and position) on the canvas and will not scale when the viewport size is changed. The `bgcolor()` function can be used to draw an image that completely fills the background.

`gui.draw.``drawField`(fld, comp=0, scale='RAINBOW', symmetric_scale=False, cvalues=None, **kargs)

  Draw intensity of a scalar field over a Mesh.

  Parameters:

  - fld: a Field, specifying some value over a Geometry.
  - comp: int: if fld is a vectorial Field, specifies the component that is to be drawn.
  - scale: one of the color palettes defined in `colorscale`. If an empty string is specified, the scale is not drawn.
  - symmetric_scale: bool : if True the mid value of the color scale will be set to the value corresponding to the middle value of the fld data range. If False the mid value of the color scale will be set to 0.0 if the range extends over negative and positive values.
  - cvalues: None or list : specify the values between which to span the color palette. If None the min , max and mid values are taken from the field data. If list the values can be defined by the user as a list of 2 values (min, max) or 3 values (min, mid, max).
  - **kargs: any not-recognized keyword parameters are passed to the draw function to draw the Geometry.

  Draws the Field’s Geometry with the Field data converted to colors. A color legend is added to convert colors to values. NAN data are converted to numerical values using numpy.nan_to_num.

`gui.draw.``drawActor`(A)

  Draw an actor and update the screen.

`gui.draw.``drawAny`(A)

  Draw an Actor/Annotation/Decoration and update the screen.

`gui.draw.``undraw`(items)

  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.

`gui.draw.``view`(v, wait=True)

  Show a named view, either a builtin or a user defined.

  This shows the current scene from another viewing angle. Switching views of a scene is much faster than redrawing a scene. Therefore this function is prefered over `draw()` when the actors in the scene remain unchanged and only the camera viewpoint changes.

  Just like `draw()`, this function obeys the drawing lock mechanism, and by default it will restart the lock to retard the next draing operation.

`gui.draw.``setTriade`(on=None, pos='lb', siz=50, triade=None)

  Toggle the display of the global axes on or off.

  This is a convenient feature to display the global axes directions with rotating actor at fixed viewport size and position.

  Parameters:

  - on: boolean. If True, the global axes triade is displayed. If False, it is removed. The default (None) toggles between on and off. The remaining parameters are only used on enabling the triade.

  - pos: string of two characters. The characters define the horizontal (one of ‘l’, ‘c’, or ‘r’) and vertical (one of ‘t’, ‘c’, ‘b’) position on the camera’s viewport. Default is left-bottom.

  - siz: size (in pixels) of the triade.

  - triade: None, Geometry or str: defines the Geometry to be used for representing the global axes.

    If None: use the previously set triade, or set a default if no previous.

    If Geometry: use this to represent the axes. To be useful and properly displayed, the Geometry’s bbox should be around [(-1,-1,-1),(1,1,1)]. Drawing attributes may be set on the Geometry to influence the appearence. This allows to fully customize the Triade.

    If str: use one of the predefined Triade Geometries. Currently, the following are available:

    - ‘axes’: axes and coordinate planes as in `candy.Axes`
    - ‘man’: a model of a man as in data file ‘man.pgf’

`gui.draw.``setGrid`(on=None, d=None, s=None, **kargs)

  Toggle the display of the canvas grid on or off.

  This is a convenient feature to display a grid on the canvas.

  Parameters:

  - on: boolean. If True, the grid is displayed. If False, it is removed. The default (None) toggles between on and off. The remaining parameters are only used on enabling the grid.
  - d: None, int or (int,int). Distance in pixels between the grid lines. A tuple of two values specifies the distance in x,y direction. If not specified, the previous grid is used, or a default grid with d=100 is created.
  - s: None, int or (int,int). Half the size of the grid in pixels. A tuple of two values specifies size in x,y direction. If not specified the size is set equal to the current openGL canvas size.

  The grid is currently centered on the canvas, but we intend to add parameters to align it on any of the corners.

  Extra drawing parameters may be added to influence the appearence of the grid. An example:

      setGrid(d=200,linewidth=3,color=red,ontop=True)

`gui.draw.``annotate`(annot)

  Draw an annotation.

`gui.draw.``decorate`(decor)

  Draw a decoration.

`gui.draw.``createView`(name, angles, addtogui=False)

  Create a new named view (or redefine an old).

  The angles are (longitude, latitude, twist). By default, the view is local to the script’s viewport. If addtogui is True, a view button to set this view is added to the GUI.

`gui.draw.``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).

`gui.draw.``bgcolor`(color=None, image=None)

  Change the background color and image.

  Parameters:

  - color: a single color or a list of 4 colors. A single color sets a solid background color. A list of four colors specifies a gradient. These 4 colors are those of the Bottom Left, Bottom Right, Top Right and Top Left corners respectively.
  - image: the name of an image file. If specified, the image will be overlayed on the background colors. Specify a solid white background color to sea the image unaltered.

`gui.draw.``fgcolor`(color)

  Set the default foreground color.

`gui.draw.``hicolor`(color)

  Set the highlight color.

`gui.draw.``colormap`(color=None)

  Gets/Sets the current canvas color map

`gui.draw.``colorindex`(color)

  Return the index of a color in the current colormap

`gui.draw.``renderModes`()

  Return a list of predefined render profiles.

`gui.draw.``renderMode`(mode, light=None)

  Change the rendering profile to a predefined mode.

  Currently the following modes are defined:

  - wireframe
  - smooth
  - smoothwire
  - flat
  - flatwire
  - smooth_avg

`gui.draw.``wireMode`(mode)

  Change the wire rendering mode.

  Currently the following modes are defined: ‘none’, ‘border’, ‘feature’,’all’

`gui.draw.``lights`(state=True)

  Set the lights on or off

`gui.draw.``transparent`(state=True)

  Set the transparency mode on or off.

`gui.draw.``set_material_value`(typ, val)

  Set the value of one of the material lighting parameters

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

`gui.draw.``linewidth`(wid)

  Set the linewidth to be used in line drawings.

`gui.draw.``linestipple`(factor, pattern)

  Set the linewidth to be used in line drawings.

`gui.draw.``pointsize`(siz)

  Set the size to be used in point drawings.

`gui.draw.``canvasSize`(width, height)

  Resize the canvas to (width x height).

  If a negative value is given for either width or height, the corresponding size is set equal to the maximum visible size (the size of the central widget of the main window).

  Note that changing the canvas size when multiple viewports are active is not approved.

`gui.draw.``clear`(sticky=False)

  Clear the canvas.

  Removes everything from the current scene and displays an empty background.

  This function waits for the drawing lock to be released, but will not reset it.