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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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')

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])

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