bpsci package

Submodules

bpsci.core module

Building Blocks of a Dynamic Visualization - bpsci.core

The bpsci core is a collection of classes and methods used to create dynamic visualizations.

class bpsci.core.anim_text(name, parent, anim, data, label, fix_place, if_str)

Bases: object

Creates animated text

Parameters

  • name (str) – the Blender object name of the text (‘_text’ will be appended to this name)

  • parent (bpy.data.object) – the Blender object parent of this text

  • anim (bpsci.core.anim) – class object that was used to initialize the animation

  • data (np.ndarray) – the data to be displayed (same length as the number of animated frames)

  • label (str) – a label to append to the text (if no label is desired, pass ‘’)

  • fix_place (int) – the number of decimal places to fix the text to

  • if_str (bool) – whether or not the data is a numerical or string vector. Currently only numerical vectors are supported.

bpsci.core.curve_to_mesh(curve)
class bpsci.core.dyn_obj(obj, pa, cog, euler_type, parent, anim)

Bases: object

The main building block of all dynamic visualizations

Parameters

  • obj (bpy.data.object) – the Blender object that will be animated

  • pa (np.ndarray) – the offset of the principal axes specified by the :param: ` euler_type:

  • cog (tuple) – the center of gravity as defined from the origin of the 3D model

  • euler_type (str) – the Euler angle order (i.e. ‘xyz’ for 1,2,3 or ‘zxz’ for 3,1,3)

  • parent (bpy.data.object) – the Blender object parent of the original object

  • anim (bpsci.core.init_anim) – class object that was used to initialize the animation

apply_animation(x_list, y_list, z_list, quat_list)

Animates a dyn_obj in the full six degrees of freedom

Parameters

  • x_list (np.ndarray) – a numpy array of the x position over time

  • y_list (np.ndarray) – a numpy array of the y position over time

  • z_list (np.ndarray) – a numpy array of the z position over time

  • quat_list (np.ndarray) – a numpy array of the quaternion over time. Can be passed None if rotation is ignored.

apply_streamline(staticity, int_x, int_y, int_z, thickness)

Gives a dyn_obj a dynamic or static trail that shows its position

Parameters

  • staticity (str) – a string [‘dynamic’ or ‘static’] that specifies whether the streamline is animated or static

  • x_list (np.ndarray) – a numpy array of the x position over time

  • y_list (np.ndarray) – a numpy array of the y position over time

  • z_list (np.ndarray) – a numpy array of the z position over time

  • quat_list (np.ndarray) – a numpy array of the quaternion over time. Can be passed None if rotation is ignored.

body

ref_frame: the body reference frame (untransformed principal axes)

euler_pa
Type

np.ndarray: the offset of the principal axes specified by the :param: ` euler_type:

frames
Type

np.ndarray: the frames that Blender will animate and have corresponding data for

name
Type

str: the Blender object name of the original object

non_rot

ref_frame: the non-rotational reference frame (owner of translational movement only)

ob
Type

bpy.data.object: the Blender object that will be animated

pa_axes

ref_frame: the principal axes rotational reference frame (owner of rotational movement, inherits translational movement from parent)

parent
Type

bpy.data.object: the Blender object parent of this reference frame

quat
Type

np.ndarray: a numpy array of one quaternion that represents the principal axes offset

scale
Type

float: global physical scale factor of the animation

class bpsci.core.dyn_vec(parent, name, scale_mag, scale_off, offset, anim)

Bases: object

Initializes a dynamic vector`

Parameters

  • parent (bpy.data.object) – the Blender object the vector is associated with

  • name (str) – the Blender object name of the vector (‘_vector’ will be appended to this name)

  • scale_mag (float) – the scaling factor of the vector’s magnitude axis (purely aesthetic)

  • scale_off (float) – the scaling factor of the vector’s off-axes (purely aesthetic)

  • offset (tuple[float]) – offset of vector from the parent object (purely aesthetic)

  • anim (bpsci.core.anim) – class object that was used to initialize the animation

anim

bpsci.core.init_anim: class object that was used to initialize the animation

animate(x, y, z)

Animates a dynamic vector

Parameters

  • x (np.ndarray) – a numpy array of the x component over time

  • y (np.ndarray) – a numpy array of the y component over time

  • z (np.ndarray) – a numpy array of the z component over time

filepath
Type

str: file path to arrow asset

frames
Type

np.ndarray: the frames that Blender will animate and have corresponding data for

name

str: the Blender object name of the vector

parent
Type

bpy.data.object: the Blender object parent of this reference frame

parent_rf
Type

bpy.data.object: holds the vector

vec
Type

bpy.data.object: the actual arrow asset

class bpsci.core.init_anim(t, speed_up, scale)

Bases: object

Sets up the global animation information such speed up and global scale :param np.ndarray t: contains the time information that corresponds with the six degrees of freedom data :param float speed_up: the ‘real time speed up’ or the ratio of the duration of the data to the duration of the animation :param float scale: global physical scale factor of the animation, i.e., .1 will reduce everything to be 1/10th its original size

frame_duration
Type

int: number of total frames in animation

frame_rate
Type

float: frame rate of animation

frames
Type

np.ndarray: the frames that Blender will animate and have corresponding data for

scale
Type

float: global physical scale factor of the animation, i.e., .1 will reduce everything to be 1/10th its original size

speed_up
Type

float: the “real time speed up” or the ratio of the duration of the data to the duration of the animation

t
Type

np.ndarray: contains the time information that corresponds with the six degrees of freedom data

class bpsci.core.ref_frame(name, parent, anim)

Bases: object

Initializes a reference frame that other objects and animations can be the child of. In blender, this takes the form of an Empty object.

Parameters

  • name (str) – the Blender object name of the reference frame

  • parent (bpy.data.object) – the Blender object parent of this reference frame

  • anim (bpsci.core.anim) – class object that was used to initialize the animation

dynamic_6DOF(quat, x_list, y_list, z_list)

Animates the reference frame over time.

Warning

This is currently an internal method. This method will be exposed properly in future updates

New in version 0.2.30.

May be useful for continually offsetting the reference frame from the parent object (i.e. for center of mass of principal axes offset for changing mass/distribution)

Parameters

  • quat (np.ndarray) – an numpy array of quaternions over time

  • x (np.ndarray) – the x position over time

  • y (np.ndarray) – the y position over time

  • z (np.ndarray) – the z position over time

frames
Type

np.ndarray: the frames that Blender will animate and have corresponding data for

name
Type

str: the Blender object name of the reference frame

ob
Type

bpy.data.object: the Blender object that represents this reference frame

parent
Type

bpy.data.object: the Blender object parent of this reference frame

scale
Type

float: global physical scale factor of the animation

static_6DOF(quat, x, y, z)

Places the reference frame in one specified static location.

Warning

This is currently an internal method. This method will be exposed properly in future updates

New in version 0.2.30.

May be useful for offsetting the reference frame from the parent object (i.e. for center of mass of principal axes offset)

Parameters

  • quat (np.ndarray) – an numpy array of one quaternion

  • x (float) – the x position

  • y (float) – the y position

  • z (float) – the z position

bpsci.utils module

bpsci.utils.bpy_obj(obj_name)

Returns the Blender object associated with the passed name

Parameters

obj_name (str) – the object name

Returns:

:returns (bpy.data.object) the Blender object

bpsci.utils.erase_others(obj_name)

Erase all objects associated with the passed object name (that is not the original object).

Warning

this function will delete any object that has the passed object name as a substring

New in version 0.2.30.

Parameters

obj_name (str) – the object name

bpsci.utils.erase_self(obj_name)

Erase object from name passed

Parameters

obj_name (str) – the object name

bpsci.utils.erase_vector(name)

Erase vector from name of the associated bpsci.core.dyn_vector

Parameters

obj_name (str) – the name passed to bpsci.core.dyn_vector

bpsci.utils.euler2quat(angles1, angles2, angles3, euler_type)

Takes a set of Euler angles over time and returns the equivalent quaternion representation

Parameters

  • angles1 (np.ndarray) – first set of angles over time

  • angles2 (np.ndarray) – second set of angles over time

  • angles3 (np.ndarray) – third set of angles over time

  • euler_type (str) – the Euler angle order (i.e. ‘xyz’ for 1,2,3 or ‘zxz’ for 3,1,3)

Returns:
returns (nd.array)

a numpy array of quaternions over time

Module contents