molecular

Module that provides molecular visualization tools.

Actor

alias of vtkmodules.vtkRenderingCore.vtkActor

DataSetAttributes

alias of vtkmodules.vtkCommonDataModel.vtkDataSetAttributes

Mol

alias of vtkmodules.vtkCommonDataModel.vtkMolecule

Molecule([atomic_numbers, coords, ...])

Your molecule class.

OpenGLMoleculeMapper

alias of vtkmodules.vtkDomainsChemistryOpenGL2.vtkOpenGLMoleculeMapper

PTable

A class to obtain properties of elements (eg: Covalent Radius, Van Der Waals Radius, Symbol etc.).

PeriodicTable

alias of vtkmodules.vtkDomainsChemistry.vtkPeriodicTable

PolyData

alias of vtkmodules.vtkCommonDataModel.vtkPolyData

PolyDataMapper

alias of vtkmodules.vtkRenderingCore.vtkPolyDataMapper

ProteinRibbonFilter

alias of vtkmodules.vtkDomainsChemistry.vtkProteinRibbonFilter

SimpleBondPerceiver

alias of vtkmodules.vtkDomainsChemistry.vtkSimpleBondPerceiver

StringArray

alias of vtkmodules.vtkCommonCore.vtkStringArray

add_atom(molecule, atomic_num, x_coord, ...)

Add atomic data to our molecule.

add_bond(molecule, atom1_index, atom2_index)

Add bonding data to our molecule.

ball_stick(molecule[, colormode, ...])

Create an actor for ball and stick molecular representation.

bounding_box(molecule[, colors, linewidth])

Create a bounding box for a molecule.

compute_bonding(molecule)

Uses vtkSimpleBondPerceiver to generate bonding information for a molecule.

deep_copy_molecule(molecule1, molecule2)

Deep copies the atomic information (atoms and bonds) from molecule2 into molecule1.

get_all_atomic_numbers(molecule)

Return an array of atomic numbers corresponding to the atoms present in a given molecule.

get_all_atomic_positions(molecule)

Return an array of atomic coordinates corresponding to the atoms present in the molecule.

get_all_bond_orders(molecule)

Return an array of integers containing the bond orders (single/double/ triple) corresponding to the bonds present in the molecule.

get_atomic_number(molecule, atom_index)

Get the atomic number of an atom for a specified index.

get_atomic_position(molecule, atom_index)

Get the atomic coordinates of an atom for a specified index.

get_bond_order(molecule, bond_index)

Get the order of bond for a specified index.

numpy_to_vtk_points(points)

Convert Numpy points array to a vtk points array.

ribbon(molecule)

Create an actor for ribbon molecular representation.

set_atomic_number(molecule, atom_index, ...)

Set the atomic number of an atom for a specified index.

set_atomic_position(molecule, atom_index, ...)

Set the atomic coordinates of an atom for a specified index.

set_bond_order(molecule, bond_index, bond_order)

Set the bond order of a bond for a specified index.

sphere_cpk(molecule[, colormode])

Create an actor for sphere molecular representation.

stick(molecule[, colormode, bond_thickness])

Create an actor for stick molecular representation.

streamtube(lines[, colors, opacity, ...])

Use streamtubes to visualize polylines.

Actor

fury.molecular.Actor

alias of vtkmodules.vtkRenderingCore.vtkActor

DataSetAttributes

fury.molecular.DataSetAttributes

alias of vtkmodules.vtkCommonDataModel.vtkDataSetAttributes

Mol

fury.molecular.Mol

alias of vtkmodules.vtkCommonDataModel.vtkMolecule

Molecule

class fury.molecular.Molecule(atomic_numbers=None, coords=None, atom_names=None, model=None, residue_seq=None, chain=None, sheet=None, helix=None, is_hetatm=None)[source]

Bases: vtkmodules.vtkCommonDataModel.vtkMolecule

Your molecule class.

An object that is used to create molecules and store molecular data (e.g. coordinate and bonding data). This is a more pythonic version of Molecule.

__init__(atomic_numbers=None, coords=None, atom_names=None, model=None, residue_seq=None, chain=None, sheet=None, helix=None, is_hetatm=None)[source]

Send the atomic data to the molecule.

Parameters
  • atomic_numbers (ndarray of integers, optional) – The shape of the array must be (N, ) where N is the total number of atoms present in the molecule. Array having atomic number corresponding to each atom of the molecule.

  • coords (ndarray of floats, optional) – The shape of the array must be (N, 3) where N is the total number of atoms present in the molecule. Array having coordinates corresponding to each atom of the molecule.

  • atom_names (ndarray of strings, optional) – The shape of the array must be (N, ) where N is the total number of atoms present in the molecule. Array having the names of atoms.

  • model (ndarray of integers, optional) – The shape of the array must be (N, ) where N is the total number of atoms present in the molecule. Array having the model number corresponding to each atom.

  • residue_seq (ndarray of integers, optional) – The shape of the array must be (N, ) where N is the total number of atoms present in the molecule. Array having the residue sequence number corresponding to each atom of the molecule.

  • chain (ndarray of integers, optional) – The shape of the array must be (N, ) where N is the total number of atoms present in the molecule. Array having the chain number corresponding to each atom.

  • sheet (ndarray of integers, optional) – The shape of the array must be (S, 4) where S is the total number of sheets present in the molecule. Array containing information about sheets present in the molecule.

  • helix (ndarray of integers, optional) – The shape of the array must be (H, 4) where H is the total number of helices present in the molecule. Array containing information about helices present in the molecule.

  • is_hetatm (ndarray of bools, optional) – The shape of the array must be (N, ) where N is the total number of atoms present in the molecule. Array containing a bool value to indicate if an atom is a heteroatom.

property total_num_atoms

Return the total number of atoms in a given molecule.

property total_num_bonds

Return the total number of bonds in a given molecule.

OpenGLMoleculeMapper

fury.molecular.OpenGLMoleculeMapper

alias of vtkmodules.vtkDomainsChemistryOpenGL2.vtkOpenGLMoleculeMapper

PTable

class fury.molecular.PTable[source]

Bases: vtkmodules.vtkDomainsChemistry.vtkPeriodicTable

A class to obtain properties of elements (eg: Covalent Radius, Van Der Waals Radius, Symbol etc.).

This is a more pythonic version of vtkPeriodicTable providing simple methods to access atomic properties. It provides access to essential functionality available in vtkPeriodicTable. An object of this class provides access to atomic information sourced from Blue Obelisk Data Repository.

__init__()
atom_color(atomic_number)[source]

Given an atomic number, return the RGB tuple associated with that element (CPK coloring convention) provided by the Blue Obelisk Data Repository.

Parameters

atomicNumber (int) – Atomic number of the element whose RGB tuple is to be obtained.

atomic_number(element_name)[source]

Given a case-insensitive string that contains the symbol or name of an element, return the corresponding atomic number.

Parameters

element_name (string) – Name of the element whose atomic number is to be obtained.

atomic_radius(atomic_number, radius_type='VDW')[source]

Given an atomic number, return either the covalent radius of the atom (in Å) or return the Van Der Waals radius (in Å) of the atom depending on radius_type.

Parameters
  • atomic_number (int) – Atomic number of the element whose atomic radius is to be obtained.

  • radius_type (string) –

    Type of atomic radius to be obtained. Two valid choices:

    • ’VDW’ : for Van der Waals radius of the atom

    • ’Covalent’ : for covalent radius of the atom

    Default: ‘VDW’

atomic_symbol(atomic_number)[source]

Given an atomic number, returns the symbol associated with the element.

Parameters

atomic_number (int) – Atomic number of the element whose symbol is to be obtained.

element_name(atomic_number)[source]

Given an atomic number, returns the name of the element.

Parameters

atomic_number (int) – Atomic number of the element whose name is to be obtained.

PeriodicTable

fury.molecular.PeriodicTable

alias of vtkmodules.vtkDomainsChemistry.vtkPeriodicTable

PolyData

fury.molecular.PolyData

alias of vtkmodules.vtkCommonDataModel.vtkPolyData

PolyDataMapper

fury.molecular.PolyDataMapper

alias of vtkmodules.vtkRenderingCore.vtkPolyDataMapper

ProteinRibbonFilter

fury.molecular.ProteinRibbonFilter

alias of vtkmodules.vtkDomainsChemistry.vtkProteinRibbonFilter

SimpleBondPerceiver

fury.molecular.SimpleBondPerceiver

alias of vtkmodules.vtkDomainsChemistry.vtkSimpleBondPerceiver

StringArray

fury.molecular.StringArray

alias of vtkmodules.vtkCommonCore.vtkStringArray

add_atom

fury.molecular.add_atom(molecule, atomic_num, x_coord, y_coord, z_coord)[source]

Add atomic data to our molecule.

Parameters
  • molecule (Molecule) – The molecule to which the atom is to be added.

  • atomic_num (int) – Atomic number of the atom.

  • x_coord (float) – x-coordinate of the atom.

  • y_coord (float) – y-coordinate of the atom.

  • z_coord (float) – z-coordinate of the atom.

add_bond

fury.molecular.add_bond(molecule, atom1_index, atom2_index, bond_order=1)[source]

Add bonding data to our molecule. Establish a bond of type bond_order between the atom at atom1_index and the atom at atom2_index.

Parameters
  • molecule (Molecule) – The molecule to which the bond is to be added.

  • atom1_index (int) – Index of the first atom.

  • atom2_index (int) – Index of the second atom.

  • bond_order (int (optional)) – Bond order (whether it’s a single/double/triple bond). Default: 1

Notes

Ensure that the total number of bonds between two atoms doesn’t exceed 3. Calling add_bond to add bonds between atoms that already have a triple bond between them leads to erratic behavior and must be avoided.

ball_stick

fury.molecular.ball_stick(molecule, colormode='discrete', atom_scale_factor=0.3, bond_thickness=0.1, multiple_bonds=True)[source]

Create an actor for ball and stick molecular representation.

Parameters
  • molecule (Molecule) – The molecule to be rendered.

  • colormode (string, optional) –

    Set the colormode for coloring the atoms. Two valid color modes:

    • ’discrete’: Atoms and bonds are colored using CPK coloring convention.

    • ’single’: All atoms are colored with same color (grey) and all bonds are colored with same color (dark grey). RGB tuple used for coloring the atoms when ‘single’ colormode is selected: (150, 150, 150). RGB tuple used for coloring the bonds when ‘single’ colormode is selected: (50, 50, 50)

    Default: ‘discrete’

  • atom_scale_factor (float, optional) – Scaling factor. Default: 0.3

  • bond_thickness (float, optional) – Used to manipulate the thickness of bonds (i.e. thickness of tubes which are used to render bonds) Default: 0.1 (Optimal range: 0.1 - 0.5).

  • multiple_bonds (bool, optional) – Set whether multiple tubes will be used to represent multiple bonds. If True, multiple bonds (double, triple) will be shown by using multiple tubes. If False, all bonds (single, double, triple) will be shown as single bonds (i.e. shown using one tube each). Default is True.

Returns

molecule_actor – Actor created to render the ball and stick representation of the molecule to be visualized.

Return type

vtkActor

References

Turner, M. Ball and stick models for organic chemistry J. Chem. Educ. 1971, 48, 6, 407.

bounding_box

fury.molecular.bounding_box(molecule, colors=(1, 1, 1), linewidth=0.3)[source]

Create a bounding box for a molecule.

Parameters
  • molecule (Molecule) – The molecule around which the bounding box is to be created.

  • colors (tuple (3,) or ndarray of shape (3,), optional) – Color of the bounding box. Default: (1, 1, 1)

  • linewidth (float, optional) – Thickness of tubes used to compose bounding box. Default: 0.3

Returns

bbox_actor – Actor created to serve as a bounding box for a given molecule.

Return type

vtkActor

compute_bonding

fury.molecular.compute_bonding(molecule)[source]

Uses vtkSimpleBondPerceiver to generate bonding information for a molecule. vtkSimpleBondPerceiver performs a simple check of all interatomic distances and adds a single bond between atoms that are reasonably close. If the interatomic distance is less than the sum of the two atom’s covalent radii plus a tolerance, a single bond is added.

Parameters

molecule (Molecule) – The molecule for which bonding information is to be generated.

Notes

This algorithm does not consider valences, hybridization, aromaticity, or anything other than atomic separations. It will not produce anything other than single bonds.

deep_copy_molecule

fury.molecular.deep_copy_molecule(molecule1, molecule2)[source]

Deep copies the atomic information (atoms and bonds) from molecule2 into molecule1.

Parameters
  • molecule1 (Molecule) – The molecule to which the atomic information is copied.

  • molecule2 (Molecule) – The molecule from which the atomic information is copied.

get_all_atomic_numbers

fury.molecular.get_all_atomic_numbers(molecule)[source]

Return an array of atomic numbers corresponding to the atoms present in a given molecule.

Parameters

molecule (Molecule) – The molecule whose atomic number array is to be obtained.

get_all_atomic_positions

fury.molecular.get_all_atomic_positions(molecule)[source]

Return an array of atomic coordinates corresponding to the atoms present in the molecule.

Parameters

molecule (Molecule) – The molecule whose atomic position array is to be obtained.

get_all_bond_orders

fury.molecular.get_all_bond_orders(molecule)[source]

Return an array of integers containing the bond orders (single/double/ triple) corresponding to the bonds present in the molecule.

Parameters

molecule (Molecule) – The molecule whose bond types array is to be obtained.

get_atomic_number

fury.molecular.get_atomic_number(molecule, atom_index)[source]

Get the atomic number of an atom for a specified index.

Returns the atomic number of the atom present at index atom_index.

Parameters
  • molecule (Molecule) – The molecule to which the atom belongs.

  • atom_index (int) – Index of the atom whose atomic number is to be obtained.

get_atomic_position

fury.molecular.get_atomic_position(molecule, atom_index)[source]

Get the atomic coordinates of an atom for a specified index.

Returns the atomic coordinates of the atom present at index atom_index.

Parameters
  • molecule (Molecule) – The molecule to which the atom belongs.

  • atom_index (int) – Index of the atom whose atomic coordinates are to be obtained.

get_bond_order

fury.molecular.get_bond_order(molecule, bond_index)[source]

Get the order of bond for a specified index.

Returns the order of bond (whether it’s a single/double/triple bond) present at bond_index.

Parameters
  • molecule (Molecule) – The molecule to which the bond belongs.

  • bond_index (int) – Index of the bond whose order is to be obtained.

numpy_to_vtk_points

fury.molecular.numpy_to_vtk_points(points)[source]

Convert Numpy points array to a vtk points array.

Parameters

points (ndarray) –

Returns

vtk_points

Return type

vtkPoints()

ribbon

fury.molecular.ribbon(molecule)[source]

Create an actor for ribbon molecular representation.

Parameters

molecule (Molecule) – The molecule to be rendered.

Returns

molecule_actor – Actor created to render the rubbon representation of the molecule to be visualized.

Return type

vtkActor

References

Richardson, J.S. The anatomy and taxonomy of protein structure Advances in Protein Chemistry, 1981, 34, 167-339.

set_atomic_number

fury.molecular.set_atomic_number(molecule, atom_index, atomic_num)[source]

Set the atomic number of an atom for a specified index.

Assign atomic_num as the atomic number of the atom present at atom_index.

Parameters
  • molecule (Molecule) – The molecule to which the atom belongs.

  • atom_index (int) – Index of the atom to whom the atomic number is to be assigned.

  • atom_num (int) – Atomic number to be assigned to the atom.

set_atomic_position

fury.molecular.set_atomic_position(molecule, atom_index, x_coord, y_coord, z_coord)[source]

Set the atomic coordinates of an atom for a specified index.

Assign atom_coordinate to the coordinates of the atom present at atom_index.

Parameters
  • molecule (Molecule) – The molecule to which the atom belongs.

  • atom_index (int) – Index of the atom to which the coordinates are to be assigned.

  • x_coord (float) – x-coordinate of the atom.

  • y_coord (float) – y-coordinate of the atom.

  • z_coord (float) – z-coordinate of the atom.

set_bond_order

fury.molecular.set_bond_order(molecule, bond_index, bond_order)[source]

Set the bond order of a bond for a specified index.

Assign bond_order (whether it’s a single/double/triple bond) to the bond present at the bond_index.

Parameters
  • molecule (Molecule) – The molecule to which the bond belongs.

  • bond_index (int) – Index of the bond whose order is to be assigned.

  • bond_order (int) – Bond order (whether it’s a single/double/triple bond).

sphere_cpk

fury.molecular.sphere_cpk(molecule, colormode='discrete')[source]

Create an actor for sphere molecular representation. It’s also referred to as CPK model and space-filling model.

Parameters
  • molecule (Molecule) – The molecule to be rendered.

  • colormode (string, optional) –

    Set the colormode for coloring the atoms. Two valid color modes:

    • ’discrete’: Atoms are colored using CPK coloring convention.

    • ’single’: All atoms are colored with same color (grey). RGB tuple used for coloring the atoms when ‘single’ colormode is selected: (150, 150, 150).

    Default: ‘discrete’

Returns

molecule_actor – Actor created to render the space filling representation of the molecule to be visualized.

Return type

vtkActor

References

Corey R.B.; Pauling L. Molecular Models of Amino Acids, Peptides, and Proteins Review of Scientific Instruments 1953, 24 (8), 621-627.

stick

fury.molecular.stick(molecule, colormode='discrete', bond_thickness=0.1)[source]

Create an actor for stick molecular representation.

Parameters
  • molecule (Molecule) – The molecule to be rendered.

  • colormode (string, optional) –

    Set the colormode for coloring the bonds. Two valid color modes:

    • ’discrete’: Bonds are colored using CPK coloring convention.

    • ’single’: All bonds are colored with the same color (dark grey) RGB tuple used for coloring the bonds when ‘single’ colormode is selected: (50, 50, 50)

    Default: ‘discrete’

  • bond_thickness (float, optional) – Used to manipulate the thickness of bonds (i.e. thickness of tubes which are used to render bonds). Default: 0.1 (Optimal range: 0.1 - 0.5).

Returns

molecule_actor – Actor created to render the stick representation of the molecule to be visualized.

Return type

vtkActor

streamtube

fury.molecular.streamtube(lines, colors=None, opacity=1, linewidth=0.1, tube_sides=9, lod=True, lod_points=10000, lod_points_size=3, spline_subdiv=None, lookup_colormap=None)[source]

Use streamtubes to visualize polylines.

Parameters
  • lines (list) – list of N curves represented as 2D ndarrays

  • colors (array (N, 3), list of arrays, tuple (3,), array (K,)) – If None or False, a standard orientation colormap is used for every line. If one tuple of color is used. Then all streamlines will have the same colour. If an array (N, 3) is given, where N is equal to the number of lines. Then every line is coloured with a different RGB color. If a list of RGB arrays is given then every point of every line takes a different color. If an array (K, 3) is given, where K is the number of points of all lines then every point is colored with a different RGB color. If an array (K,) is given, where K is the number of points of all lines then these are considered as the values to be used by the colormap. If an array (L,) is given, where L is the number of streamlines then these are considered as the values to be used by the colormap per streamline. If an array (X, Y, Z) or (X, Y, Z, 3) is given then the values for the colormap are interpolated automatically using trilinear interpolation.

  • opacity (float, optional) – Takes values from 0 (fully transparent) to 1 (opaque). Default is 1.

  • linewidth (float, optional) – Default is 0.01.

  • tube_sides (int, optional) – Default is 9.

  • lod (bool, optional) – Use LODActor(level of detail) rather than Actor. Default is True. Level of detail actors do not render the full geometry when the frame rate is low.

  • lod_points (int, optional) – Number of points to be used when LOD is in effect. Default is 10000.

  • lod_points_size (int, optional) – Size of points when lod is in effect. Default is 3.

  • spline_subdiv (int, optional) – Number of splines subdivision to smooth streamtubes. Default is None.

  • lookup_colormap (vtkLookupTable, optional) – Add a default lookup table to the colormap. Default is None which calls fury.actor.colormap_lookup_table().

Examples

>>> import numpy as np
>>> from fury import actor, window
>>> scene = window.Scene()
>>> lines = [np.random.rand(10, 3), np.random.rand(20, 3)]
>>> colors = np.random.rand(2, 3)
>>> c = actor.streamtube(lines, colors)
>>> scene.add(c)
>>> #window.show(scene)

Notes

Streamtubes can be heavy on GPU when loading many streamlines and therefore, you may experience slow rendering time depending on system GPU. A solution to this problem is to reduce the number of points in each streamline. In Dipy we provide an algorithm that will reduce the number of points on the straighter parts of the streamline but keep more points on the curvier parts. This can be used in the following way:

from dipy.tracking.distances import approx_polygon_track
lines = [approx_polygon_track(line, 0.2) for line in lines]

Alternatively we suggest using the line actor which is much more efficient.