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)	Combine two line objects into a single line object.
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: 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.

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

__add__(othr)

Combine two line objects into a single line object.

Parameters:

othr (ColorLine3DCollection object) –

Returns:

ColorLine3DCollection object

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

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

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

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.

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

Returns:

self (line object)

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.

Parameters:

• X (N x M arrays) – Cartesian x,y,z coordinate values.

• Y (N x M arrays) – Cartesian x,y,z coordinate values.

• Z (N x M arrays) – Cartesian x,y,z coordinate values.

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

Returns:

surface (ColorLine3DCollection object)

property name

Descriptive identifier for the line geometry.

property segmentcenters

A 3 x N array of line segment centers.

property segmentcolors

A N x 4 array of segment colors.

property segmentdirections

A N x 3 array of line segment direction vectors.

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>, line_alpha=<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 line_alpha: scalar 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

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)

property vertices

A 3 x N array of line vertices.

property vlim

Range of scalar values which may be associated with color