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