Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AUTHORS
Original file line number Diff line number Diff line change
Expand Up @@ -30,3 +30,4 @@ Contributors:
* Rich Waldo <plethorachutney>
* Pradyumn Prasad <Pradyumn-cloud>
* Shreejan Dolai <spyke7>
* Aviral Garg <aviralgarg05>
5 changes: 4 additions & 1 deletion CHANGELOG
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ The rules for this file:
* accompany each entry with github issue/PR number (Issue #xyz)

-------------------------------------------------------------------------------
MM/DD/2026 orbeckst, spyke7
MM/DD/2026 orbeckst, spyke7, aviralgarg05

* 1.3.0

Expand All @@ -26,6 +26,9 @@ MM/DD/2026 orbeckst, spyke7

* Implemented loading of a Grid from a native object for OpenVDB (Issue #162,
PR #170)
* Implemented loading of a Grid from a native mrcfile object such as
mrcfile.mrcfile.MrcFile or mrcfile.mrcinterpreter.MrcInterpreter; the
data are used as a view and not copied (Issue #162, Issue #172)

Fixes

Expand Down
24 changes: 18 additions & 6 deletions doc/source/gridData/interoperability.rst
Original file line number Diff line number Diff line change
Expand Up @@ -62,15 +62,27 @@ native objects are produced::
Creating a Grid from a native object
------------------------------------

.. note:: **Not implemented yet.** See issue `#162`_ for details.

:class:`~gridData.core.Grid` should be able to consume *native objects* in place of files.
.. versionadded:: 1.3.0

:class:`~gridData.core.Grid` also consumes *native objects* in place of files:
the object is passed as the *grid* argument and the data together with the
origin and the grid spacings are taken from it.

For example, a :class:`mrcfile.mrcfile.MrcFile` instance can be used to
instantiate the :class:`Grid` instance::

mrc = mrcfile.mrcfile.MrcFile("density.ccp4")
g = Grid(mrc)
mrc = mrcfile.open("density.ccp4")
g = Grid(mrc)


and in the same manner for an OpenVDB grid::

grids, _ = vdb.readAll("density.vdb")
g = Grid(grids[0])

The data are extracted by the *adapter class* of the format, namely with the
*classmethod* :meth:`gridData.mrc.MRC.from_mrcfile` for MRC data. For MRC, the
data are used as a *view* of the data of the native object and are not copied,
so the native object has to keep the data available for as long as the
:class:`Grid` is used.

(See issue `#162`_ for additional background.)
36 changes: 33 additions & 3 deletions gridData/core.py
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@
import pickle

import numpy
import mrcfile

# For interpolated grids: need scipy.ndimage but we import it only when needed:
# import scipy
Expand Down Expand Up @@ -190,6 +191,12 @@ class Grid(object):
g = Grid()
g.load(filename)

From a native object of one of the supported libraries, e.g., a
:class:`mrcfile.mrcfile.MrcFile`::

with mrcfile.open("density.mrc") as mrcobj:
g = Grid(mrcobj)


Notes
-----
Expand All @@ -209,6 +216,13 @@ class Grid(object):
CCP4 files are now read with :class:`gridData.mrc.MRC` and not anymore
with the deprecated/buggy `ccp4.CCP4`

.. versionchanged:: 1.3.0
*grid* can be a native mrcfile object, i.e., an instance of
:class:`mrcfile.mrcobject.MrcObject` such as
:class:`mrcfile.mrcfile.MrcFile` or
:class:`mrcfile.mrcinterpreter.MrcInterpreter`. The data of the grid
are a view of the data of the mrcfile object.

"""

#: Default format for exporting with :meth:`export`.
Expand Down Expand Up @@ -264,6 +278,10 @@ def __init__(self, grid=None, edges=None, origin=None, delta=None,
return
except ImportError:
pass
if isinstance(grid, mrcfile.mrcobject.MrcObject):
# if a native mrcfile object is passed
self._load_mrcfile(grid, assume_volumetric=assume_volumetric)
return
if isinstance(grid, str):
# can probably safely try to load() it...
filename = grid
Expand Down Expand Up @@ -637,12 +655,24 @@ def _load_python(self, filename, **kwargs):

def _load_mrc(self, filename, assume_volumetric=False, **kwargs):
"""Initializes Grid from a MRC/CCP4 file."""
mrcfile = mrc.MRC(filename, assume_volumetric=assume_volumetric)
grid, edges = mrcfile.histogramdd()
mrcdata = mrc.MRC(filename, assume_volumetric=assume_volumetric)
self._populate_from_mrc(mrcdata)

def _load_mrcfile(self, mrcobj, assume_volumetric=False):
"""Initializes Grid from a native mrcfile object.

The grid data are a view of the data of `mrcobj`.
"""
mrcdata = mrc.MRC.from_mrcfile(mrcobj, assume_volumetric=assume_volumetric)
self._populate_from_mrc(mrcdata)

def _populate_from_mrc(self, mrcdata):
"""Initializes Grid from a :class:`gridData.mrc.MRC` instance."""
grid, edges = mrcdata.histogramdd()
self._load(grid=grid, edges=edges, metadata=self.metadata)
# Store header for access from Grid object (undocumented)
# https://github.com/MDAnalysis/GridDataFormats/pull/100#discussion_r782604833
self._mrc_header = mrcfile.header.copy()
self._mrc_header = mrcdata.header.copy()

def _load_dx(self, filename, **kwargs):
"""Initializes Grid from a OpenDX file."""
Expand Down
164 changes: 120 additions & 44 deletions gridData/mrc.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,25 @@
.. _mrcfile: https://mrcfile.readthedocs.io/
.. _`MRC2014 file format`: http://www.ccpem.ac.uk/mrc_format/mrc2014.php

A :class:`~gridData.core.Grid` can be built either from a file or directly
from one of the native objects of the mrcfile_ library, namely
:class:`~mrcfile.mrcfile.MrcFile`,
:class:`~mrcfile.mrcinterpreter.MrcInterpreter`, and their subclasses::

import mrcfile
from gridData import Grid

g = Grid("density.mrc") # from a file

with mrcfile.open("density.mrc") as mrcobj:
g = Grid(mrcobj) # from a native object

The data of such a grid are a view of the data of the native object and are
not copied; see :meth:`MRC.from_mrcfile`.

.. versionchanged:: 1.3.0
Grids can be created from native mrcfile objects.


References
----------
Expand Down Expand Up @@ -136,6 +155,55 @@ def from_grid(cls, grid, **kwargs):

return mrc_obj

@classmethod
def from_mrcfile(cls, mrcobj, assume_volumetric=False):
"""Create a MRC object from a native mrcfile object.

Parameters
----------
mrcobj : mrcfile.mrcobject.MrcObject
Native object of the mrcfile_ library that holds the data and the
header, such as :class:`~mrcfile.mrcfile.MrcFile` or
:class:`~mrcfile.mrcinterpreter.MrcInterpreter`.
assume_volumetric : bool (optional)
If ``False`` (default), check the header to determine whether the
data in `mrcobj` are a 3D volume. If ``True``, assume that they
are volumetric.

Returns
-------
MRC
MRC wrapper object

Raises
------
TypeError
If `mrcobj` is not a native mrcfile object.
ValueError
If the unit cell is not orthorhombic or if the data are not
volumetric.

Notes
-----
The :attr:`array` is a view of the data of `mrcobj`, i.e., the data
are not copied and changes to `mrcobj` are also seen here. The data of
a memory-mapped object (from :func:`mrcfile.mmap`) become unavailable
once that object is closed.


.. versionadded:: 1.3.0
"""
if not isinstance(mrcobj, mrcfile.mrcobject.MrcObject):
raise TypeError(
"mrcobj must be a native mrcfile object (an instance of "
"mrcfile.mrcobject.MrcObject) but is a {}".format(type(mrcobj))
)

mrc_obj = cls()
mrc_obj._populate(mrcobj, assume_volumetric=assume_volumetric)

return mrc_obj

@property
def native(self):
"""Return a native :class:`~mrcfile.mrcinterpreter.MrcInterpreter` object.
Expand Down Expand Up @@ -264,52 +332,60 @@ def read(self, filename, assume_volumetric=False):
if filename is not None:
self.filename = filename
with mrcfile.open(filename) as mrc:
if assume_volumetric:
# non 3D volumes should always fail, regardless of assume_volumetric value
is_volume = mrc.data is not None and len(mrc.data.shape) == 3
else:
is_volume = mrc.is_volume()

if not is_volume:
raise ValueError(
"MRC file {} is not a volumetric density.".format(filename)
)
self.header = h = mrc.header.copy()
# check for being orthorhombic
if not np.allclose(
[h.cellb.alpha, h.cellb.beta, h.cellb.gamma], [90, 90, 90]
):
raise ValueError(
"Only orthorhombic unitcells are currently "
"supported, not "
"alpha={0}, beta={1}, gamma={2}".format(
h.cellb.alpha, h.cellb.beta, h.cellb.gamma
)
self._populate(mrc, assume_volumetric=assume_volumetric)

def _populate(self, mrc, assume_volumetric=False):
"""Populate the instance from the native mrcfile object *mrc*.

The :attr:`array` is a view of the data of *mrc*.
"""
if assume_volumetric:
# non 3D volumes should always fail, regardless of assume_volumetric value
is_volume = mrc.data is not None and len(mrc.data.shape) == 3
else:
is_volume = mrc.data is not None and mrc.is_volume()

if not is_volume:
source = (
"MRC file {}".format(self.filename)
if self.filename is not None
else "{} object".format(type(mrc).__name__)
)
raise ValueError("{} is not a volumetric density.".format(source))
self.header = h = mrc.header.copy()
# check for being orthorhombic
if not np.allclose([h.cellb.alpha, h.cellb.beta, h.cellb.gamma], [90, 90, 90]):
raise ValueError(
"Only orthorhombic unitcells are currently "
"supported, not "
"alpha={0}, beta={1}, gamma={2}".format(
h.cellb.alpha, h.cellb.beta, h.cellb.gamma
)
# mrc.data[z, y, x] indexed: convert to x,y,z as used in GridDataFormats
# together with the axes orientation information in mapc/mapr/maps.
# mapc, mapr, maps = 1, 2, 3 for Fortran-ordering and 3, 2, 1 for C-ordering.
# Other combinations are possible. We reorder the data for the general case
# by sorting mapc, mapr, maps in ascending order, i.e., to obtain x,y,z.
# mrcfile provides the data in zyx shape (without regard to map*) so we first
# transpose it to xyz and then reorient with axes_c_order.
#
# All other "xyz" quantitities are also reordered.
axes_order = np.hstack([h.mapc, h.mapr, h.maps])
axes_c_order = np.argsort(axes_order)
transpose_order = np.argsort(axes_order[::-1])
self.array = np.transpose(mrc.data, axes=transpose_order)
self.delta = np.diag(
np.array([mrc.voxel_size.x, mrc.voxel_size.y, mrc.voxel_size.z])
)
# the grid is shifted to the MRC origin by offset
# (assume orthorhombic)
offsets = np.hstack([h.nxstart, h.nystart, h.nzstart])[
axes_c_order
] * np.diag(self.delta)
# GridData origin is centre of cell at x=col=0, y=row=0 z=seg=0
self.origin = np.hstack([h.origin.x, h.origin.y, h.origin.z]) + offsets
self.rank = 3
# mrc.data[z, y, x] indexed: convert to x,y,z as used in GridDataFormats
# together with the axes orientation information in mapc/mapr/maps.
# mapc, mapr, maps = 1, 2, 3 for Fortran-ordering and 3, 2, 1 for C-ordering.
# Other combinations are possible. We reorder the data for the general case
# by sorting mapc, mapr, maps in ascending order, i.e., to obtain x,y,z.
# mrcfile provides the data in zyx shape (without regard to map*) so we first
# transpose it to xyz and then reorient with axes_c_order.
#
# All other "xyz" quantitities are also reordered.
axes_order = np.hstack([h.mapc, h.mapr, h.maps])
axes_c_order = np.argsort(axes_order)
transpose_order = np.argsort(axes_order[::-1])
self.array = np.transpose(mrc.data, axes=transpose_order)
self.delta = np.diag(
np.array([mrc.voxel_size.x, mrc.voxel_size.y, mrc.voxel_size.z])
)
# the grid is shifted to the MRC origin by offset
# (assume orthorhombic)
offsets = np.hstack([h.nxstart, h.nystart, h.nzstart])[axes_c_order] * np.diag(
self.delta
)
# GridData origin is centre of cell at x=col=0, y=row=0 z=seg=0
self.origin = np.hstack([h.origin.x, h.origin.y, h.origin.z]) + offsets
self.rank = 3

@property
def shape(self):
Expand Down
Loading
Loading