Blender API

All the scripts and modules tasked to read computational chemistry files in the formats .com, .xyz, .mol2, or .vasp and convert them to .fbx, .obj, .dae, .glb, .stl, or .usdz 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>(dict) list of ions to specify and their properties - each entry a dict with “element”/”charge”/”coordination” keys.

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

VASP Reader Module

Bond Overwriter Module

BondOverwriter.build_atom_identity_map(coords)

Builds a map of atom indices to their element symbols from a list of raw coordinates.

Parameters:

coords – (list) List of [element, x, y, z] entries.

Returns:

(dict) Dictionary mapping index strings to element symbols, e.g., {‘01’: ‘C’, ‘02’: ‘O’}

BondOverwriter.build_connection_lookup(connect_with_symbols)

Creates a dictionary of existing connections using unordered atom pairs as keys.

BondOverwriter.delete_forbidden_bonds_from_scene(custom_bond_thresholds)

Reads custom threshold rules with bond order 0, then deletes every bond object from the scene whose endpoint element types match a forbidden pair.

Parameters:

custom_bond_thresholds – (list) Dicts from get_custom_thresholds(), each with ‘atom_pair’ and ‘bond_order’.

Returns:

(int) Number of bond objects removed from the scene.

BondOverwriter.get_forbidden_type_pairs(custom_bond_thresholds)

Extracts element type pairs designated as bond order 0 from the custom threshold rules.

Parameters:

custom_bond_thresholds – (list) Rules from get_custom_thresholds(), each a dict with ‘atom_pair’ and ‘bond_order’.

Returns:

(set) Frozensets of element symbol pairs, e.g. {frozenset({‘V’, ‘V’})}.

BondOverwriter.overwrite_connectivity(connect_list_string, connect_with_symbols, coords)

Updates or appends bond connections based on a user-defined string. Validates that atom indices and identities match the current molecule.

Parameters:

• connect_list_string – (str) e.g., “Fe07-Cl25; C03=C07”

• connect_with_symbols – (list) Existing connectivity list

Returns:

(list) Updated connectivity list

BondOverwriter.parse_connection_entry(conn)

Parses a connection entry like ‘Fe07-Cl25’ into atom1, bond, atom2. Assumes bond is a single character.

BondOverwriter.parse_connection_string(connect_list_string)

Splits the input string into a list of cleaned connection entries.

BondOverwriter.remove_forbidden_bonds_from_connectivity(connect_with_symbols, forbidden_type_pairs)

Filters connect_with_symbols, removing any entry whose atom type pair is in forbidden_type_pairs.

Parameters:

• connect_with_symbols – (list) Connectivity list of (atomA, atomB, bond_char) tuples.

• forbidden_type_pairs – (set) Output of get_forbidden_type_pairs.

Returns:

(list) Filtered connectivity list.

BondOverwriter.validate_atom_identity(atom_label, identity_map)

Validates that the atom exists and matches the expected symbol.

Bound Box Builder Module

BoundBoxBuilder.InstantiateBoundingBox(bound_box_points, mat_dict, radius=0.03)

Builds a parallelepiped (unit cell) wireframe from 8 corner points.

BoundBoxBuilder.ParentBoundingBoxToEmpty()

Collects all bounding box edge objects (named ‘{i}-{j}’ with optional Blender instance suffixes) and parents them to a new Empty at the origin, preserving their world-space transforms.

Returns:

(bpy.types.Object) The created Empty, or None if no objects were found.

Unit Cell Linker Module

Unit Cell Replicator Module

UnitCellReplicator.delete_unit_cell_roots() → int

Removes all Empty objects created as unit-cell replication roots (named ‘UnitCell_Root’ and Blender-suffixed copies thereof). Should be called after flatten_scene_hierarchy, once parenting is no longer needed.

Returns:

(int) Number of Empty objects removed.

UnitCellReplicator.flatten_scene_hierarchy() → None

Clears all parent relationships in the scene while preserving world-space transforms, leaving a flat hierarchy of mesh objects.

UnitCellReplicator.parent_atoms_and_bonds_to_empty_object(objects_in_scene: ~typing.Iterable[<MagicMock id='131828376713552'>]) → <MagicMock id='131828376713552'>

Expects Blender objects representing atoms, bonds, or other scene geometry. Cameras and lights should be filtered out by the caller.

UnitCellReplicator.replicate_and_translate_cell(cell: <MagicMock id='131828376713552'>, direction: <MagicMock id='131828377077232'>) → <MagicMock id='131828376713552'>

Duplicates a unit-cell root Empty and all its children, translates the duplicate by direction, and returns the new root.

Miller Plane Builder Module

MillerPlaneBuilder.InstantiateMillerPlane(bound_box_points, h, k, l, mat_dict)

Renders a polygon clipped to the unit cell boundaries, oriented by Miller indices (hkl).

Parameters:

• bound_box_points – list of Vectors defining the unit cell corners

• h – Miller index h

• k – Miller index k

• l – Miller index l

• mat_dict – materials dictionary

MillerPlaneBuilder.assign_material_to_object(obj, mat_dict)

MillerPlaneBuilder.build_mesh_from_polygon(vertices, name)

Creates a Blender mesh object from an ordered list of vertices, forming a single flat face.

MillerPlaneBuilder.compute_lattice_vectors(bound_box_points)

MillerPlaneBuilder.compute_miller_normal(h, k, l, b1, b2, b3)

MillerPlaneBuilder.compute_plane_anchor(h, k, l, origin, a1, a2, a3)

MillerPlaneBuilder.compute_reciprocal_vectors(a1, a2, a3)

MillerPlaneBuilder.compute_unit_cell_corners(origin, a1, a2, a3)

Computes all 8 corners of the unit cell parallelepiped. Bit masking maps index 0-7 to the 8 combinations of (0/1)*a1, (0/1)*a2, (0/1)*a3.

MillerPlaneBuilder.intersect_plane_with_edges(corners, normal, anchor, tolerance=1e-08)

Finds intersection points of the (hkl) plane with the 12 edges of the unit cell parallelepiped.

The plane equation is: normal · (p - anchor) = 0 For an edge from p0 to p1, parameterize as p(t) = p0 + t*(p1-p0), solve for t, keep if 0 <= t <= 1.

MillerPlaneBuilder.sort_polygon_vertices(points, normal)

Sorts intersection points angularly around their centroid so the polygon face winds correctly.

Polyhedron Builder Module

PolyhedronBuilder.BuildPolyhedra(polyhedra_centers, connect_with_symbols, mat_dict)

Builds coordination polyhedra for every instance of each specified center element type. For each center atom, the positions of its bonded neighbors are used as vertices of a convex hull mesh.

Guards:

• Does nothing if polyhedra_centers is empty.

• Skips individual center atoms with fewer than 3 neighbors.

Parameters:

• polyhedra_centers – (list) Element symbols to treat as centers, e.g. [‘V’, ‘Fe’]. Empty list = do nothing.

• connect_with_symbols – (list) Full connectivity list of (atomA, atomB, bond_char) tuples, including inter-cell bonds from Link_Unit_Cells.

• mat_dict – (dict) Materials dictionary keyed by element symbol.

Returns:

None

PolyhedronBuilder.assign_material(obj, element, mat_dict, alpha=0.3)

Creates a node-based transparent material derived from the center element’s diffuse color and assigns it to the polyhedron object.

Parameters:

• obj – (bpy.types.Object) The polyhedron mesh object.

• element – (str) Element symbol of the center atom.

• mat_dict – (dict) Materials dictionary keyed by element symbol.

• alpha – (float) Transparency — 0.0 fully transparent, 1.0 opaque.

Returns:

None

PolyhedronBuilder.build_convex_hull_mesh(vertices, name)

Creates a Blender mesh object from a set of points using bmesh’s convex hull operator. The result is the outer shell of the polyhedron formed by the given vertices.

Parameters:

• vertices – (list) List of Vector positions (the neighbor atom positions).

• name – (str) Name for the new Blender object.

Returns:

(bpy.types.Object) The created mesh object, or None if hull failed.

PolyhedronBuilder.collect_atoms_from_scene()

Scans the active Blender scene and returns all mesh objects identified as atoms. Atoms are recognised by having at least one letter and one digit in their name, and by containing none of the bond-character symbols.

Returns:

(dict) {atom_name (str): world-space position (Vector)}

PolyhedronBuilder.get_element(atom_name)

Extracts the bare element symbol from an atom name by stripping the Blender instance suffix and numeric index. Examples: ‘Fe07’ -> ‘Fe’, ‘V03.001’ -> ‘V’.

Parameters:

atom_name – (str) Full atom name from the scene.

Returns:

(str) Element symbol.

PolyhedronBuilder.get_neighbors(center_name, connect_with_symbols, atoms_in_scene)

Returns all neighbor atom names for the given center instance. For replicated instances (names containing ‘.’), intra-cell bonds are derived from the primitive’s bonds by mapping the suffix, since those bonds are never explicitly added to connect_with_symbols.

Parameters:

• center_name – (str) Full name of the center atom instance.

• connect_with_symbols – (list) Tuples of (atomA, atomB, bond_char).

• atoms_in_scene – (dict) All atoms currently in the scene.

Returns:

(list) Names of all neighbor atoms present in the scene.

Scene Cleaner Module

SceneCleaner.clear_scene()

Removes every object from the current scene except cameras and lights, then purges any mesh data left orphaned by that removal.

Used at the start of each growth-cell export in Main_Body so every supercell is built from a clean slate instead of piling up on top of objects left behind by the previous export - which would otherwise get auto-suffixed by Blender (e.g. ‘C01.001’) and break the primitive-vs-replica name bookkeeping that UnitCellLinker, BoundBoxBuilder, and UnitCellReplicator rely on.

Returns:

None