=============================
``grail.data.shlfile`` Module
=============================
.. include:: ..\..\version.h

.. contents:: Table of Contents
   :backlinks: top


--------
Overview
--------

The Shell File (SHL) is used for describing 3D solids and surfaces as a
combination of points, and face indices into that point list. The
standard format is::

   PointCount, FaceCount
   X_0, Z_0, Y_0
   X_1, Z_1, Y_1
        ...
   X_n, Z_n, Y_n
   F0
   F1
   ...
   Fn

where X\_n, Z\_n and Y\_n are points and Fn is an face index into the
point list.  The point list and face list follow the standard
definitions defined in the grail.ag_'s `Standard Definitions`_ section.

If used with the grail.mstype_ module, you will be able to read/write
binary data without converting it to a python structure.

.. _grail.mstype: ../lib-grail-mstype.html

--------
Examples
--------

The following snippet illustrates how to read from a SHL file,

.. code-block-incl:: Python
   :file: ..\..\..\grail\test\shlfiletest.py
   :start: Start_Read_Ex
   :end: End_Read_Ex

At this point the :d:`point_list` and :d:`face_list` contain the
standard point and face lists as defined in the grail.ag_ module's
`Standard Definitions`_.

.. _grail.ag: ../lib-grail-ag.html
.. _Standard Definitions: ../lib-grail-ag.html#standard-definitions

An example of writing the contents would be as follows,

.. code-block-incl:: Python
   :file: ..\..\..\grail\test\shlfiletest.py
   :start: Start_Write_Ex
   :end: End_Write_Ex

If the grail.mstype_ module is active, then the read/write operations
will occur without converting the data to Python objects, if and only if
you don't access the contents of the point list and face list.

--------
Function
--------

:df:`open(path [,mode])`

   Opens a file at the given :a:`path`. The :a:`mode` can be either "r"
   for read-only or "w" for write-only. If you want to create a new file
   use the "w" option. Using the 

   If you are attempting to open a file in "r" mode and it does not
   exist, an :e:`IOError` is generated.

-------
ShlFile
-------

:c:`ShlFile`

   Use the :df:`open` function to load/create a :c:`ShlFile` object. For
   the most part this object behaves as a regular file like object in
   Python.

   **Methods**

      :df:`close()`

         This closes the file handle to the object. If you fail to close
         the file explicitly, the file will be closed implicitly when
         object falls out of scope.
     
      :df:`read_shell()`

         Returns a Point List and Face List tuple as defined by the
         standard point and face lists in the grail.ag_ module's
         `Standard Definitions`_.

      :df:`write_shell(point_list, face_list)`
  
         Accepts a :a:`point_list` and :a:`face_list` as defined by the
         standard point and face lists in the grail.ag_ module's
         `Standard Definitions`_.


   **Attributes**

      :dd:`mode`

         Read-only. Indicates the mode that the file is in. For example
         this would be "w" (write-only) or "r" (read-only).

      :dd:`name`

         This is the path to the file.

      :dd:`closed`
 
         Is :d:`True` when the object has been closed.