.. _storage:

####################
Surface Storage
####################

.. _storage_file_formats:

*************
File Formats
*************

Spicoli supports the following storage formats:

:.srf:
    Old GRASP format 
:.oesrf:
    OpenEye format based upon tagged binary files 

The :term:`GRASP` format is provided for backwards compatibility with
older visualization programs. There were byte ordering issues with the
format so OpenEye developed a more flexible format based upon the
tagged binary IO available in OESystem.

.. seealso:: 

   * :oe:func:`OESpicoli::OEWriteSurface`
   * :oe:constns:`OESpicoli::OESurfaceFileType`

.. _storage_molecules:

*********************
Attached to Molecules
*********************

The OpenEye format allows surfaces to be attached to molecules and
then written out to OEBinary (.oeb) files. A visualizer can then read
in the molecule and surface without any other means of making the
association. :oe:src:`Listing 1<SNIPPET-SetData-AttachSurface>`
demonstrates how to properly attach surfaces to molecules.

.. oe:source:: AttachSurface.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-SetData
   :caption: Attaching a surface as generic data to be written to OEB
   :refnum: 1

.. oe:source:: AttachSurface.py
   :language: python
   :frag:     SNIPPET-SetData
   :caption: Attaching a surface as generic data to be written to OEB
   :refnum: 1

..  oe:language:: python

   :ref:`Full listing. <listing-AttachSurface.py>`


.. oe:source:: AttachSurface.java
   :language: java
   :noindent:
   :frag:     SNIPPET-SetData
   :caption: Attaching a surface as generic data to be written to OEB
   :refnum: 1

.. oe:source:: AttachSurface.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-SetData
   :caption: Attaching a surface as generic data to be written to OEB
   :refnum: 1

:oe:src:`Listing 2<SNIPPET-GetData-AttachSurface>` demonstrates how to
then read that surface back out of the OEB file.

.. oe:source:: AttachSurface.cpp
   :language: c++
   :noindent:
   :frag:     SNIPPET-GetData
   :caption: Retrieving a surface attached as generic data from an OEB file
   :refnum: 2

.. oe:source:: AttachSurface.py
   :language: python
   :frag:     SNIPPET-GetData
   :caption: Retrieving a surface attached as generic data from an OEB file
   :refnum: 2


..  oe:language:: python

   :ref:`Full listing. <listing-AttachSurface.py>`


.. oe:source:: AttachSurface.java
   :language: java
   :noindent:
   :frag:     SNIPPET-GetData
   :caption: Retrieving a surface attached as generic data from an OEB file
   :refnum: 2

.. oe:source:: AttachSurface.cs
   :language: csharp
   :noindent:
   :frag:     SNIPPET-GetData
   :caption: Retrieving a surface attached as generic data from an OEB file
   :refnum: 2

.. seealso::
   
   * :oe:meth:`OESystem::OEBase::SetData`
   * :oe:meth:`OESystem::OEBase::GetData`

.. note:: 

   Versions of Spicoli prior to 1.0.2 required
   calling :oe:func:`OESpicoli::OEInitSurfaceHandlers` in order to have
   surfaces attached to molecules be read and written to and from OEB.

