2. formex
— Formex algebra in Python¶
This module defines the Formex
class, which is one of the two
major classes for representing geometry in pyFormex (the other one being
Mesh
). The Formex class represents geometry as a simple
3-dim :class`~coords.Coords` array.
This allows an implementation of most functionality
of Formex algebra with a consistent and easy to use syntax.
2.1. Classes defined in module formex¶
-
class
formex.
Formex
(data=None, prop=None, eltype=None)[source]¶ A structured collection of points in 3D space.
A Formex is a collection of points in a 3D cartesian space. The collection is structured into a set of elements all having the same number of points (e.g. a collection triangles all having three points).
As the Formex class is derived from
Geometry
, a Formex object has acoords
attribute which is aCoords
object. In a Formex this is always an array with 3 axes (numbered 0,1,2). Each scalar element of this array represents a coordinate. A row along the last axis (2) is a set of 3 coordinates and represents a point (aka. node, vertex).For simplicity’s sake, the current implementation only deals with points in a 3-dimensional space. This means that the length of axis 2 always equals 3. The user can create Formices (plural of Formex) in a 2-D space, but internally these will be stored with 3 coordinates, by adding a third value 0. All operations work with 3-D coordinate sets. However, it is easy to extract only a limited set of coordinates from the results, permitting to return to a 2-D environment
A plane of the array along the axes 2 and 1 is a set of points: we call this an element. This can be thought of as a geometrical shape (2 points form a line segment, 3 points make a triangle, …) or as an element in Finite Element terms. But it really is up to the user as to how this set of points is to be interpreted. He can set an element type on the Formex to make this clear (see below).
The whole Formex then represents a collection of such elements. The Formex concept and layout is made more clear in Formex data model in the pyFormex tutorial.
Additionally, a Formex may have a property set, which is an 1-D array of integers. The length of the array is equal to the length of axis 0 of the Formex data (i.e. the number of elements in the Formex). Thus, a single integer value may be attributed to each element. It is up to the user to define the use of this integer (e.g. it could be an index in a table of element property records). If a property set is defined, it will be copied together with the Formex data whenever copies of the Formex (or parts thereof) are made. Properties can be specified at creation time, and they can be set, modified or deleted at any time. Of course, the properties that are copied in an operation are those that exist at the time of performing the operation.
Finally, a Formex object can have an element type, because plexitude alone does not uniquely define what the geometric entities are, and how they should be rendered. By default, pyFormex will render plex-1 as points, plex-2 as line segments, plex-3 as triangles and any higher plexitude as polygons. But the user could e.g. set
eltype = 'tet4'
on a plex-4 Formex, and then that would be rendered as tetraeders.- Parameters
data (Formex, Coords, array_like or string) – Data to initialize the coordinates attribute
coords
in the Formex. See more details below.prop (int array_like, optional) – 1-dim int array with non-negative element property numbers. If provided,
setProp()
will be called to assign the specified properties.eltype (str |
ElementType
, optional) – The element type of the geometric entities (elements). If provided, it should be anElementType
instance or the name of such an instance. If not provided, the pyFormex default is used when needed and is based on the plexitude: 1 = point, 2 = line segment, 3 = triangle, 4 or more is a polygon.
The Formex coordinate data can be initialized by another
Formex
, by aCoords
, by a 1D, 2D or 3D array_like, or by a string that will be passed tocoords.fpattern()
to generate the coordinates. If 2D coordinates are given, a 3-rd coordinate 0.0 is added. Internally, Formices always work with 3D coordinates. Thus:F = Formex([[[1,0],[0,1]],[[0,1],[1,2]]])
creates a Formex with two elements, each having 2 points in the global z-plane. The innermost level of brackets group the coordinates of a point, the next level groups the points in an element, and the outermost brackets group all the elements of the Formex. Because the coordinates are stored in an array with 3 axes, all the elements in a Formex must contain the same number of points. This number is called the plexitude of the Formex.
A Formex may be initialized with a string instead of the numerical coordinate data. The string is passed to
coords.fpattern()
to generate the coordinates. The following are two equivalent definitions of (the circumference of) a triangle:F = Formex('2:010207') G = Formex('l:127')
Because the
Formex
class is derived fromGeometry
, it has the following attributes:coords
,prop
,attrib
,fields
.
Furthermore it has the following properties and methods that are applied on the
coords
attribute.xyz
,x
,y
,z
,xy
,yz
,xz
,points()
,bbox()
,center()
,bboxPoint()
,centroid()
,sizes()
,dsize()
,bsphere()
,bboxes()
,inertia()
,principalCS()
,principalSizes()
,distanceFromPlane()
,distanceFromLine()
,distanceFromPoint()
,directionalSize()
,directionalWidth()
,directionalExtremes()
.
Also, the following Coords transformation methods can be directly applied to a
Formex
object. The return value is a new Formex identical to the original, except for the coordinates, which are transformed by the specified method. Refer to the correspondingCoords
method for the usage of these methods:scale()
,adjust()
,translate()
,centered()
,align()
,rotate()
,shear()
,reflect()
,affine()
,toCS()
,fromCS()
,transformCS()
,position()
,cylindrical()
,hyperCylindrical()
,toCylindrical()
,spherical()
,superSpherical()
,toSpherical()
,bump()
,flare()
,map()
,map1()
,mapd()
,copyAxes()
,swapAxes()
,rollAxes()
,projectOnPlane()
,projectOnSphere()
,projectOnCylinder()
,isopar()
,addNoise()
,rot()
,trl()
.
Examples
>>> print(Formex([[0,1],[2,3]])) {[0.0,1.0,0.0], [2.0,3.0,0.0]} >>> print(Formex('1:0123')) {[0.0,0.0,0.0], [1.0,0.0,0.0], [1.0,1.0,0.0], [0.0,1.0,0.0]} >>> print(Formex('4:0123')) {[0.0,0.0,0.0; 1.0,0.0,0.0; 1.0,1.0,0.0; 0.0,1.0,0.0]} >>> print(Formex('2:0123')) {[0.0,0.0,0.0; 1.0,0.0,0.0], [1.0,1.0,0.0; 0.0,1.0,0.0]} >>> F = Formex('l:1234') >>> print(F) {[0.0,0.0,0.0; 1.0,0.0,0.0], [1.0,0.0,0.0; 1.0,1.0,0.0], [1.0,1.0,0.0; 0.0,1.0,0.0], [0.0,1.0,0.0; 0.0,0.0,0.0]} >>> print(F.info()) shape = (4, 2, 3) bbox[lo] = [0. 0. 0.] bbox[hi] = [1. 1. 0.] center = [0.5 0.5 0. ] maxprop = -1 >>> F.nelems() 4 >>> F.level() 1 >>> F.x array([[0., 1.], [1., 1.], [1., 0.], [0., 0.]]) >>> F.center() Coords([0.5, 0.5, 0. ]) >>> F.bboxPoint('+++') Coords([1., 1., 0.])
The Formex class defines the following attributes above the ones inherited from Geometry:
-
eltype
¶ - Type
None or
ElementType
-
__add__
(F)[source]¶ Concatenate two formices.
- Parameters
F (Formex) – A Formex with the same plexitude as self.
- Returns
Formex – The concatenation of the Formices self and F.
Note
This method implements the addition operation and allows to write simple expressions as F+G to concatenate the Formices F and G. When concatenating many Formices,
concatenate()
is more efficient however, because all the Formices in the list are concatenated in one operation.See also
concatenate
concatenate a list of Formices
Examples
>>> F = Formex([1.,1.,1.]).setProp(1) >>> G = Formex([2.,2.,2.]) >>> H = Formex([3.,3.,3.]).setProp(3) >>> K = F+G+H >>> print(K.asFormexWithProp()) {[1.0,1.0,1.0], [2.0,2.0,2.0], [3.0,3.0,3.0]} with prop [1 0 3]
2.2. Functions defined in module formex¶
-
formex.
connect
(Flist, nodid=None, bias=None, loop=False, eltype=None)[source]¶ Return a Formex which connects the Formices in list.
Creates a Formex of any plexitude by combining corresponding points from a number of Formices.
- Parameters
Flist (list of Formices) – The Formices to connect. The number of Formices in the list will be the plexitude of the newly created Formex. One point of an element in each Formex is taken to create a new element in the output Formex.
nodid (list of int, optional) – List of point indices to be used from each of the input Formices. If provided, the list should have the same length as
Flist
. The default is to use the first point of each element.bias (list of int, optional) – List of element bias values for each of the input Formices. Element iteration in the Formices will start at this number. If provided,, the list should have the same length as
Flist
. The default is to start at element 0.loop (bool) – If False (default), element generation will stop when the first input Formex runs out of elements. If True, element iteration in the shorted Formices will wrap around until all elements in all Formices have been used.
- Returns
Formex – A Formex with plexitude equal to
len(Flist)
. Each element of the Formex consists of a point from the corresponding element of each of the Formices in list. By default this is the first point of that element, but anodid
list may specify another point index. Corresponding elements in the Formices are by default those with the same element index; thebias
argument may specify another value to start the element indexing for each of the input Formices.If loop is False (default), the number of elements is the minimum over all Formices of the number of elements minus the corresponding bias. If loop is True, the number of elements is the maximum of the number of elements of all input Formices.
Notes
See also example Connect.
Examples
>>> F = Formex('1:1111') >>> G = Formex('l:222') >>> connect([F,G]) Formex([[[1., 0., 0.], [0., 0., 0.]], [[2., 0., 0.], [0., 1., 0.]], [[3., 0., 0.], [0., 2., 0.]]]) >>> connect([F,G],nodid=[0,1]) Formex([[[1., 0., 0.], [0., 1., 0.]], [[2., 0., 0.], [0., 2., 0.]], [[3., 0., 0.], [0., 3., 0.]]]) >>> connect([F,F],bias=[0,1]) Formex([[[1., 0., 0.], [2., 0., 0.]], [[2., 0., 0.], [3., 0., 0.]], [[3., 0., 0.], [4., 0., 0.]]]) >>> connect([F,F],bias=[0,1],loop=True) Formex([[[1., 0., 0.], [2., 0., 0.]], [[2., 0., 0.], [3., 0., 0.]], [[3., 0., 0.], [4., 0., 0.]], [[4., 0., 0.], [1., 0., 0.]]])