s3dlib.surface.Vector3DCollection

Contents

Geometry Properties/Methods

name	Descriptive identifier for the vector geometry.
bounds	Dictionary of vector geometric and value ranges.
vectorlocations	A 3 x N array of vector locations.
vectorcenters	A 3 x N array of vector centers, accounting for visualized scaling.
vectormagnitude	A N array of vector magnitudes.
vectordirection	A 3 x N array of vector directions.
vectordot(direction[, norm])	A N array of vectors dotted with a direction.
alr	Arrow head to length ratio.

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

clip(operation[, locop])	Remove vectors from the vector collection.
clip_plane(dist, **kargs)	Remove vectors from the vector collection based on a clip surface.
clip_from_direction(direction)	Remove vectors from the vector collection based on direction.
clip_from_magnitude([kind, nmag])	Remove vectors from the vector collection based on magnitude.

Color Properties/Methods

cname	Descriptive identifier for values indicated by color.
vectorcolors	A N x 4 array of vector 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 vector color from a function.
map_cmap_from_op(operation[, cmap, cname])	Functional assignment of a vector color from a color map.
map_cmap_from_direction([cmap, direction, cname])	Vector color assignment using vector direction relative to direction argument.
map_cmap_from_magnitude([cmap, cname])	Vector color assignment using vector magnitude.

Matplotlib 3D Visualization Properties/Methods

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

shade([depth, direction, contrast])	Reduce vector HSV color Value based on vector direction.
fade([depth, ax, direction])	Reduce vector opacity based on location relative to the view orientation.

Code Documentation

class s3dlib.surface.Vector3DCollection(location, vect, alr=None, name=None, **kwargs)

Bases: Line3DCollection

Collection of 3D vectors represented as arrows.

Create a collection of 3D vectors.

Parameters:

• location (N x 3 float array) – Cartesian coordinate location (tails) for N number of vectors.

• vect (N x 3 float array) – N number of vectors in Cartesian coordinates.

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

• name (string identifier) –

• **kwargs – All other parameters are passed on to mpl_toolkits.mplot3d.art3d.Line3DCollection. Valid keywords include: colors, linewidths.

property alr

Arrow head to length ratio.

property bounds

Dictionary of vector geometric and value ranges.

Each dictionary value is a 2 float array of minimum and maximum values of the vector location. 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.

‘vertvlim: magnitude

Values are assigned from the geometry and color mapping methods.

clip(operation, locop=True)

Remove vectors from the vector collection. NOTE: all operations are in xyz coordinates.

Parameters:

• operation (function object) – Function that takes one argument, a 3xN Numpy array. The function returns N array of bool { True, False } indicating if the vector is to be retained.

• locop (boolean, default: True) – If True, operation is passed the vector location. If False, operation is passed the vector direction.

Returns:

self (Vector3DCollection object)

clip_from_direction(direction)

Remove vectors from the vector collection based on direction.

Parameters:

direction (arrar of size 3) – A 3D vector in xyz Cartesian coordinates designating a direction vector. Vectors will be retained if the dot product with the direction is positive.

Returns:

self (Vector3DCollection object)

clip_from_magnitude(kind='a', nmag=0.5)

Remove vectors from the vector collection based on magnitude.

Parameters:

• kind (string, default : '+a') –

  Vectors are kept based on the magnitude using the key:

  ’a’ : above average

  ’a-’ : below average

  ’m’ : above the median

  ’m-’ : below the median

  ’v’ : above the normalized magnitude set by nmag argument

  ’v-’ : below the normalized magnitude set by nmag argument

• nmag (float, default: 0.5) – Sets the range of magnitude during clipping.

Returns:

self (Vector3DCollection object)

clip_plane(dist, **kargs)

Remove vectors from the vector collection based on a clip surface.

Parameters:

• dist (number, optional, default : 0.0) – 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 (Vector3DCollection object)

property cname

Descriptive identifier for values indicated by color.

fade(depth=0, ax=None, direction=None)

Reduce vector opacity based on location relative to the view orientation.

Parameters:

• depth (scalar, optional, default: 0) – Minimum opacity to 1 for vector opacity from back to front vector location (tail). Depth value ranges from 0 to 1.

• ax (Matplotlib 3D axes, default: default view direction.) – If not None and direction is None, viewing direction is assigned from the ax.

• direction (array-like, optional, default: (1,0,1)) – A xyz vector pointing to the viewing direction, if ax is not defined.

Returns:

self (Vector3DCollection object)

map_cmap_from_direction(cmap=None, direction=[1, 1, 1], cname=None)

Vector color assignment using vector direction relative to direction argument.

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

Parameters:

• cmap (str or Colormap, optional, default: 'viridis') – 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,1,1]) – A 3D vector in xyz Cartesian coordinates designating the reference direction.

• refCoor (string, optional, default: "XYZ") – Direction coordinate system for the evaluation. (Not implimented)

Returns:

self (Vector3DCollection object)

map_cmap_from_magnitude(cmap=None, cname=None)

Vector color assignment using vector magnitude.

Parameters:

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

Returns:

self (Vector3DCollection object)

map_cmap_from_op(operation, cmap=None, cname=None)

Functional assignment of a vector color from a color map.

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

Parameters:

• operation (function object) – Function that takes two arguments, both a 3xN Numpy array of xyz coordinates. The first and second arguments are the location and direction, respectively. The function returns a Numpy array of scalar values.

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

Returns:

self (Vector3DCollection object)

map_color_from_op(operation, rgb=True, cname=None)

Assignment of vector color from a function.

Vector colors are assigned from a function of direction and location coordinates.

Parameters:

• operation (function object) – Function that takes two arguments, both a 3xN Numpy array of xyz coordinates. The first and second arguments are the location and direction, respectively. 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.

Returns:

self (Vector3DCollection object)

property name

Descriptive identifier for the vector geometry.

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>, colors=<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>, segments=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, sort_zpos=<UNSET>, transform=<UNSET>, url=<UNSET>, urls=<UNSET>, verts=<UNSET>, visible=<UNSET>, zorder=<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 colors colors: color or list of colors edgecolor or ec or edgecolors: color or list of colors or ‘face’ facecolor or facecolors or fc: color or list of colors 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: unknown picker: None or bool or float or callable pickradius: float rasterized: bool segments: unknown sketch_params: (scale: float, length: float, randomness: float) snap: bool or None sort_zpos: unknown transform: .Transform url: str urls: list of str or None verts: unknown visible: bool zorder: float

shade(depth=0, direction=None, contrast=None)

Reduce vector HSV color Value based on vector direction.

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

Parameters:

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

• direction (array-like, optional, default: default view) – A xyz vector pointing to the illumination source, if ax is not defined.

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

Returns:

self (Vector3DCollection object)

property vectorcenters

A 3 x N array of vector centers, accounting for visualized scaling.

property vectorcolors

A N x 4 array of vector colors.

property vectordirection

A 3 x N array of vector directions.

vectordot(direction, norm=True)

A N array of vectors dotted with a direction. Vectors are normalize if norm=True (default)

property vectorlocations

A 3 x N array of vector locations.

property vectormagnitude

A N array of vector magnitudes.

property vlim

Range of values associated with color