API-interoperability: Grid.convert_to()

[orbeckst]

Implement the conversion from a Grid to a native object as described in the parent issue #160 for

• mrcfile: mrcfile.MrcFile
• OpenDX: gridData.OpenDX.field (i.e., self)
• openvdb (once we have add OpenVDB format #141 ): OpenVDB.OpenVDBField

[orbeckst]

We can create sub-issues for MRC and VDB.

[orbeckst]

Based on reviewing PR #163 I am proposing the following as a common API:

1. Each format for which we want a convert_to() should implement a static method on it's main class from_grid(grid, **kwargs) that will create the object from a grid (and use any additional optional arguments while ignoring any that it cannot process) (EDIT: from_grid() will create the GDF wrapper itself, e.g., MRC.from_grid() will create a gridData.mrc.MRC instance)

   This method is essentially taking the code from the corresponding Grid._export_<FORMAT>() method that already does exactly that.

   Having this code live in the module of the format is better because it keeps all the code for creating such an object in the same place.

2. Refactor Grid._export_<FORMAT> methods to use from_grid(): For example, the MRC writer becomes

   def _export_MRC(self, filename, **kwargs):
       mrc_file = mrc.MRC.from_grid(self, **kwargs)
       mrc_file.write(filename)

3. Create a new Grid.convert_to(format, **kwargs) -> obj method that creates an instance of the class belonging to format:

   EDIT: For each of our wrapper classes (mrc.MRC, OpenVDB.OpenVDBField) implement an attribute .native that contains an instance of the native instance from the underlying library, i.e., for MRC.native is an instance of mrcfile.MrcFile; for our own OpenDX we can supply a complete OpenDX.field)

   Add a class-level attribute Grid.converter that lists the known formats, like

   converter = {'MRC': mrc.MRC.from_grid,
                'VDB': OpenVDB.OpenVDBField.from_grid,
                'DX': OpenDX.field.from_grid,
                }

   Then we can write the convert_to() method as (EDIT: included .native)

   def convert_to(self, fmt, **kwargs):
       native_object = converter[fmt](self, **kwargs).native
       return native_object

The initial implementation should just be for the two formats that have an exporter

• DX
• MRC

Eventually we may be able to also refactor the _export_<FORMAT> methods into a single export() that uses Grid.converters but for right now, leave them explicit.

---

Does this make sense?

[orbeckst]

@PardhavMaradani @BradyAJohnston and @spyke7 what do you think about the proposed API?

[PardhavMaradani]

what do you think about the proposed API?

This looks good. One thing we should probably clarify to avoid any ambiguity, is the return type of from_grid. This comment and comment from PR #148 seem to indicate that it will be a native object, but the examples above seem to refer to the corresponding wrapper in GDF. (For example, there is no write in a native MrcFile object of mrcfile). I think returning our GDF wrapper here is fine (and probably better). For the vdb case, the native object can be made available through an attribute of the wrapper object for power users. Thanks

[orbeckst]

Good observation. The original idea was indeed to return native objects and not wrappers. We could have all our wrappers have a Wrapper.native attribute that holds the native instance. But for true API interoperability it’s cleaner for convert_to to return the native instance itself. Will have to see if we can still clean up our code. Perhaps just do both by introducing a _convert_to_wrapper() first?

[orbeckst]

from_grid() should still create the wrapper. We just need an intermediate method that returns the true native instance.

[BradyAJohnston]

Looks good and I agree that return the GDF wrapper is the way to go.

[orbeckst]

I updated #161 (comment) to take the discussion into account.