94. plugins.tools — A collection of graphical tools for pyFormex.

This is a collection of graphical tools for the pyFormex GUI. Many of these tools can be invoked from the Tools menu.

94.1. Classes defined in module plugins.tools

class plugins.tools.Label(point, text, color=0)

A colored string attached to a point in 3D.

Parameters:

• point (coords_like (3,)) – The coordinates of the point where the label is attached.

• text (str) – The string to display at the given point

• color (int) – The color to display the string with. It is an index into the current palette (pf.canvas.settings.colormap)

Notes

The Label class is intended to add discrete annotations to a rendering. It should not be used to add large annotation sets, like the numbers of all elements or nodes. Use drawNumbers() for that purpose.

match(point=None, text=None, color=None)

Check if Label attributes match the given values.

Returns:

True if the Label’s attributes match all the specified arguments.

print(prefix='')

Print a Label to the console

edit(xactions=[])

Interactively edit a Label.

Pops up a Dialog to edit each of the Label’s attributes. A list of extra action tuples (buttontext, function) may be specified to add extra action buttons on the Dialog. The default has a Cancen and an OK button.

class plugins.tools.Labels(gentext=None, gencolor=None, pointsize=10, gravity='ne', fontsize=20, autodraw=True, autoprint=True)

A flexibel collection of point annotations

The Labels class can hold a collection of Label items and provides function to interactively add, remove, or edit the labels. It can automatically generate text and color for new labels. Labels can also be added programmatically. In autodraw mode all changes are dynamically propagated to the rendering.

Parameters:

• gentext (callable, optional) – A function that returns the text for a new label. The default will generate texts like ‘point-0’, ‘point-1’…

• gencolor (callable, optional) – A function that returns the color index for a new label. The default generates the sequence 0, 1,…

• pointsize (int) – The size of the point drawn where the label is attached.

• gravity (str) – The gravity for alignment of the string with the attachment point.

• fontsize (int) – The font size to use for the label text.

• autodraw (bool) – If True (default), the labels are (re)drawn automatically after each add or remove operation.

• autoprint (bool) – If True (default), every label that is added is also printed to the console with its color.

clear()

Remove all labels.

property nlabels

Return the number of labels

property points

Return a Coords with all label attachment points

property texts

Return a list with all label texts

property colors

Return an int array with all labels colors

printc(header='LABELS:', indent='  ')

Print the list of labels in color on the console

add(labels)

Add one or more labels

Parameters:

labels (Label | list[Label]) – One or more Label instances to add to the Labels.

genLabel(point, text=None, color=None)

Create a new Label without adding it to the collection.

Parameters: see Label.

Returns:

Label – A Label with the provided attributes or where not provided, those generated by the specified or default gentext/gencolor function. This Label is not automatically added to the Labels collection.

See also

add

add a Label to the Labels collection

addLabel

create a Label and add it to the collection

addLabel(point, text=None, color=None)

Create a new label and add it to the collection.

match(point=None, text=None, color=None)

Match labels by point, text and/or color

Matches all labels in the collection with the given parameters.

Returns:

bool array – A bool array holding True or False for every Label in the collection.

See also

find

return indices of matching labels

find(point=None, text=None, color=None)

Return indices fo matching labels.

Returns:

int array – The indices of the labels matching the provided parameters.

remove(point=None, text=None, color=None)

Remove labels by point coordinates, text or color

Removes all the labels matching the provided parameters.

removeLabel(label)

Remove a label

Parameters:

• label (Label) – A Label to be removed.

• attributes. (Removed all the labels matching the provided Label's) –

draw()

Draw the collection of labels.

This keeps track of the generated scene actors, and removes the previous ones when a new draw is done. Two actors are drawn: one with the dots representing the points, and one with the text strings.

undraw()

Remove the labels from the rendering

94.2. Functions defined in module plugins.tools

plugins.tools.mergedSurface(*objects)

Create a single surface from multiple Geometry objects

Parameters:

objects (list of Geometry) – Any number of Geometry subclass instances. The objects that are TriSurface or convertible to TriSurface are merged into a single surface. The other ones are skipped with a message.

Returns:

TriSurface – A single TriSurface containing all the geometry objects convertable to surface.

plugins.tools.labelPoints(labels=None, gentext=None, edit=False)

Interactively create/edit/remove point labels.

Starts a point picking mode and creates a label for every picked point. The labels are collected in a Labels instance, can be edited and removed, and are drawn automatically.

Parameters:

• labels (Labels, optional) – A Labels collection of labels. If provided, the labels are added to this collection and existing labels can be edited. If not provided, a default Labels is created.

• gentext (callable, optional) – Only used if no labels was provided. The created default Labels will then use this function to generate the label text.

• edit (bool, optional) – If True (default), every generated label will immediately show an edit Dialog to change its attributes. If False, generated labels can not be changed, but may be edited afterwards.

Returns:

Labels – The Labels collection: either the update one that was passed in, or a newly generated one.

Notes

Points can be picked one by one or multiple at once. Picked points are then handled one by one. If no label exists at point, a new one is generated. If edit is True, the label (new or old) can then be edited. The edit dialog allows to accept, change or remove the label. When all points are handled, a new pick can be done. If the CTRL key is depressed during picking, existing labels at the points are removed instead of adding/editing labels. The procedure stops when the ESC key or right mouse button is pressed. The Labels collection is then returned. Labels.undraw() can be used to remove them from the screen, and Labels.draw() to show them again.

Currently, if you edit the coordinates of a point thus that they do not match a point of a regular actor, you will not be able to pick that point again and thus to edit/remove that label.

plugins.tools.labelPoints2D(query='point', *, surface=None, missing='r', zvalue=None, npoints=-1, labels=None, gravity='e', drawstyle=2, linewidth=2, prec='+.4f', labeltext=None)

Interactively create and label points on a plane or a surface.

Puts the user in an interactive projective mode where each mouse click generates a 3D point. Since the mouse click only generates two coordinates (in a plane perpendicular to the camera axis), the third coordinate (depth) has to be defined by projection in the direction of the camera axis) onto a surface or a plane. This only works well visually if the camera is in projection mode. Therefore perspective mode is switched off during the operation (which may slightly change the rendering) and the camera is locked. The camera is restored at the end.

The ‘query’ parameter defines what type of info is put in the labels attached to the/some points. There are currently 4 modes:

• ‘point’: every point is labeled with an index.

• ‘coords’: every point is labeled with the 2D coordinates of the point.

• ‘dist’: every second point is labeled with the 2D distance from the previous point.

• ‘angle’: after every third point the penultimate point is labeled with the 2D angle between the 2D line segments from that point to the next and to the previous point.

All labeled points are collected in a Labels instance. The operation ends when either a required number of labeled points is generated, or the user stops the interactive mode by accepting (right mouse button or ENTER key) or cancelling (ESC key).

Parameters:

• query (str) – Defines what type of information is put in the labels and how many points are labeled. It should be one of ‘point’, ‘coords’, ‘dist’ or ‘angle’. See explanation above.

• surface (TriSurface | ‘_merged_’, optional) – A surface on which to draw the points. If provided, the points are created on that surface. A special value ‘_merged_’ will create a merged surface of all current actors that can be converted to surfaces. Thus it is possible to draw points on a quad Mesh or even on the surface of a volume Mesh. Mouse clicks outside the surface are handled according to the missing parameter. Note that this function does not draw the surface itself. The caller must make sure that the proper surface is drawn beforehand to guide the user in putting the points.

• missing ('r' | 'o' | 'e') – In surface mode, defines what to do when clicking outside the surface: with the default ‘r’, no point is created; with ‘o’, a point is created on a plane in front of the surface; with ‘e’ a ProjecionMissing is raised.

• zvalue (float, optional) – The depth value of a plane perpendicular on the camera axis on which the points will be created. It is measured from the focus point towards the camera eye. Only used if no surface was provided. If not provided (and neither is surface), a plane through the camera focus is used.

• npoints (int, optional) – The number of points to be created. If < 0 (default), an unlimited number of points can be created. It is stopped by clicking the right mouse button of hitting ENTER.

• labels (Labels, optional) – The Labels class where the generated points should be added. If not provided, a new Labels instance is created.

• gravity (str | None) – If not None, overrides the gravity for the labels.

• drawstyle (int) – Type of line decorations drawn with query = ‘point’ or ‘coords’.

• linewidth (float) – Line width to be used in line decorations.

• prec (str) – Format string to use for each of the coordinate values.

• labeltext (callable | None) – If provided, overrides the default label text generator. The parameters passed to the callable depend on the query mode: for ‘point’ and ‘coords’, it is (P, prec), where P is the point in camera coodinates and prec is the prec argument; for ‘dist’ mode, two points are passed (P, Q, prec) and for ‘angle’ mode three points (P, Q, R, prec).

Returns:

labels (Labels) – Returns the passed or created Labels instance, with the generated points added to it. The 3D global coordinates of the points can be obtained from labels.points.

See also

pyformex.plugins.tools_menu.labelPoints2DDialog()

provides a dialog to set and remember some of the parameters for this function and then calls this function with the global Labels collection of the Tools menu.

plugins.tools.getPoints(K)

Return all points in the Collection as a Coords

plugins.tools.indent_str(s, n)

Indent a multiline string

plugins.tools.getObjectItems(obj, items, mode)

Get the specified items from object.

plugins.tools.getCollection(K)

Returns a collection.

plugins.tools.growCollection(K, **kargs)

Grow the collection with n frontal rings.

K should be a collection of elements. This should work on any objects that have a growSelection method, like a Mesh.

plugins.tools.partitionCollection(K)

Partition the collection according to node adjacency.

The actor numbers will be connected to a collection of property numbers, e.g. 0 [1 [4,12] 2 [6,20]], where 0 is the actor number, 1 and 2 are the property numbers and 4, 12, 6 and 20 are the element numbers.

plugins.tools.getPartition(K, prop)

Remove all partitions with property not in prop.

plugins.tools.exportObjects(obj, name, single=False)

Export a list of objects under the given name.

If obj is a list, and single=True, each element of the list is exported as a single item. The items will be given the names name-0, name-1, etc. Else, the obj is exported as is under the name.

plugins.tools.actorDialog(actorids)

Create an actor dialog for the specified actors (by index)