s3dlib.surface.ColorLine3DCollection

Contents

Static Methods

meshgrid(X, Y, Z[, name]) ColorLine3DCollection, a set of xy slice lines based on a meshgrid.

Geometry Properties/Methods

name Descriptive identifier for the line geometry.
bounds Dictionary of line geometric and value ranges.
vertices A 3 x N array of line vertices.
segmentcenters A 3 x N array of line segment centers.
segmentdirections A N x 3 array of line segment direction vectors.
get_transformAxis(**kargs) Line3DCollection of the ‘last’ transformed line coordinate axis.

The following methods will return the calling object (self).
shred([rez]) Recursively halve each line segment into separate lines.
transform([rotate, scale, translate]) Linear transformation of the line object.
clip(operation) Remove segments from the line.
clip_plane(dist, **kargs) Remove segments from the line based on a clip surface.
map_geom_from_op(operation[, name]) Functional transformation of line vertex coordinates.
map_to_plane(dist, **kargs) Project line onto a mapping surface.

Color Properties/Methods

cname Descriptive identifier for values indicated by color.
segmentcolors A N x 4 array of segment colors.
vlim Range of scalar values which may be associated with color

The following methods will return the calling object (self).
map_color_from_op(operation[, rgb, cname]) Assignment of line color from a function.
map_cmap_from_op(operation[, cmap, cname]) Functional assignment of a color from a color map.
map_cmap_from_sequence([cmap, sop, cname]) Sequential color assignment of each line segment.
map_cmap_from_direction([direction, cmap, …]) Assignment of line color based on line segment direction.
map_cmap_from_datagrid(datagrid[, cmap, cname]) Line color assignment using a 2D datagrid.
set_line_alpha(alpha[, constant]) Adjust the alpha value of the line segment colors.

Object Creation Methods

__add__(othr) ColorLine3DCollection object from vertices, segments and colors of two line objects.
get_filled_surface(**kargs) Surface3DCollection from a line projected to a surface.
get_surface_to_line(line, **kargs) Surface3DCollection from a line projected to another line.

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 line values.
stcBar_ScalarMappable([stripe, bgcolor]) ScalarMappable object with striped color values.
shade([depth, direction, contrast]) Reduce line HSV color Value based on line segment direction.
fade([depth, elev, azim, ax]) Reduce line opacity based on line segment position relative to the view orientation.

Code Documentation

class s3dlib.surface.ColorLine3DCollection(vertexCoor, segmIndices, name=None, **kwargs)[source]

Bases: mpl_toolkits.mplot3d.art3d.Line3DCollection

Base class for non-uniformly colored 3D lines.

A set 3D lines, each line with a varying number of sequential vertices.

Parameters:
  • vertexCoor (V x 3 float array-like) – An array of V number of xyz vertex coordinates.
  • segmIndices (L x Nl int list) – An list of L number of Nl line vertex indices, where Nl is the number of vertices for the Lth line.
  • name (string, optional, default: None.) – Descriptive identifier.
Other Parameters:
 

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

__add__(othr)[source]

ColorLine3DCollection object from vertices, segments and colors of two line objects.

bounds

Dictionary of line geometric and value ranges.

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

cBar_ScalarMappable

matplotlib.cm.ScalarMappable object for line values.

clip(operation)[source]

Remove segments from the line. NOTE: all operations are in xyz coordinates.

Parameters:operation (function object) – Function that takes one argument, a 3xN Numpy array of coordinates. The function returns N array of bool { True, False } indicating if the segment, at the segment center coordinate, is to be retained (True). Otherwise, the segment is removed from the line (False).
Returns:self (line object)
clip_plane(dist, **kargs)[source]

Remove segments from the line 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 (line object)

cname

Descriptive identifier for values indicated by color.

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

Reduce line opacity based on line segment position relative to the view orientation.

Parameters:
  • depth (scalar, optional, default: 0) – Minimum opacity to 1 for linear line opacity from back to front line segment 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 (line object)

get_filled_surface(**kargs)[source]

Surface3DCollection from a line projected to a surface.

Parameters:
  • dist (number, optional, default : 0.0) – distance from the origin to the projected surface, along the direction vector.
  • direction (array-like, optional, default: [0,0,1]) – A xyz vector normal to the intersection plane for planar projections or axial direction of a cylinder for cylindrical projections.
  • coor (integer or string indicating the type of projection 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
  • lrez (positive integer, optional, default : 0) – projection recursive subdivisions.
  • color (Color, optional, default : line color) –
  • alpha (scalar, optional, default : 1) – Face color alpha value, in the range 0 to 1.
  • name (string, optional, default: None.) – Descriptive identifier for the geometry.
Returns:

Surface3DCollection object

get_surface_to_line(line, **kargs)[source]

Surface3DCollection from a line projected to another line.

Parameters:
  • line (line object with the same number of vertices) – as the calling object.
  • lrez (positive integer, optional, default : 0) – projection recursive subdivisions.
  • color (Color, optional, optional, default : line color) –
  • alpha (scalar, optional, default : None (1)) – Face color alpha value, in the range 0 to 1.
  • name (string, optional, default: None.) – Descriptive identifier for the geometry.
Returns:

Surface3DCollection object

get_transformAxis(**kargs)[source]

Line3DCollection of the ‘last’ transformed line 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 axes start at origin.
Returns:

Line3DCollection object

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

Line color assignment using a 2D datagrid.

Datagrid values are normalized in the range 0 to 1.

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

Assignment of line color based on line segment direction.

The dot product of line segment directions with the direction paramenter is used to assign line segment colors from a colormap.

Parameters:
  • direction (array-like, optional, default: (1,0,1)) – A xyz vector.
  • cmap (str or Colormap, optional, default: 'viridis') – A Colormap instance or registered colormap name.
  • isAbs (boolean, optional, default: False) – If True, the absolute value of the dot product will control the color.
  • cname (str, optional, default is None) – Identifier for the color values.
Returns:

self (line object)

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

Functional assignment of a color from a color map.

Line segment center coordinates are used to calculate a scalar which is then used to assign segment colors from a colormap.

Parameters:
  • operation (function object) – Function that takes one argument, a 3xN Numpy array of native coordinates. The function returns a Numpy array of scalar values.
  • cmap (str or Colormap, optional, default: 'viridis') – A Colormap instance or registered colormap name.
  • cname (str, optional, default: function object name) – if not a lambda function, otherwise ‘’. Identifier for the color values.
Returns:

self (line object)

map_cmap_from_sequence(cmap=None, sop=None, cname=None)[source]

Sequential color assignment of each line segment.

Parameters:
  • cmap (str or Colormap, optional, default: 'viridis') – A Colormap instance or registered colormap name.
  • sop (function object, optional, default: None) – Function that takes one argument, a N Numpy array of scalar values ranging 0 to 1. The function returns a Numpy array of scalar values.
  • cname (str, optional, default: function object name) – if not a lambda function, otherwise ‘’. Identifier for the color values.
Returns:

self (line object)

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

Assignment of line color from a function.

Line segment colors are assigned from a function of line segment center 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 (str, optional, default: function object name) – if not a lambda function, otherwise ‘’. Identifier for the color values.
Returns:

self (line object)

map_geom_from_op(operation, name=None)[source]

Functional transformation of line vertex coordinates.

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.
  • name (string, optional, default: None or op function name.) – Descriptive identifier for the geometry.
Returns:

self (line object)

map_to_plane(dist, **kargs)[source]

Project line onto a mapping surface.

Parameters:
  • dist (number, optional, default : 0.0) – distance from the origin to the surface, along the direction vector.
  • direction (array-like, optional, default: [0,0,1]) – A xyz vector normal to the intersection planes for planar mapping or axial direction of a cylinder for cylindrical mapping.
  • coor (integer or string indicating the type of mapping 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 (line object)

static meshgrid(X, Y, Z, name=None)[source]

ColorLine3DCollection, a set of xy slice lines based on a meshgrid.

name

Descriptive identifier for the line geometry.

segmentcenters

A 3 x N array of line segment centers.

segmentcolors

A N x 4 array of segment colors.

segmentdirections

A N x 3 array of line segment direction vectors.

set_line_alpha(alpha, constant=False)[source]

Adjust the alpha value of the line segment colors.

Parameters:
  • alpha (scalar) – Alpha is in the domain 0 to 1.
  • constant (bool { True, False }, optional, False) – If False, segment color values are multiplied by alpha. If True, all segment colors alpha channels are assigned to alpha.
Returns:

self (line object)

shade(depth=0, direction=None, contrast=None)[source]

Reduce line HSV color Value based on line segment direction.

The dot product of line segment with the illumination direction is used to adjust face 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: (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 line segment direction. Contrast value ranges from 0.1 to 3.
Returns:

self (line object)

shred(rez=0)[source]

Recursively halve each line segment into separate lines.

Parameters:rez (integer, optional, default: 0) – Number of recursive subdivisions of a line segment. Values range from 0 to 7.
Returns:self (line object)
stcBar_ScalarMappable(stripe=None, bgcolor='k')[source]

ScalarMappable object with striped color values. Primarily useful for display of contour colorbars.

Parameters:
  • stripe (integer, optional, default: None) – Number of color stripes. If None, no stripes are formed.
  • bgcolor (color, optional, default: 'black') – Color between the stripes.
Returns:

self (Matplotlib.cm.ScalarMappable object)

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

Linear transformation of the line 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 (line object)

vertices

A 3 x N array of line vertices.

vlim

Range of scalar values which may be associated with color