Density Animations

[Splines]

Thank you so much for this amazing project! Molecular Nodes is really fun to use and looks great.

I'd like to request an addition to the mn.entities.density.io.load() method. Right now it supports setting a single file path. It'd be great if we could pass an array of file paths in order to create an animation of changing densities.

• By default, one density could last one single frame.
• [Maybe the current index (that specifies which density is currently shown), could be visible to the user by means of keyframes, such that one could stretch time, e.g. you want to show one density longer than the others.]

The use case for this request are algorithms that optimize densities (OF-DFT). With animations, one could better understand how the algorithm changes the densities to arrive at the optimum.

As alternative, I wrote a script that constructs the VDB files. Blender lets you import multiple of them to create an animation (inside one volume object). But this pipeline is more cumbersome than the nice import Molecular Nodes is offering for .mrc files.

[PardhavMaradani]

Hi Brady, I was coincidentally looking at OpenVDB, Blender's support of it in a different context recently and was wondering if there was a use case of animating densities in MN. Just sharing some findings here:

OpenVDB supports multiple grids within a single .vdb file. However, Blender doesn't treat them as individual frames when loading the .vdb. There is a way to access the grids by name using Geometry Nodes (Get/Store Named Grid), keyframe the names etc and is quite a bit involved. It is not a recommended approach. A single .vdb file with multiple grids would also be too big and cause memory issues.

The recommended approach is to enable Sequence in the volume data properties (as also pointed out by @Splines above) and specify the frame details. (as is common with smoke and fire animations in Blender) The .vdb sequences are loaded per frame. Stretching the time on just one density in the animation isn't directly possible and could possibly be done, but might be a bit of of scope of MN as it might involve separate keyframing through the graph editor, etc. Thanks

[Splines]

I've noticed that the Graphs constructor calls grid_to_vdb() here. I leveraged that to let Molecular Nodes convert all my .mrc files to .vdb files, then programmatically toggled the sequence on the volume element. Only a workaround, but it works. Note that you have to strip the _center suffix in the filename for Blender to correctly detect the sequence.

Click to expand workaround code

from pathlib import Path

import bpy
import molecularnodes as mn

C = bpy.context
D = bpy.data
FOLDER = Path(r"your/path/to/molecule/H_13C_8N_1")


def import_molecular_graph(pdb_file_path: Path):
    """Imports a molecular graph into Blender.

    Args:
        pdb_file_path: Path to the PDB file containing the molecule (coordinates in Bohr)
    """
    mol = mn.Molecule.load(pdb_file_path)
    mol.object.scale = (10, 10, 10)

    ball_and_stick = D.node_groups.get("Molecule Ball and Stick")
    mol.object.modifiers.clear()
    mol.object.modifiers.new(name="MolecularNodes", type="NODES").node_group = ball_and_stick


def import_densities(density_folder_path: Path):
    """Imports a sequence of MRC density files into Blender via the Molecular Nodes add-on (that
    internally converts them to VDB).

    Args:
        density_folder_path: Path to the folder containing VDB files
    """
    density_files = sorted(density_folder_path.glob("*.mrc"))
    if not density_files:
        raise FileNotFoundError(f"No MRC files found in {density_folder_path}")

    density = mn.entities.density.io.load(
        file_path=density_files[0],
        style="density_iso_surface",
        center=True,
    )
    density_obj = density.object

    density_obj.scale = (10, 10, 10)
    # Shift object by magic factor to align with molecule
    # it is not clear where this offset actually comes from, but it seems to work fine
    density_obj.location = (0.00716, 0.00716, 0.00716)

    density_style = density.styles[0]
    density_style.iso_value = 0.22
    density_style.material = D.materials.get("Density Iso Surface")

    density_obj.data.is_sequence = True
    density_obj.data.sequence_mode = "CLIP"
    density_obj.data.filepath = str(density_files[0].with_suffix(".vdb"))
    density_obj.data.frame_start = 0
    density_obj.data.frame_duration = len(density_files)


def convert_to_vdb(density_folder_path: Path):
    """Converts MRC density files to VDB format using Molecular Nodes.

    In the future, this might become obsolete when Molecular Nodes supports
    animated MRC files directly, see this issue:
    https://github.com/BradyAJohnston/MolecularNodes/issues/1100

    Args:
        density_folder_path: Path to the folder containing MRC files
    """
    density_files = sorted(density_folder_path.glob("*.mrc"))
    if not density_files:
        raise FileNotFoundError(f"No MRC files found in {density_folder_path}")

    for mrc_file in density_files:
        vdb_file = mrc_file.with_suffix(".vdb")
        if not vdb_file.exists():
            # conversion to VDB is called from within the constructor of Grids
            mn.entities.density.grids.Grids(
                file_path=mrc_file,
                center=True,
            )

    # remove the "_center" suffix from the VDB files, such that Blender
    # recognized them as sequence files (the number has to come at the end)
    for vdb_file in density_folder_path.glob("*_center.vdb"):
        try:
            new_vdb_file = vdb_file.with_name(vdb_file.stem.replace("_center", "") + ".vdb")
            vdb_file.rename(new_vdb_file)
        except FileExistsError:
            pass


def main():
    """Main function to import molecular graph and densities."""
    import_molecular_graph(FOLDER / "molecule.pdb")

    densities_folder = FOLDER / "scf_densities"
    convert_to_vdb(densities_folder)
    import_densities(densities_folder)


if __name__ == "__main__":
    main()

[BradyAJohnston]

There is a task about tweaking import of VDB files (#893) which change us to using the Import VDB node instead of having to use Blender's operator. We could then very easily support a sequence of .vdb files via the Format String node like this:

A similar approach could be used to get a particular grid if we were to store multiple grids in a single .vdb, but I think like you say this would be better in terms of memory footprint.

I think it's worth us trying to switch over to using a GN-based volume import, as this gives use more flexibility than the "sequence" option of the classical VDB import in Blender.

Certainly there are a number of use cases where a sequence of electron densities is desired (which I have gotten feature requests about before) and there are likely many others like those presented here.