Blender API

All the scripts and modules tasked to read computational chemistry files in the formats .com and .xyz and convert them to .fbx, .obj, .glb, or .stl formats

Main Body script

Animate Module

Animate.ExtractDataFromFile(path)

Extracts data from a path and stores it as a list

Parameters:

path – <string> path to read the file

Returns:

List[str] of data. Each entry corresponds to a line in the file to read

Animate.animate(anim_frames, mode='.fbx', step_size=20)

Orchestrates animation of molecular elements and bonds.

Parameters:

• anim_frames (str) – data of animation frames for every atom involved

• step_size (int, optional) – Frame interval between keyframes.

Animate.animate_bonds_by_type_list(bond_type_list, anim_data, bond_type, step_size=10)

Animates bonds based on their type and provided animation data.

Parameters:

• bond_type_list – (List[char]) The list of bonds to animate.

• anim_data – (List[str]) The animation data.

• bond_type – (char) The bond type.

• step_size – (int) The interval between frames.

• extra_frames – (int) The number of additional frames.

Animate.animate_elements_from_anim_data(anim_data, step_size=10)

Animates elements based on provided animation data.

Parameters:

• anim_data – (List[str]) The animation data.

• step_size – (int) The interval between frames.

• extra_frames – (int) The number of additional frames.

Animate.bake_all_animations(element_list, bond_list, end_frame=40, mode='.fbx')

Bakes all the animations in the scene.

Parameters:

• element_list – (List[bpy.data.object]) The list of elements present in the scene

• bond_list – (List[bpy.data.object]) The list of bonds present in the scene

• end_frame – (int) Optional. Determines the length of the animation

Animate.bake_for_fbx(element_list, bond_list, end_frame)

Animate.bake_for_glb(element_list, bond_list, end_frame)

Animate.build_animations(anim_data, bond_list, bond_types, step_size, extra_frames, end_frame)

Constructs animations for elements and bonds in the scene.

Parameters:

• anim_data (list[list]) – Processed animation data.

• bond_list (list) – List of bond objects.

• bond_types (dict) – Dictionary mapping bond symbols to indices.

• step_size (int) – Frame interval between keyframes.

• end_frame (int) – Last frame in the animation.

Animate.calculate_number_of_frames(animation_frames)

Determines the number of animation frames based on the JSON ‘animation_frames’ list.

Parameters:

animation_frames – List of strings, each representing an atom’s animation data.

Returns:

Number of frames in the animation.

Return type:

int

Animate.clear_all_animations()

Removes all keyframes for all objects in the scene

Animate.detect_bond_types(bond_list)

Extract the unique bond types from the bond list.

Parameters:

bond_list – (List[bpy.data.object]) objects corresponding to the bonds in the molecule

Returns:

a set of unique bonds in bond_list

Return type:

List[char]

Animate.export_animation(filepath)

Exports the current Blender scene as an animation to the specified file path. Supports .fbx, .glb, .usd and .usdz formats.

Parameters:

filepath – (str) Full path (including extension) where the animation will be saved.

Animate.filter_bond_list_by_type(bond_list)

Categorizes bonds into different types based on naming conventions.

Parameters:

bond_list (list) – List of bond objects.

Returns:

Tuple of categorized bond lists (dashed, single, aromatic, double, triple bonds).

Return type:

tuple[list, list, list, list, list]

Animate.force_nla_tracks_for_glb(objects)

Ensures that each object has its baked action pushed to an NLA track, which is required for GLB export to include animations.

Parameters:

objects – List of objects to process

Animate.get_bond_locations(bond_name, anim_data, type)

Calculates the center of mass for each bond location.

Parameters:

• bond_name (str) – The name of the bond.

• anim_data (List[str]) – The animation data.

• type (char) – The bond type.

Returns:

The list of center locations for each bond.

Return type:

List[mathutils.Vector]

Animate.get_bond_normals(bond_name, anim_data, type)

Calculates the normal vector for each bond location.

Parameters:

• bond_name – (str) The name of the bond.

• anim_data – (List[str]) The animation data.

• type – (str) The bond type.

Returns:

The list of normal vectors for the bond.

Return type:

List[Mathutils.Vector]

Animate.insert_keyframes_to_all(number_of_frames, step_size=10)

Inserts location keyframes for all objects in the scene at specified frame intervals.

Parameters:

• number_of_frames (int) – Total number of frames.

• step_size (int, optional) – Frame interval for keyframe insertion.

Animate.refine_anim_data(raw_anim_data)

Converts raw animation data into numerical vectors.

Parameters:

raw_anim_data – List of strings, each representing an atom’s animation data.

Returns:

Refined animation data with numerical vectors.

Return type:

list[list]

Animate.separate_elements_from_bonds()

Categorizes scene objects as elements or bonds based on naming conventions.

Returns:

A tuple containing lists of elements and bonds.

Return type:

tuple[list, list]

Animate.update_keyframe_locations(target, step_size, locations)

Updates and inserts keyframe locations for a target object.

Parameters:

• target (bpy.types.Object) – Object to update.

• step_size (int) – Interval between frames.

• locations (list[mathutils.Vector]) – List of location vectors for keyframes.

Animate.update_keyframe_rotations(target, step_size, normals)

Updates keyframe rotations for a target object based on normals.

Parameters:

• target (bpy.types.Object) – Object to update.

• step_size (int) – Interval between frames.

• normals (list[mathutils.Vector]) – List of normal vectors for each frame

Animate.update_keyframe_rotations_quaternion(target, step_size, normals)

Updates keyframe rotations for a target object using quaternion rotations based on normal vectors.

Parameters:

• target (bpy.types.Object) – Object to update.

• step_size (int) – Interval between frames.

• normals (list[mathutils.Vector]) – List of normal vectors for each frame.

Animate.update_keyframe_scale(target, bond_name, anim_data, bond_type, step_size)

Updates keyframe scales for a target object based on the distance between two atoms.

Parameters:

• target (bpy.types.Object) – Object to update.

• bond_name (str) – Name of the bond

• anim_data (List[List[mathutils.Vector]]) – Animation data containing atom positions.

• bond_type (str) – Character separating the two atoms in the bond name.

• step_size (int) – Interval between frames.

Atom Highlighter Module

AtomHighlighter.create_highlight_material(object_name, transparency_value=0.5, outline_color='#15eae3')

Creates a highlight material with the specified transparency and outline color.

Parameters:

• object_name – (str) The name of the object to highlight.

• transparency_value – (float) The transparency value for the material (default is 0.5).

• outline_color – (str) The color of the outline in hex format (default is “#15eae3”).

Returns:

The created highlight material.

Return type:

bpy.types.Material

AtomHighlighter.find_bond_object(atom1, atom2)

Finds the bond object in the scene that contains atom1 and atom2 in its name.

Parameters:

• atom1 – (str) The name and index of the first atom (e.g., “C01”).

• atom2 – (str) The name and index of the second atom (e.g., “C02”).

Returns:

The bond object if found, None otherwise.

Return type:

bpy.types.Object or None

AtomHighlighter.hex_to_rgba(hex_color)

Converts a hex color string to an RGBA list, supporting optional alpha.

Parameters:

hex_color – (str) A string representing the hex color (e.g., “#ea1517” or “#ea151780”).

Returns:

A list of four float values representing the RGBA color.

Return type:

[float, float, float, float]

AtomHighlighter.highlight_atom(atom_name, outline_size=1.5, transparency_value=0.5, outline_color='#15eae333')

Highlights an atom by creating a highlight sphere around it.

Parameters:

• atom_name – (str) The name of the atom object to highlight.

• outline_size – (float) The size multiplier for the outline sphere relative to the atom object (default is 1.5).

• transparency_value – (float) The transparency value for the outline material (default is 0.5).

• outline_color – (str) The color of the outline in hex format (default is “#15eae3”).

AtomHighlighter.highlight_bond(atom_1, atom_2, outline_size=0.33, transparency_value=0.5, outline_color='#15eae3')

Highlights a bond by creating a highlight cylinder around it.

Parameters:

• atom_1 – (str) The name and index of the first atom (e.g., “C01”).

• atom_2 – (str) The name and index of the second atom (e.g., “C02”).

• outline_size – (float) The size multiplier for the outline cylinder relative to the bond (default is 0.33).

• transparency_value – (float) The transparency value for the outline material (default is 0.5).

• outline_color – (str) The color of the outline in hex format (default is “#15eae3”).

Atom Data Module

class Atom_Data.Atom_Data(radius: float, vanDerWaals=0.0, color=(0.5, 0.5, 0.5, 1), ionicData=[<Atom_Data.Ionic object>])

Bases: object

Stores atomic data including covalent radius, van der Waals radius, RGBA color values, and ionic data.

Parameters:

• radius – (float) The covalent radius of the atom.

• vanDerWaals – (float) The van der Waals radius (default is 0.00 if not reported).

• color – (tuple) RGBA values representing the atom color (default is gray: (0.5, 0.5, 0.5, 1)).

• ionicData – (list) A list of Ionic objects representing ionic data (default is a list with one default Ionic instance).

get_color()

Gets the RGBA color values of the atom.

Returns:

A tuple of 4 float values representing the RGBA color.

Return type:

tuple

get_ionicData()

get_radius()

Gets the atom’s covalent radius.

Returns:

The covalent radius of the atom.

Return type:

float

get_vanDerWaals()

Gets the van der Waals radius of the atom.

Returns:

The van der Waals radius.

Return type:

float

class Atom_Data.Ionic(charge=0, coordination='', radius=0.0)

Bases: object

Represents an ionic radius with charge, coordination, and radius.

Parameters:

• charge – (int) The ionic charge (default is 0).

• coordination – (str) The coordination environment (default is an empty string).

• radius – (float) The ionic radius (default is 0.0).

set_radius(value: float)

Sets the ionic radius.

Parameters:

value – (float) The new radius value.

Bond Order Calculator Module

Clear Transforms Module

Clear_Transforms.Apply_Bond_Transforms(bond_list)

Applies location and rotation transforms to a list of bond objects.

Parameters:

bond_list – (list) List of bond objects.

Returns:

None

Clear_Transforms.Apply_Element_Transforms(names_and_pos)

Applies location and rotation transforms to a list of element objects.

Parameters:

names_and_pos – (list) List of element object names.

Returns:

None

Clear_Transforms.get_bond_obj_list()

Retrieves a list of bond objects from the scene.

Returns:

(list) List of bond objects.

Create Materials Module

Create_Materials.AssignMaterial(material_name, material_color)

Creates a material if it does not exist and assigns its name and diffuse color.

Parameters:

• material_name – (str) Name of the material.

• material_color – (tuple) RGBA values for the material.

Returns:

(bpy.types.Material) The created or existing material.

Create_Materials.AssignTransparentMaterial(material_name, material_color)

Create_Materials.CreateAndAssignMaterials(ref_dict)

Instantiates the materials for the elements present in the molecule.

Parameters:

ref_dict – (dict) Dictionary of elements present in the molecule and their data.

Returns:

(dict) Dictionary of created materials.

Create_Materials.RemoveAllMaterialsAndMeshes()

Removes all materials and meshes from the Blender scene.

Returns:

None

Export Data Module

Export_Data.ExportSceneAs(folder_path, file_name, file_type)

Exports the Blender scene to the specified file type.

Parameters:

• folder_path – (str) The path to the folder where the file will be saved.

• file_name – (str) The name of the file to be saved.

• file_type – (str) The type of file to export (e.g., .fbx, .glb, .dae, .obj, .stl).

Returns:

None

Import Data Module

Import_Data.ExtractDataFromFile(path)

Extracts data from a path and converts it to a list

Parameters:

path – (string) path to read the file

Returns:

(list) Each entry corresponds to a line in the file to read

Import_Data.FilterOutExtraInformation(spec, line_break_nmbr, extra_nmbr, raw_data)

Removes everything above or below a line break from a .com file.

Parameters:

• spec – <str> can be either ‘above’ or ‘below’

• line_break_nmbr – <int> will remove everything above or below that number of line breaks, depending of spec

• extra_nmbr – <int> will remove an extra number of lines according to what’s needed

• raw_data – <[[values]]> data matrix to filter

Returns:

data matrix without the info before or after a specific number of line breaks.

Instantiate Molecules Module

Instantiate_Molecules.Instantiate(is_ionic, represent_type, names_and_pos, materials_dict, connect_with_symbols, element_data, ion_data, ion_input, unit_cell)

Manages the instantiation of all elements and/or ions from Cartesian coordinates.

Parameters:

• is_ionic – (str) Indicates if the molecule is ionic (“0” for non-ionic, otherwise ionic).

• represent_type – (str) The type of representation (e.g., “Ball-and-Stick”, “Stick-only”, “Van-der-Waals”).

• names_and_pos – (dict) Atomic symbols and their positions.

• materials_dict – (dict) Materials that can be accessed with present elements’ symbols.

• connect_with_symbols – (list) List of connections between atoms.

• element_data – (dict) Available data for the present elements.

• ion_data – (dict) Available data for the present ions.

• ion_input – (dict) Input data for the ions.

• unit_cell – (str) Unit cell identifier.

Returns:

None

Instantiate_Molecules.handle_ionic(represent_type, names_and_pos, materials_dict, connect_with_symbols, element_data, ion_data, ion_input, unit_cell)

Handles the instantiation of ionic molecules based on the representation type.

Parameters:

• represent_type – (str) The type of representation (e.g., “Ball-and-Stick”, “Stick-only”, “Van-der-Waals”).

• names_and_pos – (dict) Atomic symbols and their positions.

• materials_dict – (dict) Materials that can be accessed with present elements’ symbols.

• connect_with_symbols – (list) List of connections between atoms.

• element_data – (dict) Available data for the present elements.

• ion_data – (dict) Available data for the present ions.

• ion_input – (dict) Input data for the ions.

• unit_cell – (str) Unit cell identifier.

Returns:

None

Instantiate_Molecules.handle_non_ionic(represent_type, names_and_pos, materials_dict, connect_with_symbols, element_data)

Handles the instantiation of non-ionic molecules based on the representation type.

Parameters:

• represent_type – (str) The type of representation (e.g., “Ball-and-Stick”, “Stick-only”, “Van-der-Waals”).

• names_and_pos – (dict) Atomic symbols and their positions.

• materials_dict – (dict) Materials that can be accessed with present elements’ symbols.

• connect_with_symbols – (list) List of connections between atoms.

• element_data – (dict) Available data for the present elements.

Returns:

None

Instantiate_Molecules.set_every_object_origin()

Sets the origin of all mesh objects in the current Blender scene to the geometric center (median) of each object.

Ions Module

Ions.CreateIonDataFromInput(ionInputList)

takes values in each entry of the ionInputList and makes a IonDataDict

Parameters:

ionInputList – <list>(string, string, string, string) list of ions to specify and their properties

Returns:

dictionary<string, Ionic> dict of Ionic class wich contains info with no radius value

Ions.GetIonDataFromInput(ion_data_dict, ion_input)

gets the correct ionic radii data set from the ionInputList for each element in ion_dict

Parameters:

• ion_dict – dict<str:Ionic> contains the symbols and possible ionic radii for elements of interest

• ion_input – dict<string:Ionic> dict of Ionic class wich contains info with no radius value

Returns:

dictionary<string, float>: Element symbol and their ionic radius

Ions.GetIonPositions(names_and_pos, ion_input)

Parameters:

• names_and_pos – dict<string, Vector3> dictionary that contains the position of each labelled element present.

• ion_input – dict<string, Ionic> dict of Ionic class wich contains info with no radius value

Returns:

dict<string, Vector3> refined dict with only the ions from the ion_input dict

Ions.RemoveNonSpecifiedIons(ion_dict, ion_input)

removes from the ion dictionary the elements that were not specified in input list

Parameters:

• ion_dict – <dictionary> contains the symbols and possible ion radii for all present elements,

• ion_input – dict<string, Ionic> dict of Ionic class wich contains info with no radius value

Returns:

smaller dictionary

Raises:

[Error] – prints out an error if input list contains an ion not present in dictionary or if ion_input is empty

Ions.RemoveSpecifiedIonsFromElementDict(ion_dict, element_dict)

removes specified ions from dict of all elements present

Parameters:

• ion_dict – dict<str:Ionic> contains the symbols and the possible radii for specified elements,

• element_dict – dict<str:bpy.data.object>: dictionary off all elements present

Returns:

dict<str:Ionic> smaller dictionary

Primitives Module

Primitives.CreateAndJoinTrantientBond(pos_dict, mat_dict, key1, key2, bond_type, dash_len, bond_radius, h_bonding=False)

Creates and joins transient bonds between two atoms.

Parameters:

• pos_dict – (dict) Atomic symbols and their positions.

• mat_dict – (dict) Atomic symbols and their materials.

• key1 – (str) Symbol and number for the first atom.

• key2 – (str) Symbol and number for the second atom.

• bond_type – (str) Type of bond.

• dash_len – (float) Length of each dash in the bond.

• bond_radius – (float) Radius of the bond.

• h_bonding – (bool) Whether the bond is a hydrogen bond.

Returns:

None

Primitives.CreateFragmentedBonds(pos_dict, mat_dict, atom1, atom2, bond_type, unit_cell='0')

Instantiates bonds from atoms to the middle-point and joins them.

Parameters:

• pos_dict – (dict) Atomic symbols and their positions.

• mat_dict – (dict) Atomic symbols and their materials.

• atom1 – (str) Symbol and number for the first atom.

• atom2 – (str) Symbol and number for the second atom.

• bond_type – (str) Type of bond (single, double, or triple).

• unit_cell – (str) Unit cell identifier.

Returns:

None

Primitives.InstantiateBondBetweenTwoPoints(p1, p2, r=0.06)

Instantiates a bond between two points.

Parameters:

• p1 – (Mathutils.Vector) Origin point.

• p2 – (Mathutils.Vector) End point.

• r – (float) Radius of the bond.

Returns:

None

Primitives.InstantiateBondsFromConnectivity(pos_dict, mat_dict, connect_list, unit_cell='0')

Instantiates bonds based on connectivity information.

Parameters:

• pos_dict – (dict) Atomic symbols and their positions.

• mat_dict – (dict) Atomic symbols and their materials.

• connect_list – (list) List of connections between atoms.

• unit_cell – (str) Unit cell identifier.

Returns:

None

Primitives.InstantiateElementsFromDictionary(pos_dict, element_data, materials_dict, van_der_waals=False)

instantiates spheres of different radii & materials at the allocated Vector3 positions.

Parameters:

• pos_dict – Dictionary<string, Vector3> all the symbols & labels of elements and their Vector3 positions

• element_data – Dictionary<string, Atom_Data(class)> available data for the present elements

• materials_dict – Dictionary<string, bpy.Material> materials that can be accessed with present elements’ symbols

Primitives.InstantiateIonsFromDictionary(pos_dict, ion_data, materials_dict)

Instantiates spheres for ions at the allocated Vector3 positions.

Parameters:

• pos_dict – (dict) All the symbols and labels of ions and their Vector3 positions.

• ion_data – (dict) Available data for the present ions.

• materials_dict – (dict) Materials that can be accessed with present ions’ symbols.

Returns:

None

Primitives.JoinMeshesFromObjectList(obj_list)

Joins a list of mesh objects.

Parameters:

obj_list – (list) List of mesh objects to join.

Returns:

None

Primitives.ModifyNamesAndMaterials(obj_name, e_symbol, materials_dict)

names of the active object and appends to it the required material.

Parameters:

• obj_name – (str) The name of the sphere to be instantiated.

• e_symbol – (str) Atom symbol, taken from name, used to access materials.

• materials_dict – (dict) Materials that can be accessed with present elements’ symbols.

Returns:

None

Primitives.MoveObjectOnLocalAxis(obj_name, value)

Moves an object along its local axis.

Parameters:

• obj_name – (str) Name of the object to move.

• value – (tuple) Vector by which to move the object.

Returns:

None

Primitives.SelectTwoMeshesAndJoin(name1, name2)

Selects two mesh objects and joins them.

Parameters:

• name1 – (str) Name of the first mesh object.

• name2 – (str) Name of the second mesh object.

Returns:

None

Raw Parameters Module

Raw_Parameters.Set_Raw_Parameters(i_folder_path, i_file_name)

Extracts raw coordinates and connectivity information from a .com file.

Parameters:

• i_folder_path – (str) The path to the folder containing the file.

• i_file_name – (str) The name of the file to be processed.

Returns:

(tuple) A tuple containing raw coordinates and connectivity information.

Raw_Parameters.count_animation_frames(raw_coord_frames)

Counts the number of animation frames in the raw coordinate frames.

Parameters:

raw_coord_frames – (list) List of raw coordinate frames.

Returns:

(int) The number of animation frames.

Raw_Parameters.split_coord_frames(raw_coord_frames)

Splits raw coordinate frames into individual frames for each element.

Parameters:

raw_coord_frames – (list) List of raw coordinate frames.

Returns:

(tuple) A tuple containing lists of initial coordinates and animated coordinates.

Receive Parameters Module

Receive_Parameters.get_parameters_data(json_path)

Retrieves parameters from the JSON config and returns them in a flat dictionary.

Parameters:

json_path – (str) Path to the JSON config file.

Returns:

(dict) Dictionary with flattened and renamed keys for Blender use.

Receive_Parameters.load_json_config(json_path)

Loads and parses the JSON configuration file.

Parameters:

json_path – (str) Path to the JSON config file.

Returns:

(dict) Parsed configuration dictionary.

Refine Data Module

Refine_Data.AddElementSymbolsToConnecrivityList(connect, coords, number_of_elements)

Adds element symbols to the connectivity list.

Parameters:

• connect – (list) Connectivity list.

• coords – (list) List of coordinates.

• number_of_elements – (int) Number of elements.

Returns:

(list) Connectivity list with element symbols added.

Refine_Data.ConvertStringToIndexInList(list)

Modifies entry list. If an enty inside the list is a string of an int, it becomes an int.

Parameters:

list – (list) List containing string representations of integers.

Returns:

(list) List with integers converted from strings.

Refine_Data.RefineConnectivity(list)

Refines the connectivity list to ensure each item has at least three elements.

Parameters:

list – (list) Connectivity list where each line has all connect info for one atom.

Returns:

(list) List of lists, each item has the numbers of the two atoms involved and the bond type.

Refine_Data.RefineCoordList(list)

Converts string coordinates to floats for each entry in the list.

Parameters:

list – (list) Each entry is a list of four strings: the symbol and each coordinate in x, y, z.

Returns:

(list) Each entry corresponds to an atom symbol and its coordinates.

Refine_Data.create_frames_dict(key_frames)

Creates a dictionary of key frames with element names as keys and vectors as values.

Parameters:

key_frames – (list) List of key frames.

Returns:

(dict) Dictionary of key frames.

Refine_Data.make_tuple(str_in)

Converts a string representation of a tuple into an actual tuple.

Parameters:

str_in – (str) String of the form “(a,b,c)”.

Returns:

(tuple) Tuple of the form (a, b, c).

Refine_Data.make_tuple_in_list(a_list)

Converts a list of string representations of tuples into a list of actual tuples.

Parameters:

a_list – (list) List of string representations of tuples.

Returns:

(list) List of tuples.

Refine_Data.rebuild_list(str_list)

Converts a string representation of a list into an actual list of strings.

Parameters:

str_list – (str) String representation of a list.

Returns:

(list) List of strings.

Refine_Data.refine_key_frames(raw_key_frames)

Refines raw key frames by converting coordinates to vectors.

Parameters:

raw_key_frames – (list) List of raw key frames.

Returns:

(list) List of refined key frames with vectors.

Refine Elements Module

Refine_Elements.AddAtomLabelsToConnectList(atom_dict, connect_list)

Adds atom labels with symbols and indexes to the connectivity list.

Parameters:

• atom_dict – (dict) Contains atom labels with symbols and indexes.

• connect_list – (list) List to update.

Returns:

None

Refine_Elements.CreateDictionaryWithNamesAndPositions(list, number_of_elements)

Creates a dictionary with element names and their positions.

Parameters:

• list – (list) Each row has 4 items: name, and xyz coordinates.

• number_of_elements – (int) Number of elements.

Returns:

(dict) Dictionary with keys as Symbol+number (e.g., C01) and values as Vector3(xyz).

Refine_Elements.GetDataForExistingElements(list, ref_dict)

Gets a smaller list of type <Atom_Data> only for the present elements.

Parameters:

• list – (list) List of elements present.

• ref_dict – (dict) Reference dictionary with element data.

Returns:

(dict) Dictionary with data for the present elements.

Refine_Elements.GetElementsPresentInMolecule(list)

Checks for the presence of elements in the molecule and returns a list of unique elements.

Parameters:

list – (list) List of elements and their xyz coordinates (as string values).

Returns:

(list) A list of all the elements present (no repeats).

XYZ Reader Module

Mol2 Reader Module