s3dlib.pntcloud.Point3DCloud

Contents

Geometry Properties/Methods

name

Descriptive identifier for the cloud.

val_source

String indicating mapping type for cloud values.

bounds

Dictionary of coordinate and value ranges.

points

A (3,N) array of point cloud coordinates.

sample_size

Number of data samples used for value mapping.

density_pdg

pdg for sample density cloud

get_domain()

domain of the point cloud.

__call__(xyz)

Values at coordinates in the cloud domain.

__str__()

String representation of the point cloud object

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

domain(xlim[, ylim, zlim])

Reset the domain of the point cloud object.

map_geom_from_op(operation[, name])

Functional transformation of point cloud coordinates.

map_vals_from_op(operation[, cmap, name])

Functional assignment of values within the point cloud.

map_vals_from_sampvals(samples[, vadj, ...])

Assign cloud values from data samples values.

map_vals_from_sampdens(samples[, pdg, ...])

Assign cloud values from normalized density of a sample coordinate distribution.

Color Properties/Methods

point_colors

A (N,4) array of point cloud colors

get_color_for_val([N])

Arrays of cloud values, normalized values and associated colors.

get_colors_at_xyz(xyz)

Colors at coordinates in the cloud domain.

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

map_color_from_op(operation[, rgb, cname])

Assignment of point color from a function.

map_cmap_from_op(operation[, cmap])

Functional assignment of a point color from a color map.

map_cmap_from_cloudvals([cmap])

Point color assignment using point values.

set_color(color)

Assignment of color.

Object Creation Methods

valsurf(*fval, **kwargs)

Surface3DCollection defined for a constant value a the point cloud.

valsurfSet(numb, **kwargs)

Surface3DCollection defined for constant values in a point cloud.

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 color mapped point cloud values.

add_to3d(axes, *focus, **kwargs)

Add the cloud points to the the 3D axis.

Code Documentation

class s3dlib.pntcloud.Point3DCloud(rez, name=None, **kwargs)[source]

Bases: object

Create a rectangular point cloud in xyz coordinates.

Parameters:

  • rez (number, optional, default: 1.0) – Number of subdivisions ( 10*rez ) along the 3 coordinate axes. Rez values range from 0.4 to 10.0.

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

  • domain (a number, list or array, default: 1) – The domain of the cloud. For a number, n, the x,y,z axes domains will be [-n,n]. For a 1-dimensional 2-element list, [a,b] will be assigned the domain for all 3 axes. Using a list of list (array), as [ [a,b],[c,d],[e,f] ], the domain is assigned individually for each of the three coordinate axes.

  • cmap (str or Colormap, optional) – A Colormap instance or registered colormap name.

  • color (str, optional) –

  • size (float, optional) – Marker size of cloud points.

  • marker (MarkerStyle, default : 'o'.) –

__call__(xyz)[source]

Values at coordinates in the cloud domain.

Parameters:

xyz (V x 3 float array-like) – Coordinates within the domain.

Returns:

V float array

__str__()[source]

String representation of the point cloud object

add_to3d(axes, *focus, **kwargs)[source]

Add the cloud points to the the 3D axis.

Parameters:

  • axes ((Matplotlib 3D axes object)) –

  • focus (number) – Focus ranges from 0 to 1 going from low to high cloud point normalized values, respectively. The color alpha is modified from opaque at the focus to fully transparent.

  • span (number from 0.1 to 1.0) – The span controls the width of alpha values from opaque to transparent over the range of cloud values.

  • subview (a 3 X 2 float array) – Sets the view domain within the point cloud domain.

  • size (float, default : 10) – Marker size of cloud points.

  • marker (string, default : 'o') – Matplotlib marker.

Returns:

number of cloud points displayed in view.

property bounds[source]

Dictionary of coordinate and value ranges.

Each dictionary value is a 2 float array of minimum and maximum values. Keys are:

‘xlim’ : x-coordinate

‘ylim’ : y-coordinate

‘zlim’ : z-coordinate

‘vlim’ : value assignments.

property cBar_ScalarMappable[source]

matplotlib.cm.ScalarMappable object for color mapped point cloud values.

property density_pdg[source]

pdg for sample density cloud

domain(xlim, ylim=None, zlim=None)[source]

Reset the domain of the point cloud object. Initial domain is set as [ [-1,1], [-1,1], [-1,1] ]

Parameters:

  • xlim (a number, list or array, default: 1) – The domain of the cloud. For a number, n, the x,y,z axes domains will be [-n,n]. For a 1-dimensional 2-element list, [a,b] will be assigned the domain for all 3 axes. Using a list of list (array), as [ [a,b],[c,d],[e,f] ], the domain is assigned individually for each of the three coordinate axes. If 2D array, ylim and zlim are ignored, otherwize, must be a number or 1D array if ylim or zlim are None.

  • ylim (a number or 2D array, default: None) – Set the ylim and/or zlim. If None, set to xlim.

  • zlim (a number or 2D array, default: None) – Set the ylim and/or zlim. If None, set to xlim.

Returns:

self (Point3DCloud object)

get_color_for_val(N=1)[source]

Arrays of cloud values, normalized values and associated colors. Useful for creating Matplotlib legend patch handles and setting focus for the add_to3d method. Colors are selected from the mapped cloud colormap.

Parameters:

N (integer or N array of floats, default: 1) – For a integer, number of evenly spaced values and colors within the cloud. For an array, used to determine the colors for a list of values within the cloud. Colors are determined from the cloud colormap.

Returns:

  • carr (N x 4 array of colors)

  • varr (N float array of values)

  • norm (N float array of normalized values)

get_colors_at_xyz(xyz)[source]

Colors at coordinates in the cloud domain.

Parameters:

xyz (V x 3 float array-like) – Coordinates within the domain.

Returns:

V X 4 float array

get_domain()[source]

domain of the point cloud. Usefull for getting the Matplotlib 3D axis xyz limits when samples are used to set the domain. (dreset=True)

map_cmap_from_cloudvals(cmap=None)[source]

Point color assignment using point values.

Parameters:

cmap (str or Colormap, optional) – A Colormap instance or registered colormap name. If not assigned, the default Colormap is used. The colormap maps the point values to colors.

Returns:

self (point cloud object)

map_cmap_from_op(operation, cmap=None)[source]

Functional assignment of a point color from a color map. Also assigns point cloud values.

Parameters:

  • operation (function object) – Coordinate mapping function that takes one argument, a 3xN Numpy array of native coordinates. The function returns an array of scalar values

  • cmap (str or Colormap, optional) – A Colormap instance or registered colormap name. If not assigned, the default Colormap is used. The colormap maps the point values to colors.

Returns:

self (point cloud object)

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

Assignment of point color from a function.

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 (string, optional, default: None or op function name.) – Descriptive identifier for values indicated by color.

Returns:

self (point cloud object)

map_geom_from_op(operation, name=None)[source]

Functional transformation of point cloud 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 (surface object)

map_vals_from_op(operation, cmap=None, name=None)[source]

Functional assignment of values within the point cloud.

Parameters:

  • operation (function object) – Coordinate mapping function that takes one argument, a 3xN Numpy array of native coordinates. The function returns an array of scalar values

  • cmap (str or Colormap, optional, default: None) – A Colormap instance or registered colormap name. If not assigned (None) , colormapping will NOT be applied.

  • name (string, optional, default: None or op function name.) – Descriptive identifier for the cloud values.

Returns:

self (point cloud object)

map_vals_from_sampdens(samples, pdg=None, dreset=False, cmap=None, name=None)[source]

Assign cloud values from normalized density of a sample coordinate distribution.

Parameters:

  • samples (V X 3 or V X 4, float array-like) – An array of V number of xyz vertex coordinates. If a V x 4 array is passed, only the first 3 are used for the coordinates.

  • pdg (number, default : 1.0) – Sample coordinate distribution, normalized within the domain and sample size. Values range .5 to 5.0.

  • dreset (bool { True, False }, optional, default: False) – Domain reset based on sample distribution. If True, the point cloud DOMAIN IS RESET to the bounds of the samples. If False, the out of the domain SAMPLES ARE EXCLUDED.

  • cmap (str or Colormap, optional, default: None) – A Colormap instance or registered colormap name. If not assigned (None) , colormapping will NOT be applied.

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

Returns:

self (point cloud object)

map_vals_from_sampvals(samples, vadj=None, dreset=False, cmap=None, name=None)[source]

Assign cloud values from data samples values.

Parameters:

  • samples (V X 4, float array-like) – An array of V number of xyz vertex coordinates and scaler values which are assigned to each vertex.

  • vadj (str {'s','c'}, optional, default: None) – Cloud value adjustment to sample value range. For ‘s’, the cloud values are scaled to the minimum and maximum of the sample values. For ‘c’, the cloud values are clipped at the minimum and maximum of the sample values.

  • dreset (bool { True, False }, optional, default: False) – Domain reset based on sample distribution. If True, the point cloud DOMAIN IS RESET to the bounds of the samples. If False, the out of the domain SAMPLES ARE EXCLUDED.

  • cmap (str or Colormap, optional, default: None) – A Colormap instance or registered colormap name. If not assigned (None) , colormapping will NOT be applied.

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

Returns:

self (point cloud object)

property name[source]

Descriptive identifier for the cloud.

property point_colors[source]

A (N,4) array of point cloud colors

property points[source]

A (3,N) array of point cloud coordinates.

property sample_size[source]

Number of data samples used for value mapping.

set_color(color)[source]

Assignment of color.

Parameters:

color (color assigned to all points.) –

Returns:

self (point cloud object)

property val_source[source]

String indicating mapping type for cloud values.

valsurf(*fval, **kwargs)[source]

Surface3DCollection defined for a constant value a the point cloud.

Parameters:

  • fval (a number) – Scalar value of surface contour within the cloud.

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

  • color (color or list of colors, optional, default: None) –

  • cmap (str or Colormap, optional) – A Colormap instance or registered colormap name. Used for multiple surface values if color is not assigned.

Returns:

Surface3DCollection object

valsurfSet(numb, **kwargs)[source]

Surface3DCollection defined for constant values in a point cloud.

Parameters:

  • numb (an integer) – Number of constant valued contour surfaces within the domain. Values are evenly spaced between minimum to maximum cloud values.

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

  • color (color or list of colors, optional, default: None) –

  • cmap (str or Colormap, optional) – A Colormap instance or registered colormap name. Used for multiple surface values if color is not assigned.

Returns:

Surface3DCollection object