A generic interface to the Coords transformation methods
This module defines a generic Geometry superclass which adds all the possibilities of coordinate transformations offered by the Coords class to the derived classes.
Warning
This is experimental stuff!
A generic geometry object allowing transformation of coords sets.
The Geometry class is a generic parent class for all geometric classes, intended to make the Coords transformations available without explicit declaration. This class is not intended to be used directly, only through derived classes.
There is no initialization to be done when constructing a new instance of this class. The class just defines a set of methods which operate on the attribute coords which is be a Coords object. Most of the transformation methods of the Coords class are thus exported through the Geometry class to its derived classes, and when called, will get executed on the coords attribute. The derived class should make sure this attribute exists and contains the coordinates of all the points that should get transformed under a Coords transformation.
Derived classes can (and in most cases should) declare a method setCoords(coords) returning an object that is identical to the original, except for its coords being replaced by new ones with the same array shape.
The Geometry class provides two possible default implementations: - setCoords_inplace sets the coords attribute to the provided new
coords, thus changing the object itself, and returns itself,
When using the first method, a statement like `B = A.scale(0.5)` will result in both A and B pointing to the same scaled object, while with the second method, A would still be the untransformed object. Since the latter is in line with the design philosophy of pyFormex, it is set as the default setCoords method. Most derived classes that are part of pyFormex however override this default and implement a more efficient copy method.
Methods
Geometry objects have the following methods:
Return a copy scaled with scale[i] in direction i.
The scale should be a list of 3 scaling factors for the 3 axis directions, or a single scaling factor. In the latter case, dir (a single axis number or a list) may be given to specify the direction(s) to scale. The default is to produce a homothetic scaling.
Translate a Coords object.
The translation vector can be specified in one of the following ways:
If an axis number is given, a unit vector in the direction of the specified axis will be used. If an array of translation vectors is given, it should be broadcastable to the size of the Coords array. If a distance value is given, the translation vector is multiplied with this value before it is added to the coordinates.
Thus, the following lines are all equivalent:
F.translate(1)
F.translate(1,1)
F.translate([0,1,0])
F.translate([0,2,0],0.5)
Return a copy rotated over angle around axis.
The angle is specified in degrees. The axis is either one of (0,1,2) designating the global axes, or a vector specifying an axis through the origin. If no axis is specified, rotation is around the 2(z)-axis. This is convenient for working on 2D-structures.
As a convenience, the user may also specify a 3x3 rotation matrix, in which case the function rotate(mat) is equivalent to affine(mat).
All rotations are performed around the point [0,0,0], unless a rotation origin is specified in the argument ‘around’.
Return a copy skewed in the direction dir of plane (dir,dir1).
The coordinate dir is replaced with (dir + skew * dir1).
Reflect the coordinates in direction dir against plane at pos.
Default position of the plane is through the origin. Default mirror direction is the z-direction.
Returns a general affine transform of the Coords object.
mat: a 3x3 float matrix
vec: a length 3 list or array of floats
The returned object has coordinates given by self * mat + vec.
Converts from cylindrical to cartesian after scaling.
dir specifies which coordinates are interpreted as resp. distance(r), angle(theta) and height(z). Default order is [r,theta,z]. scale will scale the coordinate values prior to the transformation. (scale is given in order r,theta,z). The resulting angle is interpreted in degrees.
Converts from cartesian to cylindrical coordinates.
dir specifies which coordinates axes are parallel to respectively the cylindrical axes distance(r), angle(theta) and height(z). Default order is [x,y,z]. The angle value is given in degrees.
Converts from spherical to cartesian after scaling.
Angles are interpreted in degrees. Latitude, i.e. the elevation angle, is measured from equator in direction of north pole(90). South pole is -90.
If colat=True, the third coordinate is the colatitude (90-lat) instead.
Performs a superspherical transformation.
superSpherical is much like spherical, but adds some extra parameters to enable the creation of virtually any surface.
Just like with spherical(), the input coordinates are interpreted as the longitude, latitude and distance in a spherical coordinate system.
dir specifies which coordinates are interpreted as resp. longitude(theta), latitude(phi) and distance(r). Angles are then interpreted in degrees. Latitude, i.e. the elevation angle, is measured from equator in direction of north pole(90). South pole is -90. If colat=True, the third coordinate is the colatitude (90-lat) instead.
scale will scale the coordinate values prior to the transformation.
The n and e parameters define exponential transformations of the north_south (latitude), resp. the east_west (longitude) coordinates. Default values of 1 result in a circle.
k adds ‘eggness’ to the shape: a difference between the northern and southern hemisphere. Values > 0 enlarge the southern hemishpere and shrink the northern.
Converts from cartesian to spherical coordinates.
dir specifies which coordinates axes are parallel to respectively the spherical axes distance(r), longitude(theta) and latitude(phi). Latitude is the elevation angle measured from equator in direction of north pole(90). South pole is -90. Default order is [0,1,2], thus the equator plane is the (x,y)-plane.
The returned angle values are given in degrees.
Return a Coords with a bump.
A bump is a modification of a set of coordinates by a non-matching point. It can produce various effects, but one of the most common uses is to force a surface to be indented by some point.
dir specifies the axis of the modified coordinates; a is the point that forces the bumping; func is a function that calculates the bump intensity from distance (!! func(0) should be different from 0) dist is the direction in which the distance is measured : this can be one of the axes, or a list of one or more axes. If only 1 axis is specified, the effect is like function bump1 If 2 axes are specified, the effect is like bump2 This function can take 3 axes however. Default value is the set of 3 axes minus the direction of modification. This function is then equivalent to bump2.
Return a Coords with a one-dimensional bump.
Return a Coords with a two-dimensional bump.
dir specifies the axis of the modified coordinates; a is the point that forces the bumping; func is a function that calculates the bump intensity from distance !! func(0) should be different from 0.
Create a flare at the end of a Coords block.
The flare extends over a distance xf at the start (end=0) or end (end=1) in direction dir[0] of the coords block, and has a maximum amplitude of f in the dir[1] direction.
Return a Coords mapped by a 3-D function.
This is one of the versatile mapping functions. func is a numerical function which takes three arguments and produces a list of three output values. The coordinates [x,y,z] will be replaced by func(x,y,z). The function must be applicable to arrays, so it should only include numerical operations and functions understood by the numpy module. This method is one of several mapping methods. See also map1 and mapd. Example: E.map(lambda x,y,z: [2*x,3*y,4*z]) is equivalent with E.scale([2,3,4])
Return a Coords where coordinate i is mapped by a 1-D function.
func is a numerical function which takes one argument and produces one result. The coordinate dir will be replaced by func(coord[x]). If no x is specified, x is taken equal to dir. The function must be applicable on arrays, so it should only include numerical operations and functions understood by the numpy module. This method is one of several mapping methods. See also map and mapd.
Maps one coordinate by a function of the distance to a point.
func a numerical function which takes one argument and produces one result. The coordinate dir will be replaced by func(d), where d is calculated as the distance to point. The function must be applicable on arrays, so it should only include numerical operations and functions understood by the numpy module. By default, the distance d is calculated in 3-D, but one can specify a limited set of axes to calculate a 2-D or 1-D distance. This method is one of several mapping methods. See also map3() and map1().
Example:
E.mapd(2,lambda d:sqrt(10**2-d**2),f.center(),[0,1])
maps E on a sphere with radius 10.
Return a Coords mapped by a 3-D function.
This is one of the versatile mapping functions. func is a numerical function which takes three arguments and produces a list of three output values. The coordinates [x,y,z] will be replaced by func(x,y,z). The function must be applicable to arrays, so it should only include numerical operations and functions understood by the numpy module. This method is one of several mapping methods. See also map1 and mapd. Example: E.map(lambda x,y,z: [2*x,3*y,4*z]) is equivalent with E.scale([2,3,4])
Replace the coordinates along the axes i by those along j.
i and j are lists of axis numbers or single axis numbers. replace ([0,1,2],[1,2,0]) will roll the axes by 1. replace ([0,1],[1,0]) will swap axes 0 and 1. An optionally third argument may specify another Coords object to take the coordinates from. It should have the same dimensions.
Swap coordinate axes i and j.
Beware! This is different from numpy’s swapaxes() method !
Roll the axes over the given amount.
Default is 1, thus axis 0 becomes the new 1 axis, 1 becomes 2 and 2 becomes 0.
Project Coords on a sphere.
The default sphere is a unit sphere at the origin. The center of the sphere should not be part of the Coords.
Project Coords on a cylinder with axis parallel to a global axis.
The default cylinder has its axis along the x-axis and a unit radius. No points of the Coords should belong to the axis..