s3dlib.surface.Surface3DCollection

Contents

Static Methods

coor_convert(xyz[, tocart])

Coordinate transformation.

chull(points, **kargs)

Surface3DCollection Convex Hull for a set of 3D points.

implsurf(operation[, drez, domain, fval, name])

Surface3DCollection defined by an implicit function f(x,y,z).

implsurfSet(operation[, drez, domain, numb, ...])

Set of surface contours implicit function f(x,y,z) within a domain

cloudsurf(cloud[, domain, fval, name])

Surface3DCollection defined for a constant value in a point cloud.

cloudsurfSet(cloud[, domain, numb, name])

Surface3DCollection defined for a constant value in a point cloud.

Geometry Properties/Methods

name

Descriptive identifier for the surface geometry.

bounds

Dictionary of surface geometric and value ranges.

vertices

A 3 x N array of surface vertices.

vertexnormals(**kargs)

Unit directions or Vector3DCollection of vertex normals at vertices.

facecenters

A 3 x N array of surface face center coordinates.

facenormals(**kargs)

Unit directions or Vector3DCollection of face normals at face centers.

edges

ColorLine3DCollection of the surface edges from facecolors.

initedges

ColorLine3DCollection of the initial surface edges.

area_h2b

A 2 x N array of normalized N face areas and shapes.

svd_dict

A dictionary of results from a Singular Value Decomposition of the data.

get_transformAxis(**kargs)

Line3DCollection of the 'last' transformed surface coordinate axis.

normalize_scale()

Scaling normalization array and reciprocal.

set_vertvals(values)

Assign scalar values to each vertex.

The following methods will return the calling object (self).

domain([xlim, ylim, zlim])

Set the domain of the surface.

triangulate([rez])

PLANAR subdivision of each face into triangular faces.

evert()

Reverse direction of face normals.

transform([rotate, scale, translate])

Linear transformation of the surface object.

clip(operation[, usexyz])

Remove faces from the surface based on position.

clip_alpha(alphaCut[, useval])

Remove faces from the surface based on alpha transparency.

clip_plane(dist, **kargs)

Remove faces from the surface based on a clip surface.

clip_normals([direction])

Remove faces from the surface based on a direction relative to face normals.

map_geom_from_op(operation[, returnxyz, name])

Functional transformation of surface vertex coordinates.

map_geom_from_image(fname[, scale, ...])

Append surface vertices proportional to image color component values.

map_geom_from_datagrid(datagrid[, scale, ...])

Append surface vertices proportional to 2D datagrid surface.

map_geom_from_svd(data[, pc])

Transform surface geometry based on a PCA analysis of a data set.

Color Properties/Methods

cname

Descriptive identifier for values indicated by color.

facecolors

A N x 4 array of surface face colors.

vlim

Range of values associated with color

The following methods will return the calling object (self).

map_color_from_op(operation[, rgb, cname])

Assignment of face color from a function.

map_color_from_image(fname[, viewport])

Assign image color values to surface face colors.

map_cmap_from_op([operation, cmap, cname])

Functional assignment of a color from a color map.

map_cmap_from_datagrid(datagrid[, cmap, ...])

Face color assignment using a 2D datagrid surface.

map_cmap_from_normals([cmap, direction, ...])

Face color assignment using normals relative to a direction.

map_cmap_from_vertvals([cmap, cname])

Face color assignment using face vertex values.

Object Creation Methods

__add__(othr)

Combine two surface objects into a single surface object.

contourLines(*dist, **kargs)

ColorLine3DCollection contour lines on the surface.

contourLineSet([numb])

ColorLine3DCollection of evenly spaced contour lines on the surface.

dispfield_from_op(operation, **kargs)

Vector3DCollection of displacement of vertices to a different position.

vectorfield_from_op(operation, **kargs)

Vector3DCollection of vectors in u,v,w coordinates at surface vertices.

vectorfield_to_surface(surface, **kargs)

Vector3DCollection of vectors from surface to surface vertex coordinates.

Matplotlib 3D Visualization Properties/Methods

The following are used prior to adding the object to the Matplotlib 3D axis.

cBar_ScalarMappable

matplotlib.cm.ScalarMappable object for surface values.

set_surface_alpha(alpha[, constant, adjustlw])

Adjust the face color alpha values and linewidth of the surface.

shade([depth, direction, contrast, isAbs, ...])

Reduce surface HSV color Value based on face normals.

hilite([height, direction, focus, ax, ...])

Increase surface HSV color Value and reduce Saturation, based on face normals.

fade([depth, elev, azim, ax])

Reduce surface face opacity based on face position relative to the view orientation.

Code Documentation

class s3dlib.surface.Surface3DCollection(vertexCoor, faceIndices, name=None, vcolor=None, **kwargs)[source]

Bases: Poly3DCollection

Base class for 3D surfaces.

3D surface of connected F faces, each face with N number of vertices. The surface has V number of vertices and E number of edges.

Parameters:

  • vertexCoor (V x 3, or V X 4, float array-like) – An array of V number of xyz vertex coordinates. If V X 4, scaler values are assigned to each vertex.

  • faceIndices (F x N int list or array) – A list or array of F number of faces with N vertex indices. For lists, N may be different for each face.

  • name (string, optional, default: None.) – Descriptive identifier for the geometry.

  • vcolor (V x 3 float array-like, default: None.) – An array of V number of vertex colors. (not implemented, reserved for future development)

  • **kwargs – All other arguments are passed on to mpl_toolkits.mplot3d.art3d.Poly3DCollection. Valid argument names include: color, edgecolors, facecolors, linewidths, cmap.

__add__(othr)[source]

Combine two surface objects into a single surface object.

Parameters:

othr (Surface3DCollection object) –

Returns:

Surface3DCollection object

property area_h2b

A 2 x N array of normalized N face areas and shapes.

property bounds

Dictionary of surface geometric and value ranges.

Each dictionary value is a 2 float array of minimum and maximum values of the surface. Keys are:

‘xlim’ : x-coordinate

‘ylim’ : y-coordinate

‘zlim’ : z-coordinate

‘r_xy’ : radial distance from the z axis

‘rorg’ : radial distance from the origin

‘vlim’ : value functional assignments.

Values are assigned from the geometry and color mapping methods, including clipping.

property cBar_ScalarMappable

matplotlib.cm.ScalarMappable object for surface values.

static chull(points, **kargs)[source]

Surface3DCollection Convex Hull for a set of 3D points.

Parameters:

points (N x 3 float array-like) –

Returns:

Surface3DCollection object

clip(operation, usexyz=False)[source]

Remove faces from the surface based on position.

Parameters:

  • operation (function object) – Function that takes one argument, a 3xN Numpy array of coordinates. The function returns a bool { True, False } indicating if the face, at the face centered coordinate, is to be retained (True), otherwise, the face is removed from the surface (False).

  • usexyz (bool { True, False }, default: False) – If True, face centers are passed to the operation function in xyz coordinates. If False, face centers are passed in native coordinates.

Returns:

self (surface object)

clip_alpha(alphaCut, useval=False)[source]

Remove faces from the surface based on alpha transparency.

Parameters:

  • alphaCut (scalar) – If the face color alpha is greater than alphaCut, the face is retained, otherwise, the face is removed from the surface.

  • useval (bool { True, False }, default: False) – If True, clipping based on color HSV value. Otherwise, clipping is based on the color alpha value.

Returns:

self (surface object)

clip_normals(direction=None)[source]

Remove faces from the surface based on a direction relative to face normals.

Parameters:

direction (array-like or 3Daxis, optional, default: (30,-60)) – The vector direction for viewing (elev,azim) or 3Daxis.

Returns:

self (surface object)

clip_plane(dist, **kargs)[source]

Remove faces from the surface based on a clip surface.

Parameters:

  • dist (float) – Distance from the origin to the clip surface, along the direction vector.

  • direction (array-like, optional, default: [0,0,1]) – A xyz vector normal to the intersection plane for a planar clip surface or axial direction of a cylinder for a cylindrical clip surface.

  • coor (integer or string indicating the type of clip surface:) – 0, p, P, xyz,planar - planar (default) 1, c, C, cylinder,pplar,cylindrical - cylinder 2, s, S, sphere,spherical - sphere 3, x, X - y-z plane 4, y, Y - x-z plane 5, z, Z - x-y plane

Returns:

self (surface object)

static cloudsurf(cloud, domain=1, fval=0.0, name=None, **kwargs)[source]

Surface3DCollection defined for a constant value in a point cloud.

Parameters:

  • cloud (a (M,N,P) shaped array of point cloud values.) –

  • domain (a number, list or array, default: 1) – The domain of the function evaluation. For a number, n, the x,y,z axes domains will be [-n,n]. For a 1-dimensional 2-element list, [a,b] will be assigned the domain for all 3 axes. Using a list of list (array), as [ [a,b],[c,d],[e,f] ], the domain is assigned individually for each of the three coordinate axes.

  • fval (a number, default: 0.0) – Scalar value of surface contour within the cloude.

  • name (string, optional, default: None.) – Descriptive identifier for the geometry.

Returns:

Surface3DCollection object

static cloudsurfSet(cloud, domain=1, numb=2, name=None, **kwargs)[source]

Surface3DCollection defined for a constant value in a point cloud.

Parameters:

  • cloud (a (M,N,P) shaped array of point cloud values.) –

  • domain (a number, list or array, default: 1) – The domain of the function evaluation. For a number, n, the x,y,z axes domains will be [-n,n]. For a 1-dimensional 2-element list, [a,b] will be assigned the domain for all 3 axes. Using a list of list (array), as [ [a,b],[c,d],[e,f] ], the domain is assigned individually for each of the three coordinate axes.

  • numb (an integer, default: 2) – Number of surface contours within the domain.

  • name (string, optional, default: None.) – Descriptive identifier for the geometry.

Returns:

Surface3DCollection object

property cname

Descriptive identifier for values indicated by color.

contourLineSet(numb=2, **kargs)[source]

ColorLine3DCollection of evenly spaced contour lines on the surface.

Parameters:

  • numb (integer) – Number of contour lines intersecting a surface. Numb value must be getter than zero.

  • direction (array-like, optional, default: [0,0,1]) – A xyz vector normal to the intersection planes for planar contours or axial direction of cylinders for cylindrical contours.

  • name (string identifier (default None)) –

  • color (color (default is the surface colors)) –

  • coor (integer or string indicating the type of contour surface:) – 0, p, P, xyz,planar - planar (default, planar & polar) 1, c, C, cylinder,pplar,cylindrical - cylinder (default, cylindrical) 2, s, S, sphere,spherical - sphere (default, spherical) 3, x, X - y-z plane 4, y, Y - x-z plane 5, z, Z - x-y plane

Returns:

self (line object)

contourLines(*dist, **kargs)[source]

ColorLine3DCollection contour lines on the surface.

Parameters:

  • dist (floats) – Distances from the origin to the surface of intersection, along the direction vector.

  • direction (array-like, optional, default: [0,0,1]) – A xyz vector normal to the intersection planes for planar contours or axial direction of cylinders for cylindrical contours.

  • name (string identifier (default None)) –

  • color (color (default is the surface colors)) –

  • coor (integer or string indicating the type of contour surface:) – 0, p, P, xyz,planar - planar (default, planar & polar) 1, c, C, cylinder,pplar,cylindrical - cylinder (default, cylindrical) 2, s, S, sphere,spherical - sphere (default, spherical) 3, x, X - y-z plane 4, y, Y - x-z plane 5, z, Z - x-y plane

Returns:

self (line object)

static coor_convert(xyz, tocart=False)[source]

Coordinate transformation.

To be overriddden by any subclass not in Cartesian coordinates.

dispfield_from_op(operation, **kargs)[source]

Vector3DCollection of displacement of vertices to a different position.

Parameters:

  • operation (function object) – Function that takes one coordinate argument, a 3xN Numpy array. The function returns a 3xN array of vectors.

  • returnxyz (bool { True, False }, optional, default: False) – By default, native coordinates are returned by the operation function. If set True, the operation returns xyz Cartesian coordinates.

  • useBase (bool { True, False }, optional, default: False) – When set False, vertices of the surface, prior to any geometric mapping or transforms, are passed to the operation function. Otherwise, when True, the current surface vertices are passed.

  • scale (number, optional, default: 1.) –

  • color (str or float list of length 3 or 4.) – RGB or RGBA color, either a Matplotlib format string or a list of color values in range [0,1].

  • width (number, optional, default: 1) – Line width of the vector.

  • alr (scalar, optional, default: 0.25) – Axis length ratio, head size to vector magnitude.

Returns:

Vector3DCollection object

domain(xlim=None, ylim=None, zlim=None)[source]

Set the domain of the surface.

Used for setting the domain of the base.

Parameters:

  • xlim (2d arrays) – Minimum and maximum values of the arrays are used to scale and translate the surface from an intial domains of [ -1, 1 ] If set to None, the domains are unchanged.

  • ylim (2d arrays) – Minimum and maximum values of the arrays are used to scale and translate the surface from an intial domains of [ -1, 1 ] If set to None, the domains are unchanged.

  • zlim (2d arrays) – Minimum and maximum values of the arrays are used to scale and translate the surface from an intial domains of [ -1, 1 ] If set to None, the domains are unchanged.

Returns:

self (surface object)

property edges

ColorLine3DCollection of the surface edges from facecolors.

evert()[source]

Reverse direction of face normals.

property facecenters

A 3 x N array of surface face center coordinates.

property facecolors

A N x 4 array of surface face colors.

facenormals(**kargs)[source]

Unit directions or Vector3DCollection of face normals at face centers.

Parameters:

  • scale (number, optional) – If not spectified, scaled proportional to the mean edge length of surface base faces.

  • v3d (boolean, optional, default: True) – If True, Vector3DCollection is returned, else a N x 3 array of unit vector face normals is returned if False.

  • color (str or float list of length 3 or 4.) – RGB or RGBA color, either a Matplotlib format string or a list of color values in range [0,1].

  • width (number, optional, default: 1) – Line width of the vector.

  • alr (scalar, optional, default: 0.25) – Axis length ratio, head size to vector magnitude.

Returns:

Vector3DCollection object or array of unit direction vectors

fade(depth=0, elev=None, azim=None, ax=None)[source]

Reduce surface face opacity based on face position relative to the view orientation.

Parameters:

  • depth (scalar, optional, default: 0) – Minimum opacity to 1 for face opacity from back to front face center position. Depth value ranges from 0 to 1.

  • elev (scalar, optional, default: 30) – Elevation of the axes view.

  • azim (scalar, optional, default: -60) – Azimuth of the axes view.

  • ax (Matplotlib 3D axes.) – If not None, elev and azim are taken from the ax.

Returns:

self (surface object)

get_transformAxis(**kargs)[source]

Line3DCollection of the ‘last’ transformed surface coordinate axis.

Parameters:

  • lenmult (scalar or 3D array, optional, default: 1) – Scalar multiplier of the three coordinate axis.

  • width (scalar, optional, default: 1.5) – Line width of the coordinate axis.

  • color (a Color or 3D array of Colors, optional, default: ['r','g','b']) –

  • negaxis (boolean, optional, default: False) – If True, include the negative axis, otherwise axis start at origin.

Returns:

Line3DCollection object

hilite(height=1, direction=None, focus=None, ax=None, rview=False, flat=True)[source]

Increase surface HSV color Value and reduce Saturation, based on face normals.

The dot product of face normals with the illumination direction is used to adjust face HSV color value and saturation. Faces having normals with a negative component in the direction of illumination are not affected. The reduction of color saturation is proportional to the increase in color value.

Parameters:

  • height (scalar, optional, default: 1) – Maximum color value of highlighted surface faces. Height value ranges from 0 to 1.

  • direction (array-like, optional, default: (1,0,1)) – A xyz vector pointing to the illumination source.

  • focus (scalar, optional, default: 1) – Highlighting focus adjustment from low to high with a value of 1 for quadratic variations with the normal direction. Focus value ranges from 0.1 to 3.

  • ax (Matplotlib 3D axes.) –

  • rview (boolean, default: False) –

    If True, direction is relative to the view,

    otherwise, relative to the axes.

  • flat (boolean, default: True) – If False, smooth flat triangulated faces.

Returns:

self (surface object)

static implsurf(operation, drez=2.0, domain=1, fval=0.0, name=None, **kwargs)[source]

Surface3DCollection defined by an implicit function f(x,y,z).

Parameters:

  • operation (function object) – Implicit function that takes one argument, a 3xN Numpy array of x,y,z coordinates. The function returns a single scalar value. The value of zero defines the implicit surface.

  • drez (Float, optional, default: 2.0) – Multiplier for the number of subdivisions within the domain. Frez values range from 1 to 10. Function evaluation will be the order of frez cubed.

  • domain (a number, list or array, default: 1) – The domain of the function evaluation. For a number, n, the x,y,z axes domains will be [-n,n]. For a 1-dimensional 2-element list, [a,b] will be assigned the domain for all 3 axes. Using a list of list (array), as [ [a,b],[c,d],[e,f] ], the domain is assigned individually for each of the three coordinate axes.

  • fval (a number, default: 0.0) – Scalar value of the function at the surface.

  • name (string, optional, default: None.) – Descriptive identifier for the geometry.

Returns:

Surface3DCollection object

static implsurfSet(operation, drez=2.0, domain=1, numb=2, name=None, **kwargs)[source]

Set of surface contours implicit function f(x,y,z) within a domain

Parameters:

  • operation (function object) – Implicit function that takes one argument, a 3xN Numpy array of x,y,z coordinates. The function returns a single scalar value. The value of zero defines the implicit surface.

  • drez (Float, optional, default: 2.0) – Multiplier for the number of subdivisions within the domain. Frez values range from 1 to 10. Function evaluation will be the order of frez cubed.

  • domain (a number, list or array, default: 1) – The domain of the function evaluation. For a number, n, the x,y,z axes domains will be [-n,n]. For a 1-dimensional 2-element list, [a,b] will be assigned the domain for all 3 axes. Using a list of list (array), as [ [a,b],[c,d],[e,f] ], the domain is assigned individually for each of the three coordinate axes.

  • numb (an integer, default: 2) – Number of surface contours within the domain.

  • name (string, optional, default: None.) – Descriptive identifier for the geometry.

Returns:

Surface3DCollection object

property initedges

ColorLine3DCollection of the initial surface edges. ONLY available for surfaces where the number of face edges differ among faces and the number of faces is less than 250.

map_cmap_from_datagrid(datagrid, cmap=None, viewport=None, cname=None)[source]

Face color assignment using a 2D datagrid surface.

Datagrid values are normalized in the range 0 to 1.

This method is not available for composite surfaces. The entire datagrid domain is applied to the geometric operation.

Parameters:

  • datagrid (2D float array) –

  • cmap (str or Colormap, optional) – A Colormap instance or registered colormap name. If not assigned, the surface Colormap is used. The colormap maps the datagrid values to colors.

  • viewport (4D array-like, optional, default: None) – Viewport defines the subdomain of the surface onto which the datagrid is mapped. The subdomain is set by normalized native surface coordinates in a 4D array. The entire surface is colored for the default of None.

  • cname (string, optional, default: None.) – Descriptive identifier for values indicated by color.

Returns:

self (surface object)

map_cmap_from_normals(cmap=None, direction=None, cname=None, isAbs=False)[source]

Face color assignment using normals relative to a direction.

The dot product of face normals with the direction is used to assign face colors from a colormap.

Parameters:

  • cmap (str or Colormap, optional) – A Colormap instance or registered colormap name. If not assigned, the surface Colormap is used. The colormap maps the dot product values to colors.

  • direction (list of size 3, optional, default: [1,0,1]) – A 3D vector in xyz Cartesian coordinates designating the direction of the illumination source. If assigned the Axes3D, will use the view direction.

  • cname (string, optional, default: None.) – Descriptive identifier for values indicated by color.

  • isAbs (boolean, optional, default: False) – If set True, the absolute value of the dot product between face normals and illumination direction is used.

Returns:

self (surface object)

map_cmap_from_op(operation=None, cmap=None, cname=None)[source]

Functional assignment of a color from a color map.

Face coordinates are used to calculate a scalar which is then used to assign face colors from a colormap.

Parameters:

  • operation (function object, default : None) – Function that takes one argument, a 3xN Numpy array of native coordinates. The function returns a Numpy array of scalar values. If function is None, function will map in the z-direction or r-direction, dependent on the native coordinates.

  • cmap (str or Colormap, optional) – A Colormap instance or registered colormap name. If not assigned, the surface Colormap is used. The colormap maps the function return values to colors.

  • cname (string, optional, default: None or op function name.) – Descriptive identifier for values indicated by color.

Returns:

self (surface object)

map_cmap_from_vertvals(cmap=None, cname=None)[source]

Face color assignment using face vertex values.

Parameters:

  • cmap (str or Colormap, optional) – A Colormap instance or registered colormap name. If not assigned, the surface Colormap is used. The colormap maps the datagrid values to colors.

  • cname (string, optional, default: None.) – Descriptive identifier for values indicated by color.

Returns:

self (surface object)

map_color_from_image(fname, viewport=None)[source]

Assign image color values to surface face colors.

This method is not available for composite surfaces. The entire image domain is applied to the coloring operation.

Parameters:

  • fname (str or file-like) – The image file to read: a filename, a URL or a file-like object opened in read-binary mode. Currently restricted to PNG format.

  • viewport (4D array-like, optional, default: None) – Viewport defines the subdomain of the surface onto which the image is mapped. The subdomain is set by normalized native surface coordinates in a 4D array. The entire surface is colored for the default of None.

Returns:

self (surface object)

map_color_from_op(operation, rgb=True, cname=None)[source]

Assignment of face color from a function.

Face colors are assigned from a function of face coordinates.

Parameters:

  • operation (function object) – Function that takes one argument, a 3xN Numpy array of native coordinates. The function returns a 3xN color value.

  • rgb (bool {True, False}, optional, default: True) – By default, RGB color values are returned by the operation function. If set False, the operation returns HSV color values.

  • cname (string, optional, default: None or op function name.) – Descriptive identifier for values indicated by color.

Returns:

self (surface object)

map_geom_from_datagrid(datagrid, scale=1.0, viewport=None, name=None)[source]

Append surface vertices proportional to 2D datagrid surface.

Datagrid values are normalized in the range 0 to 1.

This method is not available for composite surfaces. The entire datagrid domain is applied to the geometric operation.

Parameters:

  • datagrid (2D array) –

  • scale (number, optional, default: 1) –

  • viewport (4D array-like, optional, default: None) – Viewport defines the subdomain of the surface onto which the datagrid is mapped. The subdomain is set by normalized native surface coordinates in a 4D array. The entire surface is geometrically mapped for the default of None.

  • name (string, optional, default: None) – Descriptive identifier for the geometry.

Returns:

self (surface object)

map_geom_from_image(fname, scale=1.0, viewport=None, cref='v', hzero=0, name=None)[source]

Append surface vertices proportional to image color component values.

For planar and polar coordinates, the z-coordinate is appended. For cylindrical and spherical coordinates, the r-coordinate is appended.

This method is not available for composite surfaces. The entire image domain is applied to the geometric operation.

Parameters:

  • fname (str or file-like) – The image file to read: a filename, a URL or a file-like object opened in read-binary mode. Currently restricted to PNG format.

  • scale (number) –

  • cref ({'r','g','b','h','s','v'}, optional, default: 'v') – Sets which color tuple value to use for geometry mapping. Note: only the first character of the string is evaluated.

  • hzero (number or None, optional, default: 0) – Argument is used if cref is set to ‘h’. The hzero magnitude indicates the Hue value for a zero coordinate diplacement. The hzero sign (positive or negative), indicates the direction of increasing value in the appended coordinate with hue value. Range of hzero is [-1,1].

  • viewport (4D array-like, optional, default: None) – Viewport defines the subdomain of the surface onto which the image is mapped. The subdomain is set by normalized native surface coordinates in a 4D array. The entire surface is geometrically mapped for the default of None.

  • name (string, optional, default: None) – Descriptive identifier for the geometry.

Returns:

self (surface object)

map_geom_from_op(operation, returnxyz=False, name=None)[source]

Functional transformation of surface vertex coordinates.

This method is not available for composite surfaces.

Parameters:

  • operation (function object) – Coordinate mapping function that takes one argument, a 3xN Numpy array of native coordinates. The function returns a 3xN array of coordinates.

  • returnxyz (bool { True, False }, optional, default: False) – By default, native coordinates are returned by the operation function. If set True, the operation returns xyz Cartesian coordinates.

  • name (string, optional, default: None or op function name.) – Descriptive identifier for the geometry.

Returns:

self (surface object)

map_geom_from_svd(data, pc=None)[source]

Transform surface geometry based on a PCA analysis of a data set. Result values contained in the surface property svd_dict.

Parameters:

  • data (N x 3 array of x,y,z data coordinates.) –

  • pc (scalar, optional, default: None) – Sets the minimum size of the surface based on the relative number of data. Value range from 0 to 1, with 1 for 100%. If None, one standard deviation of the data sets the surface size.

Returns:

self (surface object)

property name

Descriptive identifier for the surface geometry.

normalize_scale()[source]

Scaling normalization array and reciprocal.

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, antialiased=<UNSET>, array=<UNSET>, capstyle=<UNSET>, clim=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, cmap=<UNSET>, color=<UNSET>, edgecolor=<UNSET>, facecolor=<UNSET>, gid=<UNSET>, hatch=<UNSET>, in_layout=<UNSET>, joinstyle=<UNSET>, label=<UNSET>, linestyle=<UNSET>, linewidth=<UNSET>, norm=<UNSET>, offset_transform=<UNSET>, offsets=<UNSET>, path_effects=<UNSET>, paths=<UNSET>, picker=<UNSET>, pickradius=<UNSET>, rasterized=<UNSET>, sizes=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, sort_zpos=<UNSET>, surface_alpha=<UNSET>, transform=<UNSET>, url=<UNSET>, urls=<UNSET>, verts=<UNSET>, verts_and_codes=<UNSET>, vertvals=<UNSET>, visible=<UNSET>, zorder=<UNSET>, zsort=<UNSET>)

Set multiple properties at once.

Supported properties are

Properties:

agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array alpha: array-like or scalar or None animated: bool antialiased or aa or antialiaseds: bool or list of bools array: array-like or None capstyle: .CapStyle or {‘butt’, ‘projecting’, ‘round’} clim: (vmin: float, vmax: float) clip_box: .Bbox clip_on: bool clip_path: Patch or (Path, Transform) or None cmap: .Colormap or str or None color: color or list of rgba tuples edgecolor or ec or edgecolors: unknown facecolor or facecolors or fc: unknown figure: .Figure gid: str hatch: {‘/’, ‘\’, ‘|’, ‘-’, ‘+’, ‘x’, ‘o’, ‘O’, ‘.’, ‘*’} in_layout: bool joinstyle: .JoinStyle or {‘miter’, ‘round’, ‘bevel’} label: object linestyle or dashes or linestyles or ls: str or tuple or list thereof linewidth or linewidths or lw: float or list of floats norm: .Normalize or None offset_transform: .Transform offsets: (N, 2) or (2,) array-like path_effects: .AbstractPathEffect paths: list of array-like picker: None or bool or float or callable pickradius: float rasterized: bool sizes: ndarray or None sketch_params: (scale: float, length: float, randomness: float) snap: bool or None sort_zpos: unknown surface_alpha: scalar transform: .Transform url: str urls: list of str or None verts: unknown verts_and_codes: unknown vertvals: list or array of length N, where N is the visible: bool zorder: float zsort: {‘average’, ‘min’, ‘max’}

set_surface_alpha(alpha, constant=False, adjustlw=True)[source]

Adjust the face color alpha values and linewidth of the surface.

Parameters:

  • alpha (scalar) – Alpha is in the range 0 to 1.

  • constant (bool { True, False }, optional, False) – If False, face color values are multiplied by alpha. If True, all face colors alpha channels are assigned to alpha.

  • adjustlw (bool { True, False }, optional, True) – If True, the surface linewidth will be set to make the edges visually transparent with the faces for Matplotlib rendering.

Returns:

self (surface object)

set_vertvals(values)[source]

Assign scalar values to each vertex.

Parameters:

values (list or array of length N, where N is the) – number of vertices.

Returns:

self (surface object)

shade(depth=0, direction=None, contrast=None, isAbs=False, ax=None, rview=False, flat=True)[source]

Reduce surface HSV color Value based on face normals.

The dot product of face normals with the illumination direction is used to adjust face HSV color value.

Parameters:

  • depth (scalar, optional, default: 0) – Minimum color value of shaded surface faces. Depth value ranges from 0 to 1.

  • direction (array-like, optional, default: (1,0,1)) – A xyz vector pointing to the illumination source.

  • contrast (scalar, optional, default: 1) – Shading contrast adjustment from low to high with a value of 1 for linear variations with the normal direction. Contrast value ranges from 0.1 to 3.

  • isAbs (bool, optional, default: False) – If True, the absolute value of the dot product is is used to determine color value.

  • ax (Matplotlib 3D axes.) –

  • rview (boolean, default: False) – If True, direction is relative to the view, otherwise, relative to the axes.

  • flat (boolean, default: True) – If False, smooth flat triangulated faces.

Returns:

self (surface object)

property svd_dict

A dictionary of results from a Singular Value Decomposition of the data.

Keys are:

‘disarr’ : array of N floats, normalized to the surface size.

‘sigma’ : standard deviation

‘trans’ : [rotation matrix, scaling, translation]

Values are assigned using the map_geom_from_svd method. The dictionary is None if the method has not been called by the surface object.

transform(rotate=None, scale=1.0, translate=[0, 0, 0])[source]

Linear transformation of the surface object.

Parameters:

  • rotate (array-like, optional, default: None) – A 3 by 3 rotation matrix.

  • scale (3D array or scalar, optional, default: 1.0) – Multipliers of the object coordinates, in xyz coordinates. If a single scalar, three multipliers are the same value.

  • translate (array-like, optional, default: [0,0,0]) – A xyz translation vector of object origin.

Returns:

self (surface object)

triangulate(rez=0)[source]

PLANAR subdivision of each face into triangular faces.

Parameters:

rez (integer, optional, default: 0) – Number of recursive subdivisions of the base faces into triangular faces, four faces per rez. Rez values range from 0 to 7. For surfaces with 4 vertices per face, each face is first subdivided into two faces, then recursion proceeds. For surfaces with 5 vertices per face, each face is first subdivided into three faces, then recursion proceeds.

Returns:

self (surface object)

vectorfield_from_op(operation, **kargs)[source]

Vector3DCollection of vectors in u,v,w coordinates at surface vertices.

Parameters:

  • operation (function object) – Function that takes one coordinate argument, a 3xN Numpy array of native coordinates. The function returns a 3xN array of vectors.

  • scale (number, optional, default: 1.) –

  • color (str or float list of length 3 or 4.) – RGB or RGBA color, either a Matplotlib format string or a list of color values in range [0,1].

  • width (number, optional, default: 1) – Line width of the vector.

  • alr (scalar, optional, default: 0.25) – Axis length ratio, head size to vector magnitude.

Returns:

Vector3DCollection object

vectorfield_to_surface(surface, **kargs)[source]

Vector3DCollection of vectors from surface to surface vertex coordinates.

Parameters:

  • surface (surface object) – Surface that matches the calling surface vectors. Should be the same basetype and rez for surface subclasses.

  • scale (number, optional, default: 1.) –

  • color (str or float list of length 3 or 4.) – RGB or RGBA color, either a Matplotlib format string or a list of color values in range [0,1].

  • width (number, optional, default: 1) – Line width of the vector.

  • alr (scalar, optional, default: 0.25) – Axis length ratio, head size to vector magnitude.

Raises:

ValueError – Mismatched surfaces based on the number of vertices.

Returns:

Vector3DCollection object

vertexnormals(**kargs)[source]

Unit directions or Vector3DCollection of vertex normals at vertices.

Parameters:

  • scale (number, optional) – If not spectified, scaled proportional to the mean edge length of surface base faces.

  • v3d (boolean, optional, default: True) – If True, Vector3DCollection is returned, else a N x 3 array of unit vector vertex normals is returned if False.

  • color (str or float list of length 3 or 4.) – RGB or RGBA color, either a Matplotlib format string or a list of color values in range [0,1].

  • width (number, optional, default: 1) – Line width of the vector.

  • alr (scalar, optional, default: 0.25) – Axis length ratio, head size to vector magnitude.

Returns:

Vector3DCollection object or array of unit direction vectors

property vertices

A 3 x N array of surface vertices.

property vlim

Range of values associated with color